Skip to main content

Braintrust MCP

The Braintrust Model Context Protocol (MCP) server lets AI tools query your Braintrust data directly: experiments, datasets, prompts, playgrounds, and production logs. Connect through Cequence AI Gateway so agents can search documentation, run SQL against eval data, infer schemas, summarize experiments, and generate shareable permalinks.

Overview​

Braintrust MCP is a remote, vendor-hosted server. Braintrust operates the endpoint; you point Cequence AI Gateway at their URL.

  • Server URL (US): https://api.braintrust.dev/mcp
  • Server URL (EU): https://api-eu.braintrust.dev/mcp
  • Transport: HTTP (streamable HTTP)
  • Hosted by: Braintrust

Capabilities and behavior are defined by Braintrust and may change over time. For the canonical tool list and behavior, see Braintrust MCP.

CLI vs MCP

Braintrust recommends the bt CLI for repeatable, scriptable work (running evals, instrumenting code, syncing data). Use the MCP server for conversational, ad-hoc exploration from an AI client through the gateway.

Supported authentication types​

TypeSupportedNotes
OAuth 2YesRecommended for AI Gateway. Braintrust supports Dynamic Client Registration (DCR) with PKCE, so clients can complete authorization without a pre-registered OAuth client. Tokens inherit the signed-in user's project permissions and SSO policies.
API key (Bearer)YesPass a personal API key as Authorization: Bearer <key>. Useful for scripted clients; gateway catalog flows typically use OAuth instead.

What you can do with this MCP server​

The server exposes these tools (names match Braintrust's MCP implementation):

  • search_docs — Semantic search across Braintrust documentation (guides, API references, SDK examples). For SDK install/setup, prefer the docs://sdk-install resource.
  • resolve_object — Convert names to IDs (or vice versa) and parse Braintrust URLs.
  • list_recent_objects — Browse recent projects, experiments, datasets, prompts, or functions you can access.
  • infer_schema — Discover fields, types, and common values in experiments, datasets, or logs before writing queries.
  • sql_query — Query experiments, datasets, and logs with SQL (SELECT / WHERE / GROUP BY / ORDER BY / LIMIT). Large results may return an overflow_url instead of inline rows.
  • summarize_experiment — Aggregated performance metrics for an experiment, optionally compared to a baseline.
  • generate_permalink — Create a direct web link to a project, experiment, dataset, prompt, or log entry.

Braintrust also exposes MCP resources such as docs://sdk-install, docs://sql, docs://url-formats, and docs://experiments for contextual guidance.

Prerequisites​

Before adding Braintrust MCP in Cequence AI Gateway:

  • Access to Cequence AI Gateway at aigateway.cequence.ai
  • A Braintrust account with access to the organization and projects you want to query
  • Confirm your data plane region (US vs EU) under Braintrust Settings → Data plane, and use the matching MCP URL

Example workflows​

  • “List my recent experiments in the chatbot project and summarize the latest one.”
  • “Infer the schema for production project logs, then show errors from the last day.”
  • “Compare accuracy and cost between my GPT-4 and Claude experiments with SQL.”
  • “Search Braintrust docs for how to write a custom scorer.”
  • “Generate a permalink to share this experiment with the team.”

Connecting MCP server from Cequence AI Gateway​

  1. Log in to Cequence AI Gateway.
  2. Choose your tenant.
  3. Go to App catalogue.
  4. Filter by Remote MCP server.
  5. Search for Braintrust MCP and select it.
  6. Select Create MCP server.
  7. Confirm the remote URL (api.braintrust.dev for US, or api-eu.braintrust.dev for EU / your self-hosted API host).
  8. Choose OAuth when prompted (DCR is supported; you usually do not need a pre-registered OAuth client in Braintrust).
  9. Complete the setup, select tools, and deploy.

Use the generated MCP server URL in your client as described in the Client Configuration docs. For detailed UI steps and screenshots, see Create a third-party MCP Server.

Additional information​

  • Permissions: Tool results respect the authenticated user's Braintrust access. You only see projects and objects you can normally open in the UI.
  • Regions: US and EU data planes use different API hosts. Using the wrong region URL will fail authentication or return empty results for your org.
  • Self-hosted: Point the gateway at https://<your-api-url>/mcp. Braintrust documents setting MCP_SERVER_URL on the data plane for OAuth discovery.
  • Official documentation: Braintrust MCP, Data plane region.
Last updated on