> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[Codex](https://openai.com/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

<Steps>
  <Step title="Install Codex">
    If you haven't already, install [Codex](https://openai.com/codex/).
  </Step>

  <Step title="Set your API key">
    Set the `BRAINTRUST_API_KEY` environment variable with your API key:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export BRAINTRUST_API_KEY="your-api-key-here"
    ```
  </Step>

  <Step title="Add the Braintrust MCP server">
    Edit `~/.codex/config.toml` and add the Braintrust MCP server configuration:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    [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.
  </Step>

  <Step title="Verify the setup">
    Launch Codex with the environment variable set:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    codex
    ```

    Run the `/mcp` command to verify Braintrust is installed and accessible.
  </Step>
</Steps>

## 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](/integrations/developer-tools/mcp#available-tools) 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

<Accordion title="BRAINTRUST_API_KEY not found">
  * 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
</Accordion>

<Accordion title="MCP server not appearing">
  * 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
</Accordion>

<Accordion title="Authentication fails">
  * Verify your API key is correct (no extra spaces)
  * Ensure you can log into [Braintrust](https://www.braintrust.dev) using the account associated with the API key
  * Generate a new API key if needed
</Accordion>

<Accordion title="Connection errors">
  * 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`
</Accordion>

## Next steps

* **Run evaluations**: Check out the [evaluation guide](/evaluate/run-evaluations) to learn evaluation patterns.
* **Explore MCP tools**: See the [MCP documentation](/integrations/developer-tools/mcp#available-tools) for all available commands.
* **Query with SQL**: Learn how to [query with SQL](/reference/sql) for complex data analysis.