Claude Codex Orchestrator MCP

A local MCP server that wraps a Windows Claude -> Codex worker orchestration workflow.

The MCP server is intentionally thin. It exposes a stable tool surface and delegates execution to the existing PowerShell dispatcher scripts under tools/.

What It Provides

• create_task: create one queued markdown task under .orchestrator/tasks/.

• dispatch_task: dispatch one task through tools/invoke-orchestrated-task.ps1.

• read_status: read compact status.json output and summarize the result.

• run_task_loop: run bounded retry/decision handling over queued tasks.

• archive_artifacts: archive historical artifacts, dry-run by default.

Requirements

• Windows PowerShell 5.x or compatible powershell.exe.

• Node.js 20+.

• Codex CLI available on PATH for app and code lanes.

• Codex Desktop/app-server support for the app lane.

Quick Start

npm run mcp:orchestrator

The server speaks MCP over stdio. It is meant to be launched by an MCP client, not used as an interactive terminal program.

MCP Client Config Example

Use absolute paths for your clone location and the workspace you want the orchestrator to manage:

{
  "mcpServers": {
    "claude-codex-orchestrator": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "D:/path/to/claude-codex-orchestrator-mcp/tools/mcp-orchestrator-server.js"
      ],
      "env": {
        "ORCHESTRATOR_WORKSPACE_ROOT": "D:/path/to/your/workspace"
      }
    }
  }
}

Safety Model

• The server validates file paths and keeps them inside the configured workspace.

• Set ORCHESTRATOR_WORKSPACE_ROOT when the MCP server is installed outside the workspace it should manage.

• Automation defaults to dry-run unless explicitly invoked with real automation flags in the underlying dispatcher path.

• Artifact archival defaults to dry-run; moves require apply: true.

• The MCP server does not edit Codex global config.

• Existing PowerShell scripts remain the source of truth for orchestration behavior.

Repository Layout

.
|-- AGENTS.md
|-- PROJECT-CONTEXT-MCP-SKILL.md
|-- package.json
|-- docs/
|   `-- ORCHESTRATOR-USAGE.md
|-- tools/
|   |-- mcp-orchestrator-server.js
|   |-- invoke-orchestrated-task.ps1
|   |-- invoke-codex-app-worker.ps1
|   |-- codex-app-worker.js
|   |-- invoke-codex-worker.ps1
|   |-- run-controlled-automation.ps1
|   |-- orchestrator-tasking.ps1
|   |-- invoke-orchestrator-task-loop.ps1
|   `-- archive-orchestrator-artifacts.ps1
`-- .claude/
    |-- commands/orchestrate.md
    `-- skills/claude-codex-orchestrator/SKILL.md

Verification

Syntax-check the MCP server:

node --check tools/mcp-orchestrator-server.js

Run non-Codex PowerShell checks:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-orchestrator-tasking.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-controlled-automation.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-archive-orchestrator-artifacts.ps1

Full app/code worker tests require a working Codex CLI/app-server setup and may take longer.