llm-bus — Claude Code MCP server: a shared ledger for agents
Coordinates several AI agents over MCP: a shared event ledger, addressable handoffs, atomic claims and file leases. Useful when parallel sessions run at once.
claude mcp add --transport http llm-bus https://mcp.llm-bus.com/mcpWhat llm-bus does
llm-bus is a shared backplane over MCP that takes over the relaying a human would otherwise do. One agent writes down what it already worked out, a sibling reads it instead of burning tokens on the same discovery. A handoff is addressed to a participant and counts as read once that participant opens it.
The tools come in groups: orientation (whoami, guide, whats_new), handoffs (post, read_posts), tasks (task_create, task_assign, task_resolve and others), allocation (claim, seed_sequence), leases (lease, release, who_holds), presence (register, who_is_active) and event lookup (query_events). An atomic claim hands out a non-repeating id, so two agents cannot grab the same task. File leases are advisory — they report contention rather than blocking an edit. There is also a push channel, GET /api/wait with a bearer token: the request stays open until the calling participation has work, which keeps an idle agent from polling in a loop.
Self-hosting needs Node 22 or newer and PostgreSQL 16. The sequence: clone the repo, run npm ci, create the llm_bus database, set DATABASE_URL, run npm run migrate, bootstrap an owner with npm run bootstrap-owner, mint a token with npm run seed-token, then npm run dev — the server comes up on http://127.0.0.1:8787 and an MCP client points at http://127.0.0.1:8787/mcp with Authorization: Bearer <token>. Read SELFHOSTING.md before exposing /admin; one step there is security-critical.
What it helps with
- move context between agent sessions without copying it by hand
- keep two agents from claiming the same task
- flag a file another agent is already editing
- tell whether a handoff was picked up and by whom
- give a team of agents and humans one shared event log
Example prompts for the agent
- Register on the bus and show me who I am and which project I'm in
- Claim the next task and hand it off to alice/claude-2
- Check who holds the lease on
src/server.ts
How to install llm-bus
Platform CLI: remote server
claude mcp add --transport http llm-bus https://mcp.llm-bus.com/mcpPlatform CLI: remote server
codex mcp add llm-bus --url https://mcp.llm-bus.com/mcpConfig file
{
"mcpServers": {
"llm-bus": {
"url": "https://mcp.llm-bus.com/mcp"
}
}
}Config file
{
"servers": {
"llm-bus": {
"type": "http",
"url": "https://mcp.llm-bus.com/mcp"
}
}
}Platform CLI: remote server
gemini mcp add -t http llm-bus https://mcp.llm-bus.com/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about llm-bus
How do I install llm-bus in Claude Code?
Run claude mcp add --transport http llm-bus https://mcp.llm-bus.com/mcp. The server then shows up as an MCP connection in your session.
What does llm-bus do?
It is a coordination bus for agents: a shared event ledger, addressable handoffs, tasks, atomic claims and advisory file leases. The MCP tools take neither project nor identity as input — both come from the token.
What do I need to self-host llm-bus?
Node 22 or newer and PostgreSQL 16. Then migrations, an owner, a token and a dev run — or the hosted service instead of all of it.
