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

​
Set up the MCP server

Braintrust provides a hosted MCP server with OAuth 2.0 authentication. Add it to your AI tool’s configuration:

​
Claude Code

# Install Claude Code (if not already installed)
npm install -g @anthropic-ai/claude-code

# Navigate to your project
cd your-project

# Add Braintrust MCP server
claude mcp add --transport http braintrust https://api.braintrust.dev/mcp

# Start Claude Code
claude

# Authenticate by typing /mcp
/mcp

​
Cursor

Click to automatically add Braintrust: Add to Cursor Or manually add to .cursor/mcp.json: 
{
  "mcpServers": {
    "braintrust": {
      "url": "https://api.braintrust.dev/mcp"
    }
  }
}

​
VS Code

  1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
  2. Run MCP: Add Server
  3. Select HTTP and enter:
    • URL: https://api.braintrust.dev/mcp
    • Name: Braintrust
  4. Click Add

​
Windsurf

Add to mcp_config.json: 
{
  "mcpServers": {
    "braintrust": {
      "url": "https://api.braintrust.dev/mcp"
    }
  }
}

​
Claude Desktop

  1. Open Settings (gear icon)
  2. Navigate to Connectors > Add custom connector
  3. Enter:
    • Name: Braintrust
    • URL: https://api.braintrust.dev/mcp

​
Authenticate

The MCP server uses OAuth 2.0 with PKCE for secure authentication. On first connection, the OAuth flow opens automatically:
  1. Your AI tool triggers the OAuth flow
  2. A browser window opens asking you to log into Braintrust
  3. After authentication, review the consent screen showing the redirect URL
  4. Click Yes, I trust this URL - Proceed
  5. Return to your AI tool
Your tool now has access to your Braintrust data.

​
Available tools

The MCP server provides these tools to your AI assistant:

​
Search documentation

search_docs - Find guides, API references, and code examples:
  • “How do I create a custom scorer?”
  • “Show me examples of BTQL queries”
  • “What’s the difference between experiments and project logs?”

​
Resolve objects

resolve_object - Convert names to IDs and vice versa:
  • “Find the ID for my ‘sentiment-analysis’ experiment”
  • “What’s the name of experiment abc123?”

​
List recent objects

list_recent_objects - Browse projects, experiments, and datasets:
  • “Show me my recent experiments in the ‘chatbot’ project”
  • “List datasets in the recommendation engine project”

​
Infer schemas

infer_schema - Understand data structure:
  • “What fields are available in my experiment data?”
  • “Show me the schema for production logs”

​
Query with BTQL

btql_query - Execute BTQL queries:
  • “Compare accuracy scores between my GPT-4 and Claude experiments”
  • “Show experiments where factuality score was below 0.7”
  • “What were the costs for my recent chatbot experiments?”

​
Summarize experiments

summarize_experiment - Get performance summaries:
  • “Summarize the results of my latest A/B test”
  • “Compare my experiment against the baseline”
generate_permalink - Create shareable links:
  • “Create a link to share my experiment results”
  • “Generate a permalink to the customer-reviews dataset”

​
Example workflows

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

​
Share findings with teammates

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

OAuth fails or gets stuck: Clear browser cache and try incognito mode. For SSO, ensure you’re logged into your SSO provider. 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. Access denied: Verify you can access the project in the Braintrust web interface. BTQL queries failing: Test queries in the web interface first. Use infer_schema to verify column names.

​
Next steps