Braintrust MCP

The Model Context Protocol (MCP) enables AI coding tools to access your Braintrust data directly. Query experiments, search documentation, and analyze production logs from tools like Claude Code, Cursor, VS Code, Windsurf, and Claude Desktop.

Set up the MCP server

Claude Code

The Braintrust plugin for Claude Code wraps the MCP server and adds tracing capabilities. If you’ve installed that plugin, you don’t need to configure MCP separately.

Install Claude Code

If you haven’t already, install Claude Code.

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

Add Braintrust MCP server with API key authentication:

claude mcp add --transport http braintrust \
  --header "Authorization: Bearer $YOUR_BRAINTRUST_API_KEY" \
  https://api.braintrust.dev/mcp

Alternatively, you can use OAuth authentication instead of an API key:

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

# Authenticate by typing /mcp
/mcp

Claude Desktop

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
URL: https://api.braintrust.dev/mcp

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.

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.

Install Cursor

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

Add the Braintrust MCP server

Click to automatically add the Braintrust MCP server: Add to CursorOr manually add 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.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.

Windsurf

Install Windsurf

If you haven’t already, install Windsurf.

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 Windsurf

Close and reopen Windsurf to load the new MCP server configuration.

Codex (OpenAI)

Install Codex

If you haven’t already, install Codex.

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 ~/.codex/config.toml and add the Braintrust MCP server configuration:

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

Verify the setup

Launch Codex with the environment variable set:

codex

Run the /mcp command to verify Braintrust is installed and accessible.

OpenCode

Install OpenCode

If you haven’t already, install OpenCode.

Add the Braintrust MCP server

Edit your OpenCode configuration file and add the Braintrust MCP server:

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

Restart OpenCode

Restart OpenCode to apply the configuration changes.

Available tools

The MCP server provides these tools to your AI assistant:

Search documentation

search_docs - Search Braintrust documentation using semantic search to find relevant guides, API references, and code examples.

“How do I create a custom scorer?”
“Show me examples of SQL queries”
“What’s the difference between experiments and project logs?”

Resolve objects

resolve_object - Convert names to IDs (or vice versa) and parse Braintrust URLs. Useful for looking up object IDs before querying.

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

List recent objects

list_recent_objects - List recently created projects, experiments, datasets, prompts, or functions you have access to.

“Show me my recent experiments in the ‘chatbot’ project”
“List datasets in the recommendation engine project”
“What projects do I have access to?”

Infer schema

infer_schema - Analyze the structure and content of experiments, datasets, or logs. Discovers available fields, data types, and shows the most common values for each field.

“What fields are available in my experiment data?”
“Show me the schema for production logs”
“What metadata fields exist in this dataset?”

Query with SQL

sql_query - Query experiments, datasets, and logs using SQL syntax. Supports SELECT, FROM, WHERE, GROUP BY, ORDER BY, and LIMIT clauses.

“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?”

Summarize experiments

summarize_experiment - Get aggregated performance metrics for an experiment, optionally compared to a baseline.

“Summarize the results of my latest A/B test”
“Compare my experiment against the baseline”

Generate permalinks

generate_permalink - Generate a direct web link to a Braintrust object for sharing or bookmarking.

“Create a link to share my experiment results”
“Generate a permalink to the customer-reviews dataset”

Available resources

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

SDK installation guide

docs://sdk-install - Step-by-step guidance for installing the Braintrust SDK into a project. Your AI assistant can read this resource to help you:

Set up Braintrust tracing in your application
Install the SDK for Python, TypeScript, Go, Java, Ruby, or C#
Configure auto-instrumentation for popular frameworks
Run your first eval

Example: “Install the Braintrust SDK in my project” or “Add Braintrust tracing to my app”

SQL query reference

docs://sql - Documentation for the sql_query tool, including syntax, available fields, and examples.

URL formats

docs://url-formats - Reference for Braintrust URL patterns, used by the resolve_object tool.

Experiments guide

docs://experiments - Background on Braintrust experiments and how to create them.

Example workflows

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 will read the docs://sdk-install resource, detect your programming language and frameworks, install the appropriate SDK, and configure auto-instrumentation. Once complete, it will run your app, verify traces are being logged, and provide a permalink to view them in Braintrust.

Analyze experiment results

Ask your AI assistant:

What were the accuracy scores for my recent sentiment analysis experiments?
Compare costs between GPT-4 and Claude experiments.

The MCP server queries your data and returns results directly in the conversation.

Debug production issues

Show me logs from the last hour where errors occurred.
What's the average latency for the summarizer prompt today?

Generate a link to my latest A/B test results.
Create a permalink to the customer-feedback dataset.

Self-hosted instances

For self-hosted Braintrust, use your API URL:

{
  "mcpServers": {
    "braintrust": {
      "url": "https://your-api-url.com/mcp"
    }
  }
}

Set the MCP_SERVER_URL environment variable to your API URL for OAuth discovery. Terraform deployments handle this 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.

Next steps

Use the Data API for programmatic access
Query with SQL for complex data analysis
View logs in the web interface
Run evaluations and analyze with MCP

AI providers

SDKs

Developer tools

Set up the MCP server

Available tools

Search documentation

Resolve objects

List recent objects

Infer schema

Query with SQL

Summarize experiments

Generate permalinks

Available resources

SDK installation guide

SQL query reference

URL formats

Experiments guide

Example workflows

Install the Braintrust SDK

Analyze experiment results

Debug production issues

Self-hosted instances

Troubleshooting

Next steps

AI providers

SDKs

Developer tools

​Set up the MCP server

​Available tools

​Search documentation

​Resolve objects

​List recent objects

​Infer schema

​Query with SQL

​Summarize experiments

​Generate permalinks

​Available resources

​SDK installation guide

​SQL query reference

​URL formats

​Experiments guide

​Example workflows

​Install the Braintrust SDK

​Analyze experiment results

​Debug production issues

​Share findings with teammates

​Self-hosted instances

​Troubleshooting

​Next steps

Set up the MCP server

Available tools

Search documentation

Resolve objects

List recent objects

Infer schema

Query with SQL

Summarize experiments

Generate permalinks

Available resources

SDK installation guide

SQL query reference

URL formats

Experiments guide

Example workflows

Install the Braintrust SDK

Analyze experiment results

Debug production issues

Share findings with teammates

Self-hosted instances

Troubleshooting

Next steps