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.
Related
Last updated: January 1, 0001
Open kanman