What can you do with this server?

Based on the provided schema, this MCP server lets you interact with the coordination bus's message blackboard and lane-claim registry. * post_message – append a message to the blackboard; action_flag is recorded/displayed only. * read_messages – fetch recent messages, newest first, with optional topic filter and limit. * claim_lane – claim a coordination lane, with optional lease_s; response shows the effective lease granted. * release_lane – release a lane you hold. * heartbeat_lane – renew a lane lease; response shows the effective lease granted. * get_bus_status – get a rollup of active lanes, orphaned claims, recent messages, pending action flags, and the lease ceiling when available.

bus-mcp

by jaimenbell

Overview Schema Source Related Servers Discussions Admin

Python

Remote

bus-mcp

PyPI MCP Registry License: MIT Tests Tools

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.

Related MCP server: cueapi-mcp

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

Tool	Bus route	Purpose
`post_message`	`POST /api/bus/message`	Append one message to the blackboard. Optional addressing: `thread_id` (a reply in that thread), `reply_to` (the message it answers), `recipient` (a role; omitted = broadcast)
`read_messages`	`GET /api/bus/messages`	Recent messages, newest first, optional topic filter. `thread_id` / `recipient` / `since_id` are accepted but the current backend ignores them -- see "Filters the backend ignores today"
`claim_lane`	`POST /api/bus/lanes/{lane}/claim`	Claim-if-free / steal-if-lease-expired / renew-if-own; 409 if held live by another. Response echoes the effective (post-clamp) `lease_s` granted -- see "Lease ceiling" below.
`release_lane`	`POST /api/bus/lanes/{lane}/release`	Free a held lane; 409 if held live by another
`heartbeat_lane`	`POST /api/bus/lanes/{lane}/heartbeat`	Renew the lease; 409 if you don't hold it live. Response echoes the effective `lease_s`, same as claim.
`get_bus_status`	`GET /api/bus/status`	Rollup: active lanes, orphaned claims, recent messages, pending action flags, effective `_meta.max_lease_seconds` ceiling

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.

Tool	Bus route	Purpose
`list_threads`	`GET /api/bus/threads`	Threads, newest first. Omitting `status` excludes archived -- ask for `status="archived"` separately
`get_thread`	`GET /api/bus/threads/{id}`	One thread plus its messages. Falls back to a client-side composition (`GET /threads` + a topic-filtered `GET /messages`) if the by-id route is absent or flagged dark -- check `composed` and, on a composed result, `scan_truncated`
`open_thread`	`POST /api/bus/threads`	Open a thread + its root message. `opened_by` is the resolve authority afterwards; `kind="DECIDE"` marks a thread only the operator may resolve
`reply_in_thread`	`POST /api/bus/message`	Reply inside a thread. `topic` is looked up from the thread when omitted
`resolve_thread`	`POST /api/bus/threads/{id}/resolve`	Resolve a thread you opened. `resolved_by="operator"` is refused client-side; a `note` is posted as a thread reply first

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

Tool	Bus route	Purpose
`list_validations`	`GET /api/bus/validations`	Validations, newest first; optional subject_ref / verdict / thread_id filters
`get_validation`	`GET /api/bus/validations/{id}`	One validation by id -- no page to fall off, 404 when genuinely absent
`request_validation`	`POST /api/bus/validations`	Open a validation. `subject_kind` is derived from the `subject_ref` prefix (`message:` / `task:` / `proposal:`), never guessed; `tier` is derived server-side and is not a parameter
`vote`	`POST /api/bus/validations/{id}/vote`	Cast one vote under a registered dispatch id. `evidence` is a pointer, not the argument
`list_dispatches`	`GET /api/bus/dispatches`	Registered dispatches, newest first
`mint_dispatch`	`POST /api/bus/dispatches`	Register a dispatch so a vote cast under it can be counted
`report_dispatch`	`POST /api/bus/dispatches/{id}/report`	Close the loop: report against a dispatch id, naming the evidence

Board, worker, events

Tool	Bus route	Purpose
`list_tasks_board`	`GET /api/bus/tasks/board`	The task board. `status` / `limit` are applied client-side (the route takes only `include_archived`)
`claim_task`	`POST /api/bus/tasks/{id}/claim`	Dark by default (`BUS_MCP_ENABLE_TASK_CLAIM`). Mints and returns the `claim_token` -- keep it, the board will not give it back
`heartbeat_task`	`POST /api/bus/tasks/{id}/heartbeat`	Dark by default. Renews the lease for the live (owner, claim_token) holder; `want_running=True` performs claimed -> running
`finish_task`	`POST /api/bus/tasks/{id}/finish`	Dark by default. Terminal write: done / failed / needs_operator
`get_worker_state`	`GET /api/bus/worker`	The overnight worker's last heartbeat. Missing is never zero: unmeasured fields are null and the envelope carries data age
`read_events`	`GET /api/bus/events`	Cursor poll over the append-only event log. Rows come back ascending by id

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.

