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

# MCP

> Expose the brain and the workflow list over the Model Context Protocol, so a coding agent can use them without being told how the CLI works.

px0 already holds two things a coding agent wants: a brain that can answer questions from what you have read, and a set of workflows that can be run. A CLI can be shelled out to, but MCP means the agent can discover what is there and what each thing takes, rather than having the shape of `px0` explained to it in a prompt.

```bash theme={null}
px0 mcp serve
px0 mcp serve --allow-runs
```

`px0 mcp serve` speaks MCP on stdin and stdout, one JSON-RPC message per line, until stdin closes. No MCP SDK is involved - the surface needed is `initialize`, `tools/list`, and `tools/call` over stdio.

## `--allow-runs`

Let a client run workflows.

* **Input:** flag, no value. Default off.
* Off by default because a workflow can post, send, and file things. Without it, `workflow_run` is not even listed, and calling it returns an error explaining how to enable it.

## What it exposes

| Tool              | What it does                                                 | Needs `--allow-runs` |
| :---------------- | :----------------------------------------------------------- | :------------------- |
| `brain_ask`       | Answer a question from the brain, citing the files used      | No                   |
| `brain_search`    | Return matching passages, without a model call               | No                   |
| `workflows_list`  | Every workflow, with its schedule and whether it is disabled | No                   |
| `guidelines_list` | Every guideline file                                         | No                   |
| `guideline_read`  | One guideline verbatim, to follow it                         | No                   |
| `workflow_run`    | Run a workflow, optionally as a dry run                      | Yes                  |

`brain_ask` and `brain_search` take an optional `kind` (`blog`, `paper`, `doc`, `video`, `stub`) and `k`. Nothing under the brain's private folder is ever returned, the same guarantee that holds for `px0 brain search` and `px0 brain ask` on the command line.

## Registering it with a client

Claude Code, and most MCP clients, take a command and its arguments:

```json theme={null}
{
  "mcpServers": {
    "px0": {
      "command": "px0",
      "args": ["mcp", "serve"],
      "env": { "PX0_HOME": "/Users/you/.px0" }
    }
  }
}
```

Set `PX0_HOME` when the client's environment differs from your shell's, since that is what selects the store.

## Related configuration

| Key                   | Effect                                                     |
| :-------------------- | :--------------------------------------------------------- |
| `retrieval.backend`   | Which retrieval backend `brain_ask` and `brain_search` use |
| `retrieval.k_default` | Passages retrieved when a call names no `k`                |
| `model.harness_cmd`   | The backend `brain_ask` asks to write the answer           |

## Exit codes

| Code | When                                |
| :--- | :---------------------------------- |
| `0`  | stdin closed and the server stopped |
| `1`  | No store, or an unknown subcommand  |