agent-bus-mcp
This server provides a universal multi-agent communication bus over MCP and SQLite, letting agents exchange messages, manage inboxes, wait for incoming messages, and register identities.
Send messages to other agents (
bus_send) with optional topic, sender, and conversation ID; triggers the recipient's doorbell for immediate wakeup.Fetch inbox messages (
bus_inbox) for a specific agent, with filtering by unread status, marking as read, and configurable limits.Block and wait for incoming messages (
bus_wait_message) using long-polling, eliminating terminal polling.Query dialogue history (
bus_history) between two agents, with a configurable limit of recent messages.List active agents (
bus_list_agents) and their statuses on the bus.Register or update agents (
bus_register) with identity, framework, doorbell mechanism, and target.Persist all messages in SQLite with WAL mode, ACID transactions, and read/delivered status tracking.
Supports heterogeneous agents including Claude Code, OpenAI Codex, Google Antigravity, and DeepSeek Harness, plus a CLI for human or script interaction.
Enables Google Antigravity (Gemini) agents to participate in the multi-agent bus, exchange messages, and receive reactive task wakeups through the Antigravity driver.
Enables OpenAI Codex agents to participate in the multi-agent bus, exchange messages, and receive doorbell wakeups through the Codex integration.
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., "@agent-bus-mcp Send a message to coordinator asking for a code review"
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.
agent-bus-mcp π
Universal Multi-Agent Communication Bus & Doorbell Wakeup System
Connect Claude Code, OpenAI Codex, Google Antigravity, and DeepSeek Harness (DSH) over standard Model Context Protocol (MCP) and SQLite.
π Why agent-bus-mcp?
Modern AI agents often operate in isolated silos:
Claude Code runs in its own CLI or Chat UI;
Google Antigravity operates in terminal raw mode;
OpenAI Codex and DeepSeek Harness have separate runtimes.
Existing orchestration tools rely on fragile PTY keyboard simulation (frequently hanging on carriage returns), single-file overwrites, or lack autonomous push notification.
agent-bus-mcp solves this with a three-layer architecture:
Universal Addressing & Identity: Every agent registers a unique ID (
antigravity-lead,coordinator,deepseek-coder). Multiple instances never collide.Persistent Concurrency Engine: SQLite with Write-Ahead Logging (
WAL), ACID transactions, status tracking (unread -> delivered -> read), and complete audit history.Heterogeneous Doorbell Subsystem: Delivers sub-second (0.7s) reactive wakeups to sleeping agents without requiring manual human keystrokes.
Related MCP server: mcp-comms
π Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Heterogeneous Agents β
β Antigravity β Claude Code β DeepSeek / Codex β
ββββββββββββββββ¬βββββββββββββββββββ¬ββββββββββββββββββ¬ββββββββββ
β (Standard MCP Tools or CLI)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β agent-bus-mcp Server (JSON-RPC 2.0) β
β Tools: bus_send / bus_inbox / bus_history / bus_register β
ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β (ACID Transactions & Status Tracking)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β SQLite WAL Database (~/.agent-bus/bus.db) β
β - messages: message_id, from, to, topic, status, timestampsβ
β - agents: agent_id, framework, doorbell_type, last_seen β
ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β (Targeted Doorbell Wakeup)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Doorbell Drivers β
β - Antigravity Driver (Platform Reactive Task Wakeup) β
β - Claude Code Driver (API Chat Turn Injection) β
β - DSH / Unix Driver (FIFO Named Pipe / Socket Signals) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββπ Quickstart
1. One-Click Installation
Clone and run the installer:
git clone https://github.com/tulong66/agent-bus-mcp.git
cd agent-bus-mcp
./install.shThe installer automatically:
Sets up
~/.agent-bus/and initializes the SQLite WAL database;Installs the global
agent-busCLI to~/.local/bin/agent-bus;Auto-detects and injects MCP configuration into:
~/.claude.json(Claude Code)~/.gemini/config/mcp_config.json(Antigravity)~/.codex/config.json(Codex)~/.dsh/(DeepSeek Harness)
2. Verify Installation
agent-bus agentsOutput:
AGENT ID FRAMEWORK STATUS DOORBELL TARGET
--------------------------------------------------------------------------------
antigravity-lead antigravity active ~/.agent-bus/doorbells/antigravity-lead.bell
coordinator claude-code active ~/.agent-bus/doorbells/coordinator.bell
deepseek-coder dsh active ~/.agent-bus/doorbells/deepseek-coder.bell
codex-lead codex active ~/.agent-bus/doorbells/codex-lead.bellπ οΈ MCP Tools Reference
When connected via MCP, any agent can call these standard tools:
Tool | Description | Key Arguments |
| Send a message to an agent & ring its doorbell |
|
| Fetch unread messages from SQLite |
|
| Query dialogue history between two agents |
|
| List all active agents on the bus | (none) |
| Register identity & doorbell configuration |
|
π» CLI Usage
Humans, background scripts, or agents using bash can interact via agent-bus:
# Send a message to an agent
agent-bus send --to coordinator --from antigravity-lead --topic review "Please inspect PR #12"
# View inbox for an agent
agent-bus inbox --agent coordinator
# View conversation history
agent-bus history antigravity-lead coordinator
# Block and listen for incoming doorbell
agent-bus listen --agent antigravity-lead --timeout 300π Guides for Specific Frameworks
π§ͺ Testing
Install the test runner once, then run the suite:
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest tests/ -vπ License
MIT License. Feel free to use in personal, academic, or commercial multi-agent systems.
Available Tools
6 toolsbus_historyA
Query chronological dialogue history between two agents from SQLite storage.
Inputs: agent_a (required), agent_b (required), limit.
bus_inboxA
Fetch incoming messages for a specific agent from the persistent SQLite inbox. Supports optional blocking wait.
Inputs: agent_name (required), wait, limit, timeout, +2 more.
bus_list_agentsA
List all active registered agents and their statuses on the universal communication bus.
Inputs: no named parameters.
bus_registerB
Register or update an agent's identity and doorbell configuration on the bus.
Inputs: agent_id (required), framework, doorbell_type, doorbell_target.
bus_sendA
Send a message to another agent on the universal agent bus. Persists to SQLite and triggers the recipient's doorbell for immediate wakeup.
Inputs: to (required), content (required), topic, from_agent, +1 more.
bus_wait_messageA
Long-poll and wait for an incoming message on the bus. Blocks until a message arrives or timeout expires. Eliminates terminal polling.
Inputs: agent_name (required), timeout, mark_read.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 6 tools
Most tools have clear, distinct purposes, but bus_inbox and bus_wait_message overlap heavily: both retrieve incoming messages and support blocking behavior. This creates potential confusion about which to use for waiting versus fetching.
All tools share a consistent bus_ prefix, but the naming patterns after the prefix are mixed: verbs (send, register), nouns (inbox, history), and verb-object phrases (wait_message, list_agents). This reduces predictability compared to a unified verb_noun convention.
Six tools is a reasonable size for an agent messaging bus, covering send, receive, polling, history, registration, and agent discovery. The slight redundancy between bus_inbox and bus_wait_message means one could potentially be removed, but the count is still well-scoped.
The toolset covers the core bus lifecycle: register agents, send and receive messages, wait for messages, view history, and list agents. Minor gaps exist, such as no explicit deregister/unregister operation or message acknowledgment mechanism, but these are not critical for basic bus functionality.
Maintenance
Related MCP Connectors
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Durable addresses and crash-safe FIFO mailboxes so AI agents message each other, free.
Lasting public addresses and threaded messages between AI agents, across apps and machines.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA SQLite-backed message queue system that enables multiple AI agents to communicate with each other via a simple HTTP interface.4Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables multiple AI agents to communicate and coordinate via a shared SQLite-backed message log, supporting directed messages, broadcasts, and session discovery.-
- AlicenseAqualityBmaintenanceEnables local AI coding agents to message each other on one machine using a durable SQLite mailbox and live-ask tools.93MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to exchange structured work items with an auditable lifecycle, supporting send, acknowledge, block, complete, and cancel operations via a shared SQLite-backed inbox.51 npm2Apache 2.0