pikopod mcp speaks JSON-RPC 2.0 over stdin and stdout, one message per line, protocol version 2024-11-05. It supports initialize, ping, tools/list and tools/call. Every call returns a result with a verdict and, on UNVERIFIABLE, a reason. Unknown arguments are refused. See Coding agents for the client setup and the verdict contract.
Result shape:
Readers
spec_diff
Diff two spec versions as declared drift with a severity per finding. It sees only what the documents declare; behaviour a provider changed without updating its spec is invisible here.FINDINGS when anything at or above fail_on exists, else CLEAN with lower findings attached. data carries fail_on, summary and findings with fingerprints.
drift_events
Drift events, incidents and divergence events the agent recorded for an upstream. Drift is reported only for traffic that passed warmup; incidents and divergence need no warmup and fire from the first request.FINDINGS when events exist. UNVERIFIABLE when the upstream has no baselines yet, or when no endpoint has passed warmup, with the samples seen and the gate, and a reminder that incidents and divergence would have been reported regardless. CLEAN otherwise, naming how many endpoint families are warmed up and how many are still warming. Every result carries a warmup block: gate values, per-family samples, and the standing notice that an endpoint with no traffic is invisible.
replay_ci
The CI gate: recorded traffic against frozen baselines, offline.FINDINGS lists drift at or above fail_on per endpoint under data.upstreams.<name>.findings, each with risk and fingerprint. Findings below the tier and accepted fingerprints are listed under accepted with a because, and never make the verdict FINDINGS. CLEAN means every gated recording matched or every finding was accepted. UNVERIFIABLE with a reason when an upstream has no baselines or no recordings. ERROR for an unknown tier. Recordings made before an endpoint warmed up are skipped and counted. See Risk tiers.
conformance
Whether an upstream’s recorded responses obey its imported spec.FINDINGS lists violations. Checks whose evidence the sanitizer redacted are counted as unverifiable and never scored as passes. With no violations and some unverifiable checks the verdict is UNVERIFIABLE.
reproduce
Turn a recorded incident into a runnable scenario pack and run it against the local sandbox. Writes one pack file underdata_dir/scenarios and touches nothing else.
FINDINGS with reproduced: true means the failure now happens locally, and data carries the pack name and path. UNVERIFIABLE when the pack ran but the failure did not recur, or when no sandbox exists to run it against. The request is rebuilt from a redacted recording, so a 4xx that depended on the exact body may not recur.
scenario_list
Which failure archetypes bind to a sandbox’s API, and why the rest do not.CLEAN when at least one archetype binds. UNVERIFIABLE when none does, with every reason attached. data carries the archetypes, saved packs, and endpoint count.
scenario_check
Run archetypes or packs against a throwaway copy of a sandbox. The served sandbox is untouched, and this drives pikopod’s own requests, not the caller’s application.CLEAN when all pass, FINDINGS when any fails, ERROR when a step could not execute. data.runs carries each scenario’s result. scenario_run, the previous name, still answers this release but is not listed.
get_requests
What the caller’s application actually sent to a running sandbox: the request journal, newest last, with identifiers tokenized.
Needs
pikopod up. When older entries were evicted the result says so, because ordering claims across the gap cannot be proven.
mode_verify
After the caller’s own tests ran against a running sandbox in a mode, check what they sent against the scenario’s verification steps: request order and spacing, webhook counts, stored state. This is the one tool that judges the caller’s code rather than the sandbox.CLEAN when every step passed, FINDINGS when the client did not do what the scenario expects, ERROR when no mode is set or a step could not run. data.result carries the run result, data.mode the scenario’s name. On FINDINGS, data.closest carries the closest journaled request for the first matcher that never matched and what differed, as a path template and header or query names, so the agent can correct the client without reading the journal. Needs pikopod up and a standing set_mode.
Controls over the running sandbox
These needpikopod up and act on a local fake, never on a provider.
set_mode
Put the running sandbox into a scenario’s failure state so the caller’s own tests meet it. The mode stands untilclear_mode.
Scenarios that have no standing state are refused with the reason.
clear_mode
Clear the standing mode and every fault it armed.arm_fault
Arm one fault. HTTP faults needmethod and path; webhook faults match by event.
clear_faults
Clear faults matchingmethod and path, or every fault when both are omitted.
emit_webhook
Fire a declared event, signed and shaped the way the sandbox’s spec declares, to the sandbox’s configured webhook URL. Undeclared events are refused.Deliberately absent
fix, import, chaos, ack, accept, up and every reset. They stay human-operated commands, and a test fails the build if any of them appears in the tool list.