Tracing quickstart

Tracing captures the details of each step of an AI application’s execution. This lets you debug issues, understand model behavior, and optimize performance in production. This quickstart describes two ways to add tracing to your app: using AI via Braintrust’s MCP server, and by hand.

Use AI
By hand

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

2. Get API keys

Create API keys for:

Braintrust
Your AI provider or framework (OpenAI, Anthropic, Gemini, etc.)

Set them as environment variables:

export BRAINTRUST_API_KEY="<your-braintrust-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

3. Instrument your app

Now, update your code to send traces to Braintrust. To do this, you’ll set up Braintrust’s MCP server and ask it to add tracing to your app.

Configure MCP

The Braintrust MCP (Model Context Protocol) server allows AI coding assistants to understand your Braintrust setup and instrument your application. Add it to your AI tool’s configuration:

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 \
   https://api.braintrust.dev/mcp \
   --header "Authorization: Bearer $BRAINTRUST_API_KEY"

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

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

# To authenticate, open Claude Code and run this command:
/mcp

Claude Desktop

Install Claude Desktop

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

Add the Braintrust MCP server

Claude Desktop MCP connections are broken due to an upstream bug: anthropics/claude-code#5826.

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

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

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.

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.

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

https://api.braintrust.dev/mcp

Streamable HTTP transportPass 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 authenticationThe 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.

Prompt assistant

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.

4. View traces

In the Braintrust UI, go to your “Tracing quickstart” project and select Logs. You’ll see a trace for each request.Click into any trace to see:

Complete input prompt and model output
Token counts, latency, and cost
Model configuration (temperature, max tokens, etc.)
Request and response metadata

This is the value of observability - you can see every request, identify issues, and understand how your application behaves in production.

Learn more about viewing your logs in Braintrust.

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

2. Get API keys

Create API keys for:

Braintrust
Your AI provider or framework (OpenAI, Anthropic, Gemini, etc.)

Set them as environment variables:

export BRAINTRUST_API_KEY="<your-braintrust-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

3. Instrument your app

Now, update your code to send traces to Braintrust. To do this, you’ll install the SDK and add a few lines of setup code — auto-instrumentation handles the rest.

This quickstart covers auto-instrumentation with TypeScript, Python, Ruby, and Go. To learn how to use wrap functions to manually instrument your code (including .NET and Java), see Trace LLM calls.

Install SDKs

Install the Braintrust SDK and OpenAI client for your language. Braintrust supports many providers and frameworks — this example uses OpenAI.

TypeScript
Python
Ruby
Go

npm install braintrust openai tsx

pip install braintrust openai

Add to your Gemfile:

gem "braintrust", require: "braintrust/setup"
gem "ruby-openai"

Then install:

bundle install

Install Orchestrion for compile-time auto-instrumentation:

go install github.com/DataDog/orchestrion@latest

Create orchestrion.tool.go in your project root:

//go:build tools

package main

import (
	_ "github.com/DataDog/orchestrion"
	_ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/all"
)

Instrument your code

The following example auto-instruments an application that asks a question to OpenAI:

quickstart.ts

import { initLogger } from "braintrust";
import OpenAI from "openai";

// Initialize Braintrust - this is all you need!
initLogger({
  apiKey: process.env.BRAINTRUST_API_KEY,
  projectName: "Tracing quickstart (TypeScript)",
});

// Create OpenAI client - no wrapping needed!
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// All LLM calls are automatically traced
const response = await client.responses.create({
  model: "gpt-5-mini",
  input: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is machine learning?" }
  ]
});

console.log(response.output_text);

Run this code:

# Using tsx (recommended)
npx tsx --import braintrust/hook.mjs quickstart.ts

# Or using ts-node
npx ts-node --import braintrust/hook.mjs quickstart.ts

All LLM calls are automatically logged to Braintrust.

This quickstart uses auto-instrumentation. Braintrust also supports wrap functions, the Braintrust gateway, and framework-specific setup — see Trace LLM calls for the full picture.

4. View traces

In the Braintrust UI, go to your “Tracing quickstart” project and select Logs. You’ll see a trace for each request.Click into any trace to see:

Complete input prompt and model output
Token counts, latency, and cost
Model configuration (temperature, max tokens, etc.)
Request and response metadata

This is the value of observability - you can see every request, identify issues, and understand how your application behaves in production.

Learn more about viewing your logs in Braintrust.

Troubleshoot

Not seeing traces in the UI?

Verify BRAINTRUST_API_KEY is set and starts with sk- (echo $BRAINTRUST_API_KEY)
Check that the project name in your code matches the project you’re looking at in the UI
Check your console for error messages — common issues are invalid API key, network connectivity, or firewall blocking api.braintrust.dev

TypeScript auto-instrumentation not working?

Run with node --import braintrust/hook.mjs (not --loader, which is deprecated)
Verify braintrust is installed (npm list braintrust)
Call initLogger() with a project name before making any LLM calls
Verify BRAINTRUST_API_KEY is set in your environment
Using a bundler (Vite, Webpack, esbuild, Rollup)? Use the bundler plugin instead of --import. See TypeScript SDK documentation
Requires Node.js 18.19.0+ or 20.6.0+ for --import flag support (node --version)

Python auto-instrumentation not working?

Call braintrust.auto_instrument() at the start of your application, before any AI library imports or client creation
Verify BRAINTRUST_API_KEY is set in your environment

Ruby auto-instrumentation not working?

Ensure your Gemfile has gem "braintrust", require: "braintrust/setup" (note the require: option)
Your application must load Bundler with require 'bundler/setup' and Bundler.require (default in Rails, may need to be added in Sinatra/Rack)
Verify BRAINTRUST_API_KEY is set in your environment

Go auto-instrumentation not working?

Ensure you have a go.mod file (go mod init your-project-name if not)
Verify Orchestrion is installed (orchestrion version). If not, reinstall with go install github.com/DataDog/orchestrion@latest
Ensure orchestrion.tool.go exists in your project root with the correct imports
Build with orchestrion go build — regular go build won’t instrument your code
Verify BRAINTRUST_API_KEY is set in your environment
Requires Go 1.24 or later (go version)

MCP not working?

Verify the URL is exactly https://api.braintrust.dev/mcp (no trailing slash)
Check internet connection — corporate networks may need to allowlist api.braintrust.dev and *.braintrust.dev
Restart your AI tool and verify JSON configuration syntax

Need help?

Join our Discord
Email us at support@braintrust.dev
Use the Loop feature in the Braintrust UI

Next steps

Explore the full Braintrust workflow
Go deeper with tracing:
- Explore integrations with AI providers, SDKs, and developer tools
- Trace application logic for application logic
- Capture user feedback like thumbs up/down
- Analyze logs for patterns and issues

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

2. Get API keys

3. Instrument your app

4. View traces

2. Get API keys

3. Instrument your app

4. View traces

Troubleshoot

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​1. Sign up

​2. Get API keys

​3. Instrument your app

​4. View traces

​1. Sign up

​2. Get API keys

​3. Instrument your app

​4. View traces

​Troubleshoot

​Next steps

1. Sign up

2. Get API keys

3. Instrument your app

4. View traces

1. Sign up

2. Get API keys

3. Instrument your app

4. View traces

Troubleshoot

Next steps