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

# External MCP servers

> Connect third-party MCP servers to Metal using OAuth discovery, Dynamic Client Registration, static OAuth clients, bearer API keys, or no authentication.

Metal can connect to remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers so people in your organization can use their tools in Metal.

<Note>
  This page covers connecting an external MCP server **to Metal**. To connect an
  AI tool such as Claude, ChatGPT, or Cursor to Metal's hosted MCP server, see
  the [Metal MCP server guide](/mcp/overview).
</Note>

## How setup works

MCP connections have two layers:

1. An admin adds the MCP server under **Settings → Integrations** and chooses how it authenticates.
2. Each user connects their own account under **Settings → Connections**.

The server configuration is shared across your organization. OAuth tokens and API keys belong to the individual user, are stored encrypted, and are used only for that user's connection.

## Choose an authentication method

| Method      | Use it when                                                                            | What each user does                           |
| ----------- | -------------------------------------------------------------------------------------- | --------------------------------------------- |
| **OAuth**   | The server has OAuth authorization and token endpoints.                                | Signs in to the provider and approves access. |
| **API Key** | The server accepts a personal API key as a bearer token in the `Authorization` header. | Pastes their own API key in Metal.            |
| **None**    | The server is intentionally available without credentials.                             | Clicks **Connect**.                           |

<Warning>
  Metal sends API keys in the `Authorization: Bearer <key>` header. The request
  header is not configurable. Providers that require a custom header such as
  `x-api-key` need to support OAuth or bearer-token authentication before they
  can be connected this way.
</Warning>

## Add a server

<Steps>
  <Step title="Open Integrations">
    As an admin, go to **Settings → Integrations** and click **Add MCP Connection**.
  </Step>

  <Step title="Describe the server">
    Enter a name, the remote MCP server URL, and an optional description. Use the complete remote MCP endpoint supplied by the provider.
  </Step>

  <Step title="Choose authentication">
    Select **OAuth**, **API Key**, or **None**. For OAuth, continue with the setup below.
  </Step>

  <Step title="Create the server">
    Click **Create Server**. The server becomes available to members of your organization under **Settings → Connections**.
  </Step>
</Steps>

## Configure OAuth

Metal uses the OAuth authorization code flow with PKCE. Each user authorizes their own provider account.

After entering the server URL, Metal attempts server discovery automatically. You can also click **Discover Server**. Discovery looks for the provider's authorization endpoint, token endpoint, and Dynamic Client Registration endpoint. It may also show tools, resources, and prompts when the server exposes them without authentication.

Discovery can succeed even when capabilities remain empty because many servers require authentication before returning their capabilities.

### Dynamic Client Registration

Use Dynamic Client Registration (DCR) when discovery reports **Dynamic Registration** as supported. Metal registers an OAuth client with the provider for your organization, so you do not need to enter a client ID or secret.

The provider's authorization server must accept Metal's registration request and callback URL. If it restricts permitted redirect URIs or OAuth clients, its administrator must allow Metal before users can connect.

### Statically configured OAuth client

Use a static OAuth client when the provider does not support DCR or requires clients to be registered in advance.

<Steps>
  <Step title="Register Metal with the provider">
    Create an OAuth application in the provider's administration console. Register this exact callback URL:

    ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
    https://api.metal.ai/v1/integrations/oauth/mcp/callback
    ```
  </Step>

  <Step title="Enter the OAuth endpoints">
    In Metal, enter the provider's **Authorization URL** and **Token URL**. **Discover Server** may fill these fields automatically.
  </Step>

  <Step title="Enter the client credentials">
    Enter the registered **Client ID**. Add the **Client Secret** when the provider created a confidential client. Leave it blank for a public client that uses PKCE without a secret.
  </Step>

  <Step title="Keep dynamic registration off">
    Leave **Dynamic Client Registration** disabled, then click **Create Server**.
  </Step>
</Steps>

The client ID and optional secret are shared OAuth configuration for your organization. The secret is stored encrypted and is not displayed again after you save the server.

Custom MCP server setup does not currently include a field for OAuth scopes. The provider must supply suitable default scopes. Contact Metal support if the provider requires Metal to request an explicit scope list.

<Tip>
  If a provider asks whether Metal must be added to an allowlist of permitted
  MCP or OAuth clients, the answer is usually yes when that provider does not
  support DCR. Register the static client and allow the callback URL above.
</Tip>

## Connect your account

After an admin adds the server:

1. Go to **Settings → Connections**.
2. Find the MCP server and click **Connect**.
3. Complete the provider sign-in, paste your API key, or confirm the unauthenticated connection, depending on the method the admin selected.

OAuth access and refresh tokens are stored per user. API keys are also stored per user. Disconnecting your connection does not remove the server for the rest of the organization.

## Permissions and ownership

Only admins can add, configure, or remove an external MCP server for the organization. After the server is added, organization members manage their own connection under **Settings → Connections**.

The server URL, authentication method, and static OAuth client configuration are organization-wide. OAuth tokens and API keys are per-user credentials. A user can disconnect or retry their own connection without changing the shared server configuration or another user's connection.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server discovery did not find OAuth settings">
    Confirm that the MCP server URL is correct and reachable by Metal. You can
    still enter the authorization URL, token URL, and static client credentials
    manually when the provider does not publish discovery metadata.
  </Accordion>

  <Accordion title="OAuth client not configured">
    The server does not advertise DCR and no static client ID is configured.
    Ask the provider administrator to register Metal, then add the client ID and
    optional client secret to the server configuration.
  </Accordion>

  <Accordion title="The provider rejected Metal's redirect URI">
    Add `https://api.metal.ai/v1/integrations/oauth/mcp/callback` to the OAuth
    application's allowed redirect URIs. The value must match exactly.
  </Accordion>

  <Accordion title="Dynamic client registration failed">
    The provider may have disabled registration, restricted client metadata, or
    require an allowlisted client. Use a statically configured OAuth client when
    the provider does not support open DCR.
  </Accordion>

  <Accordion title="An API key connection returns unauthorized">
    Confirm that the key belongs to the connecting user and is still active.
    The provider must accept it as `Authorization: Bearer <key>`. Custom API key
    headers are not currently supported.
  </Accordion>

  <Accordion title="A user needs to reconnect">
    Go to **Settings → Connections** and click **Retry** on the failed
    connection. OAuth connections may require a new provider sign-in when a
    token expires or cannot be refreshed. API key connections prompt for a
    replacement key.
  </Accordion>
</AccordionGroup>


## Related topics

- [Integrations overview](/help/integrations/overview.md)
- [Metal MCP server](/mcp/overview.md)
- [Other MCP clients](/mcp/clients.md)
- [MCP tools reference](/mcp/tools-reference.md)
- [Connect Cursor](/mcp/cursor.md)