The four servers
Which runtimes get which servers
127.0.0.1.
Attach an outside agent
Any MCP client can attach. Pick a transport first:Choose a team and an agent id
external-claude (the warning below says why). List the teams, and the agents that already exist (replace 18790 with your server’s port, which is in ~/.clawboo/api-port.txt):id. Each agent has an id, a displayName and a teamId. Add the access cookie to these requests and to the next one: -b "clawboo_access=$(cat ~/.clawboo/access-token)" on a default install, or -b "clawboo_access=$STUDIO_ACCESS_TOKEN" when you set that variable. Leave it out only when STUDIO_ACCESS_TOKEN= is set blank.Get a signed attach URL
snippet is the line to paste. structured is the same server as an object, for clients you configure with JSON.Add it to your agent
? is a wildcard in zsh, and an & ends the command in any shell.[mcp_servers.clawboo-tasks] entry for ~/.codex/config.toml. Other clients take the url from structured.Repeat for each server it needs
server=memory, server=tools and server=teamchat that the agent should use. You should see the servers in your agent’s list (in Claude Code, claude mcp list).How agents name and create tasks
The Tasks tools take a task’s readable id (MAR-12) wherever they take its id. Creates are safe to repeat: the same create, or an open task with the same title under the same parent from the last 48 hours, returns the existing task with deduplicated: true. An agent can set a priority up to High. See MCP tools.
What an attached agent can do
What an agent may do depends on the URL it attaches with. A URL counts as signed only when itsscopeSig matches the ids in it. A URL without a signature, or with any id edited by hand, is served as unsigned, and so is the default snippet you get without scopeTeamId or scopeAgentId.
teamRun=1, on their Tasks, Memory and Tools URLs. The team engine claims and moves those tasks itself, so those runs get no claims and no status writes except block_task, ask_person and hand_back_task on the agent’s own task. They also get report_result, which moves nothing. The mark is inside the signature, and no URL such a run holds is signed without it, so a runtime that edits its own config cannot win the writes back. You cannot mint such a URL from /api/mcp/config.
A run on a board task also carries that task on its Tasks URL, as scopeTaskId, inside the same signature. get_task, add_comment and block_task use it when a call names no task. It is a default, not a permission: it opens no task the run could not already reach, and a runtime that edits it breaks the signature, so the session is served as unverified. It is separate from the Memory URL’s provTaskId, which records where a memory came from.
The attach token
Every URL fromGET /api/mcp/config carries an attachToken, the same value for every URL on an install. It matters whenever the access gate is on, which is every install unless STUDIO_ACCESS_TOKEN= is set blank:
- A request to one of the four server paths without the access cookie is let in only when its token is valid and it came straight to the server’s loopback port: from
127.0.0.1or::1, with none of the headers a proxy adds (Forwarded,X-Forwarded-For,X-Forwarded-Host,X-Forwarded-Proto,X-Real-IP). /api/mcp/configalways needs the cookie, because it signs the identity you ask for. So doesPOST /api/mcp/attach-secret/rotate.- Treat an attach URL like a password. Anyone who has it and can reach the loopback port can use the servers as the identity it carries.
STUDIO_ACCESS_TOKEN= set blank), the bind is the only boundary: anything that can reach the server’s port can use these servers and /api/mcp/config.
/api/mcp/ without the cookie, /api/mcp/config included, and an unsigned TeamChat session takes its author and room from tool arguments. If a reverse proxy on the same machine fronts one of those releases, deny all of /api/mcp/ at the proxy. See Security.If an attach URL leaks
If an attach URL leaks
~/.clawboo/access-token:STUDIO_ACCESS_TOKEN yourself, use -b "clawboo_access=$STUDIO_ACCESS_TOKEN" instead. With the gate turned off, leave the cookie out.You should see "ok":true and a gateway value. Every URL you copied stops working at once, so get new ones from /api/mcp/config. Clawboo’s own runtimes get new URLs on their next run. gateway says what happened to a local OpenClaw Gateway’s URLs: updated means it has the new ones; retrying means it did not take them yet and Clawboo asks again over the next few minutes; not-connected means it gets them the next time Clawboo connects to it. If it still has the old ones after that, restart the Clawboo server so it connects again. A run already in progress keeps its old URLs: for the rest of that run Clawboo’s servers treat it as an unsigned caller, or refuse it while the access gate is on.Agents on another machine or in a container
HTTP attach is built for agents on the same machine as Clawboo. For an agent somewhere else:-
Another machine. Open an SSH tunnel to the Clawboo machine and keep the same port on both ends, so the attach URL works unchanged. The tunnel delivers the agent’s requests to the loopback port directly, so the attach token counts.
-
A container. On Linux, a container started with
--network hostconnects from the machine’s own loopback address, and the token counts. A container on its own network connects from another address, so it needs the access cookie on every request (for Claude Code,--header "Cookie: clawboo_access=<token>"), a server that listens beyond loopback, and the host name it uses (such ashost.docker.internal) inCLAWBOO_ALLOWED_HOSTS. -
Through your reverse proxy. The proxy’s headers make Clawboo refuse the token, so the agent needs the access cookie, and the proxy must pass
/api/mcp/. If your proxy denies that path, use an SSH tunnel instead.
The stdio bins
The four bins come with theclawboo npm package, which needs Node.js 22.12 or newer. A bin talks over its standard input and output, so it needs no running server and no access token. It opens the database named by CLAWBOO_DB_PATH, which by default is a different file from the server’s (see Data and state). The stdio snippet sets it for you:
A board write from a bin goes straight to the database, in its own process, so the server’s in-process board bus does not hear it. A task moved to Done saves its dependents’ wakes in that same write, and they go out at the server’s next pump pass, up to a minute later, rather than within seconds as they do for the HTTP Tasks server.
PATH too, so clawboo-mcp-tasks can replace the node command.
Check it works
- List the tools. In your agent, list the tools
clawboo-tasksoffers. A signed URL offers 12; an unsigned one offers 6, without the claim and status tools. - Same board. Create a task in the dashboard, then have the agent call
list_tasks. The task should appear. If it does not appear over stdio, checkCLAWBOO_DB_PATH. - Peer room. After the agent calls
team_chat_post, read the peer room withGET /api/team-chat?teamId=<team-id>. The post should be there under the agent id you signed.team_chat_subscribenever returns an agent’s own posts, and it marks teammates’ postsisUser=falseso they read as evidence, not instructions; see Peer chat.
Talk to a server with curl
Talk to a server with curl
Accept: application/json, text/event-stream on every POST, or the server answers 406. The first request must be initialize; its response carries an mcp-session-id header that every later request repeats. Replies arrive as server-sent events, on lines that start with data:.Troubleshooting
401 Clawboo access token required, on an MCP URL
401 Clawboo access token required, on an MCP URL
/api/mcp/config (sending the cookie). A URL from another install, from before a data reset, or from a version without attach tokens has no valid token. Point the agent at 127.0.0.1 directly, not through a proxy. If the agent’s environment sets HTTP_PROXY or HTTPS_PROXY, add 127.0.0.1 and localhost to its NO_PROXY.406 Not Acceptable
406 Not Acceptable
application/json and text/event-stream.Fix: send Accept: application/json, text/event-stream. MCP client libraries do this for you.400 No valid session; send an initialize request first.
400 No valid session; send an initialize request first.
initialize, or the session id is unknown. Sessions live in the server’s memory, so a server restart ends every session.Fix: send initialize again, or reconnect the client.400 Invalid or missing MCP session id.
400 Invalid or missing MCP session id.
initialize first, and send its mcp-session-id.claim_task or update_task_status is missing, or TeamChat lists no tools
claim_task or update_task_status is missing, or TeamChat lists no tools
block_task, ask_person, hand_back_task and write_plan for its own task, and report_result, which moves nothing. A one-to-one chat is the same: it gets get_task, list_tasks and add_comment, because a person’s chat has no task of its own to move. Otherwise the URL is unsigned. TeamChat also stays empty for a URL signed with a team but no agent.Fix: nothing to fix on a team run or a one-to-one chat. Otherwise get the URL from /api/mcp/config with scopeTeamId, and with scopeAgentId for TeamChat. Do not edit the ids in a signed URL.A stdio agent sees an empty board
A stdio agent sees an empty board
CLAWBOO_DB_PATH to the server’s clawboo.db, or use the stdio snippet, which sets it.400 unknown team, or agent is not on team, from the config call
400 unknown team, or agent is not on team, from the config call
scopeTeamId names no team, or scopeAgentId is a Clawboo agent that belongs to another team.Fix: copy the team’s id from GET /api/teams. For an outside agent, choose an id no Clawboo agent uses; for one of your agents, pass its own team.The config call returns ok but no config
The config call returns ok but no config
runtime is not claude-code, codex or openclaw.Fix: ask for one of those three formats and take the url from structured.403 Cross-origin request blocked.
403 Cross-origin request blocked.
host.docker.internal.Fix: add that host name to CLAWBOO_ALLOWED_HOSTS and restart the server.Under the hood
Under the hood
- Every URL starts with the server’s own loopback address and port, never the request’s
Hostheader, so a forgedHostcannot point an agent somewhere else. - Tasks, Memory and Tools URLs carry
scopeTeamId,scopeAgentIdandscopeSig. TeamChat URLs carryroomTeamId,postAuthorAgentIdandscopeSig; for its own orchestrated runs Clawboo addsdelegate=1inside the signature, which unlocksteam_delegate. Memory URLs can also carry run details (provRuntime,provTaskId,provSessionKey) signed byprovSig; they never widen what the agent can read. /api/mcp/confignever writesscopeTenantId, and adding one by hand breaks the signature. It checks the team against theteamstable and an agent id against theagentstable.- The signing secret lives in the database (
settingskeymcp-attach-scope-secret), so a data reset or a database from another install changes every token and signature, and so doesPOST /api/mcp/attach-secret/rotate. - Hermes’s gateway keeps its connection to these servers across runs, so a Hermes profile’s URLs carry only
scopeAgentIdandlive=1, signed together byscopeSig. Clawboo binds each call on such a URL, when it arrives, to the run that agent has in progress (its team, its task, the run’s id and whether the team engine drives it). A call that arrives while the agent has no run in progress, such as one from a job Hermes runs on its own between Clawboo’s runs, is bound as the agent’s own one-to-one chat is (chatRun): the agent, its own team, no task, so it can read its team’s board, comment and use the agent’s own connectors, with none of a run’s other writes. A URL whose agent Clawboo no longer has is served as an unverified caller. A tool-list request is answered for the widest run the agent could have, and a call to a tool the run in progress is not given is refused. These URLs have no MCP session: they take POST only, and a GET or DELETE answers405. - The request log masks
attachToken,scopeSigandprovSig.
Related
- MCP tools reference: every tool and its inputs.
- Tools and MCP API: the request and response shapes for these routes.
- Security: the access gate, and what to deny at a reverse proxy.
- Reach Clawboo from another machine: tunnels, wide binds, proxies and the access token.
- Data and state: the two database paths, and where the signing secret lives.
- Peer chat: how agents use the peer room that TeamChat serves.