Reference
MCP tools
Every tool the kraft MCP server serves, with its parameters and the kraft command that does the same.
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.
Each tool calls the same client function as its kraft command, so the two
return the same payload: --json on the command prints what the tool returns.
work_item_id is optional wherever a tool takes it. Left out, it is the work
item whose worktree or session you are in.
A tool marked human is a decision the agent should ask a person about first.
A Kraft worker cannot act on its own work item: a tool marked refused in the
last column fails when a worker aims it at the item it is running, and the API
behind it refuses the same call from a worker session. An escalation turn is
not a worker, so it may use these on the item it is helping with, except
approve_gate, reject_gate, add_review_comment and submit_review.
Read
| Tool | Parameters | Command | Own item |
|---|---|---|---|
list_work_items | status, one of paused, active, waiting, rate_limited, needs_human, completed, abandoned. | kraft view list | |
get_work_item | work_item_id. | kraft view show | |
get_gate_artifact | work_item_id. Returns the spec or plan the pending gate decides, and the digest a chain revision gate needs. | kraft view artifact | |
search | q (required), limit (default 20). Searches specs, plans and session summaries across repos. | kraft view search | |
list_threads | work_item_id, open_only (default false). Review threads, drafts included. | kraft view threads | |
compare_changes | work_item_id, from_ (default base), to (default latest), nodes (comma-separated node ids), ignore_whitespace (default false). A target is base, attempt:N, last_review or latest. | kraft view compare |
File and connect
| Tool | Parameters | Command | Own item |
|---|---|---|---|
create_work_item | title (required), repo (default: the repo of the item you are in), chain_template (default: the repo's default_chain_template, else default), description, attachments ([{"kind": "spec" or "plan", "path": ...}]), auto_gate (default true), implements_beads, policy, base_branch, skip_nodes, budget_usd, node_overrides. Files the item paused. | kraft item create | |
ensure_repo | path (default: the current directory). Connects the repo if it is not connected yet. | kraft repo connect |
Act on a work item
| Tool | Parameters | Command | Own item |
|---|---|---|---|
approve_gate | work_item_id, gate (default: the pending one), digest (a chain revision gate needs it). Human. | kraft item approve | refused |
reject_gate | note (required), work_item_id, gate, node (where the chain re-enters). Human. | kraft item reject | refused |
pause_work_item | work_item_id. | kraft item pause | refused |
resume_work_item | work_item_id, steer, steers ({task path: steer}). Starts a paused item, including one just filed. | kraft item resume | refused |
retry_work_item | work_item_id, steer, path (node, node.step or node.step.task), restart (default false). The only way back onto a stopped item. | kraft item retry | refused |
raise_budget | budget_usd (required; null for no cap), work_item_id. Raises the item's own dollar cap and retries it, like the Raise budget button. Only for a stop that cap made; any other cap's stop is refused. Human. | kraft item raise-budget | refused |
skip_work_item | work_item_id, note, path. Human. | kraft item skip | refused |
complete_work_item | reason (required), work_item_id, close_beads (default false). Human. | kraft item complete | refused |
cancel_work_item | reason (required), work_item_id. The worktree stays. Human. | kraft item cancel | refused |
escalate_work_item | message (required), work_item_id. Sends a message into the item's escalation thread. | kraft item escalate | refused |
kraft item abandon, which also deletes the worktree, has no tool.
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.
| Tool | Parameters | Command | Own item |
|---|---|---|---|
set_chain_template | template (required), work_item_id. | kraft item set-chain | |
set_attachments | work_item_id, spec, plan (paths), drop (["spec"], ["plan"] or both). | kraft item set-attachments | refused |
set_agent_overrides | work_item_id, model, escalate_model, effort, clear (default false). Applies to every agent node. | kraft item set-overrides | refused |
set_node_overrides | node_id (required), work_item_id, auto_escalate, auto_escalate_stuck, auto_escalate_delay_s, model, effort, extra_prompt, clear. | kraft item set-node-override | refused |
set_work_item_policy | work_item_id, policy (item-wide fields, plus paths for per-scope fields; item-wide budget_usd may be "none", no dollar cap), clear. Replaces the whole stored override. | kraft item set-policy | refused |
Review
| Tool | Parameters | Command | Own item |
|---|---|---|---|
add_review_comment | body (required), work_item_id, thread_id (to reply), file_path, start_line, end_line, side (old or new, default new), label (must_fix, question or nit), suggestion. Leaves a draft. | kraft item comment | refused |
resolve_thread | thread_id (required). | kraft item resolve | |
reopen_thread | thread_id (required). | kraft item reopen | |
submit_review | outcome (required: comment, request_changes or approve), work_item_id, summary, node. Sends the drafts. Human. | kraft item review | refused |
For Kraft's own workers
| Tool | Parameters | Command | Own item |
|---|---|---|---|
report_progress | task (required): the N of the plan's ## Task N heading. work_item_id. | kraft item progress | |
reply_to_thread | thread_id, body (both required), claim (fixed, answered or should_fix). | kraft item reply | |
set_mr_labels | labels (required), work_item_id. Labels the merge request and re-creates its pipeline. | kraft item mr-label | |
permission_request | tool_name, input (both required), tool_use_id. Not for an agent to call: Kraft passes it to Claude Code as --permission-prompt-tool. See Permission gate. | none |