Claude Remote MCP OAuth: Build Discovery, PKCE, Scopes, and Token Refresh

A remote MCP server is not ready for Claude when the login screen appears. It is ready when discovery is deterministic, every token is bound to the right resource and user, scopes match the requested tools, refresh survives rotation, and failure tests prove that the server rejects the wrong token.

This guide turns the current Claude connector behavior and MCP authorization requirements into an implementation contract. The original contribution is an acceptance model: eight interfaces, three client-registration choices, and a test matrix that a platform team can run before a connector reaches users.

Evidence status before implementation

Keep three evidence classes separate.

• Measured first-party search evidence: unavailable. ClaudeExperts has no configured Search Console or GA4 property, so this topic is a low-data experiment rather than a claim of measured demand.
• Current external evidence: Anthropic documents Claude's supported connector authentication modes, PKCE behavior, metadata discovery, scope selection, callback differences, and token refresh behavior. The MCP specification and OAuth RFCs define protected-resource metadata, resource indicators, token audience binding, and public-client protections.
• Implementation inference: the architecture, decision table, operational ownership, and acceptance tests below are a proposed production pattern derived from those sources. They are not requirements published by Anthropic.

Specialist review: Dhruv Khatri is the named technical reviewer. Review is requested and pending. Treat the proposed defaults below as review-ready controls, not as a record of completed expert approval.

The eight-interface authorization contract

Most failed OAuth integrations are not one bug. They are a mismatch between interfaces owned by different teams.

Assign an owner to every row. If the MCP team owns only the last HTTP handler while identity, networking, and directory onboarding are unowned, the connector is not production-ready.

Choose the registration model deliberately

Claude supports more than one way to establish an OAuth client. Use the operating model, not implementation convenience, to choose.

Do not use a query-string API key as a shortcut. Anthropic's connector documentation says user-pasted bearer tokens and credentials in connector URLs are not supported. A server-to-server client_credentials grant is also not a substitute for a consent-gated user connection.

Implement the discovery path first

Start with the unauthenticated request because it controls everything that follows.

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

The protected-resource document should identify the exact MCP resource and its authorization server:

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://identity.example.com"],
  "scopes_supported": ["records.read", "records.write"]
}

Exactness matters. If a user enters https://mcp.example.com/mcp, do not advertise only the origin as the resource. Anthropic documents path-aware discovery and recommends an explicit resource_metadata pointer in the 401 challenge. Relying on client probing adds round trips and breaks when a hosting platform cannot serve the expected well-known path.

The authorization server must then publish RFC 8414 or OpenID Connect discovery metadata. For Claude interoperability, verify the registration mechanism and advertise S256 PKCE support. Return discovery documents over HTTPS and test them from outside the corporate network so a WAF or conditional-access policy does not create a false local success.

Bind every token to this MCP resource

An access token that proves a user signed in is not sufficient. The MCP server must also prove that the token was issued for this resource.

At the start of every authenticated request, validate:

1. the token signature against the trusted issuer's current keys;
2. the issuer against an explicit allowlist;
3. the audience or resource identifier against the exact MCP server URL;
4. expiry and not-before claims with a small documented clock-skew allowance;
5. required scopes for the requested tool;
6. the subject and tenant expected for this connection;
7. revocation or session state where the identity architecture requires it.

Then build an authorization context that tools receive explicitly. Do not let a tool recover identity from a global variable or a connection-wide cache.

type McpAuthContext = {
  subject: string;
  tenantId: string;
  scopes: Set<string>;
  tokenId?: string;
};

function requireScope(ctx: McpAuthContext, scope: string) {
  if (!ctx.scopes.has(scope)) throw new Error("insufficient_scope");
}

The token from Claude is for the MCP resource. If the MCP server calls Salesforce, Google Drive, or another upstream API, use a separate upstream credential or delegated token issued for that API. Token passthrough creates an audience-confusion problem and is explicitly rejected by the MCP security model.

Make scopes match tools, not teams

Broad role names such as employee or admin are weak tool boundaries. Prefer scopes tied to stable actions:

• records.read for search and retrieval;
• records.write for reversible edits;
• records.export for bulk data movement;
• billing.refund for a narrow irreversible action.

Return only tools that the current authorization context may see, and recheck scope inside the handler. The first control reduces accidental selection; the second is the enforcement boundary.

Use the scope parameter in the WWW-Authenticate challenge when a request needs step-up access. Do not request every possible scope during initial connection. A useful policy is read scopes at connection time, write scopes when a write-capable tool is first requested, and a fresh consent event for high-impact scopes.

Design refresh as a state transition

Anthropic documents both proactive refresh shortly before expiry and reactive refresh after a 401. Your token endpoint therefore needs predictable behavior under overlap, retries, and rotation.

For public clients, rotate refresh tokens or sender-constrain them. When rotating, return the replacement refresh token in the same successful response that invalidates the old token. Store only a protected representation, link the token family to the user and client, and detect reuse of an invalidated family member.

Model refresh with these states:

Accept form-encoded bodies at the token endpoint. A JSON-only parser that returns 415 can make the entire flow look like a Claude client problem.

Run this acceptance test matrix

Do not stop at one successful login. Run positive, negative, expiry, and tenant-isolation cases.

Worked example: a CRM connector

Assume the MCP endpoint is https://mcp.example.com/crm. A sales operator connects with crm.contacts.read. Claude can list and search contacts, but the update_contact tool is absent. When the operator asks to correct a title, the server challenges for crm.contacts.write. After consent, the refreshed tool list includes the update operation.

The handler validates the token audience as the exact /crm resource, checks tenant membership, applies the write, and logs the subject and record identifier. It does not forward the MCP token to the CRM. A separate service credential, constrained to that tenant, performs the upstream API call.

This example is intentionally narrow. The design makes a mistaken write observable and bounded, and it lets removing crm.contacts.write take effect at the next refresh rather than waiting for a human to delete an integration.

Ship the contract, not only the code

Before review, attach four artifacts to the implementation:

1. the exact protected-resource and authorization-server metadata documents;
2. a registration-model decision with an owner for credential and redirect changes;
3. the scope-to-tool matrix and upstream credential boundary;
4. automated results for the acceptance matrix, including denied cases.

This turns OAuth from a login feature into a testable authorization system. If your team needs a review of the MCP resource boundary, identity model, token validation, or interoperability tests, the MCP and Tool Integration engagement is designed around that implementation work. Start with MCP versus ad-hoc Claude tools for the protocol decision and Claude tool schema design for the tool contract.

Sources

• Anthropic: Authentication for connectors
• Anthropic: Troubleshooting connectors
• Model Context Protocol: Authorization
• RFC 9728: OAuth 2.0 Protected Resource Metadata
• RFC 8707: Resource Indicators for OAuth 2.0