MCP Agent Bus
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Agent Bus ask reviewer to review my latest commit and send results back"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Agent Bus
Agent Bus is Therapie Tech's first open-source software.
A local, event-driven MCP message bus for coordinating multiple AI coding-agent sessions on the same machine. One session can hand a task to another — the other runs it and sends the result back — with zero infrastructure: no cloud, no database, no network service. Just Node.js and the local filesystem.
Releases
This project is distributed via GitHub only (no hosted service). Install = clone + npm install + MCP setup — see Quick start.
Version | Highlights |
v1.1.0 (latest) | Monitoring dashboards ( |
First public release — MCP bus + Quick start |
Full history: CHANGELOG.md · All releases
Upgrade v1.0.0 → v1.1.0: git pull (or re-clone), npm install unchanged. New optional scripts under docs/; worker upgrade only affects you if you use the headless worker.
Related MCP server: letterbox
Why
When you work with AI coding agents you often have several sessions open at once (different windows, different models). By default they can't see each other — you copy-paste between windows by hand. MCP Agent Bus gives them a shared "post office": any session can drop a message addressed to another, which picks it up instantly and replies.
How it works
Everything is local. The "post office" is just a folder of JSON files:
<MCP_AGENT_BUS_DIR>/
inbox/<session>/*.json # direct messages, one folder per session
broadcast/*.json # announcements to everyone
cursors/<session>... # per-session "already read" bookmarkOne MCP process per session, all sharing the same folder.
Atomic writes (temp file +
rename) so readers never see a partial file.Consume-once: reading an inbox removes the message.
Event-driven via
fs.watch(with a slow safety poll), so delivery is effectively instant and there's no busy-polling.
Requirements
Node.js >= 18 (
node -v)Cursor (or another MCP-capable client) with MCP enabled
Optional — headless worker only: Cursor CLI (
cursor-agenton yourPATH)
All sessions that should talk to each other must use the same MCP_AGENT_BUS_DIR (same mailbox folder on disk).
Quick start (Cursor, ~5 minutes)
1. Clone and install
git clone https://github.com/therapietech/mcp-agent-bus.git
cd mcp-agent-bus
./scripts/setup.shsetup.sh runs npm install, creates a local bus/ mailbox under this repo, writes project-local .cursor/mcp.json, and copies the always-on rule to .cursor/rules/mcp-agent-bus.mdc.
Check the server starts (optional):
npm test2. Reload Cursor
Open this folder (
mcp-agent-bus) in Cursor, or complete Use with your own project below if you work in another repo.Cursor Settings → MCP — confirm
mcp-agent-busappears (green / enabled).If you do not see it: Command Palette → “Developer: Reload Window”, then check MCP again.
3. Give each session a name
Every Cursor window is one “session”. Pick a short handle per window, e.g. backend and reviewer.
Tell the agent once per window, for example:
“On the agent bus, my session name is backend. Use that for
from/meon bus tools.”
The rule in .cursor/rules/mcp-agent-bus.mdc reminds the agent to ask if the name is not set.
Important: use different names in each window. Do not run a headless worker and interactive bus_receive on the same name (they share one inbox).
4. Smoke test (two windows)
Use the same workspace (same .cursor/mcp.json and same MCP_AGENT_BUS_DIR) in both windows.
Window | Session name | Example prompt |
A |
| “Call |
B |
| “Call |
Window B should return the JSON message. Then B can reply with bus_send(to="sender", from="reviewer", ...).
Quick check in either window: bus_list_sessions() — after traffic, you should see inbox folders for active names.
5. Optional — autonomous worker (terminal)
For a session that runs tasks without you in the loop, in a plain terminal (not inside the agent):
cd /path/to/mcp-agent-bus # or your project with WORKER_CWD set
MCP_AGENT_BUS_DIR="/path/to/mcp-agent-bus/bus" \
WORKER_CWD="/path/to/your/project" \
node src/worker.mjs reviewer --model <your-model>Requires cursor-agent installed and logged in. The worker runs prompts with --force (auto-approves tool actions) — only accept tasks from senders you trust.
Use with your own project
Most people keep coding in their app repo, not inside mcp-agent-bus. Point MCP at the cloned server and use one shared mailbox path everywhere.
Clone
mcp-agent-busonce, e.g.~/tools/mcp-agent-bus, and runnpm installthere.In your project, merge into
.cursor/mcp.json(keep your existing servers):
{
"mcpServers": {
"mcp-agent-bus": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/mcp-agent-bus/src/server.mjs"],
"env": {
"MCP_AGENT_BUS_DIR": "/ABSOLUTE/PATH/TO/mcp-agent-bus/bus"
}
}
}
}Use absolute paths. Every window that should share the bus must use the same MCP_AGENT_BUS_DIR.
Copy the rule into your project:
cp /ABSOLUTE/PATH/TO/mcp-agent-bus/examples/mcp-agent-bus.mdc \
/ABSOLUTE/PATH/TO/your-project/.cursor/rules/Reload Cursor and run the smoke test with two windows on your project folder.
Global MCP (all projects)
Alternatively, put the same mcpServers.mcp-agent-bus block in ~/.cursor/mcp.json and copy mcp-agent-bus.mdc to a location Cursor loads globally (or paste the rule into your user rules). Same rule applies: one shared MCP_AGENT_BUS_DIR for all participating sessions.
Manual install (no setup script)
git clone https://github.com/therapietech/mcp-agent-bus.git
cd mcp-agent-bus
npm installRegister the server using examples/mcp.json.template (replace <ABSOLUTE_PATH_TO_REPO> with your checkout path), then reload your MCP client.
Troubleshooting
Problem | What to try |
MCP server missing in Cursor | Reload window; check |
Messages never arrive | Both windows must share the same |
| Wrong session name ( |
Worker does nothing | Install CLI: |
Permission errors on | Ensure the mailbox directory exists and is writable ( |
Run npm test in the clone to verify the mailbox logic on your machine (no Cursor required).
Tools
Tool | Purpose |
| Send a direct message to another session's inbox. |
| Fetch & consume your messages; optionally block until one arrives. |
| Look at your inbox without consuming. |
| Post an announcement visible to all sessions. |
| Read announcements newer than your last read. |
| List sessions that currently have an inbox. |
Message shape
{
"id": "1725183600000-a1b2c3d4",
"type": "direct",
"to": "backend",
"from": "frontend",
"subject": "handoff",
"text": "please run the end-to-end tests",
"ts": "2026-09-01T10:00:00.000Z"
}Two ways to receive work
Interactive (human in the loop): your active session calls
bus_receive, you see the task, it's done with normal tools, and you reply withbus_send.Autonomous (headless worker): run
src/worker.mjsin a plain terminal. It watches an inbox and, for each task, runs a fresh headless agent (cursor-agent -p) and replies automatically:
MCP_AGENT_BUS_DIR="$PWD/bus" WORKER_CWD="$PWD" \
node src/worker.mjs backend --model <your-model>Safety: the worker runs tasks with
cursor-agent -p ... --force(auto-approves shell/file actions). Only run it for senders you trust. The agent command is configurable via theAGENT_CMDenv var.
Monitoring workers (optional)
When the headless worker runs with cursor-agent --output-format stream-json, it appends per-task metrics under $MCP_AGENT_BUS_DIR/run/ (default: <repo>/bus/run/):
Script | What it shows |
Live token dashboard (input/output/cache, per worker + total) | |
Prompt quality (TTFT, hedging %, interpretation overhead) | |
Multiplexed logs for all workers (macOS-compatible) |
cd /path/to/mcp-agent-bus
./docs/watch-usage.sh
./docs/watch-clarity.sh
./docs/watch-workers.shOptional offline LLM judge for clarity scores: AGENT_BUS_HOME="$PWD" node docs/prompt-clarity.mjs
Paths accept both MCP_AGENT_BUS_DIR (this repo) and AGENT_BUS_DIR (legacy env name used in some setups).
Configuration
Env var | Default | Meaning |
|
| Where the mailbox lives. |
| — | Convenience: each session's own name. |
| current dir | Working directory the worker runs tasks in. |
|
| The agent CLI the worker invokes. |
Development
npm test # unit tests (node:test), no external services
npm run lint # optional; eslint (some optional docs scripts are excluded from CI)The core mailbox logic lives in src/mailbox.mjs and is
fully unit-tested in isolation; src/server.mjs is a thin MCP
wrapper around it.
Limitations
Single machine. It coordinates sessions on one host; it is not a cross-machine or team-wide bus.
One receiver per session name — don't run a headless worker and an interactive receive on the same name (they'd fight over the inbox).
Messages are consumed — for a durable record, pair the bus with a shared notes file.
License
Available Tools
6 toolsbus_broadcastBroadcast a message to all sessionsA
Post a message visible to every session via bus_read_broadcasts. Use for global announcements (e.g. "deploying now", "main is frozen").
Inputs: from (required), text (required).
bus_list_sessionsList sessions that have an inboxA
List known session names (those with an inbox directory).
Inputs: no named parameters.
bus_peekPeek inbox without consumingA
Return pending messages for your session WITHOUT removing them.
Inputs: me (required).
bus_read_broadcastsRead new broadcasts since you last checkedA
Return broadcasts newer than your last read, then advance your read cursor. Non-consuming for other sessions.
Inputs: me (required).
bus_receiveReceive messages (blocks until one arrives or timeout)A
Fetch and CONSUME pending messages for your session. If none are waiting and block=true, this blocks (event-driven) until a message arrives or timeout_ms elapses. Returns a JSON array of messages (may be empty on timeout).
Inputs: me (required), block, timeout_ms.
bus_sendSend a direct message to another sessionA
Send a message to a specific session inbox. The recipient sees it on their next bus_receive. Use for handoffs and requests between agent sessions.
Inputs: to (required), from (required), text (required), subject.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct operation on the message bus, and the send vs broadcast vs receive distinctions are well drawn. The only real overlap is bus_receive vs bus_peek, both returning pending messages for the caller's session; the consume-vs-non-consume wording disambiguates this well enough.
All six tools use a consistent bus_ prefix in snake_case with an action-oriented name. Minor deviations exist: bus_broadcast names the action while bus_read_broadcasts/bus_list_sessions pair verb+noun, but the pattern remains predictable.
Six tools is well-scoped for a message-bus server, with each tool earning its place (send, receive, peek, broadcast, read broadcasts, list sessions). No redundant or filler tools.
The surface covers the core pub/sub and point-to-point lifecycle: sending, consuming, peeking, broadcasting, reading broadcasts, and discovering sessions. Minor gaps remain (no explicit session registration/join or message deletion/ack), but agents can work around these.
Maintenance
Related MCP Connectors
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
One message board for your AI agents: read what's waiting, post, hand work over, claim jobs.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal inter-agent messaging for AI coding agents via filesystem relay.42MIT
- AlicenseNot gradedqualityCmaintenanceEnables real-time, file-based messaging between terminal AI agents (like Claude Code, Gemini CLI) allowing them to collaborate on tasks directly without a server or network, using JSON files and atomic rename for coordination.16 PyPIMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents on the same machine to exchange asynchronous messages as plain Markdown files, with optional wake-up notifications per agent.1AGPL 3.0
- AlicenseAqualityBmaintenanceEnables local, event-driven messaging between multiple AI coding-agent sessions on the same machine using only Node.js and the filesystem, allowing them to hand off tasks, exchange replies, and broadcast announcements without external infrastructure.6MIT