Deterministic at the host boundary. Free reasoning between checkpoints.
runbook.v1 is an application-layer contract for MCP hosts that need governed, versioned, auditable workflows. It answers a limitation in the current MCP interaction model: an MCP server can expose a tool or workflow, but the model still decides whether to invoke it and how completely to follow it.
For enterprise workflows, execution must be required, not suggested.
A runbook is a versioned manifest resolved from a trusted skills server and executed by the host with fail-closed semantics:
{
"runbook_id": "executive-snapshot",
"version": "4.2.0",
"mode": "required",
"failure_policy": "fail_closed",
"checkpoints": [
{"id": "cp-revenue-qb", "kind": "tool_call", "required": true,
"match": {"tool": "quickbooks_profit_and_loss"}},
{"id": "cp-emit", "kind": "condition", "required": true,
"condition": "final_output"}
],
"completion": {"condition": "final_output", "receipt": true}
}
Acquisition is deterministic. The host resolves the runbook by ID + version from a trusted skills server. No semantic search. Content hash, schema, and prerequisites are validated before the first model call.Version pinning is absolute. The exact version is bound for the life of the run. It is never pasted into chat as untrusted prose.The tool surface is an allow-list. The model can only see and call tools declared in the manifest.Checkpoints are observed, not self-reported. The host derives checkpoint state from the tool-call stream. The model never claims compliance.Completion is host-evaluated. The host decides whether the runbook completed and emits a machine-readable receipt.Required mode is never silently downgraded. If the host cannot honor the contract, it returnsrunbook_failed
instead of a normal answer.
schema/runbook.v1.schema.json JSON Schema for the manifest
spec/runbook-v1.md The specification
reference/python/ Reference host implementation
conformance/ Conformance test suite (24 tests)
examples/ Example manifests
The reference implementation passes its own conformance suite:
python3 conformance/run_conformance.py
PASS: 24 FAIL: 0
The suite covers: schema validation, content hashing, tamper detection, prerequisite fail-closed, checkpoint observation, checkpoint timeout, allow-list enforcement, receipt emission, and missing-runbook behavior.
MCP won because it made agents practical. This makes them trustworthy. In enterprise procurement, those are the same word.
MIT