Orchestrator MCP

one agent. second opinion. same terminal.

Make Claude Code ask Codex. Make Codex ask Claude Code.
Use the subscriptions already signed in on your computer.
No provider API keys to configure.

See it · Install · What you get · Reviews · Security · Dashboard

Orchestrator MCP is a local Model Context Protocol server that lets one coding agent consult another. It launches the Codex, Claude Code, 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

Without Orchestrator With Orchestrator

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

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

The conversation stays connected from the same client.

Same subscriptions. Less context shuffling.

 Claude Code host  ──►  Orchestrator MCP  ──►  Codex CLI
 Codex host        ──►  Orchestrator MCP  ──►  Claude Code CLI
 Any host          ──►  Orchestrator MCP  ──►  Antigravity CLI (experimental)

                         local routing
                    no provider API keys
                   no same-runtime loops

The host's own runtime is always excluded. Claude Code cannot consult Claude Code through this server, and Codex cannot consult Codex.

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

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.

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 }

See config.example.yaml for every option and an experimental Antigravity example.

3. Add the server to your MCP client

Claude Code

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

Codex

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" }

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.

Run with `uvx` instead

Show the temporary-install configuration

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.

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.
Local history	Store consultations and reviews in SQLite, with an optional loopback dashboard.
Answer-only isolation	Consulted agents cannot edit files, run commands, use MCP tools, or start subagents.

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

The review tools are opt-in: without a consult.review block, they are not advertised at all.

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 one response envelope:

Field	Meaning
`ok`	False exactly when `error` is set. Check this before reading the answer.
`consultation_id`	Handle for continuing the same native conversation.
`content`	Answer, assumptions, uncertainties, follow-up questions, and sources.
`route`	Agent, runtime, model, score, priority, and whether it was selected explicitly.
`usage`	Token counts when the CLI reports them.
`latency_ms`	End-to-end elapsed time.
`error`	Stable error code, message, agent, and sometimes a command the user must run.

If the chosen agent fails, Orchestrator returns that failure. It does not quietly fall through to a different model.

Choose the evidence source

`source_mode`	What the consulted agent receives
`auto`	`document` when context is present; otherwise `model`.
`document`	Only the supplied context, with action tools disabled.
`web`	The target CLI's own web search. `web_turn_limit` bounds it on Claude; Codex is bounded by `timeout_s` alone.
`model`	No context and no web search; answer from model knowledge.

Consult request fields and agent options

Request fields:

Field	Required	Meaning
`capability`	yes	`coding`, `research`, `writing`, `reasoning`, or `review`.
`prompt`	yes	Task or question, up to 100,000 characters.
`context`	no	Evidence, up to 1,000,000 characters.
`source_mode`	no	`auto`, `document`, `web`, or `model`.
`consultation_id`	no	Return the previous ID to continue the conversation.
`target_agent`	no	Choose one configured agent instead of automatic routing.
`conversation_label`	no	Label stored with the consultation, up to 200 characters.

Agent configuration:

Option	Default	Meaning
`runtime`	required	`codex`, `claude`, or `antigravity`.
`command`	required	Executable name or absolute path.
`model`	required	Requested model and, where possible, verified responding model.
`priority`	`100`	Lower wins a score tie.
`enabled`	`true`	Keep the agent configured but out of routing when false.
`scores`	none	0–100 per capability; missing means ineligible.
`web_search`	`false`	Permit `source_mode: web` for this agent.
`reasoning_effort`	unset	`low`, `medium`, `high`, `xhigh`, or `max`; Codex only.

Reviews, with a checkpoint

A consultation asks one agent. A review asks one or more configured reviewers the same question over the same material.

 plan review          approve + run          synthesize
 sends nothing   ──►  reviewers answer  ──►  host records conclusion
      │                    in parallel                │
      └─ scope              one-time token            └─ every Critical kept
         reviewers
         secret hits
         request count

Enable reviews in config.yaml:

consult:
  review:
    reviewers: [codex]          # standard: exactly one
    deep_reviewers: [codex, claude]  # deep: one to five

The workflow is deliberately split:

orchestrator_review creates a plan and sends nothing. The plan shows reviewers, material size, web access, request count, and locations of credential-shaped text.
Show that plan to the user. orchestrator_review_run spends its one-time token and asks reviewers in parallel.
Read every result and call orchestrator_finalize_review. Reviewer replies alone leave the review at awaiting_synthesis.

