🐙 MCP Orchestrator

Turn one AI agent into a team. Cross-platform MCP server for spawning parallel sub-agents with multi-CLI backend support.

Platform Support

macOS (Intel & Apple Silicon)
Linux (x86-64 & ARM64)
Windows (x64 & ARM64)

Windows setup: See WINDOWS_VALIDATION.md

Features

Multi-CLI backends — Support for GitHub Copilot CLI and Claude Code CLI
Parallel execution — Run multiple sub-agents simultaneously
Context passing — Pass file contents (full/summary/grep) to sub-agents
MCP server filtering — Specify which MCP servers each sub-agent can use
MCP Resources — Expose logs and config as readable MCP resources
Timeout handling — Per-task and global timeouts
Audit logging — All executions logged to ~/.config/orchestrator/logs/

Quick Demo

Spawn 3 parallel sub-agents for job research:

# Via job-search-automation workspace
cd /path/to/job-search-automation
ma parallel \
  "search LinkedIn for SDE-2 roles" \
  "search Reddit for remote jobs" \
  "research top companies for tech stack"

Expected output:

🐙 SPAWNING PARALLEL TASKS
==========================

Tasks (3 total):
  1. search LinkedIn for SDE-2 roles
  2. search Reddit for remote jobs
  3. research top companies for tech stack

⏳ Spawning sub-agents via Orchestrator...
[Sub-Agent 1] LinkedIn search in progress...
[Sub-Agent 2] Reddit search in progress...
[Sub-Agent 3] Company research in progress...
✅ Parallel execution complete

Installation

For detailed setup instructions, see SETUP.md.

Quick start:

git clone https://github.com/Ask149/orchestrator.git
cd orchestrator
npm install
npm run build

Configuration

Config files live at:

macOS/Linux: ~/.config/orchestrator/
Windows: %LOCALAPPDATA%\\orchestrator\\ (falls back to %APPDATA%)

<config-dir>/
├── config.json          # CLI backend configuration
├── mcp-subagent.json    # MCP servers available to sub-agents
└── logs/                # Execution audit logs (JSONL)

CLI Backend Configuration (config.json)

{
  "cli": {
    "backend": "copilot",

    "copilot": {
      "command": "copilot",
      "allowAllTools": false,
      "allowAllPaths": false,
      "model": null
    },

    "claude": {
      "command": "claude",
      "allowAllTools": false,
      "maxTurns": 10,
      "model": null
    }
  }
}

Defaults are secure: allowAllTools and allowAllPaths are false. Enable explicitly for unattended runs.

Supported CLI Backends

Backend	CLI	Description
`copilot`	GitHub Copilot CLI	`copilot -p "prompt" [--allow-all-tools] [--allow-all-paths]`
`claude`	Claude Code CLI	`claude -p "prompt" [--dangerously-skip-permissions] --output-format stream-json`

Note: Sub-agents run without the --agent flag. Custom agents restrict the available toolset (e.g., to only report_intent, update_todo). By omitting --agent, sub-agents get full access to Copilot's built-in tools: bash, view, edit, create, grep.

Environment Variables

Variable	Default	Description
`COPILOT_CLI`	`copilot`	Path to Copilot CLI
`CLAUDE_CLI`	`claude`	Path to Claude Code CLI
`ORCHESTRATOR_DEFAULT_BACKEND`	`copilot`	Default CLI backend (`copilot` or `claude`)
`ORCHESTRATOR_WORKSPACE`	cwd	Default workspace for tasks
`LOG_LEVEL`	`INFO`	Logging level: `DEBUG`, `INFO`, `WARN`, `ERROR`

Smart Timeout Configuration

The orchestrator automatically selects appropriate timeouts based on MCP servers requested:

MCP Server	Default Timeout	Reason
`filesystem`, `memory`	30s	Fast local operations
`github`, `google-tasks`	60s	API calls + auth overhead
`google-calendar`, `leetcode`	90s	OAuth + complex APIs
`playwright`	120s	Browser startup + page rendering

Logic: effective_timeout = max(task.timeout_seconds, recommended_for_servers, default)

