Skip to main content
MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. Braintrust uses MCP under the hood for all tool integrations — built-in hives are MCP servers, and you can add your own.

​
When to Use MCP vs Built-In Hives

  • Use built-in hives first. They’re pre-configured, maintained, and handle auth automatically. See the Hives Reference for the full list.
  • Use custom MCP servers when you need to connect to an internal API, a service without a built-in hive, or a custom tool you’ve built.
A key difference in how credentials work: with hives, each user who hires the expert connects their own account — their Google, Notion, or Jira credentials are theirs alone, and no other user shares them. Custom MCP servers do not support this per-user credential model. The server is configured once at the expert level, meaning all users of that expert share the same connection. Keep this in mind when the service contains user-specific or sensitive data.

​
Adding an MCP Server

In the expert editor, navigate to the Config step:
  1. Name — A human-readable label for this server (e.g. “Company CRM”, “Internal Billing API”). This is for your reference only.
  2. URL — The HTTPS endpoint of the MCP server (e.g. https://mcp.yourcompany.com/sse).
  3. Transport — Choose between sse (default) and streamable_http. See Transport Types below.
  4. Verify — Always click Verify before saving. This checks connectivity and discovers available tools. If verification fails, the expert will not be able to use this server.
You can add multiple MCP servers to a single expert.

​
Transport Types

​
SSE (Server-Sent Events)

  • The original MCP transport and most widely supported.
  • Maintains a long-lived connection between the expert and the MCP server.
  • Best for: always-on servers, persistent infrastructure, most use cases.
  • Set the URL to the server’s /sse endpoint.

​
Streamable HTTP

  • A newer MCP transport that uses stateless HTTP requests.
  • Each tool call is an independent HTTP request — no persistent connection.
  • Best for: serverless deployments, ephemeral infrastructure, environments where long-lived connections are impractical.
  • Set the URL to the server’s base endpoint.
When in doubt, use sse. It’s the default and works with the vast majority of MCP servers.

​
Building Your Own MCP Server

If you need to expose a custom API or internal service to Braintrust experts, you can build your own MCP server: Your MCP server needs to:
  1. Implement the MCP protocol (tool discovery + tool execution).
  2. Be accessible over HTTPS from Braintrust’s infrastructure.
  3. Return well-structured tool descriptions so the expert knows how to use each tool.

​
Security Considerations

MCP servers receive full tool invocations including any user data the expert passes to them. Only connect MCP servers that you trust:
  • Third-party servers: Verify the provider’s security practices before connecting.

​
Troubleshooting

ProblemCauseFix
Verify fails with connection errorServer is down, URL is wrong, or not accessible from BraintrustCheck the URL, confirm the server is running, and ensure it’s reachable over HTTPS
Verify succeeds but no tools appearServer is running but not returning tool definitionsCheck your MCP server’s tool registration code
Connection drops mid-sessionSSE connection timed out or server restartedConsider switching to streamable_http if your server is ephemeral; otherwise check server stability
”Transport not supported” errorServer doesn’t support the selected transportTry the other transport type, or check server documentation

​
Next Steps

Hives Reference

See all built-in tool bundles available.

Configuring Agent Tools

Set up credentials and integrations.

Expert Fields Reference

Full reference for all expert configuration fields.