mcp-coordinator
Stop your AI coding agents from overwriting each other's work.
One daemon. Every Claude Code / Cursor / Cline / Aider session on the same repo announces what it's about to touch, sees what the others are doing, and resolves conflicts before a line of code is written. Zero conflicts, everyone aligned.
Getting started · Problem · How It Works · MCP Tools · CLI · Auth · Dashboard · Config · FAQ → · Usage guide →
Who is this for
| You are… | mcp-coordinator gives you |
|---|
| A solo dev running 2-3 Claude Code sessions in parallel | Zero-config local daemon. Each session sees the others' file claims; no more "wait, Claude already rewrote that." |
| A small team where everyone runs their own AI agent on the same repo | One shared coordinator over LAN. Real-time conflict detection across teammates' agents. |
| Building a multi-agent orchestrator | A drop-in conflict layer with MQTT push, 26 MCP tools, and an SDK. Bring your own spawn strategy. |
| Self-hosting for a regulated org | OAuth 2.1, 4 IdPs, encrypted IdP tokens at rest, SHA-256 audit chain (SOC 2 tamper-evidence), per-org allowlists. |
The Problem
You ask Claude Code to "add an updated_at field to the User type." In another terminal, Cursor is mid-migration on the same schema. Twenty minutes later you're doing git surgery to reconcile the two diffs — and it's not the first time this week.
Specifically:
- Regressions — Agent A rewrites a module that Agent B was depending on
- Duplicated work — Two agents implement the same feature from different directions
- Architectural drift — Agents make local decisions that conflict with each other's designs
- Wasted reconciliation time — Hours per week untangling what the agents did to each other
Each agent works in isolation. None of them know what the others are doing.
mcp-coordinator fixes this by giving every agent a shared nervous system over MQTT — they announce intentions before coding, conflicts are detected before a single line is written, and agents see each other's actions in real-time to agree on an approach.
Works with or without an orchestrator. Standalone with any MCP client (Claude Code, Cursor, Cline, Aider) — see the usage guide. Or pair with essaim for pre-composed agent profiles, work-stealing templates, and a behavior catalog.
2500+ tests across 750+ files, passing on every release. Feature-flagged auth means Phase 1 deployments stay byte-identical to v0.7.x — proven by a 31-case backcompat suite that runs in CI.
Getting started
The fastest path for running a long-lived coordinator is a global install:
# 1. Install once, get the `mcp-coordinator` command on your PATH
npm install -g mcp-coordinator
# 2. First-time setup — creates ~/.mcp-coordinator/, writes a default config,
# and prints a .mcp.json snippet for your MCP client.
mcp-coordinator init
# 3. Start the server in the background
mcp-coordinator server start --daemon
# 4. Verify
mcp-coordinator server status
mcp-coordinator dashboard # opens http://localhost:3100/dashboard
Requires Node.js 22+ (Node 20 reached EOL on 2026-04-30 and is no longer supported). Step 2 is idempotent — re-running init won't overwrite an existing config. The snippet it prints goes into your MCP client's config (e.g., ~/.claude/.mcp.json for Claude Code). If you'd rather not copy-paste, run mcp-coordinator init --write-mcp-config <project-path> and the snippet is written to <project-path>/.mcp.json (merging if the file already exists).
After step 4, every Claude Code (or other MCP-compatible) session connected to this coordinator can call all 26 tools (register_agent, announce_work, post_to_thread, coordinator_status, ...). For the full multi-Claude or team setup, see the usage guide.
⚠️ Approving the tools: permissionMode: "acceptEdits" does not auto-approve MCP tools — it covers file edits and filesystem Bash commands only. Use allowedTools: ["mcp__coordinator__*"] instead, or you will get a prompt on every heartbeat. See approving the tools.
🔀 Two ways to consume coordination state — agents can either poll the daemon's MCP tools (default, works since v0.6) or accept push events through the Channels sidecar (v0.12+, research preview). Most users start with polling and add Channels later when they want real-time reactivity. See docs/operating-modes.md for the side-by-side comparison and decision guide.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
