Skip to content
CodeBook

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.