Authenticate to MCP servers behind a tunnel

MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, contact your Anthropic account team.

An MCP tunnel carries Claude’s requests to an MCP server inside your network, but it does not authenticate to that server. Each tunneled server should still require OAuth, as the MCP authorization specification describes, so that a member signs in with their own account before Claude can call the server’s tools. This page is for the administrator adding a tunneled server as a custom connector, and explains what to configure when the OAuth authorization server is itself only reachable inside your network. If your authorization server is reachable from the public internet and its metadata advertises public URLs, you don’t need anything on this page. Add the connector as described in Set up an MCP tunnel and members sign in as they would for any other connector.

How OAuth works through a tunnel

Two different parties make requests during an OAuth sign-in, and they reach your authorization server by different paths.

The member’s browser is redirected to the authorization endpoint to sign in and approve access. This request comes from the member’s device, so the authorization endpoint must be a URL their browser can load, either on the public internet or on your corporate network. It can’t be a tunnel.anthropic.com hostname, because tunnel hostnames accept connections only from Claude.
Claude’s servers fetch the authorization server’s metadata, register an OAuth client if the server supports dynamic registration, and exchange the authorization code for tokens at the token endpoint. These requests come from Anthropic’s network, so the endpoints must be reachable from there, either publicly or through the tunnel.

By default Claude discovers all of these URLs from the metadata your MCP server and authorization server publish. When the authorization server sits inside your network, that metadata usually advertises internal hostnames. Claude then can’t reach the token endpoint, or the member’s browser is sent to an address it can’t load, and sign-in fails. You fix this by routing Claude’s server-to-server calls through the tunnel and telling Claude explicitly which URL to use for each endpoint.

Route the authorization server through the tunnel

Add a route for the authorization server to the proxy configuration, next to the routes for your MCP servers, and apply it as described in Add more servers later.

routes:
  docs: http://docs-mcp.example.corp:8080
  auth: https://sso.example.corp:8443

With a tunnel domain of abc123.tunnel.anthropic.com, Claude can now reach the authorization server at https://auth.abc123.tunnel.anthropic.com. For an https:// upstream like this one, also set upstream.tls.ca_file or upstream.tls.include_system_cas in the proxy configuration so the proxy can verify the server’s certificate. See the proxy configuration reference.

Set the Tunnel OAuth configuration

When you add the tunneled MCP server as a custom connector in Organization settings > Connectors, turn on Tunnel OAuth configuration in the connector dialog. The values you enter replace the ones Claude would otherwise read from the authorization server’s metadata. Anthropic enables this option for each organization in the research preview on request, so if the toggle does not appear in the dialog, contact your Anthropic account team.

Field	What to enter	Example
Issuer	The issuer identifier your authorization server puts in its metadata and tokens. This can be an internal URL, because Claude uses it for validation rather than as an address to connect to.	`https://sso.example.corp:8443`
Authorization endpoint	The sign-in URL that members’ browsers are redirected to. It must be loadable from their devices, on the public internet or your corporate network.	`https://sso.example.corp/authorize`
Token endpoint	The token endpoint Claude exchanges the authorization code at. Either the endpoint as reached through the tunnel (an `https://` URL under your tunnel domain), or a public `https://` URL on the same origin (scheme, host, and port) as the Authorization endpoint.	`https://auth.abc123.tunnel.anthropic.com/oauth/token`
Registration endpoint (optional)	The dynamic client registration endpoint, under the same rule as Token endpoint: a URL under your tunnel domain or one on the Authorization endpoint’s origin. Leave it blank if you select Use your own OAuth client and enter a client ID you registered with the authorization server yourself.	`https://auth.abc123.tunnel.anthropic.com/oauth/register`
Requested scopes	The scopes Claude requests at sign-in, separated by spaces.	`openid wiki:read wiki:write`

The paths after the hostname (/authorize, /oauth/token, and so on) are whatever your authorization server uses. Copy them from its metadata document, usually served at /.well-known/oauth-authorization-server or /.well-known/openid-configuration, and change only the scheme and host. After you save the connector, connect it yourself from your own connector settings. Your browser should land on your sign-in page, and after you approve access the connector should show as connected. If either step fails, see Troubleshooting.

Publish split metadata instead

If you operate the authorization server and can change the metadata it publishes, you can get the same result without the connector settings by advertising the split yourself. Point authorization_endpoint at the browser-reachable hostname and every other endpoint at the tunnel hostname in the authorization server’s /.well-known/oauth-authorization-server document:

{
  "issuer": "https://auth.abc123.tunnel.anthropic.com",
  "authorization_endpoint": "https://sso.example.corp/authorize",
  "token_endpoint": "https://auth.abc123.tunnel.anthropic.com/oauth/token",
  "registration_endpoint": "https://auth.abc123.tunnel.anthropic.com/oauth/register",
  "code_challenge_methods_supported": ["S256"]
}

Then have the MCP server’s /.well-known/oauth-protected-resource document name the tunnel hostname as its authorization server:

{
  "resource": "https://docs.abc123.tunnel.anthropic.com/mcp",
  "authorization_servers": ["https://auth.abc123.tunnel.anthropic.com"]
}

This approach also suits an authorization server that is publicly reachable but sits behind a source-IP allowlist that you don’t want to open to Anthropic’s egress ranges. The platform troubleshooting guide walks through the same configuration. Use Tunnel OAuth configuration when the authorization server is a product whose metadata you can’t edit, or when you prefer to keep tunnel-specific addresses out of the server’s configuration. Use split metadata when you control the authorization server and want the configuration to apply to every client that discovers it through the tunnel.

Third-party Connectors

MCP Tunnels

Building Connectors

Built-in Integrations

Authenticate to MCP servers behind a tunnel

How OAuth works through a tunnel

Route the authorization server through the tunnel

Set the Tunnel OAuth configuration

Publish split metadata instead

​How OAuth works through a tunnel

​Route the authorization server through the tunnel

​Set the Tunnel OAuth configuration

​Publish split metadata instead

How OAuth works through a tunnel

Route the authorization server through the tunnel

Set the Tunnel OAuth configuration

Publish split metadata instead