Claude Connector Authentication: How OAuth Works and When You Need It (July 2026)

TL;DR: Claude Connector auth is optional until your connector needs private data, write actions, or per-user auditability. For normal user-scoped access, use OAuth with PKCE, Protected Resource Metadata, and token validation on your MCP server. Claude supports DCR, CIMD, Anthropic-held client credentials, static request headers, authless connectors, and Enterprise Managed Auth. Build most auth tests locally, then run a narrow live Claude check for redirects, token refresh, and connector settings.

Authentication is still the fastest way to break a Claude Connector because the failure can happen before Claude ever calls a tool. Your MCP server can be reachable, your tools can be valid, and your UI can render locally, but a missing metadata document, bad callback URL, slow token endpoint, or wrong audience check can stop the connector at the “Connect” button.

This guide focuses on the Claude path. For the broader cross-host MCP auth model, read MCP App Authentication. For test strategy, read Testing authentication in MCP Apps.

When Auth Is Required

You can skip OAuth when the connector only reads public data, serves a demo, or uses fixed test data during local development. Authless remote MCP servers are supported, and they are useful while you are shaping tools and resources.

Add auth when:

• Tool output depends on the current user.
• The connector reads private files, messages, issues, customer records, invoices, or account data.
• A tool can create, update, delete, approve, send, export, or share anything.
• You need tenant isolation, role checks, admin policy, or audit logs.
• You are preparing a directory connector that reaches private user data.

Without auth, Claude does not send your application’s user ID to the MCP server. Your server receives an MCP request and tool arguments. If you need to know who the user is, the connector needs an authentication path and your server needs to validate it.

Claude’s Supported Auth Types

Claude’s connector docs list several authentication types for remote MCP servers.

Type	Use it when	Notes
oauth_cimd	Your authorization server supports Client ID Metadata Documents	Good default for new connectors when supported
oauth_dcr	Your authorization server supports Dynamic Client Registration	Works out of the box but can create many client registrations
oauth_anthropic_creds	You need a stable directory OAuth client held by Anthropic	Contact mcp-review@anthropic.com
custom_connection	The user or admin must supply custom connection details	Coordinate with Anthropic review
static_headers	An organization admin supplies a fixed API key or bearer token	Beta, organization-shared credential
none	Public, authless, or test-only connector	Supported

For most production connectors, start with oauth_cimd or oauth_dcr. Use oauth_anthropic_creds when you want a stable OAuth client for a directory connector but cannot support CIMD or DCR cleanly. Use static_headers only when a fixed organization-level credential matches the product and security model.

Avoid credentials in URLs. A connector URL such as https://mcp.example.com/mcp?token=... can leak through server logs, proxy logs, browser history, analytics tools, screenshots, and support tickets. Put credentials in OAuth or request headers instead.

The OAuth Flow Claude Runs

Claude acts as the OAuth client on behalf of the user. Your MCP server is the protected resource server. Your identity provider is the authorization server.

The flow:

1. The user connects your connector in Claude.
2. Claude tries to initialize or call your remote MCP server.
3. If no token is present, your server returns 401 Unauthorized.
4. The WWW-Authenticate challenge points Claude to Protected Resource Metadata.
5. Claude reads that metadata to find your authorization server.
6. Claude reads OAuth or OpenID Connect discovery metadata from the authorization server.
7. Claude identifies itself using CIMD, DCR, or a pre-arranged credential flow.
8. Claude sends the user through authorization code with PKCE.
9. The user signs in and consents at your authorization server.
10. Claude receives the callback, exchanges the code for tokens, and stores them.
11. Claude sends Authorization: Bearer <token> on later MCP requests.
12. Your MCP server validates the token before running tools.

Your server owns step 12. Do not trust a bearer token just because Claude sent it. Verify signature, issuer, audience or resource, expiry, not-before time, scopes, tenant membership, and any product policy before you return data.

Protected Resource Metadata

Protected Resource Metadata is how Claude discovers which authorization server protects your MCP server.

Serve it at:

https://mcp.example.com/.well-known/oauth-protected-resource

A useful document looks like this:

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["docs:read", "docs:write"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.example.com/claude-connector"
}

The resource value must match the MCP server URL the user enters in Claude, including the path. Your authorization server should mint tokens for that resource, and your MCP server should reject tokens meant for another API.

Return a 401 like this when a request has no valid token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="docs:read"

