Files

Proudlock a03fd3de4f Fix CI failures: remove unicode and fix lean build

- Replace all unicode (emojis, checkmarks, arrows, em-dashes) with ASCII in .claude/ docs
- Comment out OperatingSystemsList route in core.js - breaks lean builds without computers plugin
- Comment out Operating Systems tab in ModelCatalogHub
- TODO: Plugins should dynamically register their settings routes

Fixes #2 CI check failures on wj branch

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-09-11 16:42:19 -04:00

17 KiB

Raw Blame History

How to Connect to mcp-coordinator

Complete guide for connecting Claude Code (and other AI tools) to the mcp-coordinator daemon.

Connection Methods

mcp-coordinator supports two connection methods:

Method	How It Works	Best For
HTTP/SSE	Claude connects via HTTP to daemon at `http://localhost:3100`	Most reliable, recommended
stdio	Claude spawns coordinator process, talks via stdin/stdout	Single session, no shared state

For ShopDB: Use HTTP/SSE (allows multiple sessions to share one coordinator)

Architecture

+-------------------------------------------------------------+
|                         Your PC                              |
|                                                              |
|  +------------------+              +------------------+    |
|  |  Claude Code #1  |              |  Claude Code #2  |    |
|  |  (Session 1)     |              |  (Session 2)     |    |
|  +--------+---------+              +--------+---------+    |
|           |                                  |              |
|           | MCP over HTTP                    | MCP over HTTP|
|           | (localhost:3100)                 |              |
|           +--------------+-------------------+              |
|                          |                                  |
|                 +--------v----------+                       |
|                 |  mcp-coordinator  |                       |
|                 |     (daemon)      |                       |
|                 |   Port: 3100      |                       |
|                 |   MQTT: 1883      |                       |
|                 +-------------------+                       |
|                                                              |
+-------------------------------------------------------------+

Both Claude sessions connect to the SAME daemon = shared state = coordination works!

Setup 1: Local Solo (Just You, Multiple Sessions)

Step 1: Start the Coordinator Daemon

# Install globally first
npm install -g mcp-coordinator

# Initialize config
mcp-coordinator init

# Start daemon (runs in background)
mcp-coordinator server start --daemon

# Verify it's running
mcp-coordinator server status
# Output: "Server is running (PID: 12345) on http://127.0.0.1:3100"

Step 2: Configure Claude Code

Add to .claude/mcp-servers.json:

{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    },
    "mysql": {
      "command": "npx",
      "args": ["-y", "@benborla29/mcp-server-mysql", "mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"]
    },
    "browser": {
      "command": "npx",
      "args": ["-y", "@agent-infra/mcp-server-browser"]
    },
    "coordinator": {
      "command": "npx",
      "args": ["-y", "mcp-coordinator", "mcp"],
      "env": {
        "COORDINATOR_URL": "http://127.0.0.1:3100",
        "COORDINATOR_AGENT_NAME": "session-main",
        "COORDINATOR_AGENT_ROLE": "developer"
      }
    }
  }
}

Key environment variables:

COORDINATOR_URL - Where to connect (localhost for you)
COORDINATOR_AGENT_NAME - Unique name for this session (e.g., "session-main", "session-plugin-work")
COORDINATOR_AGENT_ROLE - What this session does (e.g., "developer", "reviewer", "refactor")

Step 3: Launch Claude Code Sessions

Session 1:

cd C:\Users\270015376\Documents\github\flask-shopdb
claude

# Inside Claude:
You: "Check coordinator status"
Claude: [Calls mcp__coordinator__coordinator_status]
Claude: "Coordinator running at http://127.0.0.1:3100. 1 agent registered: session-main (you)."

Session 2 (different terminal):

cd C:\Users\270015376\Documents\github\flask-shopdb
claude

# Need different agent name! Edit .claude/mcp-servers.json first:
# Change "COORDINATOR_AGENT_NAME": "session-main" to "session-plugin"
# Or pass as env var:
COORDINATOR_AGENT_NAME=session-plugin claude

# Inside Claude:
You: "Check coordinator status"
Claude: [Calls mcp__coordinator__coordinator_status]
Claude: "Coordinator running. 2 agents registered: session-main, session-plugin (you)."

Both sessions now see each other!

Setup 2: Team Mode (Multiple Developers)

Architecture

+---------------------+        +---------------------+
|   Dev PC #1         |        |   Dev PC #2         |
|   (270015376)       |        |   (coworker)        |
|                     |        |                     |
|  Claude Code        |        |  Cursor             |
|       |             |        |       |             |
|       +-------------+--------+-------+             |
|                     |        |                     |
+---------------------+        +---------------------+
         |                              |
         |  MCP over HTTP               |
         |  (LAN: 192.168.1.100:3100)  |
         +--------------+---------------+
                        |
              +---------v----------+
              |  Shared PC or      |
              |  Dev Server        |
              |                    |
              |  mcp-coordinator   |
              |  Host: 0.0.0.0     |
              |  Port: 3100        |
              +--------------------+

