Skip to main content
Use this page when you want an external agent to act as a teammate inside Clawboo: read and claim board tasks, search shared memory, call brokered tools, and post in a team room. Clawboo hosts four MCP servers, tasks, memory, tools, and teamchat, and the agent attaches them as MCP clients. The agent does not need to be a Clawboo runtime; anything that speaks MCP can attach. There are two transports for the same four servers:
  • stdio: Clawboo ships four standalone bins (clawboo-mcp-tasks, clawboo-mcp-memory, clawboo-mcp-tools, clawboo-mcp-teamchat). The consuming agent spawns one as a child process and talks JSON-RPC over stdin/stdout. Best for an agent on the same machine that owns its own process lifecycle.
  • Streamable HTTP: the running Clawboo server exposes the same four servers in-process at /api/mcp/{tasks,memory,tools,teamchat}. The agent connects over HTTP. Best when the agent is a separate process (or container) that talks to a long-running Clawboo.
Both transports read and write the same SQLite database, which is the shared-services bus. A stdio bin spawned by an external agent and the in-process HTTP server operate on one board, one memory store, one tool-call audit.

​
Prerequisites

Node 22+ is required to run the stdio bins (they are node scripts). For HTTP, a running Clawboo server is required (clawboo; see Installation).
  • The four stdio bins ship in the clawboo npm package (bin entries), so a clean Clawboo install has them. For HTTP, nothing extra is needed beyond a running server.
  • The external agent must already speak MCP (initialize → tools/list → tools/call). The tool surface per server is in MCP tools reference.

​
At a glance

Each HTTP path accepts POST (the JSON-RPC request body), GET (the SSE event stream for a session), and DELETE (session teardown). The session is keyed by the mcp-session-id header; the first request must be an initialize, which mints the session id returned on subsequent calls.

​
Steps

Rather than hand-write config, ask Clawboo to emit it. GET /api/mcp/config builds a copy-pasteable attach block for a given runtime, server, and transport:
snippet is the human copy-paste line; structured is the same attachment as an object (for programmatic config, e.g. Claude Code’s inline mcpServers). The query params:
The snippet builder formats config for claude-code, codex, and openclaw only. To attach from hermes, clawboo-native, or any other MCP-speaking agent, use the HTTP URL (<base>/api/mcp/<server>) or the node <bin> invocation directly; the structure is the same; only the per-runtime wrapper differs.
For transport=http, the base URL in the snippet is the server’s own bound port, resolved from app.locals.apiPort, never from the request’s Host header. A forged Host cannot redirect an agent’s MCP traffic to another server. For transport=stdio, the snippet uses the path under CLAWBOO_MCP_BIN_DIR if the server was started with that env var (the CLI sets it for the bundled bins); otherwise it emits a <path-to>/dist/bin/<server>.js placeholder.

​
2a. Attach over HTTP

Point the agent’s MCP client at <clawboo-base>/api/mcp/<server>. For Claude Code:
The agent then runs initialize (which mints an mcp-session-id), tools/list, and tools/call against that URL. The session is stateful: subsequent POSTs and the GET event stream reuse the same mcp-session-id.

​
2b. Attach over stdio

The agent spawns the bin and talks JSON-RPC over stdio. For Claude Code:
Set CLAWBOO_DB_PATH on a stdio attach so the bin opens the same database the server serves. The bins default to ~/.openclaw/clawboo/clawboo.db, but the running server uses ~/.clawboo/clawboo.db (under resolveClawbooDir()). Without the override, a stdio-attached agent would talk to a different, empty board. The GET /api/mcp/config?transport=stdio snippet embeds this for you (-e CLAWBOO_DB_PATH=... for Claude Code, an env table for Codex, an env object for OpenClaw).

​
3. Scope the Memory server (the visibility binding)

The memory server is the shared tier every runtime reads and writes. When attached for a specific run, bind its visibility scope so the agent can neither read another team’s facts nor mis-tag a save. The scope rides the attach URL as query params:
When the scope params are present, the MCP session is bound at initialize and stays bound for that session. Absent params mean unbound (legacy behavior, identity comes from tool args). The tasks URL carries scopeTeamId and scopeAgentId too: the team binding forces list_tasks to that team and makes get_task refuse another team’s ids, and the agent binding is what lets undelivered mailbox rows ride the tool response. Only the tools URL stays bare.

​
4. Bind the TeamChat author (the anti-spoof binding)

The teamchat server lets an agent post into a team room. To stop an agent from posting as a teammate it is not, the author identity is bound from the attach URL, written by Clawboo, not passed in tool args:
Because the URL is Clawboo-written config and the binding is read server-side at session init, a team_chat_post tool call cannot override the author. When both params are present the session is bound; otherwise the attachment is unbound (the raw stdio bin / external attach passes identity in tool args). Both params are required for binding; supplying only one leaves it unbound.

​
Options / variations

​
The access gate and loopback

Clawboo’s access gate is the only auth on a non-loopback bind. It blocks /api/* without a valid cookie when a STUDIO_ACCESS_TOKEN is set. The gate has one exemption for the MCP control plane:
  • A request to /api/mcp/* from a loopback peer (127.0.0.1, ::1, or ::ffff:127.0.0.1) is let through without a cookie. This is what lets a runtime Clawboo spawned on the same machine attach its MCP client; its environment is scrubbed of the token by design.
  • The prefix test is case-folded: the gate lower-cases the pathname before matching, so an uppercased /API/mcp/ (or /API/settings) cannot evade the gate.
  • A non-loopback /api/mcp/* request still requires the cookie; the exemption is loopback-only, and a remote client cannot forge a loopback source on a real TCP handshake.
The loopback exemption is keyed on the TCP peer address, not on a header. If you expose Clawboo to a network (a non-loopback bind), set STUDIO_ACCESS_TOKEN and attach over HTTP with the access cookie (or keep the attaching agent on loopback). See Security and self-host securely.

​
Verify it worked

  • List tools: over HTTP, send initialize then tools/list to /api/mcp/tasks; you should see list_tasks, claim_task, and the other task tools. Over stdio, the same handshake on the spawned clawboo-mcp-tasks bin returns the same list.
  • Same board: create a task in the Clawboo UI, then call list_tasks from the attached agent. The new task should appear. If it does not, the stdio bin is on the wrong DB path; re-check CLAWBOO_DB_PATH.
  • Scoped memory: with scopeTeamId bound, memory_search should only return that team’s facts (plus global). A save lands under the bound scope.

​
Troubleshooting

stdio agent sees an empty board. The bin defaulted to ~/.openclaw/clawboo/clawboo.db while the server uses ~/.clawboo/clawboo.db. Set CLAWBOO_DB_PATH to the server’s DB path on the attach (the transport=stdio config snippet embeds it).
401 attaching over HTTP. A STUDIO_ACCESS_TOKEN is set and the request is non-loopback (or the cookie is missing). Either attach from loopback (the /api/mcp/* exemption applies) or send the access cookie. An uppercased path will not bypass the gate; it is case-folded.
400 { "error": "unknown server: <x>" } from /api/mcp/config. The server query param must be exactly one of tasks, memory, tools, teamchat. Likewise an attach POST without a prior initialize returns a JSON-RPC error (“No valid session; send an initialize request first”).
Last modified on August 21, 2026