Claude can fall back to probing /.well-known/oauth-protected-resource/<mcp-path> and then /.well-known/oauth-protected-resource, but the explicit challenge is more reliable. It also helps on platforms where /.well-known routes are awkward, such as some edge-function or path-prefixed deployments.

Authorization Server Metadata

Your authorization server should publish OAuth Authorization Server Metadata or OpenID Connect discovery.

At minimum, check these fields:

• issuer matches the issuer in your tokens.
• authorization_endpoint is reachable from users’ browsers.
• token_endpoint accepts form-encoded authorization-code and refresh requests.
• code_challenge_methods_supported includes S256.
• scopes_supported includes the scopes your connector may request.
• client_id_metadata_document_supported is true if you want CIMD.
• registration_endpoint exists if you want DCR.
• token_endpoint_auth_methods_supported includes the method Claude will use.

Claude waits up to 10 seconds for OAuth discovery, registration, and token endpoint responses, and up to 30 seconds for refresh-token requests. A slow identity provider can look like a connector bug, so keep auth endpoints fast and make sure reverse proxies do not buffer responses behind slow downstream work.

CIMD, DCR, and Anthropic-Held Credentials

Client ID Metadata Documents, or CIMD, let Claude use an HTTPS metadata document URL as its client_id. Your authorization server fetches the document and validates Claude’s client metadata. Claude selects CIMD only when your authorization server advertises client_id_metadata_document_supported: true and supports none in token_endpoint_auth_methods_supported, because the CIMD client is public at the token endpoint.

Dynamic Client Registration, or DCR, lets Claude call your registration_endpoint and create a client dynamically. It is standard and useful, but directory traffic can create many registered clients over time.

Anthropic-held credentials are different. You create an OAuth client_id and client_secret, share them with Anthropic through review coordination, and Anthropic stores them for the directory entry. Users still go through consent. This is not a pure machine-to-machine flow because the user remains in the loop.

Use this rule:

• Prefer CIMD when your authorization server supports it.
• Use DCR when dynamic registration is already normal for your identity provider.
• Use Anthropic-held credentials when you need a stable directory OAuth client and cannot use CIMD.

Callback URLs

For hosted Claude surfaces, register:

https://claude.ai/api/mcp/auth_callback

Claude uses that callback for Claude.ai web, Claude Desktop, Claude mobile, and Cowork.

Claude Code is a native client. It uses loopback redirects on ephemeral ports, such as:

http://localhost:3118/callback

Because the port changes, your authorization server must accept these redirect patterns with port-agnostic matching:

http://localhost/callback
http://127.0.0.1/callback

For ChatGPT Apps, use the callback URL shown in the OpenAI app or plugin setup. Do not assume Claude and ChatGPT share callback URLs. The MCP server code can be shared, but each host has its own OAuth client identity and redirect configuration.

Static Headers and API Keys

Some connectors authenticate to a backend with a fixed organization-level credential instead of per-user OAuth. Claude supports this through static_headers in beta. An organization administrator enters the header value when adding the connector, and Claude sends it on requests.

This can fit:

• Internal read-only knowledge sources.
• A service account with narrow access.
• Backends that cannot support OAuth yet.
• Early private connectors where the admin controls the credential.

It is a poor fit for user-owned data, write actions, and public directory connectors where each user should keep their own source-system permissions. A shared API key means your MCP server must enforce any missing user or tenant policy itself.

Enterprise Managed Auth

Enterprise Managed Auth, or EMA, lets enterprise users connect without a normal per-user consent screen. Claude presents your authorization server with an identity assertion, signed by the customer’s identity provider. Your authorization server validates the assertion and returns an access token in a back-channel exchange.

Use EMA when:

• The connector is for enterprise customers with SSO.
• Users should connect silently from an existing organization session.
• The customer wants central identity policy instead of each user authorizing manually.
• Your authorization server can validate signed identity assertions and map them to users.

EMA is still an auth flow you have to test. Validate issuer, audience, signature, expiry, tenant, user mapping, and what happens when the user’s organization removes access.

Token Refresh and Revocation

Claude refreshes tokens proactively before expiry and reactively after a 401. Your authorization server should return standard OAuth errors, such as invalid_grant, when a refresh token is no longer valid. Custom error shapes make reconnect flows harder to diagnose.

For public-client connections through CIMD or DCR, rotate refresh tokens or sender-constrain them. If you rotate refresh tokens, return the new refresh token in the same response that invalidates the old one.