Route	Why not
the validation decide route	Authenticated by a second `X-Bus-Operator-Secret` this server does not hold. A quorum this client can request and vote in, but cannot decide, is the whole separation
the task minting route	Mints executable work; its `auto` class is operator-authenticated. Minting stays a CLI ritual against a staged file a human has read
the task sweep route	Terminally abandons other claimants' rows -- not per-task, not reversible

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

Var	Default	Purpose
`BUS_MCP_BASE_URL`	`http://127.0.0.1:8100/api/bus`	Base URL of the coordination bus
`BUS_MCP_TIMEOUT_S`	`10.0`	Per-request timeout (seconds)
`BUS_MCP_LIVE`	unset	Set to `1` to run the real-network smoke test (see Testing)
`BUS_MCP_ENABLE_WRITE`	unset (off)	Local write gate. Every mutating tool refuses with a typed `policy_refusal` until this is truthy -- separate from `BUS_WRITE_SECRET`, which authenticates a write against the bus over the wire
`BUS_MCP_ENABLE_TASK_CLAIM`	unset (off)	Second, narrower gate for `claim_task` / `heartbeat_task` / `finish_task`. See "Task claiming is dark by default"
`BUS_MCP_AGENT_ID`	`session:<hostname>:<pid>`	The identity this server asserts on writes and echoes as `agent_id`. See "Identity"
`BUS_WRITE_SECRET`	unset	Same var the bus itself reads to arm write-auth (v1.1). When set here (and `BUS_MACHINE_TOKEN` is NOT set), every write tool call sends `X-Bus-Secret: <value>` automatically. Unset = no header sent, matching an unarmed bus byte-for-byte.
`BUS_MACHINE_TOKEN`	unset	A per-caller, per-scope, revocable machine token (`<token_id>.<secret>`) minted by the AlphaHive backend, sent as `X-Bus-Token`. Takes precedence over `BUS_WRITE_SECRET` when both are set. See "Write auth" below.

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:

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.
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

Available Tools

6 tools

claim_laneA

Claim a coordination lane before starting work in it: claim-if-free, steal-if-lease-expired, renew-if-you-already-own-it. A 409 (lane held live by another owner) comes back as a clean ok=False conflict, not a crash. The bus may grant a shorter lease than requested (server-side ceiling, coordination-bus v1.3+): on ok=True the response's top-level lease_s is the EFFECTIVE (post-clamp) duration actually granted -- always check it rather than assuming the requested value was honored. See get_bus_status's _meta.max_lease_seconds for the currently configured ceiling. Older bus servers (pre-v1.3) omit lease_s from the response entirely; its absence just means the bus predates the ceiling feature, not an error.

ParametersJSON Schema

Name	Required	Description	Default
`lane`	Yes
`owner`	Yes
`lease_s`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses behavior: conflict handling (409 with ok=False), lease clamping, and backward compatibility with older servers. It warns about checking the effective lease_s rather than assuming the requested value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose and is structurally sound. It is somewhat lengthy but every sentence adds value, covering modes, conflict, lease clamping, and version info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, lack of annotations, and presence of an output schema, the description covers all essential aspects: behavior, edge cases (409, older servers), and guidance for checking effective lease_s. It is complete for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description explains the lease_s parameter's behavior (requested vs. effective) and implies the meanings of lane and owner through context. It does not explicitly describe lane and owner, but the usage context is sufficient for understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'Claim a coordination lane before starting work in it.' It lists three specific modes (claim-if-free, steal-if-lease-expired, renew-if-you-already-own-it), which distinguishes it from sibling tools like release_lane and heartbeat_lane.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use (before starting work) and references get_bus_status for checking the ceiling. However, it does not explicitly state when not to use or compare directly with siblings, though the behavior is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bus_statusA

