Which integrations are available for this server?

Orchestrates Gemini CLI for research, synthesis, and large-context analysis tasks with automatic fallback. Orchestrates Codex CLI for code generation, refactoring, and full-auto edits with automatic fallback.

How do I use cli-orchestrator-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cli-orchestrator-mcp Route this code review to Claude CLI with fallback to Codex" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

cli-orchestrator-mcp

by lleontor705

Overview Schema Related Servers Score Discussions

TypeScript

Local

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:

CLI	Install	Auth
Claude	`npm i -g @anthropic-ai/claude-code`	`claude` (interactive login)
Gemini	`npm i -g @google/gemini-cli`	`gemini` (Google auth)
Codex	`npm i -g @openai/codex`	`codex` (OpenAI auth)

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?

Without MCP	With cli-orchestrator-mcp
Each agent hardcodes CLI calls	Agents call `cli_execute` — one interface for all CLIs
No retry, no fallback, no circuit breaker	Full resilience pipeline built-in
Agent must know which CLI is installed	Auto-detection — server discovers available CLIs
Agent handles errors and timeouts	Server handles errors, redacts secrets, returns clean output
Switching CLI requires code changes	Change the `cli` parameter — or let `cli_route` pick automatically

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

MCP Tools

Tool	Description
`cli_execute`	Execute a task with full resilience (retry + circuit breaker + fallback)
`cli_route`	Recommend the best CLI based on agent role
`cli_stats`	Health dashboard — installation, circuit breaker, execution stats
`cli_list`	List installed CLI providers with paths and strengths

`cli_execute`

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

Parameter	Type	Default	Description
`cli`	`"claude" \| "gemini" \| "codex"`	required	Target CLI provider
`prompt`	string (max 100KB)	required	Prompt to send
`mode`	`"generate" \| "analyze"`	`"generate"`	Execution mode
`timeout_seconds`	number (10–1800)	`300`	Global timeout budget (covers all retries and fallbacks)
`allow_fallback`	boolean	`true`	Allow fallback to other CLIs on failure
`cwd`	string	—	Working directory for CLI execution

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

CLI arguments by provider:

Provider	Generate mode	Analyze mode
Claude	`-p <prompt> --allowedTools "" --max-turns N`	`-p <prompt> --max-turns N`
Gemini	`-e none -p <prompt>`	`-e none -p <prompt>`
Codex	`exec <prompt> --full-auto`	`exec <prompt> --full-auto`

--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.

Parameter	Type	Description
`role`	`"manager" \| "coordinator" \| "developer" \| "researcher" \| "reviewer" \| "architect"`	Agent role
`task_description`	string (optional)	Task context for better routing

`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

URI	Description
`mcp://cli-stats`	Real-time health dashboard (JSON)

MCP Prompts

Prompt	Inputs	Description
`code_review`	`code` (required), `language` (optional)	Code review for bugs, performance, best practices
`architecture_design`	`requirements` (required)	System architecture from requirements

Role-based Routing

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

Role	Primary	Why	Fallback Chain
Manager	Gemini	Research, trends, large-context analysis	Claude → Codex
Coordinator	Claude	Reasoning, planning, architecture decisions	Gemini → Codex
Developer	Codex	Code generation, refactoring, full-auto edits	Claude → Gemini
Researcher	Gemini	Knowledge synthesis, web search	Claude → Codex
Reviewer	Claude	Code analysis, debugging, quality review	Gemini → Codex
Architect	Claude	System design, architecture patterns	Gemini → Codex

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:

State	Behavior
Closed	Normal — track failures (threshold: 3) and timeouts (threshold: 5)
Open	Reject all calls for 60s cooldown
Half-open	Allow 1 test request — success closes, failure reopens

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

Layer	Protection
Environment	Only essential system vars forwarded (PATH, HOME, TERM, proxy). CLIs authenticate inline.
Secrets	API key patterns (`sk-`, `key-`, `AIza`) automatically redacted from all output and errors
Execution	No shell — commands built as arrays, never string concatenation. No `shell: true`.
Prompts	Large prompts (>30KB) sent via stdin to avoid OS arg-length limits
Process	Each CLI runs in isolated subprocess with configurable timeout and buffer limits (10MB)

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

Command	Scope	Environment
`npm test`	Unit tests — definitions, detection, circuit breaker, resilience	CI — fast, mocked
`npm run test:local`	Integration + stress tests	Local — requires real CLIs
`npm run test:all`	All of the above	Local

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

Component	Technology
Runtime	Node.js >= 18 (cross-platform)
Language	TypeScript 5.7 (strict mode)
MCP SDK	@modelcontextprotocol/sdk
Process exec	execa
Circuit breaker	Custom (lightweight, per-provider)
Validation	Zod
Testing	Vitest

License

MIT

Available Tools

4 tools

cli_executeA

Execute a task on a CLI (Claude, Gemini, or Codex) inline with automatic retry, circuit breaker, and fallback.

ParametersJSON Schema

Name	Required	Description	Default
`cli`	Yes	Target CLI provider
`cwd`	No	Working directory for execution
`mode`	No	Execution mode	generate
`prompt`	Yes	Prompt to send to the CLI
`allow_fallback`	No	Allow fallback to other CLIs on failure
`timeout_seconds`	No	Global timeout budget in seconds (covers all retries and fallbacks)

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide basic traits (not read-only, open-world, not idempotent, not destructive). The description adds valuable behavioral context: automatic retry, circuit breaker, and fallback. These are critical for agent decision-making and go beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and key features. No redundant or filler words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers core purpose and key behaviors but does not elaborate on return values, error handling details, or potential side effects (given openWorldHint=true). With no output schema, some additional context would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 6 parameters. The description does not add parameter-specific details beyond what the schema already provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Execute' and resource 'CLI', listing the three supported providers (Claude, Gemini, Codex). It clearly distinguishes from sibling tools (cli_stats, cli_list, cli_route) by focusing on task execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for executing tasks on a CLI but does not provide explicit when-to-use or when-not-to-use guidance relative to siblings or alternatives. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cli_listA

