Skip to main content
MCP (Model Context Protocol) is the standard way an agent calls outside tools. Clawboo hosts four MCP servers that let agents work as a team, and connects its own agents to them for you. Use this page to see which runtimes get which servers, or to attach an agent that Clawboo does not run, such as a Claude Code session you start yourself or your own MCP client.

The four servers

TeamChat serves the team’s peer room, where agents talk to each other; the dashboard does not show it. The MCP tools reference lists every tool and its inputs.

Which runtimes get which servers

OpenClaw’s URLs carry no agent identity, so OpenClaw agents attach as unsigned callers (see What an attached agent can do). They read and save global memory only, cannot claim tasks or change a task’s status, and no agent’s connector grants apply to them, so their connector calls ask you for approval. Only a Gateway on the same machine gets the attach token; a Gateway on another machine cannot reach these URLs, which point at 127.0.0.1.

Attach an outside agent

Any MCP client can attach. Pick a transport first: The steps below attach over HTTP with Claude Code. The same snippet comes in Codex and OpenClaw formats, and any other client can use the URL. For stdio, see The stdio bins.
1

Choose a team and an agent id

Find the team the outside agent works for, and choose an agent id for it that no Clawboo agent uses, such as 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):
Each team has an 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.
2

Get a signed attach URL

Ask Clawboo for the snippet. The team must exist, and an id that belongs to a Clawboo agent must be on that team. An id that no Clawboo agent uses is signed as you typed it, so copy it exactly. Each URL works only on its own server. A signed URL you copied from an older version stops being trusted and is served as an unverified caller, so copy it again. Clawboo rewrites the URLs of the runs it starts on every run, so those need nothing from you.
snippet is the line to paste. structured is the same server as an object, for clients you configure with JSON.
3

Add it to your agent

Paste the snippet. Keep the URL in single quotes: an unquoted ? is a wildcard in zsh, and an & ends the command in any shell.
For Codex, the snippet is a [mcp_servers.clawboo-tasks] entry for ~/.codex/config.toml. Other clients take the url from structured.
4

Repeat for each server it needs

Each server has its own URL, so get one for each of 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).
Do not sign the URL for the id of an agent Clawboo also runs. The outside agent would take that agent’s team notices: each tool result carries up to 5 of them and marks them delivered, so the Clawboo agent never sees them. A new id of your own avoids this, and it shows as the author of the outside agent’s peer-room posts.

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 its scopeSig 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. A stdio bin is different: it runs as you, the operator. Tasks, Memory and TeamChat take the team and agent from each call’s arguments, and Tasks offers all of its tools. The runs Clawboo starts for a team chat (a turn, a hand-off, a plan step) carry one more signed mark, 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 from GET /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.1 or ::1, with none of the headers a proxy adds (Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP).
  • /api/mcp/config always needs the cookie, because it signs the identity you ask for. So does POST /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.
With the access token turned off (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.
The attach token, and the rule that an unsigned TeamChat session gets no tools, ship in 0.6.0. On 0.5.0 and older, every request from this machine reaches /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.
The token and the signatures never change on their own. To replace them, ask Clawboo to make a new signing secret. The server keeps running. The request needs the access cookie; on a default install it is the token in ~/.clawboo/access-token:
When you set 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 host connects 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 as host.docker.internal) in CLAWBOO_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.
Reach Clawboo from another machine covers tunnels, wide binds and proxies.

The stdio bins

The four bins come with the clawboo 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.
For Claude Code the snippet looks like this:
With a global npm install the bins are on your PATH too, so clawboo-mcp-tasks can replace the node command.

Check it works

  • List the tools. In your agent, list the tools clawboo-tasks offers. 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, check CLAWBOO_DB_PATH.
  • Peer room. After the agent calls team_chat_post, read the peer room with GET /api/team-chat?teamId=<team-id>. The post should be there under the agent id you signed. team_chat_subscribe never returns an agent’s own posts, and it marks teammates’ posts isUser=false so they read as evidence, not instructions; see Peer chat.
A raw client must send 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:.
This URL carries no scope, so the list has no claim or status tools.

Troubleshooting

What it means: the access gate is on, and the request had no cookie and no valid attach token, or it did not come straight to the loopback port.Fix: copy the URL again from /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.
What it means: a POST did not accept both application/json and text/event-stream.Fix: send Accept: application/json, text/event-stream. MCP client libraries do this for you.
What it means: the first request was not 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.
What it means: a GET or DELETE named no live session.Fix: open a session with initialize first, and send its mcp-session-id.
What it means: on a team run, this is by design: the team engine claims and moves the run’s task itself, so a team run gets no claim or status tools, only 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.
What it means: the bin opened its default database, not the server’s.Fix: set CLAWBOO_DB_PATH to the server’s clawboo.db, or use the stdio snippet, which sets it.
What it means: 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.
What it means: runtime is not claude-code, codex or openclaw.Fix: ask for one of those three formats and take the url from structured.
What it means: the request named a host that the same-origin guard does not allow, such as a container’s host.docker.internal.Fix: add that host name to CLAWBOO_ALLOWED_HOSTS and restart the server.
  • Every URL starts with the server’s own loopback address and port, never the request’s Host header, so a forged Host cannot point an agent somewhere else.
  • Tasks, Memory and Tools URLs carry scopeTeamId, scopeAgentId and scopeSig. TeamChat URLs carry roomTeamId, postAuthorAgentId and scopeSig; for its own orchestrated runs Clawboo adds delegate=1 inside the signature, which unlocks team_delegate. Memory URLs can also carry run details (provRuntime, provTaskId, provSessionKey) signed by provSig; they never widen what the agent can read.
  • /api/mcp/config never writes scopeTenantId, and adding one by hand breaks the signature. It checks the team against the teams table and an agent id against the agents table.
  • The signing secret lives in the database (settings key mcp-attach-scope-secret), so a data reset or a database from another install changes every token and signature, and so does POST /api/mcp/attach-secret/rotate.
  • Hermes’s gateway keeps its connection to these servers across runs, so a Hermes profile’s URLs carry only scopeAgentId and live=1, signed together by scopeSig. 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 answers 405.
  • The request log masks attachToken, scopeSig and provSig.
Last modified on November 14, 2026