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

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.md for 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()