Braintrust MCP server: 34 tools, led by SQL

An evaluation platform that hands an agent SQL over its own logs, what happens when a result is too large to return, and which tools write.

Last verified 27 August 2026 · from Braintrust's own MCP documentation and the official MCP registry

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Braintrust MCP server?

It is Braintrust's server for the Model Context Protocol. Braintrust evaluates model output, so a connected agent reaches experiments, datasets, logs and the scorers that grade them.

The design is unusually query-first. Rather than a tool per report, three tools carry most of the weight: sql_query for arbitrary questions, infer_schema to find the fields, and summarize_experiment for aggregated metrics against a baseline.

The rest of the surface is authoring. An agent can create a prompt, create an evaluator, test it on a trace and then run an eval, which is a full loop rather than a read-only view.

It is strongest in agent observability, touches code and tests through evaluators, and reaches nothing in CI or production observability.

For an agent, Braintrust answers what your model did and how well it scored, and lets the agent write the next scorer. It has no view of the service around the model, so it pairs with a telemetry connector rather than replacing one.

What can an AI agent do with Braintrust?

The documented order is infer_schema first, then sql_query. infer_schema returns the available fields, their data types and the most common values. The agent composes the SQL from that schema, so the first query names fields that exist.

What connecting costs before the first question

A context window is the amount of text a model can hold at once. Thirty-four tools across nine categories arrive at connection, whether or not the agent calls one. On Claude that is 2,568 to 3,133 tokens; on the GPT encodings, 1,129 to 1,440.

Grouping does not reduce the bill. Braintrust sends all nine categories at connection, so the model reads nine sets of definitions before the first question.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted from the 34 tool entries in the vendor's own documentation. That documentation is the only public inventory.

The server could not be run for a live tools/list. No input schemas are available, so these figures cover each tool's name and description only. They are a floor, not the figure.

The Claude columns are measured through the API's count_tokens endpoint with an empty schema per tool. So they cover the same content as the GPT columns. The range there is two tokenizer generations. Haiku 4.5 and Opus 4.6 are at the low end. Opus 5 and Sonnet 5 are at the high end. The gap between them is about a quarter.

Can Braintrust watch your own AI agents?

Partly. Braintrust covers scoring and offline experiments, and covers tracing, prompt versions and cost only in part. It is an evaluation product first, and the table below shows that. Read from Braintrust's own documentation on 24 August 2026.

Braintrust MCP server limits: where answers come back incomplete

Both limits below are about a result that is smaller than it looks.

How to configure Braintrust MCP for agents

1. 1

   Turn on confirmation for writes

   Braintrust's own documentation asks you to configure the client to require confirmation before a write tool runs.

2. 2

   Understand the permission model

   Write tools act on your organization using the permissions of the authenticated account, so the account is the boundary.

3. 3

   Plan for large results

   sql_query returns a signed URL rather than rows above 1 MB, and return_url: true requests that behavior deliberately.

4. 4

   Pick the region

   The US endpoint is api.braintrust.dev/mcp and the EU endpoint is api-eu.braintrust.dev/mcp.

Paste this into your agent’s instructions

Field values are truncated by default and large results are replaced by a link, so an answer can rest on partial data without saying so.

When you answer using Braintrust MCP tools, state:
- The SQL you ran, if the answer came from sql_query.
- Whether the result overflowed to a URL, or whether field
  values were truncated at the default preview length.
- Whether you created or updated anything: alerts, monitor
  views, evaluators, prompts or dataset rows.
Never state that data does not exist. State that the query
above returned no rows.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Yes, when the questions are open ended. For a fixed report, Braintrust's API or SDK avoids the connector entirely.

The connector earns its place because it hands the agent SQL. An open query language over logs and experiments is not something a fixed set of endpoints reproduces.

For tracing model calls rather than evaluating them, Langfuse and Arize Phoenix cover that ground with their own connectors.

Connect it for open questions over evaluation data. Use the API for a report you already know how to shape.

Braintrust MCP server setup

The server is hosted, so there is nothing to install. Braintrust documents OAuth and an API key.

The registry entry carries a region variable, which is why the US and EU endpoints differ only by a hostname segment.

claude mcp add --transport http braintrust \
  https://api.braintrust.dev/mcp

{"mcpServers":{"braintrust":{
  "url":"https://api.braintrust.dev/mcp"}}}

[mcp_servers.braintrust]
url = "https://api.braintrust.dev/mcp"

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"braintrust":{"url":"https://api.braintrust.dev/mcp"}}}

{"mcpServers":{"braintrust":{"url":"https://api.braintrust.dev/mcp"}}}

{"servers":{"braintrust":{"url":"https://api.braintrust.dev/mcp"}}}

{"mcpServers":{"braintrust":{"url":"https://api.braintrust.dev/mcp"}}}

{"mcpServers":{"braintrust":{
  "url":"https://api.braintrust.dev/mcp",
  "headers":{"Authorization":"Bearer <your-key>"}}}}

{"mcpServers":{"braintrust":{
  "url":"https://api-eu.braintrust.dev/mcp"}}}

Read-only access, permissions and security

• Most of the surface writes

  Alerts, monitor views, evaluators, prompts, preprocessors, project settings and dataset rows are all creatable or editable from this connector.

• Braintrust asks for confirmation explicitly

  Its documentation warns that write tools act with the authenticated account's permissions and recommends client confirmation before any write runs.

• update_online_scoring_rule touches live traffic

  Changing an online scoring rule changes how production requests are graded.

• Query results can leave through a URL

  Above 1 MB, sql_query uploads the result to object storage and returns a signed link.

Troubleshooting

A query returns a URL instead of rows

The result exceeded 1 MB. The envelope carries an overflow_url, a byte_length, a row_count where available and instructions for retrieving the full result.

Field values look cut off

Values are truncated to preview_length characters, 1024 by default. Set preview_length: -1 to include untruncated values.

A first query fails on unknown fields

Call infer_schema first. It returns available fields, data types and the most common values for experiments, datasets or logs.

A write tool is refused

Write tools use the permissions of the authenticated account. Check what that account can do in the Braintrust organization.

Braintrust MCP server: Reference

What engineers report

The documentation is specific about limits, so the figures below are its own.

Tool inventory and limits read from Braintrust's own MCP documentation on 24 August 2026. An unauthenticated tools/list against api.braintrust.dev/mcp returned 401 on 27 August 2026, which is why this page is sourced from documentation rather than from the wire. The registry entry was read from the official MCP registry.

Should you connect an agent to Braintrust?

Yes. Best for OAuth with write confirmation on, and infer_schema called before the first query.

Strongest fit

Braintrust users who want an agent to ask open questions of their evaluation data rather than open a dashboard.

Main advantage

SQL over experiments, datasets and logs, with a documented path for results too large to return inline.

Main weakness

Most of the surface writes, so the connector needs client confirmation configured to be safe.

Operational risk

Alerts, online scoring rules and dataset rows are all editable with the authenticated account's permissions.

Frequently asked questions