MCP setup

MCP is the tool layer. It lets Codex call the orchestrator without copying shell commands by hand.

Codex config

Add this to Codex config.toml:

[mcp_servers.claude-code-orchestrator]
command = "python"
args = [
  "-c",
  "import os,sys,runpy; home=os.environ.get('CODEX_HOME') or os.path.join(os.environ.get('USERPROFILE') or os.path.expanduser('~'), '.codex'); root=os.environ.get('CC_ORCHESTRATOR_HOME') or os.path.join(home, 'skills', 'claude-code-orchestrator', 'scripts', 'cc-orchestrator'); sys.path.insert(0, root); runpy.run_path(os.path.join(root, 'server.py'), run_name='__main__')"
]

[mcp_servers.claude-code-orchestrator.env]
PYTHONIOENCODING = "utf-8"
PYTHONUTF8 = "1"

On Windows, the safe installer can write Codex and Claude MCP config after making backups:

powershell -ExecutionPolicy Bypass -File .\install\install-mcp.ps1

The same example lives in:

docs/mcp.codex.example.toml

Tools

Tool	What it does
cc_healthcheck	Checks Claude Code, CCSwitch, Python, and config
cc_list_profiles	Lists CCSwitch profiles with secrets redacted
cc_pick_profile	Shows which profile and model a role would use
cc_run_agent	Runs one Claude Code worker
cc_run_streaming_agent	Starts a background worker with live events.ndjson
cc_poll_run	Polls compact controller progress by default
cc_summarize_run	Writes and returns controller artifacts plus rolling checkpoints
cc_compact_events	Compacts raw events into a timeline and deduplicated tool summary
cc_run_status	Lists active workers or inspects one run
cc_stop_run	Stops one worker by run id
cc_send_instruction	Restarts a run with recovered context and a new instruction
cc_spawn_role_team	Starts several role workers
cc_collect_team_results	Summarizes team output
cc_cross_review	Starts second-round reviewer workers
cc_preflight_write_scope	Writes allowed/denied path rules
cc_check_write_scope	Blocks acceptance when writes cross the scope
cc_diff_summary	Summarizes changed files and risk
cc_secret_scan_run	Scans run logs and diff for secrets
cc_verify_run	Runs diff, scope, secret scan, tests, and report
cc_rollback_run	Conservatively rolls back a safe run diff
cc_benchmark_model	Plans or runs one benchmark task
cc_benchmark_suite	Plans or runs fixed benchmark tasks
cc_calibrate_policy	Saves local model preference notes
cc_model_registry	Builds the local model capability database
cc_local_policy	Reads or writes user-owned routing overrides
cc_score_worker	Grades a worker run and updates quality history
cc_prompt_pack	Lists or renders reusable worker prompts
cc_cost_guard	Sets concurrency and timeout guardrails
cc_usage_summary	Estimates daily usage from logs
cc_queue_submit	Submits a queued worker job
cc_queue_tick	Starts queued jobs up to a limit
cc_queue_status	Reads queued, running, done, failed, timed_out, and cancelled state
cc_queue_cancel	Cancels a queue job
cc_queue_policy	Reads or writes queue concurrency, retry, and timeout policy
cc_upgrade_check	Preserves local preferences across upgrades
cc_mock_stream_test	Tests streaming without spending model quota
cc_dashboard	Generates a local HTML dashboard
cc_open_run_folder	Opens a run folder
cc_export_report	Exports a run or team report
cc_run_visible_agent	Opens a visible Claude Code worker window
cc_last_run	Reads the latest run metadata and output tails
cc_git_diff	Returns a capped git diff for review
cc_workflow_plan	Builds the configured multi-agent workflow plan
cc_write_claude_md	Writes project instructions for Claude Code workers
cc_score_models	Scores models discovered from CCSwitch
cc_write_strategy_reports	Writes model score and strategy reports

Safe defaults

By default, worker runs use plan mode.

Pass allow_write=true only after Codex has decided that file edits are needed and the write scope is clear.

Secrets are redacted from tool output and persisted logs, but prompts should still avoid asking for raw secrets.

Smoke test

After restarting Codex, call:

cc_healthcheck
cc_list_profiles
cc_score_models

If these work, Codex can route workers through MCP.