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

# MCP Server

> Connect ProductBrain to Claude Desktop, Claude Code, or Cursor over MCP.

The ProductBrain MCP server lets an MCP client — **Claude Desktop, Claude Code, Cursor** — drive your plan directly: search, read, mutate, run the planning methodology, and read/drive the live view.

<Note>
  **A thin shim, on purpose.** The server is a thin transport over ProductBrain's versioned **v1 REST API** — each tool is one call to an existing `/api/v1` endpoint. The REST contract stays canonical: it's stable when the MCP spec churns, you can drop to raw HTTP or bring your own LLM any time, and responses carry the same in-band `_meta` coaching the API returns.
</Note>

## Install

<CodeGroup>
  ```jsonc Claude Desktop theme={null}
  // claude_desktop_config.json
  {
    "mcpServers": {
      "productbrain": {
        "command": "npx",
        "args": ["-y", "@productbrain-com/mcp"],
        "env": {
          "PRODUCTBRAIN_API_KEY": "pb_your_key",
          "PRODUCTBRAIN_PROJECT_ID": "your-project-id"
        }
      }
    }
  }
  ```

  ```bash Claude Code theme={null}
  claude mcp add productbrain \
    -e PRODUCTBRAIN_API_KEY=pb_your_key \
    -e PRODUCTBRAIN_PROJECT_ID=your-project-id \
    -- npx -y @productbrain-com/mcp
  ```
</CodeGroup>

Cursor and other clients: add an `mcpServers` entry with the same `command` / `args` / `env`.

## Configuration

| Variable                  | Required | Default                                              |
| ------------------------- | -------- | ---------------------------------------------------- |
| `PRODUCTBRAIN_API_KEY`    | yes      | — (your `pb_` key from the app's **API Keys** modal) |
| `PRODUCTBRAIN_PROJECT_ID` | no       | — (tools also accept a `projectId` argument)         |
| `PRODUCTBRAIN_API_URL`    | no       | `https://productbrain.com/api/v1`                    |

## Tools

| Tool                     | Maps to                                 | Use                                                                                 |
| ------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
| `search`                 | `GET /search`                           | Semantic search — **use first** for any lookup                                      |
| `list_nodes`             | `GET /nodes`                            | Bulk read, optional type / iteration filter                                         |
| `get_tree`               | `GET /tree`                             | A node in context (ancestors / siblings / children / subtree)                       |
| `mutate`                 | `POST /mutate`                          | Create / update / delete nodes + phases; pass `idempotencyKey` to make retries safe |
| `list_iterations`        | `GET /iterations`                       | Phases; `current: true` for the active one                                          |
| `run_workflow`           | `POST /workflow`                        | Story-Mapping methodology (add / task-curate / phase-assign)                        |
| `set_view` / `read_view` | `POST /view-command`, `GET /view-state` | Drive / read the live canvas                                                        |

The complete contract — every endpoint, field, and validation rule — is the [LLM Guide](https://productbrain.com/docs/llm-guide.md).