> ## 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, such as ad-hoc lookups and exploration from your IDE.

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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.

## Set up the MCP server

<Note>
  The examples below use `https://api.braintrust.dev/mcp`, the US data plane. If your organization is on the EU [data plane](/docs/admin/organizations#data-plane-region), use `https://api-eu.braintrust.dev/mcp` instead. If you self-host, use the read-only MCP URL in your [Data plane settings](https://www.braintrust.dev/app/~/configuration/org/api-url).
</Note>

<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. The server is available at:

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

    **Streamable HTTP transport**

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

    ```
    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
    ```

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

    **OAuth authentication**

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

## Install the Braintrust SDK

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

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

Your assistant reads the [`docs://sdk-install`](#available-resources) resource, 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.

## Supported tools

Braintrust MCP provides read and write tools for the data and objects in your Braintrust organization. Your AI assistant can call several of them in one task. For example, it can query your logs, create a scorer from what it finds, and then run an eval to test it.

The tools below are grouped by what you would use them for.

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

### Explore your data

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

Example prompts:

* "Show me the last 10 logged requests with errors"
* "Compare accuracy scores between my GPT-4 and Claude experiments"
* "What were the costs for my recent chatbot experiments?"
* "What fields are available in my experiment data?"
* "Show me the schema for production logs"
* "What metadata fields exist in this dataset?"
* "Summarize the results of my latest A/B test"
* "Compare my experiment against the baseline"

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.

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

### Find and share objects

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

Example prompts:

* "Show me my recent experiments in the 'chatbot' project"
* "List datasets in the recommendation engine project"
* "What projects do I have access to?"
* "Find the ID for my 'sentiment-analysis' experiment"
* "What's the name of experiment abc123?"
* "Parse this Braintrust URL and tell me what object it points to"
* "Create a link to share my experiment results"
* "Generate a permalink to the customer-reviews dataset"

### Configure Topics

These tools configure the [Topics](/docs/observe/topics) pipeline, which preprocesses traces into text, extracts facets from that text, and clusters the results. Each one expects your assistant to load the `braintrust/topics-workflow` [skill](#available-skills) first.

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

Example prompts:

* "Set up Topics for my project"
* "My traces don't store conversation text on LLM spans. Write a preprocessor that works with my trace shape"

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

### Build monitor views

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

Example prompts:

* "Create a dashboard for daily cost analysis"
* "Add a p95 latency chart to my error monitoring view"

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

### Manage automations and alerts

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

Example prompts:

* "What automations are configured in this project?"
* "Alert me when the error rate goes above 2% over the last hour"
* "Pause the online scoring rule you just created"

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

### Author prompts and evaluators

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

Example prompts:

* "Write a scorer that detects the errors in these logs, then test it on a few traces"
* "Create an LLM-as-a-judge scorer for helpfulness"
* "Set up online scoring with the scorer you just created"

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

### Run evals and edit datasets

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

Example prompts:

* "Run an eval comparing these two prompts on my regression dataset"
* "Add these traces to my regression dataset and set the expected output"

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

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

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

### Manage project settings

* **`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](#available-skills) to be loaded first.

Example prompts:

* "What preprocessor is my project using by default?"
* "Make the preprocessor you just created the project default"

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

### Search docs and load skills

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

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

Example prompts:

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

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

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

## Next steps

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