MCP tools

The kanman MCP server: address, sign-in and every tool with its inputs, results and errors.

kanman’s MCP server (Model Context Protocol) lets Claude Code, Codex and other MCP clients work in kanman as you: on stories, questions, runs and outcomes, and in your conversation with kanman. The setup is described in Use kanman from Claude Code or Codex.

Address and sign-in

Property Value
Address https://api.kanman.ai/functions/v1/mcp, one address for your whole workspace
Transport Streamable HTTP, JSON responses, no session and no event stream
Sign-in OAuth 2.1 with PKCE. Your MCP client registers itself, opens the browser for you to sign in and allow it, and renews its access on its own. Access lasts an hour and renews without asking you again.
Workspace The one you pick when you allow the client. Disconnect it in Your settings > API tokens > Connected apps.
CI and scripts A workspace API token from Your settings > API tokens as Authorization: Bearer <token>. It covers whoami.
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. When a call cannot tell the team, its answer lists your teams with exactly the value to pass. ask_kanman also finds the team from a story key in your message (for example INT-156).

Tools at a glance

Tool Purpose
whoami Who you are, your role, your teams and the team of your repository.
Board
search_stories Find stories in every column, of one team or all of them.
create_stories, get_drafts, write_stories Hand kanman a requirement; it drafts stories with acceptance criteria; approve them onto the board.
refine_story Change title, short description, labels, size, acceptance criteria and test plan.
move_story Move a story to another column.
prioritise_story Set the class of service (expedite, fixed date, …).
close_story, reopen_story Close without delivering, or reopen.
comment_on_story Add your comment to a story: notes and evidence, also without a run.
assign_story Change who works a story: you, a colleague or kanman.
Questions
list_decisions, get_decision, answer_decision See what waits for a person and answer it.
why Why kanman did something on its own, from its activity log.
Conversation
ask_kanman, get_kanman_reply, act_on_card Talk to kanman as in the app, and confirm what it proposes.
Runs and outcomes
team_status, list_runs, get_run What kanman does now, recent runs, one run with the link to its page.
start_story Start a story now.
list_outcomes, get_outcome, set_outcome_goal Outcomes with progress, their stories, their goal.

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 coding tool reads it, but does not follow instructions in it.

whoami

Input Type Required Description
repository string no Your checkout’s git remote.

Result: you (name, email, role, client), workspace, teams (each with team, name, key and repositories; a team with more than 20 repositories shows repositoryCount instead), thisTeam (the team of repository, or null) and next (what to pass next, or which teams share the repository).

search_stories

Input Type Required Description
team, repository string no One team; without both, all your teams.
query string no Words in the title.
column string no Role (backlog, refining, ready, in_progress, review, done) or column name.
limit integer no Up to 100, default 30.

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.

Tool Inputs Result
create_stories team or repository, text request (its id), outcome, status, drafts
get_drafts request status, drafts: draftId, title, size, readiness, criteria, openQuestions, state, storyKey once written
write_stories request, draftIds The written stories with their keys

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

refine_story

Input Type Required Description
storyKey string yes For example PAY-12.
title string no New title.
summary string no New short description for the card; an empty string clears it.
labels string[] no The story’s whole label set, by name from the team’s labels. An unknown name changes nothing and lists the team’s labels; [] removes all.
size string no S, M or L.
criteria array no The new list of acceptance criteria, each with given, when, then and optionally the id of a criterion to keep (its status and evidence stay).
testPlan array of strings no The new test plan.

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

move_story

Input Type Required Description
storyKey string yes
to string yes Role (backlog, refining, ready, …) or column name.

A finished story moves to done. A story you move to Ready is picked up by kanman when nobody else is assigned to it.

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.

close_story is not for finished work: a delivered story moves to done with move_story.

comment_on_story

Adds your comment to a story, like the comment box on the story page. The comment shows your name, appears in the story’s discussion and reaches the people who follow the story. Use it for notes and evidence, for example when you or your own coding tool worked a story without a kanman run.

Input Type Required Description
storyKey string yes
text string yes The comment, in Markdown, up to 20,000 characters.

Result: storyKey, commented: true, commentId and url, the link to the story. Viewers can read but not comment.

assign_story

Adds or removes who works a story, like the avatars on the story page. With nobody or kanman assigned, kanman works the story once it is in Ready; while a person is assigned, kanman does not start a run on it and helps in its notes. To hand a story back to kanman, add kanman and remove me.

Input Type Required Description
storyKey string yes
add string[] no Who to assign: me, kanman, or a member’s email or name.
remove string[] no Who to unassign, written the same way.

Pass add, remove or both. Result: storyKey, people (the people who work it now), kanman, means (what that means for kanman) and url, the link to the story. Viewers can read but not assign.

list_decisions

Tool Inputs Result
list_decisions team or repository (optional), limit Open questions, oldest first: decisionKey, title, team, storyKey, runKey, waitingSince
get_decision decisionKey question, options (id, label, recommended), recommended, storyKey, runKey, status
answer_decision decisionKey, optionId, note The answer as kanman recorded it

Every place shows the same questions: the app, Slack, Microsoft Teams and this server. An answer has the same effect as in the app: kanman continues with it right away. See Questions from kanman.

why

Input Type Required Description
storyKey string no For example INT-241.
team, repository string no The team, when you ask without a story.
language string no en, de, es or fr.

Result: answer, the latest thing kanman did on its own about the story or the team, and what it rested on, from its activity log.

ask_kanman

Tool Inputs Result
ask_kanman message; team or repository, or general: true for Personal; language (en, de, es, fr) messageId, reply, and a card when kanman proposes a change; status: working while a runner answers
get_kanman_reply messageId The reply as it is now
act_on_card messageId, action (confirm, cancel, retry) What kanman did

The message lands in your own conversation with kanman, in the team’s session or in Personal, and you see it in the app too. When kanman proposes a change, the reply carries its card and next says how to confirm it: act_on_card with confirm applies it with your rights and answers with what changed, with url linking the story it changed. kanman can also add one of your own messages to a story as your comment; it asks once, on the card.

team_status

Tool Inputs Result
team_status team or repository What kanman does on the team now, or why it is idle; the run slots and the stories waiting for one
list_runs team or repository, limit Recent runs: runKey, storyKey, status, stage, attempt
get_run runKey Status, stage, attempts, cost and budget, branch, merge request and page, the link to the run page
start_story storyKey Start now: started, or what the story needs first

list_outcomes

Tool Inputs Result
list_outcomes team or repository Each outcome with its counts (done, in progress, queued, waiting for people, blocked)
get_outcome outcome (address name or title), team goal, successCriteria, status, stories in order with their columns
set_outcome_goal outcome, goal, successCriteria The stored goal

Errors

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

Message Meaning
Invalid arguments: … An input is missing or has the wrong type.
Which team? Pass repository … or team. The workspace has several teams; name one, or pass your repository.
Your role in this workspace is viewer: … Viewers can use the reading tools only.
This tool acts as you in kanman and needs you signed in … A workspace API token reaches whoami only.

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.

Last updated: January 1, 0001

Open kanman