MCP Integration

You don't need the VS Code extension to use AgentKanban with an agent. The board has an MCP server (Model Context Protocol - a standard way of giving an agent tools), and any harness that speaks MCP over HTTP can connect to it with an API key. That covers Claude Code, Codex CLI, VS Code / Copilot without the extension, Claude Desktop, Cursor and most other current harnesses.

This page covers how to connect, which API key to create, and how to prompt your agent with a task ID so it fetches everything it needs from the board itself.

What you get: the full set of board tools - read a task with its comments, todos and board instructions, read and update board memory and the technical document, add comments, tick todos, move tasks between lanes, create tasks, download assets.

What you don't get: the things the extension does on top of MCP. There's no turn capture (your chat isn't recorded to the task), no Resume button, no AGENTS.md injection and no Git worktree integration. If you want those, see VS Code Extension. The two approaches aren't exclusive - the extension itself uses this same MCP server.

The endpoint

https://www.agentkanban.io/api/mcp/v1

Transport is streamable HTTP. Every request needs a bearer header:

Authorization: Bearer ak_YourApiKeyHere

The Settings > API Keys page shows the endpoint for whichever host you're on and has a copyable config snippet.

Create an API key

Go to Settings > API Keys and click Create API key. The full mechanics (revealing, revoking, per-board grants, rate limits) are in API Keys - this is just what to pick for an agent harness.

Board access: tick All boards. The key then follows you onto any board you're given access to later, and it's always capped at your own permission on each board. Per-board keys are better suited to CI and shared scripts than to your own agent.

Permission: Edit. A Read key will happily return task context, but every update, comment, todo and move tool will fail, which makes for a confusing first session. Choose Read only if you genuinely just want the agent to ask questions about the board.

One key per machine and harness. Name them that way ("Laptop - Claude Code", "Desktop - Codex") so you can revoke one without breaking the others. Keys are personal to you, so a teammate needs their own.

Storage: put the key in config that lives outside the repository where you can. Each harness below has a user-level option. If you do use a project-level file (.mcp.json, .vscode/mcp.json), either gitignore it or use the harness's variable expansion so the raw key never lands in the file. Keys can be revealed again from Settings at any time, so there's no need to keep a copy elsewhere.

Rotation: revoke the old key in Settings, create a new one, paste it into each config. Revocation is immediate.

Claude Code

The quickest route is the CLI. User scope makes the server available in every project on the machine and keeps the key out of the repository:

claude mcp add --transport http agent-kanban https://www.agentkanban.io/api/mcp/v1 \
  --scope user \
  --header "Authorization: Bearer ak_YourApiKeyHere"

Drop --scope user (the default is local, which is per-project and also outside version control) if you'd rather it only applied to the current project.

If you prefer a file, or want the server shared with everyone who clones the repo, Claude Code reads .mcp.json at the project root:

{
    "mcpServers": {
        "agent-kanban": {
            "type": "http",
            "url": "https://www.agentkanban.io/api/mcp/v1",
            "headers": {
                "Authorization": "Bearer ${AGENT_KANBAN_API_KEY}"
            }
        }
    }
}

Claude Code expands ${VAR} from your environment, so this file is safe to commit with each developer setting AGENT_KANBAN_API_KEY in their shell. Replace the placeholder with the raw key only if the file is gitignored.

Check it's connected with claude mcp list, or /mcp inside a session.

Codex CLI

Codex keeps MCP config in ~/.codex/config.toml, which is per-user so already outside the repo. Add:

[mcp_servers.agent-kanban]
url = "https://www.agentkanban.io/api/mcp/v1"
bearer_token_env_var = "AGENT_KANBAN_API_KEY"

Then set AGENT_KANBAN_API_KEY in your shell environment. If you'd rather not use an environment variable, http_headers takes a static value instead:

[mcp_servers.agent-kanban]
url = "https://www.agentkanban.io/api/mcp/v1"
http_headers = { "Authorization" = "Bearer ak_YourApiKeyHere" }

You can also register the URL with codex mcp add agent-kanban --url https://www.agentkanban.io/api/mcp/v1 and then add the auth line to the generated table by hand.

VS Code and Copilot (without the extension)

VS Code has its own MCP support, so Copilot agent mode can use the board without the AgentKanban extension. Create .vscode/mcp.json:

{
    "inputs": [
        {
            "type": "promptString",
            "id": "agent-kanban-api-key",
            "description": "AgentKanban API key",
            "password": true
        }
    ],
    "servers": {
        "agent-kanban": {
            "type": "http",
            "url": "https://www.agentkanban.io/api/mcp/v1",
            "headers": {
                "Authorization": "Bearer ${input:agent-kanban-api-key}"
            }
        }
    }
}

VS Code prompts for the key once on first start and stores it securely, so the file is safe to commit. Note the top-level key is servers here, not mcpServers.

To make it global rather than per-workspace, run MCP: Open User Configuration from the Command Palette and put the same servers block there.

Other MCP clients

Anything that supports streamable HTTP servers with custom headers will work. The generic shape (used by Claude Desktop, Cursor and most others) is the snippet from the API Keys page:

{
    "mcpServers": {
        "agent-kanban": {
            "url": "https://www.agentkanban.io/api/mcp/v1",
            "headers": {
                "Authorization": "Bearer ak_YourApiKeyHere"
            }
        }
    }
}

Check your client's docs for where that file lives and whether it wants type: "http" spelled out. If your client only supports stdio servers, you'll need a stdio-to-HTTP bridge (there are several on npm) - we don't ship one.

Prompting with a task ID

Without the extension there's no AGENTS.md telling the agent which task is active, so you name it in the prompt. Every task has a UUID.

Get the task ID

Open the task and click Copy ID in the task header. You can also take it from the URL - it's the last segment:

https://www.agentkanban.io/boards/<board-id>/tasks/<task-id>

Start a session

The MCP server's own instructions tell agents to call get_task_context first, and that one call returns the task description, comments, captured turns, todos and the board's agent instructions. So the prompt is short:

Use the agent-kanban MCP server to load task 7c1e4b2a-9f3d-4a8e-b6c5-2d1f0e9a8b7c
with get_task_context, then start on the first outstanding todo.

The agent doesn't need the board ID - the task ID resolves it.

Follow-on prompts

A few that work well once the task is loaded:

Make it stick

Add a line to your own AGENTS.md or CLAUDE.md so you don't have to spell it out every time:

When given an AgentKanban task ID, call get_task_context on the agent-kanban
MCP server before doing anything else. Keep the task's todos up to date as you
work and never post conversation as comments.

That last clause matters if you later add the extension - turn capture records the conversation, and comments posted by the agent would duplicate it.

Troubleshooting