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

Claude Connector OAuth authentication flow.
TL;DR: Claude Connector auth is optional for public data. Use OAuth with PKCE, Protected Resource Metadata, and server-side token validation when access depends on the user. Claude also supports limited-beta shared request headers and authless servers. CIMD is the preferred new MCP client registration path; DCR remains supported for compatibility. Test discovery, scopes, user isolation, and refresh locally, then run one live Claude connection.
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.
Let public tools work before sign-in
If the server mixes public and private tools, Claude’s lazy authentication flow lets people use public tools before they connect an account. Keep tool discovery and public calls open. When Claude calls a protected tool without a valid token, stop the HTTP request before the MCP SDK handles it and return 401 with a WWW-Authenticate header pointing to your Protected Resource Metadata. Claude shows a Connect card and retries the call after sign-in. A tool handler that returns { isError: true } is wrapped in HTTP 200, so it cannot start this flow.
Use 403 with WWW-Authenticate: Bearer error="insufficient_scope" when a valid token needs more scope. Other 403 responses are terminal errors in Claude. This distinction matters when a user can search public records but needs a separate scope to edit one.
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 | You need compatibility with an existing Dynamic Client Registration setup | Claude supports it, though the MCP specification now deprecates DCR in favor of CIMD |
oauth_anthropic_creds | You need a stable directory OAuth client held by Anthropic | Enter the client in the Claude developer portal when you submit the listing |
custom_connection | The user or admin must supply custom connection details | Coordinate with Anthropic review |
static_headers | An organization Owner supplies a fixed API key or bearer token | Beta for a limited set of organizations; one shared credential |
none | Public, authless, or test-only connector | Supported |
For a new OAuth server, start with oauth_cimd if your authorization server supports it. The July 2026 MCP authorization specification deprecates DCR but keeps it for compatibility, and Claude’s authentication guide still supports it. Use oauth_anthropic_creds when you need a stable directory OAuth client and cannot support CIMD cleanly. Use static_headers only when your organization has access to the beta and one fixed credential matches the permission 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:
- The user connects your connector in Claude.
- Claude tries to initialize or call your remote MCP server.
- If no token is present, your server returns
401 Unauthorized. - The
WWW-Authenticatechallenge points Claude to Protected Resource Metadata. - Claude reads that metadata to find your authorization server.
- Claude reads OAuth or OpenID Connect discovery metadata from the authorization server.
- Claude identifies itself using CIMD, DCR, or a pre-arranged credential flow.
- Claude sends the user through authorization code with PKCE.
- The user signs in and consents at your authorization server.
- Claude receives the callback, exchanges the code for tokens, and stores them.
- Claude sends
Authorization: Bearer <token>on later MCP requests. - 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.
If your metadata lists more than one authorization server, Claude currently uses only the first entry. Put the intended issuer first and test the exact metadata URL from outside your private network. A reachable MCP endpoint with an unreachable metadata document still fails before tool discovery.
Authorization Server Metadata
Your authorization server should publish OAuth Authorization Server Metadata or OpenID Connect discovery.
At minimum, check these fields:
issuermatches the issuer in your tokens.authorization_endpointis reachable from users’ browsers.token_endpointaccepts form-encoded authorization-code and refresh requests.code_challenge_methods_supportedincludesS256.scopes_supportedincludes the scopes your connector may request.client_id_metadata_document_supportedis true if you want CIMD.registration_endpointexists if you want DCR.token_endpoint_auth_methods_supportedincludes 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.
- Keep DCR when an existing identity provider relies on it; plan a CIMD path for new deployments.
- 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
If the same MCP server supports other hosts, configure each host’s OAuth client identity and redirect separately. Never reuse Claude’s callback URL for a different client.
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 for a limited set of organizations. An Owner enters the header value when adding the connector, and Claude sends the same value on requests from every member. If the Request headers option is missing, that organization does not have beta access.
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 Team and Enterprise users auto-connect without a normal per-user consent screen. Claude presents your authorization server with an identity assertion signed by the customer’s identity provider or by Claude. Claude-issued assertions are in beta. Your authorization server validates the assertion and returns an access token in a back-channel exchange. Anthropic’s EMA guide documents both issuers and the listing coordination required for auto-connect.
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 current sunpeak releases, the auth info returned by your server’s auth() hook is available on extra.http?.authInfo. Validate the token in that hook before returning it. The clientId in AuthInfo identifies the OAuth client, so do not use it as the end user’s ID. The guard below prevents a handler from reading data if auth context is missing; the HTTP gate described above must issue the 401 that starts sign-in:
import type { ToolHandlerExtra } from 'sunpeak/mcp';
export default async function searchDocs(
args: { query: string },
extra: ToolHandlerExtra
) {
const auth = extra.http?.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 user = await resolveUserFromValidatedToken(auth.token);
const results = await searchAuthorizedDocs({ userId: user.id, query: args.query });
return {
structuredContent: { results },
};
}
resolveUserFromValidatedToken stands for your own identity lookup after token validation; it is not a sunpeak API. 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 follow-up data, use 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.http.authInfo. - Test user isolation with two identities and two data sets.
- Test
/.well-known/oauth-protected-resourceoutput. - Test unauthenticated requests return
401with aWWW-Authenticatechallenge. - For mixed auth, confirm public tools work without a token and a protected call triggers an HTTP
401, then succeeds after sign-in. - Test a valid token with too few scopes returns a step-up challenge, while a user who lacks source-system access remains denied after refresh.
- 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 its Claude runtime replica. Simulation files let you pin toolInput, structuredContent, _meta, and error states without a real OAuth provider or host account.
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, not200, when auth is required. - Include
WWW-Authenticate: Bearer resource_metadata="...". - Make sure protected resource metadata is reachable and its
resourcevalue 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_callbackexactly. - 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
resourceor audience claim matches your MCP server. - Return a clean
401for expired tokens so Claude can refresh or reconnect. - Check tenant and source-system permissions before returning data.
If Claude shows an error message instead of a Connect card, inspect the HTTP status before the MCP SDK handles the request. A tool result with isError: true and HTTP 200 tells Claude the tool failed; it does not start OAuth. For a missing or expired token, send the transport-level 401 challenge. For a missing scope, send the 403 step-up challenge described above.
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:
- Auth middleware validates tokens and rejects bad tokens.
- Tool handlers scope data to
extra.http.authInfo. - Tool results omit auth secrets.
- The UI renders connected, disconnected, denied, expired-token, and empty-data states.
- 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.
Get Started
npx sunpeak newFurther Reading
- Testing authentication in MCP Apps - token validation, authInfo, and OAuth flow checks
- MCP App Authentication - OAuth setup for ChatGPT, Claude, and other hosts
- What are Claude Connectors - types, data access, and custom setup
- Claude Connector Directory submission - auth review requirements and common rejections
- Testing Claude Connectors - local, CI, visual, and live host checks
- Security Testing for MCP Apps - token handling and trust boundaries
- Claude Connector framework - build and test interactive connectors
- Claude Connector tool design - permissions and narrow tool contracts
- Claude Connector data access patterns - user isolation and results
- Claude authentication for connectors
- Claude lazy authentication - public and protected tools on one server
- Claude Enterprise Managed Auth
- MCP authorization specification
- sunpeak MCP App testing guide
Frequently Asked Questions
Do Claude Connectors require OAuth?
No. Remote Claude Connectors can use per-user OAuth, an organization-level static credential where that beta option is available, or no authentication. Use OAuth for private user data, user-scoped write actions, and per-user audit trails. Authless servers suit public or test data; protect every private request on the MCP server.
What authentication types does Claude support for remote MCP connectors?
Claude supports oauth_dcr, oauth_cimd, oauth_anthropic_creds, custom_connection, static_headers, and none for remote MCP servers. DCR and CIMD are supported out of the box. Anthropic-held credentials and custom connection flows require review coordination. Static request headers are in beta for fixed organization-level credentials.
What OAuth callback URL should I register for Claude Connectors?
For Claude.ai web, Claude Desktop, Claude mobile, and Cowork, register https://claude.ai/api/mcp/auth_callback. Claude Code uses loopback redirects on ephemeral localhost ports, so authorization servers must accept http://localhost/callback and http://127.0.0.1/callback with port-agnostic matching.
What is Protected Resource Metadata for Claude Connectors?
Protected Resource Metadata is the OAuth resource-server discovery document for your MCP server. It declares the resource identifier and authorization server issuer. Claude can find it from a WWW-Authenticate challenge or by probing /.well-known/oauth-protected-resource paths, but the challenge path is more reliable across hosting platforms.
Can Claude use fixed API keys for custom connectors?
Claude supports static_headers in beta for a limited set of organizations. An Owner can enter a fixed request header, such as an API key or bearer token, when adding the connector. Claude sends the same value for every member who uses it, so scope the credential to what all those members should access. Never put secrets in connector URLs.
What is Enterprise Managed Auth for Claude Connectors?
Enterprise Managed Auth lets Team and Enterprise users auto-connect without an OAuth consent screen. Claude sends your authorization server a signed identity assertion issued by the customer identity provider or by Claude, then receives an access token in a back-channel exchange. Claude-issued assertions are in beta, and directory listings need Anthropic coordination to offer auto-connect.
How should I test Claude Connector authentication?
Test token validation, scope checks, user isolation, protected resource metadata, and unauthenticated 401 behavior locally. Use simulation fixtures for authenticated and unauthenticated UI states. Save real Claude live tests for OAuth redirects, connector settings, token refresh, public network reachability, and Claude Code loopback behavior.
Is Dynamic Client Registration still the recommended OAuth choice for Claude?
Claude still supports Dynamic Client Registration, but the July 2026 MCP authorization specification deprecated DCR in favor of Client ID Metadata Documents. Prefer CIMD for new authorization servers when you can support it. Keep DCR for compatibility with existing deployments, and confirm Claude can discover the registration method your server advertises.