> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikopod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Serve pikopod's checks to a coding agent over the Model Context Protocol.

`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.

<CodeGroup>
  ```json Claude Code (.mcp.json) theme={null}
  {
    "mcpServers": {
      "pikopod": {
        "command": "pikopod",
        "args": ["mcp", "--config", "/path/to/pikopod.yaml"]
      }
    }
  }
  ```

  ```json Generic MCP client theme={null}
  { "mcpServers": { "pikopod": { "command": "pikopod", "args": ["mcp"] } } }
  ```
</CodeGroup>

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](/reference/mcp-tools).

## A typical agent session

<Steps>
  <Step title="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.
  </Step>

  <Step title="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>`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>