Claude Connector Authentication: How OAuth Works and When You Need It

TL;DR: Claude Connector OAuth is only required if your connector accesses private user data. The flow is standard OAuth 2.0 with user consent, not machine-to-machine. You must allowlist both claude.ai and claude.com callback URLs. Client credentials flow is not supported. For local development, you can build and test connector behavior without any auth.

Authentication trips up a lot of connector developers because it’s not required by default, and the requirements only surface at submission time or when accessing protected resources. Here’s what you actually need to know.

When OAuth Is Required

Not every Claude Connector needs auth. Whether you need it depends on what your connector does and who it’s for.

You do not need OAuth if:

• Your connector accesses public data (public APIs, open datasets, public RSS feeds)
• Your connector accesses an internal service where all users share the same credentials
• You are building a development connector just for your own use

You need OAuth if:

• Your connector accesses private user data (email, calendar, documents, CRM records)
• Each user should only see their own data
• You are submitting to the Connectors Directory and your connector requires per-user authentication

Without OAuth, Claude does not forward any user identity information to your server. There are no user IDs, no session tokens, no IP addresses passed through. Your tool handlers run with no way to identify who called them. If you need to know which Claude user is calling your connector, OAuth is the only mechanism Claude supports.

How the OAuth Flow Works

Claude Connector OAuth is standard OAuth 2.0 authorization code flow with user consent. Claude handles the browser redirect and token management. You configure the OAuth application at your identity provider.

The flow works like this:

1. A user enables your connector in Claude.
2. If your connector requires auth, Claude redirects the user to your OAuth authorization URL.
3. The user signs in at your identity provider (Google, GitHub, your own auth system) and grants consent.
4. The identity provider redirects back to Claude’s callback URL with an authorization code.
5. Claude exchanges the code for an access token and refresh token, and stores them encrypted.
6. On every subsequent tool call, Claude includes the access token in the request so your server can authorize the user.

One important constraint: pure client credentials flow (machine-to-machine OAuth without user interaction) is not supported. Every user must complete the interactive consent flow to authenticate their individual account. If you need background, server-to-server access, that has to live inside your tool handlers, not in Claude’s credential management.

Configuring OAuth Callback URLs

The most common Connectors Directory rejection related to OAuth is missing callback URLs. Both of these must be allowlisted in your OAuth provider as valid redirect URIs:

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

Claude operates under both domains. If you only add the claude.ai URL, some users (depending on their region or the Claude product they use) will hit an OAuth error when authorizing. Add both.

Where you add these depends on your identity provider:

• Google: Google Cloud Console > APIs & Services > Credentials > your OAuth 2.0 client > Authorized redirect URIs
• GitHub: GitHub Developer Settings > OAuth Apps > your app > Authorization callback URL (GitHub only supports one, so you may need two apps or use a proxy)
• Okta, Auth0, custom: Add both URLs to your application’s allowed callback URLs

Setting Up OAuth for a Custom Connector

When you add a custom connector in Claude Settings, auth is optional. You can add a connector with just an MCP server URL for development and testing.

If your MCP server needs to protect its endpoints with OAuth, add it in the advanced settings:

1. Go to Claude Settings > Connectors.
2. Click the + icon and choose Add custom connector.
3. Enter your MCP server URL (e.g., https://abc123.ngrok-free.app/mcp).
4. Open Advanced settings.
5. Enter your OAuth Client ID and Client Secret.
6. Save.

For local development, you usually skip this. Test your connector’s tool behavior and UI rendering without auth, then wire up real OAuth when you’re ready to deploy.

OAuth Requirements for the Connectors Directory

If you are submitting to the Connectors Directory, the auth requirements are stricter.

If your connector requires authentication:

• Use OAuth 2.0 with user consent flow.
• Allowlist both callback URLs (claude.ai and claude.com).
• Provide a test account for Anthropic’s reviewers. They need to be able to authorize your connector and verify it works.
• Pure client credentials flow is not supported for Connectors Directory submissions.

If your connector does not require authentication:

• No OAuth setup needed.
• Reviewers will test without authenticating.

One nuance from the Anthropic FAQ: client credentials are not required for standard OAuth flows with user authentication. This means you can implement OAuth for your connector without provisioning specific credentials for Claude itself. Standard OAuth 2.0 authorization code flow, where Claude acts as the OAuth client using your registered Client ID, is what Anthropic expects.

Token Lifecycle

Understanding how Claude manages tokens helps you avoid confusion around token expiry and revocation.

Storage: Anthropic stores encrypted access tokens and refresh tokens. Your server does not need to manage token storage for Claude’s requests. The access token arrives in each tool call request.

Refresh: Claude handles token refresh automatically using the stored refresh token. You should return appropriate OAuth error responses if a token is invalid so Claude can re-initiate the auth flow.

Disconnection: When a user disconnects your connector in Claude settings, Anthropic removes the stored tokens from their systems. However, tokens at your identity provider remain valid until they expire. If your application needs to immediately cut off access when a user disconnects, you need to call your identity provider’s token revocation endpoint separately. Claude does not do this automatically.

No user metadata without auth: Without an OAuth token, Claude does not pass user information to your server. If you need per-user data segmentation, OAuth is the only way to get it.

What Claude Passes to Your Server

When Claude calls a tool on an authenticated connector, the access token from your identity provider arrives in the Authorization header of the HTTP request to your MCP server:

Authorization: Bearer <access_token>

You validate this token the same way you would for any OAuth-protected API. Verify it against your identity provider, extract the user identity, and use it to scope the data you return.

Without OAuth, there is no Authorization header. Your tool handlers receive the tool arguments only, with no user context.

Testing Auth Locally

For local development, you can build and test your connector’s tool behavior and UI without going through OAuth. Run your MCP server locally and connect to it directly. This lets you iterate on tool logic and resource rendering without wiring up an identity provider.

When you’re ready to test real OAuth end-to-end:

1. Deploy your server or expose it with ngrok (ngrok http 3000).
2. Register your OAuth app at your identity provider with the two Claude callback URLs.
3. Add your connector in Claude Settings with your Client ID and Secret.
4. Enable the connector in a conversation. Claude will redirect you through the OAuth consent flow.

If you’re using sunpeak, the local inspector lets you develop and test connector behavior (tool calls, resource rendering, simulations) without any auth. When you’re ready for the real OAuth flow, expose your sunpeak server with ngrok and add it as a custom connector.

The Claude Connectors tutorial covers the full local-to-production flow including ngrok setup and custom connector configuration.

Reading the Token in a Tool Handler

Here’s what reading the access token looks like in a typical MCP server tool handler. The token arrives via the MCP SDK’s extra parameter:

export default async function (args: { query: string }, extra: ToolHandlerExtra) {
  const token = extra.authInfo?.token;
  if (!token) {
    throw new Error('Authentication required');
  }

  // Use the token to call your identity provider or resource server
  const results = await fetchUserData(token, args.query);

  return {
    structuredContent: { results },
  };
}

The extra.authInfo object contains the access token from the Authorization header. This works the same whether the request comes from Claude, ChatGPT, or any other MCP host, because it’s part of the MCP protocol, not specific to any host.

If you’re building a connector that needs to reach the Connectors Directory, start by building and testing your tool behavior locally, then add OAuth at your identity provider when you’re ready to submit. The Connectors Directory submission guide covers the full requirements.