@clawboo/mcp has two halves. The server half gives agents Clawboo’s board, memory, tools and peer channel as four
MCP servers. The client half is how Clawboo itself connects to the third-party MCP servers you add as connectors.
Between them sits attach signing, which stops an agent from claiming an identity Clawboo did not give it.
Use this page when you add or change an MCP tool, change how runtimes attach, or work on connectors. Each tool’s
inputs are listed on MCP tools, and attaching an outside agent is covered in
MCP servers. This is the only package that depends on @modelcontextprotocol/sdk, which
is why the connector client lives here too.
The four servers
Each server is a thin layer over
@clawboo/db: the handlers call its repository functions. A few behaviors matter
to anyone changing them:
- Tasks.
readOnlyserves onlylist_tasksandget_task, plusask_personandreport_resulton a team run bound to a task andwrite_planon a run bound to a task; Clawboo Native uses it for an agent whose Tasks access is set to read.ask_person,report_resultandhand_back_taskact only on the bound task of a team run, and are not served without one.report_resultwrites no status: it stores a claim on the run’s execution, fordecideDone.block_task, andupdate_task_statusandcreate_taskintoblockedorin_review, need awaitingOnreason.teamRunis set for a run the team engine drives (signedteamRun=1on its Tasks, Memory and Tools URLs; Clawboo Native sets it in-process): it leaves outclaim_task,assign_task,release_task,update_task_statusandunblock_task, and letsblock_taskblock only the bound agent’s own task. A bound agent’sclaim_taskclaims for that agent. A bound team scope forceslist_tasksto that team and makesget_taskrefuse another team’s task. A bound task (boundScope.taskId, from the signedscopeTaskIdof a run on a board task;boundTaskIdonAttachScope) is whatget_task,add_commentandblock_taskuse when a call leaves outtaskId. Cancelling a task withupdate_task_statuscancels the plan steps waiting on it and leaves its delegator a mailbox note. A lost claim, a dependency cycle inlink_taskand a refused subtask (too many children, too deep) come back as tool errors the model should not retry. Every argument naming a task takes its readable id too, resolved in one wrapper (acceptReadableIds) and only within a bound team.create_taskandcreate_subtasksend an idempotency key, the caller’s (kept to the bound task, else the agent, else the team, and to the parent and title) or one derived from the bound task, the parent and the title. With no bound task it derives from the team and matches only an open task. They mark the create as an agent’s, so the same-title check applies; a repeat returns the existing task withdeduplicated: true.prioritystops at High (clampAgentTaskPriority).assign_taskrefuses a hand-off back up the chain unless the target is a lead, which the host names withisLeadAgent; the default is the team’s own lead. - Tools. Every call runs through the
@clawboo/dbbroker, so a connector tool is checked against the agent’s grants. A connector tool is listed only to an agent whose grant would allow it. - TeamChat.
team_delegateonly signals: the team engine sees the tool call and creates the board task. - A comment starts nothing by itself.
add_commenton a session bound to an agent labels the commentagent, and no other caller labels it at all. Only the board route’spersoncomment starts a run at once. Anagentcomment saves a wake unless a person said no for the job (commentMayWakein@clawboo/board-core), and the server’s wake pump decides whether it starts, which can mean asking a person first. A move to Done saves its dependents’ wakes in the write itself, so a stdio bin’s does too; they wait for the server’s next pump pass. - Mailbox delivery. For a bound agent, its undelivered mailbox rows ride along on the next Tasks or TeamChat
tool response as a second content block, each framed as data with
formatInterSessionMessage(from@clawboo/board-core, whichformatPeerPostis now built on).
Transports
- HTTP.
createStreamableHttpHandlersserves each server inside the dashboard server at/api/mcp/<server>. Clawboo’s own Claude Code, Codex and Hermes runs and the OpenClaw Gateway connect here.createStatelessHttpHandlerserves the same servers with no MCP session (POST only; GET and DELETE answer405), building a server per request. The dashboard server uses it for a live URL (live=1, seeAttachScope.live), which names only an agent and is bound per call to that agent’s run in progress: the URL each Hermes profile keeps, since the Hermes gateway holds its connection across runs. - In-process.
connectInMemoryClientconnects Clawboo Native’s MCP bridge to the servers without a network hop.probeServerchecks that a server answers, for the boot probe and the MCP supervisor. - stdio.
runStdioServerbacks the four binsclawboo-mcp-tasks,clawboo-mcp-memory,clawboo-mcp-toolsandclawboo-mcp-teamchat, for runtimes you attach yourself.
packages/mcp/src/bin/*.ts by apps/web/tsup.mcp-bins.config.ts, with every @clawboo/*
package inlined, and scripts/assemble-cli.sh copies them into the published clawboo package. Each bin opens
createDb(defaultDbPath()): the file named by CLAWBOO_DB_PATH, else ~/.openclaw/clawboo/clawboo.db. That is a
different file from the server’s ~/.clawboo/clawboo.db, on purpose, so set CLAWBOO_DB_PATH to the server’s
file or use the snippet from GET /api/mcp/config, which embeds it. The Memory bin re-resolves its embedding
provider once a minute and falls back to keyword search when there is none.
Attach URLs and signing
mcpHttpUrl(baseUrl, server, scope) writes the URL a runtime attaches with, and buildAttachConfig wraps it in a
runtime’s own config shape (a claude mcp add line, a Codex config.toml entry, an openclaw.json entry). A URL
Clawboo mints with the install’s attach secret carries up to three signatures. An unscoped URL, such as the one
registered with a local OpenClaw Gateway, carries the token alone.
attachToken, on every such URL: proof that the request comes from a runtime this server started. The access gate admits a request without the dashboard cookie only when it carries a valid token, targets one of the four server mounts, arrives on the loopback port directly and was not forwarded by a proxy.GET /api/mcp/configmints signed URLs, so it always needs the cookie when the gate is on.scopeSig, when the URL claims a team, agent or tenant: an HMAC over those, the delegation privilege and the server the URL is for, so a signature for one server opens no other.provSig, on Memory URLs that carry provenance stamps (runtime, task, session): it signs the stamps recorded with saves and feedback.
signAttachAccess, signAttachScope and signAttachProvenance mint these from the per-install secret, and their
verify partners check them in constant time. The secret never leaves the server.
Unverified callers
A scope whose signature is missing or wrong counts as no scope at all. Over HTTP that makes the caller unverified, and each server narrows what it serves:
A stdio caller with no scope is the operator running a bin and is served without these limits. OpenClaw agents are
always unverified: the Gateway registers Memory, Tasks and Tools once for all its agents, with no per-run
identity, and gets no TeamChat server. The server-side flags are
unverifiedCaller on the Tasks, Memory and
TeamChat options.
The connector client
When you connect a connector, Clawboo is the MCP client. The server’s connector supervisor and OAuth flow (apps/web/server/lib/connectors/) call into this half; the connector definitions themselves come from
@clawboo/connector-catalog.
- Sessions.
connectStdioConnector(spec)spawns a local server andconnectHttpConnector(spec)dials a remote one. Both return aConnectorSessionthat lists tools and calls them, and both throwConnectorHandshakeErrorwhen the server never completes the MCP handshake. - Time budgets. The handshake, each tool-list page and each tool call have separate timeouts
(
DEFAULT_HANDSHAKE_TIMEOUT_MS,DEFAULT_LIST_TIMEOUT_MS,DEFAULT_CALL_TIMEOUT_MS). The handshake budget is the generous one, because a coldnpxinstall happens inside it. Discovery stops atMAX_CONNECTOR_TOOLStools. - Results.
flattenContentturns an MCP result into text for the model, and images ride along separately. - Environment.
connectorChildEnvbuilds a stdio connector’s environment from an empty set, the few variables a process needs to start, the proxy settings, npm’s prefix, cache and update check in either spelling and Python’sPYTHONDONTWRITEBYTECODEandPYTHONPYCACHEPREFIX(CONNECTOR_ENV_ALLOWLIST), and the credentials you gave that connector, so it never inherits your provider keys or npm credentials. It setsnpm_config_update_notifier=falseunless that is already set; passnpmUpdateCheck: 'inherit'to leave it as the operator configured it, as approved shell commands do. From 0.9.0, given the connector’scommand, it also setsPYTHONDONTWRITEBYTECODE=1unless either Python setting is already set, for a connector started through npm only (launchesThroughNpm: the command’s file name isnpx,npmornode, plusnpx.cmd,npm.cmdandnode.exeon Windows), so a native build thatnpxruns writes no__pycache__into npm’s own folder. Any other command, such asuvx, gets no Python setting added. With nocommandit sets it too. PasspythonBytecode: 'inherit'to add nothing, as approved shell commands do. This closes the environment only. It is not a sandbox: the connector still runs as your user and can read your files.
1
Discover
An unauthenticated request returns
401 with a WWW-Authenticate header. resourceMetadataUrl reads it,
discoverResourceMetadata fetches the protected-resource metadata (RFC 9728), and discoverAuthServer fetches the
authorization server’s metadata (RFC 8414).2
Register
registerClient registers this install as a client through dynamic client registration (RFC 7591), with the
loopback redirect it is about to listen on. Clawboo ships no client secret, so an authorization server without a
registration endpoint cannot be used; the catalog marks such providers with needsPreregisteredApp.3
Authorize and exchange
createPkce makes an S256 challenge, buildAuthorizeUrl builds the sign-in URL, and exchangeCode and
refreshToken talk to the token endpoint.https unless it is on this machine, and a host that resolves to a private or link-local
address is refused, so a connector cannot point Clawboo at your local network. isLoopbackUrl lets the flow tell
an authorization server you run yourself from one a remote server named.
Add or change a tool
1
Add the tool definition
Each server builds its tools as plain definitions (
name, description, a zod inputSchema, a handler) and
passes them to buildServer in src/shared.ts. buildServer validates arguments with zod and converts the schema
to JSON Schema itself. The servers use the SDK’s low-level Server API, because the high-level per-tool type
inference exhausts the TypeScript compiler’s memory once a server has about a dozen tools.2
Keep data access in the database package
Put the query or write in a
@clawboo/db repository function and call it from the handler, so the REST routes
and the other servers can reuse it.3
Decide who may call it
If an argument names an agent, a team or a room, take it from the bound scope instead of trusting the model, and
decide what an unverified caller gets. Tasks lists its identity tools in
IDENTITY_TOOL_NAMES for this reason.
Return a refusal the model must not retry as an error result (textResult(message, true)).4
Test and document it
Run
pnpm --filter @clawboo/mcp test; the suite includes the shared server contract and the unverified-caller
cases. Then add the tool to MCP tools. You should see it in a client’s tools/list, for
example from the stdio bin with CLAWBOO_DB_PATH set.Related
- MCP tools: every tool’s inputs, outputs and limits.
- MCP servers: attach an outside agent, and the attach token in practice.
- @clawboo/db: the repositories behind every handler.
- Add a connector: the definitions the connector client launches.
- @clawboo/gateway-client: the access gate that checks the attach token.