MCP tools

kraft admin mcp serves these tools over stdio. The Kraft plugin and kraft admin init register it for Claude Code; for any other agent, see Set up without the plugin.

The tool names and parameters are a public interface: they keep their shape between minor releases. See Versioning and stability.

Same as the CLI

Each tool calls the same client function as its kraft command, and --json prints that function's payload, with two differences:

• get_work_item returns a trimmed item (its status, current node, pending gate, attachments, progress, stop reason, usage, any policy override and next_node_id, and not its chain or sessions). kraft view show --json prints the full detail, with the effective chain, worker sessions and stop.
• list_work_items lists every repo. kraft view list is scoped to the repo you are in unless --all or --repo says otherwise.

work_item_id is optional wherever a tool takes it. Left out, it is the work item whose worktree or session you are in.

Errors

A refused call is an error result whose text ends with the line the command prints, such as kraft: 404: unknown work item, so the agent can see why.

An argument the API cannot read names the field and what is wrong with it: kraft: 422: label: Input should be 'must_fix', 'question' or 'nit'.

Who may call what

The last column of each table below, and the Human mark, say what an agent may do.

Three exceptions:

• An escalation turn is not a worker, so neither the client nor the API refuses it the refused tools on the item it is helping with. Four are still refused to it: approve_gate, reject_gate, raise_budget and set_work_item_policy, because a gate and a spending cap are a person's call.
  In practice a turn can use retry_work_item on a needs_human item, which Kraft records and performs once the turn ends, complete_work_item, cancel_work_item, set_agent_overrides, and set_node_overrides for a node that has not started. The API answers it 409 for these:
  • skip_work_item, resume_work_item and escalate_work_item, while any escalation turn is running, the caller's own included.
  • pause_work_item: a turn runs only on an item that is needs_human or paused, and pause takes only a running one.
  • set_attachments: a turn runs only on an item that has started, and a started item's documents are fixed.
• The API refuses add_review_comment, submit_review, resolve_thread and reopen_thread from any Kraft session, a worker or an escalation turn, on any item and not only its own.
• kraft item abandon has no tool, and a worker is refused it on its own item too.

Read

File and connect

Creating a work item

Some create_work_item parameters have a default or a shape:

• repo defaults to the repo of the item you are in.
• chain defaults to the repo's default_chain, else default.
• attachments is [{"kind": "spec" or "plan", "path": ...}], at most one of each. A path is resolved against the repo and against the working tree you are standing in, relative to that tree or absolute.
• auto_gate defaults to true.
• budget_usd sets a dollar cap. This tool can set a cap but not lift one.

The tool warns, in repo_warning, when the repo declares no setup command or no test command, which would stop the item.

A call that files an item with a spec attached:

{"title": "fix the flaky test", "attachments": [{"kind": "spec", "path": ".engineering/specs/x.md"}]}

An attached document trims the node whose gate it satisfies, so nobody approves again what was already agreed.

Connecting a repo

When it connects a repo, ensure_repo proposes both commands from the repo's task runner, CI and lockfiles, or takes the ones given ("" for none). It returns every candidate it found.

With test_command: "" the repo is saved disabled: a repo with no tests passes every work item's verification untested, so a person enables it, not the agent. An already-connected repo is left as it is.

Act on a work item

Raising a dollar cap

raise_budget raises the item's own cap, or the item-wide budget_usd of its policy, which it merges into the item's policy override, keeping its other fields.

Any other cap's stop is refused. A node's budget_usd or a token_budget comes with a pointer to kraft item set-policy (here, set_work_item_policy), which replaces the whole override, so pass the fields it already has too. A stop on budget.daily_usd is refused too: raise it in policy.yaml, or wait for local midnight. Raise a cap that stopped an item lists every refusal. See Raise a cap on a stopped item.

Change a work item's setup

These refuse with 409 once the item, or the node, has started, except the policy tool, which binds from the next node entered.

Review

Review comment parameters

• side is old or new, default new: end_line's side.
• start_side is start_line's side, when the range crosses sides.
• quote is the range's lines, each led by its diff mark; left out, Kraft quotes them from the diff.
• label is must_fix, question or nit.
• suggestion is for new-side lines only.

For Kraft's own workers

Related

• CLI: the verb behind each tool, with its flags and output.
• Use Kraft from your agent: how to register these tools with an agent, and how to check that it works.
• Permission gate: how Kraft answers a worker's asks, and what permission_request is for.