Orchestrator MCP

Use Codex from Claude Code, or Claude Code from Codex, through the subscriptions you already have.

If you pay for more than one AI subscription, Orchestrator MCP helps you use each model for what it does best. It runs the installed Codex or Claude Code CLI under your existing login, routes the work automatically, prevents an agent from consulting itself, and keeps a record of every consultation.

No provider API key is required for this setup. Authentication stays inside the Codex and Claude Code command-line apps on your computer. Orchestrator only checks whether they are signed in — it never reads, stores, or returns a credential. The optional direct routing path described later is the only part that talks to a provider endpoint, and therefore the only part that needs a key.

With Orchestrator MCP, your agent can:

• ask another vendor's agent for coding, research, writing, reasoning, or review help;
• continue a consultation across several turns;
• choose the best configured agent automatically;
• review consultation history in a local dashboard.

Quick start

1. Install with Homebrew

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

Apple Silicon uses a prebuilt package. Intel macOS and Linux build the dependencies from source, which can take about 15 minutes. On those systems, the uvx setup shown below is usually faster and does not install the server permanently.

2. Sign in to the agent CLIs

Sign in to each agent you want Orchestrator to use:

codex login
claude auth login

These commands use the normal Codex and Claude Code account login. Orchestrator only checks whether the CLI is signed in; it does not read or store the login credentials.

3. Create a configuration file

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 full annotated example is in config.example.yaml.

4. Add it to your MCP client

For Claude Code:

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

For 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 your MCP client after changing its configuration.

Install with uvx instead

You can run the same server without installing it permanently:

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 project is published to PyPI as orchestrator-mcp-server. The shorter PyPI name belongs to another project.

What it does

Orchestrator has two independent paths. They can be used together or one at a time.

The consultation path is the reason this project exists. The direct routing path is older and optional. Configure the consult section only, and the two ask tools are never registered.

The consultation path

The consult tool starts the Codex or Claude Code command-line app already installed and signed in on your computer. Claude Code can ask Codex, and Codex can ask Claude Code, using the subscriptions already connected to those CLIs.

The consulted agent can answer, but it cannot change files, run commands, use MCP tools, or start subagents. Orchestrator also removes agents that use the same runtime as the caller, which prevents consultation loops.

ORCHESTRATOR_HOST_RUNTIME tells Orchestrator which agent is making the request. It must be claude or codex. The server excludes that runtime from the available targets, so a host can never consult itself. The value comes from the environment only; a calling model cannot set it as a tool argument.

consult

What you send:

Source modes:

What you get back. Every outcome uses the same envelope:

All five content fields are required of the consulted agent. A list may be empty but never missing: "no uncertainties" is a claim the agent has to make, not something you infer from an absent key.

Consultation error codes: agent_not_installed, connection_required, configured_model_unavailable, agent_unavailable, session_not_found, session_busy, session_target_mismatch, protocol_validation_failed, web_search_unavailable, transport_error, timeout, invalid_request, no_agent_available.

Behaviour worth knowing:

• Routing is predictable: the highest capability score wins, then the lowest priority number, then the agent ID. A score of 0, or a capability left out of the map, means that agent is not eligible.
• If the chosen agent fails, that is the answer. Orchestrator does not quietly try the next one.
• A consultation is pinned to the agent, runtime, and model that started it. Naming a different target_agent later returns session_target_mismatch rather than switching.
• If the CLI answers as a different model than the one configured, the consultation fails with configured_model_unavailable instead of returning an answer from a model nobody chose. For Codex this is checked against the session log the CLI writes under ~/.codex/sessions, because codex exec --json on 0.146 does not name the model anywhere in its output. If neither source names one, the configured name is reported unverified — absent metadata is not treated as evidence of substitution, so a quiet release of either CLI does not become an outage.
• Two processes cannot advance the same consultation at once. The second gets session_busy.
• Nothing is ever run through a shell. Every CLI call is an argument list, and the prompt is written to the process's standard input.