Finalization must preserve every machine-readable Critical finding, even when other reviewers disagree with it. Deep mode also requires the host agent to record its own findings before seeing the reviewers' answers.

[!IMPORTANT]
Material sent to a reviewer may remain in that vendor CLI's own history. Orchestrator cannot erase Codex, Claude Code, or Antigravity session logs.

Review tool reference

Tool	What it does
`orchestrator_review`	Plan a review and show what would be sent. Sends nothing.
`orchestrator_review_run`	Spend the token and ask reviewers in parallel.
`orchestrator_retry_review`	Re-run failed reviewers without discarding successful answers.
`orchestrator_finalize_review`	Record the host's synthesis; the only path to `complete`.
`orchestrator_cancel_review`	Cancel a review while retaining answers already received.
`orchestrator_apply_fixes`	Return selected findings and fix steps. Changes no files.
`orchestrator_record_fix_round`	Record the host's claim about a fix round.
`orchestrator_test_reviewers`	Check installation and login readiness without sending project material.
`orchestrator_get_review` / `orchestrator_list_reviews`	Read one review or recent review metadata.
`orchestrator_delete_review`	Delete a review, its rechecks, and linked consultations.
`orchestrator_request_delete_all` / `orchestrator_delete_all_reviews`	Preview and confirm deletion of an exact history snapshot.

Reviews default to web: false. Reviewers cannot change files or run commands. orchestrator_apply_fixes is a plan for work the host agent performs; it never applies a patch itself.

Credential-shaped values are masked before storage. secrets="send_as_is" is an explicit escape hatch for a false positive: it requires the exact original goal and context again, sends those originals to the reviewers, and still stores only the redacted copy.

store_full_content: false does not apply here in full. A review's goal and context are stored either way — the second half of the approval handshake reads them back to send what was approved — and reviewer answers and findings are not. That leaves nothing to prove every Critical survived synthesis, so orchestrator_finalize_review refuses, and the review stays at awaiting_synthesis. Finalization is refused on the same grounds when a reviewer answered only in unparseable prose, or when its findings were truncated.

Security model

Property	Guarantee
Credentials	No provider key setting exists. Orchestrator never reads, stores, returns, or refreshes a CLI's own credential. A credential you put in a prompt is material, not a credential here — see the warning below.
Process launch	Commands are executed as argument lists, never through a shell.
Self-consultation	`ORCHESTRATOR_HOST_RUNTIME` comes from the environment and cannot be overridden by a tool call.
Agent permissions	Consulted agents are answer-only, except for the target CLI's bounded search in explicit web mode.
Model identity	A detected mismatch fails with `configured_model_unavailable`. Missing CLI metadata is reported as unverified, not invented.
Storage	SQLite directory permissions are `0700`; the database and managed agent file are `0600`.
Dashboard	Loopback only, with host-header checks and a per-process token.
Review approval	Plans bind the scope to a one-time token before reviewer requests are made.

[!WARNING]
Redaction covers the review path, and only this database. In a review, credential-shaped values are replaced before every insert — the goal, the context, the manifest, and every reviewer's answer. A plain orchestrator_consult is not redacted: its prompts, context, and answers are stored as you sent them. Detection is best-effort pattern matching rather than a scanner with perfect recall, so a secret with no recognizable shape survives it either way. Keep the database private, or set store_full_content: false.

Vendor history is outside all of this. Material sent to a reviewer also lands in that reviewer's own CLI history — Codex writes ~/.codex/sessions/, and the others keep their own logs. Orchestrator cannot redact or erase those files. It does read from them, in two places and for two fields: the Codex adapter opens the rollout file for the session it just ran to recover the model identity the CLI does not otherwise report, and opens the newest rollout to read the rate-limit numbers the service last returned. Nothing else is taken from either file.

Two more limits worth knowing:

CLI error text is shortened and common secret formats are redacted, but an unusual one may still appear in a returned error. Do not forward a raw error envelope somewhere untrusted.
A caller-supplied JSON Schema is trusted input. A pathological regular expression in one can consume a large amount of CPU.

Orchestrator checks structure, routing, permissions, and model identity where observable. It cannot prove that a model's factual claims are true.

Experimental Antigravity runtime

Antigravity (agy) uses its own login and OS keyring, but its isolation is weaker than Codex or Claude Code:

