Claude Orchestrator MCP

An MCP server for coordinating multiple Claude Code sessions across related projects. When you're working on a multi-service system with separate repos (e.g., auth service, API gateway, frontend), this orchestrator enables sessions to communicate changes, request sync points, and stay aware of what's happening in related services.

The Problem

You have 6 repos for a platform, each with its own Claude Code session. When the auth service session modifies the User schema:

• The API gateway session has no idea
• The frontend session keeps using old types
• Someone has to manually copy/paste context between terminals
• Changes get out of sync, causing integration issues

The Solution

Claude Orchestrator acts as a coordination layer:

┌─────────────────────────────────────────────────────────────┐
│                 claude-orchestrator-mcp                      │
│                                                             │
│  Sessions register → Changes detected → Updates routed      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
         │           │           │           │
    ┌────┴───┐  ┌────┴───┐  ┌────┴───┐  ┌────┴───┐
    │ Auth   │  │ API    │  │ Catalog│  │Frontend│
    │Session │  │Session │  │Session │  │Session │
    └────────┘  └────────┘  └────────┘  └────────┘

Installation

# Clone and build
git clone <repo>
cd claude-orchestrator-mcp
npm install
npm run build

# Or install globally
npm install -g claude-orchestrator-mcp

Quick Start

1. Initialize configuration

# Create example topology
npx claude-orchestrator init

# Or manually create your topology
npx claude-orchestrator group create my-platform
npx claude-orchestrator member add my-platform ~/repos/auth-service --role auth
npx claude-orchestrator member add my-platform ~/repos/api-gateway --role gateway --depends-on auth
npx claude-orchestrator member add my-platform ~/repos/frontend --role frontend --depends-on gateway

2. Add to Claude Code MCP configuration

Add to your ~/.claude.json:

{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "node",
      "args": ["/path/to/claude-orchestrator-mcp/dist/index.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "npx",
      "args": ["-y", "claude-orchestrator-mcp"]
    }
  }
}

3. Use in your Claude Code sessions

When starting work in a repo:

> Use the register_session tool with repoPath="/Users/me/repos/auth-service",
  projectGroup="my-platform", role="auth"

Check for updates from other sessions:

> Use get_cross_project_updates with my session ID

Notify others about a change:

> Use notify_related_sessions to broadcast that I modified the User schema

Configuration

The topology configuration lives at ~/.config/claude-orchestrator/topology.yml:

version: "1.0"

groups:
  my-platform:
    name: my-platform
    description: "My multi-service platform"

    members:
      - path: ~/repos/auth-service
        role: auth
        exports: [UserToken, AuthContext]

      - path: ~/repos/api-gateway
        role: gateway
        dependsOn: [auth]

      - path: ~/repos/frontend
        role: frontend
        dependsOn: [gateway]

    communicationRules:
      - when: schema_change
        from: "*"
        notify: dependents
        priority: high

      - when: breaking_change
        from: "*"
        notify: all
        priority: critical

Change Types

• schema_change - Database/GraphQL/Protobuf schema changes
• api_endpoint_change - Route/controller/API changes
• type_definition_change - TypeScript/interface changes
• config_change - Configuration file changes
• dependency_update - package.json/requirements.txt changes
• breaking_change - Detected via commit message patterns
• any_change - Catch-all for any file change

Notification Targets

• "all" - Notify all members in the group
• "dependents" - Notify only members that depend on the source
• ["role1", "role2"] - Notify specific roles

MCP Tools

Session Management

Tool	Description
register_session	Register this session with the orchestrator
unregister_session	Unregister when done
heartbeat	Keep session active, update current task

Cross-Project Updates

Tool	Description
get_cross_project_updates	Check for updates from related sessions
notify_related_sessions	Broadcast a change to related sessions

State Queries

Tool	Description
query_project_state	Query another project's status/changes
list_group_sessions	List all sessions in a project group

Sync Points

Tool	Description
request_sync_point	Request coordination barrier
acknowledge_sync_point	Acknowledge a sync request
get_pending_sync_points	Get pending sync requests

Topology

Tool	Description
get_topology	Get project topology configuration

CLI Commands

# Group management
claude-orchestrator group create <name>
claude-orchestrator group list
claude-orchestrator group show <name>
claude-orchestrator group delete <name>

# Member management
claude-orchestrator member add <group> <path> --role <role> --depends-on <roles>
claude-orchestrator member remove <group> <path>

# Rule management
claude-orchestrator rule add <group> --when <type> --from <roles> --notify <targets>

# Utilities
claude-orchestrator validate
claude-orchestrator init
claude-orchestrator config-path

How It Works

1. Session Registration: Each Claude Code session registers with the orchestrator, providing its repo path, project group, and role.

2. Change Detection: The orchestrator watches registered repos for file changes (via chokidar) and git commits (via polling). Changes are classified by type based on file patterns.

3. Event Routing: When changes are detected, the topology manager determines which sessions should be notified based on communication rules and dependency relationships.

4. Update Queuing: Updates are queued for target sessions. When a session calls get_cross_project_updates, it receives all pending notifications.

5. Sync Points: Sessions can request sync points for coordinated changes. Other sessions are notified and can acknowledge before the requester proceeds.

Example Workflow

Terminal 1 (auth-service):
> Register session for auth-service in my-platform group
> [Working on User schema changes...]
> Notify related sessions: "Modified User schema, added refreshToken field"

Terminal 2 (api-gateway):
> Register session for api-gateway in my-platform group
> Check for cross-project updates
> [Receives notification about User schema change]
> "Update UserToken type to include refreshToken"

Terminal 3 (frontend):
> Register session for frontend in my-platform group
> Check for cross-project updates
> [Receives notification via gateway dependency chain]
> "Update auth context to handle new token field"

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run CLI
npm run cli -- group list

# Type check
npm run typecheck

# Run tests
npm test

License

MIT