Zero conflicts. Every agent aligned.
5 agents, 1 codebase, 0 merge conflicts. The MCP server that keeps parallel Claude Code, Cursor, and Cline agents aligned.
The coordination pain
Parallel agents without shared awareness produce three failure modes that ship to production.
Silent regressions
Tuesday 3pm. Alice's agent ships User.updated_at. Four minutes later, Bob's agent renames User.id. Tests pass. Prod breaks at 2am because the migration order was wrong.
Duplicated effort
Two agents both implement retry logic. Agent A picks exponential backoff (250ms→8s). Agent B picks linear (500ms, 5 retries). Code review surfaces the divergence — 800k tokens in.
No visibility
Tom asks his agent: “is anyone else working on auth?” The agent answers: “I have no way to know.” Tom shrugs and proceeds. Carol's agent did the same thing 20 minutes ago.
See it run live
Four agents stay aligned in real time without chat tools, merge gymnastics, or shared spreadsheets.
Conflicts caught before code is written
Every announcement reaches every concerned agent before they open a file. Overlaps surface as a paused turn, not a midnight rollback.
How it works
Four steps run before any code is written, then a score decides who consults.
Announce
The agent declares intent: task, target files, affected modules. No code yet.
Detect
The scorer checks every active announcement across six layers and returns a 0-to-100 impact score.
Consult
The coordinator opens a consultation thread and publishes it to the MQTT broker. Each concerned agent reads the event between turns and posts context, constraints, or a resolution. No sidecar process required.
Resolve
Proposals are approved, contested, or re-proposed. The thread closes on consensus. Every decision lands on the dashboard timeline.
Impact score
Every announcement is scored 0 to 100 against active work. The score decides the response.
Six layers, most severe wins. Full details on GitHub →
In-flight awarenessv0.5
Hook-based PreToolUse + PostToolUse hooks let the coordinator see agents start editing files — not just when they finish. Conflicts surface before bytes are written, not after.
Symbol-aware scoringv0.3+
tree-sitter parses 15 languages (TS/TSX/JS/JSX/Python/Go/Rust/Java/C#/C/C++/Ruby/PHP/Kotlin/Swift/Bash). Two agents editing the same file but different functions get an annotated reason — not a silent block.
Git co-change scoringv0.5
Files that move together in git history (config + consumer, fixture + test) are scored as related: impact 60 if >50% co-change, 40 if >20%. Catches regressions invisible to filename matching.
Real-time push: MQTT topics and delivery flow
An embedded MQTT broker fans every event to subscribers. Eight topics, end-to-end latency under 50ms.
| Topic | Emitted when | Key payload |
|---|---|---|
coordinator/consultations/new |
A thread is opened | thread_id, subject, initiator_id, target_files |
.../consultations/+/messages |
Someone posts to a thread | agent_id, name, content, type |
.../consultations/+/status |
Thread transitions state | status: open/resolving/resolved/timeout |
.../consultations/+/claimed |
Work-stealing claim (atomic) | claimed_by, thread_id |
.../consultations/+/completed |
Claimed task finishes | agent_id, thread_id, resolution |
coordinator/agents/+/status |
Agent online / offline | status, name, modules |
coordinator/broadcast |
System-wide announcement | arbitrary JSON |
coordinator/quota/update |
Anthropic quota refresh | usage, limit, utilization_pct |
Push delivery flow
Coordination patterns
Four coordination shapes the protocol supports natively. Build them with the 26 MCP tools.
All agents start at once. The coordinator opens a consultation thread the moment two announcements overlap.
[A] [B] [C] [D] | | | | A & C overlap on types.ts → consultation
Agents work in declared order. Each one consumes the prior agent's output before announcing its own work.
[A] → [B] → [C] spec code test handoff between turns
A lead agent splits the mission and dispatches subtasks. Subordinates announce work, consult, and report back.
[lead] / | \ [A] [B] [C] ↑ ↑ ↑ report results
Observer agents watch the timeline. They post warnings or comments without ever announcing their own work.
[A] [B] [C] | | | [obs] reads timeline → posts comment or warning
Wire these patterns yourself via mcp-coordinator's 26 MCP tools — or skip the boilerplate with essaim's pre-built catalog. See essaim's catalog →
Why not alternatives?
Worktrees, lockfiles, CI, orchestrators — none of them know your agent's intent.
…git worktrees?
No. Worktrees isolate filesystems. mcp-coordinator coordinates intent. A clean merge of two incompatible designs still ships a broken runtime. Use both.
…Claude Code subagents?
Subagents coordinate inside one Claude Code session. mcp-coordinator coordinates any MCP client across any session, machine, or vendor. Cursor and Claude Code on different laptops can share one consultation thread.
…Slack and manual coordination?
Slack works because humans read it. Your agent doesn't. mcp-coordinator lets the agent itself ask "is anyone touching this file?" before writing — at a cost of a few milliseconds.
…CI gates and branch protection?
CI catches the conflict after both agents have already burned tokens writing incompatible code. mcp-coordinator catches it before a single line is written. CI is the safety net; this is the harness.
…multi-agent orchestrators?
Orchestrators run agents; mcp-coordinator is the protocol they speak. essaim composes with mcp-coordinator natively. AutoGen and CrewAI ship without conflict detection — pair them with mcp-coordinator and they stop colliding.
npm install -g mcp-coordinator
Install in one command
Architecture & deployment
One agent-loop per developer, one coordinator serving MCP, MQTT, and the dashboard, same shape from laptop to cloud.
The shape of a coordinated session
agent-loop
MCP + MQTT + SSE
agent-loop
TCP 1883 / WS /mqtt
SSE events :3100/dashboard
Agent-loop
A programmatic loop wrapping the Claude CLI (spawn-per-turn claude -p --resume). Holds the MQTT listener, the protocol state machine, and the work-stealing claim logic. Use essaim's loop, or roll your own.
mcp-coordinator server
A Node.js process exposing 26 MCP tools over HTTP/SSE, with the embedded Aedes MQTT broker. SQLite stores threads, agents, and the dependency map. Anthropic quota is pre-flighted before multi-agent runs.
Dashboard
A live SSE stream at localhost:3100/dashboard. Per-agent activity, scoring breakdown, quota widget, decision timeline, and the v0.5 "Conflict signals" panel showing per-layer firing counts over the last 24 h. No auth in local mode; JWT-gated for cloud.
Three modes, one experience
Local mode
The coordinator, broker, and dashboard run on your machine. Best for solo work or trying mcp-coordinator before bringing teammates in.
agent-loop
:3100
Aedes · :1883 / /mqtt
:3100/dashboard
mcp-coordinator server start --daemonTeam server
One coordinator on a shared LAN machine. Every developer's agent-loop connects to the same instance. Every announcement, every consultation, visible to the whole team.
agent-loop
coordinator :3100
MQTT :1883 / /mqtt
dashboard /dashboard
agent-loop
agent-loop
mcp-coordinator init ~/project --url http://192.168.x.x:3100 --name "Alice"Cloud hosted
Self-hosted on a VM or container. Remote teams coordinate through one TLS endpoint, with WebSocket MQTT on port 443. JWT-gated.
agent-loop
coordinator + Aedes
WS /mqtt on 443
TLS + JWT auth
agent-loop
agent-loop
mcp-coordinator init ~/project --name "Alice" --url https://coordinator.team.comGet started
Self-hosted from one npm package — embedded broker and dashboard, no cloud, ready in under a minute.
Install
One npm package. The -g flag adds the mcp-coordinator command to your PATH. No separate broker, no database to provision.
First-time setup
Creates the config directory, writes a default config.json, and prints the .mcp.json snippet for your MCP client (Claude Code, Cursor, Cline). Add --write-mcp-config <path> to merge the snippet straight into a project's .mcp.json.
Start the server
Boots the MCP server, embedded MQTT broker, and dashboard on localhost:3100. --daemon backgrounds the process and writes logs to the config directory.
Verify and open
The doctor command checks config, server, MCP responses, and MQTT connections, then opens the dashboard at localhost:3100/dashboard.
Prefer Docker? Pull the multi-arch image instead: docker pull ghcr.io/swoofer/mcp-coordinator:0.13.0. A working compose stack with Caddy auto-TLS ships at examples/docker-compose/.
Want real-time push instead of polling? Add the Channels sidecar (v0.12+ research preview) so coordination events arrive as <channel> tags in your Claude Code session between turns. See the polling-vs-push decision guide and the channels-quickstart example.
git worktree add ../feature-x main and run each agent in its own worktree — mcp-coordinator handles "who's editing types.ts"; worktrees handle "no two agents fighting the same inode."
What you'll see in 60 seconds
Tested coordination scenarios
Four canonical conflict patterns, each run end-to-end with two real agents to verify score, thread state, and resolution.
| Scenario | Description | Score | Outcome |
|---|---|---|---|
| S1 | Two agents announce work on the same file at the same moment | 100 | Consultation thread opens, both agents post context, consensus reached, both proceed |
| S2 | Two agents announce work inside the same feature module | 30 | Auto-resolved, both agents notified for awareness |
| S3 | Agent A's module depends on Agent B's current output | 80 | Dependency flagged, dependent agent waits or replans |
| S4 | Fully independent tasks, no shared files or modules | 0 | No conflict detected, both agents proceed in parallel |
Enterprise & Compliance
Built for compliance from the foundation up. v0.11.0 ships full Phase 2 OAuth 2.1, multi-IdP SSO, and SHA-256 audit log tamper-evidence — the capabilities regulated-industry and SOC 2 Type II deployments actually need to assemble an audit dossier.
| Capability | Status | Aligned with |
|---|---|---|
Multi-tenant org_id isolation across 14 tables |
Shipped v0.7 | SOC 2 CC6.1 · GDPR Art. 32 |
| OAuth 2.1 + RFC 8628 device flow + cookie sessions + service tokens (Phase 2) | Shipped v0.8 | SOC 2 CC6.1 · CC6.6 · CC6.7 |
| Multi-IdP SSO — GitHub OAuth App + GitHub App + Google + generic OIDC | Shipped v0.9 → v0.10 | SOC 2 CC6.1 · centralized identity |
| Audit log table (append-only data layer) + 35 event types Tier 1/Tier 2 | Shipped v0.7 → v0.8 | SOC 2 CC7.2 · CC7.3 |
SHA-256 hash chain on every audit_log row (tamper-evidence) |
Shipped v0.9.1 | SOC 2 Type II · CC7.3 |
JWT — HS256 pin · RFC 6750 · zero-downtime rotation + rotate-jwt-secret CLI |
Shipped v0.7 → v0.9.2 | SOC 2 CC6.1 |
OIDC id_token RS256 signature + iss + aud + nonce verification |
Shipped v0.9 → v0.10.1 | OIDC Core 1.0 §3.1.2.1 |
EncryptionProvider interface (passthrough default) |
Shipped v0.7 | Hook for envelope encryption |
Encryption-at-rest for idp_*_token + SQLCipher whole-DB |
Planned v0.10.x | SOC 2 CC6.1 |
| Per-org DEK + BYOK (AWS KMS / GCP KMS / Vault) | Future | Regulated industries |
GDPR /export & /delete endpoints + Art. 17 procedures |
Procedures shipped · endpoints future | GDPR Art. 15 · 17 · 20 |
| Retention policies + audit log surface UI | Sweeper shipped · UI future | SOC 2 · GDPR minimization |
mcp-coordinator is not SOC 2 certified — certification is auditor work, not code. We ship the architectural hooks (multi-tenant isolation, audit log, encryption interface) so teams pursuing audits get a head start, but the certification itself is your team's process.
FAQ
Quick answers to common questions about coordination, deployment, and integration.
Does this replace git worktrees?
Is it production-ready?
doctor command, structured Pino logs.What does it cost?
Which MCP clients work?
Can multiple repos share one coordinator?
Is auth or JWT required?
How is this different from Aider or Cline's own coordination?
Yet another tool to maintain?
npm install -g, or pull the published image ghcr.io/swoofer/mcp-coordinator:0.13.0 if you prefer Docker. Embedded MQTT broker, SQLite, and dashboard ship in the package. Zero sidecar. Symmetric uninstall reverses the init actions; --purge wipes the data dir.What if the coordinator goes down?
Will my agent lose context between turns?
Which programming languages does conflict detection support?
How does conflict detection work under the hood?
Roadmap
Shipped, in flight, and what comes after.
v0.1 — Server extraction
26 MCP tools, embedded Aedes broker, SQLite state, real-time dashboard. Standalone npm package.
v0.2 — Standalone autonomy
First-run init, doctor diagnostics, daemon log tailing via server logs, symmetric uninstall. Vanilla MCP clients (Claude Code, Cursor, Cline) coordinate via polling out of the box. essaim's agent-loop adds push.
v0.3 — Semantic conflict detection
AST-level analysis on top of filename scoring via tree-sitter. Detects API contract changes and interface incompatibilities before a thread opens. Symbol-aware scoring: same file, different functions = annotated reason, not a silent block. 15 languages supported (TS/TSX/JS/JSX/Python/Go/Rust/Java/C#/C/C++/Ruby/PHP/Kotlin/Swift).
v0.4 — Dashboard redesign & operability
Full landing page and dashboard redesign. New "Conflict signals" panel with per-layer firing counts over the last 24 h. Extended /readyz with tree_sitter and git_cochange health blocks. 5 new Prometheus metrics, 8 new env vars / CLI flags, PRAGMA user_version downgrade guard, and 413 body-size cap.
v0.5 — In-flight awareness & git co-change
Hook-based PreToolUse + PostToolUse: the coordinator sees agents start editing, not just finish. Git co-change scoring: files that share commit history (config + consumer, fixture + test) get impact score 60 if >50% co-change, 40 if >20%.
v0.6 — Semantic conflict detection & 15-language symbol parsing
Tree-sitter symbol extraction extended to 15 languages (added Bash, C#, C, C++, Ruby, PHP, Kotlin, Swift). Layer 4 git co-change scoring detects historical co-edit patterns. /api/working-files/{start,stop} lets agents signal in-progress edits for real-time conflict detection.
v0.7 — Multi-tenant security foundation
Organization scoping (org_id) baked into 14 tables and every MCP/HTTP/MQTT/SSE call. JWT hardened with HS256 pin, RFC 6750 WWW-Authenticate headers, and zero-downtime secret rotation via COORDINATOR_JWT_PREV_SECRET. audit_log table, EncryptionProvider interface, and IdPProvider interface ship as hooks for Phase 2 OAuth, multi-IdP, and encryption-at-rest.
v0.8 — Phase 2 OAuth 2.1 + device flow
Full OAuth 2.1 + RFC 8628 device flow + cookie sessions (__Host-coordinator_session) + service tokens for CI/CD + refresh-token rotation with stolen-token detection (10s grace window, family revoke on reuse) + two-tier audit pipeline (Tier 1 sync never-drop + Tier 2 async batched) + 29 Prometheus metrics on /metrics/auth. Feature-flagged behind COORDINATOR_OAUTH_ENABLED=true; Phase 1 deployments byte-identical when unset.
v0.9 — Multi-IdP + audit chain + rotation tooling
First-class GoogleProvider (id_token verification via jose + JWKS) and generic OIDCProvider (auto-discovery via /.well-known/openid-configuration for Okta / Auth0 / Azure AD / Keycloak / Authentik). Picker UI on /auth/login when 2+ providers are registered. SHA-256 hash chain on every audit_log row (SOC 2 Type II tamper-evidence) + verify-audit-chain.ts operator script. mcp-coordinator rotate-jwt-secret CLI helper with systemd-timer + Kubernetes CronJob automation patterns.
v0.10 — GitHub App + OIDC defense-in-depth + per-provider allowlist strategies
First-class GitHubAppProvider sibling to the OAuth App, with auto-refresh of 8h user-to-server tokens via refreshIdpToken. OIDC nonce claim verification (Core 1.0 §3.1.2.1) guards against id_token replay. Four allowlist strategies — memberships / idp_org_id / id_token_groups / none — auto-selected per provider so Google Workspace deploys off the hd claim, OIDC off configurable groups path, GitHub App off either user orgs or installation footprint. 1740 tests across 119 passing files.
LLM Reasoner — gray-zone arbitration (opt-in)
A gated, opt-in layer that sends ambiguous gray-zone conflicts to a small LLM for structured arbitration. Design phase — will ship after one month of v0.5.0 telemetry confirms the ROI justifies the latency trade-off.
Encryption-at-rest for IdP tokens
Envelope encryption for users.idp_access_token and users.idp_refresh_token. Master key via COORDINATOR_ENCRYPTION_KEY; per-row DEK derived via HKDF. Shipped in v0.10.5 with column-level rotation support and a self-healing decrypt path for graceful key migration.
v0.11 — pnpm migration + official Docker image
Tooling stack moved from npm to pnpm (Corepack-managed) for faster, deterministic installs and a stricter dep tree. Official multi-arch Docker image now published to GitHub Container Registry (ghcr.io/swoofer/mcp-coordinator) on every release tag with provenance and SBOM attestation. server status exit code now reflects daemon health for clean shell scripting. FK constraints added on coordinator tables to prevent orphan rows on org delete. 5 npm-audit findings cleared (uuid, qs).
v0.12 — Channels Phase 1 (push) + stdio fixes
Push-based delivery via Claude Code Channels: a new mcp-coordinator channel stdio process subscribes to the embedded MQTT broker and surfaces consultation events, agent-status changes, and conflicts as notifications/claude/channel directly into Claude Code — no polling, no sidecar subscriber. Stdio-mode tool calls fixed (no more spurious “MCP tool requires a session” errors). New MCP SDK integration test harness exercises a real client + server end-to-end.
v0.13 — Channels Phase 2 reply tool + chained Docker publish
Channels become bidirectional: a new post_to_thread tool lets a Claude Code session reply directly into a consultation thread over MQTT. CI: the chained release.yml → docker-publish.yml workflow_call now auto-publishes the multi-arch image to GHCR on every release tag without manual dispatch (root-cause was gating on the wrong event field). New operating-modes (polling vs push) guide spells out the choice; list_threads status enum corrected for external integrators.
v1.0 — Stable API + cross-repo coordination
Frozen public API, versioned REST endpoints, migration guides. Coordination across multiple repositories from a single MQTT broker. Phase 5 multi-instance via Redis pub/sub for membership cache invalidation + token_epoch reads + rate-limit + sweeper leader election.