MCP tools

kraft admin mcp serves these tools over stdio. The Kraft plugin registers it in the agent it is installed in, and kraft admin init registers it for Claude Code. For an agent without the plugin, see Register Kraft with your agent.

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 three differences:

• get_work_item returns a trimmed item (its status, current node, pending gate, attachments, progress, stop reason, usage, any policy override, any concerns a task raised about its own work, 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.
• approve_gate, reject_gate, resume_work_item, retry_work_item, raise_budget, skip_work_item, complete_work_item and cancel_work_item answer as get_work_item does. The CLI's --json prints the item's whole row, with its frozen chain.
• 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, item archive and item restore have no tool. A worker is refused abandon 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.
• depends_on is work item ids this item comes after. You still start it; started while one is unfinished it is blocked, and Kraft starts it when they complete. They cannot be added later.
• 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.