agent mcp bridge

Set up and use an MCP message broker for direct inter-agent communication between OpenClaw and other AI agents (e.g. hermes-agent, Claude Code, any MCP-capab...

Security Scan

The files and runtime instructions match the described purpose (a local MCP broker + filesystem fallback) and do not request unrelated credentials or install arbitrary third-party code from unknown URLs, though there are security considerations (no auth, plaintext messages, pip installs) you should review before running.

Purpose & Capability

The name/description (MCP bridge for inter-agent messaging) aligns with the included server and filesystem-bridge code: a FastMCP + SQLite broker and a Python filesystem fallback. The only minor mismatch is that the AgentBridge default SHARED_DIR is Path(__file__).parent while the SKILL.md suggests using ~/.openclaw/shared; this is an implementation choice, not a functional contradiction.

Instruction Scope

SKILL.md instructs the user to copy the server files, run start.sh (which creates a venv and installs deps), optionally register a user launchd job, and add a local URL to OpenClaw config. The instructions do not ask the agent to read unrelated system files or external secrets. Note: message data is stored as plaintext (SQLite and JSON files) and the filesystem fallback writes to user-visible directories — there is no built-in authentication or encryption.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but the included start.sh will create a virtualenv and pip-install requirements from PyPI (fastmcp, uvicorn, aiosqlite). This is a standard pattern but does entail network access to PyPI and execution of code you should audit before running.

Credentials

The skill declares no required environment variables, credentials, or config paths, and the code does not reference external secrets. The scope of access (local filesystem and a local TCP port) is appropriate for a local message broker.

Persistence & Privilege

always:false and default autonomous invocation are normal. The only persistence is user-level (virtualenv, SQLite DB, JSON files) and an optional per-user launchd plist. The skill does not attempt to modify other skills or system-wide privileged settings.

Assessment

This skill appears coherent with its purpose, but review and accept the security tradeoffs before installing: 1) There is no authentication or encryption — any local user/process with file or loopback access can read messages; keep the broker confined to a single trusted user or network namespace. 2) start.sh will pip-install packages from PyPI into a created venv — inspect requirements.txt and the code before running. 3) The filesystem bridge writes JSON files and the server creates messages.db in the server directory; ensure those directories have appropriate ownership and permissions. 4) If you enable auto-start (launchd), edit the plist paths carefully and avoid running as a privileged user. 5) Consider running the broker in an isolated environment (dedicated user, container, or VM) or adding authentication/transport restrictions if you plan to expose the service beyond localhost. 6) Note the small implementation detail: AgentBridge defaults to using the package directory as the shared directory — if you want inboxes under ~/.openclaw/shared, pass that path explicitly when instantiating AgentBridge.

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