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

# Cursor

> Trace Cursor agent sessions to Braintrust and access your Braintrust data through the MCP server

[Cursor](https://cursor.com) is a coding agent, available as a desktop app and from the command line. You can connect it to Braintrust in two ways:

* **Trace Cursor sessions** to record session, turn, model call, tool, and subagent spans in Braintrust.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from Cursor.

> [!NOTE]
>
> Braintrust tracing for Cursor requires `bt` v0.26.0 or later and supports the Cursor CLI and desktop app on macOS, Linux, and Windows.

## Trace Cursor sessions

The [Braintrust plugin for Cursor](https://github.com/braintrustdata/braintrust-cursor-extension) uses `bt` to trace your Cursor agent sessions to Braintrust.

### Set up tracing

> [!NOTE]
>
> If you already enabled Cursor tracing, follow [Update the tracing plugin](#update-the-tracing-plugin).

**1. Install Cursor**

If you haven't already, install [Cursor](https://cursor.com/).

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.

**3. Enable tracing**

Run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable cursor --project <your-project>
```

This command sets up three things:

* **Capture hooks** in `~/.cursor/hooks.json`. Each hook passes a Cursor event to `bt`, which traces it. Other hooks in the file are preserved.
* **Tracing settings** in `~/.cursor/braintrust.json`, which record whether tracing is enabled and which project receives traces. The file doesn't store credentials. The settings apply to every Cursor workspace, except in sessions started with [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run).
* **The Braintrust plugin** in `~/.cursor/plugins/local/trace-cursor`, which adds the [Braintrust MCP server](#connect-to-braintrust-mcp). With `bt` v0.27.0 or later, the command uses Git to install the latest published version, replacing any earlier version. If Git isn't on your `PATH`, it installs the version bundled with `bt` and prints a warning.

Tracing doesn't require Cursor to load the plugin. To use the plugin's MCP server, see [Use the Braintrust plugin](#use-the-braintrust-plugin).

For all options, see [`bt trace enable`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

**4. Reload Cursor**

Reload the Cursor window, or restart the Cursor CLI, so it loads the plugin and hooks.

**5. Log a test trace**

Ask the Cursor agent to do something simple. When the agent finishes, open your Braintrust project and confirm that the trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page.

### What Braintrust traces

Cursor traces in Braintrust include:

* Session spans with the session ID, local username, operating system, workspace, Cursor and plugin versions, and Git repository metadata when available.
* Turn spans with prompts, final responses, and token metrics for the turn when Cursor reports them.
* Model call spans with conversation input reconstructed from hook events and Cursor's transcript, response output, tool calls, and the model when Cursor reports it.
* Tool spans named after Cursor's tool, with inputs, outputs, errors, and denied approvals, including shell commands, MCP tool calls, and file edits.
* Subagent spans nested under the `Task` tool call that started the subagent, with the subagent's task as input.
* Compaction spans when Cursor requests a context compaction.

**Fields for filtering**

| Field | Recorded on | Value |
| - | - | - |
| `context.span_origin.name` | Every span | `braintrust.plugin.cursor` |
| `context.span_origin.version` | Every span | Plugin version |
| `context.span_origin.bt.version` | Every span | `bt` version |
| `context.span_origin.cursor.version` | Every span | Cursor version |
| `metadata.turn_span_id` | Every span in a turn, including the turn span | The turn's span ID |

Versions are captured when each span is created. Unknown versions are `null`.

**Approximate data**

* **Token usage:** Cursor reports it for each turn, not for each model call.
* **Model inputs:** Reconstructed rather than captured as raw provider requests.
* **Model call start times:** Estimated.

### Common workflows

> [accordion] Use different tracing settings for one session
>
> Use [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run) to trace a single Cursor CLI invocation without changing the saved tracing configuration:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace run --project <your-project> cursor
> ```
>
> This workflow launches the Cursor CLI (`agent`) from the terminal. Set `CURSOR_BIN` to launch a different executable. The run must be interactive: `bt trace run cursor` rejects `-p` and `--print`, and requires a terminal for input and output, because Cursor's print mode does not emit the hooks needed for a complete trace.
>
> To change the saved destination, profile, or organization, rerun [`bt trace enable cursor`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/switch) does not change the saved tracing configuration.
>
> To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace run` for one invocation or to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.
>
> Pass `--tag ci --tag release-validation` to either command to [tag session spans](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Trace a saved Cursor session
>
> Cursor stores agent transcripts locally. Use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-import) with `cursor` and the session ID to import a past session, even if tracing was not enabled when it ran. Pass `--attach` to keep importing new turns from an active session until you press Ctrl-C.
>
> Imports contain less information than live tracing. They include conversation text and the final status of the last turn, but not tool activity or token usage. Cursor transcripts have no timestamps, so every imported span uses the transcript file's last-modified time. Cursor might keep only the latest turn in a transcript.

> [accordion] Stop tracing Cursor sessions
>
> Use [`bt trace disable cursor`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) to remove the plugin, its hook entries in `~/.cursor/hooks.json`, and its tracing configuration. Other plugins and hooks, and saved `bt` profiles and credentials, are preserved. Reload Cursor afterward.

### Update the tracing plugin

`bt` uses Git to install the latest published version of the plugin, along with the capture hooks that match your `bt` version. If Git isn't on your `PATH`, it installs the plugin bundled with `bt`.

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations. [`bt update`](https://docs.braintrust.dev/reference/cli/update) can also update the Cursor plugin, but run the next step to make sure the plugin and its hooks are current.

**2. Update the tracing plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update cursor
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-update) updates the installed plugin and its hook entries without changing your saved tracing configuration.

**3. Reload and verify Cursor**

Reload Cursor, run a short agent session, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

### Troubleshooting tracing

First, run `bt trace doctor cursor`. Then, review the following:

> [accordion] Doctor reports that the capture hooks are missing
>
> If `bt trace doctor cursor` reports that the Cursor user capture hooks are missing, run:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace enable cursor --project <your-project>
> ```
>
> Reload Cursor afterward. The doctor report checks the capture hooks in `hooks.json` and whether the installed plugin is out of date, not whether Cursor loaded them. It doesn't report a missing plugin. Tracing doesn't depend on Cursor loading the plugin, but the Braintrust MCP server does.

> [accordion] Traces do not appear after setup
>
> If Cursor was running when its plugin or configuration changed, reload it. Confirm that `bt` is on the `PATH` of the environment that launches Cursor.
>
> Run `bt trace doctor cursor` and confirm that tracing is enabled and routed to the intended project.
>
> If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the Cursor session.

> [accordion] Cursor blocks prompts after you install Claude Code tracing
>
> When third-party plugin imports are enabled, Cursor imports your installed Claude Code plugins. With `trace-claude-code` earlier than v3.0.4, Cursor runs the imported tracing hooks incorrectly and blocks your prompts. Update the Claude Code plugin to v3.0.4 or later:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace update claude
> ```
>
> Reload Cursor afterward. With v3.0.4 or later, the Claude Code plugin runs no hooks in Cursor, and Cursor tracing records Cursor sessions on its own.

> [accordion] A temporary tracing run fails to start
>
> `bt trace run cursor` requires an interactive terminal. Remove `-p` or `--print` from the agent arguments, and run the command from a terminal rather than with redirected input or output.
>
> When the Cursor CLI runs non-interactively, such as with `-p` or `--print` or from a script, it doesn't report prompts, responses, or when each turn ends. Braintrust can't fully trace these runs, even with `bt trace enable cursor`.

> [accordion] Cursor uses an unexpected configuration directory
>
> Cursor tracing writes its hooks, plugin, and tracing settings to separate places, each set by its own environment variable:
>
> * **Hooks:** `bt trace enable cursor` adds its hook entries to `hooks.json` in the directory set by `BRAINTRUST_CURSOR_CONFIG_DIR`, then `CURSOR_CONFIG_DIR`, or in `~/.cursor` when neither is set.
> * **Plugin:** Installed in `trace-cursor` under the directory set by `BRAINTRUST_CURSOR_PLUGIN_DIR`, or under `~/.cursor/plugins/local` when it isn't set.
> * **Tracing settings:** Saved in the file set by `BRAINTRUST_DAEMON_CONFIG`, or in `~/.cursor/braintrust.json` when it isn't set.
>
> `BRAINTRUST_DAEMON_CONFIG` sets one tracing settings file for every coding agent, not only Cursor. If you set it:
>
> * Set it in every environment where you run `bt` or launch Cursor. Otherwise, Cursor's hooks look for `~/.cursor/braintrust.json` and don't trace.
> * After you run [`bt update`](https://docs.braintrust.dev/reference/cli/update), run `bt trace update cursor`. Because every agent shares the settings file, `bt update` can't tell which agents have tracing enabled, so it doesn't update their plugins.

> [accordion] Traces use unexpected settings
>
> Invocation settings supplied by `bt trace run` take precedence over the saved tracing configuration. For normal sessions, the integration does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.
>
> For environment variables accepted by the `bt` commands themselves, see [`bt trace`](https://docs.braintrust.dev/reference/cli/trace).

## Connect to Braintrust MCP

The Braintrust MCP server lets Cursor's agent query and update Braintrust data. You can connect Cursor to it in two ways:

* **[Braintrust plugin](#use-the-braintrust-plugin):** The plugin adds the server for you and authenticates with a Braintrust API key. It works for organizations on the US data plane.
* **[Manual configuration](#configure-the-server-manually):** You add the server to Cursor's MCP configuration yourself. Manual configuration works for organizations on any data plane, including EU and self-hosted, and supports OAuth or an API key.

Use one of these options, not both.

> [!NOTE]
>
> If you [set up tracing](#set-up-tracing), `bt trace enable cursor` installed the Braintrust plugin, which includes the MCP server. However, setting up tracing doesn't authenticate the server, because tracing uses your `bt` login. To use MCP, follow one of the options below.

### Use the Braintrust plugin

The Braintrust plugin adds the MCP server and authenticates with a Braintrust API key. It connects to `https://api.braintrust.dev/mcp`, so it works only for organizations on the US data plane. For EU or self-hosted organizations, or to sign in with OAuth, [configure the server manually](#configure-the-server-manually).

**1. Install the plugin**

If you set up tracing, `bt trace enable cursor` installed the plugin. Check for **Braintrust** in Cursor's plugins. If it isn't there, install it from the Marketplace.

To install the plugin from the [Cursor Marketplace](https://cursor.com/marketplace/braintrust), use `/add-plugin` in Cursor and search for **Braintrust**.

**2. Set your API key**

In Braintrust, create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys). In the plugin's settings in Cursor, enter it in **Braintrust API key**.

**3. Reload Cursor**

Reload the Cursor window to connect the MCP server.

### Configure the server manually

Manual configuration works for organizations on any data plane. It supports OAuth, which signs you in with your own Braintrust account, and API keys, which suit shared or non-interactive setups.

> [tab] OAuth (recommended)
>
> With OAuth, each person signs in with their own Braintrust account and acts with their own permissions. You don't need an OAuth client ID or client secret.
>
> **1. Add the server**
>
> For organizations on the US or EU data plane, add the server in one click:
>
> * [Add the Braintrust MCP server for the US data plane](cursor://anysphere.cursor-deeplink/mcp/install?name=braintrust\&config=eyJ1cmwiOiJodHRwczovL2FwaS5icmFpbnRydXN0LmRldi9tY3AifQ%3D%3D)
> * [Add the Braintrust MCP server for the EU data plane](cursor://anysphere.cursor-deeplink/mcp/install?name=braintrust\&config=eyJ1cmwiOiJodHRwczovL2FwaS1ldS5icmFpbnRydXN0LmRldi9tY3AifQ%3D%3D)
>
> To edit a configuration file instead, or for a self-hosted deployment, add the Braintrust server to one of Cursor's MCP configuration files:
>
> * `~/.cursor/mcp.json` makes the server available in all your projects.
> * `.cursor/mcp.json` in a project makes it available only in that project. Cursor adds a project's server turned off, so turn it on before you use it.
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> {
>   "mcpServers": {
>     "braintrust": {
>       "url": "https://api.braintrust.dev/mcp"
>     }
>   }
> }
> ```
>
> If the file already defines other servers, add the `braintrust` entry inside the existing `mcpServers` object. For the EU data plane, use `https://api-eu.braintrust.dev/mcp`. For a self-hosted deployment, use the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane).
>
> **2. Restart Cursor**
>
> If you edited a configuration file, close and reopen the Cursor app, or start a new Cursor CLI session, to load it. The one-click links don't require a restart.
>
> **3. Sign in to Braintrust**
>
> Start the sign-in, then finish it in your browser:
>
> * **In the Cursor app:** Ask Cursor's agent to connect to the Braintrust MCP server.
> * **In the Cursor CLI:** Run `agent mcp login braintrust`.

> [tab] API key
>
> Use an API key for shared or non-interactive setups. The connection acts with the permissions of the account the key belongs to.
>
> **1. Create an API key**
>
> In Braintrust, create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
>
> **2. Add the server**
>
> Add the Braintrust server to `~/.cursor/mcp.json` for all your projects, or to `.cursor/mcp.json` in a project. The `Authorization` header reads your key from the `BRAINTRUST_API_KEY` environment variable, so the key isn't stored in the file:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> {
>   "mcpServers": {
>     "braintrust": {
>       "url": "https://api.braintrust.dev/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:BRAINTRUST_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> If the file already defines other servers, add the `braintrust` entry inside the existing `mcpServers` object. For the EU data plane, use `https://api-eu.braintrust.dev/mcp`. For a self-hosted deployment, use the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane). Cursor adds a project's server turned off, so turn it on before you use it. Don't commit an API key to a project's `.cursor/mcp.json`.
>
> **3. Set your API key and restart Cursor**
>
> Set `BRAINTRUST_API_KEY` in the environment you launch Cursor from, then close and reopen Cursor:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> export BRAINTRUST_API_KEY="your-api-key-here"
> ```
>
> Cursor reads the variable only from the environment it was launched in. If you set it in a shell profile, launch Cursor from a terminal.

### Use MCP tools

To verify the connection, ask Cursor's agent to list your recent Braintrust projects. If it can't connect, see [Braintrust MCP troubleshooting](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#troubleshooting).

Cursor's agent can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

### Troubleshooting MCP

> [accordion] Cursor reports HTTP 401 Unauthorized for an API key
>
> If you use the Braintrust plugin, the plugin sends no key until you enter one. Enter your API key in **Braintrust API key** in the plugin's settings, then reload the Cursor window.
>
> If you configured the server manually, Cursor fills in the `Authorization` header from `BRAINTRUST_API_KEY` in the environment Cursor was launched from. If the variable isn't set there, Braintrust rejects the request. Launching Cursor from the Dock, Spotlight, or another launcher doesn't load variables set in your shell profile. Quit Cursor, then launch it from a terminal where `BRAINTRUST_API_KEY` is set.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.