clawborrator-mcp (channel_v1)

MCP server that connects each running Claude Code instance to a clawborrator hub over WebSocket. Designed to be invoked by Claude Code via .mcp.json; runs as both a long-lived stdio MCP server AND a short-lived hook spawn (selected by the --hook=<HookName> CLI flag).

Published as clawborrator-mcp on npm.

Status: production hub at next.clawborrator.com. Local dev uses ws://localhost:8787. Both supported.

Configuration

Set in your project's .mcp.json:

{
  "mcpServers": {
    "clawborrator": {
      "command": "npx",
      "args": ["-y", "clawborrator-mcp"],
      "env": {
        "CLAWBORRATOR_HUB_URL": "wss://next.clawborrator.com",
        "CLAWBORRATOR_TOKEN":   "ck_live_…"
      }
    }
  }
}

Get the snippet pre-filled with the right URL + token via the clawborrator-cli:

npx clawborrator-cli token mint --kind=channel --name=mbp --mcp-snippet --out .mcp.json

If you're running the desktop daemon (clawborrator-supervisor), it mints channel tokens server-side when it spawns managed Claude Code sessions for you — the .mcp.json ends up in the spawned project automatically.

Install as a Claude Code plugin

clawborrator is an official external Claude Code plugin. This repo ships .claude-plugin/plugin.json and a root .mcp.json, so once it is listed in a plugin marketplace it installs with:

/plugin install clawborrator@<marketplace>

The bundled .mcp.json resolves its config from environment variables instead of a committed token, so it carries no secret. You still have to supply the channel token yourself — a committed plugin cannot ship a per-user secret. Before the MCP server can connect to the hub, set in your environment:

Without CLAWBORRATOR_TOKEN set, the server starts but cannot authenticate, and the session never registers with the hub. This is the one manual step the plugin install cannot do for you.

What it does

Long-lived MCP path (default invocation):

1. Reads env config; loads channel token.

2. Opens WSS to <HUB_URL>/channel with Authorization: Bearer <CHANNEL_TOKEN>.

3. Sends register with host / cwd / pid / version; receives welcome with sessionId + routingName.

4. Writes <cwd>/.claude/clawborrator/runtime.json (mode 0600) so per-event hook spawns can find the active session.

5. Maintains the WS with heartbeat ping/pong; reconnects with exponential backoff (1s/2s/5s/15s/30s/60s).

6. Listens for hub-side messages: prompt (cross-session route), permission_response, peers_update, bye, error.

7. Dispatches MCP tool calls (see below) over the same WS.

8. On clean shutdown (SIGINT/SIGTERM/exit), deletes the sidecar.

Short-lived hook path (--hook=<HookName> flag):

1. Reads JSON payload from stdin (Claude Code's hook protocol).

2. Locates the active sidecar at .claude/clawborrator/runtime.json.

3. Maps the hook name to a clawborrator event (e.g. PreToolUse → tail/PreToolUse, UserPromptSubmit → chat/prompt).

4. POSTs to <HUB_URL>/api/channel/event with the channel token from the sidecar.

5. Echoes stdin to stdout so Claude's hook chain stays intact.

6. Exits cleanly even if the hub is unreachable — never breaks the operator's actual Claude flow.

Hooks are auto-installed on first MCP startup: clawborrator-mcp reconciles .claude/settings.json to add (or refresh) the entries that point at dist-hook/clawborrator-tail.mjs. No separate install step.

MCP tools exposed to Claude

Routed: targets a peer (your own session or another operator's session you have a share on) by routingName.

Cross-tenant — public agents owned by other operators:

File exchange:

The hub correlates reply / reply_chunk to their originating route_to_peer / dispatch_to_agent by chatId; the source session's CC unblocks when the matching reply lands. 15-minute timeout caps — see hub_v1/server/src/services/agents.ts and services/op-routes.ts.

For await_routed_prompt to actually fire — i.e., for an agent to service incoming requests — its CLAUDE.md needs a line telling Claude to call it at the start of each turn. Without that note, Claude won't know to consult the inbox. See hub_v1/docs/3-AGENT-SETUP.md for the dispatcher-pattern setup.

Hook coverage

Maps each Claude Code hook to a hub event. The hook script is dist-hook/clawborrator-tail.mjs; auto-installed on first MCP startup (no separate install step).

SessionStart / SessionEnd are intentionally not hooked by this MCP. The hook spawn had a fundamental race — the sidecar isn't written yet at SessionStart, and is already gone by SessionEnd — so lifecycle is now emitted server-side from the /channel WS welcome / close transitions (hub_v1/server/src/ws/channel.ts). Hub-authoritative, captures actual channel liveness, no hook timing involved.

The tail reads the CC transcript file directly to enrich PreToolUse with the assistant's pre-reply text (which CC doesn't put on the hook payload directly). See transcript.ts for the walker.

Local dev (linked to a sibling hub_v1 checkout)

npm install
npm run build
npm link

# verify the binary is on PATH
clawborrator-mcp --hook=PreToolUse < /dev/null   # exits cleanly with no sidecar

When claude runs in a folder whose .mcp.json references clawborrator-mcp, npm/npx resolves it to your linked build.

To publish a new release:

npm version patch                # bumps package.json + creates git tag
npm publish
git push --follow-tags

The CLI's claw token mint --mcp-snippet autogenerates an .mcp.json snippet pointing at the published version.