bus-mcp

Tests

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:<hostname>:<pid> 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

Write auth (v1.1 shared secret + v1.2 machine token)

The coordination bus can optionally gate its 4 write routes (post_message, claim_lane, release_lane, heartbeat_lane) behind one of two credentials, checked by the bus's require_write_auth dependency (backend/auth/dependency.py in the alphahive repo) in this order:

1. Machine token (X-Bus-Token, from BUS_MACHINE_TOKEN) -- a per-caller, per-scope, individually-revocable token minted by the backend. If a token is presented and fails to resolve, the request is rejected outright -- it does not fall through to the legacy secret.
2. Legacy shared secret (X-Bus-Secret, from BUS_WRITE_SECRET) -- the original v1.1 credential: one shared value, wildcard-scoped, no per-caller identity.

This client mirrors that precedence exactly and reads the same two env var names from its own process. bus_mcp/client.py's post() attaches at most one header per call:

• BUS_MACHINE_TOKEN set -> sends X-Bus-Token: <value> only. The legacy secret, even if also configured, is not also sent -- sending both would misrepresent the secret as a fallback the server will actually take when it won't (the server ignores legacy_secret entirely once a machine_token is presented).
• BUS_MACHINE_TOKEN unset, BUS_WRITE_SECRET set -> sends X-Bus-Secret: <value> (the original v1.1 behavior, unchanged).
• Neither set -> no auth header, identical to talking to a bus that has never been armed.

bus_mcp/routes.py and every tool caller stay unaware of which credential, if any, is configured or which header was chosen. client.get() never attaches either header (GET routes are never gated bus-side).

To use with an armed bus: for the legacy secret, set BUS_WRITE_SECRET to the same value in both the AlphaHive backend's environment and this MCP server's environment, then restart both processes. For a machine token, the backend never reads an env var: mint the token on the backend (it stores only a hash) and set BUS_MACHINE_TOKEN to the minted value in THIS server's environment only (e.g. in the config that launches run_server.py), then restart this server. If the value is missing or wrong, a write tool call returns the normal {"ok": false, "error": {"type": "bus_api_error", "status_code": 401, ...}} shape -- no special-casing needed, it flows through the same typed BusApiError path as any other 4xx.

Unset (default): no header is sent, identical to talking to a bus that has never been armed -- zero behavior change from pre-v1.1.

Lease ceiling surfacing (coordination-bus v1.3+)

The bus supports an operator-configurable ceiling on granted lease durations (BUS_MAX_LEASE_SECONDS, bus-side): a claim_lane/heartbeat_lane request for lease_s=7200 may be silently clamped to a shorter effective grant (e.g. 3600s) rather than rejected -- see coordination_bus.README.md's "v1.3 - configurable lease ceiling" section in the alphahive repo for the full server-side story.

This client surfaces both halves of that contract, additively:

• claim_lane / heartbeat_lane responses include a top-level lease_s field on ok=True -- the EFFECTIVE (post-clamp) duration actually granted. Always check this rather than assuming the requested lease_s was honored in full; a caller that ignores it and heartbeats on its own optimistic schedule risks its lane going stale early.
• get_bus_status exposes _meta.max_lease_seconds -- the currently configured ceiling, so a caller can check before it even claims.

Both fields are pure passthrough: bus_mcp/routes.py merges the bus's raw JSON response into the tool result ({"ok": True, **result}), so no client-side code change was needed to carry these new fields -- only the tool descriptions (below) and test coverage locking the behavior in both directions. Version-tolerant by construction: against a pre-v1.3 bus that omits these fields entirely, the tool result simply lacks lease_s / max_lease_seconds -- never a crash, never a synthesized default.

No client-side ceiling caching/pre-flight warning is implemented -- this client holds no state between calls (every tool call is a fresh httpx request), so there is nothing to check a requested lease_s against locally before the round-trip. A caller that wants to avoid a surprise clamp should call get_bus_status first and compare its own lease_s request against _meta.max_lease_seconds.