Override with explicit timeout_seconds in task definition when needed.

Usage

Tool: `spawn_subagents`

Spawn parallel sub-agents for complex tasks.

Parameters:

Parameter	Type	Required	Description
`tasks`	array	Yes	Array of sub-agent tasks (max 10)
`default_timeout_seconds`	number	No	Default timeout (default: 120)
`default_workspace`	string	No	Default working directory

Task Properties:

Property	Type	Required	Description
`id`	string	Yes	Unique task identifier
`prompt`	string	Yes	Task prompt for sub-agent
`context`	object	No	File/data context to pass
`mcp_servers`	array	No	MCP servers to enable
`workspace`	string	No	Working directory
`timeout_seconds`	number	No	Task timeout
`cli_backend`	string	No	Override CLI backend (`copilot` or `claude`)

Example: Parallel Research

{
  "tasks": [
    {
      "id": "stripe",
      "prompt": "Find SDE-2 roles at Stripe",
      "mcp_servers": ["playwright"]
    },
    {
      "id": "google",
      "prompt": "Find SDE-2 roles at Google",
      "mcp_servers": ["playwright"]
    },
    {
      "id": "meta",
      "prompt": "Find SDE-2 roles at Meta",
      "mcp_servers": ["playwright"],
      "cli_backend": "claude"
    }
  ]
}

Example: Context Passing

{
  "tasks": [
    {
      "id": "analyze",
      "prompt": "Analyze this file and summarize",
      "context": {
        "files": [
          { "path": "src/main.ts", "mode": "full" },
          { "path": "README.md", "mode": "summary" },
          { "path": "src/", "mode": "grep", "pattern": "TODO|FIXME" }
        ]
      }
    }
  ]
}

MCP Server Configuration (mcp-subagent.json)

Define MCP servers available to sub-agents.

⚠️ IMPORTANT: For Copilot CLI in -p (programmatic) mode, MCP servers must be configured in the default config location. The --additional-mcp-config flag only augments (adds to) this default config. Servers not in the default location will not load in -p mode.

Config location:

macOS/Linux: ~/.copilot/mcp-config.json

Windows: %USERPROFILE%\.copilot\mcp-config.json (e.g., C:\Users\username\.copilot\mcp-config.json)

Required fields for CLI compatibility:

Field	Copilot CLI	Claude CLI	Description
`type`	Required	Optional	`"local"`, `"stdio"`, `"http"`, or `"sse"`
`tools`	Required	Optional	Array of tool names or `["*"]` for all
`command`	Required	Required	Executable path
`args`	Required	Required	Command arguments

macOS/Linux:

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "tools": ["*"]
    }
  }
}

Windows (requires cmd /c wrapper for npx):

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"],
      "tools": ["*"]
    }
  }
}

Windows Users: Without cmd /c, you'll encounter "Connection closed" errors because Windows cannot directly execute npx. See WINDOWS_VALIDATION.md for details.

MCP Integration

Job Search Automation (Recommended)

Use the ma CLI for integrated job search workflows:

cd /path/to/job-search-automation
ma parallel "search LinkedIn for SDE-2" "search Reddit for remote jobs"

See automation/ORCHESTRATOR.md in job-search-automation workspace for complete usage guide with workflows and examples.

Standalone: VS Code / Cline

Add to your MCP settings to use as a standalone server:

{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["/path/to/orchestrator/dist/index.js"],
      "env": {
        "ORCHESTRATOR_WORKSPACE": "/path/to/your/workspace"
      }
    }
  }
}

Audit Logs

Execution logs are written to <config-dir>/logs/orchestrator.jsonl:

{"timestamp":"2026-02-01T10:00:00.000Z","level":"INFO","message":"Spawning 3 sub-agents","taskIds":["stripe","google","meta"]}

Production Features

Health Check

Verify CLI backends are available before deployment:

npm run health
# or
npx mcp-orchestrator-health

Returns JSON with backend availability and exit code 0 if at least one backend is available.

Graceful Shutdown

Server waits up to 30 seconds for active tasks to complete on SIGTERM/SIGINT.

