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

Related MCP server: agentsync

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 20+ (Node 22+ recommended — Node 20 reaches EOL on 2026-04-30). 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.

🔀 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.

Other install styles

† Local installs require a package.json in the working directory — if you're just trying it out, prefer -g or npx.

Installation légère (skip tree-sitter grammars)

The tree-sitter code-extraction feature ships ~292 MB of grammar packages as optionalDependencies. If you don't need cross-repo code extraction, skip them: npm install mcp-coordinator --omit=optional (pnpm equivalent: pnpm install --no-optional). The rest of the coordinator — agent registry, consultation threads, MQTT, dashboard — works unaffected; only the tree-sitter-backed extraction gracefully degrades.

Running via Docker

The image is published to GitHub Container Registry on every release tag — multi-arch (linux/amd64 + linux/arm64), with provenance and SBOM attestation. Three tag tracks:

A working compose stack (coordinator + Caddy auto-TLS + GitHub OAuth) ships at examples/docker-compose/. For a Kubernetes CronJob example doing JWT secret rotation, see docs/ops/auto-rotation.md.

Real-time push via Claude Code Channels (research preview)

Channels is Anthropic's new push-into-session primitive: an out-of-band subprocess streams <channel> tags into a running Claude Code session, so the agent reacts to coordination events the moment they happen — no polling, no extra tool call. mcp-coordinator channel is a thin bridge over the embedded MQTT broker that emits one channel event per consultation, agent status change, and thread message. It also exposes a post_to_thread MCP tool so Claude can reply into a thread directly from the session.

# 1. Daemon already running? Add the channel server to ~/.claude/.mcp.json
#    (see examples/channels-quickstart/.mcp.json.sample)
# 2. Launch Claude Code with channels enabled
claude --dangerously-load-development-channels server:mcp-coordinator-channel
# 3. Watch consultation events arrive as <channel> tags in the session, and
#    let Claude reply via post_to_thread when appropriate

Research preview — requires --dangerously-load-development-channels in a Channels-capable Claude Code (v2.1.80+). Phase 3 (permission relay) intentionally deferred.

📖 Choosing between polling and push? See docs/operating-modes.md for a full comparison of the two modes, when to pick each, and how to run them side by side. Full setup walkthrough at examples/channels-quickstart/.

How It Works

   Agent A                          Agent B
     │                                │
     │  announce_work                 │  announce_work
     ▼                                ▼
┌──────────────┐                ┌──────────────┐
│  MCP client  │ ◄── MQTT ────► │  MCP client  │
│ (any vendor) │   push-based   │ (any vendor) │
└──────┬───────┘                └──────┬───────┘
       │         MCP HTTP / SSE        │
       └──────────────┬────────────────┘
                      │
            ┌─────────▼──────────┐
            │   mcp-coordinator  │
            │  26 MCP tools + DB │
            │  Aedes MQTT broker │
            └─────────┬──────────┘
                      │ SSE
            ┌─────────▼──────────┐
            │     Dashboard      │
            │  live events/quota │
            └────────────────────┘

The consultation cycle has four steps:

1. Announce — A client calls announce_work with target files, depends_on_files, and target modules before coding.

2. Detect — The coordinator scores impact against all online agents and opens a thread if a score ≥ 90 matches.

3. Consult — MQTT pushes the new thread to every affected agent. Each agent posts context, constraints, or proposes a resolution.

4. Resolve — Agents approve, contest, or propose again. The thread closes when consensus is reached, or auto-resolves after timeout / in gray zones.

The server is client-agnostic: any MCP-compatible agent (Claude Code, Cursor, Cline, Aider, custom scripts) can connect over HTTP/SSE or stdio.

MQTT layer

The coordinator ships with an embedded Aedes MQTT broker. Agents subscribe once and receive every coordination event in real-time — no polling, no extra infrastructure.

Topic map: coordinator/consultations/new, coordinator/consultations/{id}/{messages,status,claimed,completed}, coordinator/agents/{id}/status, coordinator/broadcast, coordinator/quota/update. Clients self-filter their own messages and the payloads are small JSON envelopes.

Impact Scoring

Every announce_work call scores all online agents across multiple detection layers. The highest matching layer wins.

Scores are categorized into three outcomes:

Layer 0 is critical. Without announced intentions, a two-agent scenario where both work in src/auth/ would score only 30 (gray zone, auto-resolved). With announce_work, the same scenario scores 100 and triggers a full consultation.

