Skip to content
Orcho Docs

Start 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.

Run this once from a shell:

Terminal window
orcho workspace init ~/www/my-workspace
source ~/www/my-workspace/workspace-orchestrator/orcho-env.sh

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 installation handoff. Register one Orcho MCP server per workspace, restart or reload the client so it refreshes the tool catalogue, then continue with orcho_workspace_info.

The init step also creates the workspace run storage, orcho-env.sh, local workspace config, and extension-point folders. Read Workspace model when you want the deeper mental model.

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 workspace-orchestrator;
  • 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, but the project still needs normal developer verification (git diff, your tests) before you call the work done.

Section titled “Related”