Skip to main content
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 /register endpoint returning the configured clientId, injects clientId/clientSecret at token exchange, and passes upstream tokens through without minting its own.
All factories import from mcp-use/server.

Functions

oauthAuth0Provider

Create an Auth0 OAuth provider for an MCP server.
Builds an 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
Partial<Auth0ProviderConfig>
default:"{}"
Optional Auth0 configuration. Values passed here override the corresponding environment variables.
Returns
OAuthProvider
Signature
Example

oauthBetterAuthProvider

Create a Better Auth OAuth provider for an MCP server.
Builds an 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
BetterAuthOAuthProviderOptions
Better Auth issuer URL and optional MCP resource metadata.
Returns
OAuthProvider<BetterAuthOAuthUser>
Signature
Example

oauthClerkProvider

Create a Clerk OAuth provider for an MCP server.
Builds an 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
Partial<ClerkProviderConfig>
default:"{}"
Optional Clerk configuration. Values passed here override the corresponding environment variables.
Returns
OAuthProvider
Signature
Example

oauthKeycloakProvider

Create a Keycloak OAuth provider for an MCP server.
Builds an 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
Partial<KeycloakProviderConfig>
default:"{}"
Optional Keycloak configuration. Values passed here override the corresponding environment variables.
Returns
OAuthProvider
Signature
Example

oauthSupabaseProvider

Create a Supabase OAuth provider for an MCP server.
Builds an 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
Partial<SupabaseProviderConfig>
default:"{}"
Optional Supabase configuration. Values passed here override the corresponding environment variables.
Returns
OAuthProvider
Signature
Example

oauthWorkOSProvider

Create a WorkOS AuthKit OAuth provider for an MCP server.
Builds an 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
Partial<WorkOSProviderConfig>
default:"{}"
Optional WorkOS configuration. Values passed here override the corresponding environment variables.
Returns
OAuthProvider
Signature
Example

oauthCustomProvider

Create an OAuth provider for any standards-compliant authorization server.
Builds an 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
CustomProviderConfig
required
Custom provider configuration with explicit endpoints and a verifyToken function.
Returns
OAuthProvider
Signature
Example

oauthProxy

Create an OAuth proxy for providers without Dynamic Client Registration.
Builds an 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
OAuthProxyConfig
required
OAuth proxy configuration including upstream endpoints, client credentials, and a verifyToken function.
Returns
OAuthProxy
Signature
Example

mountOAuthProxy

Mount CORS-free OAuth proxy routes on a Hono app.
Mounts a server-side OAuth BFF for browser MCP clients. This is distinct from 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
Hono
required
The Hono application instance to register routes on.
OAuthProxyOptions
default:"{}"
Configuration options for the proxy routes.
Returns
void
Signature
Example

Types

Auth0ProviderConfig

Configuration for oauthAuth0Provider.
Configuration for the Auth0 provider. oauthAuth0Provider accepts Partial<Auth0ProviderConfig> and fills any missing domain/audience from environment variables. Properties
string
required
Auth0 tenant domain, e.g. my-tenant.auth0.com.
string
required
API identifier used as the JWT aud claim.
boolean
Whether to verify the JWT signature.
string[]
Scopes advertised in metadata.
Signature

BetterAuthOAuthProviderOptions

Configuration for oauthBetterAuthProvider.
Configuration for the Better Auth provider. It includes the shared OAuth resource options (resource, requiredScopes, scopesSupported, resourceName, and serviceDocumentationUrl). Properties
string
required
Base 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.
string[]
Scopes advertised in metadata.
Signature

ClerkProviderConfig

Configuration for oauthClerkProvider.
Configuration for the Clerk provider. frontendApiUrl falls back to MCP_USE_OAUTH_CLERK_FRONTEND_API_URL. Properties
string
required
Clerk Frontend API URL, e.g. https://verb-noun-42.clerk.accounts.dev or https://clerk.yourdomain.com.
string
Optional audience for JWT verification.
boolean
Whether to verify the JWT signature.
string[]
Scopes advertised in metadata.
Signature

KeycloakProviderConfig

Configuration for oauthKeycloakProvider.
Configuration for the Keycloak provider. 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
string
required
Keycloak base URL, e.g. https://keycloak.example.com.
string
required
Keycloak realm name.
string
MCP server URL used to validate the JWT aud claim (set via a Keycloak audience mapper on client scopes).
boolean
Whether to verify the JWT signature.
string[]
Scopes advertised in metadata.
Signature

SupabaseProviderConfig

Configuration for oauthSupabaseProvider.
Configuration for the Supabase provider. Either 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
string
Supabase project ID used to derive the hosted URL.
string
Explicit Supabase base URL. Overrides the projectId-derived URL, e.g. http://localhost:54321.
string
Optional JWT secret for legacy HS256 token verification.
boolean
Whether to verify the JWT signature.
string[]
Scopes advertised in metadata.
Signature

WorkOSProviderConfig

Configuration for oauthWorkOSProvider.
Configuration for the WorkOS provider. subdomain falls back to MCP_USE_OAUTH_WORKOS_SUBDOMAIN. Properties
string
required
WorkOS AuthKit subdomain, e.g. my-company.authkit.app.
boolean
Whether to verify the JWT signature.
string[]
Scopes advertised in metadata.
Signature

CustomProviderConfig

Configuration for oauthCustomProvider.
Configuration for an arbitrary OAuth provider. 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
string
required
OAuth issuer URL.
string
required
Authorization endpoint URL.
string
required
Token endpoint URL.
(token) => Promise<any>
required
Function that verifies a bearer token and resolves to its decoded payload.
string
JWKS endpoint URL for signature verification.
string
User info endpoint URL.
string[]
Scopes advertised in metadata.
string
Audience for JWT verification.
string[]
Grant types advertised in metadata.
(payload) => UserInfo
Optional callback mapping a verified payload to user info.
Signature

OAuthProxy

The proxy-mode provider returned by oauthProxy.
Extends 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
"proxy"
required
Discriminator used to detect proxy providers in the provider union.
string
required
Pre-registered OAuth client ID.
string
Pre-registered OAuth client secret (optional for public clients).
Record<string, string>
Extra parameters appended to authorize requests.
Signature

OAuthProxyConfig

Configuration for oauthProxy.
Configuration for creating an OAuth proxy. 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
string
required
Upstream 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.
Signature

OAuthProxyOptions

Options for mountOAuthProxy.
Options for configuring the fail-closed Hono OAuth BFF routes mounted by mountOAuthProxy. Cross-origin access and loopback targets are disabled by default. authenticate and validateServerUrl may return a boolean or a promise. Properties
string
default:"/oauth"
Base path for the proxy routes.
boolean
default:"true"
Enable request logging to the console.
readonly string[]
default:"[]"
Browser origins allowed to call the BFF cross-origin. Same-origin calls are implicit.
boolean
default:"false"
Permit HTTP(S) loopback targets for explicit local development.
number
default:"10000"
Upstream request timeout.
number
default:"65536"
Maximum BFF and OAuth endpoint request body size.
number
default:"1048576"
Maximum upstream response body size.
(c: Context) => Promise<boolean> | boolean
Optional request authentication. Return false to reject with 401.
(serverUrl: string, c: Context) => Promise<boolean> | boolean
Optional deployment-specific allowlist for logical MCP server URLs. Return false to reject with 403.
Signature