- Match recurring failures to known issues in your issue tracker.
- Consult internal documentation to understand expected behavior.
- Create follow-up tasks with supporting traces, without leaving the investigation.
To give Claude Code, Cursor, or another AI coding agent access to Braintrust data, use the Braintrust MCP server.
Connect a server
You need a remote MCP server that supports Streamable HTTP, its URL, and an OAuth account or bearer API key.1
Add the server
Ask Loop to connect an MCP server to open project settings in the workspace, or go to Settings > MCP, add a new server, and enter its Name and URL.
2
Authenticate
In Credentials, choose an authentication method:
-
OAuth: Click Connect with OAuth, sign in, then click Save. Closing without saving discards the connection.
If your provider requires an approved redirect URL
Ask its administrator to approvehttps://www.braintrust.dev/redirects/mcp-clientbefore connecting. Providers that allow clients to register themselves need no setup: Braintrust registers the URL automatically. -
API key: Enter the server’s bearer token in API key, then click Save. Do not include the
Bearerprefix.
3
Test and use the connection
Open the saved server and click Test connection. A successful test reports how many tools the server exposes.Send your next message in the same Loop thread. Loop picks up saved connection changes on that message, so you don’t need to start a new thread.For example, if you connected a Linear MCP server, ask:
Access and security
Project MCP credentials are encrypted and stored on your data plane. Loop and prompts using project MCP servers can use these credentials to authenticate requests. Calls using saved credentials have the shared account’s or API key’s permissions, rather than each project member’s individual permissions on the external service. Loop’s MCP calls run outside the sandbox.Manage connections
Open a server in project MCP settings to manage its credentials.Renew or replace credentials
Renew or replace credentials
- OAuth: Access tokens refresh automatically while the provider’s refresh token remains valid. If authorization expires or is revoked, or if you change the server URL, click > Reconnect, complete the sign-in flow, then click Save.
- API key: Click Replace, enter the new key, then click Save.
- Authentication method: In the other method’s tab, connect with OAuth or enter an API key, then click Save.
Remove credentials
Remove credentials
For OAuth credentials, click > Remove. For an API key, click . Then click Save. To cancel the removal before saving, click Undo.
Troubleshoot a connection
Troubleshoot a connection
When Loop can’t reach a configured server, it explains why:
- Missing or rejected credentials: Reconnect with OAuth or replace the API key.
- Timeout or connection failure: Check that the server is reachable with Test connection.
- Unsupported protocol version: Contact Braintrust support. Reconnecting does not fix a protocol mismatch.
- Redirect URI error: For
redirect_uri_mismatchorinvalid redirect_uri, ask the provider’s administrator to approvehttps://www.braintrust.dev/redirects/mcp-client. - Test succeeds but tools are missing: Send another Loop message to load the saved connection.
Limitations
- Remote servers only. Connections require a remote MCP server that supports Streamable HTTP and authenticates with OAuth or a bearer API key.
- Shared credentials. Everyone using the project’s connection acts with the shared account’s or key’s permissions on the external service, rather than their own account’s permissions.
- External writes depend on the server. An MCP connection can expose tools that change external data. Braintrust’s Write tool permissions do not restrict these tools. Limit access through the external account or key.
- No interactive approval in scheduled runs. Loop automations and Patterns can invoke all tools the shared credentials allow without interactive approval.
- On BYOC, connections come from your data plane. Loop connects to MCP servers from the Loop runtime in your BYOC deployment, so the servers must be reachable from it. Deployments without the runtime can’t use external MCP servers. See BYOC Loop availability.
Next steps
- What Loop can do for tasks you can combine with external context.
- Run Loop on a schedule to use connections in recurring work.
- Add MCP servers to prompts to use external tools in playgrounds.