orchestrator-mcp

<h1 align="center">Orchestrator MCP</h1> <p align="center"> <strong>one agent. second opinion. same terminal.</strong> </p> <p align="center"> Make Claude Code ask Codex. Make Codex ask Claude Code.<br> Use the subscriptions already signed in on your computer.<br> <strong>No provider API keys to configure.</strong> </p> <p align="center"> <a href="https://github.com/crAK1644/orchestrator-mcp/stargazers"><img src="https://img.shields.io/github/stars/crAK1644/orchestrator-mcp?style=flat&color=yellow" alt="GitHub stars"></a> <a href="https://pypi.org/project/orchestrator-mcp-server/"><img src="https://img.shields.io/pypi/v/orchestrator-mcp-server?style=flat&cacheSeconds=3600" alt="PyPI version"></a> <a href="https://pypi.org/project/orchestrator-mcp-server/"><img src="https://img.shields.io/pypi/pyversions/orchestrator-mcp-server?style=flat" alt="Python versions"></a> <a href="https://github.com/crAK1644/orchestrator-mcp/actions/workflows/test.yml"><img src="https://github.com/crAK1644/orchestrator-mcp/actions/workflows/test.yml/badge.svg" alt="Tests"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/crAK1644/orchestrator-mcp?style=flat" alt="MIT License"></a> </p> <p align="center"> <a href="#before--after">See it</a> · <a href="#install">Install</a> · <a href="#what-you-get">What you get</a> · <a href="#reviews-with-a-checkpoint">Reviews</a> · <a href="#the-three-phase-workflow">Workflow</a> · <a href="#security-model">Security</a> · <a href="#local-dashboard">Dashboard</a> </p>

---

Orchestrator MCP is a local Model Context Protocol server that lets one coding agent consult another. It launches the Codex, Claude Code, OpenCode, or experimental Antigravity CLI already installed and authenticated on your machine, routes the request, and returns a structured answer.

It does not ask for a provider key, proxy provider traffic, or silently switch models. Authentication remains inside each vendor's CLI.

Before / After

<table> <tr> <th width="50%">Without Orchestrator</th> <th width="50%">With Orchestrator</th> </tr> <tr> <td valign="top">

1. Copy the prompt, diff, and context.
2. Open another coding agent.
3. Recreate the task and paste everything.
4. Bring the answer back.
5. Repeat when you need a follow-up.

</td> <td valign="top">

1. Call orchestrator_consult.
2. Get the other agent's structured answer.
3. Reuse consultation_id for follow-ups.

The conversation stays connected from the same client.

</td> </tr> </table>

Same subscriptions. Less context shuffling.

 Claude Code host  ──►  Orchestrator MCP  ──►  Codex CLI
 Codex host        ──►  Orchestrator MCP  ──►  Claude Code CLI
 Any host          ──►  Orchestrator MCP  ──►  OpenCode CLI (DeepSeek, Qwen, Kimi…)
 Any host          ──►  Orchestrator MCP  ──►  Antigravity CLI (experimental)

                         local routing
                    no provider API keys
                no same-execution-identity loops

Ordinary orchestrator_consult calls exclude the host's entire runtime: Claude Code cannot use that tool to consult Claude Code, and Codex cannot use it to consult Codex. Reviews and workflows use the narrower (runtime, model) execution identity; when consult.host.model names the host precisely, they may route to a provably different, versioned model on the same runtime. The host can never route work back to its own execution identity.

Install

Homebrew:

brew tap crAK1644/tap
brew install orchestrator-mcp-server

Apple Silicon uses a prebuilt package. Intel macOS and Linux build dependencies from source; use the uvx option if you want a faster, temporary install.

1. Sign in to the agent CLIs

Sign in to each agent you want Orchestrator to use:

codex login
claude auth login

These are the normal Codex and Claude Code login flows. Orchestrator checks readiness, but never reads or stores their credentials.

For OpenCode, sign in once with opencode auth login for whichever provider you plan to consult. Hosted providers only — this server does not run a model on your machine. See the OpenCode runtime section below.

2. Create config.yaml

consult:
  database_path: ~/.orchestrator-mcp/consultations.sqlite3
  timeout_s: 180

  agents:
    codex:
      runtime: codex
      command: codex
      model: gpt-5.6-sol
      priority: 10
      web_search: true
      scores: { coding: 95, research: 90, reasoning: 95, review: 90 }

    claude:
      runtime: claude
      command: claude
      model: claude-opus-4-6
      priority: 10
      web_search: true
      scores: { coding: 90, research: 95, writing: 95, review: 95 }

The key each agent is filed under is its id -- the name callers pass as target_agent, and the name the dashboard writes into URLs. It has to be lowercase, start with a letter or digit, and use only letters, digits, dots, dashes and underscores, up to 64 characters. Anything else is refused at startup with a message naming the key.

See config.example.yaml for a broader annotated configuration, an OpenCode agent, and an experimental Antigravity example.

3. Add the server to your MCP client

<details open> <summary><strong>Claude Code</strong></summary> <br>

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$PWD/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- orchestrator-mcp-server

