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

# MCP server

> Expose the read-only query layer (plus one explicit capture tool) to IDEs and coding agents over MCP.

## MCP server

The same read-only query layer is available to IDEs and coding agents over the
[Model Context Protocol](https://modelcontextprotocol.io), so the *why* is one tool call away
without shelling out. Install the extra and start a stdio server:

```bash theme={null}
pip install 'whyfile[mcp]'
whyfile --mcp --graph graphify-out/graph.json
```

Register it with a client (Claude Code, Cursor, IDE agents). For Claude Code, add to `.mcp.json`
at the project root (launch the server from the project root so a `--base`-style git diff resolves
against your repo):

```json theme={null}
{
  "mcpServers": {
    "whyfile": {
      "command": "whyfile",
      "args": ["--mcp", "--graph", "graphify-out/graph.json"]
    }
  }
}
```

Seven `intent_*` tools are exposed: six read-only query tools plus one explicit write tool, each a
thin wrapper over the CLI command of the same name, so a tool result is identical to its CLI
counterpart's JSON:

| Tool                         | Inputs                                                            | What it does                                                                                                                                |
| ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `intent_explain`             | `node`                                                            | Why is *this* node like this: the intent that motivates a code/doc node, or an intent node's claim, rationale, alternatives, and relations. |
| `intent_list`                | `kind?`, `min_confidence?`, `provenance?`                         | The intent inventory, optionally filtered.                                                                                                  |
| `intent_why`                 | `question`, `top?`                                                | Ranked intent matching a natural-language question.                                                                                         |
| `intent_changed`             | `files[]` or `base`                                               | The intent governing changed files, constraints first.                                                                                      |
| `intent_coverage`            | (none)                                                            | Which code has recorded intent and which is dark.                                                                                           |
| `intent_digest`              | `since`                                                           | What intent was added, removed, or superseded since a checkpoint.                                                                           |
| `intent_capture` (**write**) | `chosen`, `rationale`, `question?`, `options?`, `recommendation?` | Persist a resolved decision as a record + a `captured` node, without shelling out.                                                          |

The six query tools are **read-only, LLM-free, and free at query time** (they read the local graph,
make no backend call). `intent_capture` is the one **write** tool (B5): it is explicit (a distinctly
named tool, never a mode on a read tool), schema-validated, and scoped to capturing a decision, so
the read-only guarantee of the others is unchanged. Results carry both a JSON body and MCP
`structuredContent`; a real failure sets
`isError`, while a missing intent layer returns a graceful `no_intent_layer` result rather than an
error. The server only reads a local graph: no mutations, no pipeline runs, no secrets, safe to
hand to any agent. See [ADR-0018](../adr/0018-mcp-server.md) for the design.