announce_work accepts an optional target_symbols?: string[] (up to 200 entries, max 256 chars each). When two agents touch the same file with disjoint symbols, the score stays 100 but the reason text enriches with disjoint symbols: you=[X], them=[Y] — tree-sitter extracts symbols server-side from 15 languages (TS, JS, Python, Go, Rust, Java, C#, C/C++, Ruby, PHP, Kotlin, Swift, Bash) via optionalDependencies.

Capabilities at a glance

Out of the box, zero config:

• Run the coordinator — mcp-coordinator server start, that's the whole setup

• Conflict detection — 4-layer impact scoring (announce / file / module / co-change), MQTT push delivery

• Dashboard — live timeline, agent panel, scoring breakdown, quota widget

• Observability — structured Pino logs, MQTT broker stats, /livez + /readyz + /metrics

Full version-by-version detail in CHANGELOG.md.

MCP Tools

26 tools registered under one HTTP/SSE transport at /mcp (and stdio for stdio-mode clients). The three you'll reach for 90% of the time:

Any MCP client can discover the full tool schema at runtime via the standard tools/list MCP protocol call — no dedicated introspection tool needed.

Agent registry

Consultation

File tracking

Dependency map

MQTT

Status

CLI

Quick start

# Start the coordinator (embedded MQTT + dashboard)
mcp-coordinator server start --daemon

# Open the dashboard
mcp-coordinator dashboard

# Stop when done
mcp-coordinator server stop

In-process from your own Node app

import { startServer } from "mcp-coordinator";

await startServer({
  port: 3100,
  dataDir: "./coordinator-data",
});

For multi-Claude setups, team deployments, walkthroughs, and debugging recipes, see the usage guide.

Authentication

The coordinator runs in one of three modes, selected by env-var configuration. Single-user / dev local stays zero-config; multi-user deployments opt in to JWT or full OAuth via a single feature flag.

OAuth mode adds: 4 IdP providers (GitHub OAuth App, GitHub App, Google, generic OIDC) with picker UI, cookie sessions + Bearer JWT + service tokens, refresh-token rotation with stolen-token detection, SHA-256 audit chain (SOC 2 tamper-evidence), and an admin UI at /dashboard/admin.html.

MCP authorization spec discovery: /mcp does not implement the MCP authorization spec's OAuth discovery flow — no resource_metadata (RFC 9728) on WWW-Authenticate, no /.well-known/oauth-protected-resource. This is a deliberate scope decision, not an oversight: today's clients are the maintainer's own agents under an intra-org trust model (see docs/security/threat-model.md), and token provisioning is proprietary — shared-secret registration (/api/auth/register, Phase 1) or the device flow (Phase 2) — rather than spec-compliant discovery. Third-party spec-compliant MCP clients need manual configuration (they can't auto-discover the auth flow). The Phase 2 OAuth authorization server already exists, so wiring up spec-compliant discovery later is additive, not a rearchitecture.

Operational tooling: mcp-coordinator init phase2 (interactive wizard), mcp-coordinator doctor --phase2 (8 health probes), mcp-coordinator service-token {issue,list,revoke}, mcp-coordinator rotate-jwt-secret, tsx scripts/verify-audit-chain.ts.

Anthropic Quota Pre-flight

The coordinator tracks Anthropic workspace quota live and exposes it on MQTT, the dashboard, and the coordinator_status MCP tool — so MCP clients can decide whether to abort, throttle, or proceed before launching expensive turns.

• Reads the Claude Code OAuth token from the macOS Keychain (security find-generic-password -s "Claude Code-credentials") and calls Anthropic's /api/oauth/usage endpoint directly — macOS only. On Linux/Windows the credential reader is an unimplemented stub, so the quota endpoint returns 503 (fail-open: the rest of the coordinator keeps working without a quota guardrail).

• The coordinator itself enforces no abort threshold — it just serves fresh utilization numbers (2 min cache TTL). Deciding what "too high" means, e.g. via a MAX_QUOTA_PCT convention, is left to the orchestrator reading coordinator_status.quota.

