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

# Cursor

> Use Product Brain from Cursor through MCP or terminal access.

<Warning>
  **Early access** — Cursor MCP JSON shape varies by release channel. If this block fails, paste the error in the [**Product Brain Community**](https://community.productbrain.io). UI screenshots: **coming soon**.
</Warning>

Cursor can work with Product Brain through **MCP** or the **`pb` CLI**. In both paths, **you speak normally**; Cursor (your agent) runs Product Brain on your behalf.

## Two paths

| Path                | When it fits                                                                          |
| ------------------- | ------------------------------------------------------------------------------------- |
| **MCP**             | You want tools inside Cursor without relying on a shell.                              |
| **Terminal (`pb`)** | The agent already runs commands in your repo and you want tight git/test integration. |

See also [pb vs MCP package](/docs/pb-and-mcp).

## MCP configuration (`.cursor/mcp.json`)

Create or merge this block (replace the API key with one from **Settings → API keys** in the app):

```json theme={null}
{
  "mcpServers": {
    "productbrain": {
      "url": "https://mcp.productbrain.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Restart Cursor after saving. Then ask:

```text theme={null}
Use Product Brain MCP to orient for the task we're about to do.
```

## API key flow (human)

1. Open [work.productbrain.io](https://work.productbrain.io) → your workspace.
2. **Settings → API keys** → create key (read vs read-write per need).
3. Paste into `.cursor/mcp.json` as shown above.

Screenshot of the keys screen: **coming soon**.

## Recommended `.cursorrules` snippet

```text theme={null}
Before substantive edits, use Product Brain (MCP or pb) to orient for the current task and respect captured DEC/STD/TEN context. Start a session before writes; close it when done.
```

## Working pattern

1. Orient with the task (natural language → MCP `orient` or `pb orient --task`).
2. Read relevant Chain entries.
3. Make the code or docs change.
4. Capture durable decisions or tensions.
5. Close the session.

<details>
  <summary>CLI equivalents</summary>

  ```bash theme={null}
  pb orient --task "Describe the work"
  pb session start
  # ... work ...
  pb session close
  ```
</details>

## Troubleshooting

| Symptom            | Fix                                                         |
| ------------------ | ----------------------------------------------------------- |
| Tools never appear | Restart Cursor; confirm JSON path and trailing `/mcp`.      |
| 401 / unauthorized | Rotate key; check `Bearer` prefix and workspace.            |
| Writes blocked     | Use read-write key; start MCP session tools before capture. |

## Related

* [MCP overview](/docs/mcp/overview)
* [MCP authentication](/docs/mcp/authentication)
* [Troubleshooting](/docs/troubleshooting)