MCP
Connect an MCP client to your Kairoku workspace.
Kairoku exposes one MCP endpoint:
https://api.kairoku.io/api/mcpAny MCP client can connect to it. Claude Code and Codex are the two verified paths; the plugin page covers both installs. That address is the Kairoku API's own origin and the one the plugin is configured with; the web app still forwards https://kairoku.io/api/mcp to it, but only as a temporary bridge.
Signing in
There are two credential types, and each resolves to an owner — the workspace whose projects the tools read. An owner is not necessarily a person. It is either a Kairoku user or an organization, and every tool call is scoped by exactly that value plus the scopes the credential carries (below).
OAuth browser sign-in is the default and the one to use interactively. The client discovers the authorization server from the endpoint, registers itself, and sends you to a browser to approve. Nothing is pasted. In Claude Code that is /mcp → kairoku → Authenticate; in Codex it is codex mcp login kairoku.
An OAuth token carries a person rather than a context, so the server resolves the owner from that person's organization memberships on each request:
- No organizations — the owner is the user. The personal workspace, exactly as it behaved before organizations existed.
- Exactly one organization — the owner is that organization.
- Two or more — the request is refused. Nothing is guessed, and nothing quietly falls back to personal.
The refusal is deliberate. A silent personal fallback would hand a team member an empty workspace that reads as a real answer, and choosing an organization arbitrarily would write a team's work into whichever one happened to sort first. The remedy is a personal access token minted in the organization you mean to work in.
Personal access tokens — the kai_ prefixed kind — are for headless callers: CI, a cron job, a dispatched agent on a machine with no browser, and any person who belongs to more than one organization. A PAT carries its owner permanently: whatever context was active when it was minted — an organization if you had one active, you otherwise — is the context it resolves to for the rest of its life. Switching context in the app afterwards does not re-point it; to work in another organization, mint a token there.
Mint them in Settings → Developers → MCP tokens, one per headless caller — a person's own agent session, a CI job, a cron — and name them for the caller. Choose the token's scopes there too (below); leaving every box checked carries all four, the same reach a pre-1.2 token had. A dispatched run needs none of this: the app mints that run's own credential when it composes the run, delivers it as KAIROKU_PAT, and deletes it when the run ends, so there is no long-lived slot token to name or to rotate (see Runner setup). A run's own token is always read + write, pinned to the dispatch's project — never operate or admin. The app stores only a hash; the value is shown once. Revocation is a hard delete, and a kai_ token that matches no row is rejected outright rather than retried against OAuth.
Whichever credential arrives, the server records which one it was alongside whose it was, so every agent write in the activity feed is attributable to a specific credential rather than to the word "agent".
Keep PAT values in a password manager. They do not belong in a repository, a brief, a transcript, or these docs.
Scopes
A credential's reach is one or more of four scopes. A tool needs exactly one; a credential missing it gets a plain scope refusal, not a crash.
| Scope | Lets a token… |
|---|---|
kairoku:read | Read projects, documents and plans |
kairoku:write | Write documents, plans and item status |
kairoku:operate | Dispatch and cancel runs |
kairoku:admin | Create projects and change settings |
An interactive PAT chooses its scopes at mint — all four when none are picked, so nothing that worked before 1.2 stops working. A run's own token is minted automatically as read + write, pinned to one project, so a dispatched agent can read and write that project's plan but cannot dispatch further work, create a project, or list the workspace's repositories.
Three tools — create_project, list_forge_repos, get_operations — act across the whole workspace rather than one project. A project-pinned token calling one of them gets Not found, exactly as if the tool did not exist: from that credential's vantage point, it doesn't.
The tool catalog
The registry behind this endpoint is also what the in-app operator and the plugin's operator agent call — one set of tools, one set of rules, read by the credential's scopes. Tool names on the wire are snake_case, and so is every argument — there are no exceptions. upsert_plan also accepts the older camelCase spellings needsManualCheck and testNotes for one release: each behaves exactly like needs_manual_check and test_notes, and a request carrying either one writes a single deprecation line to the server log naming the replacement — one line per request, however many items it carries. Send both spellings for the same field and the snake_case value wins. The camelCase pair is removed at the CLI release, so write snake_case now.
Most tools execute the moment they return. A handful never do: calling one of them files an approval for a person to decide in Kairoku (inline, Needs you, or the Mission Control rail) and returns {status: "approval_required", action_id, ask_id} instead of a result. Those are marked Approval below. dispatch_work and a dispatch_control retry are ordinarily writes, but come back the same way when the workspace owner's operator policy requires a person's sign-off on dispatch.
Projects
| Tool | Access | What it does |
|---|---|---|
list_projects read | kairoku:read | Every project in the workspace this credential resolves to, optionally filtered by release stage. Start here when you do not yet know which project is meant, or to get a project's slug for the other tools. |
get_project read | kairoku:read | One project in full: description, deploy status, its releases, and an index of its documents — titles and types, no bodies. Pass brief to additionally attach a session brief: what moved, what is blocked, the current phase's remainder, and the next gate — one call instead of several. |
create_project write | kairoku:admin | Start a new project with its first release; returns the slug every other tool takes as project. |
update_project write | kairoku:admin | Rename a project or change its one-liner, description, Jira key or deploy link. |
manage_project_repos write | kairoku:admin | List, add, relabel or promote a project's linked repositories. |
list_forge_repos read | kairoku:admin | The workspace's connected GitHub or GitLab repositories, to pick one for manage_project_repos. |
request_project_removal write | kairoku:admin | Approval. Ask a person to remove the whole project, or unlink one repository. |
Documents & folders
| Tool | Access | What it does |
|---|---|---|
list_documents read | kairoku:read | One project's document index — id, title, type, format, update time. Pinned first. |
get_document read | kairoku:read | One document in full, text and metadata. |
search_documents read | kairoku:read | Case-insensitive substring search across documents, chat messages and activity, up to 20 hits per kind. query is optional once you pass at least one document filter (release, doc_class, folder, type, updated_since); neither a query nor a filter is refused. No match is an empty list, not an error. |
create_document write | kairoku:write | Author a new document onto a project, optionally filed into a folder by id, template slot slug, or /-joined path. Publishing it to Confluence stays a separate human action. |
update_document write | kairoku:write | Revise a document's title or content, or move it to another of your projects — any combination in one call. A living document is editable directly like any other; every edit is kept as a recoverable revision. Pass section (a markdown heading's exact text, case-insensitive) with content or append to rewrite or extend just that section's body — a heading that does not exist, or matches more than once, is refused with no write. |
manage_document write | kairoku:write | Move a document to a folder (or unfile it), or pin/unpin it. |
manage_folders write | kairoku:write | Create, rename or reorder document folders. |
request_delete write | kairoku:write | Approval. Ask a person to delete a document, folder, phase or issue. |
Plan
| Tool | Access | What it does |
|---|---|---|
get_plan read | kairoku:read | A release's plan: ordered phases, ordered items, each not_started, in_progress, blocked or done — or, with scope: "project", a project's epics and issues instead. Defaults to the current release; takes a version, or all. Pass include_ledger for agents' recorded claims against each item, or include_context_pack to orient in one call — the release box's documents, the last progress note, and a derived summary. |
upsert_plan write | kairoku:write | Create or update a release's phases and items in one call, matched by name so a re-run converges instead of duplicating. Takes needs_manual_check and test_notes per item. Pass scope: "project" to instead write epics and issues. Never overwrites an item's status or its Jira key. |
update_item_status write | kairoku:write | Move one plan item to not_started, in_progress or blocked, optionally with a note. done is refused — it comes from the merge, or from a person. expected_status and expected_title are accepted by the schema but not yet available on this surface: passing either is refused. |
manage_plan write | kairoku:write | Reorder phases or items, move issues to another release, or set an issue's epic. |
add_item_comment write | kairoku:write | Comment on an issue. |
request_item_done write | kairoku:write | Approval. Ask a person to mark one issue Done. |
Releases
| Tool | Access | What it does |
|---|---|---|
create_release write | kairoku:write | Open a new release for a project, starting in the idea stage. |
update_release write | kairoku:write | Rename a release's version or change its scope note. |
set_release_stage write | kairoku:write | Move a release to idea, exploring, planning, handoff or building, or park it. Pass dry_run to see what blocks the move first. |
request_ship write | kairoku:write | Approval. Ask a person to ship a release, or unlock one from shipped/parked back to an earlier stage. |
request_publish write | kairoku:write | Approval. Ask a person to push the plan to Jira, or publish one document to Confluence. |
Execution & dispatch
| Tool | Access | What it does |
|---|---|---|
dispatch_work write | kairoku:operate | Dispatch agents to work on a release, phase, issue or document, on a machine from get_operations. May itself come back Approval (above). |
dispatch_control write | kairoku:operate | Cancel a dispatch or run, or retry one. Cancelling is always direct; a retry may itself come back Approval. |
prepare_release_dispatch read | kairoku:operate | Read-only: a release's scope snapshot and hash, to hand to request_release_dispatch_decision. |
request_release_dispatch_decision write | kairoku:operate | Approval. Ask a person to approve a release's scope for execution, or close an approved execution. |
Mission Control reads
| Tool | Access | What it does |
|---|---|---|
get_operations read | kairoku:operate | view: enrolled machines, the fleet, environment profile counts (never secret names or values), one dispatch's runs, or the Mission Control snapshot. Call it before dispatch_work to pick a machine. |
Ship & approvals
| Tool | Access | What it does |
|---|---|---|
ship_sweep write | kairoku:write | Read pending amendments and a release's still-open items, or record each item's carry/drop disposition. |
draft_release_notes write | kairoku:write | Draft (or redraft) the release's "Release notes" document from its Done items. Refused once the release has shipped. |
Agent asks & notes
| Tool | Access | What it does |
|---|---|---|
add_progress_note write | kairoku:write | A free-text note on the project's activity feed, stored verbatim and attributed to the agent. One per milestone, not one per commit. |
create_ask write | kairoku:write | Ask a person for something only a person can settle — a decision, a review, access. Files a durable item on their Needs you list. Set hold truthfully (waiting, assuming with an assumption, or none); never ask for a secret, password, token or key. Pass a stable key so a retry never files twice. |
get_ask read | kairoku:read | One ask you raised: its status and, for the credential that raised it, the answer. Pass wait_seconds (at most 50) to hold the call until it is answered. |
list_asks read | kairoku:read | The asks this credential raised: open ones plus those resolved in the last 7 days. Pass answered_unread at session start to get only unread answers. |
attach_screenshot write | kairoku:write | Attach a screenshot to a plan item as evidence of implemented work. Takes the item's id or its KEY-NUMBER identifier from get_plan, the image bytes as base64, and optionally a run_id and caption. png, jpeg, gif or webp, up to 4MB. |
Connections
A connected service in Settings → Connections adds its own tools to this same endpoint automatically — there is no entry for them in the registry above, because the set depends on what each workspace has connected. Each one is named <connector>__<tool> (for example linear__create_issue), reads or writes under the same kairoku:read/kairoku:write rule as the tool's own annotations say, and is listed and called exactly like a first-party tool. See Connections for the catalog and what connecting does.