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

# Braintrust MCP

> Access Braintrust from AI coding tools

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.

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) enables AI coding tools to access your Braintrust data directly. Query experiments, search documentation, and analyze production logs from tools like Claude Code, Cursor, VS Code, Windsurf, and Claude Desktop.

<Note>
  For most workflows, the [`bt` CLI](/reference/cli/quickstart) is the recommended interface and is the better default for coding agents (e.g., Claude Code, Codex, Cursor), covering running evals, instrumenting your code, querying logs, syncing data, and managing functions. Use the MCP tools below for ad-hoc data access from your IDE.
</Note>

## Set up the MCP server

<Note>
  The examples below use `https://api.braintrust.dev/mcp` (US data plane). If your organization is on the EU data plane, use `https://api-eu.braintrust.dev/mcp` instead. See [Data plane region](/admin/organizations#data-plane-region).
</Note>

<AccordionGroup>
  <Accordion title="Claude Code" icon="https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Note>
      The [Braintrust plugin for Claude Code](/integrations/developer-tools/claude-code) wraps the MCP server and adds tracing capabilities. If you've installed that plugin, you don't need to configure MCP separately.
    </Note>

    <Steps>
      <Step title="Install Claude Code">
        If you haven't already, install [Claude Code](https://claude.com/product/claude-code).
      </Step>

      <Step title="Set your API key">
        Set the `BRAINTRUST_API_KEY` environment variable with your API key:

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

      <Step title="Add the Braintrust MCP server">
        Add Braintrust MCP server with API key authentication:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude mcp add --transport http braintrust \
           https://api.braintrust.dev/mcp \
           --header "Authorization: Bearer $BRAINTRUST_API_KEY"
        ```

        Alternatively, you can use OAuth authentication instead of an API key:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude mcp add --transport http braintrust \
           https://api.braintrust.dev/mcp

        # To authenticate, open Claude Code and run this command:
        /mcp
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Claude Desktop" icon="https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Claude Desktop">
        If you haven't already, download and install [Claude Desktop](https://claude.ai/download).
      </Step>

      <Step title="Add the Braintrust MCP server">
        Follow the [Claude Desktop documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) to create a custom connector with the following details:

        * **Name**: `Braintrust`
        * **URL**: `https://api.braintrust.dev/mcp`

        <Note>
          Claude Desktop uses OAuth 2.0 for authentication. You don't need to provide an API key in the connector configuration - you'll authenticate when you first use the server.
        </Note>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Cursor" icon="https://img.logo.dev/cursor.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Note>
      The [Braintrust extension for Cursor](/integrations/developer-tools/cursor) automatically configures the MCP server for you. If you've installed that extension, you don't need to configure MCP separately.
    </Note>

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

      <Step title="Add the Braintrust MCP server">
        Click to automatically add the Braintrust MCP server: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=braintrust\&config=eyJ1cmwiOiJodHRwczovL2FwaS5icmFpbnRydXN0LmRldi9tY3AifQ%3D%3D)

        Or manually add to `.cursor/mcp.json`:

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

        Replace `YOUR_BRAINTRUST_API_KEY` with your actual API key.

        Cursor also supports OAuth authentication. If you omit the `headers` field, Cursor will prompt you to authenticate via OAuth when you first use the server.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="VS Code" icon="https://img.logo.dev/vscode.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install VS Code">
        If you haven't already, download and install [Visual Studio Code](https://code.visualstudio.com/).
      </Step>

      <Step title="Install an AI assistant extension">
        VS Code requires an AI assistant extension that supports the Model Context Protocol (MCP). Popular options include:

        * [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
        * [Continue](https://marketplace.visualstudio.com/items?itemName=Continue.continue)
        * Other MCP-compatible extensions

        Install one of these extensions from the VS Code marketplace.
      </Step>

      <Step title="Add the Braintrust MCP server">
        Add the Braintrust MCP server to your VS Code settings, either in workspace settings or user settings:

        * **Workspace settings** - Create or edit `.vscode/mcp.json` in your project:

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

        * **User settings** - Add to your VS Code user settings (`Cmd+,` / `Ctrl+,` → Search for "mcp"):

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

        Replace `YOUR_BRAINTRUST_API_KEY` with your actual API key.

        VSCode also supports OAuth authentication. If you omit the `headers` field, VSCode will prompt you to authenticate via OAuth when you first use the server.
      </Step>

      <Step title="Restart VS Code">
        Reload the VS Code window (`Cmd+R` / `Ctrl+R`) or restart VS Code to apply the configuration.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Windsurf" icon="https://img.logo.dev/codeium.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <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>
  </Accordion>

  <Accordion title="Codex (OpenAI)" icon="https://img.logo.dev/openai.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Codex">
        If you haven't already, install [Codex](https://openai.com/codex/).
      </Step>

      <Step title="Set your API key">
        Set the `BRAINTRUST_API_KEY` environment variable with your API key:

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

      <Step title="Add the Braintrust MCP server">
        Edit `~/.codex/config.toml` and add the Braintrust MCP server configuration:

        ```toml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        [mcp_servers.braintrust]
        url = "https://api.braintrust.dev/mcp"
        bearer_token_env_var = "BRAINTRUST_API_KEY"
        ```

        This configures Codex to read your Braintrust API key from the `BRAINTRUST_API_KEY` environment variable.
      </Step>

      <Step title="Verify the setup">
        Launch Codex with the environment variable set:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        codex
        ```

        Run the `/mcp` command to verify Braintrust is installed and accessible.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="OpenCode" icon="https://img.logo.dev/opencode.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Tip>
      For automatic tracing of OpenCode sessions, consider the [Braintrust plugin for OpenCode](/integrations/developer-tools/opencode).
    </Tip>

    <Steps>
      <Step title="Install OpenCode">
        If you haven't already, install [OpenCode](https://opencode.ai/).
      </Step>

      <Step title="Add the Braintrust MCP server">
        Edit your [OpenCode configuration file](https://opencode.ai/docs/config/) and add the Braintrust MCP server:

        ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        {
          "$schema": "https://opencode.ai/config.json",
          "mcp": {
            "braintrust": {
              "type": "remote",
              "url": "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 OpenCode">
        Restart OpenCode to apply the configuration changes.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Gemini CLI" icon="https://img.logo.dev/gemini.google.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Gemini CLI">
        If you haven't already, install [Gemini CLI](https://github.com/google-gemini/gemini-cli).
      </Step>

      <Step title="Set your API key">
        Set the `BRAINTRUST_API_KEY` environment variable with your API key:

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

      <Step title="Add the Braintrust MCP server">
        Edit `~/.gemini/settings.json` and add the Braintrust MCP server configuration:

        ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        {
          "mcpServers": {
            "braintrust": {
              "httpUrl": "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="Verify the setup">
        Launch Gemini CLI and run the `/mcp` command to confirm the Braintrust server is connected.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Warp" icon="https://img.logo.dev/warp.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Warp">
        If you haven't already, download and install [Warp](https://warp.dev/).
      </Step>

      <Step title="Add the Braintrust MCP server">
        Open Warp and navigate to **Settings > AI > MCP Servers**. Add a new server with the following details:

        * **Name**: `Braintrust`
        * **URL**: `https://api.braintrust.dev/mcp`
        * **Header**: `Authorization: Bearer YOUR_BRAINTRUST_API_KEY`

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

      <Step title="Verify the setup">
        Once added, the Braintrust MCP server will be available in Warp's AI agent. You can verify the connection from the MCP Servers settings page.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Other clients">
    Any MCP-compatible client can connect to the Braintrust MCP server. The server is available at:

    ```
    https://api.braintrust.dev/mcp
    ```

    **Streamable HTTP transport**

    Pass your API key as a bearer token in the `Authorization` header:

    ```
    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
    ```

    Most clients that support remote MCP servers accept a URL and optional headers. Refer to your client's documentation for where to configure these. SSE-only MCP clients will not work with the Braintrust server.

    **OAuth authentication**

    The Braintrust MCP server also supports OAuth 2.0. If your client supports OAuth-based MCP authentication, you can connect without an API key and authenticate interactively.
  </Accordion>
</AccordionGroup>

## Available tools

The MCP server provides these tools to your AI assistant:

### Search documentation

**`search_docs`** - Search Braintrust documentation to find relevant guides, API references, and code examples.

* "How do I create a custom scorer?"
* "Show me examples of SQL queries"
* "What's the difference between experiments and project logs?"

### Resolve objects

**`resolve_object`** - Convert names to IDs (or vice versa) and parse Braintrust URLs. Useful for looking up object IDs before querying.

* "Find the ID for my 'sentiment-analysis' experiment"
* "What's the name of experiment abc123?"
* "Parse this Braintrust URL and tell me what object it points to"

### List recent objects

**`list_recent_objects`** - List recently created projects, experiments, datasets, prompts, or functions you have access to.

* "Show me my recent experiments in the 'chatbot' project"
* "List datasets in the recommendation engine project"
* "What projects do I have access to?"

### Infer schema

**`infer_schema`** - Analyze the structure and content of experiments, datasets, or logs. Discovers available fields, data types, and shows the most common values for each field.

* "What fields are available in my experiment data?"
* "Show me the schema for production logs"
* "What metadata fields exist in this dataset?"

### Query with SQL

**`sql_query`** - Query experiments, datasets, and logs using SQL syntax. Supports SELECT, FROM, WHERE, GROUP BY, ORDER BY, and LIMIT clauses.

* "Show me the last 10 logged requests with errors"
* "Compare accuracy scores between my GPT-4 and Claude experiments"
* "What were the costs for my recent chatbot experiments?"

### Summarize experiments

**`summarize_experiment`** - Get aggregated performance metrics for an experiment, optionally compared to a baseline.

* "Summarize the results of my latest A/B test"
* "Compare my experiment against the baseline"

### Generate permalinks

**`generate_permalink`** - Generate a direct web link to a Braintrust object for sharing or bookmarking.

* "Create a link to share my experiment results"
* "Generate a permalink to the customer-reviews dataset"

## Available resources

MCP resources provide contextual documentation that AI assistants can read to perform tasks more effectively.

### SDK installation guide

**`docs://sdk-install`** - Step-by-step guidance for installing the Braintrust SDK into a project. Your AI assistant can read this resource to help you:

* Set up Braintrust tracing in your application
* Install the SDK for Python, TypeScript, Go, Java, Ruby, or C#
* Configure auto-instrumentation for popular frameworks
* Run your first eval

Example: "Install the Braintrust SDK in my project" or "Add Braintrust tracing to my app"

### SQL query reference

**`docs://sql`** - Documentation for the `sql_query` tool, including syntax, available fields, and examples.

### URL formats

**`docs://url-formats`** - Reference for Braintrust URL patterns, used by the `resolve_object` tool.

### Experiments guide

**`docs://experiments`** - Background on Braintrust experiments and how to create them.

## Example workflows

### Install the Braintrust SDK

Ask your AI assistant to set up Braintrust in your project:

```
Install the Braintrust SDK and add tracing to my app.
```

Your assistant will read the `docs://sdk-install` resource, detect your programming language and frameworks, install the appropriate SDK, and configure auto-instrumentation. Once complete, it will run your app, verify traces are being logged, and provide a permalink to view them in Braintrust.

### Analyze experiment results

Ask your AI assistant:

```
What were the accuracy scores for my recent sentiment analysis experiments?
Compare costs between GPT-4 and Claude experiments.
```

The MCP server queries your data and returns results directly in the conversation.

### Debug production issues

```
Show me logs from the last hour where errors occurred.
What's the average latency for the summarizer prompt today?
```

### Share findings with teammates

```
Generate a link to my latest A/B test results.
Create a permalink to the customer-feedback dataset.
```

## Self-hosted instances

For self-hosted Braintrust, use your API URL:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "mcpServers": {
    "braintrust": {
      "url": "https://your-api-url.com/mcp"
    }
  }
}
```

<Note>
  Set the `MCP_SERVER_URL` environment variable to your API URL for OAuth discovery. Terraform deployments handle this automatically.
</Note>

## Troubleshooting

**Invalid client errors:**
Verify the URL is exactly `https://api.braintrust.dev/mcp` (no trailing slash).

**Connection timeouts:**
Check internet connection. Corporate networks may need to allowlist `api.braintrust.dev` and `*.braintrust.dev`.

**MCP server not appearing:**
Restart your AI tool and verify JSON configuration syntax.

## Next steps

* [Use the Data API](/api-reference) for programmatic access
* [Query with SQL](/reference/sql) for complex data analysis
* [View logs](/observe/view-logs) in the web interface
* [Run evaluations](/evaluate/run-evaluations) and analyze with MCP