Roll-up for the command-center panel: active lanes, orphaned/stale claims, recent messages, pending display-only action flags. Also exposes _meta.max_lease_seconds (coordination-bus v1.3+): the currently configured lease ceiling that claim_lane/heartbeat_lane requests get silently clamped to. Check this before claiming a lane for longer than the default if you need to know whether the request will actually be honored in full. Older bus servers (pre-v1.3) omit max_lease_seconds from _meta entirely; its absence just means the bus predates the ceiling feature, not an error.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully covers behavioral traits: it returns a roll-up of status data, and exposes `_meta.max_lease_seconds` which represents a silent clamp for claim/heartbeat requests. It also clarifies that absence of `max_lease_seconds` is not an error but indicates an older server. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with the main purpose upfront, followed by detailed context about `_meta.max_lease_seconds`. While slightly lengthy, every sentence adds value. It could be slightly more concise but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (indicated by context), the description does not need to detail return values. It covers the essential elements of the roll-up and provides critical context about the meta field. The tool is complex but the description is complete for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description does not need to add parameter semantics beyond the schema. Baseline 4 applies as no parameter info is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a roll-up for the command-center panel including active lanes, orphaned/stale claims, recent messages, and pending display-only action flags. It also specifies the exposure of `_meta.max_lease_seconds` for coordination-bus v1.3+. This distinguishes it from siblings like claim_lane and heartbeat_lane.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to check this tool before claiming a lane for longer than the default to know if the request will be honored in full. It also notes behavior differences for older bus servers, providing clear guidance on when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

heartbeat_laneA

Renew the lease on a coordination lane you hold live. A 409 (not held live by you) tells you to (re)claim instead of crashing. Like claim_lane, renewal is subject to the same server-side lease ceiling (coordination-bus v1.3+): on ok=True the response's top-level lease_s is the EFFECTIVE (post-clamp) duration actually granted, which may be shorter than requested -- check it rather than assuming the request was honored in full. See get_bus_status's _meta.max_lease_seconds for the currently configured ceiling. Older bus servers (pre-v1.3) omit lease_s from the response entirely; its absence just means the bus predates the ceiling feature, not an error.

ParametersJSON Schema

Name	Required	Description	Default
`lane`	Yes
`owner`	Yes
`lease_s`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that renewal is subject to a server-side lease ceiling, the response's lease_s may be shorter than requested, and older bus servers (pre-v1.3) omit lease_s entirely. It also mentions the 409 error condition and references get_bus_status for the current ceiling. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet thorough. It starts with the core action, then covers error handling, lease ceiling behavior, and older server behavior in a logical order. Every sentence adds value without redundancy. It is well-structured and information-dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (renewal with lease ceiling, response semantics, error handling), the description covers all necessary aspects. It explains the response's lease_s, references get_bus_status for configuration, and handles the 409 error. An output schema exists, so return values are not required in the description. It is complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description clarifies the lease_s parameter as the requested duration and explains that the response's lease_s is the effective granted duration. It does not explicitly define lane or owner, but they are implied from context (lane is the coordination lane, owner is the holder). The description adds meaningful interpretation for lease_s but could be more explicit about lane and owner.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Renew the lease on a coordination lane you hold live.' It uses a specific verb (renew) and resource (coordination lane lease). It distinguishes from siblings like claim_lane and release_lane by focusing on renewal and mentioning the 409 error that tells you to re-claim instead of crashing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use: when holding a live lane to extend its lease. It provides a specific condition: a 409 status indicates you need to re-claim (using claim_lane) rather than retrying the heartbeat. It also advises checking the response's lease_s rather than assuming the request was honored, which guides correct usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

post_messageA

Append one message to the coordination-bus blackboard (append-only). v1 stores action_flag but performs no action -- it is display-only, seen by a human watching the command-center panel.

ParametersJSON Schema

Name	Required	Description	Default
`body`	Yes
`topic`	Yes
`sender`	Yes
`action_flag`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that action_flag is stored but display-only (no action performed). However, no annotations are provided, and the description does not cover other behavioral aspects like idempotency, rate limits, or potential side effects beyond append-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two brief sentences that efficiently convey core purpose and a key nuance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately describes the tool's main function and a behavioral quirk, but lacks details on response format (though output schema exists), error conditions, and parameter constraints. Sufficient for a simple append operation but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate, but it only explains action_flag's behavior. The other parameters (topic, sender, body) are left undefined, providing insufficient guidance for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Append one message' and the resource 'coordination-bus blackboard', and specifies append-only behavior. Distinguishes from sibling tools like read_messages, release_lane, etc., which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage context from sibling tool names (e.g., read_messages for reading), but no explicit when to use or when not to use. Lacks guidance on prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_messagesA

Recent bus messages, newest first, optionally filtered by topic.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`topic`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It mentions ordering and filtering but omits details like read-only nature, pagination, maximum limit, or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that front-loads key information: what (recent bus messages), how ordered (newest first), and optional filter. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values are covered externally. The description adequately communicates the core functionality for a simple read operation, though minor details like the default limit behavior could be mentioned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description adds value by mentioning 'optionally filtered by topic' for the topic parameter, but does not explain the limit parameter (default, max) or what constitutes a valid topic string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (read), resource (bus messages), ordering (newest first), and optional filtering (by topic). It distinguishes from sibling tools like post_message (write) or heartbeat_lane (status).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives like post_message or get_bus_status. It implies reading messages but lacks context-specific guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

