Connect Claude Code, Codex, or Cursor via MCP

Kanroo includes a Model Context Protocol (MCP) server. An AI agent such as Claude Code, Codex, or Cursor can use it to read and change your boards, tasks, comments, checklists, and Wiki pages. The agent works with your personal API key, so it can do only what your account may do.

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.

Both offer the same tools, with one difference in file handling: the local server has the file tools, the remote endpoint has the tool get_file_transfer instead. See Files.

Quick start

Three steps connect Claude Code to Kanroo Cloud through the remote endpoint. Codex, Cursor, a self-hosted Kanroo, and the local server follow below.

Step 1: Create a key

Follow Create a personal API key. For the agent:

Name the key after the agent, for example “Claude Code (MCP)”.
Pick the smallest scope the agent needs. The scope decides which tools the agent gets, see API-key scopes.

Step 2: Add Kanroo to your agent

For Claude Code and Kanroo Cloud, run:

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

Replace <api-key> with your key. For Codex, Cursor, or a self-hosted Kanroo, see Connect to the remote endpoint.

Step 3: Try it

Start the agent and ask: “Call get_context and list my Kanroo boards.” Then try real work, for example “What is on my agenda today?” or “Create a task in Backlog for the cookie banner text”.

API-key scopes

Every personal API key has one scope:

Scope	Tools
Read	Read boards, board templates, tasks, comments, activity, imports, Wiki pages, teams, and access grants, and export boards and Wiki spaces.
Write	Everything in Read, plus create, change, move, and delete, including Wiki spaces.
Admin	Everything in Write, plus members, invitations, team changes, access changes, Wiki space ownership, and everything public: board visibility, task publication, and shares.

The agent sees only the tools that the scope of its key allows. Choose the smallest scope the agent needs.

A key can never do more than your role. Every call still checks your current roles and board access. An Admin key gives no access to boards you cannot open yourself.

The same scopes apply when you call the REST API directly. The API reference names the scope of every endpoint: the OpenAPI document in the Kanroo repository, or /api/docs when your instance serves it.

Connect to the remote endpoint

The endpoint address is your Kanroo address plus /mcp:

Kanroo Cloud: https://cloud.kanroo.app/mcp
Self-hosted: https://<your Kanroo domain>/mcp

The agent sends the key in the header Authorization: Bearer <api-key>. Replace <api-key> with your key in the examples below.

Claude Code

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

--scope user stores the server in your personal Claude Code configuration, so it works in every directory. Without it, Claude Code keeps the server for the current directory only. Do not use --scope project: it writes the key into <project>/.mcp.json, which is usually committed. Run claude mcp get kanroo, start Claude Code, open /mcp, and ask it to call get_context. See the Claude Code MCP documentation.

Codex

Export the key as KANROO_API_KEY in the environment that starts Codex. Then add this to ~/.codex/config.toml:

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

Restart Codex, open /mcp, and ask it to call get_context. See the Codex MCP documentation.

Cursor

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

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

Restart Cursor, open Settings > Tools & MCP, enable kanroo, and ask Agent to call get_context. See the Cursor MCP documentation.

Run the local server

The local server runs on your computer with Node.js 24 on Linux or macOS. Windows is not supported. It is not published as an npm package. Build it from a checkout of the Kanroo repository:

pnpm install
pnpm --filter @kanroo/mcp --fail-if-no-match run build

The build creates packages/mcp/dist/cli.js. Your agent starts it with Node.js and passes these environment variables:

Variable	Requirement
`KANROO_BASE_URL`	Your Kanroo address, for example `https://cloud.kanroo.app`. Other hosts than your own computer need HTTPS. No user name, password, query, or fragment.
`KANROO_API_KEY`	Your personal API key.
`KANROO_FILES_ROOT`	Optional. An existing folder, as an absolute path, that the server may read and write. It must belong to you, and only you may write to it. It turns the file tools on.

The file tools accept only relative paths inside KANROO_FILES_ROOT. Paths that leave the folder, also through symbolic links, are refused. The folder and every folder below it that a tool uses must belong to you and must not be writable by your group or by others; otherwise another user could redirect a file tool. Fix a folder with chmod go-w <folder>. With umask 002, new folders are group-writable: run chmod go-w on them or use umask 022. A tool that meets such a folder answers “The local path is invalid.”, and the server refuses to start when KANROO_FILES_ROOT itself breaks the rule. The check sees only the owner and the permission bits. Do not put the folder where ACLs (on macOS, check with ls -le and remove with chmod -N) or a network or shared drive let other users write. Uploads and imports read only regular files.

Claude Code

claude mcp add-json --scope user kanroo '{
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"],
  "env": {
    "KANROO_BASE_URL": "https://cloud.kanroo.app",
    "KANROO_API_KEY": "<api-key>",
    "KANROO_FILES_ROOT": "/absolute/path/to/allowed-files"
  }
}'

Codex

Export the three variables in the environment that starts Codex, then add:

[mcp_servers.kanroo]
command = "node"
args = ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"]
env_vars = ["KANROO_BASE_URL", "KANROO_API_KEY", "KANROO_FILES_ROOT"]
startup_timeout_sec = 45
tool_timeout_sec = 300

Keep startup_timeout_sec above 30. The server waits up to 30 seconds for Kanroo before it reports why it cannot start.