list_consult_agents

Returns the host runtime and one row per configured agent: agent_id, runtime, model, priority, enabled, scores, web_search, excluded_as_host, plus installed, authenticated, and a detail string from the last status check.

get_consultation

Takes a consultation_id and returns the stored consultation: target agent, runtime and model, capability, the source modes used, label, status, whether a native session is still bound, timestamps, every turn, and the routing decision that picked the agent.

Agent options

Each entry under consult.agents accepts:

Consultation settings

The direct routing path

ask and list_capabilities route a request to a model deployment through LiteLLM. This is separate from the consultation path and, for any hosted provider, it is the part that needs an API key.

The ask tool routes a named capability, such as coding or research, to the deployment assigned to it. LiteLLM handles load balancing, retries, cooldowns, and fallbacks. A deployment can be a local model or another endpoint already configured for LiteLLM.

What you send:

What you get back:

Routing error codes: invalid_request, no_deployment, upstream_error, rate_limited, context_exceeded, schema_validation_failed, timeout, content_filtered, auth_failed, output_truncated.

list_capabilities returns each configured capability with its description, the deployments behind it, and the capabilities it falls back to.

You can leave capabilities and model_list out of config.yaml if you only want subscription-based consultations. In that setup, Orchestrator only shows the three consultation tools.

Dashboard and consultation history

The dashboard is off by default because it can display every stored consultation.

Enable it in config.yaml:

consult:
  dashboard:
    enabled: true
    editable: false

Start it separately:

ORCHESTRATOR_CONFIG=config.yaml orchestrator-mcp-dashboard

Open http://127.0.0.1:8765. The dashboard only listens on your computer. It shows configured agents, recent consultations, prompts, answers, routing, usage, latency, and errors. host accepts only a loopback address, and a request whose Host header names anything else is refused.

The dashboard runs as its own process and reads the configuration once, at startup — the same as the MCP server. Neither one notices a change the other made. It never runs a login command; the connect commands on the page are text for you to copy.

Editing agents from the browser

Set editable: true and open /agents. This is a second flag on purpose: turning the dashboard on gets you a window, and editing is a different thing to agree to.

What the form can change: consult agents only — runtime, command, model, priority, enabled, the five capability scores, web search, and reasoning effort. Nothing else is editable from the browser. capabilities, model_list, router_settings, limits, timeout_s, web_turn_limit, store_full_content, and the dashboard's own host and port are config-file settings.

Agents you add here are written to ~/.orchestrator-mcp/agents.yaml, with 0600 permissions in a 0700 directory. The dashboard never writes config.yaml. Agents defined there are listed on the page but not editable, and the page says so.

The two files are merged at startup and neither one wins. An agent ID defined in both files stops the server from starting, and the error names the ID and both paths. There is no precedence rule, because a precedence rule is how you get an edit that saves and then does nothing. The form refuses a save that would create that state, and it checks config.yaml as it is on disk rather than as it was when the dashboard started — so an agent you add to that file by hand is refused here right away, and one you delete from it stops being refused. Only the IDs are re-read, so it works in one direction: an agent added to config.yaml while the page is open does not appear in the read-only table until the dashboard restarts, but it is still enough to block a save the next startup would reject.

If config.yaml is empty or half-written when the page reads it — the state an editor leaves for a moment while saving — the check falls back to the agents the dashboard started with. Reading that moment as "this file defines no agents" is exactly how a duplicate would slip through.

An agent that exists in both files keeps its row and its delete button, since deleting the copy here is the only fix available from the browser.

Changes take effect when the MCP server next starts. The page says so after every save, and it warns you when the running server is on an older configuration than the one on disk.

By default, consultation prompts and answers are saved in SQLite. Set store_full_content: false to save only metadata and routing information.

Configuration

ORCHESTRATOR_CONFIG points to the configuration file. If it is not set, the server looks for config.yaml in its working directory.