It inherits MCP servers from your agy settings. Headless mode denies tools by default, and Orchestrator fails the consultation if a tool step is reported, but this is detection rather than prevention. Do not enable it if you loosened headless permissions.
It accepts prompts in process arguments rather than standard input. Other users on a shared machine may be able to read those arguments while the process runs.
It has no login-status command, so readiness is reported as unverified until a real request succeeds or fails.

Large prompts are split across turns because Linux limits one argument to 128 KiB. Gemini models have handled this transport in testing; some non-Gemini models may reject the fragments as prompt injection. reasoning_effort and web mode are not available for this runtime.

Local dashboard

The optional dashboard shows agents, routing decisions, prompts, answers, usage, latency, errors, reviews, and recorded fix rounds. It is off by default because it can display everything stored in the consultation database.

consult:
  dashboard:
    enabled: true
    editable: false

Start it separately:

ORCHESTRATOR_CONFIG=/absolute/path/to/config.yaml orchestrator-mcp-dashboard

Open http://127.0.0.1:8765.

Set editable: true to manage consult agents and reviewer selection in the browser. Browser-managed agents are written to ~/.orchestrator-mcp/agents.yaml; the dashboard never rewrites config.yaml, runs login commands, or starts consultations.

Both the MCP server and dashboard read configuration at startup. Restart them to pick up changes.

Configuration

ORCHESTRATOR_CONFIG points to the YAML file. If unset, the server looks for config.yaml in its working directory.

Setting	Default	Meaning
`database_path`	`~/.orchestrator-mcp/consultations.sqlite3`	Consultation and review history.
`managed_agents_path`	`~/.orchestrator-mcp/agents.yaml`	Agents written by the dashboard.
`timeout_s`	`180`	Limit for one consultation turn.
`web_turn_limit`	`8`	Assistant turns allowed in web mode. Enforced by the Claude runtime only.
`store_full_content`	`true`	Set false to keep metadata and routing only — except a review's goal and context, which are stored either way. Reviews cannot be finalized under it — see below.
`review`	absent	Configured reviewers; absent means no review tools.
`dashboard`	off	Loopback history UI and optional agent editor.

consult is the only top-level section. Configuration from releases before 0.4 containing capabilities, model_list, router_settings, or limits is rejected at startup because direct API routing was removed.

System requirements

macOS or Linux. Windows is not currently tested.
Python 3.11, 3.12, or 3.13.
Homebrew or uv.
A stdio MCP client such as Claude Code or Codex.
At least one other supported agent CLI installed and signed in.

Test it

The offline suite uses fake CLI agents. It needs no network and spends no model capacity:

uv sync
uv run pytest -q

Live smoke tests use the agents in your configuration:

ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_consult_live.py
ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_review_live.py

Live tests make real requests and may use paid capacity. Do not run them in CI unless that is intentional.

Troubleshooting

Problem	Fix
`config not found: config.yaml`	Set `ORCHESTRATOR_CONFIG` to an absolute path.
`no_agent_available`	Give an enabled, non-host agent a positive score for the requested capability.
`agent_not_installed`	Use an absolute path for `command`; GUI apps often inherit a smaller `PATH`.
`connection_required`	Run the login command returned in `required_action`, then retry.
Host runtime error	Set `ORCHESTRATOR_HOST_RUNTIME` to `claude`, `codex`, or `antigravity`.
Every consultation starts over	Return the previous `consultation_id` on the next call.
`timeout` during a review	Raise `consult.timeout_s`; high-effort review can take much longer than 180 seconds.
Dashboard changes do not appear	Restart the MCP server; configuration is loaded at startup.
Startup names a removed block	Delete pre-0.4 direct-routing keys: `capabilities`, `model_list`, `router_settings`, and `limits`.

Deliberately not included

No direct provider API routing or provider API-key configuration.
No file edits, shell commands, MCP tools, or subagents for consulted agents.
No automatic fixes; the host agent owns edits and tests.
No streaming; each consultation returns one complete envelope.
No dashboard-initiated consultations.
No automatic configuration reload.
No multi-user or shared state.
No account system for the loopback dashboard.

Contributing

Issues and pull requests are welcome.

Fork the repository and create a branch.
Make the change and add a test that fails without it.
Run uv run pytest -q.
Open a pull request.

Keep private configuration, login data, and consultation databases out of commits. For bugs, open an issue with the response envelope after removing paths, credentials, and other private information.

License

MIT · PyPI · GitHub issues

Built with Pydantic and the Python MCP SDK.