MCP tools

kanman exposes a small MCP server (Model Context Protocol) that coding agents use to work on a story under your team’s rules. Inside a run, kanman attaches it to the coding agent automatically. You can also add it to Claude Code or Codex on your own machine and work on a kanman story from the terminal; the change still goes through the outcome gate and gets an evidence pack. The setup is described in Use kanman from Claude Code or Codex.

Endpoint and authentication

Claude Code:

claude mcp add --transport http kanman \
  https://api.kanman.ai/functions/v1/executor-mcp/stories/SBX-12 \
  --header "Authorization: Bearer $KANMAN_API_KEY"

Codex (~/.codex/config.toml, with the token in the environment variable KANMAN_API_KEY):

[mcp_servers.kanman]
url = "https://api.kanman.ai/functions/v1/executor-mcp/stories/SBX-12"
bearer_token_env_var = "KANMAN_API_KEY"

Tools at a glance

The coding agent never declares a story done. kanman runs the gates and performs every gated move. See The outcome gate and evidence.

get_story

Returns the story, its acceptance criteria and Demonstrate block, the test plan, the current run and a summary of the team policy. No inputs.

Example result:

{
  "story": {
    "key": "SBX-12",
    "title": "Export invoices as CSV, filtered by date range",
    "description": "Customers need to export their invoices for their accountant.",
    "acceptanceCriteria": [
      {
        "id": "ac-1",
        "text": "Given a customer with 3 invoices in March, When they export March as CSV, Then the file has 3 rows and the columns date,number,amount"
      }
    ],
    "demonstrate": {
      "kind": "ui",
      "steps": ["open /invoices", "pick 2026-03-01..2026-03-31", "click Download CSV"],
      "expected": "a CSV downloads with columns date,number,amount"
    },
    "testPlan": ["unit: CSV serializer", "e2e: download flow"],
    "affectedAreas": ["src/invoices/**"]
  },
  "run": {
    "runKey": "run-7f3k",
    "attempt": 1,
    "phase": "implement",
    "stage": "implementing",
    "branch": "kanman/sbx-12-export-invoices-as-csv-filtered-by-date-range",
    "status": "running"
  },
  "policy": {
    "preset": "balanced",
    "deniedPaths": ["infra/**", "**/*.tf", ".github/workflows/**", ".kanman/acceptance/**"],
    "maxChangedFiles": 30,
    "maxChangedLines": 800,
    "runBudgetCents": 200,
    "planApproval": "always",
    "requireAcceptanceSpec": true,
    "repositories": ["kanman-ai/pilot-sandbox"]
  }
}

run is null until a run exists. phase is plan while a run waits for plan approval and implement afterwards.

start_work

Moves the story from Backlog, Refining or Ready to the In Progress column and returns the run. Locally, the first call opens a run for the story, so progress, verification and the evidence pack work as for kanman’s own runs. No inputs.

While a kanman run is still planning (the team requires plan approval and the plan is not approved yet), start_work refuses: the agent writes the plan and ends its turn, and the plan goes to the decision inbox. Local runs have no planning phase.

report_progress

Posts one line to the progress updates on the run page and sets the run’s stage.

Result: { "recorded": true }.

request_human_input

Asks a question in the decision inbox (decision kind clarification) and pauses the run until someone answers. The answer comes back to the run as input when it continues.

{ "decisionKey": "dec-4h2k", "next": "Your question is in the team inbox. End your turn now; the run continues with the answer." }

check_policy

Asks whether an action is allowed before the agent tries it, for example “may I touch infra/?”. The answer uses the same rules kanman applies later to the final diff. Every call is recorded in the audit log as policy_decision.

{
  "allowed": false,
  "authority": "ESCALATE",
  "reasonKey": "policy.path.denied",
  "reasonParams": { "path": "infra/alarms.tf", "glob": "infra/**", "preset": "balanced" },
  "decisionKind": "touch_denied_path",
  "decisionKey": null
}

submit_for_review

Tells kanman that the work is committed and pushed. The summary is kept for the evidence pack. Inside a kanman run, verification starts when the agent ends its turn; a local run is finished right away and verification starts. kanman then runs the gates (the acceptance spec against a fresh environment, the diff guard and the diff limits, CI and the review) and moves the story to Review only when they pass. The result appears on the run page.

{ "submitted": true, "next": "Verification has started; the run page shows the evidence." }

If a gate fails, kanman starts an automatic rework attempt with the gate output, as the policy allows.

complete_work

Moves the story to the next column (Review, or Done when the team has no Review column). kanman refuses unless the run has a verification record in which no gate failed and, when the team requires an acceptance spec, the spec proved the outcome. No inputs.

Result: { "completed": true, "movedTo": "<column>" }.

Errors

A tool that cannot do what was asked returns a tool result marked isError: true with a readable message. The agent should read it and act on it. Typical messages:

Requests the server cannot accept at all (missing or invalid token, a story outside the token’s workspace) are answered with HTTP 401. See Errors and rate limits.

Related

• Use kanman from Claude Code or Codex
• Runs
• Decisions
• Policy settings