> ## Documentation Index > Fetch the complete documentation index at: https://www.braintrust.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Braintrust MCP > Connect Claude Code, Cowork, Cursor, Codex, and other MCP clients to Braintrust. Query logs, author scorers, configure Topics, and run evaluations The Braintrust MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that lets AI tools read and write your Braintrust data directly. Query production logs, author prompts and scorers, configure monitoring, and run evals from Claude Code, Cowork, Cursor, Codex, VS Code, and any other MCP-compatible client. > **MCP or CLI?** > > Which one you want depends on what your tool can access and where the work needs to run. > > * **[MCP](https://www.braintrust.dev/docs/integrations/developer-tools/mcp.md)**: Best when your AI tool can connect to Braintrust but has no authenticated shell, which is common in chat applications. It also fits when you want an assistant to reason over your Braintrust data and take several connected actions in one conversation, without installing and maintaining a CLI in its execution environment. > * **[`bt` CLI](https://www.braintrust.dev/docs/reference/cli/quickstart)**: Best for repeatable work in scripts, CI, local files, and shell pipelines, where you want deterministic commands instead of an assistant's judgment. Coding agents with shell access can call those commands too. > > If your tool supports both, either one works. Pick whichever is more reliable for the task at hand. > [!NOTE] > > This page covers MCP clients, such as Claude Code and Cursor, connecting to the Braintrust MCP server. It does not cover Braintrust connecting to your MCP server or a third-party MCP server. To give prompts access to an external MCP server, see [Add external MCP servers](https://www.braintrust.dev/docs/evaluate/prompts/create.md#add-mcp-servers). To let Loop use one, see [Connect external MCP servers](https://www.braintrust.dev/docs/loop/mcp.md). ## Connect your client Braintrust hosts the MCP server, so there is nothing to install or deploy. **1. Choose authentication** **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. **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 ``` **2. Choose your endpoint** Use the endpoint for your organization's [data plane region](https://www.braintrust.dev/docs/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. Configure your client** Follow your client's documentation to add a remote MCP server using the endpoint and authentication method above. The client documentation covers configuration, authentication controls, and any plan or administrator requirements. > [!NOTE] > > Each client names the HTTP transport setting differently. For example, in Claude Code, add `--transport http` to `claude mcp add`. In Gemini CLI's `settings.json`, set the server address with `httpUrl`, not `url`.
Client Setup
![Amp logo](https://img.logo.dev/ampcode.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Amp [Amp guide](https://ampcode.com/docs/customize/mcp)
![Claude Code logo](https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Claude Code [Claude Code guide](https://code.claude.com/docs/en/mcp) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/claude-code.md#connect-to-braintrust-mcp)If you installed the retired Braintrust MCP plugin, [remove it](https://www.braintrust.dev/docs/integrations/developer-tools/claude-code.md#connect-to-braintrust-mcp) before you add the server.
![Claude logo](https://img.logo.dev/claude.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Claude (chat and Cowork) [Claude guide](https://claude.com/docs/connectors/custom/add-unlisted) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/claude-cowork.md#connect-to-braintrust-mcp)
![Codex logo](https://img.logo.dev/openai.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Codex [Codex guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli#cli-connect-codex-to-an-mcp-server) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/codex.md#connect-to-braintrust-mcp)If you installed the retired Braintrust MCP plugin, [remove it](https://www.braintrust.dev/docs/integrations/developer-tools/codex.md#connect-to-braintrust-mcp) before you add the server.
![Cursor logo](https://img.logo.dev/cursor.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Cursor [Cursor guide](https://cursor.com/docs/mcp#installing-mcp-servers) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/cursor.md#connect-to-braintrust-mcp)
![Devin Desktop logo](https://img.logo.dev/devin.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Devin Desktop [Devin guide](https://docs.devin.ai/cli/extensibility/mcp/configuration#adding-mcp-servers) · [Cascade guide](https://docs.devin.ai/desktop/cascade/mcp) (legacy agent) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/devin-desktop.md)
![Gemini CLI logo](https://img.logo.dev/gemini.google.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Gemini CLI [Gemini CLI guide](https://geminicli.com/docs/tools/mcp-server/#how-to-set-up-your-mcp-server)
![Google Antigravity logo](https://img.logo.dev/antigravity.google?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Google Antigravity [Antigravity guide](https://antigravity.google/docs/mcp#getting-started-by-surface) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/antigravity.md#connect-to-braintrust-mcp)
![Grok logo](https://img.logo.dev/grok.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Grok [Grok guide](https://docs.x.ai/build/features/mcp-servers#adding-a-server) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/grok.md#connect-to-braintrust-mcp)
![OpenCode logo](https://img.logo.dev/opencode.ai?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)OpenCode [OpenCode guide](https://opencode.ai/docs/mcp-servers/#enable) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/opencode.md#connect-to-braintrust-mcp)
![pi logo](https://img.logo.dev/pi.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)pi [pi guide](https://pi.dev/docs/latest/mcp#configure-servers) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/pi.md#connect-to-braintrust-mcp)
![VS Code logo](https://img.logo.dev/vscode.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)VS Code [VS Code guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) · [VS Code configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) · [Braintrust guide](https://www.braintrust.dev/docs/integrations/developer-tools/vscode.md)
![Warp logo](https://img.logo.dev/warp.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Warp [Warp guide](https://docs.warp.dev/agents/capabilities/mcp/)
![Zed logo](https://img.logo.dev/zed.dev?token=pk_BdcHD9e5SCW3j1rnJkNyMQ)Zed [Zed guide](https://zed.dev/docs/ai/mcp#installing-mcp-servers)
For other clients, check that the client supports remote MCP servers over streamable HTTP with OAuth or bearer-token authentication. **4. Verify the connection** Ask your assistant: ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} Use the Braintrust MCP server to list my recent projects. ``` The assistant calls a Braintrust tool and returns projects you can access. If the call fails, see [Troubleshooting](#troubleshooting). ## What the MCP can do Your assistant works with the data and objects in your Braintrust organization, and it chains several tools in one turn. Suppose a support chatbot starts making claims about your product that aren't true. In a single conversation, your assistant can: 1. [Query recent logs](#explore-your-data) to find examples of the behavior. 2. [Write an evaluator](#author-prompts-and-evaluators) that detects the unsupported claims, and test it against those traces before saving it. 3. [Add the failing cases](#run-evals-and-edit-datasets) to a regression dataset, with the corrected responses as the expected output. 4. [Run an eval](#run-evals-and-edit-datasets) comparing the current prompt against a proposed fix. Each step produces a real Braintrust object, and your assistant [returns a permalink](#find-and-share-objects) so you can inspect or share it. Each capability below lists the tools behind it, and [Tools](#tools) describes every tool in one place. > [!WARNING] > > Write tools act on your Braintrust organization using the permissions of your authenticated account. Configure your MCP client to require confirmation before it runs a write tool. ### Install the Braintrust SDK Before you can query anything, your application has to send traces to Braintrust. Your assistant handles that setup: it detects your programming language and frameworks, installs the appropriate SDK, and configures auto-instrumentation. Once complete, it runs your app, verifies traces are being logged, and provides a permalink to view them in Braintrust. Example prompts: > **Set up tracing from scratch** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Install the Braintrust SDK and add tracing to my app. > ``` > **Instrument an existing integration** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > My app calls the OpenAI SDK. Add Braintrust tracing so those calls show up as spans. > ``` > **Confirm traces are landing** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Run my app and confirm traces are reaching Braintrust. Send me a permalink to one. > ``` See [Trace LLM calls](https://www.braintrust.dev/docs/instrument/trace-llm-calls.md) for what auto-instrumentation covers. **Resource**: [`docs://sdk-install`](#resources). ### Explore your data Your assistant can answer questions about what your application actually did. It queries logs, experiments, and datasets with SQL, discovers the fields and value distributions in a data source before writing a query, and pulls aggregated metrics for an experiment with or without a baseline to compare against. Because it reads the same data the UI shows, you can investigate a production issue without switching to a browser. When a query returns more than 1 MB, `sql_query` returns a signed URL to the full result instead of inline rows, so your assistant can work with production-scale results without filling its context window. See [Tools](#tools) for how to control that behavior. Example prompts: > **Find recent errors** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Show me the last 10 logged requests with errors, and include the error message and the model used. > ``` > **See what fields your data has** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What fields are available in my production logs, and which ones are populated most often? > ``` > **Break down cost** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What did my chatbot experiments cost last week, broken down by model? > ``` > **Compare an experiment to its baseline** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Summarize my latest experiment and compare it to the baseline. Call out any score that regressed. > ``` See [SQL](https://www.braintrust.dev/docs/reference/sql.md) for query syntax, and [View logs](https://www.braintrust.dev/docs/observe/view-logs.md) for the equivalent in the UI. **Tools**: `sql_query`, `infer_schema`, `summarize_experiment`. ### Find and share objects Most Braintrust tools take an object ID, so your assistant finds the right project, experiment, or dataset by name and translates between names and IDs on its own. It usually does this as a step inside a larger request rather than as something you ask for. When you want to hand a result to someone else, it produces a direct link to the object. It can also reverse the lookup, finding a person's traces from their name or email. Example prompts: > **List recent work in a project** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What experiments have I run recently in the 'chatbot' project? > ``` > **Identify a Braintrust URL** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What does this Braintrust URL point to, and what does the object contain? > ``` > **Get a link to share** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Give me a shareable link to those experiment results so I can post it for my team. > ``` > **Attribute traces to a teammate** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Who logged the traces in this project this week, and which API keys produced the rest? > ``` **Tools**: `list_recent_objects`, `resolve_object`, `generate_permalink`, `lookup_users`, `lookup_api_keys`. ### Analyze traces A long agent trace is hard to follow span by span. Your assistant partitions a single trace into chronological work sections and annotates each one, so you can see what a run actually did and where it spent its time. Example prompts: > **Break down a trace** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Break down what this trace actually did, step by step, and annotate each step. > ``` > **Find the slow steps** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Which steps in this trace took the longest? > ``` **Tools**: `get_trace_work_items`, `update_trace_work_report`. ### Manage patterns Patterns record the recurring behaviors your traces reveal, so an investigation doesn't have to start over each time. Your assistant checks what has already been reported, catching duplicates that use different wording, adds a new pattern with supporting evidence, and attaches further evidence as it turns up. Example prompts: > **Investigate a suspected problem** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > I think we might be overspending on web searches. Dig into that, and report a pattern if you find one. > ``` > **Review active patterns** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What patterns are active that I can solve right now? > ``` > **Manage duplicate patterns** > > You can also manage [duplicate patterns](https://www.braintrust.dev/docs/observe/patterns/review.md#duplicate-patterns), which requires data plane v2.18.0 or later on self-hosted deployments: > > * **Find duplicates:** `search_patterns` accepts `status: "duplicate"` and returns `duplicate_of`, the canonical pattern's ID. > > * **Close a duplicate:** Call `update_pattern` with `status: "duplicate"` and `duplicate_of` set to an existing canonical pattern in the same project. The target cannot be the pattern itself or another duplicate. > > * **Undo duplicate closure:** Call `update_pattern` with `duplicate_of: null` and `status: "active"` or `status: "inactive"`. Both fields are required to undo the closure. > > > [!WARNING] > > > > Closing a pattern as a duplicate removes it from the **Open** list and hides its **Reopen** button. Its history is preserved, and it links to the canonical pattern. **Tools**: `search_patterns`, `new_pattern`, `update_pattern`. ### Configure Topics [Topics](https://www.braintrust.dev/docs/observe/topics.md) preprocesses traces into text, extracts facets from that text, and clusters the results to show what your users actually do. Your assistant builds that pipeline for you: it writes a preprocessor that matches your trace shape, tests it against real traces before saving, defines the facets to extract, and enables the automation that keeps it running. It can also rewind an automation over historical traffic. > [!NOTE] > > Rewinding a Topics automation processes historical traces and draws from your monthly [model credits](https://www.braintrust.dev/docs/plans-and-limits.md#model-credits). Example prompts: > **Set up Topics from scratch** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Set up Topics for my project. Validate the preprocessor and facets on real traces before you enable anything. > ``` > **Write a preprocessor for an unusual trace shape** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > My traces don't store conversation text on LLM spans. Write a preprocessor that works with my trace shape, and test it on a few traces. > ``` > **Process historical traces** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Rewind my Topics automation so it covers the last 30 days. > ``` **Tools**: `create_preprocessor`, `test_preprocessor_on_trace`, `create_facet`, `test_facet_on_trace`, `enable_topics_automation`, `set_topics_automation`, `rewind_topics_automation`. ### Build dashboards Dashboards collect the charts you check regularly. Your assistant previews a chart against real project logs so you can see it before anything is saved, then puts it into a new or existing dashboard. It can also read back what a dashboard already contains and edit charts in place, one at a time or in bulk. Example prompts: > **Preview a chart before saving it** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Chart daily cost for this project over the last two weeks. Show it to me before you save anything. > ``` > **Create a cost dashboard** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Create a dashboard for daily cost analysis, with charts for total cost, cost per trace, and cost by model. > ``` > **Add a chart to an existing view** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Add a p95 latency chart to my error monitoring dashboard. > ``` See [Dashboards](https://www.braintrust.dev/docs/observe/dashboards.md) for the equivalent in the UI. **Tools**: `generate_monitor_chart`, `list_monitoring_views`, `get_monitoring_view`, `create_monitoring_view`, `update_monitoring_view`. ### Manage automations and alerts Automations watch your data so you don't have to. Your assistant inspects what a project already runs, including online scoring rules, exports, and retention policies, then creates what's missing: an alert on individual matching logs, an alert on an aggregate threshold over a recent window, an alert on environment updates, or a Loop job that analyzes recent traffic on a schedule. It can also pause and resume any of them. Example prompts: > **Audit what's configured** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What automations are configured in this project, and which ones are paused? > ``` > **Alert on an error rate** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Alert me when the error rate goes above 2% over the last hour. > ``` > **Schedule recurring analysis** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Every Monday morning, analyze last week's traces and summarize the top failure modes. > ``` > **Pause an automation** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Pause the online scoring rule you just created. > ``` See [Alerts](https://www.braintrust.dev/docs/observe/alerts.md) for delivery channels and tuning, and [Loop automations](https://www.braintrust.dev/docs/loop/automations.md) for scheduled analysis. **Tools**: `list_automations`, `set_automation_status`, `create_log_alert`, `create_environment_update_alert`, `create_threshold_alert`, `create_scheduled_loop_job`, `list_slack_channels`. ### Author prompts and evaluators Prompts and evaluators are versioned objects that your application, experiments, and online scoring all share. Your assistant drafts one from what it found in your logs, runs it against real traces to see how it behaves before anything is saved, and saves it as a new version when you're satisfied. It can then attach an evaluator to an online scoring rule so it scores production logs continuously. Example prompts: > **Write a scorer for errors you found** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Write a scorer that detects the errors in these logs, then test it on a few traces before saving it. > ``` > **Create an LLM-as-a-judge** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Create an LLM-as-a-judge scorer for helpfulness and test it on ten recent traces. > ``` > **Apply a scorer to production logs** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Set up online scoring with the scorer you just created. Leave it paused so I can review the configuration first. > ``` > **Save a prompt as a new version** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Save this prompt to my project as a new version of the summarizer prompt. > ``` See [Create prompts](https://www.braintrust.dev/docs/evaluate/prompts/create.md) and [Write scorers](https://www.braintrust.dev/docs/evaluate/write-scorers.md) for details. **Tools**: `create_prompt`, `create_evaluator`, `test_evaluator`, `update_online_scoring_rule`. ### Run evals and edit datasets Evals, and the datasets that feed them, are how you measure whether a change helps. Your assistant curates dataset rows from the failures it finds in your logs, then runs an experiment against them using a saved or inline task and whichever scorers you want. A prior experiment can supply the input data, in which case its outputs become the expected values. Use `add_to_dataset` to copy project log rows into a dataset in the same project without loading their full contents into the assistant's context. Find rows with `sql_query` against `project_logs`, then pass their `id` values in `log_row_ids`, along with `project_id` and either `dataset_id` or `dataset_name`. Use row IDs, not `span_id` or `root_span_id` values. Set `create_if_missing` to create a new named dataset. * **Copied fields.** Each row preserves `input`, `metadata`, and `tags`, with an `origin` link to the source log. Its `expected` comes from the log's `expected`, falling back to `output` when `expected` is missing or `null`. * **Missing rows.** If any requested row ID is missing, the tool writes no rows. * **Batch limits.** Both `add_to_dataset` and `edit_dataset_rows` accept up to 1,000 rows per call on hosted Braintrust. Self-hosted limits depend on deployment configuration, with a fallback of 100. Check the tool's description for its limit and split larger batches across calls. Use `save_dataset_custom_view` to give reviewers a [custom view](https://www.braintrust.dev/docs/annotate/custom-views.md) for labeling a dataset's rows. The tool saves the view's React code on the dataset and returns a link that opens the dataset with the view selected. To reuse a view as a template, call `list_dataset_custom_views` to read its code, adjust it, and save it on another dataset under a new slug. Set `if_exists` to `replace` to save a new version of an existing view. Example prompts: > **Build a regression dataset from failures** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Add the traces that failed the helpfulness scorer to my regression dataset, and set the expected output from the corrected responses. > ``` > **Compare two prompts** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Run an eval comparing these two prompts on my regression dataset, and tell me which one wins. > ``` > **Re-run last week's inputs** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Run my task against the inputs from last week's experiment and compare the results. > ``` See [Run evaluations](https://www.braintrust.dev/docs/evaluate/run-evaluations.md) and [Datasets](https://www.braintrust.dev/docs/annotate/datasets.md) for details. **Tools**: `run_eval`, `edit_dataset_rows`, `add_to_dataset`, `list_dataset_custom_views`, `save_dataset_custom_view`. > [!NOTE] > > `run_eval` creates an experiment and can execute your code or call AI providers, so it incurs compute and model usage. > [!WARNING] > > `edit_dataset_rows` can permanently delete dataset rows. Review the operations your assistant proposes before approving them. ### Manage project settings Project settings hold the defaults that other functions inherit. Your assistant reads a project's typed settings, including which preprocessor facets and other project functions fall back to, and changes that default when you want a new one to apply everywhere. Example prompts: > **Check the default preprocessor** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What preprocessor is my project using by default? > ``` > **Change the default** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Make the preprocessor you just created the project default. > ``` See [Projects](https://www.braintrust.dev/docs/admin/projects.md) for the equivalent in the UI. **Tools**: `get_project_settings`, `set_project_default_preprocessor`. ### Search docs and load skills Your assistant grounds its answers in Braintrust documentation rather than guesswork, so it can explain a concept or find the right guide without leaving your editor. For multi-step work, it loads a skill first: a workflow guide that tells it the order to do things in and what to validate at each stage. Example prompts: > **Ask a product question** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > How do I create a custom scorer in Braintrust? > ``` > **Clarify a concept** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > What's the difference between experiments and project logs? > ``` > **Follow a guided workflow** > > ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > Walk me through building an evaluator and applying it to my logs. > ``` See [Skills](#skills) for guidance on loading the right skill for a task. **Tools**: `search_docs`, `load_braintrust_skill`. ## Reference ### Tools Every tool the server exposes, in the order of the capabilities above. | Tool | Description | | - | - | | `sql_query` | Query experiments, datasets, and logs using SQL. Supports `SELECT`, `FROM`, `WHERE`, `GROUP BY`, `ORDER BY`, and `LIMIT`. | | `infer_schema` | Discover the available fields, data types, and most common values in experiments, datasets, or logs. The `limit` parameter defaults to 1,000 fields and cannot exceed 1,000. Use `fields` to narrow the result to specific top-level fields such as `metadata`. | | `summarize_experiment` | Get aggregated performance metrics for an experiment, optionally compared to a baseline. | | `list_recent_objects` | List recently created projects, experiments, datasets, prompts, or functions you have access to. | | `resolve_object` | Convert names to IDs or vice versa, and parse Braintrust URLs. For pattern, prompt, and scorer URLs, returns the containing project as `object_id` and the resource as `row_id`. App URLs retain their organization scope. Supply `org_name` to disambiguate name lookups. Ambiguous names return an error. | | `generate_permalink` | Generate a direct web link to a Braintrust object for sharing or bookmarking. For `project_logs`, `project_patterns`, `project_prompts`, and `project_functions`, supply `project_name` or the project UUID as `object_id`. Pass `root_span_id` as `row_id` for log entries, or the resource ID as `row_id` for patterns, prompts, and scorers. Supply `org_name` to scope a name lookup to one organization. | | `lookup_users` | Resolve Braintrust organization member IDs to names and emails. Pass a batch of user IDs, search by partial name or email, or list every member. | | `lookup_api_keys` | Resolve API key and service token IDs to their names. Pass a batch of IDs, match an exact name, or list every key visible to you. Results follow existing API key and service token visibility rules. | | `get_trace_work_items` | Return meaningful LLM, tool, function, and task spans in chronological order for [trace analysis](https://www.braintrust.dev/docs/loop/capabilities.md#analyze-traces). If no eligible child spans exist, return the root span when it contains analyzable input, output, or error. | | `update_trace_work_report` | Save those work sections and per-span annotations back to the trace. | | `search_patterns` | Search existing project patterns by text, semantic similarity, ID, status, or quality. Pass `similar_to` with one or more pattern IDs or unreported pattern drafts to catch duplicates that use different wording. For listings and text searches, continue while `has_more` is `true` by passing the returned `cursor` with the same project and filters. Semantic searches using `similar_to` do not support cursors. | | `new_pattern` | Record a pattern the agent has identified, with the evidence behind it. The agent decides what counts as a pattern, so asking for one doesn't guarantee a record is written. | | `update_pattern` | Update an existing project pattern, attach evidence to matching traces, or [manage duplicate patterns](#manage-duplicate-patterns). Can also set `severity` and `category`, set or clear `quality` (`useful` or `noise`), and append a `feedback` comment attributed to the calling user or automation. Category values are ignored when a person has corrected the pattern's categories. | | `create_preprocessor` | Create a versioned preprocessor from inline JavaScript that converts raw trace data into text. | | `test_preprocessor_on_trace` | Run a saved, global, or inline preprocessor on up to 50 span, trace, or group references without writing to the source trace. | | `create_facet` | Create a versioned facet that extracts a short summary from spans or traces. Facet extraction always uses Braintrust's built-in facet model. | | `test_facet_on_trace` | Run an inline facet definition on up to ten span, trace, or group references without writing the result to the source trace. | | `enable_topics_automation` | Enable Topics for a project. This seeds processing for new traffic and doesn't rewind historical data. | | `set_topics_automation` | Update an existing Topics automation's facets, scope, filters, sampling, or timing. | | `rewind_topics_automation` | Rewind an existing Topics automation to process historical data from a start time or a recent window. | | `generate_monitor_chart` | Preview a monitor chart for project logs without modifying a saved view. | | `list_monitoring_views` | List a project's saved monitor views and chart IDs. | | `get_monitoring_view` | Inspect a saved monitor view, including its options and ordered chart definitions. | | `create_monitoring_view` | Create a project-scoped monitor view, optionally containing charts you already previewed. | | `update_monitoring_view` | Insert, update, or remove charts in an existing monitor view, one edit at a time or several in bulk. | | `list_automations` | List a project's automations, including online scoring rules, alerts, exports, retention policies, and Topics automations. Filter by `automation_id`, `name`, or `kind`. Returns complete configurations, so you can inspect an automation before updating it. | | `set_automation_status` | Pause or activate an alert, scheduled job, or online scoring rule. | | `create_log_alert` | Create an alert for individual matching project logs. Use `config.interval_seconds` to throttle repeated notifications. | | `create_environment_update_alert` | Create an alert for environment updates. Use `config.environment_filter` to limit notifications to specific environment slugs. | | `create_threshold_alert` | Create an alert for an aggregate over a recent window of project data, evaluated on a schedule. Use it for averages, counts, rates, percentages, percentiles, and distributions. | | `create_scheduled_loop_job` | Create a Loop job that runs on an interval or cron schedule over a recent window of project data. | | `list_slack_channels` | List connected Slack workspaces and public channels for a project to resolve workspace and channel IDs before configuring Slack delivery. | | `create_prompt` | Create a versioned prompt from a completion-style prompt or chat messages. Set `if_exists` to `replace` to save a new version, or `ignore` to leave an existing prompt unchanged. | | `create_evaluator` | Create a versioned LLM or inline code evaluator. Set `output_type` to `score` for numeric scores or `classification` for categorical labels. | | `create_human_review_score` | Create a categorical, slider, or free-form human review score for a project. Fails if the name already exists. | | `add_to_human_review_queue` | Add up to 100 project log traces, experiment traces, or dataset rows from one source to [human review](https://www.braintrust.dev/docs/annotate/human-review/score-traces.md) by row ID. Targets project logs by default. Pass `experiment_id` or `dataset_id` to select an experiment or dataset in the same project. Optionally [assign reviewers](https://www.braintrust.dev/docs/annotate/human-review/manage-review-work.md#assign-rows-for-review) via `assignee_user_ids`. If any row is missing or already marked complete, the tool writes no rows. | | `test_evaluator` | Run a saved, global, or inline evaluator against span, trace, or group references without writing results to the source trace. | | `update_online_scoring_rule` | Save or rewind an online scoring rule that runs saved evaluator functions. New rules default to paused. | | `run_eval` | Run an experiment with a hosted dataset, inline rows, or a prior experiment as input data, any saved or inline task, and zero or more saved or inline scorers. When a prior experiment supplies the data, its outputs become expected values unless an expected value was already recorded. | | `edit_dataset_rows` | Insert, update, or delete dataset rows. Target a dataset by ID or name, and set `create_if_missing` to create a new named dataset. Inserts accept optional `tags` and `origin`. See [Batch limits](#run-evals-and-edit-datasets). | | `add_to_dataset` | Copy project log rows into a dataset by row ID, preserving their data and source links. See [Copy behavior and limits](#run-evals-and-edit-datasets). | | `list_dataset_custom_views` | List up to 100 of a project's saved dataset custom views, optionally for one dataset, with each view's code and a link that opens it. | | `save_dataset_custom_view` | Save a [custom view](https://www.braintrust.dev/docs/annotate/custom-views.md) for labeling a dataset's rows and return a link that opens the dataset with the view selected. Set `if_exists` to `replace` to save a new version of an existing view, or `ignore` to leave an existing view unchanged. | | `get_project_settings` | Return a project's typed settings, including the effective default preprocessor. An unset default resolves to the built-in `thread` preprocessor. | | `set_project_default_preprocessor` | Set or clear a project's default preprocessor. Pass `null` to restore the built-in default. This changes the default used by facets and other project functions that don't select a preprocessor explicitly. | | `search_docs` | Search Braintrust documentation to find relevant guides, API references, and code examples. | | `load_braintrust_skill` | Load a Braintrust workflow guide or developer skill. The tool's description and `skill_name` parameter list the skills available on your MCP server. | When a result exceeds 1 MB, `sql_query` uploads it to object storage and returns an overflow envelope instead of inline rows. The envelope includes an `overflow_url` (a signed URL to the JSON result), a `byte_length`, a `row_count` (when available), and an `instructions` field describing how to retrieve the full result. Set `return_url: true` to request a URL even when the result is below the threshold, which is useful when you want to download or save results without putting them in model context. Field values in the result are truncated to `preview_length` characters (1024 by default). Set `preview_length: -1` to include untruncated field values. ### Skills Skills are workflow guides your assistant loads with `load_braintrust_skill` and then follows. They cover Braintrust workflows such as Topics, evaluators, patterns, and automations, as well as working with the Braintrust SDK and your application code. Loading a skill is read-only and costs one tool call. The catalog combines Braintrust's built-in workflow guides with skills from the public [Braintrust skills repository](https://github.com/braintrustdata/braintrust-skills). You can also install the public skills directly into your assistant by following the repository's installation instructions. Ask your assistant to inspect `load_braintrust_skill` for the available names, then load the relevant skill. Each MCP server release includes a pinned revision of the public skills alongside its built-in guides, so its contents can differ from the latest version on GitHub. Follow each skill's prerequisites, such as access to your application repository or an authenticated Braintrust CLI. Loop uses a selected subset of this catalog. A skill available to an external MCP client is not necessarily available to Loop. Use the names advertised to the assistant making the request. ### Resources MCP resources provide contextual documentation that AI assistants can read to perform tasks more effectively. * **`docs://sdk-install`** - Step-by-step guidance for installing the Braintrust SDK into a project, setting up tracing, configuring auto-instrumentation, and running your first eval. * **`docs://sql`** - Documentation for the `sql_query` tool, including syntax, available fields, and examples. * **`docs://url-formats`** - Reference for Braintrust URL patterns, used by the `resolve_object` tool. * **`docs://experiments`** - Background on Braintrust experiments and how to create them. `docs://sdk-install` has companion resources for Python, TypeScript, Go, Java, Ruby, and C#. Your assistant reads the one matching your project automatically. ## Troubleshooting **Authentication fails:** For OAuth, sign in again using your client's authentication controls. If you are switching from API-key authentication, remove the manually configured `Authorization` header or bearer token first. For API-key authentication, verify that the key is valid and that your client sends the header as `Authorization: Bearer YOUR_BRAINTRUST_API_KEY`. **Invalid client errors:** Verify that the URL matches your organization's [MCP endpoint](#endpoints), including `/mcp` and no trailing slash. **Connection timeouts:** Check your internet connection. Corporate networks might need to allowlist `*.braintrust.dev` and, for self-hosted deployments, your [MCP endpoint](#endpoints). **MCP server not appearing:** Restart your client, then check the server configuration and connection status using your [client's MCP documentation](#client-setup). **Request body too large (HTTP 413):** The MCP server accepts request bodies up to 100 MiB. A tool call whose payload exceeds that limit returns an HTTP 413 error. Split the input into smaller requests, or fetch the data incrementally. **Server URL errors on a self-hosted deployment:** The MCP server derives its own address from the forwarding headers your ingress sets. If it reports that it could not determine the server URL, set the `MCP_SERVER_URL` environment variable on your data plane to your API URL. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.