An open extension of the Model Context Protocol

Schemas teach the moves. Pilotage teaches the game.

An MCP server publishes the checkable competence to use its complex tools, so any agent can learn, validate, plan, execute, and trace them through one interface, with the result on the record.

pilotage · the agent-driven loop · live
manifest guides catalog validate plan execute trace Agent 007
the agent asks the server answers
spec v1.1
id io.github.jafarsa0/pilotage
text CC BY 4.0 · schemas Apache-2.0
DOI 10.5281/zenodo.21396027
How it works

Calling a tool, vs. authoring a checkable program

Seven layers, five tools, one handshake, with the agent at the center, deciding what to call, and when. The numbers are the usual journey; the agent chooses the order.

pilotage · the loop, at a glance · v1.1
MCP ALONE MCP + PILOTAGE arrive together rides the response agent writes a whole program call a tool one blind shot · a sealed box ✗ opaque failure an error it can't act on no grammar no live names no pre-run check no record 1 · manifest the welcome card pilotage 1.1 · buildingflow/1 maps all 5 tools 2 · guides learn the language quickstart reference examples 3 · catalog the live, real names light.lobby lock.dock_door sensor.occupancy + 8 more · cv_40d6648b 4 · validate checked before it runs unknown_device light.lobby 5 · plan risk before it runs safe write destructive 6 · execute run · keep the record? run_0001 · success store: true 7 · trace one record, two doors inline · with the response fetch · later, by run_id gate took: "then" agent decides what to call · and when
the agent asks the server answers

MCP finds a tool. Pilotage makes the whole program checkable.

Why it exists

The same three problems, everywhere agents meet real systems

A SQL engine, an automation platform, a workflow processor: the pattern repeats.

PROBLEM 1

Schemas describe structure, not languages

A JSON Schema can say a field is a string. It cannot teach the grammar the string must be written in, the names it may reference, or the rules that make it meaningful.

PROBLEM 2

Complex work rarely succeeds in one call

Real programs are drafted, checked, repaired, and only then run. A bare tool call gives an agent one confident shot and an opaque failure.

PROBLEM 3

Competence does not scale when hardcoded

Today each agent bakes in private knowledge of each system. Publishing that competence on the server (checkable, versioned, discoverable) makes it work once, for every agent.

See it work

One real job, walked through the loop

Every payload below is real, captured from Harborview, a public example server whose language no model has seen. Click a stage, or step through with the arrows.

pilotage · one real job · buildingflow/1 · live
1 · manifest 2 · guides 3 · catalog 4 · validate + plan 5 · execute 6 · trace
request
response
Start here

Three ways in

The honest part

Self-report is not evidence. The checkable end state is.

Pilotage doesn't make agents identical, and it doesn't promise any one of them succeeds. It makes the server checkable and the loop honest, so different agents, taking different paths, converge on the same verified result.

Read the proof →