Automatic Retry

Transient failures (timeout, connection reset) are automatically retried once with a 2s delay.

Log Rotation

Application logs auto-rotate at 10MB:

~/.config/orchestrator/logs/orchestrator.jsonl

MCP Resources (v1.1.0+)

The orchestrator exposes its logs and configuration as MCP resources:

Resource URI	Description
`logs://orchestrator/app`	Application logs in JSONL format
`logs://orchestrator/recent`	Tail of application logs (last ~200 lines)
`config://orchestrator/current`	Current CLI and MCP server configuration
`health://orchestrator/status`	Health status snapshot (same as `check_health`)
`state://orchestrator/active_tasks`	In-flight task IDs tracked for graceful shutdown

Use these resources to inspect orchestrator state without direct file access.

Tool: `check_health`

Verify orchestrator health via MCP (alternative to CLI npm run health):

{
  "healthy": true,
  "timestamp": "2026-02-03T10:00:00.000Z",
  "platform": "darwin-arm64",
  "backends": {
    "copilot": { "available": true, "version": "1.0.0" },
    "claude": { "available": false, "error": "not found" }
  }
}

Development

# Build
npm run build

# Watch mode
npm run watch

# Type check
npx tsc --noEmit

# Run smoke tests
npm test

# Watch tests
npm test:watch

Known Limitations

Playwright MCP & Browser Automation

Issue	Description	Mitigation
Chrome profile lock	Chrome locks `--user-data-dir` to one process. If Chrome is already running with the same profile (e.g., VS Code's Playwright MCP), sub-agents cannot use Playwright MCP tools.	The orchestrator auto-generates isolated temp profiles per sub-agent (`/tmp/pw-profile-{taskId}`). If the MCP still fails, the `BROWSER_AUTOMATION_FALLBACK` prompt instructs sub-agents to use `chromium.launch({ headless: true })` via the Playwright npm package directly.
Parallel browser concurrency	Multiple sub-agents requesting Playwright spawn separate browser instances, which increases memory/CPU usage.	Limit parallel Playwright tasks to 2-3 at a time.
No headless mode in MCP	Playwright MCP launches a visible browser window by default, which steals focus and fails in CI/CD.	Pass `--headless` in the Playwright MCP args in `mcp-subagent.json`, or rely on the npm fallback which uses headless by default.
No output streaming	Sub-agents buffer all stdout until process exit. For long Playwright tasks, there's no progress indication.	Use shorter, focused prompts. Complex multi-page workflows should be split into separate tasks.

Claude CLI Backend

Issue	Description	Mitigation
Auth not auto-detected	`claude --version` succeeds without auth, but prompts fail with "Invalid API key".	The health check now runs a quick prompt to validate auth. Run `claude login` to fix.
Stricter MCP schema	Claude CLI rejects `type` and `tools` fields in MCP config.	The orchestrator auto-strips these fields when generating Claude-compatible configs.

Testing

Cross-platform smoke tests validate:

Config path resolution (macOS/Linux/Windows)
Temp file handling
Secure permission defaults
Grep implementation (no Unix deps)
Platform-specific spawn behavior

Run tests with: npm test

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github		.github
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
WINDOWS_VALIDATION.md		WINDOWS_VALIDATION.md
jest.config.json		jest.config.json
mcp-subagent.json		mcp-subagent.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🐙 MCP Orchestrator

Platform Support

Features

Quick Demo

Installation

Configuration

CLI Backend Configuration (config.json)

Supported CLI Backends

Environment Variables

Smart Timeout Configuration

Usage

Tool: spawn_subagents

Example: Parallel Research

Example: Context Passing

MCP Server Configuration (mcp-subagent.json)

MCP Integration

Job Search Automation (Recommended)

Standalone: VS Code / Cline

Audit Logs

Production Features

Health Check

Graceful Shutdown

Automatic Retry

Log Rotation

MCP Resources (v1.1.0+)

Tool: check_health

Development

Known Limitations

Playwright MCP & Browser Automation

Claude CLI Backend

Testing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Tool: `spawn_subagents`

Tool: `check_health`

Packages