Beads MCP Server

An owned Python MCP server built on the official MCP SDK v2. It exposes a curated typed surface over bd and keeps bd as the Beads domain authority.

Architecture

MCP SDK v2 Streamable HTTP
  -> static bearer verification
  -> typed tools with mandatory workspace_id and request actor for mutations
  -> explicit workspace registry
  -> one bounded async bd subprocess per call
  -> workspace-configured shared Dolt server

The server does not import or wrap the upstream beads-mcp package. It never queries Dolt directly and does not reproduce Beads business logic. Each call starts a fresh bd process using an argv list, a hard timeout, bounded stdout and stderr, cancellation cleanup, and an explicit child-environment allowlist.

Protocol sessions are not application state. Modern 2026-07-28 requests are sessionless and every workspace-sensitive call carries workspace_id. The registry resolves that stable identifier to an operator-controlled absolute path; clients cannot submit filesystem paths.

The first release deliberately has no request queue, semaphore, per-workspace lock, connection pool, or Dolt adapter. Sparse traffic from 40 to 50 connected agents should be measured before adding coordination that may duplicate what bd and the shared Dolt server already provide.

Tool surface

The server exposes workspaces, workspace_status, ready, list, show, create, claim, update, close, reopen, dep, comment, comments, note, heartbeat, unclaim, reclaim, stats, and blocked. workspaces returns only exact IDs and never server paths. workspace_status performs a read-only bd stats --no-activity probe for one ID. There is no mutable context tool, cwd discovery, arbitrary command passthrough, workspace provisioning, or direct Dolt operation.

Every mutating call carries a validated actor, which the runner passes as the global bd --actor argument. A worker must use the same stable actor for claim, heartbeat, and close. The server never changes an assignee during close and never exposes a force flag. Assignee changes through update require if_assignee compare-and-swap protection. Dead-worker recovery is explicit through reclaim, limited to stale leases on the local replica; cross-replica override is not exposed. Actor/assignee failures return a bounded, redacted BD_ASSIGNEE_MISMATCH diagnostic with the supported recovery choices.

Configuration

Copy .env.example to the service's existing protected environment file and set values through the operator's secret-management process. The service fails closed when the bearer token, public URL, allowed hosts, or workspace registry is absent.

For a central service with many repositories, point the server at an operator-controlled root:

BEADS_WORKSPACE_ROOT=/srv/beads-workspaces
BEADS_READINESS_WORKSPACE_ID=project-a

Every immediate child containing .beads/metadata.json or .beads/config.yaml becomes one exact workspace_id. The server never scans components of a client path and never treats dashes and underscores as aliases. Consequently, library, cognovis_core, and cognovis-core can coexist without ambiguity. An explicit BEADS_WORKSPACES_JSON object remains available for installations that prefer a fixed mapping; configure exactly one source.

Only these variables can reach bd when present: PATH, HOME, USER, LOGNAME, LANG, LC_ALL, BEADS_ACTOR, BEADS_DOLT_SERVER_HOST, BEADS_DOLT_SERVER_PORT, BEADS_DOLT_SERVER_USER, BEADS_DOLT_PASSWORD, and DOLT_PASSWORD. The server never logs their values. BEADS_ACTOR remains only a process fallback for read-only calls and legacy direct use; MCP mutations use their explicit request actor.

The public /health route is a process liveness check. /ready performs one configured read-only workspace probe and returns no workspace ID or filesystem path. The /mcp route requires the configured static bearer token. Host and Origin validation is enforced by the SDK's TransportSecuritySettings.

Local development

Python 3.14 and uv are required.

uv sync --frozen
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv build

Run the service with an operator-provided environment:

uv run beads-mcp-server

Deployment boundary

This repository contains the reusable package rather than a specific server's deployment. Install with uv sync --frozen --no-dev and run:

.venv/bin/beads-mcp-server

Keep service-manager units, reverse-proxy rules, concrete hostnames, secret delivery, and workspace locations in the consuming infrastructure repository. The server does not copy an environment file, create a token, initialize a Beads database, or rewrite workspace metadata.

Compatibility evidence

The test suite uses the official in-memory SDK client for modern discovery and typed tool calls. HTTP integration tests exercise the real ASGI transport, bearer rejection, Host and Origin rejection, and independent 2026-07-28 requests without Mcp-Session-Id.

No handshake-era client behavior is promised. stateless_http=True therefore disables legacy back-channels; this server has no server-initiated requests or legacy notifications that require them. Official final-spec conformance is run against a local HTTP endpoint before release and is reported separately from unit and client compatibility evidence.

License

Released under the MIT License.