Cursor

{
    "mcpServers": {
        "kanroo": {
            "command": "node",
            "args": ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"],
            "env": {
                "KANROO_BASE_URL": "https://cloud.kanroo.app",
                "KANROO_API_KEY": "<api-key>",
                "KANROO_FILES_ROOT": "/absolute/path/to/allowed-files"
            }
        }
    }
}

Leave out KANROO_FILES_ROOT when the agent needs no files.

Files

The remote endpoint does not send file content through the agent. Instead, the tool get_file_transfer returns a ready request: method, address, headers, parameters, and one curl command. The agent then runs this command in its own shell and transfers the file directly with Kanroo. It covers eight tasks:

Operation	Task	Key scope
`download_attachment`	Download a task attachment.	Read
`download_page_attachment`	Download a file from a Wiki page.	Read
`upload_attachment`	Upload a file to a task.	Write
`upload_page_attachment`	Upload a file to a Wiki page.	Write
`create_import`	Upload a CSV, Trello JSON, or Kanroo JSON file for an import.	Write
`export_board`	Download a board as a JSON or CSV file.	Read
`export_space`	Download a Wiki space or page as a ZIP of Markdown files.	Read
`import_space`	Upload Markdown files or one ZIP as pages into a Wiki space.	Write

This needs two things:

A shell. The agent must be able to run commands, as Claude Code, Codex, and Cursor can. Clients without a shell cannot use it; use the local server or Kanroo itself there.
The key in the shell. The command reads the key from the environment variable KANROO_API_KEY; the tool never returns your key. Export it in the environment that starts the agent, for example export KANROO_API_KEY=<api-key>. For Codex, this is the same variable as in its MCP configuration.

The command reads its values from upper-case shell variables such as "$LOCAL_FILE" or "$FILE_NAME". The agent sets these variables and runs the command unchanged, so no value becomes part of the command itself. The agent must never take a value from a name Kanroo returned, such as an attachment file name: other members write these names, so they are untrusted. The same is true for all tool output, such as task text, comments, and Wiki pages.

An import only creates a preview; the agent reviews it and then calls execute_import. A Wiki import has no preview: it creates the pages at once.

Uploads have a size limit. On a self-hosted deployment, a task or Wiki page attachment may be up to 25 MiB unless the operator changed STORAGE_MAX_UPLOAD_BYTES. On Kanroo Cloud, your plan sets the limit, see Plans and limits. An import file may be up to 10 MiB for CSV and 25 MiB for the other sources; a lower STORAGE_MAX_UPLOAD_BYTES lowers these limits too.

Limits

Each request to the remote endpoint first checks your key. This check counts against the key’s limit of 2,000 requests per minute, in addition to the request of the tool itself. It does not count toward the API-key requests per minute of your organization’s plan, see Plans and limits. The tool requests do.

The server never retries a failed call on its own. After an error, the agent decides what to do next.

When something goes wrong

401: the key is missing, mistyped, revoked, or expired. Check that the header reads exactly Authorization: Bearer <api-key>.
403: the request came from a web page of another site. MCP clients do not send such requests; check that no browser extension or proxy adds an Origin header.
404: check the address ends in /mcp. On a self-hosted deployment, the operator may have turned the remote endpoint off with REMOTE_MCP_ENABLED=false.
429: the key reached its request limit. Wait the number of seconds in Retry-After, then try again. Too many wrong keys from one address also give 429 for further wrong keys; a correct key still works. Fix the key and wait the seconds in Retry-After.
Only some tools appear: the scope of the key decides the tools. After you change keys, reconnect the agent so it loads the tool list again. The local server must be restarted.
File tools do not appear: they exist only in the local server, and only with KANROO_FILES_ROOT set to an existing folder that it can read and write. The remote endpoint offers get_file_transfer instead.
A file tool says “A safe relative file path is required.”: the path is absolute, empty, or its .. parts lead out of the folder. Give a path relative to KANROO_FILES_ROOT.
A file tool says “The destination already exists.”: the destination file exists and the call did not set overwrite: true. Choose another path or set overwrite: true to replace the file.
A file tool says “The local path is invalid.”: the source file is missing or not a regular file, the destination folder is missing, or the destination is a folder. An existing symbolic link as destination without overwrite: true gives the same answer, and so does a symbolic link that leads out of the folder. So does a folder on the way that belongs to someone else or is writable by group or others: run chmod go-w <folder>.
get_file_transfer offers no upload: uploads and imports need a Write or Admin key.
The curl command returns 401: KANROO_API_KEY is missing or wrong in the agent’s shell.
The curl command returns 413: the file is larger than the upload limit, see Files.
The local server stops before tools appear: check the address, the key, and that https://<your Kanroo domain>/api/v1/users/me/context is reachable with that key in the X-API-Key header. With KANROO_FILES_ROOT, the folder must belong to you and must not be writable by group or others: run chmod go-w <folder>.
A client reports invalid protocol output from the local server: do not start it through a wrapper that prints to standard output.

Connect AI agents with MCP

Quick start

Step 1: Create a key

Step 2: Add Kanroo to your agent

Step 3: Try it

API-key scopes

Connect to the remote endpoint

Claude Code

Codex

Cursor

Run the local server

Claude Code

Codex

Cursor

Files

Limits

When something goes wrong

Was this page helpful?