mcp-comms

MCP server for multi-agent communication. Multiple AI agents (Claude Code, Codex, etc.) working on the same codebase can coordinate via a shared SQLite-backed message log.

How it works

Each agent spawns its own server.py process over STDIO. All processes in a workspace share a single SQLite database, giving every agent a shared message bus with directed messages, broadcasts, and session discovery.

Agent A (claude-1) ──spawns──> server.py --name claude-1 ──┐
Agent B (codex-1)  ──spawns──> server.py --name codex-1  ──┼──> <workspace>/.agent-comms/comms.db
Agent C (codex-2)  ──spawns──> server.py --name codex-2  ──┘

The DB path defaults to .agent-comms/comms.db relative to CWD, so each project gets its own message log.

Related MCP server: Brain MCP

Setup

Requires uv. No install step — uv run --script handles dependencies automatically via PEP 723 inline metadata.

Claude Code

Add to .mcp.json in your project:

{
  "mcpServers": {
    "comms": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/mcp-comms/server.py", "--name", "claude-1"]
    }
  }
}

Codex

Add to .codex/config.toml in your project:

[mcp_servers.comms]
command = "uv"
args = ["run", "--script", "/path/to/mcp-comms/server.py", "--name", "codex-1"]

Replace /path/to/mcp-comms with the actual path where you cloned this repo. Give each agent a unique --name.

MCP Tools

CLI Options

uv run --script server.py --name <session-name> [--db-path <path>]

• --name (required): unique session name for this agent

• --db-path (optional): path to SQLite database (default: .agent-comms/comms.db)

Running Tests

uv run pytest tests/

Design Notes

• SQLite WAL mode for concurrent reads/writes across multiple agent processes

• Thread-safe connections via threading.local()

• Heartbeat tracking — every tool call updates last_heartbeat, so agents can detect stale sessions

• Read tracking — messages are marked read per-session via a JSON array, so each agent gets its own unread state

• Broadcasts reach everyone except the sender

• send_message fails fast with a helpful error listing known sessions if the target doesn't exist

• Delete .agent-comms/comms.db to reset all state