Skip to main content
Use oauthCustomProvider when your identity provider supports Dynamic Client Registration but mcp-use does not have a built-in provider for it. The MCP client registers with the upstream provider, and your MCP server verifies the resulting access token. If your provider only supports a pre-registered application with a fixed clientId and clientSecret, use OAuth Proxy instead. This guide shows the shape of a custom provider. Use the auth providers API reference for exact required fields, optional fields, defaults, and return contracts.

Confirm the provider supports DCR

Before using oauthCustomProvider, confirm the provider’s OAuth metadata advertises the full flow that MCP clients will use. Server-side authEndpoint and tokenEndpoint config does not repair incomplete upstream metadata.
At minimum, look for authorization, token, and registration endpoints:
Without a registration endpoint, MCP clients cannot register themselves upstream.

Configure token verification

Your custom provider must verify access tokens and return the verified payload.
The provider metadata at the issuer must advertise the registration endpoint. Do not skip signature, issuer, or audience checks for deployed servers.

Normalize user claims

Use getUserInfo to map provider-specific claims into fields your tools can read consistently.
After this mapping, tools can use ctx.auth.user.organizationId without parsing raw claims. Top-level ctx.auth.permissions is populated from the raw verified payload’s permissions claim; if you only return permissions from getUserInfo, read them from ctx.auth.user.permissions.

Verify the setup

Run the server and connect with an OAuth-capable MCP client.
Confirm these cases:
  • The client discovers OAuth metadata with a registration endpoint.
  • The client registers with the upstream provider.
  • Invalid tokens are rejected.
  • Authenticated tool calls include normalized fields in ctx.auth.

Next steps

OAuth Proxy

Use a provider that does not support Dynamic Client Registration.

User Context

Use normalized user claims inside tools.

Custom provider API reference

Look up exact custom provider options and contracts.

jose

Verify JWTs against a remote JWKS.