Step 1: Set Up Shared Coordinator

On shared machine (or your PC if you're hosting):

# Install
npm install -g mcp-coordinator

# Initialize
mcp-coordinator init

# Edit config to allow LAN connections
# File: ~/.mcp-coordinator/config.json

Edit ~/.mcp-coordinator/config.json:

{
  "server": {
    "port": 3100,
    "host": "0.0.0.0",  // <- Changed from 127.0.0.1 to allow LAN
    "cors": {
      "enabled": true,
      "origins": ["*"]  // Or specific IPs
    }
  },
  "auth": {
    "enabled": true,  // Recommended for team mode
    "method": "basic",
    "users": [
      {"username": "270015376", "password": "your-password-here"},
      {"username": "coworker", "password": "their-password"}
    ]
  },
  "repo": {
    "root": "/shared/path/to/shopdb-flask",  // Or leave blank
    "git_cochange_enabled": true
  }
}

Start daemon:

mcp-coordinator server start --daemon

# Find the IP address
# Windows:
ipconfig | findstr IPv4
# Output: IPv4 Address. . . . . . . . . . . : 192.168.1.100

# Verify externally accessible:
mcp-coordinator server status
# Or from another PC: curl http://192.168.1.100:3100/health

Step 2: Connect Each Developer

Dev 1 (You) - .claude/mcp-servers.json:

{
  "mcpServers": {
    "coordinator": {
      "command": "npx",
      "args": ["-y", "mcp-coordinator", "mcp"],
      "env": {
        "COORDINATOR_URL": "http://192.168.1.100:3100",
        "COORDINATOR_AGENT_NAME": "270015376-claude",
        "COORDINATOR_AGENT_ROLE": "developer",
        "COORDINATOR_AUTH_USER": "270015376",
        "COORDINATOR_AUTH_PASS": "your-password-here"
      }
    }
  }
}

Dev 2 (Coworker) - their config:

{
  "mcpServers": {
    "coordinator": {
      "command": "npx",
      "args": ["-y", "mcp-coordinator", "mcp"],
      "env": {
        "COORDINATOR_URL": "http://192.168.1.100:3100",
        "COORDINATOR_AGENT_NAME": "coworker-cursor",
        "COORDINATOR_AGENT_ROLE": "developer",
        "COORDINATOR_AUTH_USER": "coworker",
        "COORDINATOR_AUTH_PASS": "their-password"
      }
    }
  }
}

Now both devs' AI tools coordinate through the same daemon!

Connection Flow (Technical Details)

What Happens When Claude Starts

Claude reads .claude/mcp-servers.json
Claude spawns npx mcp-coordinator mcp with env vars
Coordinator MCP wrapper connects to daemon at COORDINATOR_URL
Wrapper registers agent via HTTP POST to /api/register_agent
MQTT subscription opens for real-time events
Claude calls MCP tools, wrapper forwards to daemon via HTTP
Daemon responds via HTTP, wrapper returns to Claude
MQTT pushes events (consultations, status) to wrapper
Wrapper surfaces as MCP tool results to Claude

Connection Verification

Check if daemon is reachable:

# From same machine:
curl http://127.0.0.1:3100/health
# Expected: {"status":"ok","version":"2.3.0"}

# From other machine (team mode):
curl http://192.168.1.100:3100/health

# Check MQTT broker:
# Install MQTT client first: npm install -g mqtt
mqtt sub -h 127.0.0.1 -p 1883 -t 'coordinator/#' -v
# Should show: Connected to mqtt://127.0.0.1:1883

Check if Claude is connected:

Inside Claude session:

You: "Call coordinator_status"

Claude: [Calls mcp__coordinator__coordinator_status]
Claude: "Connected. Daemon version 2.3.0. Agents registered: 1"

View in dashboard:

# Open browser
mcp-coordinator dashboard
# Or manually: http://127.0.0.1:3100/dashboard

# Should show:
# - Active Agents: session-main (online)
# - Connection count: 1
# - MQTT clients: 1

Agent Naming Strategy

Important: Each Claude session needs a UNIQUE COORDINATOR_AGENT_NAME.

Recommended Naming:

Session Purpose	Agent Name	Role
Main development	`270015376-main`	`developer`
Plugin work	`270015376-plugins`	`developer`
Code review	`270015376-review`	`reviewer`
Refactoring	`270015376-refactor`	`refactor`
Testing	`270015376-test`	`tester`

Dynamic Naming:

Option 1: Per-project config

Create .claude/mcp-servers.json in each project with unique names:

# In flask-shopdb/.claude/mcp-servers.json
"COORDINATOR_AGENT_NAME": "270015376-shopdb-main"

# In another-project/.claude/mcp-servers.json
"COORDINATOR_AGENT_NAME": "270015376-otherproject-main"

Option 2: Environment variable override

# Launch with custom name
COORDINATOR_AGENT_NAME=270015376-bugfix-session claude

# Or in Windows:
set COORDINATOR_AGENT_NAME=270015376-bugfix-session
claude

Option 3: Auto-generate from git branch

Add to .claude/mcp-servers.json:

"coordinator": {
  "command": "bash",
  "args": [
    "-c",
    "export COORDINATOR_AGENT_NAME=\"270015376-$(git branch --show-current)\"; npx -y mcp-coordinator mcp"
  ],
  "env": {
    "COORDINATOR_URL": "http://127.0.0.1:3100"
  }
}

Now agent name is: 270015376-wj or 270015376-wilm based on branch!

Multiple Sessions Example

Scenario: You're working on two features simultaneously.

Session 1: Main Work (Operator Reports)

cd C:\Users\270015376\Documents\github\flask-shopdb
COORDINATOR_AGENT_NAME=270015376-operator-reports claude

# Inside Claude:
You: "Fix operator report email alerts"
Claude: [register_agent as "270015376-operator-reports"]
Claude: [announce_work for plugins/endpoints/api/routes.py]
Claude: "Registered. No conflicts. Proceeding..."

Session 2: Plugin Work (Fleet Alerts)

cd C:\Users\270015376\Documents\github\flask-shopdb
COORDINATOR_AGENT_NAME=270015376-fleet-alerts claude

# Inside Claude:
You: "Add scope filtering to fleet alerts"
Claude: [register_agent as "270015376-fleet-alerts"]
Claude: [announce_work for plugins/notifications/models/notification.py]
Claude: "Registered. No conflicts. Proceeding..."

Dashboard View:

http://127.0.0.1:3100/dashboard shows:

Active Agents (2)
+- 270015376-operator-reports
|  +- Files: plugins/endpoints/api/routes.py
|  +- Status: Working
|  +- Since: 2 minutes ago
|
+- 270015376-fleet-alerts
   +- Files: plugins/notifications/models/notification.py
   +- Status: Working
   +- Since: 1 minute ago

Consultations (0)
No conflicts detected

If They Conflict:

Session 2 tries to edit routes.py:

You: "Also update the route handler"
Claude: [announce_work for plugins/endpoints/api/routes.py]
Claude: "[!] Conflict detected!"
Claude: "Agent '270015376-operator-reports' is currently modifying routes.py"
Claude: [post_to_thread]
Claude: "Consulting... Opening thread #1"

# Session 1 sees notification via MQTT
Claude (Session 1): "[ANNOUNCE] New consultation: Agent '270015376-fleet-alerts' also needs routes.py"
Claude (Session 1): [Reads thread]
Claude (Session 1): [post_to_thread] "I'm working on _send_operator_report_alert function. What do you need?"

# Session 2 sees response
Claude (Session 2): [Reads thread]
Claude (Session 2): [post_to_thread] "I need to update the route registration. Different concern. Can proceed in parallel."

# Both agree
Claude (Session 1): [Approves in thread]
Claude (Session 2): [Approves in thread]
# Coordinator auto-closes thread as "resolved"

# Both proceed with edits

Connection Troubleshooting

Problem: "Connection refused"

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:3100

Solutions:

Check daemon is running:
```
mcp-coordinator server status
```
If not running, start it:
```
mcp-coordinator server start --daemon
```

Check port:

# Windows:
netstat -ano | findstr 3100
# Should show: TCP 127.0.0.1:3100 ... LISTENING

Check firewall (team mode):

# Windows: Allow port 3100 inbound
netsh advfirewall firewall add rule name="mcp-coordinator" dir=in action=allow protocol=TCP localport=3100

Problem: "Agent already registered"

Symptoms:

Error: Agent name "270015376-main" is already registered

Cause: You started two Claude sessions with the same name.

Solution: Use different names:

# Session 1
COORDINATOR_AGENT_NAME=270015376-main claude

# Session 2
COORDINATOR_AGENT_NAME=270015376-secondary claude

Problem: "Unauthorized"

Symptoms:

Error: 401 Unauthorized

Cause: Team mode has auth enabled, but you didn't provide credentials.

Solution: Add to env vars:

"env": {
  "COORDINATOR_URL": "http://192.168.1.100:3100",
  "COORDINATOR_AUTH_USER": "270015376",
  "COORDINATOR_AUTH_PASS": "your-password"
}

Problem: "MCP tools not showing up"

Symptoms: Claude doesn't have coordinator tools available.

Solutions:

Restart Claude Code completely
Check .mcp.json is in right location:
```
ls .claude/mcp-servers.json
```

Verify JSON syntax:

cat .claude/mcp-servers.json | jq .
# Should parse without error

Check Claude Code MCP settings:

# In Claude Code settings (if GUI)
# Or check logs: ~/.claude/logs/

Test connection manually:

npx -y mcp-coordinator mcp
# Should connect and show MCP server ready

Connection Best Practices

1. Keep Daemon Running

Start on boot (Windows):

Create startup-coordinator.bat:

@echo off
mcp-coordinator server start --daemon

Add to: shell:startup

Or use Task Scheduler:

<Task version="1.2">
  <Actions>
    <Exec>
      <Command>mcp-coordinator</Command>
      <Arguments>server start --daemon</Arguments>
    </Exec>
  </Actions>
  <Triggers>
    <LogonTrigger />
  </Triggers>
</Task>

2. Monitor Daemon Health

Check periodically:

# Status
mcp-coordinator server status

# Logs
mcp-coordinator server logs --tail 50

# Restart if crashed
mcp-coordinator server restart

Set up health check (team mode):

# Cron job (Linux) or Task Scheduler (Windows)
# Every 5 minutes:
curl http://127.0.0.1:3100/health || mcp-coordinator server start --daemon

3. Use Descriptive Agent Names

Good:

270015376-operator-reports
270015376-plugin-refactor
jdoe-bugfix-auth

Bad:

agent1
claude
test

Why: Dashboard shows names. You want to see "who's working on what" at a glance.

4. Set Agent Roles

"COORDINATOR_AGENT_ROLE": "developer"  // or:
"COORDINATOR_AGENT_ROLE": "reviewer"   // Code review session
"COORDINATOR_AGENT_ROLE": "refactor"   // Refactoring session
"COORDINATOR_AGENT_ROLE": "tester"     // Test writing session
"COORDINATOR_AGENT_ROLE": "debugger"   // Bug hunting session

Why: Dashboard can filter/group by role.

Connection Summary

Local Solo Mode:

Start daemon: mcp-coordinator server start --daemon
Add to .claude/mcp-servers.json with COORDINATOR_URL=http://127.0.0.1:3100
Launch Claude sessions with unique COORDINATOR_AGENT_NAME
All sessions connect to same daemon = coordination works

Team Mode:

Start daemon on shared machine with host: "0.0.0.0"
Open firewall port 3100
Each dev adds coordinator to their MCP config with COORDINATOR_URL=http://SHARED_IP:3100
Each dev uses unique agent name (include username)
Enable auth in coordinator config
All devs' AIs coordinate through shared daemon

Key Points:

One daemon, many sessions = shared state
Unique agent names = identity tracking
HTTP/SSE transport = reliable, scalable
MQTT for push = real-time updates
Dashboard = visibility

Next: Testing the Connection

Once connected, test with:

You: "Check coordinator status"
Claude: [Calls coordinator_status]

You: "List active agents"
Claude: [Calls list_agents]

You: "Announce I'm working on routes.py"
Claude: [Calls announce_work]

You: "Show any consultations"
Claude: [Calls list_consultations]

If all work, you're fully connected!

References

Connection docs: https://swoofer.github.io/mcp-coordinator/connection.html
MCP config examples: https://github.com/swoofer/mcp-coordinator/tree/main/examples
Troubleshooting: https://swoofer.github.io/mcp-coordinator/troubleshooting.html

17 KiB Raw Blame History

How to Connect to mcp-coordinator

Connection Methods

Architecture

Setup 1: Local Solo (Just You, Multiple Sessions)

Step 1: Start the Coordinator Daemon

Step 2: Configure Claude Code

Step 3: Launch Claude Code Sessions

Setup 2: Team Mode (Multiple Developers)

Architecture

Step 1: Set Up Shared Coordinator

Step 2: Connect Each Developer

Connection Flow (Technical Details)

What Happens When Claude Starts

Connection Verification

Agent Naming Strategy

Recommended Naming:

Dynamic Naming:

Multiple Sessions Example

Session 1: Main Work (Operator Reports)

Session 2: Plugin Work (Fleet Alerts)

Dashboard View:

If They Conflict:

Connection Troubleshooting

Problem: "Connection refused"

Problem: "Agent already registered"

Problem: "Unauthorized"

Problem: "MCP tools not showing up"

Connection Best Practices

1. Keep Daemon Running

2. Monitor Daemon Health

3. Use Descriptive Agent Names

4. Set Agent Roles

Connection Summary

Local Solo Mode:

Team Mode:

Key Points:

Next: Testing the Connection

References

17 KiB

Raw Blame History