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
ImportMCPServer 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, the issuer, the required exp and sub claims, and the resource binding, then returns the auth information in the shape the SDK expects. Pass audience when the provider’s JWT audience differs from the MCP resource. With no audience, the token must carry a matching RFC 8707 resource claim or an aud claim containing the resource URL.
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, withidas the stable subject;payload: the verified claims or introspection response;permissions: application permissions derived from verified data.
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.