Skip to content
Kanroo
Sign inStart free

Connect Claude Code, Codex or Cursor to your Kanban board with MCP

A step-by-step guide: create a scoped API key, add the Kanroo MCP server to Claude Code, Codex or Cursor, test the connection and keep your key safe.

By Dejan Vi.Published 5 min read
On this page

Your coding agent already reads your code. With the Model Context Protocol (MCP), it can also read and update your board: pick up the next task, comment on progress, move a task to review, or write release notes into the wiki.

Kanroo has no built-in AI. Instead, it includes an MCP server, so you can connect the agent you already use. This guide shows the setup for Claude Code, Codex and Cursor, step by step.

What the agent can do

The Kanroo MCP server offers 116 tools (October 2026). They cover boards, lists, labels, tasks, comments, checklists, attachments, imports, exports and wiki pages. A few examples:

Tool What it does
get_context Tells the agent who you are and which organization it works in
get_my_agenda Your assigned tasks: what is due, what is stuck
search_tasks Finds tasks across your boards
create_task, move_task Creates a task, or moves it to another list
create_comment Adds a comment to a task
get_page, edit_page_body Reads or edits a wiki page

The agent works with your personal API key. It can do only what your account may do, and every call checks your current roles and board access.

Remote endpoint or local server?

There are two ways to connect:

  • Remote endpoint. Your Kanroo address plus /mcp. Nothing to install. Use this by default.
  • Local server. A small program that you build from the Kanroo repository and run on your computer. Use it when the agent must handle files but cannot run shell commands.

This guide uses the remote endpoint. The local server is covered in the MCP documentation.

Step 1: Create an API key

  1. In Kanroo, open Settings, then the API keys tab.
  2. Choose Create API key.
  3. Pick the scope. Choose the smallest one the agent needs:
Scope What the agent gets
Read Reads boards, tasks, comments, activity and wiki pages, and exports
Write Everything in Read, plus create, change, move and delete
Admin Everything in Write, plus members, invitations, access and everything public

For a coding agent that updates tasks, Write is usually enough.

Kanroo shows the key once. Keep it in your agent’s personal configuration or in an environment variable. Never commit it to a repository.

If you signed in with single sign-on (SSO), Kanroo asks you to verify your personal account before you create a key.

Step 2: Connect your agent

The endpoint on Kanroo Cloud is https://cloud.kanroo.app/mcp. The agent sends the key in the header Authorization: Bearer <api-key>. Replace <api-key> with your key in the examples.

Claude Code

Run this once in your terminal:

claude mcp add --scope user --transport http kanroo https://cloud.kanroo.app/mcp --header "Authorization: Bearer <api-key>"

This stores the server in your personal Claude Code configuration. Do not add --scope project: it writes the key into <project>/.mcp.json, which is usually committed.

Check it with:

claude mcp get kanroo

Codex

Export the key as KANROO_API_KEY in the environment that starts Codex:

export KANROO_API_KEY=<api-key>

Then add this to ~/.codex/config.toml:

[mcp_servers.kanroo]
url = "https://cloud.kanroo.app/mcp"
bearer_token_env_var = "KANROO_API_KEY"

Codex reads the key from the variable, so the file itself holds no secret.

Cursor

Add this to your personal file ~/.cursor/mcp.json:

{
    "mcpServers": {
        "kanroo": {
            "url": "https://cloud.kanroo.app/mcp",
            "headers": {
                "Authorization": "Bearer <api-key>"
            }
        }
    }
}

Use the personal file in your home folder, not a .cursor/mcp.json inside a project that you commit.

Step 3: Test the connection

Restart the agent, then check that it sees Kanroo:

  • Claude Code: start it, open /mcp, and ask it to call get_context.
  • Codex: open /mcp, and ask it to call get_context.
  • Cursor: open Settings > Tools & MCP, enable kanroo, and ask Agent to call get_context.

If the call returns your context, you are connected.

Step 4: Give it real work

Agents work best with clear, small requests. Some prompts to start with:

Show my agenda in Kanroo. Which of my tasks are due this week?
Find the task "Login timeout" on the board "App". Read it, fix the bug in this repository,
then comment on the task with a short summary and move it to "In review".
Create a task in the list "Backlog" of the board "App" for every TODO comment in src/auth.
Use the file path in the title.
Read the wiki page "Release checklist" and tell me which steps are not done for release 2.4.

Keep a person in the loop for anything public. Board visibility, task publication and shares need an Admin key, which is one more reason to start with Write.

Files: attachments, imports and exports

The remote endpoint does not send file content through the agent. Instead, the tool get_file_transfer returns a ready curl command. The agent runs it in its own shell and moves the file directly between your computer and Kanroo. Claude Code, Codex and Cursor can all do this.

For that, the shell needs the key in KANROO_API_KEY. The tool never returns your key. If you followed the Codex steps, the variable is already set.

Stay safe

An agent with a key acts as you. These rules keep that safe:

  • Smallest scope. Read for questions, Write for task work, Admin only when you need it.
  • One key per agent. Then you can revoke one key without breaking the others. Set an expiry date if the agent is a short experiment.
  • Treat board content as untrusted. Other members write task text, comments, file names and wiki pages. An agent should read them as data, never as instructions.
  • Keep the key out of Git. Use personal configuration files or environment variables.

When something goes wrong

  • 401: the key is missing, mistyped, revoked or expired. Check that the header reads exactly Authorization: Bearer <api-key>.
  • 404: check that the address ends in /mcp.
  • 429: the key reached its request limit. Wait the seconds in Retry-After, then try again. Your plan sets the API requests per minute for your organization, see plans and limits.
  • Only some tools appear: the scope of the key decides the tools. After you change the key, reconnect the agent so it loads the tool list again.

Self-hosted Kanroo

The MCP server is part of the open-source core. On your own server, the endpoint is https://<your Kanroo domain>/mcp. Use that address in the examples above. The operator can turn the remote endpoint off with REMOTE_MCP_ENABLED=false; then /mcp answers 404.

Next steps

Did you like this post?

Try it on your own board.

Kanroo Cloud has every feature on every plan. Try it with a real project, then decide.

Start freeSee pricing