Braintrust MCP

The Braintrust MCP server is a hosted Model Context Protocol (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.

MCP or CLI?

Which one you want depends on what your tool can access and where the work needs to run.

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

Connect your client

The server is remote, so there is nothing to install or deploy. Point your client at your MCP endpoint and authenticate with OAuth or an API key.

Claude Code

Install Claude Code

If you haven’t already, install the Claude Code CLI or the Claude Code desktop app.

Add the Braintrust MCP server

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:

claude plugin list --json

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

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.

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:

Current project
All projects

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.

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.

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.These commands add the server but do not authenticate it. See Authentication for API-key setup and Endpoints for EU and self-hosted URLs.

Authenticate

Start the OAuth flow:

claude mcp login braintrust

MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.

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.

Claude Cowork

Follow Anthropic’s remote custom connector instructions using the Braintrust connection details below.

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

Choose the Braintrust endpoint

Use the MCP endpoint for your Braintrust organization. The default US endpoint is:

https://api.braintrust.dev/mcp

For EU and self-hosted organizations, find the appropriate URL under MCP endpoints.

Add the remote connector

Add a remote custom connector using Anthropic’s instructions. 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.

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.

Claude Desktop Chat

These instructions cover standard Chat in the Claude desktop app. For the Code tab, follow Claude Code setup. For Cowork, follow Cowork setup.

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

Install Claude Desktop

If you haven’t already, download and install Claude Desktop.

Add the Braintrust MCP server

Follow the Claude Desktop documentation 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.
Authentication: OAuth. Braintrust supports dynamic client registration, so you do not need to provide an OAuth client ID or client secret.

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.

Codex (OpenAI)

Install Codex

If you haven’t already, install the Codex CLI.

Add the Braintrust MCP server

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:

codex plugin list --json

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

codex plugin remove braintrust@braintrust-codex-plugins

Keep the marketplace if you use the trace-codex tracing plugin.

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

codex mcp add braintrust --url https://api.braintrust.dev/mcp

See Authentication for API-key setup and Endpoints for EU and self-hosted URLs.

Authenticate

Complete the browser sign-in if Codex starts an OAuth flow when you add the server. Otherwise, start it with:

codex mcp login braintrust

MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.

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.

Cursor

The Braintrust extension for 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.

Install Cursor

If you haven’t already, download and install Cursor.

Add the Braintrust MCP server

For the US data plane, click to automatically add the Braintrust MCP server: Add to CursorFor 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:

{
  "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 Settings > Data plane.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.

VS Code

Install VS Code

If you haven’t already, download and install Visual Studio Code.

Install an AI assistant extension

VS Code requires an AI assistant extension that supports the Model Context Protocol (MCP). Popular options include:

GitHub Copilot
Continue
Other MCP-compatible extensions

Install one of these extensions from the VS Code marketplace.

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:

{
    "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”):

{
    "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.

Restart VS Code

Reload the VS Code window (Cmd+R / Ctrl+R) or restart VS Code to apply the configuration.

Devin Desktop

Install Devin Desktop

If you haven’t already, install Devin Desktop.

Add the Braintrust MCP server

Edit ~/.codeium/windsurf/mcp_config.json and add the Braintrust server:

{
  "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.

Restart Devin Desktop

Close and reopen Devin Desktop to load the new MCP server configuration.

Gemini CLI

Install Gemini CLI

If you haven’t already, install Gemini CLI.

Set your API key

Set the BRAINTRUST_API_KEY environment variable with your API key:

export BRAINTRUST_API_KEY="your-api-key-here"

Add the Braintrust MCP server

Edit ~/.gemini/settings.json and add the Braintrust MCP server configuration:

{
  "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.

Verify the setup

Launch Gemini CLI and run the /mcp command to confirm the Braintrust server is connected.

Antigravity

Install Antigravity

If you haven’t already, install the Antigravity CLI.

Add the Braintrust MCP server

From the terminal, configure Antigravity’s connection to the Braintrust MCP server:

agy mcp add braintrust https://api.braintrust.dev/mcp

See Endpoints for EU and self-hosted URLs.

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.

Verify the connection

In Antigravity, ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.

Grok

Install Grok

If you haven’t already, install the Grok CLI.

Add the Braintrust MCP server

From the terminal, configure Grok’s connection to the Braintrust MCP server:

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 for scope and configuration details.See Authentication for API-key setup and Endpoints for EU and self-hosted URLs.

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.

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.

Zed

Install Zed

If you haven’t already, install Zed.

Add the Braintrust MCP server

Open your Zed settings (Cmd+, on macOS / Ctrl+, on Windows/Linux) and add the Braintrust server under context_servers:

{
  "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.

Verify the setup

Open the Agent Panel settings and confirm the Braintrust server appears in the context servers list with a green indicator.

Amp

Install Amp

If you haven’t already, install Amp.

Add the Braintrust MCP server

Edit ~/.config/amp/settings.json and add the Braintrust server under amp.mcpServers:

{
  "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.

Verify the setup

Restart Amp, then run amp mcp list to confirm the Braintrust server is connected.

OpenCode

For automatic tracing of OpenCode sessions, consider the Braintrust plugin for OpenCode.

Install OpenCode

If you haven’t already, install OpenCode.

Add the Braintrust MCP server

Add the Braintrust MCP server to your OpenCode configuration file, preserving any existing settings and servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "braintrust": {
      "type": "remote",
      "url": "https://api.braintrust.dev/mcp"
    }
  }
}

See Endpoints for EU and self-hosted URLs.

Authenticate

Start OAuth authentication from the terminal:

opencode mcp auth braintrust

Complete the sign-in in your browser. See OpenCode’s MCP authentication documentation for details.MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.

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.

pi does not include built-in MCP support. If you add MCP through a third-party adapter, follow its configuration instructions using your Braintrust MCP endpoint and a supported authentication method.

Warp

Install Warp

If you haven’t already, download and install Warp.

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.

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.

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 and authenticate with OAuth or an API key. Refer to your client’s documentation for where to configure these.

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:

Query recent logs to find examples of the behavior.
Write an evaluator that detects the unsupported claims, and test it against those traces before saving it.
Add the failing cases to a regression dataset, with the corrected responses as the expected output.
Run an eval comparing the current prompt against a proposed fix.

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

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.

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:

Set up tracing from scratch

Install the Braintrust SDK and add tracing to my app.

Instrument an existing integration

My app calls the OpenAI SDK. Add Braintrust tracing so those calls show up as spans.

Confirm traces are landing

Run my app and confirm traces are reaching Braintrust. Send me a permalink to one.

See Trace LLM calls for what auto-instrumentation covers. Resource: docs://sdk-install.

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 for how to control that behavior. Example prompts:

Find recent errors

Show me the last 10 logged requests with errors, and include the error message and the model used.

See what fields your data has

What fields are available in my production logs, and which ones are populated most often?

Break down cost

What did my chatbot experiments cost last week, broken down by model?

Compare an experiment to its baseline

Summarize my latest experiment and compare it to the baseline. Call out any score that regressed.

See SQL for query syntax, and View logs for the equivalent in the UI. Tools: sql_query, infer_schema, summarize_experiment. 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:

List recent work in a project

What experiments have I run recently in the 'chatbot' project?

Identify a Braintrust URL

What does this Braintrust URL point to, and what does the object contain?

Attribute traces to a teammate

Who logged the traces in this project this week, and which API keys produced the rest?

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

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:

Break down a trace

Break down what this trace actually did, step by step, and annotate each step.

Find the slow steps

Which steps in this trace took the longest?

Tools: get_trace_work_items, update_trace_work_report.

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:

Investigate a suspected problem

I think we might be overspending on web searches. Dig into that, and report a pattern if you find one.

Review active patterns

What patterns are active that I can solve right now?

Tools: search_patterns, new_pattern, update_pattern.

Configure Topics

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.

Rewinding a Topics automation processes historical traces and draws from your monthly model credits.

Example prompts:

Set up Topics from scratch

Set up Topics for my project. Validate the preprocessor and facets on real traces before you enable anything.

Write a preprocessor for an unusual trace shape

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.

Process historical traces

Rewind my Topics automation so it covers the last 30 days.

These tools expect your assistant to load the braintrust/topics-workflow skill 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.

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:

Preview a chart before saving it

Chart daily cost for this project over the last two weeks. Show it to me before you save anything.

Create a cost dashboard

Create a dashboard for daily cost analysis, with charts for total cost, cost per trace, and cost by model.

Add a chart to an existing view

Add a p95 latency chart to my error monitoring dashboard.

See Dashboards for the equivalent in the UI. Tools: generate_monitor_chart, list_monitoring_views, get_monitoring_view, create_monitoring_view, update_monitoring_view.

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:

Audit what's configured

What automations are configured in this project, and which ones are paused?

Alert on an error rate

Alert me when the error rate goes above 2% over the last hour.

Schedule recurring analysis

Every Monday morning, analyze last week's traces and summarize the top failure modes.

Pause an automation

Pause the online scoring rule you just created.

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

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:

Write a scorer for errors you found

Write a scorer that detects the errors in these logs, then test it on a few traces before saving it.

Create an LLM-as-a-judge

Create an LLM-as-a-judge scorer for helpfulness and test it on ten recent traces.

Apply a scorer to production logs

Set up online scoring with the scorer you just created. Leave it paused so I can review the configuration first.

Save a prompt as a new version

Save this prompt to my project as a new version of the summarizer prompt.

See Write prompts and Write scorers for details. Tools: create_prompt, create_evaluator, test_evaluator, update_online_scoring_rule.

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:

Build a regression dataset from failures

Add the traces that failed the helpfulness scorer to my regression dataset, and set the expected output from the corrected responses.

Compare two prompts

Run an eval comparing these two prompts on my regression dataset, and tell me which one wins.

Re-run last week's inputs

Run my task against the inputs from last week's experiment and compare the results.

See Run evaluations and Datasets for details. Tools: run_eval, edit_dataset_rows.

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

edit_dataset_rows can permanently delete dataset rows. Review the operations your assistant proposes before approving them.

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:

Check the default preprocessor

What preprocessor is my project using by default?

Change the default

Make the preprocessor you just created the project default.

See Projects for the equivalent in the UI. Tools: get_project_settings, set_project_default_preprocessor.

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:

Ask a product question

How do I create a custom scorer in Braintrust?

Clarify a concept

What's the difference between experiments and project logs?

Follow a guided workflow

Walk me through building an evaluator and applying it to my logs.

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

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 Settings > Data plane. 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 Settings > 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 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 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 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.

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.

AI providers

SDKs

Developer tools

Runtime environments

Connect your client

What the MCP can do

Install the Braintrust SDK

Explore your data

Analyze traces

Manage patterns

Configure Topics

Build dashboards

Manage automations and alerts

Author prompts and evaluators

Run evals and edit datasets

Manage project settings

Search docs and load skills

Reference

Endpoints

Authentication

Tools

Skills

Resources

Troubleshooting

​Connect your client

​What the MCP can do

​ Install the Braintrust SDK

​ Explore your data

​ Find and share objects

​ Analyze traces

​ Manage patterns

​ Configure Topics

​ Build dashboards

​ Manage automations and alerts

​ Author prompts and evaluators

​ Run evals and edit datasets

​ Manage project settings

​ Search docs and load skills

​Reference

​Endpoints

​Authentication

​Tools

​Skills

​Resources

​Troubleshooting

Connect your client

What the MCP can do

Install the Braintrust SDK

Explore your data

Find and share objects

Analyze traces

Manage patterns

Configure Topics

Build dashboards

Manage automations and alerts

Author prompts and evaluators

Run evals and edit datasets

Manage project settings

Search docs and load skills

Reference

Endpoints

Authentication

Tools

Skills

Resources

Troubleshooting