</details> <details> <summary><strong>Codex</strong></summary> <br>

Add this to ~/.codex/config.toml:

[mcp_servers.orchestrator]
command = "orchestrator-mcp-server"
env = { ORCHESTRATOR_CONFIG = "/absolute/path/to/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

</details>

Restart the MCP client after changing its configuration.

[!TIP] Use an absolute ORCHESTRATOR_CONFIG path. GUI-launched clients often start in a different working directory and inherit a smaller PATH than your terminal.

The client spawns the server and talks to it over stdin, so orchestrator-mcp-server is not a command you start yourself. (The dashboard is the other half of this distribution and is started by hand.) Two flags answer questions from outside a client:

orchestrator-mcp-server --version   # which build the client will spawn
orchestrator-mcp-server --help      # what the environment variables have to say

Both answer and exit without reading your configuration. Anything else on the command line is refused rather than ignored. To make the server read the configuration, run it with no arguments: a file it cannot accept leaves as a message naming the key -- one line for most mistakes, several for a schema violation, never a traceback.

Run with uvx instead

<details> <summary><strong>Show the temporary-install configuration</strong></summary> <br>

No permanent server install is required:

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$PWD/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- uvx orchestrator-mcp-server

For Codex:

[mcp_servers.orchestrator]
command = "uvx"
args = ["orchestrator-mcp-server"]
env = { ORCHESTRATOR_CONFIG = "/absolute/path/to/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

The PyPI distribution is named orchestrator-mcp-server; the shorter PyPI name belongs to another project.

</details>

What you get

| Capability | What it does | |---|---| | Second opinion | Ask another vendor's coding agent about code, research, writing, reasoning, or review. | | Connected follow-ups | Continue the native CLI session by returning its consultation_id. | | Predictable routing | Rank configured agents by capability score, priority, then agent ID. | | Explicit model choice | Verify the responding model when the CLI exposes that information; fail on a detected substitution. | | Review panel | Ask one reviewer, or up to five in deep mode, over the same approved material. | | Three-phase workflow | Run a whole job — research and planning, implementation and testing, review and fixing — with eligible models bound to steps their runtime and configured execution mode permit. | | Slash commands | Drive consultations, reviews and workflows by name, with their checkpoints written down rather than hoped for. | | Local history | Store consultations, reviews, and workflows in SQLite, with an optional loopback dashboard. | | Answer-only isolation | Codex, Claude Code, and OpenCode are prevented from using action tools; explicit web mode enables only the target runtime's web-search facility. Experimental Antigravity detects and fails reported tool use but cannot yet prevent it. |

The consultation tools

| Tool | Purpose | |---|---| | orchestrator_consult | Start or continue a structured consultation. | | orchestrator_list_consult_agents | Show configured agents, routing scores, installation, and login readiness. | | orchestrator_get_consultation | Retrieve a stored consultation, its turns, usage, and routing decision. | | orchestrator_delete_consultation | Delete one ordinary consultation and its local turns. | | orchestrator_request_delete_all_consultations / orchestrator_delete_all_consultations | Preview and confirm deletion of an exact ordinary-history snapshot. |

These deletion tools remove local SQLite records only. They cannot erase a consulted runtime's own CLI or provider history.

Three independent opt-ins: the consult tools are always advertised, the review tools only with a consult.review block, the workflow tools only with a consult.workflow block. Reviewers are not a workflow, and a workflow is not reviewers.

Slash commands

The server also serves MCP prompts, which a client that speaks prompts/list renders as slash commands. In Claude Code they appear as /mcp__<server-name>__<command>, where the server name is whatever you called it in your MCP client config — /mcp__orchestrator__review for the orchestrator entry shown above.

| Command | Arguments | What it expands to | |---|---|---| | consult | question, agent | Ask another agent, keep the consultation_id, and report the disagreements rather than smoothing them out. | | review | goal, deep | Plan the review, show the plan and secret_hits, stop for the user, then run and finalize. | | workflow | goal, workdir | Start the workflow, then plan-step, stop, run-step, check status, one step at a time. | | status | workflow_id | Report which reviews and workflows are unfinished and what each is waiting on. |

Every argument is optional; a command with none expands into an instruction to ask you for the missing part. review and workflow are advertised only when their tools are, on the same two answers — a command that could only reply "no reviewers are configured" costs a round trip and reads like a bug.

Two things worth being clear about. Nothing is installed. These arrive over the same stdio connection as the tools: no command directory, no generated markdown, nothing written to your machine, and a client that does not speak prompts/list is unaffected. A prompt is text, not an action. Expanding one consults nobody, sends nothing, and starts no workflow — it reaches the host's conversation as if you had typed it, and the host then calls the tools, checkpoints and all. They exist because the flows worth having here are handshakes, and a host driving them from tool descriptions alone tends to skip the checkpoint that makes them worth having.

How consultation works

orchestrator_consult selects the eligible agent with the highest capability score. Lower priority wins a score tie; agent ID breaks the final tie. A missing capability or a score of 0 makes an agent ineligible.

The selected CLI runs under its existing login and returns o