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.

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

Tool	Description
send_message(to, content)	Send a directed message to a named session
broadcast(content)	Message all other sessions
read_messages(limit, unread_only)	Check inbox (marks messages as read)
list_sessions()	Discover other agents
check_unread_count()	Lightweight unread count (doesn't mark as read)
get_conversation(with_session, limit)	Bidirectional history with another agent
read_all_messages(limit)	Global message log (doesn't mark as read)

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