Docs · Setup & everyday use
Codon MCP
Codon MCP gives Claude Code, Codex, Cursor and your other MCP clients one shared task queue — the same one CodonTerminal runs. Agents can queue work, claim it, and report it done. It runs on your machine, keeps its files in your project, and nine of its ten tools are free.
Set it up
Check you have Node.js 20 or newer
That is the only prerequisite. There is nothing to download from us and no account to create — your MCP client fetches and runs the server on demand with npx. If you have CodonTerminal, you can skip npm entirely: Settings → Connect tools shows ready-to-paste commands that use the copy bundled with the app.
Get Node.js →Add Codon to your MCP client
Codon speaks stdio, so you add it as a command rather than a URL. In Claude Code: claude mcp add codon --scope user -- npx -y codon-mcp. In Codex: codex mcp add codon -- npx -y codon-mcp. Anywhere else, add {"mcpServers": {"codon": {"command": "npx", "args": ["-y", "codon-mcp"]}}} to the MCP configuration. On native Windows, if the client cannot launch npx directly, put cmd /c in front (for example -- cmd /c npx -y codon-mcp). Restart the client, then check the server shows as connected in a new chat.
Point it at a project
Each tool works on one project folder. It takes the workspace from the tool call if given one, otherwise the CODON_WORKSPACE environment variable, otherwise the folders your client says you have open, otherwise the current folder — but only if that is a git repository or already has a .codon folder. If none of those fits, it asks rather than guessing.
Optional: Gattaca Plus for codon_plan
Nine tools need no key. codon_plan, which turns a goal into a queue of tasks, is part of Gattaca Plus ($15/month) and runs through CodonTerminal, so the app must be open. Subscribe from your account, create an API key there, and add it in CodonTerminal under Settings → License — the MCP server itself never needs the key. Copy the key when it is shown: Gattaca keeps only a one-way hash of it and cannot show you the same key twice.
Open your Gattaca account →
Everyday use
The ten tools
- codon_status — which coding CLIs are installed and signed in, which are resting after a usage limit, and whether the queue is running or paused.
- codon_tasks — list the queue: Queued → Running → Review → Done or Failed.
- codon_task_add — queue a task, optionally pinned to a route such as codex, claude:opus or an API model. Unless the queue is paused, the next free subscription picks it up.
- codon_task_update — edit a task, add a note, or change its status.
- codon_task_claim — take a task to do in this session. It returns the task and the project brief.
- codon_task_complete — report a claimed task ready for review, done, failed, or handed back to the queue.
- codon_brief — read or replace .codon/brief.md, the one context file every task sees.
- codon_run — start a task on CodonTerminal's swarm now, in its own git worktree. Needs the app.
- codon_plan — turn a goal into a queue of tasks. Needs the app and Gattaca Plus.
- codon_usage — subscription token usage from the CLIs' own local logs, plus today's API spend.
With the app, or without it
When CodonTerminal is running, every call goes through the app's engine: the queue updates on screen immediately, and codon_run hands work to the swarm, which routes it to whichever subscription has room. When the app is closed, the task tools read and write the project's .codon/tasks.json directly, using the same code the app uses — so work you queue from an agent chat is waiting in CodonTerminal the next time you open it.
About CodonTerminal →Queued is not running — unless the app is
On its own, Codon MCP coordinates work; it does not perform it. codon_task_add writes a task to the queue and nothing more. An agent in your chat can claim it and do it, or CodonTerminal's queue can run it in a worktree. codon_run and codon_plan say plainly when the app isn't there to do the work.
Where Codon keeps things
Everything lives in a .codon folder inside your project: tasks.json for the queue, brief.md for the project brief, and runs/ for the task file and log of each swarm run. It is project-local on purpose. The brief is meant to be committed; the rest can stay out of git.
Coming from codon-mcp 0.3
2.0 replaces the 0.3 tool set. The board, status-board, mission and reviewer tools are gone; the queue, claim and complete tools cover the same ground with less ceremony, and planning and review moved into CodonTerminal (Plan and Second opinion). The first time CodonTerminal 2.0 opens a project, it imports the old board.json once. If you still run CodonTerminal 0.1.x, pin the old server with npx -y codon-mcp@0.3.
What leaves your machine
Nothing, from the MCP server itself. It makes no network calls of its own: it talks to your MCP client over stdio and to CodonTerminal over loopback when the app is running. It does not proxy model requests, and it never copies or sends a provider's sign-in — it only looks at each CLI's own files to report whether you're signed in. Beyond your own model providers, CodonTerminal makes three kinds of network call: the license check, which sends just your Gattaca key; the OpenRouter model list, if you add OpenRouter; and the one-time voice model download, if you use voice.