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#

text

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#

bash

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)#

bash

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:

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#

ToolParametersReturnsUse whensend_message``from_agent, to, subject, body, reply_to?``{message_id, timestamp}Sending a task or replypoll_messages``agent_id, limit?list of message dictsChecking your inboxmark_read``message_id``{status}After processing a messagelist_agents—list of agent idsDiscovering who's active

Message format#

json

{
  "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.md for setup
• Inbox/outbox dirs: ~/.openclaw/shared/{agent}-inbox/

Heartbeat integration (OpenClaw)#

Add to HEARTBEAT.md to auto-process incoming messages:

text

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:

bash

# 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()