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.

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.