Agent MCP Bridge
A lightweight FastMCP + SQLite message broker that lets two AI agents communicate directly via MCP tools. Both agents connect to the same server as MCP clients — symmetric, no platform-specific adapters.
Architecture
Agent A (OpenClaw) MCP Broker Agent B (hermes-agent / any)
send_message() ──────► FastAPI+SQLite ◄────────── poll_messages()
poll_messages() ◄────── localhost:8765 ──────────► send_message()
Quick Setup
1. Install and start the broker
cp -r <skill-dir>/scripts/server/ ~/.openclaw/agent-bridge-mcp/
cd ~/.openclaw/agent-bridge-mcp
./start.sh # creates venv, installs deps, starts on port 8765
2. Register as a launchd service (macOS auto-start)
cp <skill-dir>/references/launchd-plist.md ~/Library/LaunchAgents/ai.openclaw.agent-bridge.plist
# Edit the plist to set correct paths, then:
launchctl load ~/Library/LaunchAgents/ai.openclaw.agent-bridge.plist
3. Add to OpenClaw config
Add to ~/.openclaw/openclaw.json:
{
"mcp": {
"servers": {
"agent-bridge": {
"url": "http://127.0.0.1:8765/mcp",
"transport": "streamable-http"
}
}
}
}
4. Connect the other agent
Give the other agent the MCP URL: http://127.0.0.1:8765/mcp (streamable-http transport). They connect with their native MCP client support.
MCP Tools
| Tool | Parameters | Returns | Use when |
|---|---|---|---|
send_message | from_agent, to, subject, body, reply_to? | {message_id, timestamp} | Sending a task or reply |
poll_messages | agent_id, limit? | list of message dicts | Checking your inbox |
mark_read | message_id | {status} | After processing a message |
list_agents | — | list of agent ids | Discovering who's active |
Message format
{
"id": "83223c09",
"from_agent": "hermes",
"to_agent": "isaac",
"subject": "Research request",
"body": "Please analyze...",
"timestamp": "2026-03-31T16:58:31Z",
"thread_id": "83223c09",
"reply_to": null,
"status": "pending"
}
Fallback: Filesystem bridge
If the MCP server is unavailable, use the filesystem bridge (zero infrastructure):
- See
references/filesystem-bridge.mdfor setup - Inbox/outbox dirs:
~/.openclaw/shared/{agent}-inbox/
Heartbeat integration (OpenClaw)
Add to HEARTBEAT.md to auto-process incoming messages:
Check ~/.openclaw/shared/isaac-inbox/ for new .json files.
If any exist: read, process, reply via hermes-inbox/, move to processed/.
Verification
Test the full loop:
# From Python
from agent_bridge import AgentBridge
bridge = AgentBridge("isaac")
bridge.send("hermes", "Handshake test", "Can you receive this?")
# Other agent polls and replies
msgs = bridge.receive()