Agent Bus MCP

Agent Bus MCP is a public, vendor-neutral, MIT-licensed durable task queue with a minimal MCP bridge. It is intended for an operator who wants a small, inspectable handoff between a local producer and one configured MCP worker route.

It exposes exactly three remote tools: claim_task, complete_task, and fail_task.

Capability boundary

It can durably accept locally produced bounded tasks, let the configured worker claim one task, and let that worker complete or fail its exact live lease. It uses atomic filesystem JSON records, a process lock, file and directory fsync, durable idempotency keys, 900-second leases with fencing, and immutable terminal completed/failed states. Producer and worker identities use a closed format and are fixed at startup; an MCP request cannot select either identity.

It cannot enqueue remotely; expose fail reasons; create sessions, SSE, heartbeats, or multi-worker routing; fetch a network URL; access a filesystem or shell through an MCP tool; integrate with a vendor; or publish packages/releases. References receive syntactic public-HTTPS validation only: HTTPS plus a hostname is not proof that a source is safe, public, accurate, or appropriate to fetch.

Related MCP server: superagentic

Protocol boundary

The endpoint is authenticated, stateless POST /mcp JSON-RPC. It accepts one request per POST and rejects batches. Notifications without an id receive HTTP 202 with an empty body. It supports initialize, ping, tools/list, and calls to the three tools above. This is not full Streamable-HTTP compatibility: there are no sessions, SSE streams, resumability, or server-initiated messages. Confirm that the selected MCP client can use this stateless POST-only contract before deploying it.

Every tool response has this envelope; content[0].text is a JSON string encoding the same object as structuredContent:

{"result":{"content":[{"type":"text","text":"{\"status\":\"empty\"}"}],"structuredContent":{"status":"empty"}}}

claim_task returns either {"status":"empty"} or {"status":"claimed","task_id":"...","goal":"...","references":["..."],"lease_id":"...","lease_expires_at":"..."}. Its lease is 900 seconds. complete_task requires task_id, lease_id, and a result of at most 2048 bytes; it returns {"status":"completed","task_id":"..."} or {"status":"already_completed","task_id":"..."}. fail_task requires only task_id and lease_id, takes no result, and returns failed or already_failed in the same shape. Both terminal tools refuse stale or mismatched leases.

Install and configure

Requires Python 3.11+ and Unix fcntl; running the bridge also requires uvicorn.

git clone https://github.com/rickkeller/agent-bus-mcp
cd agent-bus-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
# Alternative, install directly from the public repository:
python -m pip install 'git+https://github.com/rickkeller/agent-bus-mcp.git'

Create a private environment file (mode 0600 is appropriate). Tokens never belong in git.

mkdir -p /home/operator/.config/agent-bus-mcp /home/operator/.local/state/agent-bus-mcp
chmod 700 /home/operator/.local/state/agent-bus-mcp
cp .env.example /home/operator/.config/agent-bus-mcp/env
chmod 600 /home/operator/.config/agent-bus-mcp/env

/home/operator is deliberately fake; replace it with the operator's actual home directory. Edit the private file and replace every value:

AGENT_BUS_STATE_DIR=/home/operator/.local/state/agent-bus-mcp
AGENT_BUS_BEARER_SECRET=EXAMPLE_NOT_A_REAL_TOKEN_REPLACE_ME
AGENT_BUS_BIND_HOST=loopback
AGENT_BUS_PORT=8765
AGENT_BUS_PRODUCER_ID=example_producer
AGENT_BUS_WORKER_ID=example_worker

AGENT_BUS_STATE_DIR must be the persistent 0700 directory. AGENT_BUS_BEARER_SECRET must be a unique high-entropy token kept only in the private file and rotated after suspected exposure. AGENT_BUS_BIND_HOST must be loopback; AGENT_BUS_PORT is a decimal port. The two identities must each be 1--64 characters of [A-Za-z0-9_-] and must match between bridge and producer. The shown token and identities are intentionally fake.

Run locally:

set -a; . /home/operator/.config/agent-bus-mcp/env; set +a
agent-bus-mcp

The service listens only on loopback. For remote use, the operator must place an authenticated TLS-terminating reverse proxy in front of it and decide who may reach it. Do not expose the loopback service directly or treat syntactic HTTPS reference validation as a network safety control.

Generic remote MCP configuration:

{"mcpServers":{"agent-bus":{"url":"https://mcp.example.invalid/mcp","headers":{"Authorization":"Bearer EXAMPLE_NOT_A_REAL_TOKEN_REPLACE_ME"}}}}

The URL and token above are placeholders; use a client that supports the stateless compatibility limit described above.

Operator smoke test

With the private env loaded and bridge running, these requests demonstrate the contract:

curl -sS -X POST http://localhost:8765/mcp -H 'Authorization: Bearer EXAMPLE_NOT_A_REAL_TOKEN_REPLACE_ME' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
curl -sS -X POST http://localhost:8765/mcp -H 'Authorization: Bearer EXAMPLE_NOT_A_REAL_TOKEN_REPLACE_ME' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
curl -sS -X POST http://localhost:8765/mcp -H 'Authorization: Bearer EXAMPLE_NOT_A_REAL_TOKEN_REPLACE_ME' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"claim_task","arguments":{}}}'

After a claimed response, keep its task_id and lease_id, finish within 900 seconds, and submit either complete_task with a bounded result or fail_task without one. A lease that expires or does not match is refused; do not retry it as a new lease.

Local example producer and systemd

The checked-in public-research manifest is only an example workload, not the product. Its sole reference uses a reserved .invalid URL and it never fetches that URL. The timer and service run it weekly, matching the manifest:

agent-bus-public-research --cadence weekly --state-dir /home/operator/.local/state/agent-bus-mcp --producer-id example_producer --worker-id example_worker
mkdir -p /home/operator/.config/systemd/user
cp systemd/* /home/operator/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now agent-bus-mcp.service agent-bus-public-research.timer

The shipped user services load %h/.config/agent-bus-mcp/env, preserve state at %h/.local/state/agent-bus-mcp, and permit writes only there. Create that directory with 0700 before enabling them; state must survive reboot.

Development

python3 -m pytest -q
python3 -m compileall -q src tests
systemd-analyze --user verify systemd/*.service systemd/*.timer
git diff --check

What this is not

It is not a general job platform, a network agent, a remote enqueue API, a full Streamable-HTTP server, a task-result trust boundary, or a substitute for an operator's TLS, authorization, backup, and incident-response decisions. See SECURITY.md.