> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/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.

## Trace Grok sessions

The [`trace-grok` plugin](https://github.com/braintrustdata/braintrust-grok-plugin) uses `bt` to trace your Grok sessions to Braintrust.

### Set up tracing

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

**1. Install Grok**

If you haven't already, install the [Grok CLI](https://grok.com/build).

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt` v0.19.3 or later, authenticate, and set your active context.

**3. 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.

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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

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

**5. 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 [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page.

### 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`, along with versions in `context.span_origin`: the plugin version in `version`, the `bt` version in `bt.version`, and the Grok version in `grok.version`. These versions are captured when each span is created, and unknown versions are `null`. Each turn span and every span under it records the turn's span ID in `metadata.turn_span_id`.

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

> [accordion] Change saved tracing settings
>
> To change the saved destination, profile, or organization, rerun [`bt trace enable grok`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/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] 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] Stop tracing Grok sessions
>
> Use [`bt trace disable grok`](https://docs.braintrust.dev/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.

### Update the tracing plugin

To update the plugin, follow these steps:

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the tracing plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update grok
```

[`bt trace update`](https://docs.braintrust.dev/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.

**3. Restart and verify Grok**

Restart Grok and run `/reload-plugins`. Run a short session and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

### Troubleshooting tracing

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

> [accordion] 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] Traces do not appear after setup
>
> Run `/reload-plugins` in the active Grok session. Confirm that `bt` is on the `PATH` of the environment that launches Grok.
>
> 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](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the Grok session.

> [accordion] Grok uses an unexpected configuration directory
>
> The tracing file is `~/.grok/braintrust.json`. An explicit `BRAINTRUST_DAEMON_CONFIG` (`BT_DAEMON_CONFIG` in `bt` v0.25.0 and earlier) override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Grok.

> [accordion] 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`](https://docs.braintrust.dev/reference/cli/trace).

## Connect to Braintrust MCP

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

**1. Choose authentication**

> [tab] OAuth (recommended)
>
> Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
>
> * No Braintrust API key required
> * No OAuth client ID or client secret to configure
>
> The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at `/.well-known/oauth-authorization-server` on the same host as your MCP endpoint (see next step), so a client can register itself.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane). This is your Braintrust API URL with `/mcp` appended.
* **Transport:** If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can't connect.

**3. Add the server to Grok**

Follow the [Grok guide](https://docs.x.ai/build/features/mcp-servers#adding-a-server) to add the remote server.

**4. Verify the connection**

To verify the connection, ask Grok to list your recent Braintrust projects. If it can't connect, see [Braintrust MCP troubleshooting](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#troubleshooting).

**5. Start using Braintrust tools**

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](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.