Skip to main content
Use these routes for two related things. The tools broker routes (/api/tools*) list Clawboo’s built-in tools, show and answer the tool-approval queue, and read the tool-call audit log. The MCP routes (/api/mcp/*) carry Clawboo’s four MCP servers (tasks, memory, tools, teamchat) over Streamable HTTP, which the runtimes Clawboo starts attach to. GET /api/mcp/config builds an attach snippet for an agent you connect yourself.
The MCP routes speak the Model Context Protocol (JSON-RPC over Streamable HTTP), not a Clawboo request and response format, so they are documented by their transport rules and status codes. The tools each server offers, and their inputs, are in the MCP tools reference. To attach an outside agent step by step, see MCP servers.
Every route here is on the general rate limit (3,000 requests a minute per client address), including the approval resolve and the MCP transport; none is on the sensitive tier. Request bodies are JSON (up to 2 MB). Argument and result summaries are scrubbed when they are written; the approval queue and the audit log mask them again before they leave the server, and the /api/tools* routes mask their error messages. The /api/tools* routes, GET /api/mcp/config and POST /api/mcp/attach-secret/rotate need the access cookie (see Authentication), and the MCP transport takes the attachToken described below.

Routes


GET /api/tools

Lists every built-in tool with an availability verdict worked out from the server’s environment. A tool that needs something not set up reads available: false, with diagnostics saying why; the dashboard greys it out, and the Tools MCP server leaves it out of tools/list. The two built-in tools are echo and note, both risk safe and always available. There is no built-in web search: connect a search connector, such as Exa Search, and grant it to the agents that need it.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the tools and their availability:
500 Internal Server Error: the tool list could not be built:

Example


GET /api/tools/approvals

The pending tool-approval queue: rows whose status is pending and whose expiresAt has not passed, newest first. Each row’s argsSummary (scrubbed when it was written) is masked again here. The dashboard’s approval cards read this queue, on the board’s Needs you column and in team chat. A broker waiting on an approval, in this server or in an MCP stdio process, checks the same rows for the answer. The queue holds two kinds of row, told apart by kind:
  • tool: Clawboo itself holds the call. Its tool broker is waiting for the answer, a native agent’s run_command is waiting on the row it wrote, or a delegation is waiting for its approval.
  • exec: a shell command an OpenClaw agent asked to run. The OpenClaw Gateway holds the command; Clawboo copies the request into a row so the card survives a closed tab, a refresh, or a tab opened partway through. Such a row has toolName: 'exec', toolClass: 'destructive', and the command’s first 200 characters as toolSummary.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the pending approvals, each the whole stored row:
500 Internal Server Error:

Example


POST /api/tools/approvals/:id/resolve

Answers an approval. An unknown decision is a 400. The route then loads the row and acts on its kind, because the two kinds are held by different things and released in different ways. The 404 means only that no row with that id exists; an approval that was already answered is not a 404. A kind: 'tool' row is answered here. The answer is written only while the row is still pending and its expiresAt has not passed. A row someone already answered comes back unchanged with 200, so check status in the response. A row that has expired, or is still pending past its expiresAt, is refused with 409, and a pending one is marked expired then. A waiting broker sees the answer the next time it checks. For a tool row, allow_always also creates a standing allow rule tied to the row’s grant: later calls of the same tool under that grant run without asking, whatever their arguments, for 30 days. That covers a call with an external effect too. A call to a destructive tool is stored with neverRemember: 1 and asks every time, even when a rule exists. No rule is made when the row has no grantId, when it has neverRemember: 1, or when this call did not change the row (it was already answered). A kind: 'exec' row is held by the OpenClaw Gateway, and answering Clawboo’s copy alone would not release the command. So the answer goes to the Gateway as exec.approval.resolve, in OpenClaw’s own words (allow_once becomes allow-once, allow_always becomes allow-always, deny stays deny), and Clawboo marks its copy only after the Gateway takes it. This branch answers a different 200 body and is the only one that can answer 502.
Clawboo makes no rule of its own for an exec row. An allow_always is passed on as allow-always, and any standing permission it creates lives in OpenClaw’s own allowlist, which you can read and revoke through /api/exec-allowlist (see the Agent settings API).
  • Path params: id (approval id).
  • Request body:

Responses

400 Bad Request: decision is missing or not one of the three values. details is the validation error:
403 Forbidden: { "ok": false, "error": "person_only" }: an answer is a person’s, and the request did not pass the person check. The approval is left as it was. A script answering for you sends Sec-Fetch-Site: same-origin and Sec-Fetch-Mode: cors; this is a speed bump on your own computer, not a boundary. 403 Forbidden: { "error": "allow_always_from_app", "message": "An answer from the app that started Clawboo can allow once or deny." }: an allow_always from one of the people an app that started Clawboo names. The approval is left as it was, on either kind of row. 404 Not Found: no approval with that id exists:
200 OK (kind: 'tool'): the whole row after the answer, with the same fields as the queue. argsSummary is the stored, scrubbed value; this route does not mask it again:
409 Conflict (kind: 'tool'): the card’s time ran out, so the answer was not recorded. approval is the row, with status: 'expired':
200 OK (kind: 'exec'): the Gateway took the answer. There is no approval object here:
alreadyResolved: true means the Gateway reports the command as already answered. That is a normal race, not a failure: the same card can be open in several browser tabs, each with its own Gateway connection. Clawboo then leaves its copy as it is and settles it from the Gateway’s exec.approval.resolved broadcast, which is also how a card answered elsewhere clears from a tab. 502 Bad Gateway (kind: 'exec' only): the Gateway did not take the answer, so the command is still waiting and the card stays open:
500 Internal Server Error:

Example


GET /api/tools/audit

The tool-call audit log: one row before and one after each brokered call, newest first. argsSummary and resultSummary are masked again before they are returned.
  • Query params:
  • Request body: none.

Responses

200 OK: the audit rows:
500 Internal Server Error:

Example


MCP transport: /api/mcp/{tasks,memory,tools,teamchat}

Twelve routes, POST, GET and DELETE on each of /api/mcp/tasks, /api/mcp/memory, /api/mcp/tools and /api/mcp/teamchat, carry Clawboo’s four MCP servers over Streamable HTTP. The servers run inside the Clawboo server. Each connection is a stateful session named by the mcp-session-id header. Headers a client sends:
  • Every POST: Content-Type: application/json and Accept: application/json, text/event-stream.
  • A GET: Accept: text/event-stream.
  • After initialize: the mcp-session-id it returned, and optionally mcp-protocol-version.
Each session gets its own server instance, made at initialize and dropped when the session closes. The servers bind the session to a caller when it starts (see the binding sections below). Sessions live in memory, so a restart of the Clawboo server ends them all and clients must send initialize again. Errors from the transport are JSON-RPC error bodies, { "jsonrpc": "2.0", "error": { "code": -32000, "message": "<message>" }, "id": null }, except where the table says otherwise:

Access: the attachToken

With the access gate on (every install, unless STUDIO_ACCESS_TOKEN is set blank), a request to one of the twelve transport routes needs either the access cookie or an attachToken query parameter. The token is an HMAC-SHA256 the server derives from a per-install secret, and it is the same on every attach URL of an install. Clawboo writes it into every attach URL it builds: for the runtimes it starts, and in the GET /api/mcp/config snippet. It is checked on every request (initialize and the session’s later POST, GET and DELETE alike), which is why it rides in the URL. The token counts only on a request that reached the loopback port directly. It is refused from another machine, and on any request that carries a proxy header (Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto or X-Real-IP). It opens these twelve routes only: GET /api/mcp/config always needs the cookie while the gate is on, because it signs attach URLs. With the gate off, neither is needed. The server log masks attachToken, scopeSig and provSig values. Without either credential the gate answers 401:
Clawboo 0.5.0 and older do not have this rule: on those releases any loopback request reaches every /api/mcp/* route, /api/mcp/config included, without the cookie. See Security.

Session binding: who is calling

Every server reads who is calling from the attach URL when the session starts, at initialize. A binding counts only when its scopeSig signature verifies. Clawboo signs the URLs it writes for the runtimes it starts, and GET /api/mcp/config signs the ones it builds for you. A parameter added or edited by hand, without a matching signature, is ignored, so neither the model nor the runtime can widen what a session sees by changing tool arguments or its own config. The provenance stamps have their own signature, provSig. They are dropped when it does not verify, and they never widen what a session can see. delegate=1 is covered by scopeSig, so it cannot be added to a signed URL.

What an unverified caller gets

An HTTP session with no binding, or with a signature that does not verify, is an unverified caller: OpenClaw agents are always unverified callers. The Gateway’s MCP config is one entry for the whole Gateway, so it cannot carry a per-agent binding. Clawboo registers tasks, memory and tools for OpenClaw with no binding, and never registers teamchat. The URL carries the attachToken only when the Gateway runs on this machine; a Gateway on another machine gets the bare URL. The stdio servers (the MCP bins) are different: there you, the operator, run the server, so scope comes from the tool arguments.

What each server offers

Tasks serves board tools (12, including list_tasks, create_task, claim_task and add_comment), Memory serves memory_save, memory_search, memory_browse and memory_feedback, Tools serves the available built-in tools, the connector tools the caller’s grants allow, and read_tool_result for a result too large to return at once, and TeamChat serves team_chat_post, team_chat_subscribe and, on a delegate=1 session, team_delegate. The full list, with each tool’s inputs, is in the MCP tools reference. The GET stream carries MCP notifications and streamed results, not Clawboo-shaped events.

Example (a raw initialize)

Without a binding this session is an unverified caller, so its tools/list leaves out the claim and status tools. In practice an MCP client library, or the runtime’s own MCP support, speaks the protocol for you; get its attach snippet from GET /api/mcp/config.

GET /api/mcp/config

Builds a copy-and-paste attach snippet for one runtime and one MCP server. The HTTP address uses the port this server is bound to (http://127.0.0.1:<port>), never the request’s Host header, so a forged Host cannot send a runtime’s MCP traffic elsewhere. If that port is unknown, it falls back to CLAWBOO_API_PORT, else 18790. Every http URL it returns carries the attachToken. Send scopeTeamId or scopeAgentId and the URL also carries those parameters with a matching scopeSig, so the binding counts. Because the route signs the identity you ask for, it always needs the access cookie while the gate is on; the attachToken does not open it.
  • Query params:
scopeTeamId must name a team in the teams table, archived or not. A scopeAgentId that is a Clawboo agent must be on that team; an id no Clawboo agent uses is signed as given, for an outside agent’s own identity. runtime and transport are not checked: an unknown runtime answers 200 with { "ok": true } and no config.
Binding scopeAgentId to an existing agent makes your outside agent act as that agent: it uses that agent’s grants, and the Tasks server delivers that agent’s inbox messages to it, so the real agent no longer receives them. Use scopeAgentId only with an agent id that nothing else runs as.
  • Request body: none.

Responses

400 Bad Request: server is not one of the four servers, scopeTeamId names no team, or scopeAgentId is a Clawboo agent on another team:
200 OK: the attach config:
What snippet holds: An http URL looks like http://127.0.0.1:18790/api/mcp/tasks?attachToken=<64 hex characters>, with the scope parameters before the token when you ask for them. A stdio snippet runs node <CLAWBOO_MCP_BIN_DIR>/<server>.js (a <path-to>/dist/bin/<server>.js placeholder when CLAWBOO_MCP_BIN_DIR is not set) and sets CLAWBOO_DB_PATH to this server’s database, because the stdio bins otherwise open a different default database (see Data and state). 500 Internal Server Error:

Example


POST /api/mcp/attach-secret/rotate

Replaces the per-install secret that every attachToken, scopeSig and provSig is derived from. Every attach URL minted before stops verifying at once, in every Clawboo process that uses this database: the ones you copied, the ones a local OpenClaw Gateway holds, and those of runs already in progress. Clawboo’s own runtimes get new URLs on their next run. When this server is connected to an OpenClaw Gateway, it re-registers the Gateway’s URLs and waits up to 5 seconds for the write before it answers. Use it when an attach URL leaks, then copy new URLs from GET /api/mcp/config. Like GET /api/mcp/config, it always needs the access cookie while the gate is on; the attachToken does not open it.
  • Request body: none.

Responses

200 OK: the secret is replaced. gateway says what became of the OpenClaw Gateway’s registered URLs:
500 Internal Server Error: the new secret could not be stored:

Example


Error envelope

The /api/tools* routes, GET /api/mcp/config and POST /api/mcp/attach-secret/rotate use the standard { "error": string } body; on the /api/tools* routes the message is masked. The resolve route’s validation 400 adds details. The MCP transport answers with the JSON-RPC error bodies in its table, except for the gate’s 401 and a 500, which use the standard body. A rate-limited request answers 429 { "error": "Too many requests. Wait a moment and retry." } with a Retry-After header. Source of truth: apps/web/server/api/tools.ts and mcp.ts; the servers in packages/mcp/src/ (http.ts, config.ts, tasks/, memory/, tools/, teamchat/); the gate in packages/gateway-proxy/src/access-gate.ts; approvals in packages/db/src/tools/persistence.ts.
  • MCP tools reference: every tool the four servers offer, and its inputs.
  • MCP servers: attach an outside agent, transports and scoping in practice.
  • Security: the access gate, the attach token and reverse proxies.
  • Approvals: answering approval cards in the dashboard.
  • Runtimes API: a task run attaches to these servers.
  • REST API overview: authentication, rate limits and conventions.
Last modified on November 16, 2026