shopdb-flask/.claude/setup/MCP-COORDINATOR-CONNECTION-GUIDE.md

# 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)                 │              │
│           └──────────────┬───────────────────┘              │
│                          │                                  │
│                 ┌────────▼──────────┐                       │
│                 │  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

```bash
# 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`:

```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:**
```bash
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):**
```bash
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)  │
         └──────────────┬───────────────┘
                        │
              ┌─────────▼──────────┐
              │  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):**

```bash
# 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`:

```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:**

```bash
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:**

```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:**

```json
{
  "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

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

### Connection Verification

**Check if daemon is reachable:**

```bash
# 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:**

```bash
# 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:

```bash
# 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**

```bash
# 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`:

```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)

```bash
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)

```bash
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): "📢 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:**

1. Check daemon is running:
   ```bash
   mcp-coordinator server status
   ```

2. If not running, start it:
   ```bash
   mcp-coordinator server start --daemon
   ```

3. Check port:
   ```bash
   # Windows:
   netstat -ano | findstr 3100
   # Should show: TCP 127.0.0.1:3100 ... LISTENING
   ```

4. Check firewall (team mode):
   ```bash
   # 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:

```bash
# 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:

```json
"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:**

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

3. Verify JSON syntax:
   ```bash
   cat .claude/mcp-servers.json | jq .
   # Should parse without error
   ```

4. Check Claude Code MCP settings:
   ```bash
   # In Claude Code settings (if GUI)
   # Or check logs: ~/.claude/logs/
   ```

5. Test connection manually:
   ```bash
   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`:

```bat
@echo off
mcp-coordinator server start --daemon
```

Add to: `shell:startup`

**Or use Task Scheduler:**

```xml
<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:**

```bash
# 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):**

```bash
# 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

```json
"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:

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

### Team Mode:

1. Start daemon on shared machine with `host: "0.0.0.0"`
2. Open firewall port 3100
3. Each dev adds coordinator to their MCP config with `COORDINATOR_URL=http://SHARED_IP:3100`
4. Each dev uses unique agent name (include username)
5. Enable auth in coordinator config
6. 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