orcho-mcp

Model Context Protocol server for Orcho.

Exposes orcho's runtime to MCP-aware clients (Claude Code, Cursor, Zed, and other MCP-speaking tools) over stdio. It lets clients drive Orcho as a production harness and control plane for agentic software delivery: act, observe, decide, inspect, and resume without raw log scraping.

📖 Documentation: docs.orcho.dev

_{An AI client (here Claude Code) driving a run through this server — orcho_run_start → orcho_run_watch → orcho_run_evidence → verdict, all typed, no log scraping. Real session; the run is mock=True. Interactive version: docs.orcho.dev.}

Status: public alpha. Core control-loop surfaces are available:

• Act: orcho_run_start / orcho_run_resume / orcho_run_cancel with L4-test-pinned semantics (process-group signal handling, supervisor-owned restart-recovery, race-aware cancel).
• Observe: orcho_run_status answers "What is happening / what should I do next?"; orcho_run_history and orcho_run_events_tail are read-only, polling-friendly context.
• Route: orcho_run_diagnose and orcho_workspace_pending_decisions classify the continuation subject and visible decision work.
• Decision support: orcho_handoff_advice / orcho_delivery_gate explain sanctioned choices without applying them.
• Decide: orcho_phase_handoff_decide resolves runtime-published phase-handoff actions; orcho_delivery_gate / orcho_delivery_decide expose and resolve post-release delivery or correction; orcho_criterion_decide records an operator's accept/reject on a human acceptance criterion. Decision tools never invent actions, never infer a verdict from conversation, and never spawn a pipeline process.
• Inspect: orcho_run_evidence answers "What happened / what proves it?"; orcho_run_diff answers "What changed?"
• Measure: orcho_run_metrics answers "How much did it consume?" with tokens, duration, phase breakdown, and cost-reference fields when available.
• Reclaim: orcho_workspace_cleanup_report previews what retained checkouts could be freed and what is protected; orcho_workspace_cleanup_reclaim acts only on a selection the operator confirmed.

Live progress: orcho_run_watch emits ordered notifications/progress when the MCP request carries a progressToken. Clients that don't carry one poll orcho_run_status / orcho_run_events_tail against the same run state.

Install

Choose an install path:

If pipx is missing, install it first. On macOS with Homebrew:

brew install pipx
pipx ensurepath
exec zsh -l

For Linux or Windows, use the official pipx installation guide.

Recommended CLI install

Use the orcho distribution when you want both the Orcho commands and the MCP server available from your shell. Since orcho 0.1.1 the server ships by default — no extra needed. pipx keeps the command set isolated from the current project or Python environment.

pipx install orcho
orcho-mcp --help

Since orcho 0.1.1 this includes the MCP server by default. The [mcp] and [all] extras remain as no-op aliases.

Containerized MCP server

Use Docker when an MCP client should start an isolated server over stdio:

docker run --rm -i \
  -v /path/to/my-workspace:/workspace \
  -v ~/.orcho-auth:/agent-auth:ro \
  -e ORCHO_WORKSPACE=/workspace/workspace-orchestrator \
  ghcr.io/symphos-ai/orcho \
  orcho-mcp

Inside that server, projects live under /workspace/<project-name>. The orcho Docker docs cover one-time credential bootstrap and custom project toolchains.

Direct MCP package install

Use pip when you intentionally want orcho-mcp in the active virtual environment, CI image, devcontainer, or Docker image.

python -m pip install orcho-mcp

This pulls orcho-core (the engine), the official mcp Python SDK, and the runtime pieces orcho-mcp depends on.

Create a workspace

Orcho writes run state into an Orcho workspace. Start by pointing it at the folder that groups your project repos:

orcho workspace init ~/www/my-workspace

The command creates ~/www/my-workspace/workspace-orchestrator/, including .orcho/ settings and extension-point guides, and prints the MCP config snippet for that workspace. To write the snippet directly into a project-local MCP config:

ORCHO_MCP_COMMAND="$(command -v orcho-mcp)"

