Cursor

Cursor 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.

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 uses bt to trace your Cursor agent sessions to Braintrust.

Set up tracing

If you already enabled Cursor tracing, follow Update the tracing plugin.

Install Cursor

If you haven’t already, install Cursor.

Install and authenticate bt

Follow the bt CLI quickstart to install bt, authenticate, and set your active context.

Enable tracing

Run this command in a terminal:

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.
The Braintrust plugin in ~/.cursor/plugins/local/trace-cursor, which adds the Braintrust MCP server. 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.For all options, see bt trace enable.

Reload Cursor

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

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 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

Use different tracing settings for one session

Use bt trace run to trace a single Cursor CLI invocation without changing the saved tracing configuration:

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 with the corresponding options. Running bt 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.

Trace a saved Cursor session

Cursor stores agent transcripts locally. Use 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.

Stop tracing Cursor sessions

Use bt trace disable cursor 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.

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations. bt update can also update the Cursor plugin, but run the next step to make sure the plugin and its hooks are current.

Update the tracing plugin

bt trace update cursor

bt trace update updates the installed plugin and its hook entries without changing your saved tracing configuration.

Reload and verify Cursor

Reload Cursor, run a short agent session, and confirm that its trace appears on the Logs page in the intended Braintrust project.

Troubleshooting tracing

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

Doctor reports that the capture hooks are missing

If bt trace doctor cursor reports that the Cursor user capture hooks are missing, run:

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.

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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the Cursor session.

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:

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.

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.

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, 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.

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.

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: 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: 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.

If you 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.

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, use /add-plugin in Cursor and search for Braintrust.

Set your API key

In Braintrust, create a key in Settings > API keys. In the plugin’s settings in Cursor, enter it in Braintrust API key.

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.

OAuth (recommended)
API key

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.

Add the server

For organizations on the US or EU data plane, add the server in one click:

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.

{
  "mcpServers": {
    "braintrust": {
      "url": "https://api.braintrust.dev/mcp"
    }
  }
}

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.

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.

Use an API key for shared or non-interactive setups. The connection acts with the permissions of the account the key belongs to.

Create an API key

In Braintrust, create a key in Settings > API keys.

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:

{
  "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. 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.

Set your API key and restart Cursor

Set BRAINTRUST_API_KEY in the environment you launch Cursor from, then close and reopen Cursor:

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. 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 for more workflows and example prompts.

Troubleshooting MCP

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.
Run evaluations: Follow the evaluation guide.
Explore MCP tools: See the Braintrust MCP tool reference.
Browse the source: View the coding-agent plugins repository.

AI providers

SDKs

Developer tools

Runtime environments

Trace Cursor sessions

Set up tracing

What Braintrust traces

Common workflows

Update the tracing plugin

Troubleshooting tracing

Connect to Braintrust MCP

Use the Braintrust plugin

Configure the server manually

Use MCP tools

Troubleshooting MCP

Next steps

​Trace Cursor sessions

​Set up tracing

​What Braintrust traces

​Common workflows

​Update the tracing plugin

​Troubleshooting tracing

​Connect to Braintrust MCP

​Use the Braintrust plugin

​Configure the server manually

​Use MCP tools

​Troubleshooting MCP

​Next steps

Trace Cursor sessions

Set up tracing

What Braintrust traces

Common workflows

Update the tracing plugin

Troubleshooting tracing

Connect to Braintrust MCP

Use the Braintrust plugin

Configure the server manually

Use MCP tools

Troubleshooting MCP

Next steps