# MCP

# MCP

MCP (Model Context Protocol) is a standard way for AI tools to talk to other apps. Codecks runs an MCP server, so tools like Claude, ChatGPT, Claude Code, Cursor or VS Code can read your cards and, if you allow it, create and change them. You can then ask things like "What's in my hand?", "Which cards in the current Run are blocked?" or "Create a card for the crash on startup in the Bugs deck and assign it to me".

The server's address is:

```
https://mcp.codecks.io/mcp
```

You log in with your Codecks account when you connect. There's nothing to install and no token to copy.

## How it works

- **The AI tool acts as you.** Cards and comments it creates show you as the author, and it can never see or do more than your [role](https://manual.codecks.io/users/#roles) allows in each organization.
- **You pick the organizations.** When connecting, you choose which of your organizations the tool may access. A single connection can cover several of them.
- **You pick read or write.** _Read only_ lets the tool look at cards, decks, comments and so on. _Read and change_ also lets it create and update cards, write comments and more. See [Tools](#tools) for the full list.
- **Nothing gets deleted.** No tool deletes cards, decks, comments or anything else. Every change to a card is kept in its [history](https://manual.codecks.io/history/), so the tool (or you) can look up and restore an earlier version.

## Connecting

### Claude (claude.ai and the Claude apps)

1. Open **Settings → Connectors** and click **Add custom connector**
2. Enter `Codecks` as the name and `https://mcp.codecks.io/mcp` as the URL, then click **Add**
3. Click **Connect** next to Codecks. A Codecks page opens where you log in and [allow access](#the-consent-page)

The connector is added to your Claude account, so it's available in the web app, the desktop app and the mobile apps alike. To use it in a chat, make sure Codecks is turned on in the chat's tools menu.

### ChatGPT

1. Open **Settings → Plugins**, click **Add** and choose **Add MCP Server**
2. Enter `Codecks` as the name, set the type to **Streamable HTTP** (it defaults to STDIO) and enter `https://mcp.codecks.io/mcp` as the URL
3. Click **Authenticate**. A Codecks page opens where you log in and [allow access](#the-consent-page)

### Claude Code

Run this in your terminal:

```bash
claude mcp add --transport http codecks https://mcp.codecks.io/mcp
```

Then start Claude Code, type `/mcp`, select **codecks** and choose **Authenticate**. Your browser opens the Codecks page where you log in and [allow access](#the-consent-page).

### Cursor

Open this link to add Codecks to Cursor: [Add Codecks to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=Codecks\&config=eyJ1cmwiOiJodHRwczovL21jcC5jb2RlY2tzLmlvL21jcCJ9)

Or add it by hand to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "codecks": {
      "url": "https://mcp.codecks.io/mcp"
    }
  }
}
```

Cursor then shows a **Needs login** button next to Codecks in **Settings → MCP**. Click it to log in and [allow access](#the-consent-page).

### VS Code

Run this in your terminal:

```bash
code --add-mcp '{"name":"codecks","type":"http","url":"https://mcp.codecks.io/mcp"}'
```

Or add it to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "codecks": {
      "type": "http",
      "url": "https://mcp.codecks.io/mcp"
    }
  }
}
```

VS Code asks you to log in the first time it uses the server.

### Other tools

Any tool that supports remote MCP servers over "Streamable HTTP" with OAuth can connect with `https://mcp.codecks.io/mcp`. For a tool without OAuth support, use a [personal API token](#using-a-personal-api-token).

## The consent page

When you connect a tool, Codecks shows you what is asking for access before anything is shared:

- **The tool's name and the website it sends you back to.** Claude, ChatGPT, Cursor and VS Code are recognized by Codecks. Any other tool chooses its own name, so it's shown in quotes. If the name or the website doesn't match the tool you're connecting, cancel.
- **Your organizations**, each with a checkbox. Organizations where an admin turned MCP off aren't listed. On the Free plan, the [daily limit](#daily-limit) is shown next to the name.
- **Read only** or **Read and change.**

If you logged in more than 10 minutes ago, Codecks asks you to confirm it's you first, the same way as when changing your [security settings](https://manual.codecks.io/two-factor-authentication/).

After you click **Allow**, you receive an email naming the tool, the organizations and the access you granted. Connecting the same tool again replaces the earlier connection, so you can use this to add an organization or change the access.

## Tools

These are the actions the AI tool can take. You don't call them yourself: the AI picks them based on what you ask.

Every tool accepts a card's code (`$12a`), the code without the `$`, or the card's URL to refer to a card. If your connection covers several organizations, the AI picks the organization from a card URL, or from the projects you name.

### Reading

| Tool                 | What it does                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `get_context`        | lists your organizations and their projects                                                                                       |
| `list_decks`         | lists the decks of one or more projects                                                                                           |
| `search_cards`       | finds cards by text, deck, project, owner, status, milestone, Run, tag or priority                                                |
| `get_card`           | reads a card: content, status, owner, deck, effort, priority, due date, hero card, sub cards, dependencies, etc.                  |
| `get_comments`       | reads a card's [conversations](https://manual.codecks.io/conversations/)                                                          |
| `get_card_history`   | reads a card's [history](https://manual.codecks.io/history/): who changed what and when, and the full content of earlier versions |
| `list_conversations` | lists conversations, newest comment first: yours, another member's, or all of them                                                |
| `search_comments`    | finds comments by text                                                                                                            |
| `list_hand`          | reads a person's [hand](https://manual.codecks.io/hand/) and the cards they finished most recently                                |
| `list_milestones`    | lists upcoming, past or current [milestones](https://manual.codecks.io/milestones/)                                               |
| `list_runs`          | lists current, upcoming or completed [Runs](https://manual.codecks.io/runs/)                                                      |
| `list_members`       | lists the people in the organization and their roles                                                                              |

### Changing

Only available with _Read and change_ access.

| Tool                       | What it does                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `create_card`              | creates a card                                                                                                                 |
| `create_cards`             | creates up to 50 cards at once                                                                                                 |
| `update_card`              | changes a card's content, status, owner, deck, effort, priority, milestone, Run, etc.                                          |
| `update_cards`             | applies changes to several cards at once                                                                                       |
| `add_comment`              | starts a conversation (a comment, a [blocker](https://manual.codecks.io/conversations/) or a review request) or replies to one |
| `update_comment`           | edits a comment you wrote                                                                                                      |
| `set_thread_resolved`      | closes or reopens a conversation                                                                                               |
| `set_thread_participation` | stops or resumes [notifications](https://manual.codecks.io/notifications/) for a conversation                                  |
| `add_to_hand`              | adds cards to the end of a person's hand                                                                                       |
| `remove_from_hand`         | removes cards from a person's hand                                                                                             |
| `create_deck`              | creates a deck                                                                                                                 |
| `create_milestone`         | creates a milestone                                                                                                            |
| `update_milestone`         | changes a milestone                                                                                                            |

### What the tools can't do

- **Delete anything.** A single mistaken request should never cost you data. Delete cards and decks in Codecks itself.
- **Manage the organization.** Projects, members, billing and integrations stay in Codecks.
- **Upload files.**

> **Card content is data, not instructions**
>
> Cards and comments are written by people, and sometimes contain text that reads like an instruction ("ignore the above and…"). Codecks tells the AI tool to treat such text as content, not as something to follow. Still, read what the tool proposes to change before you confirm it, especially in organizations with many outside collaborators.

## Daily limit

Each request to a tool counts as one call against the organization it acts on:

| Plan | MCP tool calls per day |
| ---- | ---------------------- |
| Free | 100                    |
| Plus | no limit               |
| Pro  | no limit               |

The limit is shared by all members of the organization and resets at 00:00 UTC. `get_context` doesn't count, and neither do calls that fail because of the limit. Once the limit is reached, the AI tool tells you so, along with when it resets.

On top of that, a single connection can make 60 calls in quick succession, then one per second. Normal use never gets close to this.

You can see today's calls under **Your Profile → MCP Connections** and, as an admin, under **Organization Settings → Integrations → MCP**.

## Managing connections

### Your connections

**Your Profile → MCP Connections** lists every tool you connected, across all your organizations. For each one you see the organizations it covers, its access, when you connected it and when it was last used.

Click **Disconnect** to end a connection. The tool loses access to all its organizations right away. To use it again, connect it again from within the tool.

A connection that isn't used for 90 days ends by itself.

### For admins

**Organization Settings → Integrations → MCP** shows:

- **The Enabled switch.** MCP is on by default. Turning it off blocks every MCP request to the organization. Members' connections are kept and work again once you turn it back on.
- **Today's MCP tool calls** and the plan's limit.
- **Members' connections**, with the member, the tool, the access, and when it was connected and last used. Click **Revoke** to remove your organization from a member's connection. The member receives an email about it. Their connection keeps working in their other organizations.

When someone leaves the organization, their connections lose access to it automatically.

## Using a personal API token

Instead of logging in, you can send a [personal API token](https://manual.codecks.io/api/#personal-tokens) (`cdxut_…`) to `https://mcp.codecks.io/mcp`. This is useful for tools without OAuth support, or for scripts. The token's permission decides what the tool can do: _Read_ gives read-only access, anything above also allows changes. A token covers the one organization it belongs to.

For example, with Claude Code:

```bash
claude mcp add --transport http codecks https://mcp.codecks.io/mcp --header "Authorization: Bearer cdxut_..."
```

Organization tokens (`cdxat_…`) don't work with MCP: they don't belong to a person, and tools like `list_hand` need one.

## Privacy

The AI tool receives whatever its tools return: card content, comments, the names of members, owners and comment authors, and who changed a card and when. That data is then processed by the tool's provider (e.g. Anthropic for Claude, OpenAI for ChatGPT) according to your agreement with them. Only connect organizations whose content you're allowed to share with that provider. See our [privacy policy](https://www.codecks.io/privacy/) for details.