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

# Windsurf

If you are a coding agent, prefer the Braintrust [`bt` CLI](/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, such as ad-hoc lookups and exploration from your IDE.

[Windsurf](https://codeium.com/windsurf) is Codeium's AI-native IDE with deep AI integration. The Braintrust MCP server connects to Windsurf, giving its AI assistant (Cascade) access to your Braintrust projects, experiments, and logs.

## Setup

<Steps>
  <Step title="Install Windsurf">
    If you haven't already, install [Windsurf](https://windsurf.com/editor).
  </Step>

  <Step title="Add the Braintrust MCP server">
    Edit `~/.codeium/windsurf/mcp_config.json` and add the Braintrust server:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    {
      "mcpServers": {
        "braintrust": {
          "serverUrl": "https://api.braintrust.dev/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
          }
        }
      }
    }
    ```

    Replace `YOUR_BRAINTRUST_API_KEY` with your actual API key.
  </Step>

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

## Usage

Once configured, Cascade (Windsurf's AI assistant) can access Braintrust data through the MCP server. You can fetch experiment results, query logs, log data, and more. See [MCP documentation](/integrations/developer-tools/mcp#available-tools) for details.

Example prompts to Cascade:

* "Show me my recent Braintrust experiments"
* "Query the last 10 logged requests with errors"
* "What's the average latency for the summarizer prompt today?"
* "Summarize my latest A/B test results"

## Troubleshooting

<Accordion title="MCP server not appearing">
  * Verify the JSON configuration syntax is correct (no trailing commas, proper quotes)
  * Check that the file path is exactly `~/.codeium/windsurf/mcp_config.json`
  * Try restarting Windsurf completely
</Accordion>

<Accordion title="Authentication fails">
  * Verify your API key is correct (no extra spaces or quotes)
  * Ensure you can log into [Braintrust](https://www.braintrust.dev) in your browser
  * Check that the `Authorization` header is properly formatted
</Accordion>

<Accordion title="Connection errors">
  * Verify the URL is exactly `https://api.braintrust.dev/mcp` (no trailing slash)
  * Check your internet connection
  * Corporate networks may need to allowlist `api.braintrust.dev` and `*.braintrust.dev`
</Accordion>

<Accordion title="Configuration not loading">
  * Ensure the JSON file is valid (use a JSON validator)
  * Check file permissions: `chmod 644 ~/.codeium/windsurf/mcp_config.json`
  * Look for error messages in Windsurf's developer console
</Accordion>

## Next steps

* **Run evaluations**: Check out the [evaluation guide](/evaluate/run-evaluations) to learn evaluation patterns.
* **Explore MCP tools**: See the [MCP documentation](/integrations/developer-tools/mcp#available-tools) for all available commands.
* **Query with SQL**: Learn how to [query with SQL](/reference/sql) for complex data analysis.