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

# Connect external MCP servers

> Connect Loop to external tools and data to investigate failures with business context, find related issues, and turn findings into follow-up work.

export const feature_0 = "External MCP connections in Loop"

export const verb_0 = "are"

Connect external MCP (Model Context Protocol) servers so Loop can investigate your traces with context from the tools your team already uses. Depending on the server's tools, Loop can:

* 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.

Connections belong to a project and share the account's or key's permissions, including access to write tools the server exposes.

<Warning>
  {feature_0} {verb_0} in [public preview](/docs/feature-lifecycle) and can change before reaching general availability.
</Warning>

<Note>
  This page covers giving Loop access to external tools, such as Linear, through their MCP servers. For the reverse, giving an AI coding agent such as Claude Code or Cursor access to your Braintrust data, see [Braintrust MCP server](/docs/integrations/developer-tools/mcp).
</Note>

## Connect a server

You need a remote MCP server that supports Streamable HTTP, its URL, and an OAuth account or bearer API key.

<Steps>
  <Step title="Add the server">
    Ask Loop to connect an MCP server to open project settings in the workspace, or go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="plug" /> MCP**](https://www.braintrust.dev/app/~/configuration/mcp), add a new server, and enter its **Name**, **URL**, and an optional **Description**.
  </Step>

  <Step title="Authenticate">
    <Warning>
      Project members can use these connections with the shared credentials' access. Scheduled Loop runs, including Patterns automations, can invoke all tools those credentials allow without interactive approval. Use an account or key limited to the access you intend to share with the project.
    </Warning>

    In **Credentials**, choose an authentication method:

    * **OAuth**: Click **Connect with OAuth** and complete the provider's sign-in flow. Connecting saves both the server and the project connection.
    * **API key**: Enter the server's bearer token in **API key**, then click **Save**. Do not include the `Bearer` prefix.

          <Warning>
            Don't paste API keys into Loop messages or save them in sandbox files, where they become part of the conversation or sandbox contents instead of the project's encrypted credential store.
          </Warning>
  </Step>

  <Step title="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:

    ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Investigate the most common tool-call failures in this project's traces from the past week. Search Linear for related issues, and draft a bug report for any recurring failure that isn't already tracked. Include example traces.
    ```
  </Step>
</Steps>

<h2 id="manage-shared-access">
  Access and security
</h2>

Project MCP credentials are encrypted and stored on your data plane using the same mechanism as function environment variables. Loop's runtime decrypts credentials to authenticate requests to the project's configured MCP servers. These calls run outside the sandbox and use the shared account's or API key's permissions, rather than each project member's individual account on the external service.

## Manage connections

Open a server in project MCP settings to manage its credentials.

<AccordionGroup>
  <Accordion title="Renew or replace credentials">
    * **OAuth:** Access tokens refresh automatically while the provider's refresh token remains valid. Click **Reconnect** if authorization expires or is revoked, or if you change the server URL.
    * **API key:** Click **Replace**, enter the new key, then click **Save**.
    * **Authentication method:** Connect with OAuth or save an API key in the other method's tab.

    <Warning>
      Replacing credentials or switching authentication methods changes the external account or key used by everyone in the project, including scheduled automations.
    </Warning>
  </Accordion>

  <Accordion title="Remove credentials">
    Click **Remove**, then **Save**. To cancel the removal before saving, click **Undo**.

    <Warning>
      Removing credentials removes the project's stored authentication for that server. The change takes effect on the next Loop turn, including in scheduled automations.
    </Warning>
  </Accordion>

  <Accordion title="Troubleshoot a connection">
    Click **Test connection** to check access and tool discovery. If authentication fails, renew or replace the credentials as described above. If the test succeeds but Loop can't find the tools, send another message to load the saved connection.

    Opening the settings panel or saving a server without credentials does not authenticate it.
  </Accordion>
</AccordionGroup>

## Limitations

* **Braintrust-hosted deployments only.** This integration is not yet available on self-hosted deployments.
* **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](/docs/loop/automations) and [Patterns](/docs/observe/patterns) can invoke all tools the shared credentials allow without interactive approval.

## Next steps

* [What Loop can do](/docs/loop/capabilities) for tasks you can combine with external context.
* [Run Loop on a schedule](/docs/loop/automations) to use connections in recurring work.
* [Add MCP servers to prompts](/docs/evaluate/prompts/create#add-mcp-servers) to use external tools in playgrounds.