> ## 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, Cowork, Cursor, Codex, and other MCP clients to Braintrust. Query logs, author scorers, configure Topics, and run evaluations

The Braintrust MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that lets AI tools read and write your Braintrust data directly. Query production logs, author prompts and scorers, configure monitoring, and run evals from Claude Code, Cowork, 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">
    <Steps>
      <Step title="Install Claude Code">
        If you haven't already, install the [Claude Code CLI](https://code.claude.com/docs/en/overview) or the [Claude Code desktop app](https://code.claude.com/docs/en/desktop-quickstart).
      </Step>

      <Step title="Add the Braintrust MCP server">
        <Accordion title="Remove the retired Braintrust MCP plugin (if installed)">
          To connect Claude Code to the Braintrust MCP server, Braintrust previously published a `braintrust` plugin. However, the plugin has been retired in favor of Claude Code's native MCP configuration. If you installed the plugin, remove it before configuring the direct connection below.

          Check whether the plugin is still installed:

          ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          claude plugin list --json
          ```

          If `braintrust@braintrust-claude-plugin` appears in the list, use its `scope` value to remove it:

          ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          claude plugin uninstall braintrust@braintrust-claude-plugin \
            --scope <scope>
          ```

          If it appears at more than one scope, repeat the command for each scope. Keep the marketplace if you use the `trace-claude-code` tracing plugin.
        </Accordion>

        From the terminal, configure Claude Code's connection to the Braintrust MCP server. Choose whether to make it available only in the current project or across all of your projects:

        <Tabs>
          <Tab title="Current project">
            ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
            claude mcp add --transport http braintrust \
              https://api.braintrust.dev/mcp
            ```

            Claude stores this local-scope configuration in `~/.claude.json` under the current project's path.
          </Tab>

          <Tab title="All projects">
            ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
            claude mcp add --scope user --transport http braintrust \
              https://api.braintrust.dev/mcp
            ```

            Claude stores this user-scope configuration in `~/.claude.json` and makes it available across your projects.
          </Tab>
        </Tabs>

        Both scopes work in the Claude Code CLI and in local Code-tab sessions of the desktop app. They do not apply to standard Chat or Cowork, which use [connectors](https://support.claude.com/en/articles/11176164).

        These commands add the server but do not authenticate it. See [Authentication](/docs/integrations/developer-tools/mcp#authentication) for API-key setup and [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
      </Step>

      <Step title="Authenticate">
        Start the OAuth flow:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude mcp login braintrust
        ```

        MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
      </Step>

      <Step title="Verify the connection">
        Open or restart Claude Code in the interface you use:

        * **CLI**: Start Claude Code and run `/mcp` to confirm that the Braintrust server is connected.
        * **Code tab**: Start a local session. For local scope, open the project where you ran `claude mcp add`. For user scope, open any project.

        Ask Claude Code to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Claude Cowork" icon="https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    Follow [Anthropic's remote custom connector instructions](https://support.claude.com/en/articles/11175166) using the Braintrust connection details below.

    <Note>
      Team and Enterprise organizations require an Owner or Primary Owner to add the connector before members connect their individual accounts.
    </Note>

    <Steps>
      <Step title="Choose the Braintrust endpoint">
        Use the MCP endpoint for your Braintrust organization. The default US endpoint is:

        ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        https://api.braintrust.dev/mcp
        ```

        For EU and self-hosted organizations, find the appropriate URL under [MCP endpoints](/docs/integrations/developer-tools/mcp#endpoints).
      </Step>

      <Step title="Add the remote connector">
        Add a remote custom connector using Anthropic's [instructions](https://support.claude.com/en/articles/11175166). Provide these values when prompted:

        * **Name**: `Braintrust`
        * **Remote MCP server URL**: The endpoint from the previous step.
        * **Authentication**: OAuth. Braintrust supports dynamic client registration, so you do not need to provide an OAuth client ID or client secret.
      </Step>

      <Step title="Authenticate and verify the connection">
        Follow Anthropic's instructions to connect your Braintrust account and make the connector available to Cowork. Complete the Braintrust OAuth flow when prompted.

        Ask Cowork to list your recent Braintrust projects. Confirm that Cowork uses the Braintrust connector and returns projects your account can access.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Claude Desktop Chat" icon="https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    These instructions cover standard Chat in the Claude desktop app. For the Code tab, follow [Claude Code setup](/docs/integrations/developer-tools/claude-code#set-up-the-mcp-server). For Cowork, follow [Cowork setup](/docs/integrations/developer-tools/claude-cowork#set-up-the-mcp-server).

    <Note>
      Team and Enterprise organizations require an Owner or Primary Owner to add the connector before members connect their individual accounts.
    </Note>

    <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`.
        * **Remote MCP server URL**: `https://api.braintrust.dev/mcp`. For EU and self-hosted organizations, use your [MCP endpoint](/docs/integrations/developer-tools/mcp#endpoints).
        * **Authentication**: OAuth. Braintrust supports dynamic client registration, so you do not need to provide an OAuth client ID or client secret.
      </Step>

      <Step title="Authenticate and verify the connection">
        Follow Anthropic's instructions to connect your Braintrust account and make the connector available to Chat. Complete the Braintrust OAuth flow when prompted.

        Ask Claude to list your recent Braintrust projects. Confirm that it uses the Braintrust connector and returns projects your account can access.
      </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 the [Codex CLI](https://developers.openai.com/codex/cli).
      </Step>

      <Step title="Add the Braintrust MCP server">
        <Accordion title="Remove the retired Braintrust MCP plugin (if installed)">
          To connect Codex to the Braintrust MCP server, Braintrust previously published a `braintrust` plugin. However, the plugin has been retired in favor of Codex's native MCP configuration. If you installed the plugin, remove it before configuring the direct connection below.

          Check whether the plugin is still installed:

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

          If `braintrust@braintrust-codex-plugins` appears in the installed plugins, remove it:

          ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          codex plugin remove braintrust@braintrust-codex-plugins
          ```

          Keep the marketplace if you use the `trace-codex` tracing plugin.
        </Accordion>

        From the terminal, configure Codex's connection to the Braintrust MCP server:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        codex mcp add braintrust --url https://api.braintrust.dev/mcp
        ```

        See [Authentication](/docs/integrations/developer-tools/mcp#authentication) for API-key setup and [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
      </Step>

      <Step title="Authenticate">
        Complete the browser sign-in if Codex starts an OAuth flow when you add the server. Otherwise, start it with:

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

        MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
      </Step>

      <Step title="Verify the connection">
        Open or restart Codex and run `/mcp` to confirm that the Braintrust server is connected. Ask Codex to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
      </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. For EU or self-hosted deployments, follow the extension's [API URL setup instructions](/docs/integrations/developer-tools/cursor#setup).
    </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">
        For the US data plane, click to automatically add the Braintrust MCP server: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=braintrust\&config=eyJ1cmwiOiJodHRwczovL2FwaS5icmFpbnRydXN0LmRldi9tY3AifQ%3D%3D)

        For EU or self-hosted deployments, use the manual configuration below and replace the URL as described after the example. You can also use this configuration for the US data plane. Add it to `.cursor/mcp.json`:

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

        For EU data-plane organizations, replace `https://api.braintrust.dev/mcp` with `https://api-eu.braintrust.dev/mcp`. For self-hosted Braintrust, use the **MCP URL** shown in **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url).

        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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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 the [Antigravity CLI](https://antigravity.google/product/antigravity-cli).
      </Step>

      <Step title="Add the Braintrust MCP server">
        From the terminal, configure Antigravity's connection to the Braintrust MCP server:

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

        See [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
      </Step>

      <Step title="Authenticate">
        In an `agy` session, enter `/mcp`, select the Braintrust MCP server, and press **Enter**. Choose **Authenticate** and complete the sign-in in your browser.

        MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
      </Step>

      <Step title="Verify the connection">
        In Antigravity, ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
      </Step>
    </Steps>
  </Accordion>

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

      <Step title="Add the Braintrust MCP server">
        From the terminal, configure Grok's connection to the Braintrust MCP server:

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

        Grok stores this configuration in `~/.grok/config.toml`. To configure only the current project, add `--scope project` to write `.grok/config.toml` instead. See [Grok's MCP documentation](https://docs.x.ai/build/features/mcp-servers) for scope and configuration details.

        See [Authentication](/docs/integrations/developer-tools/mcp#authentication) for API-key setup and [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
      </Step>

      <Step title="Authenticate">
        In Grok, enter `/mcps`, select the Braintrust MCP server, and press `i` to start OAuth authentication. Complete the sign-in in your browser.

        MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
      </Step>

      <Step title="Verify the connection">
        Run `grok mcp doctor braintrust` to check the connection. In Grok, ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
      </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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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">
        Add the Braintrust MCP server to your [OpenCode configuration file](https://opencode.ai/docs/config/), preserving any existing settings and servers:

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

        See [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
      </Step>

      <Step title="Authenticate">
        Start OAuth authentication from the terminal:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        opencode mcp auth braintrust
        ```

        Complete the sign-in in your browser. See [OpenCode's MCP authentication documentation](https://opencode.ai/docs/mcp-servers/#authenticating) for details.

        MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
      </Step>

      <Step title="Verify the connection">
        Run `opencode mcp list` to check the connection. Restart OpenCode, then ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="pi" icon="https://img.logo.dev/pi.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    pi [does not include built-in MCP support](https://pi.dev/docs/latest/usage#design-principles). If you add MCP through a third-party adapter, follow its configuration instructions using your [Braintrust MCP endpoint](/docs/integrations/developer-tools/mcp#endpoints) and a supported [authentication method](/docs/integrations/developer-tools/mcp#authentication).
  </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.

It can also reverse the lookup, finding a person's traces from their name or email.

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>

  <Accordion title="Attribute traces to a teammate">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Who logged the traces in this project this week, and which API keys produced the rest?
    ```
  </Accordion>
</AccordionGroup>

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

### <Icon icon="sparkles" /> Analyze traces

A long agent trace is hard to follow span by span. Your assistant partitions a single trace into chronological work sections and annotates each one, so you can see what a run actually did and where it spent its time.

Example prompts:

<AccordionGroup>
  <Accordion title="Break down a trace">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Break down what this trace actually did, step by step, and annotate each step.
    ```
  </Accordion>

  <Accordion title="Find the slow steps">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Which steps in this trace took the longest?
    ```
  </Accordion>
</AccordionGroup>

**Tools**: `get_trace_work_items`, `update_trace_work_report`.

### <Icon icon="scan-search" /> Manage patterns

Patterns record the recurring behaviors your traces reveal, so an investigation doesn't have to start over each time. Your assistant checks what has already been reported, catching duplicates that use different wording, adds a new pattern with supporting evidence, and attaches further evidence as it turns up.

Example prompts:

<AccordionGroup>
  <Accordion title="Investigate a suspected problem">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    I think we might be overspending on web searches. Dig into that, and report a pattern if you find one.
    ```
  </Accordion>

  <Accordion title="Review active patterns">
    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    What patterns are active that I can solve right now?
    ```
  </Accordion>
</AccordionGroup>

**Tools**: `search_patterns`, `new_pattern`, `update_pattern`.

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

Dashboards 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 dashboard. It can also read back what a dashboard 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 dashboard 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 dashboard.
    ```
  </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`, `list_slack_channels`.

### <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. For pattern, prompt, and scorer URLs, returns the containing project as `object_id` and the resource as `row_id`. App URLs retain their organization scope. Supply `org_name` to disambiguate name lookups. Ambiguous names return an error.                                                                                                   |
| `generate_permalink`               | Generate a direct web link to a Braintrust object for sharing or bookmarking. For `project_logs`, `project_patterns`, `project_prompts`, and `project_functions`, supply `project_name` or the project UUID as `object_id`. Pass `root_span_id` as `row_id` for log entries, or the resource ID as `row_id` for patterns, prompts, and scorers. Supply `org_name` to scope a name lookup to one organization. |
| `lookup_users`                     | Resolve Braintrust organization member IDs to names and emails. Pass a batch of user IDs, search by partial name or email, or list every member.                                                                                                                                                                                                                                                              |
| `lookup_api_keys`                  | Resolve API key and service token IDs to their names. Pass a batch of IDs, match an exact name, or list every key visible to you. Results follow existing API key and service token visibility rules.                                                                                                                                                                                                         |
| `get_trace_work_items`             | Return a chronological list of the meaningful LLM and tool spans in a trace, as input for the [work sections](/docs/observe/debug-traces) that **Analyze trace** produces.                                                                                                                                                                                                                                         |
| `update_trace_work_report`         | Save those work sections and per-span annotations back to the trace.                                                                                                                                                                                                                                                                                                                                          |
| `search_patterns`                  | Search existing project patterns by text, semantic similarity, ID, status, or quality. Pass `similar_to` with one or more pattern IDs or unreported pattern drafts to catch duplicates that use different wording.                                                                                                                                                                                            |
| `new_pattern`                      | Record a pattern the agent has identified, with the evidence behind it. The agent decides what counts as a pattern, so asking for one doesn't guarantee a record is written.                                                                                                                                                                                                                                  |
| `update_pattern`                   | Update an existing project pattern, or attach evidence to matching traces.                                                                                                                                                                                                                                                                                                                                    |
| `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.                                                                                                                                                                                                                                                                                                             |
| `list_slack_channels`              | List connected Slack workspaces and public channels for a project to resolve workspace and channel IDs before configuring Slack delivery.                                                                                                                                                                                                                                                                     |
| `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.

**Request body too large (HTTP 413):**
The MCP server accepts request bodies up to 100 MiB. A tool call whose payload exceeds that limit returns an HTTP 413 error. Split the input into smaller requests, or fetch the data incrementally.

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