These factory functions build the
oauth value you pass to new MCPServer({ ... }). Each one returns an OAuthProvider (or OAuthProxy) that the server uses to verify bearer tokens, proxy .well-known metadata discovery, and extract user info onto ctx.auth.
There are two integration modes:
- DCR-direct providers (
oauthAuth0Provider,oauthBetterAuthProvider,oauthClerkProvider,oauthKeycloakProvider,oauthSupabaseProvider,oauthWorkOSProvider,oauthCustomProvider). The MCP server proxies metadata discovery to the upstream authorization server and verifies tokens. Clients communicate directly with the upstream for authorize, token, and register. - Proxy mode (
oauthProxy) for providers without Dynamic Client Registration support (Google, GitHub, Okta, Microsoft Entra ID, and enterprise IdPs). The server mediates the flow: it exposes a/registerendpoint returning the configuredclientId, injectsclientId/clientSecretat token exchange, and passes upstream tokens through without minting its own.
mcp-use/server.
Functions
oauthAuth0Provider
Create an Auth0 OAuth provider for an MCP server.OAuthProvider backed by Auth0. Supports zero-config setup: when config is omitted, domain falls back to MCP_USE_OAUTH_AUTH0_DOMAIN and audience falls back to MCP_USE_OAUTH_AUTH0_AUDIENCE. Throws Error if domain is missing ("Auth0 domain is required.") and throws Error if audience is missing ("Auth0 audience is required."). The config argument is Partial<Auth0ProviderConfig> and defaults to an empty object.
Parameters
ReturnsPartial<Auth0ProviderConfig>default:"{}"Optional Auth0 configuration. Values passed here override the corresponding environment variables.
SignatureOAuthProvider
oauthBetterAuthProvider
Create a Better Auth OAuth provider for an MCP server.OAuthProvider backed by Better Auth’s OAuth Provider plugin. The MCP server advertises Better Auth’s /oauth2/authorize, /oauth2/token, and /oauth2/register endpoints and verifies access-token JWTs against /jwks. Your application creates and mounts Better Auth separately.
Parameters
ReturnsBetterAuthOAuthProviderOptionsBetter Auth issuer URL and optional MCP resource metadata.
SignatureOAuthProvider<BetterAuthOAuthUser>
oauthClerkProvider
Create a Clerk OAuth provider for an MCP server.OAuthProvider backed by Clerk. Uses Dynamic Client Registration: clients register themselves with Clerk (enable DCR in the Clerk Dashboard under Configure, OAuth Applications, Dynamic Client Registration), and the MCP server only verifies Clerk-issued tokens. frontendApiUrl falls back to MCP_USE_OAUTH_CLERK_FRONTEND_API_URL. Throws Error if frontendApiUrl is missing ("Clerk frontendApiUrl is required."). The config argument is Partial<ClerkProviderConfig> and defaults to an empty object.
Parameters
ReturnsPartial<ClerkProviderConfig>default:"{}"Optional Clerk configuration. Values passed here override the corresponding environment variables.
SignatureOAuthProvider
oauthKeycloakProvider
Create a Keycloak OAuth provider for an MCP server.OAuthProvider backed by Keycloak using its native Dynamic Client Registration (RFC 7591). serverUrl falls back to MCP_USE_OAUTH_KEYCLOAK_SERVER_URL, realm falls back to MCP_USE_OAUTH_KEYCLOAK_REALM, and audience falls back to MCP_USE_OAUTH_KEYCLOAK_AUDIENCE. Throws Error if serverUrl is missing ("Keycloak serverUrl is required.") and throws Error if realm is missing ("Keycloak realm is required."). The config argument is Partial<KeycloakProviderConfig> and defaults to an empty object.
Parameters
ReturnsPartial<KeycloakProviderConfig>default:"{}"Optional Keycloak configuration. Values passed here override the corresponding environment variables.
SignatureOAuthProvider
oauthSupabaseProvider
Create a Supabase OAuth provider for an MCP server.OAuthProvider backed by Supabase’s OAuth 2.1 server. Supports zero-config setup: projectId falls back to MCP_USE_OAUTH_SUPABASE_PROJECT_ID, supabaseUrl falls back to MCP_USE_OAUTH_SUPABASE_URL, and jwtSecret falls back to MCP_USE_OAUTH_SUPABASE_JWT_SECRET. The hosted URL is derived as https://${projectId}.supabase.co unless supabaseUrl is set (use supabaseUrl for local or self-hosted instances, e.g. http://localhost:54321). Throws Error if neither projectId nor supabaseUrl is resolved ("Supabase projectId or supabaseUrl is required."). The config argument is Partial<SupabaseProviderConfig> and defaults to an empty object.
Parameters
ReturnsPartial<SupabaseProviderConfig>default:"{}"Optional Supabase configuration. Values passed here override the corresponding environment variables.
SignatureOAuthProvider
oauthWorkOSProvider
Create a WorkOS AuthKit OAuth provider for an MCP server.OAuthProvider backed by WorkOS AuthKit using Dynamic Client Registration. Clients register themselves with WorkOS (enable DCR in the WorkOS Dashboard under Connect, Configuration), and the MCP server only verifies WorkOS-issued tokens. subdomain falls back to MCP_USE_OAUTH_WORKOS_SUBDOMAIN. Throws Error if subdomain is missing ("WorkOS subdomain is required."). The config argument is Partial<WorkOSProviderConfig> and defaults to an empty object.
Parameters
ReturnsPartial<WorkOSProviderConfig>default:"{}"Optional WorkOS configuration. Values passed here override the corresponding environment variables.
SignatureOAuthProvider
oauthCustomProvider
Create an OAuth provider for any standards-compliant authorization server.OAuthProvider from explicit endpoint URLs and a custom verifyToken function. Unlike the other factories, config is required (there are no environment-variable fallbacks). Use this for any OAuth provider that exposes standard .well-known discovery and an authorization plus token endpoint, where you supply your own token verification logic.
Parameters
ReturnsCustomProviderConfigrequiredCustom provider configuration with explicit endpoints and averifyTokenfunction.
SignatureOAuthProvider
oauthProxy
Create an OAuth proxy for providers without Dynamic Client Registration.OAuthProxy for providers that lack DCR support (Google OAuth, GitHub OAuth, Okta, Microsoft Entra ID, and enterprise IdPs). The proxy exposes a /register endpoint that returns the configured clientId, injects clientId/clientSecret at token exchange, verifies tokens via the supplied verifyToken function, and passes upstream tokens through without minting its own. scopes defaults to ["openid", "email", "profile"] and grantTypes defaults to ["authorization_code", "refresh_token"]. When getUserInfo is omitted, a default extractor reads the standard OIDC claims (sub, email, name, picture) and splits the scope claim into scopes.
Throws Error if any of authEndpoint, tokenEndpoint, issuer, clientId, or verifyToken is missing. The verifyToken error message points you to jwksVerifier() for JWT/JWKS providers.
Pair oauthProxy with jwksVerifier() (exported from mcp-use/server) to verify JWTs against a remote JWKS. jwksVerifier enforces the iss claim, optionally enforces aud, and throws early with a helpful message if the token is not a three-segment signed JWT (for example, when an authorize request omitted a valid audience and the provider issued an opaque token).
Parameters
ReturnsOAuthProxyConfigrequiredOAuth proxy configuration including upstream endpoints, client credentials, and averifyTokenfunction.
SignatureOAuthProxy
mountOAuthProxy
Mount CORS-free OAuth proxy routes on a Hono app.oauthProxy, which configures the MCP server’s own authentication.
Both routes require a logical serverUrl. GET <basePath>/metadata?serverUrl=...&url=... accepts only protected-resource metadata derived from that MCP URL and authorization-server metadata advertised by the protected resource. POST <basePath>/proxy accepts { serverUrl, url, method: "POST", headers, body } only after discovery has bound url to the advertised registration, token, revocation, or introspection endpoint. Authorization navigation is never proxied.
Targets must use HTTPS. Loopback HTTP(S) is available only with the explicit local-development option. Private and non-routable addresses, redirects, unsafe headers, oversized bodies, and cross-origin callers not listed in allowedOrigins are rejected. Same-origin calls are always accepted. Metadata is returned unchanged; the BFF does not rewrite resource or add private fields.
Parameters
ReturnsHonorequiredThe Hono application instance to register routes on.OAuthProxyOptionsdefault:"{}"Configuration options for the proxy routes.
Signaturevoid
Types
Auth0ProviderConfig
Configuration foroauthAuth0Provider.
oauthAuth0Provider accepts Partial<Auth0ProviderConfig> and fills any missing domain/audience from environment variables.
Properties
SignaturestringrequiredAuth0 tenant domain, e.g.my-tenant.auth0.com.stringrequiredAPI identifier used as the JWTaudclaim.booleanWhether to verify the JWT signature.string[]Scopes advertised in metadata.
BetterAuthOAuthProviderOptions
Configuration foroauthBetterAuthProvider.
resource, requiredScopes, scopesSupported, resourceName, and serviceDocumentationUrl).
Properties
stringrequiredBase URL of the Better Auth OAuth server, e.g.http://localhost:61843/api/auth. This may be a different origin from the MCP resource server.Signaturestring[]Scopes advertised in metadata.
ClerkProviderConfig
Configuration foroauthClerkProvider.
frontendApiUrl falls back to MCP_USE_OAUTH_CLERK_FRONTEND_API_URL.
Properties
SignaturestringrequiredClerk Frontend API URL, e.g.https://verb-noun-42.clerk.accounts.devorhttps://clerk.yourdomain.com.stringOptional audience for JWT verification.booleanWhether to verify the JWT signature.string[]Scopes advertised in metadata.
KeycloakProviderConfig
Configuration foroauthKeycloakProvider.
serverUrl falls back to MCP_USE_OAUTH_KEYCLOAK_SERVER_URL, realm to MCP_USE_OAUTH_KEYCLOAK_REALM, and audience to MCP_USE_OAUTH_KEYCLOAK_AUDIENCE.
Properties
SignaturestringrequiredKeycloak base URL, e.g.https://keycloak.example.com.stringrequiredKeycloak realm name.stringMCP server URL used to validate the JWTaudclaim (set via a Keycloak audience mapper on client scopes).booleanWhether to verify the JWT signature.string[]Scopes advertised in metadata.
SupabaseProviderConfig
Configuration foroauthSupabaseProvider.
projectId or supabaseUrl must resolve (from config or environment). projectId derives the hosted URL https://${projectId}.supabase.co; supabaseUrl overrides it for self-hosted or local instances.
Properties
SignaturestringSupabase project ID used to derive the hosted URL.stringExplicit Supabase base URL. Overrides the projectId-derived URL, e.g.http://localhost:54321.stringOptional JWT secret for legacy HS256 token verification.booleanWhether to verify the JWT signature.string[]Scopes advertised in metadata.
WorkOSProviderConfig
Configuration foroauthWorkOSProvider.
subdomain falls back to MCP_USE_OAUTH_WORKOS_SUBDOMAIN.
Properties
SignaturestringrequiredWorkOS AuthKit subdomain, e.g.my-company.authkit.app.booleanWhether to verify the JWT signature.string[]Scopes advertised in metadata.
CustomProviderConfig
Configuration foroauthCustomProvider.
issuer, authEndpoint, tokenEndpoint, and verifyToken are required; the rest are optional. verifyToken resolves to an object containing a payload (see the signature fence for the exact type, which contains a curly brace). The optional getUserInfo callback maps a payload to a UserInfo.
Properties
SignaturestringrequiredOAuth issuer URL.stringrequiredAuthorization endpoint URL.stringrequiredToken endpoint URL.(token) => Promise<any>requiredFunction that verifies a bearer token and resolves to its decoded payload.stringJWKS endpoint URL for signature verification.stringUser info endpoint URL.string[]Scopes advertised in metadata.stringAudience for JWT verification.string[]Grant types advertised in metadata.(payload) => UserInfoOptional callback mapping a verified payload to user info.
OAuthProxy
The proxy-mode provider returned byoauthProxy.
OAuthProvider with proxy-specific fields for providers without DCR support. Implements the full provider interface (the getter methods plus verifyToken/getUserInfo) and adds a type discriminator, pre-registered client credentials, and optional extra authorize params. The proxy exposes a /register endpoint returning the configured clientId, injects clientId/clientSecret at token exchange, and passes upstream JWTs through without minting tokens.
Properties
Signature"proxy"requiredDiscriminator used to detect proxy providers in the provider union.stringrequiredPre-registered OAuth client ID.stringPre-registered OAuth client secret (optional for public clients).Record<string, string>Extra parameters appended to authorize requests.
OAuthProxyConfig
Configuration foroauthProxy.
authEndpoint, tokenEndpoint, issuer, clientId, and verifyToken are required. scopes defaults to ["openid", "email", "profile"] and grantTypes defaults to ["authorization_code", "refresh_token"] inside oauthProxy. The verifyToken field is a VerifyToken function that resolves to an object with a payload (see the signature fence for the exact type, which contains a curly brace). When getUserInfo is omitted, standard OIDC claims are extracted.
Properties
stringrequiredUpstream authorization endpoint URL, e.g.https://accounts.google.com/o/oauth2/v2/auth.
string
required
Upstream token endpoint URL, e.g.
https://oauth2.googleapis.com/token. string
required
Token issuer, used in metadata and (when paired with
jwksVerifier) enforced as the iss claim. VerifyToken
required
Token verification function. Use
jwksVerifier() for JWT+JWKS providers, or write your own for opaque tokens. string
required
Pre-registered OAuth client ID.
string
Pre-registered OAuth client secret (optional for public clients).
string[]
default:"[\"openid\", \"email\", \"profile\"]"
OAuth scopes to request.
string[]
default:"[\"authorization_code\", \"refresh_token\"]"
Supported grant types.
Record<string, string>
Extra parameters added to authorize requests, e.g.
{ access_type: "offline", prompt: "consent" }. (payload) => UserInfo
Custom extractor for user info from the verified payload. Defaults to standard OIDC claims.
OAuthProxyOptions
Options formountOAuthProxy.
mountOAuthProxy. Cross-origin access and loopback targets are disabled by default. authenticate and validateServerUrl may return a boolean or a promise.
Properties
Signaturestringdefault:"/oauth"Base path for the proxy routes.booleandefault:"true"Enable request logging to the console.readonly string[]default:"[]"Browser origins allowed to call the BFF cross-origin. Same-origin calls are implicit.booleandefault:"false"Permit HTTP(S) loopback targets for explicit local development.numberdefault:"10000"Upstream request timeout.numberdefault:"65536"Maximum BFF and OAuth endpoint request body size.numberdefault:"1048576"Maximum upstream response body size.(c: Context) => Promise<boolean> | booleanOptional request authentication. Returnfalseto reject with 401.(serverUrl: string, c: Context) => Promise<boolean> | booleanOptional deployment-specific allowlist for logical MCP server URLs. Returnfalseto reject with 403.