agent-mesh

agent-mesh

A central, event-driven messaging hub for AI agents, exposed as an MCP server.

One small Docker container runs the hub. Every agent (Claude Code instance, script, daemon) connects to it over MCP by URL only — no install, no local process. Messages are pushed the instant they arrive: an agent that waits for a message holds one open call that resolves on delivery, like a socket read. No polling.

            +-----------------------------+
            |  Docker container (hub)      |
            |  agent-mesh serve --http     |
            |  MCP over HTTP/SSE  :8765    |
            |  per-agent inbox queue       |
            |  push on arrival (no poll)   |
            +-------------+---------------+
            127.0.0.1:8765 |  (localhost only)
        +------------------+------------------+
     Claude #1          Claude #2          script/daemon
   (MCP url config)   (MCP url config)   (MCP url config)

Setup

The host machine runs the hub once; agents just point at it.

1 - Run the hub (one machine)

git clone https://github.com/NG-Bullseye/agent-mesh.git
cd agent-mesh
docker compose up -d --build
curl -s http://localhost:8765/health   # {"ok": true, "agents": 0}

The container binds to 127.0.0.1:8765 - reachable from this machine only.

2 - Connect an agent (no install)

Add to the Claude Code MCP config (~/.claude/settings.json); merge under mcpServers, keep existing keys:

{
  "mcpServers": {
    "agent-mesh": { "url": "http://localhost:8765/sse" }
  }
}

That's it. The agent now has the mesh tools. For a fully scripted setup (including the global CLAUDE.md note), paste SETUP_PROMPT.md into a Claude Code session.

MCP tools

| Tool | Description | |------|-------------| | mesh_register | Connect this agent to the hub (name, role) | | mesh_send | Send a message (to, message, from_agent, optional private) - delivered instantly if the target is listening | | mesh_listen | Block until one DIRECT message arrives (name, timeout_s) - event-driven, no polling | | mesh_ping | Liveness check for an agent (agent) | | mesh_who | List all live agents | | mesh_request | Send a request and block for the reply (to, message, from_agent, timeout_s) | | mesh_reply | Reply to a request (nonce, text) - resolves the requester's pending call | | mesh_pending | List an agent's outstanding requests (name) |

Session-Init pattern

At the start of a session that joins the mesh:

1. mesh_register with a name + role.
2. To receive messages, call mesh_listen - it blocks until something arrives,

so the agent reacts on delivery instead of polling.

Request/reply

mesh_request sends and blocks on a reply Future. The receiving agent sees the message via mesh_listen with a reply_to nonce, then calls mesh_reply with that nonce - the requester's call resolves immediately.

How it works

The hub is a single asyncio process. Each registered agent has an in-memory asyncio.Queue as its inbox. mesh_send drops an item into the target's queue; a waiting mesh_listen is parked on queue.get() and wakes the moment the item lands. There is no broker, no database, no polling loop - state lives in the hub process for as long as it runs.

Group broadcasts (non-private sends) are fanned out to every other agent's inbox as scope: "group" items. A fixed-window rate gate limits direct sends per sender->target; over-limit sends are denied only when AGENT_MESH_GATE_ENFORCE=1.

State is intentionally ephemeral: restarting the container clears inboxes and the registry, like restarting a switch. This keeps the hub a single, dependency-free artifact. Scope is one host (localhost bind); a networked multi-machine mesh would add auth and is out of scope here.

Endpoints

| Path | Purpose | |------|---------| | /sse | MCP transport (point agents here) | | /health | {"ok": true, "agents": N} | | /agents | JSON list of live agents |

Config env vars

| Variable | Default | Description | |----------|---------|-------------| | AGENT_MESH_GATE_ENFORCE | 0 | Set to 1 to hard-deny over-rate sends | | AGENT_MESH_GATE_LIMIT | 40 | Max direct sends per sender->target per 10s window |

Running without Docker

pip install .
agent-mesh serve --http --port 8765   # or `serve` for stdio
agent-mesh health                      # check a running hub

License

MIT - see LICENSE.