Skip to main content
Codex is OpenAI’s command-line AI coding assistant. The Braintrust MCP server integrates with Codex, giving it access to your Braintrust projects, experiments, and logs.

​
Setup

1

Install Codex

If you haven’t already, install Codex.
2

Set your API key

Set the BRAINTRUST_API_KEY environment variable with your API key:
export BRAINTRUST_API_KEY="your-api-key-here"
3

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

Verify the setup

Launch Codex with the environment variable set:
codex
Run the /mcp command to verify Braintrust is installed and accessible.

​
Usage

Once configured, Codex can access Braintrust data through the MCP server. You can fetch experiment results, query logs, log data, and more. See MCP documentation for details. Example prompts in Codex:
  • “Show me my recent Braintrust experiments”
  • “Query the last 10 logged requests with errors”
  • “What’s the average latency for the summarizer prompt today?”
  • “Compare accuracy scores between my GPT-4 and Claude experiments”

​
Troubleshooting

  • Verify the variable is set: echo $BRAINTRUST_API_KEY (macOS/Linux) or echo %BRAINTRUST_API_KEY% (Windows)
  • Ensure you’ve reloaded your shell after setting the variable
  • Check that Codex is launched from a shell where the variable is set
  • Verify the TOML configuration syntax is correct
  • Check that the file path is exactly ~/.codex/config.toml
  • Run /mcp in Codex to see available MCP servers
  • Try restarting Codex
  • Verify your API key is correct (no extra spaces)
  • Ensure you can log into Braintrust using the account associated with the API key
  • Generate a new API key if needed
  • Verify the URL is exactly https://api.braintrust.dev/mcp (no trailing slash)
  • Check your internet connection
  • Corporate networks may need to allowlist api.braintrust.dev and *.braintrust.dev

​
Next steps