Skip to main content
Grok 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 uses bt to trace your Grok sessions to Braintrust.

​
Set up tracing

If trace-grok is already installed, follow Update the tracing plugin.
1

Install Grok

If you haven’t already, install the Grok CLI.
2

Install and authenticate bt

Follow the bt CLI quickstart to install bt v0.19.3 or later, authenticate, and set your active context.
3

Enable tracing

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:
This command:
  • Installs (or updates), trusts, and enables trace-grok. 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.
4

Load the tracing hooks

Start Grok and run /reload-plugins inside the session before sending your first prompt.
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.
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 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

To change the saved destination, profile, or organization, rerun bt trace enable grok with the corresponding options. Running bt 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.
When you resume a Grok session, new turns are added to its existing Braintrust trace. Run /reload-plugins in the resumed session before continuing.
Use bt trace disable grok 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 to update bt to the latest version and complete the applicable migrations.
2

Update the tracing plugin

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 page in the intended Braintrust project.

​
Troubleshooting tracing

First, run bt trace doctor grok. Then, review the following:
Run grok plugin list --json and confirm that trace-grok is installed and enabled. If it is missing or broken, run:
Run /reload-plugins in Grok afterward. The doctor report checks tracing settings and authentication, not whether Grok loaded the hooks.
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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the Grok session.
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.
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.

​
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

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.
Your bt login doesn’t authenticate the MCP server.
2

Choose your endpoint

Use the endpoint for your organization’s data plane region:Other connection details:
  • Self-hosted: Copy the MCP URL from Settings > 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 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.
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 for more workflows and example prompts.

​
Next steps