Usage examples

Once connected in a Claude session, an agent can:

claim_lane(lane="feeds-refactor", owner="session-A", lease_s=300)
heartbeat_lane(lane="feeds-refactor", owner="session-A")
post_message(topic="converge", sender="session-A", body="lane merged to master")
release_lane(lane="feeds-refactor", owner="session-A")
get_bus_status()

Or hold a conversation, and get a claim refuted rather than believed:

open_thread(topic="converge", title="feeds-refactor is ready", kind="DECIDE",
            body="suite green on a clean checkout, one skip. Merge?")
list_threads(status="open")
reply_in_thread(thread_id=4, body="re-ran it on a clean checkout: same result")
get_thread(thread_id=4)
resolve_thread(thread_id=4, note="merged at a1b2c3d")

mint_dispatch(lane="feeds-refactor", repo="bus-mcp", purpose="verify the claim")
request_validation(subject_ref="message:24047", evidence_refs="junit.xml")
vote(validation_id=7, dispatch_id="a1b2c3d4e5f6", verdict="refuted",
     evidence="tests/out.xml line 88")
get_validation(validation_id=7)

Testing

.venv/Scripts/python.exe -m pytest -q

CI (.github/workflows/ci.yml) runs this suite on every push/PR and fails the build if the Tests badge above drifts from what the suite actually reports -- see scripts/check_readme_counts.py.

All HTTP is mocked via respx -- the full suite never depends on a live bus, and an autouse fixture makes that enforceable rather than customary: any unmocked request raises instead of leaving the process. (Opt-in mocking failed silently exactly where it mattered most -- on refusal tests, which assert that a call does not happen.) One additional test, tests/test_live_smoke.py::test_live_get_bus_status_returns_rollup, is gated behind BUS_MCP_LIVE=1 and calls a real running bus's get_bus_status route. It skips unless you set that variable, which is why the suite reports one skip.

The bus routes are live on a running backend -- point BUS_MCP_BASE_URL at yours and that test passes. A 404 from one of them does not mean the route is wrong: it means the backend is running a build older than the route, and the tool result says so, carrying status_code: 404 in the same typed bus_api_error shape as any other response. Update the backend or use the tools that its build does serve.

Install / connect

python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[test]"

Registered in ~/.claude.json under mcpServers.bus-mcp as a stdio server invoking run_server.py by absolute path (no cwd needed -- the entrypoint adds its own directory to sys.path).

After merging a new version, an already-running Claude Code session is still talking to the OLD server process. Run /mcp to reconnect (or start a new session) before relying on any behavior a new release changed -- otherwise a fixed tool can look unfixed simply because nothing restarted it.

Handshake check

.venv/Scripts/python.exe scripts/list_tools.py

Prints every registered tool name with no transport started -- pure introspection, useful for verifying the server wires up cleanly after any change. The count it prints is gated against the Tools badge above by tests/test_check_readme_counts.py, which also fails if a registered tool has no row in the tables above -- a matching count is not coverage.

Out of scope

• Authenticating who owner/sender claims to be -- the shared secret (v1.1) proves possession of a value, not identity; that stays client- asserted, now consistently so via BUS_MCP_AGENT_ID. See "Identity" above and the bus's own README for that boundary.
• Any operator-authority route: deciding a validation, minting a task, sweeping the board. See "What this will never wrap".
• Restarting the AlphaHive backend to bring the live bus routes up (operator, elevated -- not something this MCP does)
• Bus v2 execution/approval features (a separate, not-yet-built arc)

Commercial support

Maintained by Jaimen Bell. For production MCP integrations, custom servers, or agent-reliability work, see jaimenbell.dev.

Building your own MCP server? The MCP Starter Kit has templates, a build playbook, and packaging war-stories from shipping this one.

mcp-name: io.github.jaimenbell/bus-mcp