• Back-off when the usage endpoint itself returns 429 (5 min cool-down by default, or the server's Retry-After).

• Live widget in the dashboard with manual refresh + historical buckets.

• coordinator/quota/update MQTT events stream into the timeline by default.

Orchestrators that spawn N agents at once can read coordinator_status.quota and abort their run if utilization is over a configured threshold — the essaim reference orchestrator does exactly this.

Token Observability

Every MCP tool call and agent turn is logged with token breakdown.

• Logs — component logger tokens emits input_tokens, output_tokens, cache_read, cache_creation, thinking, model id, turn index.

• Dashboard — live per-agent token gauge, cumulative session total, quota widget.

Aggregating across runs (e.g., reports/YYYY-MM-DD-<run-id>.md) is an orchestrator responsibility — the coordinator emits the events, the orchestrator consumes them.

Dashboard

http://localhost:3100/dashboard (or /dashboard on whichever port the coordinator is bound to).

• Timeline — all threads + quota_update events with scores and resolution types

• Agent panel — online/offline, working/idle/waiting, current file, thread being waited on

• Scoring breakdown — which detection layer triggered each conflict

• Quota widget — live utilization %, stacked buckets, manual refresh button

• Consensus metrics — per session: consensus / timeout / auto-resolved split, token totals

All events arrive via SSE on /api/events. No polling.

Agent activity states

Configuration

Local data

~/.mcp-coordinator/
├── config.json          # persistent configuration
├── data/
│   └── coordinator.db   # SQLite database
├── server.pid           # PID file (when daemonized)
└── logs/
    └── server.log       # daemon logs

config.json

{
  "server": { "port": 3100, "data_dir": "~/.mcp-coordinator/data" },
  "defaults": { "coordinator_url": "http://localhost:3100" }
}

Resolution priority (highest to lowest): CLI flag → env var → config.json → default.

Core env vars

COORDINATOR_DATA_DIR's default depends on how the server is started:

• CLI (mcp-coordinator server start, mcp-coordinator init, ...) defaults to ~/.mcp-coordinator/data (see config.json above).

• Direct entry points — node dist/src/serve-http.js, or stdio via .mcp.json (node dist/src/index.js / tsx src/index.ts) — do not go through the CLI's config resolution. Without COORDINATOR_DATA_DIR set, they fall back to ./data relative to the process's current working directory, which is unpredictable for a server a client spawns from an arbitrary cwd. Both entry points log a warning at boot when this fallback is in effect.

Always set COORDINATOR_DATA_DIR explicitly (or use the CLI) for a stable, predictable data location outside of local single-shot dev use.

The complete annotated env reference (50+ variables including all Phase 2 OAuth / multi-IdP / hardening vars) lives in .env.example — copy-paste and fill in.

Structured Logging

Pino emits JSON per subsystem. Component loggers: http, mcp, mqtt, consultation, conflict, auth, tokens, quota.

{"level":"info","time":1712345678901,"component":"http","msg":"Server started","port":3100}

Dev (NODE_ENV=development) renders pretty human-readable lines. Levels controlled via LOG_LEVEL.

SDK

A TypeScript reference client lives in sdk/ (not yet published to npm). Install via npm install file:./sdk from a consumer project.

import { McpCoordinatorClient, FileTokenStore, ProactiveRefresh } from "@mcp-coordinator/sdk-js";

const client = new McpCoordinatorClient({
  baseUrl: "https://coordinator.example.com",
  store: new FileTokenStore(),
  refreshStrategy: new ProactiveRefresh(),
  refreshLockPath: process.env.HOME + "/.mcp-coordinator/refresh.lock",
});

await client.loadFromStore();
const me = await client.whoami();

See sdk/README.md for the full API.

Integration patterns

• Any MCP client — connect to http://localhost:3100/mcp (HTTP/SSE) or stdio. The server speaks MCP 2024-11-05.

• Custom orchestrator — spawn agents that connect to the MQTT broker and register via the MCP register_agent tool. The orchestrator decides spawn count, lifecycle, and quota gating; the coordinator handles the protocol. See essaim for a reference implementation, or write your own.

• Behavior catalog — coordinator-aware agent behaviors (announce-before-write, work-stealing, conflict resolution) are YAML configs assembled by @swoofer/promptweave. See essaim's behaviors for a curated catalog.

Development

# This repo uses pnpm 10 (pinned via "packageManager" in package.json).
# Run `corepack enable` once — corepack then resolves the right pnpm
# version automatically.

pnpm install
pnpm test
pnpm dev          # HTTP / SSE on port 3100
pnpm dev:stdio    # stdio mode
pnpm build        # TypeScript build → dist/

# Standalone binary (requires Bun)
bun build --compile cli/index.ts --outfile bin/mcp-coordinator

Open an issue or PR on GitHub.

Roadmap

• v1.0 — Multi-instance: Redis-backed cache invalidation + leader election for the sweeper and rate limiter.

• Postgres adapter — for regulated multi-instance workloads. See design spec.

• SDK polish — Windows DPAPI encryption for the on-disk token file (keytar keychain integration and named-profile TOML config already shipped).

Per-version detail for everything already shipped lives in CHANGELOG.md.

Related projects

• @swoofer/promptweave — YAML composer for assembling agent prompts, hooks, and MCP configs. Use it with mcp-coordinator-aware behaviors from essaim.

• essaim — end-to-end orchestrator that spawns N coordinated agents using @swoofer/promptweave + mcp-coordinator. Ships the reference catalog of coordinator-aware behaviors.

Support

Built and maintained by @swoofer, with a large and growing automated test suite and a growing list of external contributors.

If this project saves you time:

• ⭐ Star the repo — it helps other devs find it

• 💖 GitHub Sponsors

• ☕ Buy Me A Coffee

• 🐛 Open an issue if something is broken or missing

License

MIT