> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.ti.trilogy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom MCP Servers

> Connect your own MCP servers to give experts access to custom APIs and internal services.

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](/experts/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](#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:

* **Python**: Use the [fastmcp](https://github.com/jlowin/fastmcp) library for a quick start, or the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
* **TypeScript**: Use the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).

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

| Problem                             | Cause                                                           | Fix                                                                                                   |
| ----------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Verify fails with connection error  | Server is down, URL is wrong, or not accessible from Braintrust | Check the URL, confirm the server is running, and ensure it's reachable over HTTPS                    |
| Verify succeeds but no tools appear | Server is running but not returning tool definitions            | Check your MCP server's tool registration code                                                        |
| Connection drops mid-session        | SSE connection timed out or server restarted                    | Consider switching to `streamable_http` if your server is ephemeral; otherwise check server stability |
| "Transport not supported" error     | Server doesn't support the selected transport                   | Try the other transport type, or check server documentation                                           |

## Next Steps

<CardGroup cols={2}>
  <Card title="Hives Reference" icon="cubes" href="/experts/hives-reference">
    See all built-in tool bundles available.
  </Card>

  <Card title="Configuring Agent Tools" icon="plug" href="/experts/configuring-agent-tools">
    Set up credentials and integrations.
  </Card>

  <Card title="Expert Fields Reference" icon="list-check" href="/experts/expert-fields-reference">
    Full reference for all expert configuration fields.
  </Card>
</CardGroup>