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

# Cursor

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[Cursor](https://cursor.com) is an AI-powered code editor. The Braintrust extension for Cursor automatically connects to the Braintrust MCP server, giving Cursor's AI assistant access to your Braintrust projects, experiments, and logs.

## Setup

<Steps>
  <Step title="Install Cursor">
    If you haven't already, download and install [Cursor](https://cursor.com/).
  </Step>

  <Step title="Install the extension">
    Install from the Cursor extension marketplace\~\~:\~\~

    1. Open Cursor.
    2. Go to **Extensions** (`Shift+Cmd+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
    3. Search for "Braintrust".
    4. Click **Install**.
  </Step>

  <Step title="Set your API key">
    The extension reads your API key from the `BRAINTRUST_API_KEY` environment variable:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export BRAINTRUST_API_KEY="your-api-key-here"
    ```

    Then restart your terminal.
  </Step>

  <Step title="Add Braintrust as a trusted domain">
    To allow the extension to authenticate without OAuth prompts:

    1. Open Cursor Settings (`Cmd+,` on macOS / `Ctrl+,` on Windows/Linux)
    2. Search for "trusted domains"
    3. Add `braintrust.dev` to the list of trusted domains
  </Step>

  <Step title="Restart Cursor">
    Close and reopen Cursor to load the new MCP server configuration.
  </Step>
</Steps>

## Usage

Once the extension is installed and `BRAINTRUST_API_KEY` is set, the Braintrust MCP server is automatically registered when Cursor starts. No manual steps required.

You can fetch experiment results, query logs, log data, and more. See [MCP documentation](/docs/integrations/developer-tools/mcp#what-the-mcp-can-do) for details.

## Troubleshooting

<Accordion title="BRAINTRUST_API_KEY is not set">
  * Verify the variable is set: `echo $BRAINTRUST_API_KEY` (macOS/Linux) or `echo %BRAINTRUST_API_KEY%` (Windows).
  * Cursor must be **restarted** after setting environment variables.
  * On macOS, launching Cursor from Spotlight or Dock may not inherit shell variables. Try launching from the terminal instead.
</Accordion>

<Accordion title="Extension doesn't seem to work">
  * This extension only works in Cursor, not vanilla VS Code.
  * Ensure you're running a recent version of Cursor that supports the MCP Extension API.
</Accordion>

## Next steps

* **Run evaluations**: Check out the [evaluation guide](/docs/evaluate/run-evaluations) to learn evaluation patterns.
* **Browse the source**: The [braintrust-cursor-extension repository](https://github.com/braintrustdata/braintrust-cursor-extension) contains the extension source code.