Read-onlyIdempotent

List installed CLI providers with their paths.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds no new behavioral context beyond confirming it's a list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words, making it highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description mentions output includes 'paths', providing minimal but sufficient detail for a tool with no output schema. Could be more specific about return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With no parameters (schema properties empty), the description does not need to add param details. It implicitly covers the entire operation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('installed CLI providers with their paths'), clearly differentiating from sibling tools like cli_execute, cli_stats, and cli_route.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing installed CLIs but does not explicitly state when to use it versus alternatives or mention exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cli_routeA

Read-onlyIdempotent

Suggest the best CLI for a task based on agent role. Returns recommended provider with reasoning and fallback chain.

ParametersJSON Schema

Name	Required	Description	Default
`role`	Yes	Agent role
`task_description`	No	Brief task description for context

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the output includes reasoning and a fallback chain. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is front-loaded with the main action. No unnecessary words. Efficient and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two parameters, no output schema), the description covers the core functionality. It states the output includes reasoning and fallback, but doesn't specify exact format. Annotations provide safety context. Adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description restates the role and task context but doesn't add new meaning beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Suggest the best CLI for a task based on agent role.' It specifies the resource (best CLI), verb (suggest), and context (agent role and task). This differentiates it from sibling tools like cli_execute, cli_stats, and cli_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a CLI recommendation is needed, but does not explicitly state when to use this tool vs. alternatives like cli_execute or cli_list. No exclusions or when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cli_statsA

Read-onlyIdempotent

Health dashboard showing per-provider installation status, circuit breaker state, and usage stats.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about the specific data shown (per-provider installation status, circuit breaker state, usage stats), which is useful beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no filler. It is front-loaded and efficiently conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only dashboard with no parameters and no output schema, the description fully explains what the tool returns. No additional information is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters; schema coverage is 100%. The description adds no parameter details, but none are needed. Baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a health dashboard showing per-provider installation status, circuit breaker state, and usage stats. This distinguishes it from sibling tools like cli_execute, cli_list, and cli_route, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for viewing health stats, but does not explicitly state when to use it versus alternatives or provide exclusions. Usage context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Disambiguation5/5

Each tool has a distinct purpose: execution, statistics, listing, and routing. No overlap exists; an agent can easily distinguish them.

Naming Consistency5/5

All tools follow the consistent pattern 'cli_<verb>', with verbs (execute, stats, list, route) clearly describing the action. No mixing of conventions.

Tool Count5/5

Four tools is well-scoped for an orchestration server covering execution, monitoring, listing, and routing. Each tool earns its place.

Completeness4/5

Core workflows (execute, monitor, list, route) are covered. Missing provider installation/removal, but that may be out of scope for an orchestrator.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

BrainstormRouter MCP Server
io.github.justinjilg
AI routing, memory, guardrails, and governance. Routes across Claude, GPT, Gemini.
RAG Systems Knowledge & Memory Agent Orchestration
2
RogerRat A
io.github.opcastil11
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Communication Agent Orchestration
21
Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
toolweave
io.github.andreysparish
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
App Automation AI & Machine Learning Agent Orchestration
2

Related MCP Servers

Zen MCP
Agent Orchestration Code Analysis Autonomous Agents
jray2123
F
license
Not graded
quality
D
maintenance
An orchestration server that enables AI agents to collaborate across multiple AI models for advanced code analysis, debugging, and development workflows. It maintains context persistence across sessions, allowing agents like Claude to delegate subtasks to other models like Gemini or O3 seamlessly.
Updated a year ago (2025-06-29 13:53 UTC)
38
nexus-mcp
Autonomous Agents Agent Orchestration Developer Tools
j7an
A
license
A
quality
A
maintenance
MCP server that lets AI models invoke CLI agents (Gemini, Codex, Claude, OpenCode) as tools — with parallel execution, retries, and structured output parsing.
Updated 2 days ago (2026-09-01 14:37 UTC)
5
4
MIT
switchyard
Agent Orchestration Coding Agents Command Line
timjensgrossinger
A
license
C
quality
A
maintenance
Routes coding tasks across multiple AI CLIs (Copilot, Claude Code, Gemini, etc.) with cost-aware tier routing and parallel wave orchestration.
Updated 7 days ago (2026-08-27 15:04 UTC)
55
2
Apache 2.0
overmind-mcp
Agent Orchestration RAG Systems
DeamonDev888
A
license
Not graded
quality
B
maintenance
Orchestrates and controls multiple AI agent CLIs (Claude-Code, Gemini-cli, etc.) via a unified MCP server, enabling complex multi-agent missions with shared memory and HTTP singleton architecture.
Updated a month ago (2026-07-29 04:09 UTC)
521
2
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lleontor705/cli-orchestrator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Why cli-orchestrator-mcp?

Architecture

Quick Start

Configuration

Claude Code

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

Gemini CLI (settings.json)

OpenCode (opencode.json)

What is MCP and Why Use It?

MCP Tools

cli_execute

cli_route

cli_stats

cli_list

MCP Resources

MCP Prompts

Role-based Routing

Resilience Pipeline

Global Time Budget

Circuit Breaker

Retry Policy

Abort Handling

Progress Notifications

Security

Development

Test Suites

Project Structure

Tech Stack

License

Available Tools

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

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

Gemini CLI (`settings.json`)

OpenCode (`opencode.json`)

`cli_execute`

`cli_route`

`cli_stats`

`cli_list`