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

> Connect Claude Code, Cursor, Codex, and other MCP clients to Braintrust. Query logs, author scorers, configure Topics, and run evals from your editor.

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.

The Braintrust MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that lets AI coding tools read and write your Braintrust data directly. Query production logs, author prompts and scorers, configure monitoring, and run evals from Claude Code, Cursor, Codex, VS Code, and any other MCP-compatible client.

<Accordion title="MCP or CLI?">
  Which one you want depends on what your tool can access and where the work needs to run.

  * **[MCP](/docs/integrations/developer-tools/mcp)**: Best when your AI tool can connect to Braintrust but has no authenticated shell, which is common in chat applications. It also fits when you want an assistant to reason over your Braintrust data and take several connected actions in one conversation, without installing and maintaining a CLI in its execution environment.
  * **[`bt` CLI](/docs/reference/cli/quickstart)**: Best for repeatable work in scripts, CI, local files, and shell pipelines, where you want deterministic commands instead of an assistant's judgment. Coding agents with shell access can call those commands too.

  If your tool supports both, either one works. Pick whichever is more reliable for the task at hand.
</Accordion>

## Connect your client

The server is remote, so there is nothing to install or deploy. Point your client at your [MCP endpoint](#endpoints) and authenticate with [OAuth or an API key](#authentication).

<AccordionGroup>
  <Accordion title="Claude Code" icon="https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Note>
      The [Braintrust plugin for Claude Code](/docs/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="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="Cursor" icon="https://img.logo.dev/cursor.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Note>
      The [Braintrust extension for Cursor](/docs/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="Devin Desktop" icon="https://img.logo.dev/devin.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Devin Desktop">
        If you haven't already, install [Devin Desktop](https://devin.ai/desktop).
      </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 Devin Desktop">
        Close and reopen Devin Desktop to load the new MCP server configuration.
      </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="Antigravity" icon="https://img.logo.dev/antigravity.google?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    <Steps>
      <Step title="Install Antigravity">
        If you haven't already, install [Antigravity](https://antigravity.google/).
      </Step>

      <Step title="Open the MCP configuration">
        Open Antigravity settings, go to the **Customizations** tab, and select **Open MCP config** to edit `mcp_config.json` (located at `~/.gemini/config/mcp_config.json`).
      </Step>

      <Step title="Add the Braintrust MCP server">
        Add the Braintrust server to `mcp_config.json`:

        ```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="Refresh the server list">
        Save the file, then refresh the **Installed MCP servers** section to load the new configuration.
      </Step>
    </Steps>
  </Accordion>

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

      <Step title="Add the Braintrust MCP server">
        Open your Zed settings (`Cmd+,` on macOS / `Ctrl+,` on Windows/Linux) and add the Braintrust server under `context_servers`:

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

        Replace `YOUR_BRAINTRUST_API_KEY` with your actual API key.

        If you omit the `headers` field, Zed prompts you to authenticate via OAuth when you first use the server.
      </Step>

      <Step title="Verify the setup">
        Open the Agent Panel settings and confirm the Braintrust server appears in the context servers list with a green indicator.
      </Step>
    </Steps>
  </Accordion>

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

      <Step title="Add the Braintrust MCP server">
        Edit `~/.config/amp/settings.json` and add the Braintrust server under `amp.mcpServers`:

        ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        {
          "amp.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.
      </Step>

      <Step title="Verify the setup">
        Restart Amp, then run `amp mcp list` to confirm the Braintrust server is connected.
      </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](/docs/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="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. Most clients that support remote MCP servers accept a URL and optional headers. Point the client at your [MCP endpoint](/docs/integrations/developer-tools/mcp#endpoints) and [authenticate](/docs/integrations/developer-tools/mcp#authentication) with OAuth or an API key. Refer to your client's documentation for where to configure these.
  </Accordion>
</AccordionGroup>

## What the MCP can do

Your assistant works with the data and objects in your Braintrust organization, and it chains several tools in one turn. Suppose a support chatbot starts making claims about your product that aren't true. In a single conversation, your assistant can:

1. [Query recent logs](#explore-your-data) to find examples of the behavior.
2. [Write an evaluator](#author-prompts-and-evaluators) that detects the unsupported claims, and test it against those traces before saving it.
3. [Add the failing cases](#run-evals-and-edit-datasets) to a regression dataset, with the corrected responses as the expected output.
4. [Run an eval](#run-evals-and-edit-datasets) comparing the current prompt against a proposed fix.

Each step produces a real Braintrust object, and your assistant [returns a permalink](#find-and-share-objects) so you can inspect or share it. Each capability below lists the tools behind it, and [Tools](#tools) describes every tool in one place.

<Warning>
  Write tools act on your Braintrust organization using the permissions of your authenticated account. Configure your MCP client to require confirmation before it runs a write tool.
</Warning>

### <Icon icon="code" /> Install the Braintrust SDK

Before you can query anything, your application has to send traces to Braintrust. Your assistant handles that setup: it detects your programming language and frameworks, installs the appropriate SDK, and configures auto-instrumentation. Once complete, it runs your app, verifies traces are being logged, and provides a permalink to view them in Braintrust.

Example prompts:

<AccordionGroup>
  <Accordion title="Set up tracing from scratch">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Install the Braintrust SDK and add tracing to my app.
    ```
  </Accordion>

  <Accordion title="Instrument an existing integration">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    My app calls the OpenAI SDK. Add Braintrust tracing so those calls show up as spans.
    ```
  </Accordion>

  <Accordion title="Confirm traces are landing">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Run my app and confirm traces are reaching Braintrust. Send me a permalink to one.
    ```
  </Accordion>
</AccordionGroup>

See [Trace LLM calls](/docs/instrument/trace-llm-calls) for what auto-instrumentation covers.

**Resource**: [`docs://sdk-install`](#resources).

### <Icon icon="search" /> Explore your data

Your assistant can answer questions about what your application actually did. It queries logs, experiments, and datasets with SQL, discovers the fields and value distributions in a data source before writing a query, and pulls aggregated metrics for an experiment with or without a baseline to compare against. Because it reads the same data the UI shows, you can investigate a production issue without switching to a browser.

When a query returns more than 1 MB, `sql_query` returns a signed URL to the full result instead of inline rows, so your assistant can work with production-scale results without filling its context window. See [Tools](#tools) for how to control that behavior.

Example prompts:

<AccordionGroup>
  <Accordion title="Find recent errors">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Show me the last 10 logged requests with errors, and include the error message and the model used.
    ```
  </Accordion>

  <Accordion title="See what fields your data has">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What fields are available in my production logs, and which ones are populated most often?
    ```
  </Accordion>

  <Accordion title="Break down cost">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What did my chatbot experiments cost last week, broken down by model?
    ```
  </Accordion>

  <Accordion title="Compare an experiment to its baseline">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Summarize my latest experiment and compare it to the baseline. Call out any score that regressed.
    ```
  </Accordion>
</AccordionGroup>

See [SQL](/docs/reference/sql) for query syntax, and [View logs](/docs/observe/view-logs) for the equivalent in the UI.

**Tools**: `sql_query`, `infer_schema`, `summarize_experiment`.

### <Icon icon="link" /> Find and share objects

Most Braintrust tools take an object ID, so your assistant finds the right project, experiment, or dataset by name and translates between names and IDs on its own. It usually does this as a step inside a larger request rather than as something you ask for. When you want to hand a result to someone else, it produces a direct link to the object.

Example prompts:

<AccordionGroup>
  <Accordion title="List recent work in a project">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What experiments have I run recently in the 'chatbot' project?
    ```
  </Accordion>

  <Accordion title="Identify a Braintrust URL">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What does this Braintrust URL point to, and what does the object contain?
    ```
  </Accordion>

  <Accordion title="Get a link to share">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Give me a shareable link to those experiment results so I can post it for my team.
    ```
  </Accordion>
</AccordionGroup>

**Tools**: `list_recent_objects`, `resolve_object`, `generate_permalink`.

### <Icon icon="pentagon" /> Configure Topics

[Topics](/docs/observe/topics) preprocesses traces into text, extracts facets from that text, and clusters the results to show what your users actually do. Your assistant builds that pipeline for you: it writes a preprocessor that matches your trace shape, tests it against real traces before saving, defines the facets to extract, and enables the automation that keeps it running. It can also rewind an automation over historical traffic.

<Note>
  Rewinding a Topics automation processes historical traces and draws from your monthly [model credits](/docs/plans-and-limits#model-credits).
</Note>

Example prompts:

<AccordionGroup>
  <Accordion title="Set up Topics from scratch">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Set up Topics for my project. Validate the preprocessor and facets on real traces before you enable anything.
    ```
  </Accordion>

  <Accordion title="Write a preprocessor for an unusual trace shape">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    My traces don't store conversation text on LLM spans. Write a preprocessor that works with my trace shape, and test it on a few traces.
    ```
  </Accordion>

  <Accordion title="Process historical traces">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Rewind my Topics automation so it covers the last 30 days.
    ```
  </Accordion>
</AccordionGroup>

These tools expect your assistant to load the `braintrust/topics-workflow` [skill](#skills) first, so it validates each stage before saving.

**Tools**: `create_preprocessor`, `test_preprocessor_on_trace`, `create_facet`, `test_facet_on_trace`, `enable_topics_automation`, `set_topics_automation`, `rewind_topics_automation`.

### <Icon icon="chart-no-axes-column" /> Build monitor views

Monitor views collect the charts you check regularly. Your assistant previews a chart against real project logs so you can see it before anything is saved, then puts it into a new or existing view. It can also read back what a view already contains and edit charts in place, one at a time or in bulk.

Example prompts:

<AccordionGroup>
  <Accordion title="Preview a chart before saving it">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Chart daily cost for this project over the last two weeks. Show it to me before you save anything.
    ```
  </Accordion>

  <Accordion title="Create a cost dashboard">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Create a monitor view for daily cost analysis, with charts for total cost, cost per trace, and cost by model.
    ```
  </Accordion>

  <Accordion title="Add a chart to an existing view">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Add a p95 latency chart to my error monitoring view.
    ```
  </Accordion>
</AccordionGroup>

See [Dashboards](/docs/observe/dashboards) for the equivalent in the UI.

**Tools**: `generate_monitor_chart`, `list_monitoring_views`, `get_monitoring_view`, `create_monitoring_view`, `update_monitoring_view`.

### <Icon icon="radio" /> Manage automations and alerts

Automations watch your data so you don't have to. Your assistant inspects what a project already runs, including online scoring rules, exports, and retention policies, then creates what's missing: an alert on individual matching logs, an alert on an aggregate threshold over a recent window, an alert on environment updates, or a Loop job that analyzes recent traffic on a schedule. It can also pause and resume any of them.

Example prompts:

<AccordionGroup>
  <Accordion title="Audit what's configured">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What automations are configured in this project, and which ones are paused?
    ```
  </Accordion>

  <Accordion title="Alert on an error rate">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Alert me when the error rate goes above 2% over the last hour.
    ```
  </Accordion>

  <Accordion title="Schedule recurring analysis">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Every Monday morning, analyze last week's traces and summarize the top failure modes.
    ```
  </Accordion>

  <Accordion title="Pause an automation">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Pause the online scoring rule you just created.
    ```
  </Accordion>
</AccordionGroup>

See [Alerts](/docs/observe/alerts) for delivery channels and tuning.

**Tools**: `list_automations`, `set_automation_status`, `create_log_alert`, `create_environment_update_alert`, `create_threshold_alert`, `create_scheduled_loop_job`.

### <Icon icon="triangle" /> Author prompts and evaluators

Prompts and evaluators are versioned objects that your application, experiments, and online scoring all share. Your assistant drafts one from what it found in your logs, runs it against real traces to see how it behaves before anything is saved, and saves it as a new version when you're satisfied. It can then attach an evaluator to an online scoring rule so it scores production logs continuously.

Example prompts:

<AccordionGroup>
  <Accordion title="Write a scorer for errors you found">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Write a scorer that detects the errors in these logs, then test it on a few traces before saving it.
    ```
  </Accordion>

  <Accordion title="Create an LLM-as-a-judge">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Create an LLM-as-a-judge scorer for helpfulness and test it on ten recent traces.
    ```
  </Accordion>

  <Accordion title="Apply a scorer to production logs">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Set up online scoring with the scorer you just created. Leave it paused so I can review the configuration first.
    ```
  </Accordion>

  <Accordion title="Save a prompt as a new version">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Save this prompt to my project as a new version of the summarizer prompt.
    ```
  </Accordion>
</AccordionGroup>

See [Write prompts](/docs/evaluate/write-prompts) and [Write scorers](/docs/evaluate/write-scorers) for details.

**Tools**: `create_prompt`, `create_evaluator`, `test_evaluator`, `update_online_scoring_rule`.

### <Icon icon="beaker" /> Run evals and edit datasets

Evals, and the datasets that feed them, are how you measure whether a change helps. Your assistant curates dataset rows from the failures it finds in your logs, then runs an experiment against them using a saved or inline task and whichever scorers you want. A prior experiment can supply the input data, in which case its outputs become the expected values.

Example prompts:

<AccordionGroup>
  <Accordion title="Build a regression dataset from failures">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Add the traces that failed the helpfulness scorer to my regression dataset, and set the expected output from the corrected responses.
    ```
  </Accordion>

  <Accordion title="Compare two prompts">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Run an eval comparing these two prompts on my regression dataset, and tell me which one wins.
    ```
  </Accordion>

  <Accordion title="Re-run last week's inputs">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Run my task against the inputs from last week's experiment and compare the results.
    ```
  </Accordion>
</AccordionGroup>

See [Run evaluations](/docs/evaluate/run-evaluations) and [Datasets](/docs/annotate/datasets) for details.

**Tools**: `run_eval`, `edit_dataset_rows`.

<Note>
  `run_eval` creates an experiment and can execute your code or call AI providers, so it incurs compute and model usage.
</Note>

<Warning>
  `edit_dataset_rows` can permanently delete dataset rows. Review the operations your assistant proposes before approving them.
</Warning>

### <Icon icon="settings-2" /> Manage project settings

Project settings hold the defaults that other functions inherit. Your assistant reads a project's typed settings, including which preprocessor facets and other project functions fall back to, and changes that default when you want a new one to apply everywhere.

Example prompts:

<AccordionGroup>
  <Accordion title="Check the default preprocessor">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What preprocessor is my project using by default?
    ```
  </Accordion>

  <Accordion title="Change the default">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Make the preprocessor you just created the project default.
    ```
  </Accordion>
</AccordionGroup>

See [Projects](/docs/admin/projects) for the equivalent in the UI.

**Tools**: `get_project_settings`, `set_project_default_preprocessor`.

### <Icon icon="book-open" /> Search docs and load skills

Your assistant grounds its answers in Braintrust documentation rather than guesswork, so it can explain a concept or find the right guide without leaving your editor. For multi-step work, it loads a skill first: a workflow guide that tells it the order to do things in and what to validate at each stage.

Example prompts:

<AccordionGroup>
  <Accordion title="Ask a product question">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    How do I create a custom scorer in Braintrust?
    ```
  </Accordion>

  <Accordion title="Clarify a concept">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What's the difference between experiments and project logs?
    ```
  </Accordion>

  <Accordion title="Follow a guided workflow">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Walk me through building an evaluator and applying it to my logs.
    ```
  </Accordion>
</AccordionGroup>

See [Skills](#skills) for what each skill covers and which tools expect one.

**Tools**: `search_docs`, `load_braintrust_skill`.

## Reference

### Endpoints

The MCP endpoint is your Braintrust API URL with `/mcp` appended, which depends on your organization's [data plane region](/docs/admin/organizations#data-plane-region):

| Region | MCP endpoint                        |
| ------ | ----------------------------------- |
| US     | `https://api.braintrust.dev/mcp`    |
| EU     | `https://api-eu.braintrust.dev/mcp` |

If you self-host, use the value shown in the **MCP URL** card in **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url).

The server uses the streamable HTTP transport. SSE-only MCP clients cannot connect.

### Authentication

The Braintrust MCP server supports two authentication methods:

* **OAuth**

  Clients that support OAuth-based MCP authentication connect without an API key. The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at `/.well-known/oauth-authorization-server` on the same host, so a client can register itself. The first time you use the server, your client opens a Braintrust authorization page where you approve access.

* **API key**

  Clients that don't support OAuth, along with programmatic clients, send a Braintrust API key as a bearer token on every request:

  ```
  Authorization: Bearer YOUR_BRAINTRUST_API_KEY
  ```

Create a key in **<Icon icon="settings-2" /> Settings** > [**<Icon icon="key-square" /> API keys**](https://www.braintrust.dev/app/~/configuration/org/api-keys). The server acts with the permissions of the account the key belongs to.

### Tools

Every tool the server exposes, in the order of the capabilities above.

| Tool                               | Description                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sql_query`                        | Query experiments, datasets, and logs using SQL. Supports `SELECT`, `FROM`, `WHERE`, `GROUP BY`, `ORDER BY`, and `LIMIT`.                                                                                                                                                                   |
| `infer_schema`                     | Discover the available fields, data types, and most common values in experiments, datasets, or logs.                                                                                                                                                                                        |
| `summarize_experiment`             | Get aggregated performance metrics for an experiment, optionally compared to a baseline.                                                                                                                                                                                                    |
| `list_recent_objects`              | List recently created projects, experiments, datasets, prompts, or functions you have access to.                                                                                                                                                                                            |
| `resolve_object`                   | Convert names to IDs or vice versa, and parse Braintrust URLs. Useful for looking up IDs before querying.                                                                                                                                                                                   |
| `generate_permalink`               | Generate a direct web link to a Braintrust object for sharing or bookmarking.                                                                                                                                                                                                               |
| `create_preprocessor`              | Create a versioned preprocessor from inline JavaScript that converts raw trace data into text.                                                                                                                                                                                              |
| `test_preprocessor_on_trace`       | Run a saved, global, or inline preprocessor on up to 50 span, trace, or group references without writing to the source trace.                                                                                                                                                               |
| `create_facet`                     | Create a versioned facet that extracts a short summary from spans or traces. Facet extraction always uses Braintrust's built-in facet model.                                                                                                                                                |
| `test_facet_on_trace`              | Run an inline facet definition on up to ten span, trace, or group references without writing the result to the source trace.                                                                                                                                                                |
| `enable_topics_automation`         | Enable Topics for a project. This seeds processing for new traffic and doesn't rewind historical data.                                                                                                                                                                                      |
| `set_topics_automation`            | Update an existing Topics automation's facets, scope, filters, sampling, or timing.                                                                                                                                                                                                         |
| `rewind_topics_automation`         | Rewind an existing Topics automation to process historical data from a start time or a recent window.                                                                                                                                                                                       |
| `generate_monitor_chart`           | Preview a monitor chart for project logs without modifying a saved view.                                                                                                                                                                                                                    |
| `list_monitoring_views`            | List a project's saved monitor views and chart IDs.                                                                                                                                                                                                                                         |
| `get_monitoring_view`              | Inspect a saved monitor view, including its options and ordered chart definitions.                                                                                                                                                                                                          |
| `create_monitoring_view`           | Create a project-scoped monitor view, optionally containing charts you already previewed.                                                                                                                                                                                                   |
| `update_monitoring_view`           | Insert, update, or remove charts in an existing monitor view, one edit at a time or several in bulk.                                                                                                                                                                                        |
| `list_automations`                 | List a project's automations, including online scoring rules, alerts, exports, retention policies, and Topics automations. Filter by `automation_id`, `name`, or `kind`. Returns complete configurations, so you can inspect an automation before updating it.                              |
| `set_automation_status`            | Pause or activate an alert, scheduled job, or online scoring rule.                                                                                                                                                                                                                          |
| `create_log_alert`                 | Create an alert for individual matching project logs. Use `config.interval_seconds` to throttle repeated notifications.                                                                                                                                                                     |
| `create_environment_update_alert`  | Create an alert for environment updates. Use `config.environment_filter` to limit notifications to specific environment slugs.                                                                                                                                                              |
| `create_threshold_alert`           | Create an alert for an aggregate over a recent window of project data, evaluated on a schedule. Use it for averages, counts, rates, percentages, percentiles, and distributions.                                                                                                            |
| `create_scheduled_loop_job`        | Create a Loop job that runs on an interval or cron schedule over a recent window of project data.                                                                                                                                                                                           |
| `create_prompt`                    | Create a versioned prompt from a completion-style prompt or chat messages. Set `if_exists` to `replace` to save a new version, or `ignore` to leave an existing prompt unchanged.                                                                                                           |
| `create_evaluator`                 | Create a versioned LLM or inline code evaluator. Set `output_type` to `score` for numeric scores or `classification` for categorical labels.                                                                                                                                                |
| `test_evaluator`                   | Run a saved, global, or inline evaluator against span, trace, or group references without writing results to the source trace.                                                                                                                                                              |
| `update_online_scoring_rule`       | Save or rewind an online scoring rule that runs saved evaluator functions. New rules default to paused.                                                                                                                                                                                     |
| `run_eval`                         | Run an experiment with a hosted dataset, inline rows, or a prior experiment as input data, any saved or inline task, and zero or more saved or inline scorers. When a prior experiment supplies the data, its outputs become expected values unless an expected value was already recorded. |
| `edit_dataset_rows`                | Insert, update, or delete up to 100 dataset rows. Target a dataset by ID or name, and set `create_if_missing` to create a new named dataset.                                                                                                                                                |
| `get_project_settings`             | Return a project's typed settings, including the effective default preprocessor. An unset default resolves to the built-in `thread` preprocessor.                                                                                                                                           |
| `set_project_default_preprocessor` | Set or clear a project's default preprocessor. Pass `null` to restore the built-in default. This changes the default used by facets and other project functions that don't select a preprocessor explicitly. Expects the `braintrust/topics-workflow` [skill](#skills) to be loaded first.  |
| `search_docs`                      | Search Braintrust documentation to find relevant guides, API references, and code examples.                                                                                                                                                                                                 |
| `load_braintrust_skill`            | Load a Braintrust workflow guide before using the tools it covers. Available skills are `braintrust/automations-workflow`, `braintrust/evaluator-workflow`, and `braintrust/topics-workflow`.                                                                                               |

When a result exceeds 1 MB, `sql_query` uploads it to object storage and returns an overflow envelope instead of inline rows. The envelope includes an `overflow_url` (a signed URL to the JSON result), a `byte_length`, a `row_count` (when available), and an `instructions` field describing how to retrieve the full result. Set `return_url: true` to request a URL even when the result is below the threshold, which is useful when you want to download or save results without putting them in model context. Field values in the result are truncated to `preview_length` characters (1024 by default). Set `preview_length: -1` to include untruncated field values.

### Skills

Skills are workflow guides your assistant loads with `load_braintrust_skill` and then follows. Where a tool reference tells your assistant what a tool does, a skill tells it the order to do things in, what to validate at each stage, and when to ask you for input.

* **`braintrust/topics-workflow`** - Configure, evaluate, and improve the [Topics](/docs/observe/topics) pipeline, covering preprocessors, facets, scope, and Topics automations.
* **`braintrust/evaluator-workflow`** - Create, test, refine, deploy, and rewind evaluators, and apply them to production logs with an online scoring rule.
* **`braintrust/automations-workflow`** - Set up, validate, and manage alerts and scheduled Loop jobs, including threshold-triggered work, Slack and webhook delivery, and refining existing automations.

The [Topics tools](#configure-topics) expect `braintrust/topics-workflow` to be loaded first, so your assistant validates the preprocessor and facets against real traces before it saves anything or enables an automation. Loading a skill is read-only and costs one tool call.

### Resources

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

* **`docs://sdk-install`** - Step-by-step guidance for installing the Braintrust SDK into a project, setting up tracing, configuring auto-instrumentation, and running your first eval.
* **`docs://sql`** - Documentation for the `sql_query` tool, including syntax, available fields, and examples.
* **`docs://url-formats`** - Reference for Braintrust URL patterns, used by the `resolve_object` tool.
* **`docs://experiments`** - Background on Braintrust experiments and how to create them.

`docs://sdk-install` has companion resources for Python, TypeScript, Go, Java, Ruby, and C#. Your assistant reads the one matching your project automatically.

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

**Server URL errors on a self-hosted deployment:**
The MCP server derives its own address from the forwarding headers your ingress sets. If it reports that it could not determine the server URL, set the `MCP_SERVER_URL` environment variable on your data plane to your API URL.