Coding agents

pikopod mcp serves pikopod over the Model Context Protocol on stdin and stdout, so an agent that just wrote or patched an integration can verify it against what the provider actually sends before opening a pull request. It reads the same pikopod.yaml, starts no listener and no daemon, and exits 2 when the configuration is missing or invalid.

Connect a client

Add pikopod to your MCP client’s server list. The --config flag is optional and defaults to ./pikopod.yaml in the working directory.

{
  "mcpServers": {
    "pikopod": {
      "command": "pikopod",
      "args": ["mcp", "--config", "/path/to/pikopod.yaml"]
    }
  }
}

{ "mcpServers": { "pikopod": { "command": "pikopod", "args": ["mcp"] } } }

The transport is JSON-RPC 2.0 over stdio, implemented with no third-party dependency. One process per client session.

Verdicts

Every tool returns one verdict from a closed set, and CLEAN and UNVERIFIABLE never collapse. An agent proceeds on CLEAN and must be able to see that nothing was proven.

Verdict	Meaning
`CLEAN`	The check ran and found nothing.
`FINDINGS`	The check ran and found something. Findings are attached.
`UNVERIFIABLE`	The check could not determine an answer. `reason` says why: no recordings, warmup incomplete, evidence redacted, nothing binds.
`ERROR`	pikopod or its configuration is broken. `error` carries what, why, fix and a docs link.

Every result is {verdict, reason?, warmup?, data?, error?}. drift_events always carries a warmup block so the agent can see how much of the API it has actually observed, with the standing notice: only endpoints that received traffic through the agent are known; an endpoint with no traffic is invisible, and one still warming up cannot alert.

What the tools answer

The readers are the checks an agent cannot make by reading files.

Tool	Answers
`spec_diff`	What two spec versions declare differently, with a severity per finding.
`drift_events`	What the agent observed change in traffic that passed warmup. Before warmup it is `UNVERIFIABLE` with the samples seen and the gate, never an empty `CLEAN`.
`replay_ci`	The CI gate: recordings against frozen baselines.
`conformance`	Whether the provider’s recorded responses obey its own spec. Redacted evidence counts as unverifiable, never as a pass.
`reproduce`	A recorded incident turned into a pack and run locally.
`scenario_list`, `scenario_run`	Which archetypes bind to a sandbox, with the reason when one does not, and the verdict of running them against a throwaway copy.
`get_requests`	What the caller’s own code actually sent to the running sandbox.

The controls put a running sandbox (pikopod up) into a state the caller’s own tests then meet. They act on a local fake and never on a provider: set_mode, clear_mode, arm_fault, clear_faults, emit_webhook. Deliberately absent: fix (a model editing code with no human in the loop), import, chaos, ack, accept, and every reset. They stay human-operated commands. The full argument schemas and verdict rules per tool are in the MCP tools reference.

A typical agent session

Check the contract the agent is coding against

spec_diff between the pinned spec and the provider’s current one. FINDINGS at ERR means the agent is about to integrate against a contract that already broke.

Put the sandbox into the failure the code must survive

set_mode with name: "retry_storm" on the running sandbox, then run the project’s own tests against http://127.0.0.1:4600/<sandbox>.

Confirm what the code actually sent

get_requests returns the sandbox’s request journal. A retry claim is provable here, because the journal records order and headers with identifiers tokenized.

Ask whether production disagrees

drift_events and conformance on the upstream. If the answer is UNVERIFIABLE because warmup is incomplete, the agent knows exactly how many samples it has and how many the gate needs.

Clean up

clear_mode and clear_faults so the next suite meets a clean sandbox. Modes are global to the sandbox and stay until cleared.

Getting started

Gate: catch declared changes in CI

Sandbox: rehearse failures

Scenarios

Observe: the agent

Reproduce and fix

Operations

Project

Connect a client

Verdicts

What the tools answer

A typical agent session

​Connect a client

​Verdicts

​What the tools answer

​A typical agent session

Connect a client

Verdicts

What the tools answer

A typical agent session