orcho workspace init ~/www/my-workspace \
  --mcp-config ~/www/my-workspace/.mcp.json \
  --mcp-server-name orcho-my-workspace \
  --orcho-mcp-command "$ORCHO_MCP_COMMAND"

ORCHO_MCP_COMMAND must point to the command your MCP client can run. For packaged installs this is normally orcho-mcp. For source installs, use the absolute path inside the Orcho environment, for example /Users/me/orcho-preview/orcho-core/.venv/bin/orcho-mcp.

Each MCP server process owns one workspace through ORCHO_WORKSPACE. For multiple workspaces, add multiple MCP server entries.

Register with an MCP-aware client

Each client has its own MCP registry/config format. Use docs/mcp_client_setup.md for copy-paste instructions for Codex CLI/app, Claude Code, Gemini CLI, the Claude app, and Antigravity.

What's inside

npx @modelcontextprotocol/inspector orcho-mcp

Opens a web UI on localhost showing every registered tool, resource, and prompt with full JSON schemas — Anthropic's official Inspector ≈ Swagger UI for MCP.

A static catalogue is also committed at docs/mcp_schema.json — the same shape, snapshotted in CI.

Control loop

The full contract — starting, observing, resuming, cancelling, deciding, and inspecting runs through the MCP wire — lives in docs/run_lifecycle.md. The complete multi-axis decision graph is documented in docs/architecture/control_state_machine.md. Tool docstrings stay terse; those files are the long-form references.

Tool naming is consistent: every run-lifecycle tool is orcho_run_<verb>. State-transition and inspection tools sit beside that group with their own names:

When choosing a read tool, start from the question:

Reclaiming space is deliberately two calls. orcho_workspace_cleanup_report is read-only and mints a confirm_token for the exact selection it just showed; orcho_workspace_cleanup_reclaim refuses any token that does not match the live workspace. A model cannot tidy up on its own initiative, and a selection that changed after the operator reviewed it is refused rather than swept. Separate tool names also mean a client that allowlists the preview has not thereby allowlisted the removal.

For an end-to-end walkthrough of the full control loop with code, see docs/control_loop_walkthrough.md.

Current public-alpha boundaries

• orcho_run_live_status is a bounded mono-run card. Cross runs use the broader status, event, evidence, and sub-run projections. Its closed state_class distinguishes healthy phase-empty starting from core-owned stalled; stalled runs are diagnosed/inspected and cancelled only when MCP owns control, never resumed or watched as active.
• orcho_workspace_pending_decisions currently aggregates phase handoffs; it is not a universal inbox for every delivery and cross-gate decision.
• a CLI-started or otherwise foreign run can be fully inspected, but mutation is refused as inspect_only when this MCP server does not own its supervisor record.
• core owns the lifecycle and allowed actions. The MCP layer projects that state; it does not create a second state machine.

Architecture

orcho-mcp is one of the public Orcho runtime packages:

• orcho-core — pipeline runtime + CLI (Apache-2.0).
• orcho-mcp — MCP server, this repo (Apache-2.0).

The post-v1 cross-MCP consumer roadmap (orcho-as-MCP-client — pipeline agents calling external GitHub / Linear / Slack MCP servers) is documented in orcho-core/docs/plans/2026-05-06-cross-mcp-orchestration.md.

For contributor-facing architecture and test guidance:

• docs/architecture/control_state_machine.md maps core lifecycle state, MCP projections, pending decisions, delivery, continuation lineage, and the typed tool edge for each supported transition.
• docs/architecture/mcp_boundaries.md describes the package boundaries enforced by the architecture tests.
• docs/architecture/observation_delivery.md defines the durable replay contract for MCP observation and notification use.
• docs/architecture/workspace_cleanup_confirmation.md explains the report/reclaim split and the confirmation token that keeps a destructive sweep tied to a selection an operator actually reviewed.
• docs/testing.md explains the test philosophy, layer model, fixture style, and verification commands.

License

Apache-2.0. See LICENSE.