Skip to content
Orcho Docs

Start Orcho Runs with MCP

MCP is the path for using Orcho from an LLM-aware client instead of operating only from the terminal.

Use this path when you want the client to start a run, read state, inspect evidence, diagnose pauses, and help you choose the next safe action.

This page is intentionally the short path. Once the setup and first run are clear, move to Expert MCP control loop for the full client-captain workflow.

MCP start

The first MCP step is not an MCP tool call. Run orcho workspace init first: it creates the workspace, prints the MCP server setup block, and gives the client the workspace it must control. After the client reloads, verify the connection, run a mock pass, then start one real feature-shaped run.

workspace initprinted MCP setupclient reloadmock first

1. Initialise the workspace

Section titled “1. Initialise the workspace”

This is the bootstrap step. MCP starts here, because the client needs a workspace-scoped Orcho server before it can see or control runs.

One prerequisite: the MCP server must be available either as the native orcho-mcp command from the standard install, or as the containerized stdio server from Installation methods. For the native path, verify:

Terminal window
orcho-mcp --help

The shape to remember: one MCP server process, native or Docker, bound to one workspace through the ORCHO_WORKSPACE environment variable.

Run this once from the existing project:

Terminal window
cd ~/www/my-project
orcho workspace init

After the command finishes, read the terminal output before opening the MCP client. orcho workspace init prints the client setup block:

  • terminal-client commands such as codex mcp add ... or claude mcp add ...;
  • JSON mcpServers snippets for clients that use config files;
  • the ORCHO_WORKSPACE value that binds the MCP server to this workspace;
  • the verification call to run after the client restarts.

That printed block is the native installation handoff. For example, the Claude Code registration has this shape; copy the actual path and server name printed for your project:

Terminal window
claude mcp add orcho-my-project \
  --env ORCHO_WORKSPACE="/absolute/managed/workspace/path" \
  -- "$(command -v orcho-mcp)"

Register one Orcho MCP server per workspace, restart or reload the client so it refreshes the tool catalogue, then continue with orcho_workspace_info. For Docker-based MCP registration, use the JSON or docker run ... orcho-mcp shape in Installation methods.

The repository is not moved. Init registers it in place and creates external run storage, orcho-env.sh, local workspace config, a plugin scaffold, and agent-guidance templates. Read Workspace model for the single-project and shared-product topologies.

2. Check the client sees Orcho

Section titled “2. Check the client sees Orcho”

Call:

orcho_workspace_info

Check:

  • the workspace path is the one you expect;
  • the runs directory is inside the workspace printed by init;
  • recent projects are either empty or belong to this workspace.

Do not start a run until this is correct.

3. Choose the profile

Section titled “3. Choose the profile”

Call:

orcho_profiles_list

For a normal first run, choose feature. It gives the reader the real Orcho shape without jumping straight into cross-project or expert tuning:

plan -> validate_plan -> implement -> review_changes -> repair_changes -> final_acceptance

Use small_task only when you deliberately want a thinner envelope.

If the client should recommend the work shape, use the auto-detect selector instead of a concrete profile. It is an advisor path: Orcho resolves a concrete profile and mode, records the rationale/confidence, and the client should show that decision back to the operator. Read Profile advisor before making it the default client behavior.

4. Start with a mock run

Section titled “4. Start with a mock run”
orcho_run_start(
  project_dir="/abs/path/to/project",
  task="Add input validation to the login endpoint.",
  profile="feature",
  mock=True,
  max_rounds=2,
)

The mock run is a protocol rehearsal. It should finish quickly and produce a run id, status snapshots, events, and evidence surfaces without touching your project.

5. Watch the state loop

Section titled “5. Watch the state loop”

Use bounded state first:

orcho_run_status(run_id="<run_id>")
orcho_run_events_tail(run_id="<run_id>")
orcho_run_evidence(run_id="<run_id>", slice="findings")
orcho_run_diagnose(run_id="<run_id>")

The client should not scrape raw logs to guess what happened. It should read status, events, evidence, and diagnosis in that order.

6. Start the real run

Section titled “6. Start the real run”

When the mock path is clear:

orcho_run_start(
  project_dir="/abs/path/to/project",
  task="Add input validation to the login endpoint.",
  profile="feature",
  mock=False,
  max_rounds=2,
)

Now the worker runtime can edit files. Use a branch or a disposable copy until you trust the workflow.

What comes after the first run

Section titled “What comes after the first run”

Setup is done. The rest of the lifecycle — reading a typed pause, deciding a handoff, resuming from a checkpoint, and closing with evidence — is a repeating loop, not a one-off. That loop is the flagship workflow in Expert MCP control loop.

One rule starts now, though: MCP tells you what Orcho recorded; it does not invent project readiness. Before relying on real runs, configure the generated project plugin from the repository’s existing tests, lint, builds, analysis, and CI evidence. Review the diff and official verification receipts, while CI remains an independent repository gate. See Project tuning and plugins and Scheduled verification setup.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Section titled “Related”