Important sections:

Several deployments may use the same capability name. LiteLLM will balance requests between them.

You may configure only ask, only consult, or both. If consult is missing, the consultation tools are not shown. If capabilities and model_list are both missing, the model tools are not shown.

The default limits block, which applies to ask only:

Invalid configuration is rejected when the server starts instead of failing during a request.

Guardrails and limits

Orchestrator MCP checks request and response structure. It does not know whether a model's factual claims are true.

It does enforce these rules:

• Unknown capabilities and oversized requests are rejected before contacting a provider.
• Structured replies are checked locally against your JSON Schema.
• Truncated, filtered, malformed, and failed answers are returned as errors, not partial answers.
• Errors use stable codes such as connection_required, timeout, and session_busy.
• The response always identifies the model and whether a fallback was used.
• Consulted agents run in answer-only mode and may not act on your computer.
• A consulted agent cannot route work back to the same agent runtime.
• Login credentials are not read or stored. Authentication stays in the vendor's CLI.

Important limits:

• Treat caller-provided JSON Schemas as trusted input. A complex regular expression can use a large amount of CPU.
• Provider error text is shortened and common secret formats are redacted, but unusual secrets may still appear. Do not forward errors to an untrusted place.
• The consultation database may contain full prompts and answers. Keep it private or disable full-content storage.

System requirements

• macOS or Linux. Windows is not tested; the Homebrew instructions are macOS only, and the server has only been run on POSIX systems.
• Python 3.11, 3.12, or 3.13
• Homebrew or uv
• An MCP client that supports stdio, such as Claude Code or Codex
• The Codex or Claude Code CLI installed and signed in
• For optional direct routing: a model endpoint configured through LiteLLM

Testing

Run the offline test suite:

uv sync
uv run pytest -q

The tests use fake providers and CLI agents. They do not need a network connection or spend money.

To test your real model configuration:

uv run python smoke_live.py

To test real Codex and Claude Code consultations:

ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_consult_live.py

The smoke tests make real requests and may use paid capacity from your configured services. Do not run them in CI unless that is intentional.

Troubleshooting

Bug reports

Open an issue and include the returned response envelope. Remove paths, credentials, and other private information before attaching your configuration.

For routing or retry problems, a LiteLLM debug log is useful:

LITELLM_LOG=DEBUG uv run python smoke_live.py 2>debug.log

Contributing

Issues and pull requests are welcome.

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

Keep private configuration, login data, and consultation databases out of commits.

Releasing

1. Update version in pyproject.toml.
2. Create a GitHub Release tagged vX.Y.Z.
3. The release workflow runs the tests, checks the version, and publishes to PyPI using Trusted Publishing.
4. Update the formula in the homebrew-tap repository and rebuild its Apple Silicon bottle.

Not included

Deliberately out of scope for now:

• Consulted agents cannot act. No file changes, no commands, no MCP tools, no subagents. Answers only.
• No streaming. A consultation returns one complete envelope.
• No consultations from the dashboard. The page reads history and edits agent configuration; it has never started an agent process, and that is worth keeping until there is a reason to give it up.
• No runtime settings in the dashboard. Timeouts, storage, and the dashboard's own host and port are config-file settings. A page that can change the port it is served on is a footgun that deserves its own design.
• No accounts on the dashboard. Its protection is a loopback bind, a Host header check, and a per-process token — enough for one person on one machine, not for a shared host.
• No automatic restart. Both processes read the configuration once, at startup.
• No multi-user or shared state. One SQLite file, local to your computer.
• No semantic intent routing, streaming tool results, automatic PII removal, or shared Redis state on the routing path. LiteLLM can provide some of these through its own configuration and callbacks.

License and support

This project uses the MIT License.

• GitHub issues
• PyPI releases
• LiteLLM routing documentation
• Model Context Protocol

Built with LiteLLM, Pydantic, and the Python MCP SDK.