The MCP server
Every workflow is also an MCP server, so outside agents can read cards, move them and trigger workers — the tools it offers, how tokens are scoped, and what a token can never do.
Every workflow's board is also an MCP server. Point an outside agent at it — Claude Code, Codex, Kiro, Devin, anything that speaks the Model Context Protocol — and it can read cards, move them and trigger the worker on a station.
This is how CodeBook works with the agents you already use rather than instead of them: they do their work wherever they run, and the factory is where that work is queued, routed, gated and recorded.
Running your factories as yourself from Claude or ChatGPT? That is a different connector:
https://app.codebook.work/mcp, signed in with your Bookbag account, covering every factory you can see. See Run your factory from the chat. This page is about the per-workflow server, which agents reach with a workflow's token.
The endpoint
https://app.codebook.work/kanban/api/mcp
It speaks JSON-RPC over Streamable HTTP: one POST per message, no stdio, no long-lived stream. It implements initialize, tools/list, tools/call and ping.
The token
The credential is an API token, created on the workflow itself. A token names exactly one workflow.
That is a design decision worth understanding: because the token names the workflow, the workflow is never a parameter. There is no tool you can call with somebody else's id, because there is no id to pass. A card id guessed from another workflow reads as no such card.
Scopes
A token is read-only unless its scope is write.
Anything else — a missing scope, an unrecognised value, a token minted before write support existed — is treated as read-only. It fails closed, deliberately.
tools/list still shows the write tools to a read-only token, and says plainly why they cannot be called. A tool that is invisible produces a client that guesses; a tool that explains its refusal produces one that tells you what to fix.
The tools
Reading
| Tool | What it does |
|---|---|
board_overview |
The workflow's board, its groups and columns, with counts |
list_columns |
The columns |
list_cards |
Cards, filterable |
get_card |
One card in full — fields, checklist, discussion |
list_comments |
A card's discussion |
Writing (requires scope: write)
| Tool | What it does |
|---|---|
create_card |
Create a card in a column |
update_card |
Change a card's fields |
move_card |
Move a card to another column — entering a station starts its worker, exactly as a drag would |
delete_card |
Delete a card and its child content |
add_comment |
Add to a card's discussion |
trigger_worker |
Queue the station's worker for a card |
Outside workers
A workflow token also lets an external worker follow events and work an assigned station. Use the workflow’s Share & API access dialog to name the token. Select Can write when the worker will claim or update work. The runner must retain its own claim for that run. Treat the token as a credential.
| Tool | When to use it |
|---|---|
list_events |
Read workflow events after a saved cursor. |
list_work |
Find runs waiting for a pull worker in this workflow. |
claim_work |
Take one waiting run and receive its brief and claim information. |
start_run, heartbeat |
Mark a claimed run active and keep its lease current while work continues. |
get_context, get_memory, get_instructions |
Read the claimed run’s brief, permitted memory and assigned agent instructions. |
run_comment, produce_artifact |
Record progress and attach a typed result to the run’s story. |
report_usage |
Record the worker’s cumulative token usage for this run. |
request_human |
Send a decision to a person and stop execution at the gate. |
complete_work |
Report pass, fail or blocked with evidence. The station’s routing rules determine the destination. |
For a runnable worker, the SDK guide covers setup, claiming, renewals and reporting a result. Worker SDK
trigger_worker
This is the one that makes CodeBook part of a toolchain rather than a destination. An agent in your editor that has just discovered a bug can file the card and start the QA worker on it; a nightly job can move a release card and let the line take over.
It respects everything the workflow already enforces: approvals, the station's permissions, and the retry limit. A trigger through MCP is the same job as a trigger through a drag.
What a token is not
A token is not a person. It does not impersonate a member and it is not resolved to one.
- Writes go through the same services the app's own controllers use, so the workflow's rules and validation apply identically. A refused move comes back as a refusal, not a silent no-op.
- A card or comment created through a token carries the token's name —
Claude,QA agent— as its author label, so the discussion shows what actually wrote it.
Connecting a client
In your MCP client's configuration, add the endpoint above with the token as a bearer credential. In Claude Code or Claude Desktop that is a remote MCP server entry; in another agent or editor it is whatever it calls a remote MCP server.
Then ask it to list your columns. If that works, everything else will.
Connecting tools to a worker
The MCP server is CodeBook answering. The reverse — a worker on a station using somebody else's MCP server, such as live documentation or a browser test runner — is Tool connections.