Pilotage Reference

This section is for engineers who need either a quick explanation or the exact rule.

Pilotage is an MCP extension for tools whose arguments behave like programs. It standardizes one checkable loop:

manifest → guides → catalog → validate + plan → execute → trace

Seven layers, five tools, one handshake, with the agent at the center deciding what and when to call. One trace, two doors: it rides the execute response; if the run was stored, the same trace can be fetched later by run_id. It does not standardize the program language underneath.

Choose the right layer#

Concepts#

Use Concepts to understand one idea quickly. Each page explains the problem, the mechanism, one real Harborview example, and where the formal rule lives.

1. The loop
2. Guides
3. The catalog and catalog_version
4. Validation and closed diagnostics
5. The plan and risk
6. Execution, traces, and decisions
7. Outcomes: failure as a value
8. Drift and recovery
9. Idempotency
10. Cold start
11. The trust boundary
12. Discovery and the manifest

Specification#

Use the Specification when implementing or testing Pilotage. Parts II and III are normative. Their MUST, SHOULD, and MAY statements define conformance.

• Specification index
• Part I: Story and positioning (informative)
• Part II: The Abstract Model (normative)
• Part III: The MCP Binding (normative)
• Part IV: Implementation Notes (informative)

Machine-readable companions:

• Pilotage 1.1 JSON Schema
• Conformance vectors
• Conformance guide

Learn by doing#

The Guided Journey builds one Harborview job from discovery to drift recovery. The Proof shows what happened when three agents attempted the same job without prior knowledge of Harborview's language.

The boundary in one sentence#

Pilotage makes a cooperative server checkable. It does not make a malicious server safe, and it does not guarantee that an agent will complete its task.