cli-orchestrator-mcp

Why cli-orchestrator-mcp?

Modern AI workflows often need more than one LLM CLI. Claude excels at reasoning, Gemini at research, Codex at code generation. But managing multiple CLIs — handling failures, retries, fallbacks, and routing — is complex and error-prone.

cli-orchestrator-mcp solves this by providing a single Model Context Protocol (MCP) server that:

• Orchestrates Claude CLI, Gemini CLI, and Codex CLI through a unified interface

• Routes intelligently — picks the best CLI based on the agent's role

• Recovers automatically — retry with backoff, circuit breaker isolation, and provider fallback

• Runs inline — executes CLIs as local subprocesses, no API keys or cloud calls needed

Any MCP-compatible client (Claude Code, Codex CLI, Gemini CLI, OpenCode, or custom agents) can use it out of the box.

Related MCP server: nexus-mcp

Architecture

The server sits between your MCP client and the installed CLI tools. When a task arrives via cli_execute, it flows through the resilience pipeline — global time budget, circuit breaker check, process execution, retry logic, and fallback — before returning a redacted, safe response.

Quick Start

npx -y cli-orchestrator-mcp

Prerequisites: Node.js >= 18 and at least one CLI installed and authenticated:

CLIs handle their own authentication inline — no API keys or environment variables required.

Configuration

Claude Code

claude mcp add cli-orchestrator --transport stdio -- npx -y cli-orchestrator-mcp

Codex CLI (~/.codex/config.toml)

[mcp_servers.cli-orchestrator]
command = "npx"
args = ["-y", "cli-orchestrator-mcp"]

Gemini CLI (settings.json)

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

OpenCode (opencode.json)

mcp: {
  servers: {
    "cli-orchestrator": { command: "npx", args: ["-y", "cli-orchestrator-mcp"] }
  }
}

What is MCP and Why Use It?

Model Context Protocol (MCP) is an open standard that lets AI agents discover and use tools through a unified interface. Instead of hardcoding integrations, agents connect to MCP servers that expose capabilities as tools, resources, and prompts.

Why MCP for CLI orchestration?

The goal: Let AI agents focus on what to do, not how to execute it reliably across multiple CLI tools.

MCP Tools

cli_execute

The primary tool. Sends a prompt to a CLI provider with the full resilience pipeline.

Returns: { success, provider, output, duration_ms, fallback_used, attempts, error? }

CLI arguments by provider:

--max-turns for Claude is calculated dynamically based on remaining timeout budget (~1 turn per 30s, min 2, max 25).

cli_route

Recommends the best available CLI for a given agent role.

cli_stats

Returns per-provider health: installed status, path, circuit breaker state, execution/failure/timeout counts, and strengths.

cli_list

Returns all installed CLI providers with their binary paths and declared strengths.

MCP Resources

MCP Prompts

Role-based Routing

Each agent role maps to a primary CLI based on its strengths, with automatic fallback to alternatives:

Resilience Pipeline

Global Time Budget

The entire chain — retries and fallbacks — shares a single time budget (default: 300s). Each attempt receives remainingSeconds, not the full timeout. This prevents the classic problem where 3 providers × 3 attempts × timeout = 9× the expected wait.

Circuit Breaker

Per-provider state machine with separate thresholds for hard failures and timeouts:

Timeouts use a higher threshold (5 vs 3) because a slow provider isn't necessarily broken.

Retry Policy

• Max retries: 2 (3 total attempts per provider)

• Backoff: Exponential (base 1s, max 10s) with ±30% jitter

• Retryable: Rate limits (429), server errors (503), ECONNRESET, ETIMEDOUT

• Non-retryable: Process timeouts (skip directly to fallback), auth errors, permanent failures

Abort Handling

AbortSignal propagates from MCP client through the entire pipeline:

• Cancels running CLI process immediately via execa

• Interrupts retry backoff sleep — no wasted wait time

• Checked between every attempt and every provider

Progress Notifications

During execution, the server sends MCP progress notifications every 5 seconds with enriched context:

[claude] primary, attempt 1, 15s elapsed, 285s remaining
[gemini] fallback #1, attempt 1, 45s elapsed, 255s remaining

Security

Development

git clone https://github.com/lleontor705/cli-orchestrator-mcp.git
cd cli-orchestrator-mcp
npm install
npm run build          # Compile TypeScript
npm run dev            # Run with tsx (no build)
npm test               # Unit tests (CI-safe, no CLIs needed)
npm run test:all       # All tests including stress & integration
npm run lint           # Type-check (tsc --noEmit)
npm run inspect        # Debug with MCP Inspector

Test Suites

Stress tests cover: timeout enforcement, abort/cancellation, concurrent execution (10+), fallback chain timing, large output (5MB+), circuit breaker rapid-fire, large prompt stdin.

Project Structure

src/
  index.ts                  Entry point (stdio transport)
  server.ts                 MCP server factory
  cli/
    definitions.ts          CLI provider configs & arg builders
    detection.ts            Auto-detection with 5-min cache
    executor.ts             Process execution via execa
    circuit-breaker.ts      Per-provider state machine
    resilience.ts           Retry + fallback orchestration
  tools/
    orchestrator.ts         MCP tools, resources, prompts
  types/
    index.ts                TypeScript types & routing table
  utils/
    env-allowlist.ts        Safe environment filtering
    redact.ts               Secret redaction

Tech Stack

License

MIT