Expert MCP control loop

The first MCP path should stay short: configure the client, verify the workspace, run mock=True, then start one real feature run.

This page is the deeper version. Use it when an MCP-aware client is not merely launching Orcho, but acting as a lifecycle captain: reading typed state, inspecting proof, asking for operator decisions, and resuming work from the right control point.

CLI is the strongest first perception surface.
MCP is the strongest lifecycle control surface.

When this mode fits

Use the expert MCP loop when at least one of these is true:

the run can stop on plan, review, handoff, or final-acceptance decisions;
the operator cannot watch the terminal continuously;
a client needs to explain “what happened, why, and what is safe next”;
evidence, receipts, metrics, and resume state matter after the live stream;
the client is building a delivery cockpit, IDE side panel, or assistant flow around Orcho.

For a tiny one-shot edit, use the CLI first. MCP becomes valuable when typed state saves the operator from reconstructing a run from prose logs.

Division of labor

Layer	Owns
MCP client	Conversation, user-facing UX, polling rhythm, summaries, and asking the operator for decisions.
Orcho	Run lifecycle, profiles, phase state, evidence, artifacts, metrics, handoff state, and resume points.
Worker runtime	The phase work itself: planning, implementation, review, repair, or acceptance according to the profile.
Project toolchain	Final project verification such as `git diff`, tests, lint, and local domain checks.

The client should not pretend to be the delivery system. It asks Orcho for the run state, asks the operator when a human decision is required, and verifies the project with normal project tools before calling the work done.

Flagship loop

The expert loop is an ordered control path, not a bag of tools.

workspace -> profile -> mock run -> real run
  -> status/events -> evidence/diagnose
  -> decide handoff or delivery gate
  -> resume or follow up
  -> evidence/metrics/history
  -> project verification

1. Establish the workspace

orcho_workspace_info
orcho_profiles_list

The client should show the workspace path, runs directory, available profiles, and the profile it is about to use. If the workspace is wrong, stop before starting a run.

2. Rehearse safely

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

The mock pass teaches the client the lifecycle shape without editing the project or spending worker-runtime tokens. A serious MCP integration should support this path before it supports real edits.

3. Start the real run

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

The client should store the run id, project path, profile, workspace, and initial artifact locations. Do not rely on the visible chat transcript as the only state store.

4. Observe through typed state

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>")
orcho_handoff_advice(run_id="<run_id>")

Use status for state, events for progress, evidence for proof, and diagnosis for the next safe action. Use advice only when there is a paused handoff that needs a structured recommendation. Raw logs are useful after that, not before it.

5. Decide explicit control points

If Orcho returns an operator decision, the client should surface the typed payload before suggesting an action.

orcho_phase_handoff_decide(
  run_id="<run_id>",
  handoff_id="<handoff id>",
  action="retry_feedback",
  feedback="Narrow the plan to the failing endpoint and add the missing negative test.",
)
orcho_run_resume(run_id="<run_id>")

The important behavior is not the particular action name. The important behavior is that the client treats the pause as a controlled lifecycle point: read proof, explain the choice, ask the operator, then resume from a meaningful state.

6. Close with evidence and project checks

orcho_run_evidence(run_id="<run_id>")
orcho_run_status(run_id="<run_id>")

Then leave MCP and verify the actual project:

cd /abs/path/to/project
git diff
pytest -q

MCP can say what Orcho recorded. It cannot replace project-local verification.

Decision table

Condition	Read next	Safe client action
`running`	`orcho_run_status`, then bounded events	Keep observing; summarize phase progress.
`awaiting_phase_handoff`	status handoff payload, evidence findings, optional advisor	Ask the operator for a typed decision, then resume.
review or plan rejected	evidence findings and diagnosis	Suggest targeted feedback or a follow-up task, not blind retry.
delivery gate parked	delivery gate state and evidence	Ask for an explicit delivery decision.
failed or halted	diagnosis, events, relevant evidence	Explain the stop reason and propose the narrowest recovery path.
done	evidence, metrics, project diff/tests	Summarize proof and ask for project verification.

What expert clients should avoid

Do not scrape output.log before checking status, evidence, and diagnosis.
Do not invent an action when Orcho exposes typed available_actions.
Do not auto-waive a finding without making the operator decision visible.
Do not resume a terminal failure as if it were a checkpoint.
Do not claim delivery from MCP state alone; inspect the project diff and run the project checks.
Do not treat Orcho accounting as the full cost of the surrounding assistant conversation. Cost accounting explains the boundary.

Start with MCP is the minimal first path.
LLM captain mode explains the ROI of spending extra client calls.
Handoffs and advisors explains pause decisions and LLM advice.
MCP control surface lists the lifecycle tools.
Observe through MCP explains typed observation.
Recovery and resume explains when to resume and when to follow up.