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

# Grok

> Trace Grok sessions to Braintrust and access your Braintrust data through the MCP server

[Grok](https://grok.com/build) is xAI's coding agent. You can connect it to Braintrust in two ways:

* **Trace Grok sessions** to record session, turn, model call, and tool spans in Braintrust.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from Grok.

<Note>
  This guide covers the Grok CLI on macOS and Linux. The tracing hooks require Bash.
</Note>

## Trace Grok sessions

The [`trace-grok` plugin](https://github.com/braintrustdata/braintrust-grok-plugin) passes your interactions with Grok to `bt`, which in turn uses a background process to build and deliver the trace to Braintrust.

Grok continues to communicate directly with its model provider, and tracing failures do not stop your Grok session.

### Set up tracing

<Note>
  If `trace-grok` is already installed, follow [Update the tracing plugin](#update-the-tracing-plugin).
</Note>

<Steps>
  <Step title="Install Grok">
    If you haven't already, install the [Grok CLI](https://grok.com/build).
  </Step>

  <Step title="Install and authenticate bt">
    Follow the [`bt` CLI quickstart](/docs/reference/cli/quickstart) to install `bt` v0.19.3 or later, authenticate, and set your active context.
  </Step>

  <Step title="Enable tracing">
    <Warning>
      If you installed `trace-grok` from a local directory or a different repository, this command uninstalls that version and installs Braintrust's published plugin. Save a copy of any changes you made to the plugin's code or hooks before continuing.
    </Warning>

    Before starting Grok, run this command in a terminal:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable grok --project <your-project>
    ```

    This command:

    * Installs (or updates), trusts, and enables [`trace-grok`](https://github.com/braintrustdata/braintrust-grok-plugin). Trust applies to the plugin's executable hooks, not to your project folders.
    * Writes `~/.grok/braintrust.json`, which records whether tracing is enabled and which project receives traces.

    The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.

    For more information, see [`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable).
  </Step>

  <Step title="Load the tracing hooks">
    Start Grok and run `/reload-plugins` inside the session before sending your first prompt.

    <Note>
      Due to a bug in the Grok CLI, you must run `/reload-plugins` at the start of each session for traces to be reported, even after restarting. To automate this, alias Grok to run the command on launch with `alias grok="grok /reload-plugins"` until the [issue is resolved](https://github.com/xai-org/plugin-marketplace/issues/236).
    </Note>
  </Step>

  <Step title="Log a test trace">
    Ask Grok to do something simple. When the session finishes, open your Braintrust project and confirm that the trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page.
  </Step>
</Steps>

### What Braintrust traces

Grok traces in Braintrust include:

* Session spans with the session ID, local username, available workspace and permission settings, Grok and plugin versions, and Git repository metadata when available.
* Turn spans with prompts, visible assistant responses, and available usage metrics.
* Reconstructed model call spans with available responses and reasoning. The first model call can also include the recovered system prompt and first user message.
* Tool spans with available inputs, outputs, timing, outcomes, and errors.

Every span records its origin as `braintrust.plugin.grok`.

Grok does not expose complete provider requests or native boundaries for every model call. Usage belongs to the whole turn, not individual model calls. The turn's usage is also attached to the final reconstructed model span with `usage_scope: "turn"`. Raw `cost_usd_ticks` values are not converted to estimated dollar costs.

### Common workflows

<AccordionGroup>
  <Accordion title="Change saved tracing settings">
    To change the saved destination, profile, or organization, rerun [`bt trace enable grok`](/docs/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](/docs/reference/cli/switch) does not change the saved tracing configuration.

    To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.
  </Accordion>

  <Accordion title="Resume a Grok session">
    When you resume a Grok session, new turns are added to its existing Braintrust trace. Run `/reload-plugins` in the resumed session before continuing.
  </Accordion>

  <Accordion title="Stop tracing Grok sessions">
    Use [`bt trace disable grok`](/docs/reference/cli/trace#bt-trace-disable) to uninstall the published tracing plugin and remove its tracing configuration. Saved `bt` profiles and credentials are preserved. Restart Grok afterward.

    The command leaves local or custom plugins with the same name installed.
  </Accordion>
</AccordionGroup>

### Update the tracing plugin

To update the plugin, follow these steps:

<Steps>
  <Step title="Update bt">
    Follow the [CLI migration guide](/docs/reference/cli/migrate) to update `bt` to the latest version and complete the applicable migrations.
  </Step>

  <Step title="Update the tracing plugin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace update grok
    ```

    [`bt trace update`](/docs/reference/cli/trace#bt-trace-update) updates the installed plugin without changing your saved tracing configuration. The command requires the published Braintrust plugin and does not replace local or custom installations.
  </Step>

  <Step title="Restart and verify Grok">
    Restart Grok and run `/reload-plugins`. Run a short session and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.
  </Step>
</Steps>

### Troubleshooting tracing

First, run `bt trace doctor grok`. Then, review the following:

<AccordionGroup>
  <Accordion title="The tracing plugin is missing or disabled">
    Run `grok plugin list --json` and confirm that `trace-grok` is installed and enabled. If it is missing or broken, run:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable grok --project <your-project>
    ```

    Run `/reload-plugins` in Grok afterward. The doctor report checks tracing settings and authentication, not whether Grok loaded the hooks.
  </Accordion>

  <Accordion title="Traces do not appear after setup">
    Run `/reload-plugins` in the active Grok session. Confirm that `bt` is available in the environment that launches Grok. If necessary, set `BT_BIN` to the executable's path.

    Run `bt trace doctor grok` and confirm that tracing is enabled and routed to the intended project.

    If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](/docs/reference/cli/trace#project-log-permissions).

    For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](/docs/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](/docs/reference/cli/migrate#troubleshooting).

    Tracing failures do not interrupt the Grok session.
  </Accordion>

  <Accordion title="Grok uses an unexpected configuration directory">
    The tracing file is `~/.grok/braintrust.json`. An explicit `BT_DAEMON_CONFIG` override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Grok.
  </Accordion>

  <Accordion title="Traces use unexpected settings">
    For normal sessions, the integration does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.

    For environment variables accepted by the `bt` commands themselves, see [`bt trace`](/docs/reference/cli/trace).
  </Accordion>
</AccordionGroup>

## Connect to Braintrust MCP

The Braintrust MCP server lets Grok query and update Braintrust data. MCP is configured independently from the tracing plugin.

### Set up the MCP server

<Steps>
  <Step title="Install Grok">
    If you haven't already, install the [Grok CLI](https://grok.com/build).
  </Step>

  <Step title="Add the Braintrust MCP server">
    From the terminal, configure Grok's connection to the Braintrust MCP server:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    grok mcp add --transport http braintrust https://api.braintrust.dev/mcp
    ```

    Grok stores this configuration in `~/.grok/config.toml`. To configure only the current project, add `--scope project` to write `.grok/config.toml` instead. See [Grok's MCP documentation](https://docs.x.ai/build/features/mcp-servers) for scope and configuration details.

    See [Authentication](/docs/integrations/developer-tools/mcp#authentication) for API-key setup and [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
  </Step>

  <Step title="Authenticate">
    In Grok, enter `/mcps`, select the Braintrust MCP server, and press `i` to start OAuth authentication. Complete the sign-in in your browser.

    MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
  </Step>

  <Step title="Verify the connection">
    Run `grok mcp doctor braintrust` to check the connection. In Grok, ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
  </Step>
</Steps>

### Use MCP tools

Once connected, Grok can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](/docs/integrations/developer-tools/mcp#what-the-mcp-can-do) for more workflows and example prompts.

### Troubleshooting MCP

<AccordionGroup>
  <Accordion title="Braintrust MCP tools do not appear">
    Run `grok mcp list` to confirm that the Braintrust server is registered. Use `/mcps` in Grok to enable the server or refresh it after configuration changes.

    If Grok loads an unexpected server, run `grok inspect` to see its configuration source. Grok can also load MCP definitions from Claude Code and Cursor configurations. See [Grok's MCP documentation](https://docs.x.ai/build/features/mcp-servers) for configuration precedence.
  </Accordion>

  <Accordion title="MCP authentication or connection fails">
    Run `grok mcp doctor braintrust` to diagnose the connection. To authenticate again, enter `/mcps` in Grok, select the Braintrust MCP server, and press `i` to start the OAuth flow.

    For authentication methods, regional and self-hosted endpoints, and network requirements, see the [Braintrust MCP guide](/docs/integrations/developer-tools/mcp#connect-your-client).
  </Accordion>
</AccordionGroup>

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](/docs/evaluate/run-evaluations).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](/docs/integrations/developer-tools/mcp#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).