apps/docs/integrations/mcp-server.mdx
Rama main · réplica de lectura del repositorio original.
---
title: "MCP Server"
description: "Control Kan from Claude Desktop, Codex, and other MCP-compatible AI clients."
tag: "NEW"
---
Kan ships with a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets any MCP-compatible AI client read and control your Kan instance using natural language: list boards, move cards, manage checklists, invite members, and more.
## Two ways to connect
<CardGroup cols={2}>
<Card title="Hosted" icon="cloud" color="#0284c7">
Point your client at `https://mcp.kan.bn` with an API key. No install, no
environment variables. **Requires a Team, Pro, or Enterprise workspace
plan** on Kan Cloud.
</Card>
<Card title="Local" icon="terminal" color="#65a30d">
Run the server yourself with `npx`. Works against self-hosted or Kan Cloud
instances, on any plan including Free.
</Card>
</CardGroup>
## Hosted (Kan Cloud)
<Note>
The hosted endpoint requires a **Team, Pro, or Enterprise** workspace plan. An
API key belonging to an account with only Free-plan workspaces gets a `403`
from every request. Use the Local server below instead: it works on any plan.
</Note>
Get a Kan Cloud API key from **Settings → API Keys → Create key**, then point your client at:
```
https://mcp.kan.bn
```
authenticating with:
```
Authorization: Bearer kan_your_api_key_here
```
For example, in Claude Desktop's config:
```json
{
"mcpServers": {
"kan": {
"type": "http",
"url": "https://mcp.kan.bn",
"headers": {
"Authorization": "Bearer kan_your_api_key_here"
}
}
}
}
```
<Note>
Exact config syntax for remote/HTTP MCP servers varies by client and changes
as clients add support. Check your client's docs if the shape above doesn't
match. Every client needs the same two things: the URL and the `Authorization:
Bearer` header.
</Note>
## Local (self-hosted or Kan Cloud, any plan)
### Prerequisites
- Node.js 18+
- A running Kan instance (self-hosted or cloud)
- A Kan API key (**Settings → API Keys → Create key**)
### Installation
You do **not** need to clone the repository. The recommended way is `npx`, which runs the server on-demand and always uses the latest version:
```bash
npx -y @kan.bn/mcp
```
Alternatively, install it globally:
```bash
npm install -g @kan.bn/mcp
kan-mcp
```
### Configuration
The server is configured via two environment variables:
| Variable | Description |
| --------------- | ----------------------------------- |
| `KAN_BASE_URL` | Base URL of your Kan instance |
| `KAN_API_TOKEN` | API key from your Kan user settings |
`KAN_BASE_URL` is whatever instance you're running the API key against:
<Tabs>
<Tab title="Kan Cloud">
```bash
KAN_BASE_URL=https://kan.bn
```
</Tab>
<Tab title="Self-hosted">
```bash
KAN_BASE_URL=https://your-kan-instance.com
```
During local development against a self-hosted instance running on your machine, this is typically:
```bash
KAN_BASE_URL=http://localhost:3000
```
</Tab>
</Tabs>
### Client setup
<Tabs>
<Tab title="Claude Desktop">
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"kan": {
"command": "npx",
"args": ["-y", "@kan.bn/mcp"],
"env": {
"KAN_BASE_URL": "https://your-kan-instance.com",
"KAN_API_TOKEN": "kan_your_api_key_here"
}
}
}
}
```
</Tab>
<Tab title="Codex CLI">
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.kan]
command = "npx"
args = ["-y", "@kan.bn/mcp"]
env = { "KAN_BASE_URL" = "https://your-kan-instance.com", "KAN_API_TOKEN" = "kan_your_api_key_here" }
```
</Tab>
<Tab title="Cursor / VS Code Copilot / other">
Every MCP stdio client follows the same `command` + `args` + `env` pattern shown above. Point it at:
```bash
command: npx
args: -y @kan.bn/mcp
env: KAN_BASE_URL, KAN_API_TOKEN
```
</Tab>
</Tabs>
<Note>
ChatGPT's MCP support is oriented around remote connectors configured via its
own UI rather than a client-side config file like the ones above. Check
ChatGPT's own connector docs for how it expects the URL and credentials to be
supplied.
</Note>
## Example prompts
Once connected, you can ask your AI assistant things like:
**Browsing**
- _"List all my workspaces"_
- _"Show me all boards in the Marketing workspace"_
- _"What cards are in the Backlog list of the Q3 Planning board?"_
- _"Get the full details of card X including comments and checklists"_
**Managing cards**
- _"Create a card called 'Fix login bug' in the To Do list of the Dev board"_
- _"Move the 'API redesign' card to the In Progress list"_
- _"Set a due date of next Friday on the 'Write docs' card"_
- _"Add a comment to the 'Deploy to prod' card saying the deployment is blocked"_
- _"Duplicate the 'Sprint template' card into the new Sprint 4 list"_
- _"Mark the 'Setup CI' checklist item as complete"_
**Organisation**
- _"Add the 'urgent' label to all cards assigned to me in the Backend board"_
- _"Create a 'Release checklist' checklist on the v2.0 card with items: smoke test, update changelog, tag release"_
- _"What tasks are assigned to @alice in the Mechanics Rework board?"_
**Workspace management**
- _"Create a new workspace called 'Client Projects'"_
- _"Invite bob@example.com to the Marketing workspace as a member"_
- _"Create a new board called 'Sprint 5' in the Dev workspace with lists: Backlog, In Progress, Done"_
- _"Search for anything related to 'authentication' across the Dev workspace"_
## Available tools
The MCP server exposes 46 tools across 7 resource types:
| Resource | Tools |
| ----------------- | ------------------------------------------------------------------- |
| Workspaces | list, find by name, get, create, update, delete, search, check slug |
| Boards | list, find by name, get, get by slug, create, update, delete |
| Lists | create, update, delete |
| Cards | create, get, update, delete, duplicate, get activities |
| Card interactions | add/update/delete comment, toggle label, toggle member |
| Checklists | create, update, delete, create item, update item, delete item |
| Labels | get, create, update, delete |
| Members | invite, remove, update role, manage invite links |
## Troubleshooting
<AccordionGroup>
<Accordion title="The hosted endpoint returns a 403">
The API key's account doesn't have a Team, Pro, or Enterprise workspace. The
hosted server (`mcp.kan.bn`) is a paid-plan feature. Either upgrade a
workspace, or switch to the Local setup above, which works on any plan.
</Accordion>
<Accordion title="Every tool call fails with an authentication error">
Double check `KAN_API_TOKEN` (local) or the `Authorization` header (hosted):
it must be a key created under **Settings → API Keys**, not your login
password. For the local server, confirm `KAN_BASE_URL` points at the
instance the key was created on (a self-hosted key won't work against Kan
Cloud, and vice versa).
</Accordion>
<Accordion title="Calls start failing partway through a long session">
API keys are rate limited to 100 requests per minute. An AI client looping
through many tool calls in quick succession (for example, resolving names to
IDs one board at a time) can hit this. Ask it to slow down, or batch fewer
operations per prompt.
</Accordion>
<Accordion title="The client can't find the kan-mcp command">
This applies to the Local setup only. Make sure Node.js 18+ is installed and
on the `PATH` the client uses to spawn subprocesses. GUI apps like Claude
Desktop don't always inherit your shell's `PATH`. Using the full `npx`
invocation (rather than a bare `kan-mcp` after a global install) avoids this
in most cases.
</Accordion>
</AccordionGroup>