# Connect Cursor to iKanban

Cursor's agent can work with your iKanban board without leaving the editor: pull the next task from the sprint, open an issue for the bug in front of you, add a comment with what you changed, and move the task along when you are done. It connects through the **iKanban MCP server**, a remote [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.i-kanban.com/sse`.

The MCP server is included in every paid plan, from Starter up, with no daily call limit (fair use). See [Pricing](/pricing) for the plans.

## What you need

- An iKanban workspace on a paid plan.
- A personal API key. Open **Settings → API Keys**, create a key, and copy it. Keys start with `vk_` and are shown once.
- Cursor.

## 1. Add the server to mcp.json

Cursor reads MCP servers from `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` in a project folder (that project only). Add an `ikanban-remote` entry:

```json
{
  "mcpServers": {
    "ikanban-remote": {
      "url": "https://mcp.i-kanban.com/sse",
      "headers": {
        "Authorization": "Bearer ${env:IKANBAN_API_KEY}"
      }
    }
  }
}
```

A remote server is recognised by its `url`; there is no `type` field to set. `${env:IKANBAN_API_KEY}` reads the key from an environment variable so it never sits in the file — set `IKANBAN_API_KEY` to your `vk_` key in the environment Cursor starts from. If you would rather paste the key, write `"Bearer vk_your_key_here"` instead, and keep that file out of version control.

Do not commit a project-level `.cursor/mcp.json` that contains a real key.

## 2. Try it

Restart Cursor so it loads the new server, then ask the agent, using your own team's identifier:

```text
List the open tasks in the ENG team.
```

The agent calls `list_issues` and replies with the tasks. From there it can create and update tasks, assign them, comment, move them between columns, and manage sprints and documents.

## What it can and cannot do

- **Read, create and update.** Teams, issues, projects, sprints, releases, documents, folders, comments and tags. The full, current tool list is in the app under **Settings → MCP Servers**.
- **No delete.** Nothing can be deleted over MCP, by design. Remove things in the web app.
- **Human identifiers.** Teams are addressed by their key (`ENG`) and issues by their key (`ENG-42`); projects, sprints and documents use the ids returned by the matching `list_*` tool.

The [MCP field guide](/docs/mcp/mcp-usage-from-field) covers each tool group, the parameters that trip people up, and a troubleshooting table.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `401` or "unauthorized" | The environment variable is not set where Cursor runs, or the key was deleted | Check `IKANBAN_API_KEY`, or paste the key directly to rule it out; create a new key if needed |
| No iKanban tools appear | Cursor has not reloaded `mcp.json` | Restart Cursor; check the JSON is valid |
| Refused although the key is valid | MCP is switched off for your keys, or the client is not on the allowed-client list | Check the MCP access switch and allowed clients on **Settings → API Keys**; changes can take up to five minutes |
| A delete request is refused | Deletes are not exposed over MCP | Delete in the web app |

Using Claude Code? See [Connect Claude Code](/docs/mcp/claude-code). Other agents: [Other MCP clients](/docs/mcp/other-clients).