release_laneB

Release a coordination lane you hold. A 409 (held live by another owner) comes back as a clean ok=False conflict, not a crash.

ParametersJSON Schema

Name	Required	Description	Default
`lane`	Yes
`owner`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description adds behavioral context that a conflict returns ok=False instead of a crash, but does not disclose other traits like whether the operation is destructive or requires certain permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two clear, focused sentences; the first states the purpose, the second adds error-handling nuance. Efficient with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of parameter info and no annotations, the description is insufficient for agents to understand how to use the tool correctly, especially without explaining what lane and owner values are valid.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fails to explain what 'lane' and 'owner' represent, providing no additional meaning beyond the bare field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'release' and identifies 'coordination lane' as the resource, clearly distinguishing it from siblings like claim_lane and heartbeat_lane.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating how conflicts are handled (409 becomes ok=False), but does not explicitly state when to use the tool vs alternatives or provide prerequisites like having claimed the lane.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.1Jul 24, 2026
- First observedclaim_lane
- First observedget_bus_status
- First observedheartbeat_lane
- First observedpost_message
- First observedread_messages
- First observedrelease_lane

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-24 18:43 across 6 tools

Disambiguation5/5

Each tool targets a distinct operation: posting versus reading messages, claiming, releasing, heartbeating a lane, and getting bus status. Their descriptions are detailed and uniquely identify each tool's purpose.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (post_message, read_messages, release_lane, claim_lane, heartbeat_lane, get_bus_status), making them predictable.

Tool Count5/5

Six tools is appropriate for a coordination bus: two for messaging, three for lane lifecycle management, and one for status. No obvious over- or under-coverage.

Completeness5/5

The tool set covers the core operations of the bus: message production/consumption, lane claiming/releasing/heartbeating, and status introspection. No obvious gaps given the append-only messaging and lane management domain.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Probe V0 A
io.github.lexbritten
Experimental MCP server for current empirical verification of explicit public HTTPS endpoint claims.
API Testing Penetration Testing
21
Tanjiren MCP Server
app.tanjiren
Hosted MCP server for task-first delegation to remote workstations and workers.
Agent Orchestration Autonomous Agents Developer Tools
2
mcp-serverOAuth
com.ffmpeg-micro
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Multimedia Processing App Automation
21
Customer Io
io.github.pipeworx-io
MCP server for customer-io
Communication CRM Customer Data Platforms
1

Related MCP Servers

taskqueue-mcp
Project Management Agent Orchestration
chriscarrollsmith
A
license
A
quality
C
maintenance
MCP server for "taming the Claude" with structured task queues.
Updated a year ago (2025-04-12 16:32 UTC)
14
29 npm
71
MIT
cueapi-mcpofficial
Autonomous Agents Agent Orchestration CI/CD & DevOps
cueapi
A
license
A
quality
F
maintenance
Official MCP server for CueAPI. Schedule agent work on a cron, report write-once outcomes with evidence, and gate handoffs with verification from any MCP host.
Updated 2 months ago (2026-08-03 15:55 UTC)
8
45 npm
3
MIT
MCP Manager
Developer Tools Agent Orchestration
daniel3303
A
license
Not graded
quality
B
maintenance
Self-hosted MCP proxy and aggregation platform. Register multiple upstream MCP servers and expose them through a single unified endpoint with namespace routing, multi-transport support (HTTP/SSE, stdio, OpenAPI→MCP), per-tool overrides, and a web admin UI.
Updated a month ago (2026-08-13 16:46 UTC)
18
MIT
quads-mcp
Cloud Platforms Virtualization
grafuls
A
license
Not graded
quality
D
maintenance
MCP server for interacting with QUADS infrastructure systems via API, enabling resource management and automation through LLM applications.
Updated a year ago (2025-07-10 11:07 UTC)
MIT

bus-mcp

Quickstart (60 seconds)

What this is / is not

Tools

What this will never wrap

Identity (BUS_MCP_AGENT_ID)

Task claiming is dark by default (BUS_MCP_ENABLE_TASK_CLAIM)

Filters the backend ignores today

Typed errors, never a raw crash

Env vars

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

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

Usage examples

Testing

Install / connect

Handshake check

Out of scope

Commercial support

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

cueapi-mcpofficial

Identity (`BUS_MCP_AGENT_ID`)

Task claiming is dark by default (`BUS_MCP_ENABLE_TASK_CLAIM`)