Skip to main content
Metal can connect to remote Model Context Protocol (MCP) servers so people in your organization can use their tools in Metal.
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.

​
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

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.

​
Add a server

1

Open Integrations

As an admin, go to Settings → Integrations and click Add MCP Connection.
2

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

Choose authentication

Select OAuth, API Key, or None. For OAuth, continue with the setup below.
4

Create the server

Click Create Server. The server becomes available to members of your organization under Settings → Connections.

​
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.
1

Register Metal with the provider

Create an OAuth application in the provider’s administration console. Register this exact callback URL:
2

Enter the OAuth endpoints

In Metal, enter the provider’s Authorization URL and Token URL. Discover Server may fill these fields automatically.
3

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. Set OAuth Client Type to match: Confidential — secret in header (Basic) (the default), Confidential — secret in body (POST), or Public — no client secret.
4

Keep dynamic registration off

Leave Dynamic Client Registration disabled, then click Create Server.
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.

​
OAuth client type

Use the OAuth Client Type field to choose how Metal authenticates its OAuth client to the provider’s token endpoint. The field appears only for OAuth servers. API Key and None servers have no client type. For servers that use DCR, Metal requests the selected method as token_endpoint_auth_method when it registers the client. If the provider responds with a method Metal cannot use, Metal keeps the method it requested. For statically configured clients, Metal uses the stored method when it exchanges and refreshes tokens. A client saved before this field existed keeps body placement until you change the client type.
On a DCR server, changing the OAuth client type invalidates every existing connection for that server. Metal asks you to confirm the change before saving. After you confirm, everyone in the organization must reconnect. Statically configured clients keep their existing connections when you change the client type.

​
OAuth scopes

Use the OAuth Scopes field to declare which scopes Metal requests when a user connects. The field appears for every OAuth server, whether or not the provider supports DCR.
  • Enter one or more scopes separated by spaces, for example all-apis offline_access.
  • Include offline_access when the provider requires it to issue a refresh token. Without a refresh token, connections break as soon as the access token expires.
  • Leave the field blank only if the provider grants a working default scope set on its own. Some providers, including Databricks, reject an authorization request that carries no scope.
  • The value is always sent for OAuth servers. Clearing the field clears the stored scopes.
  • Individual scopes cannot contain whitespace. Metal joins the entries with a single space when it calls the authorization endpoint.
If you leave the field blank, Metal falls back to scopes advertised by the MCP server’s resource metadata (RFC 9728 scopes_supported) when the provider publishes them. Set the field explicitly whenever you know which scopes the provider expects.
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.

​
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. After you connect a server, you can also use its read-only tools from Claude and other AI clients through the Metal connector. See Connected MCP servers.

​
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

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.
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.
Add https://api.metal.ai/v1/integrations/oauth/mcp/callback to the OAuth application’s allowed redirect URIs. The value must match exactly.
Metal shows the provider’s registration error details, including the description when the provider returns one. The provider may have disabled registration, restricted client metadata, or require an allowlisted client. Some providers also reject the requested OAuth Client Type. Switch to the method the provider supports, or use a statically configured OAuth client when the provider does not support open DCR.
The provider rejected Metal’s token request after the user signed in. Metal shows the provider’s error code or description on the callback page, for example Token exchange failed (invalid_client). invalid_client usually means the OAuth Client Type does not match how the provider expects the client to authenticate, or the client secret is wrong. Open the server in Settings → Integrations, select the method the provider supports, and have the user retry the connection.
Metal surfaces the provider’s error and description on the callback page. invalid_scope means the authorization request asked for a scope the provider does not recognize, or asked for none at all when the provider requires an explicit list. access_denied means the provider or the user refused the request. Open the server in Settings → Integrations, adjust the OAuth Scopes field to match what the provider expects, and have the user retry the connection.
The provider issued an access token but no refresh token, so the connection fails once the access token expires. Add offline_access (or the provider’s equivalent refresh scope) to OAuth Scopes and reconnect.
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.
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.