Use kanman from Claude Code or Codex

kanman’s runs use the kanman MCP server to read the story, report progress and ask questions. You can add the same server to Claude Code or Codex on your own machine. Then you, or your local agent, can pick up a kanman story from the terminal, and the work still goes through the same gates and ends with the same evidence pack.

This is useful when a story needs a human at the keyboard, when you want to pair with your agent on a tricky change, or to try kanman’s workflow before handing stories over.

What you get

All parameters and results are in the MCP tools reference.

Step 1: Create a token

1. In kanman, open Settings, API and click Create token, for example with the name “Laptop Anna”.
2. Pick a short expiry, for example 30 days.
3. Copy the token and store it in your shell profile or password manager:

export KANMAN_API_KEY=km_your_token

The server accepts any active token of the workspace the story belongs to.

Step 2: Add the server

The server address names the story you want to work on. Use the story key kanman shows on the story, for example SBX-12:

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"

Run claude mcp list to check that kanman is connected. For the next story, change the key in the address (claude mcp remove kanman, then add it again).

Codex

Add this to ~/.codex/config.toml:

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

Start Codex in the repository. The kanman tools appear in its tool list. If your client can send extra headers, add x-kanman-executor: codex so the run page shows Codex as the executor.

Step 3: Pick up the story

In your repository, ask your agent to take the story:

Use kanman to work on SBX-12. Read the story, start work, and follow the policy.

The agent calls get_story and start_work. start_work opens a run for the story (for example run-7f3k) and moves the story to In Progress. Work on your own branch.

While you work:

• progress lines from report_progress appear on the run page for the team
• check_policy tells you up front if a path is denied (for example infra/**), instead of failing at review
• questions you send with request_human_input land in the decision inbox; the run waits for the answer

Step 4: Submit for review

When the change is committed and pushed and the pull request is open, call submit_for_review with a summary and the pull request URL (or ask your agent to). kanman then runs the same gates as for its own runs: the acceptance spec against a fresh environment, the diff guard, denied paths and diff limits, CI and the review. The story moves to Review only when they pass, and the pull request gets the evidence pack.

complete_work refuses until verification has passed. That is the point: a story is done when it is proven, no matter who wrote the code.

Good to know

• Your commits keep your own authorship. The audit log records the run’s steps with you as the actor.
• Your local agent’s model usage runs on your own subscription and is not charged to the team’s budget.
• Revoke the token in Settings, API when you no longer need it.