When a user disconnects a connector, Anthropic removes its stored tokens. Tokens at your identity provider remain valid until they expire or your system revokes them. If disconnect must cut off access immediately, expose or trigger token revocation on your side.

What Your Tool Handler Sees

Authenticated MCP requests include:

Authorization: Bearer <access_token>

In a sunpeak tool handler, the validated auth info is available on extra.authInfo:

import type { ToolHandlerExtra } from 'sunpeak/mcp';

export default async function searchDocs(
  args: { query: string },
  extra: ToolHandlerExtra
) {
  const auth = extra.authInfo;
  if (!auth?.token) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Authentication is required.' }],
    };
  }

  if (!auth.scopes?.includes('docs:read')) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Missing docs:read scope.' }],
    };
  }

  const results = await searchAuthorizedDocs({
    token: auth.token,
    userId: auth.clientId,
    query: args.query,
  });

  return {
    structuredContent: { results },
  };
}

Keep tokens on the server. Do not put access tokens, refresh tokens, API keys, permission maps, or session cookies in content, structuredContent, _meta, or UI component props. If a UI resource needs to fetch follow-up data, prefer a server tool or a narrow backend endpoint that revalidates the caller.

Local and Live Testing

Most connector auth tests should run locally:

• Unit test token validation with valid, expired, wrong-issuer, wrong-audience, missing-scope, and malformed tokens.
• Unit test tool handlers by passing mock extra.authInfo.
• Test user isolation with two identities and two data sets.
• Test /.well-known/oauth-protected-resource output.
• Test unauthenticated requests return 401 with a WWW-Authenticate challenge.
• Test authenticated and unauthenticated UI states with simulation files.
• Test that no tool result leaks raw tokens or private auth data.

Use sunpeak to render authenticated and unauthenticated connector states locally in Claude and ChatGPT runtime replicas. Simulation files let you pin toolInput, structuredContent, _meta, and error states without a real OAuth provider, host account, or AI credits.

Save live Claude tests for the parts only Claude can prove:

• The remote MCP URL is reachable from Anthropic infrastructure.
• OAuth redirects return to https://claude.ai/api/mcp/auth_callback.
• Claude Code loopback redirects work if you support Claude Code.
• Token refresh works after expiry.
• Organization-level custom connector settings work for Team or Enterprise users.
• Static headers, EMA, or Anthropic-held credentials behave as reviewed.

Troubleshooting

If Claude cannot connect:

• Confirm the MCP server URL is public HTTPS and includes the correct path.
• Return 401, not 200, when auth is required.
• Include WWW-Authenticate: Bearer resource_metadata="...".
• Make sure protected resource metadata is reachable and its resource value matches the MCP URL.
• Make sure the authorization server is reachable from Anthropic’s outbound network.

If the browser redirect fails:

• Register https://claude.ai/api/mcp/auth_callback exactly.
• Add Claude Code loopback redirect patterns if you support Claude Code.
• Check that the authorization server advertises PKCE S256.
• Confirm the token endpoint accepts application/x-www-form-urlencoded.

If users connect but tools fail:

• Verify token issuer, audience, expiry, and scopes.
• Check that the resource or audience claim matches your MCP server.
• Return a clean 401 for expired tokens so Claude can refresh or reconnect.
• Check tenant and source-system permissions before returning data.

If Enterprise Managed Auth fails:

• Validate the identity assertion signature and issuer.
• Confirm the customer’s identity provider is configured for the connector.
• Check tenant mapping and user provisioning.
• Log assertion validation failures without logging secrets.

Where sunpeak Fits

You can build Claude Connector authentication with any MCP SDK and identity provider. The hard part is proving all the states before review or rollout.

sunpeak gives you the local Claude inspector, mockable tool state, simulation fixtures, E2E tests, visual tests, live host checks, and CI workflow. Use it to test the connector without auth first, then add auth fixtures, then run one live Claude test for the real OAuth path.

For an authenticated interactive connector, test the contract in this order:

1. Auth middleware validates tokens and rejects bad tokens.
2. Tool handlers scope data to extra.authInfo.
3. Tool results omit auth secrets.
4. The UI renders connected, disconnected, denied, expired-token, and empty-data states.
5. The deployed connector completes one live Claude OAuth flow.

That is enough coverage to catch most Claude Connector authentication bugs before a reviewer or customer sees them.