MCP OAuth Integration#

The @better-auth/mcp package turns a Better Auth instance into an OAuth 2.1 authorization server for Model Context Protocol clients. It is a thin wrapper over @better-auth/oauth-provider: the mcp() plugin calls oauthProvider() internally, binds issued tokens to a required resource identifier (RFC 8707), registers RFC 9728 protected-resource metadata, and defaults refreshTokenReuseInterval to 30 seconds so retried refresh requests can recover a rotated response 1.

Legacy vs. new. An older mcp plugin ships inside better-auth/plugins on top of the deprecated oidc-provider, with endpoints under /mcp/*. The standalone @better-auth/mcp package (introduced in v1.7.0-beta.6) moves endpoints to /oauth2/* and is the actively maintained path 2.

JWT Plugin Alignment and JWKS Endpoint#

The JWT plugin (better-auth/plugins → jwt()) is required by @better-auth/mcp 2. It performs two roles:

1. Signing key provider — when a resource audience is included in a token request, createJwtAccessToken calls getJwtPlugin(ctx.context) and delegates signing to the JWT plugin 3. OAuth access tokens and ordinary session JWTs share the same issuer, algorithm, and key pair.

2. JWKS endpoint — the JWT plugin registers GET /jwks. The introspection endpoint fetches this key set to verify JWT access tokens: it prefers an in-process call to jwtPlugin.endpoints.getJwks(ctx) when no jwks.remoteUrl is configured, and passes the plugin instance as a WeakMap-keyed cache entry (jwksCacheKey) so the key set is reused across requests rather than fetched per call 4.

Guard against plain session JWTs. Because session JWTs and OAuth access tokens share the same signing key, validateJwtAccessToken rejects any token that lacks the azp (authorized party) claim. Only tokens issued by the OAuth token endpoint carry azp; plain session JWTs do not 5.

Token Introspection Endpoint (POST /oauth2/introspect)#

Implemented in introspectEndpoint, per RFC 7662. Requires client credentials (Basic auth or client_id/client_secret body params). The legacy plugin has no equivalent 3.

Resolution order (when no token_type_hint): JWT access token → opaque access token → refresh token 6.

Custom claims in responses:

• Opaque tokens: validateOpaqueAccessToken calls the customAccessTokenClaims hook and merges the result into the introspection response — custom claims are re-evaluated at introspection time 3.
• JWT tokens: the full decoded JWT payload (including custom claims baked in at issuance by createJwtAccessToken) is returned directly 6.

Response shape (RFC 7662 §2.2): active, sub, scope, client_id, exp, iat, iss, sid, plus any custom claims. BAD_REQUEST errors are swallowed and returned as { active: false } 3. Pairwise sub identifiers are resolved at the presentation layer by resolveIntrospectionSub before the response is emitted 3.

Protected Resource Metadata (RFC 9728)#

The mcp() plugin intercepts GET /.well-known/oauth-protected-resource (and a path-inserted alias) and returns an RFC 9728 document built by buildResourceServerMetadata 7. The document includes:

• resource — the canonical MCP resource URI
• authorization_servers — the provider's issuer URL
• scopes_supported — resource-scoped scopes only (OIDC identity scopes and offline_access are filtered out)
• bearer_methods_supported: ["header"]
• dpop_signing_alg_values_supported — from provider DPoP config

Endpoint Map#

3 2

Key Source Files#