MCP tools

kanman’s MCP server (Model Context Protocol) lets Claude Code, Codex and other MCP clients work in kanman as you: on stories, decisions, runs and outcomes, and in your conversation with kanman. Inside a run, kanman gives the coding agent its own connection to the story-work tools. The setup is described in Use kanman from Claude Code or Codex.

Address and sign-in

claude mcp add --transport http --scope user kanman https://api.kanman.ai/functions/v1/mcp
codex mcp add kanman --url https://api.kanman.ai/functions/v1/mcp

Every tool acts with your role in the workspace. A viewer can use the reading tools only. Every change is recorded in the audit log as you, with the name of the client.

Which team a call is about

Team tools take team (the team’s address name, key or name) or repository (your checkout’s git remote get-url origin); kanman picks the team that works on that repository. Tools that take a storyKey find the story’s team on their own. If your workspace has one team, you can leave both out. Call whoami first: it lists your teams and names the one of your repository.

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.

Text kanman passes on from others, such as a story’s description, a decision’s question, a CI log or kanman’s own replies quoting them, arrives marked as data (<untrusted-data source="…">). Your agent reads it, but does not follow instructions in it.

whoami

Result: you (name, email, role, client), workspace, teams (each with team, name, key, repositories), thisTeam (the team of repository, or null) and next (what to pass next, or which teams share the repository). On teams where kanman brings you a brief, brief.needsYou says how many of its items wait for you, so a session starts with what needs you.

search_stories

Result: stories, each with key, title, team, column, role, classOfService and dueDate, newest change first.

create_stories

create_stories hands a requirement to kanman’s intake for a team, as the intake in the app does. kanman drafts one or more stories with acceptance criteria and a size, or asks back when the requirement is unclear (outcome). Drafts stay off the board until you approve them.

On teams whose model runs on your own runners, drafts arrive a little later: read them with get_drafts.

refine_story

Result: storyKey, the new readiness (0 to 100) and the criteria texts.

move_story

Moving into Ready on a team with the outcome gate works as on the board: the story waits in Refining until its acceptance spec runs red, then the gate moves it (gated: true).

prioritise_story

storyKey and classOfService: expedite (first, never stopped by budgets), fixed_date (with dueDate, YYYY-MM-DD), standard or exploration.

close_story

close_story takes storyKey, reason (duplicate, covered or wont_do), coveringStoryKey for a duplicate or covered story, and an optional note. reopen_story takes storyKey.

list_decisions

Every place shows the same decisions: a question kanman is still settling itself (its own review, or its steward checking the evidence) is missing from the list, the app, Slack and Teams alike, until it needs you. heldByKanman tells you how many there are.

An answer has the same effect as in the app: an approved plan starts the run, an approved merge merges, a resumed run continues.

get_brief

The brief is the same one you see in the team chat, in Slack and in Microsoft Teams. One answer applies to every story the item covers and shows everywhere within seconds. Viewers can read the brief but not answer it. Teams without a brief are listed under withoutBrief; list_decisions shows what waits there.

ask_kanman

The message lands in your own conversation with kanman, in the team’s session or in General, and you see it in the app too. What needs me? is answered at once with kanman’s brief (source: brief), like get_brief.

team_status

list_outcomes

Which story a story-work tool acts on

Every story-work tool except list_stories and ask_about_code takes an optional storyKey (for example PAYME-3). Without it, a call acts on the story you started with start_work. If you have not started one yet, get_story and start_work take the next story in the team’s Ready column that nobody works on (“take the next story”). Inside a run, the tools always work on the run’s story.

list_stories

Lists the team’s stories in Ready, In progress and Review, in board order. Inputs: team or repository.

{
  "stories": [
    { "key": "PAYME-3", "title": "Show the invoice total in the list", "column": "Ready", "role": "ready", "readiness": 100, "workingOnIt": false }
  ]
}

workingOnIt is true when someone already works on the story.

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 }, with "approaches": 2 (or 3) when approaches were recorded.

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." }

A fact or base question is settled by checking, not by asking: kanman answers with how to find it out (read the code, run the test, read the CI job, compare with the main branch). If the agent tried and still cannot know, it asks again and the question reaches the person who knows the code:

{ "answered": false, "settleYourself": true, "kind": "fact", "next": "This asks for a fact the world can settle, so I do not ask a person for it. …" }

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, if you can). 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>" }.

ask_about_code

Asks kanman about the team’s code, with the same answers the team chat gives (see Ask about the code). kanman returns the facts with their links; your agent writes the answer.

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 (no sign-in, an expired or disconnected client, a token of another workspace) are answered with HTTP 401; your client then asks you to sign in again. See Errors and rate limits.

Related

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

service_status

How one of the team’s services or systems is doing, with the same facts as the chat’s answer to “How is payment-api doing?” (see Backstage and Checkmk). kanman returns the facts; your agent writes the answer.