Bus MCP

bus-mcp

An ergonomic MCP server fronting the self-hosted AlphaHive coordination bus (backend/coordination_bus.py in the alphahive repo) -- so a Claude agent calls claim_lane("feeds-refactor", owner="session-A") instead of hand-rolling curl -X POST .../lanes/feeds-refactor/claim -d '{...}'. Built to the desktop-mcp/github-mcp standard (own pyproject, fastmcp server, honest README, real test suite) -- this is that exact "MCP over an HTTP API" pattern turned on our own self-hosted API.

Quickstart (60 seconds)

pip install bus-mcp

Add to your Claude Desktop/Code MCP config:

{

"mcpServers": { "bus-mcp": { "command": "bus-mcp" } } }

No console script on PATH? Fall back to "command": "python", "args": ["-m", "bus_mcp"]. By default this talks to a bus at http://127.0.0.1:8100/api/bus -- see "Env vars" below to point it elsewhere.

What this is / is not

This fronts a private, localhost-only, no-auth v1 coordination substrate -- not a public service. The bus itself is a blackboard (append-only messages) + a lane-claim registry (task-queue leases with steal-on-expiry) + a status rollup for a command-center panel. It executes nothing outward-facing: action_flag on a message is recorded and displayed only, never acted on by the bus. bus-mcp adds zero new capability over what the bus already does via curl -- it only makes the routes ergonomic MCP tools with typed inputs and typed errors instead of raw HTTP. It deliberately wraps LESS than the bus offers: see "What this will never wrap" below.

Tools

24 tools. Writes are gated (BUS_MCP_ENABLE_WRITE); reads never are.

Messages and lanes

Threads -- topics are the broadcast log; threads are how two agents (or an agent and a human) hold one conversation with a beginning and an end.

Validations and dispatches -- request a refutation, vote under a registered dispatch id.

Board, worker, events

Every bus route wrapped here is coordination-only (store / display / claim). As of coordination-bus v1.1 the bus MAY require a shared secret on its write routes (default off); this client mirrors that with zero new config surface of its own -- see "Write-secret auth (v1.1)" below. Separately, this server has its own local write gate (BUS_MCP_ENABLE_WRITE, default off) and a second, narrower gate for task claiming.

What this will never wrap

Three bus routes are operator-authority and have no tool here, by design. tests/test_rails_pins.py enforces their absence by both source grep and registered-tool introspection, so the rule is a test rather than a promise.

Identity (BUS_MCP_AGENT_ID)

The bus authenticates nobody on sender / owner / opened_by: it shape-checks a string. Two MCP sessions sharing a write secret are otherwise indistinguishable in the log.

This server asserts one consistent identity -- BUS_MCP_AGENT_ID when set, otherwise session: : computed once at import and sanitized to the bus's own role shape (printable ASCII, no whitespace, 1-64 chars). It is the default for sender, owner, opened_by, requested_by, voter, minted_by and resolved_by when the caller omits them, and every tool result echoes the value used under `agent_id` -- including error and refusal payloads, where a caller most needs to know which identity was rejected.

This is not authentication, and the echo is the honest part. Any holder of the write secret can assert any identity. What this buys is consistency and a straight answer to "what did you put on the wire as me".

Task claiming is dark by default (BUS_MCP_ENABLE_TASK_CLAIM)

claim_task / heartbeat_task / finish_task refuse unless BUS_MCP_ENABLE_TASK_CLAIM is truthy, with a refusal that names both the gate and the reason.

It is not a duplicate of BUS_MCP_ENABLE_WRITE. The write gate asks whether this server may write to the bus at all; this one asks whether an MCP-driven session is a registered *claimant* of board work -- a separate question, whose answer today is no. The two gates stack with the write gate outermost, so a server with writes off answers "writes are off", and arming the narrow gate is never a way around the broad one.

Filters the backend ignores today

read_messages accepts thread_id, recipient and since_id and sends them as query params. The current backend ignores all three: its message read declares topic and limit only, and FastAPI drops query params a route does not declare. Passing them changes nothing about what comes back.

They are wired anyway, deliberately: the server-side filters are a separate backend change, and when it lands these params start working with no change here and no version negotiation. get_thread no longer needs this pattern for its own primary path (it calls the bus's GET /threads/{id} route directly as of 0.2.1) -- but its FALLBACK path still filters client-side exactly this way when that route is unavailable, which is why a composed result reports scanned and scan_truncated rather than implying it saw the whole thread.

Typed errors, never a raw crash

Every tool returns {"ok": true, ...} on success or {"ok": false, "error": {...}} on failure -- never an unhandled exception or stack trace.

• `bus_unreachable` -- connection refused, timeout, or DNS failure. Means the AlphaHive backend isn't running, or is running without the bus routes loaded (backend/coordination_bus.py mounted on :8100).
• `bus_api_error` -- the bus responded with a 4xx/5xx. Carries status_code + the bus's own detail text -- e.g. a 409 lane-conflict message telling you who holds the lane and for how long.

Internally, bus_mcp/client.py raises typed BusUnreachable / BusApiError exceptions; bus_mcp/routes.py catches both and normalizes to the dict shape above before a tool ever returns. Tests exercise both layers.

Env vars

| BUS_MCP_ENABLE_TASK_CLAIM | unset (off) | Second, narrower gate for claim_task / heartbeat_task / finish_task. See "Task c