Skip to main content
Use oauthCustomProvider when your authorization server supports Dynamic Client Registration (DCR) but mcp-use does not provide a built-in adapter. The MCP client registers upstream; your server publishes metadata, verifies access tokens, and maps verified claims into application identity.

Required contract

Import MCPServer from mcp-use and the provider contract from mcp-use/oauth.
createTokenVerifier(resource) receives the resolved canonical MCP resource. The verifier must validate token signature or introspection, issuer, expiry, and that resource, then return SDK auth information including scopes, expiresAt, and the validated resource. If your authorization server issues standard JWTs, createJwtVerifier does all of that for you and is the same helper the built-in providers use. Given a jwksUrl, it checks the signature, issuer, required exp and sub claims, and resource binding. It then returns the auth information in the shape the SDK expects. For standards-conformant JWT access tokens, the verifier checks the aud claim for the MCP resource URL. The aud claim can be a string or an array containing the resource URL. RFC 8707 defines resource as an authorization and token request parameter, not as a JWT access-token claim. For compatibility with providers that include a non-standard resource claim, the verifier accepts a string-valued resource claim equal to the MCP resource URL and uses it instead of aud. Pass audience when the provider’s JWT audience differs from the MCP resource. Write the verifier by hand when the provider does not issue JWTs, for example when you have to call a token introspection endpoint. oauthMetadata is the authorization server’s RFC 8414 metadata. It must describe the actual upstream endpoints and include the registration_endpoint used by MCP clients. mapAuthInfo(authInfo) receives only verified SDK auth information. It must return:
  • user: your provider-specific normalized user, with id as the stable subject;
  • payload: the verified claims or introspection response;
  • permissions: application permissions derived from verified data.
The server exposes those values as ctx.auth.user, ctx.auth.payload, and ctx.auth.permissions. ctx.auth.scopes remains the verifier’s verified authInfo.scopes.

Verify the integration

Test that:
  • the client discovers metadata containing the correct registration endpoint;
  • client registration, PKCE authorization, and token exchange happen upstream;
  • tokens with the wrong issuer, expiry, signature, or MCP resource are rejected;
  • mapped identity and permissions contain only verified data.

Next steps

User Context

Use the mapped user, scopes, and permissions in callbacks.

OAuth overview

Compare built-in providers.