@better-auth/mcp 1.7.0-rc.2 → 1.7.0-rc.3

package/README.md

@@ -2,19 +2,43 @@
 
 Model Context Protocol (MCP) plugin for [Better Auth](https://www.better-auth.com).
 
-`mcp()` turns your Better Auth app into an OAuth 2.1 authorization server for MCP
-clients, built on [`@better-auth/oauth-provider`](https://www.better-auth.com/docs/plugins/oauth-provider).
-It serves the RFC 9728 protected resource metadata so MCP clients can discover it.
-To protect an MCP route, wrap its handler with `requireMcpAuth` (or `mcpHandler`),
-which verifies bearer tokens against the published JWKS.
+`mcp()` turns your Better Auth app into an OAuth 2.1 authorization server and
+protected resource for MCP clients, built on
+[`@better-auth/oauth-provider`](https://www.better-auth.com/docs/plugins/oauth-provider).
+It serves RFC 9728 protected resource metadata and binds issued tokens to the
+configured resource. Compose it with `cimd()` for the MCP 2026-07-28 Client ID
+Metadata Document flow, which pins CIMD draft-00 through an explicit metadata
+profile. Dynamic Client Registration is disabled unless explicitly enabled.
+
+`@better-auth/mcp` owns authorization, not MCP protocol transport. Serve MCP
+2026-07-28 requests with version 2 of the official
+[`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+package, configure `createMcpHandler` with `legacy: "reject"`, mount it behind
+`requireMcpAuth`, and expose only the HTTP `POST` route. The modern protocol
+handles each request independently and does not need a Redis-backed MCP
+session store. Multi-instance `subscriptions/listen` deployments can supply a
+shared SDK event bus without introducing protocol-level sessions.
 
 ```ts
 import { betterAuth } from "better-auth";
 import { jwt } from "better-auth/plugins";
+import { cimd } from "@better-auth/cimd";
+import { fetchClientMetadataResource } from "@better-auth/cimd/node";
 import { mcp } from "@better-auth/mcp";
 
 export const auth = betterAuth({
-  plugins: [jwt(), mcp({ loginPage: "/login", consentPage: "/consent" })],
+  plugins: [
+    jwt(),
+    mcp({
+      loginPage: "/login",
+      consentPage: "/consent",
+      resource: "https://api.example.com/mcp",
+    }),
+    cimd({
+      fetchClientMetadataResource,
+      metadataProfile: "mcp-2026-07-28",
+    }),
+  ],
 });
 ```
 

package/dist/index.d.mts

@@ -1,21 +1,54 @@
 import { OAuthOptions, Scope, oauthProvider } from "@better-auth/oauth-provider";
-import { DpopReplayReservations, DpopReplayStore, verifyAccessTokenRequest } from "better-auth/oauth2";
-import { JWTPayload } from "jose";
+import { DpopReplayReservations, DpopReplayStore } from "better-auth/oauth2";
 import { Awaitable } from "@better-auth/core";
+import { JWTPayload, JWTVerifyOptions } from "jose";
 import { BetterAuthOptions } from "better-auth/types";
 //#region src/handler.d.ts
+interface McpProtectedRequestHandlerOptions {
+  /** Expected authorization-server issuer for the access token. */
+  issuer: string;
+  /** Canonical MCP protected-resource URL expected in the token audience. */
+  audience: string;
+  /**
+   * Additional JOSE verification constraints. `issuer` and `audience` remain
+   * authoritative from the top-level fields.
+   */
+  jwtVerifyOptions?: Omit<JWTVerifyOptions, "issuer" | "audience">;
+  /** URL of the authorization server's JSON Web Key Set. */
+  jwksUrl?: string;
+  /** Remote introspection settings for opaque or remotely checked tokens. */
+  remoteVerify?: {
+    introspectUrl: string;
+    clientId: string;
+    clientSecret: string;
+    force?: boolean;
+    allowMissingAudience?: boolean;
+  };
+  /** Scopes every accepted access token must satisfy. */
+  requiredScopes?: readonly string[];
+  /**
+   * Scopes to advertise in unauthenticated `WWW-Authenticate` challenges.
+   * Defaults to `requiredScopes`.
+   */
+  challengeScopes?: readonly string[];
+  /** Custom required-scope matcher. Defaults to exact membership. */
+  isScopeSatisfied?: (requiredScope: string, grantedScopes: ReadonlySet<string>) => boolean;
+  /** DPoP proof validation and replay-protection settings. */
+  dpop?: {
+    proofMaxAgeSeconds?: number;
+    signingAlgorithms?: readonly string[];
+    replayStore?: DpopReplayStore;
+  };
+}
 /**
  * A request middleware handler that verifies an MCP access token and responds
  * with an RFC 9728 `WWW-Authenticate` header for unauthenticated requests.
+ * When `options.requiredScopes` is set, tokens missing a required scope receive
+ * a 403 with an RFC 6750 `insufficient_scope` challenge naming them instead.
  *
  * @external
  */
-declare const mcpHandler: (
-/** Verifier options. `audience` must match the protected resource identifier. */
-verifyOptions: Parameters<typeof verifyAccessTokenRequest>[1], handler: (req: Request, jwt: JWTPayload) => Awaitable<Response>, opts?: {
-  /** Maps non-url (ie urn, client) resources to resource_metadata */
-  resourceMetadataMappings: Record<string, string>;
-}) => (req: Request) => Promise<Response>;
+declare const createMcpProtectedRequestHandler: (options: McpProtectedRequestHandlerOptions, handler: (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>) => (request: Request) => Promise<Response>;
 //#endregion
 //#region src/plugin.d.ts
 /**
@@ -28,17 +61,22 @@ interface McpOptions extends OAuthOptions<Scope[]> {
    * token response for the same effective scopes, requested resources, and
    * sender constraint.
    *
-   * MCP overrides the OAuth Provider default because native/public MCP clients
-   * can have multiple local sessions racing the same refresh token. Set to `0`
-   * to keep strict replay handling.
+   * OAuth Provider remains strict by default. MCP overrides that default for
+   * every client configured through this plugin so a retried refresh can
+   * recover the response produced by an earlier request. Set to `0` to disable
+   * the overlap window and keep strict replay handling.
    *
    * @default 30
    */
   refreshTokenReuseInterval?: OAuthOptions<Scope[]>["refreshTokenReuseInterval"];
   /**
-   * The protected resource identifier (RFC 8707 / RFC 9728) that access tokens
-   * are bound to. Published as `resource` in the protected resource metadata,
-   * added to `resources`, and used as the expected token audience.
+   * The canonical protected resource identifier (RFC 8707 / RFC 9728) for this
+   * MCP server. Issued tokens are audience-bound to it, and it is published as
+   * `resource` in the protected resource metadata, added to `resources`, and
+   * used as the expected token audience.
+   *
+   * Must be an HTTPS URL with no query, fragment, or credentials. HTTP is
+   * accepted only on loopback hosts for local development.
    */
   resource: string;
 }
@@ -46,12 +84,19 @@ interface McpOptions extends OAuthOptions<Scope[]> {
  * Model Context Protocol authorization server.
  *
  * `mcp()` is the OAuth 2.1 / OIDC provider ({@link oauthProvider}) configured for
- * MCP: it enables dynamic client registration, binds issued tokens to the MCP
- * `resource`, and, as the resource server, serves the RFC 9728 protected resource
- * metadata so MCP clients discover and use it through standard OAuth discovery.
- * It also defaults `refreshTokenReuseInterval` to 30 seconds for native/public
- * MCP clients that may retry a refresh after a local process loses the rotated
- * response.
+ * MCP: it binds issued tokens to the MCP `resource`, links that resource to
+ * newly registered clients, and, as the resource server, serves the RFC 9728
+ * protected resource metadata so MCP clients discover and use it through
+ * standard OAuth discovery. Client registration is opt-in: compose with
+ * `cimd()` for Client ID Metadata Documents, or explicitly enable the OAuth
+ * Provider dynamic-registration options.
+ * It also defaults `refreshTokenReuseInterval` to 30 seconds for all MCP
+ * clients, allowing a retried refresh to recover a rotated response. OAuth
+ * Provider remains strict by default; set the MCP option to `0` to disable the
+ * overlap window.
+ * MCP 2026-07-28 pins Client ID Metadata Documents draft-00. Configure the
+ * CIMD plugin with `metadataProfile: "mcp-2026-07-28"` and an application-owned
+ * metadata-resource transport.
  * Because it is the OAuth provider, it cannot be combined with a separate
  * {@link oauthProvider}.
  *
@@ -59,7 +104,9 @@ interface McpOptions extends OAuthOptions<Scope[]> {
  * ```ts
  * import { betterAuth } from "better-auth";
  * import { jwt } from "better-auth/plugins";
+ * import { cimd } from "@better-auth/cimd";
  * import { mcp } from "@better-auth/mcp";
+ * import { fetchClientMetadataResource } from "./oauth-network";
  *
  * export const auth = betterAuth({
  *   plugins: [
@@ -69,6 +116,10 @@ interface McpOptions extends OAuthOptions<Scope[]> {
  *       consentPage: "/consent",
  *       resource: "https://api.example.com/mcp",
  *     }),
+ *     cimd({
+ *       fetchClientMetadataResource,
+ *       metadataProfile: "mcp-2026-07-28",
+ *     }),
  *   ],
  * });
  * ```
@@ -93,16 +144,20 @@ interface RequireMcpAuthOptions {
    */
   jwksUrl?: string;
   /**
-   * Space-delimited scopes to advertise in the `WWW-Authenticate` challenge
-   * (RFC 6750), hinting which scopes the client should request.
+   * Scopes to advertise in the `WWW-Authenticate` challenge (RFC 6750),
+   * hinting which scopes the client should request. Defaults to the enforced
+   * `requiredScopes` when those are set.
    */
-  scope?: string;
+  challengeScopes?: readonly string[];
   /**
-   * Maps a non-URL `resource` (an RFC 8707 `urn:` identifier or a client id) to
-   * the URL of its protected resource metadata. Required when `resource` is not
-   * an origin-based URL, so the `WWW-Authenticate` challenge can point at it.
+   * Scopes the access token must include, enforced against the token's
+   * `scope` claim. A token missing any of them is rejected with a 403 and an
+   * RFC 6750 `insufficient_scope` challenge naming every missing scope, so MCP
+   * clients can step up their authorization in one round-trip.
    */
-  resourceMetadataMappings?: Record<string, string>;
+  requiredScopes?: readonly string[];
+  /** Custom required-scope matcher. Defaults to exact membership. */
+  isScopeSatisfied?: (requiredScope: string, grantedScopes: ReadonlySet<string>) => boolean;
   /**
    * DPoP proof validation settings. By default the replay store is backed by
    * the auth instance's database adapter, so anti-replay holds across multiple
@@ -120,10 +175,15 @@ interface RequireMcpAuthOptions {
  * audience, and expiry) and forwards the verified JWT payload to the handler.
  * Unauthenticated requests receive a JSON-RPC 401 with the RFC 9728
  * `WWW-Authenticate` header so MCP clients can start the authorization flow.
+ * Tokens missing a required scope receive a 403 with an RFC 6750
+ * `insufficient_scope` challenge naming the missing scopes, so clients can step
+ * up their authorization; a handler can raise the same challenge for scopes only
+ * it knows about by throwing `createInsufficientScopeError`.
  *
  * For a resource server that runs separately from the authorization server, or
- * a server using a dynamic `baseURL`, use {@link mcpHandler} with explicit
- * verification options instead.
+ * a server using a dynamic `baseURL`, use
+ * {@link createMcpProtectedRequestHandler} with explicit verification options
+ * instead.
  *
  * @external
  */
@@ -133,6 +193,6 @@ declare const requireMcpAuth: <Auth extends {
     baseURL: string;
     internalAdapter: DpopReplayReservations;
   }>;
-}>(auth: Auth, handler: (req: Request, jwt: JWTPayload) => Awaitable<Response>, opts?: RequireMcpAuthOptions) => (req: Request) => Promise<Response>;
+}>(auth: Auth, handler: (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>, opts?: RequireMcpAuthOptions) => (req: Request) => Promise<Response>;
 //#endregion
-export { type McpOptions, mcp, mcpHandler, requireMcpAuth };
+export { type McpOptions, type McpProtectedRequestHandlerOptions, type RequireMcpAuthOptions, createMcpProtectedRequestHandler, mcp, requireMcpAuth };

package/dist/index.mjs

@@ -1,42 +1,85 @@
-import { ResourceUriSchema, getIssuer, metadataResponse, oauthProvider, raiseResourceServerChallenge } from "@better-auth/oauth-provider";
-import { DPOP_SIGNING_ALGORITHMS, createDpopReplayStore, requestToResourceInput, verifyAccessTokenRequest } from "better-auth/oauth2";
-import { APIError } from "better-call";
+import { createResourceServerChallenge, getIssuer, metadataResponse, oauthProvider } from "@better-auth/oauth-provider";
+import { DPOP_SIGNING_ALGORITHMS, createDpopReplayStore, isInsufficientScopeError, requestToResourceInput, verifyAccessTokenRequest } from "better-auth/oauth2";
 //#region src/handler.ts
+function isLoopbackHost(hostname) {
+	const ipv4Octets = hostname.split(".");
+	const isIpv4Loopback = ipv4Octets.length === 4 && ipv4Octets[0] === "127" && ipv4Octets.every((octet) => /^\d+$/.test(octet) && Number(octet) <= 255);
+	return hostname === "localhost" || hostname === "[::1]" || isIpv4Loopback;
+}
+/**
+* Validates the canonical protected-resource identifier accepted by MCP.
+*
+* @internal
+*/
+function validateMcpResource(resource) {
+	if (typeof resource !== "string") throw new TypeError("MCP resource must be a single URL string");
+	let url;
+	try {
+		url = new URL(resource);
+	} catch {
+		throw new TypeError("MCP resource must be an absolute URL");
+	}
+	if (url.username || url.password) throw new TypeError("MCP resource URL must not contain credentials");
+	if (resource.includes("#")) throw new TypeError("MCP resource URL must not contain a fragment");
+	if (resource.includes("?")) throw new TypeError("MCP resource URL must not contain a query; to protect a query-carrying resource, verify tokens with verifyAccessTokenRequest and build challenges with createResourceServerChallenge");
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) throw new TypeError("MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs");
+	return resource;
+}
+function toChallengeResponse(error, resource, opts) {
+	const challenge = createResourceServerChallenge(error, resource, opts);
+	if (!challenge) throw error;
+	const headers = new Headers(challenge.headers);
+	headers.set("Content-Type", "application/json");
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		error: {
+			code: -32e3,
+			message: challenge.message
+		},
+		id: null
+	}), {
+		status: challenge.statusCode,
+		headers
+	});
+}
 /**
 * A request middleware handler that verifies an MCP access token and responds
 * with an RFC 9728 `WWW-Authenticate` header for unauthenticated requests.
+* When `options.requiredScopes` is set, tokens missing a required scope receive
+* a 403 with an RFC 6750 `insufficient_scope` challenge naming them instead.
 *
 * @external
 */
-const mcpHandler = (verifyOptions, handler, opts) => {
-	return async (req) => {
+const createMcpProtectedRequestHandler = (options, handler) => {
+	const resource = validateMcpResource(options.audience);
+	const resolvedChallengeOptions = {
+		challengeScopes: options.challengeScopes ?? options.requiredScopes,
+		dpopSigningAlgorithms: options.dpop?.signingAlgorithms
+	};
+	const accessTokenVerificationOptions = {
+		verifyOptions: {
+			...options.jwtVerifyOptions,
+			issuer: options.issuer,
+			audience: options.audience
+		},
+		jwksUrl: options.jwksUrl,
+		remoteVerify: options.remoteVerify,
+		requiredScopes: options.requiredScopes,
+		isScopeSatisfied: options.isScopeSatisfied,
+		dpop: options.dpop
+	};
+	return async (request) => {
+		let accessTokenClaims;
 		try {
-			return handler(req, await verifyAccessTokenRequest(requestToResourceInput(req), verifyOptions));
+			accessTokenClaims = await verifyAccessTokenRequest(requestToResourceInput(request), accessTokenVerificationOptions);
 		} catch (error) {
-			try {
-				raiseResourceServerChallenge(error, verifyOptions.verifyOptions.audience, {
-					...opts,
-					dpopSigningAlgorithms: verifyOptions.dpop?.signingAlgorithms
-				});
-			} catch (err) {
-				if (err instanceof APIError) {
-					const headers = new Headers(err.headers);
-					headers.set("Content-Type", "application/json");
-					return new Response(JSON.stringify({
-						jsonrpc: "2.0",
-						error: {
-							code: -32e3,
-							message: err.message
-						},
-						id: null
-					}), {
-						status: err.statusCode,
-						headers
-					});
-				}
-				throw new Error(String(err));
-			}
-			throw new Error(String(error));
+			return toChallengeResponse(error, resource, resolvedChallengeOptions);
+		}
+		try {
+			return await handler(request, accessTokenClaims);
+		} catch (error) {
+			if (isInsufficientScopeError(error)) return toChallengeResponse(error, resource, resolvedChallengeOptions);
+			throw error;
 		}
 	};
 };
@@ -57,6 +100,7 @@ const appendProtectedResource = (resources, resource) => {
 	if (configuredResources.some((configuredResource) => resourceIdentifier(configuredResource) === resource)) return configuredResources;
 	return [...configuredResources, resource];
 };
+const appendResourceIdentifier = (resources, resource) => resources?.includes(resource) ? resources : [...resources ?? [], resource];
 /**
 * Build the RFC 9728 Protected Resource Metadata document. The MCP server is the
 * resource server, and its authorization server is this same provider, so
@@ -82,12 +126,19 @@ const buildResourceServerMetadata = (ctx, providerOptions, resource) => {
 * Model Context Protocol authorization server.
 *
 * `mcp()` is the OAuth 2.1 / OIDC provider ({@link oauthProvider}) configured for
-* MCP: it enables dynamic client registration, binds issued tokens to the MCP
-* `resource`, and, as the resource server, serves the RFC 9728 protected resource
-* metadata so MCP clients discover and use it through standard OAuth discovery.
-* It also defaults `refreshTokenReuseInterval` to 30 seconds for native/public
-* MCP clients that may retry a refresh after a local process loses the rotated
-* response.
+* MCP: it binds issued tokens to the MCP `resource`, links that resource to
+* newly registered clients, and, as the resource server, serves the RFC 9728
+* protected resource metadata so MCP clients discover and use it through
+* standard OAuth discovery. Client registration is opt-in: compose with
+* `cimd()` for Client ID Metadata Documents, or explicitly enable the OAuth
+* Provider dynamic-registration options.
+* It also defaults `refreshTokenReuseInterval` to 30 seconds for all MCP
+* clients, allowing a retried refresh to recover a rotated response. OAuth
+* Provider remains strict by default; set the MCP option to `0` to disable the
+* overlap window.
+* MCP 2026-07-28 pins Client ID Metadata Documents draft-00. Configure the
+* CIMD plugin with `metadataProfile: "mcp-2026-07-28"` and an application-owned
+* metadata-resource transport.
 * Because it is the OAuth provider, it cannot be combined with a separate
 * {@link oauthProvider}.
 *
@@ -95,7 +146,9 @@ const buildResourceServerMetadata = (ctx, providerOptions, resource) => {
 * ```ts
 * import { betterAuth } from "better-auth";
 * import { jwt } from "better-auth/plugins";
+* import { cimd } from "@better-auth/cimd";
 * import { mcp } from "@better-auth/mcp";
+* import { fetchClientMetadataResource } from "./oauth-network";
 *
 * export const auth = betterAuth({
 *   plugins: [
@@ -105,19 +158,22 @@ const buildResourceServerMetadata = (ctx, providerOptions, resource) => {
 *       consentPage: "/consent",
 *       resource: "https://api.example.com/mcp",
 *     }),
+*     cimd({
+*       fetchClientMetadataResource,
+*       metadataProfile: "mcp-2026-07-28",
+*     }),
 *   ],
 * });
 * ```
 */
 const mcp = (options) => {
-	const { resource, refreshTokenReuseInterval = 30, ...oauthOptions } = options;
-	ResourceUriSchema.parse(resource);
+	const { resource: configuredResource, refreshTokenReuseInterval = 30, ...oauthOptions } = options;
+	const resource = validateMcpResource(configuredResource);
 	const provider = oauthProvider({
-		allowDynamicClientRegistration: true,
-		allowUnauthenticatedClientRegistration: true,
 		refreshTokenReuseInterval,
 		...oauthOptions,
-		resources: appendProtectedResource(oauthOptions.resources, resource)
+		resources: appendProtectedResource(oauthOptions.resources, resource),
+		clientRegistrationDefaultResources: appendResourceIdentifier(oauthOptions.clientRegistrationDefaultResources, resource)
 	});
 	const serveProviderDiscovery = provider.onRequest;
 	return {
@@ -149,70 +205,46 @@ const mcp = (options) => {
 };
 //#endregion
 //#region src/require-mcp-auth.ts
-const unauthorized = (error) => {
-	const headers = new Headers(error.headers);
-	headers.set("Content-Type", "application/json");
-	return new Response(JSON.stringify({
-		jsonrpc: "2.0",
-		error: {
-			code: -32e3,
-			message: error.message
-		},
-		id: null
-	}), {
-		status: error.statusCode,
-		headers
-	});
-};
 /**
 * Protects an MCP server route handler. Verifies the bearer access token
 * against the authorization server's JWKS (checking signature, issuer,
 * audience, and expiry) and forwards the verified JWT payload to the handler.
 * Unauthenticated requests receive a JSON-RPC 401 with the RFC 9728
 * `WWW-Authenticate` header so MCP clients can start the authorization flow.
+* Tokens missing a required scope receive a 403 with an RFC 6750
+* `insufficient_scope` challenge naming the missing scopes, so clients can step
+* up their authorization; a handler can raise the same challenge for scopes only
+* it knows about by throwing `createInsufficientScopeError`.
 *
 * For a resource server that runs separately from the authorization server, or
-* a server using a dynamic `baseURL`, use {@link mcpHandler} with explicit
-* verification options instead.
+* a server using a dynamic `baseURL`, use
+* {@link createMcpProtectedRequestHandler} with explicit verification options
+* instead.
 *
 * @external
 */
 const requireMcpAuth = (auth, handler, opts) => {
-	if (opts?.resource !== void 0) ResourceUriSchema.parse(opts.resource);
+	if (opts?.resource !== void 0) validateMcpResource(opts.resource);
 	return async (req) => {
 		const { baseURL, internalAdapter } = await auth.$context;
-		if (!baseURL) throw new Error("requireMcpAuth requires a resolvable base URL. For dynamic base URLs use `mcpHandler` with explicit verify options.");
+		if (!baseURL) throw new Error("requireMcpAuth requires a resolvable base URL. For dynamic base URLs use `createMcpProtectedRequestHandler` with explicit verification options.");
 		const issuer = opts?.issuer ?? baseURL;
 		const resource = opts?.resource ?? baseURL;
 		const jwksUrl = opts?.jwksUrl ?? `${baseURL}/jwks`;
-		try {
-			return handler(req, await verifyAccessTokenRequest(requestToResourceInput(req), {
-				verifyOptions: {
-					issuer,
-					audience: resource
-				},
-				jwksUrl,
-				dpop: {
-					proofMaxAgeSeconds: opts?.dpop?.proofMaxAgeSeconds,
-					signingAlgorithms: opts?.dpop?.signingAlgorithms,
-					replayStore: opts?.dpop?.replayStore ?? createDpopReplayStore(internalAdapter)
-				}
-			}));
-		} catch (error) {
-			try {
-				raiseResourceServerChallenge(error, resource, {
-					scope: opts?.scope,
-					resourceMetadataMappings: opts?.resourceMetadataMappings,
-					dpopSigningAlgorithms: opts?.dpop?.signingAlgorithms
-				});
-			} catch (challengeError) {
-				if (challengeError instanceof APIError) return unauthorized(challengeError);
-				if (challengeError instanceof Error) throw challengeError;
-				throw new Error(String(challengeError));
+		return createMcpProtectedRequestHandler({
+			issuer,
+			audience: resource,
+			requiredScopes: opts?.requiredScopes,
+			challengeScopes: opts?.challengeScopes,
+			isScopeSatisfied: opts?.isScopeSatisfied,
+			jwksUrl,
+			dpop: {
+				proofMaxAgeSeconds: opts?.dpop?.proofMaxAgeSeconds,
+				signingAlgorithms: opts?.dpop?.signingAlgorithms,
+				replayStore: opts?.dpop?.replayStore ?? createDpopReplayStore(internalAdapter)
 			}
-			throw new Error(String(error));
-		}
+		}, handler)(req);
 	};
 };
 //#endregion
-export { mcp, mcpHandler, requireMcpAuth };
+export { createMcpProtectedRequestHandler, mcp, requireMcpAuth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/mcp",
-  "version": "1.7.0-rc.2",
+  "version": "1.7.0-rc.3",
   "description": "Model Context Protocol (MCP) plugin for Better Auth",
   "type": "module",
   "license": "MIT",
@@ -36,49 +36,31 @@
       "dev-source": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
-    },
-    "./client": {
-      "dev-source": "./src/client/index.ts",
-      "types": "./dist/client/index.d.mts",
-      "default": "./dist/client/index.mjs"
-    },
-    "./client/adapters": {
-      "dev-source": "./src/client/adapters.ts",
-      "types": "./dist/client/adapters.d.mts",
-      "default": "./dist/client/adapters.mjs"
     }
   },
   "typesVersions": {
     "*": {
       "*": [
         "./dist/index.d.mts"
-      ],
-      "client": [
-        "./dist/client/index.d.mts"
-      ],
-      "client/adapters": [
-        "./dist/client/adapters.d.mts"
       ]
     }
   },
   "dependencies": {
     "jose": "^6.1.3",
-    "@better-auth/oauth-provider": "^1.7.0-rc.2"
+    "@better-auth/oauth-provider": "^1.7.0-rc.3"
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "better-call": "1.3.7",
-    "listhen": "1.9.0",
     "tsdown": "0.22.7",
-    "better-auth": "1.7.0-rc.2",
-    "@better-auth/core": "1.7.0-rc.2"
+    "@better-auth/core": "1.7.0-rc.3",
+    "better-auth": "1.7.0-rc.3"
   },
   "peerDependencies": {
-    "@better-auth/utils": "0.4.2",
-    "@better-fetch/fetch": "1.3.1",
     "better-call": "1.3.7",
-    "better-auth": "^1.7.0-rc.2",
-    "@better-auth/core": "^1.7.0-rc.2"
+    "@better-auth/core": "^1.7.0-rc.3",
+    "better-auth": "^1.7.0-rc.3"
   },
   "scripts": {
     "build": "tsdown",

package/dist/client/adapters.d.mts

@@ -1,55 +0,0 @@
-import { McpResourceClient, McpResourceClientOptions, McpSession } from "./index.mjs";
-//#region src/client/adapters.d.ts
-interface HonoContext {
-  req: {
-    header: (name: string) => string | undefined;
-    raw: Request;
-  };
-  set: (key: string, value: unknown) => void;
-  json: (data: unknown, status?: number, headers?: Record<string, string>) => Response;
-  header: (name: string, value: string) => void;
-}
-type HonoNext = () => Promise<void>;
-type HonoMiddleware = (c: HonoContext, next: HonoNext) => Promise<Response | void>;
-interface HonoApp {
-  get: (path: string, handler: (c: HonoContext) => Promise<Response>) => void;
-}
-declare function mcpAuthHono(options: McpResourceClientOptions): {
-  client: McpResourceClient;
-  middleware: HonoMiddleware;
-  discoveryRoutes: (app: HonoApp, serverURL: string) => void;
-};
-declare function mcpAuthOfficial(options: McpResourceClientOptions): {
-  client: McpResourceClient;
-  handler: McpResourceClient["handler"];
-  verifyToken: McpResourceClient["verifyToken"];
-};
-type OAuthMode = "direct" | "proxy";
-interface McpUseUserInfo {
-  userId: string;
-  roles?: string[];
-  permissions?: string[];
-  scopes?: string;
-  clientId?: string;
-  [key: string]: unknown;
-}
-interface OAuthProvider {
-  verifyToken(token: string): Promise<{
-    payload: Record<string, unknown>;
-  }>;
-  getUserInfo(payload: Record<string, unknown>): McpUseUserInfo;
-  getIssuer(): string;
-  getAuthEndpoint(): string;
-  getTokenEndpoint(): string;
-  getScopesSupported(): string[];
-  getGrantTypesSupported(): string[];
-  getMode(): OAuthMode;
-  getRegistrationEndpoint?(): string;
-}
-interface McpUseBetterAuthConfig {
-  authURL: string;
-  getUserInfo?: (payload: Record<string, unknown>) => McpUseUserInfo;
-}
-declare function mcpAuthMcpUse(config: McpUseBetterAuthConfig): OAuthProvider;
-//#endregion
-export { type McpResourceClient, type McpResourceClientOptions, type McpSession, McpUseBetterAuthConfig, mcpAuthHono, mcpAuthMcpUse, mcpAuthOfficial };

package/dist/client/adapters.mjs

@@ -1,130 +0,0 @@
-import { createMcpResourceClient, makeDpopWWWAuthenticate } from "./index.mjs";
-import { DPOP_SIGNING_ALGORITHMS, isDpopBindingError, parseAccessTokenAuthorization } from "better-auth/oauth2";
-//#region src/client/adapters.ts
-const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
-function getProtectedResourceMetadataPath(resource) {
-	const resourceUrl = new URL(resource);
-	if (resourceUrl.origin === "null") return PROTECTED_RESOURCE_METADATA_PATH;
-	const resourcePath = resourceUrl.pathname === "/" ? "" : resourceUrl.pathname.replace(/\/$/, "");
-	return `${PROTECTED_RESOURCE_METADATA_PATH}${resourcePath}`;
-}
-function getProtectedResourceMetadataURL(resource) {
-	const resourceUrl = new URL(resource);
-	if (resourceUrl.origin === "null") throw new Error("MCP resource_metadata requires an origin-based resource URL");
-	return `${resourceUrl.origin}${getProtectedResourceMetadataPath(resource)}${resourceUrl.search}`;
-}
-function mcpAuthHono(options) {
-	const client = createMcpResourceClient(options);
-	const resourceMetadata = getProtectedResourceMetadataURL(options.resource ?? client.authURL);
-	const dpopChallenge = makeDpopWWWAuthenticate(options.dpop?.signingAlgorithms ?? DPOP_SIGNING_ALGORITHMS);
-	const unauthorized = (c, challenge, message) => {
-		c.header("WWW-Authenticate", challenge);
-		return c.json({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message
-			},
-			id: null
-		}, 401);
-	};
-	const middleware = async (c, next) => {
-		const authHeader = c.req.header("Authorization");
-		let session;
-		try {
-			session = await client.verifyRequest(c.req.raw);
-		} catch (error) {
-			if (isDpopBindingError(error)) return unauthorized(c, dpopChallenge, "Invalid or expired token");
-			throw error;
-		}
-		if (!session) {
-			const challenge = parseAccessTokenAuthorization(authHeader)?.scheme === "DPoP" || !!c.req.header("DPoP") ? dpopChallenge : `Bearer resource_metadata="${resourceMetadata}"`;
-			return unauthorized(c, challenge, authHeader ? "Invalid or expired token" : "Unauthorized: Authentication required");
-		}
-		c.set("mcpSession", session);
-		await next();
-	};
-	const discoveryRoutes = (app, serverURL) => {
-		const discoveryFn = client.discoveryHandler();
-		const protectedResourceFn = client.protectedResourceHandler(serverURL);
-		const protectedResourcePaths = /* @__PURE__ */ new Set([PROTECTED_RESOURCE_METADATA_PATH, getProtectedResourceMetadataPath(options.resource ?? client.authURL)]);
-		app.get("/.well-known/oauth-authorization-server", async (c) => {
-			const response = await discoveryFn(c.req.raw);
-			const data = await response.json().catch(() => ({ error: "Invalid response from auth server" }));
-			return c.json(data, response.status);
-		});
-		for (const path of protectedResourcePaths) app.get(path, async (c) => {
-			const response = await protectedResourceFn(c.req.raw);
-			const data = await response.json().catch(() => ({ error: "Invalid response from auth server" }));
-			return c.json(data, response.status);
-		});
-	};
-	return {
-		client,
-		middleware,
-		discoveryRoutes
-	};
-}
-function mcpAuthOfficial(options) {
-	const client = createMcpResourceClient(options);
-	return {
-		client,
-		handler: client.handler,
-		verifyToken: client.verifyToken
-	};
-}
-function mcpAuthMcpUse(config) {
-	const authURL = normalizeURL(config.authURL);
-	if (!authURL) throw new Error("Better Auth authURL is required. Pass authURL in config, e.g.: mcpAuthMcpUse({ authURL: 'http://localhost:3000/api/auth' })");
-	const client = createMcpResourceClient({ authURL });
-	return {
-		async verifyToken(token) {
-			const session = await client.verifyToken(token);
-			if (!session) throw new Error("Invalid or expired token");
-			return { payload: session };
-		},
-		getUserInfo(payload) {
-			if (config.getUserInfo) return config.getUserInfo(payload);
-			const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
-			return {
-				userId: payload.sub,
-				roles: [],
-				permissions: scopes,
-				scopes: payload.scope,
-				clientId: payload.azp ?? payload.client_id
-			};
-		},
-		getIssuer() {
-			return authURL;
-		},
-		getAuthEndpoint() {
-			return `${authURL}/oauth2/authorize`;
-		},
-		getTokenEndpoint() {
-			return `${authURL}/oauth2/token`;
-		},
-		getScopesSupported() {
-			return [
-				"openid",
-				"profile",
-				"email",
-				"offline_access"
-			];
-		},
-		getGrantTypesSupported() {
-			return ["authorization_code", "refresh_token"];
-		},
-		getMode() {
-			return "direct";
-		},
-		getRegistrationEndpoint() {
-			return `${authURL}/oauth2/register`;
-		}
-	};
-}
-function normalizeURL(url) {
-	if (!url || url.trim() === "") return void 0;
-	return url.endsWith("/") ? url.slice(0, -1) : url;
-}
-//#endregion
-export { mcpAuthHono, mcpAuthMcpUse, mcpAuthOfficial };

package/dist/client/index.d.mts

@@ -1,53 +0,0 @@
-import { VerifyAccessTokenRequestOptions } from "better-auth/oauth2";
-import { JWTPayload } from "jose";
-//#region src/client/index.d.ts
-interface McpResourceClientOptions {
-  authURL: string;
-  resource?: string;
-  allowedOrigin?: string;
-  fetch?: typeof globalThis.fetch;
-  dpop?: VerifyAccessTokenRequestOptions["dpop"];
-}
-interface McpSession extends JWTPayload {
-  sub?: string;
-  scope?: string;
-  client_id?: string;
-}
-interface NodeLikeRequest {
-  headers: Record<string, string | string[] | undefined> & {
-    get?: (name: string) => string | undefined;
-    authorization?: string;
-    host?: string;
-    "x-forwarded-proto"?: string;
-  };
-  get?: (name: string) => string | undefined;
-  method?: string;
-  originalUrl?: string;
-  protocol?: string;
-  url?: string;
-  mcpSession?: McpSession;
-}
-interface NodeLikeResponse {
-  set?: (name: string, value: string) => void;
-  get?: (name: string) => string | undefined;
-  setHeader?: (name: string, value: string) => void;
-  getHeader?: (name: string) => string | number | string[] | undefined;
-  status?: (code: number) => {
-    json: (body: unknown) => void;
-  };
-  writeHead?: (code: number, headers: Record<string, string>) => void;
-  end?: (body: string) => void;
-}
-interface McpResourceClient {
-  verifyToken: (token: string) => Promise<McpSession | null>;
-  verifyRequest: (req: Request) => Promise<McpSession | null>;
-  handler: (fn: (req: Request, session: McpSession) => Response | Promise<Response>) => (req: Request) => Promise<Response>;
-  discoveryHandler: () => (req: Request) => Promise<Response>;
-  protectedResourceHandler: (serverURL: string) => (req: Request) => Promise<Response>;
-  middleware: () => (req: NodeLikeRequest, res: NodeLikeResponse, next: () => void) => Promise<void>;
-  authURL: string;
-}
-declare function makeDpopWWWAuthenticate(algorithms: readonly string[]): string;
-declare function createMcpResourceClient(options: McpResourceClientOptions): McpResourceClient;
-//#endregion
-export { McpResourceClient, McpResourceClientOptions, McpSession, createMcpResourceClient, makeDpopWWWAuthenticate };

package/dist/client/index.mjs

@@ -1,267 +0,0 @@
-import { DPOP_SIGNING_ALGORITHMS, createInMemoryDpopReplayStore, enforceDpopBinding, getDpopJktFromPayload, isDpopBindingError, parseAccessTokenAuthorization } from "better-auth/oauth2";
-import { createRemoteJWKSet, jwtVerify } from "jose";
-//#region src/client/index.ts
-const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
-function buildCorsHeaders(authURL, allowedOrigin) {
-	let origin;
-	if (allowedOrigin) origin = allowedOrigin;
-	else try {
-		origin = new URL(authURL).origin;
-	} catch {
-		origin = authURL;
-	}
-	return {
-		"Access-Control-Allow-Origin": origin,
-		"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-		"Access-Control-Allow-Headers": "Content-Type, Authorization, DPoP",
-		"Access-Control-Expose-Headers": "WWW-Authenticate",
-		"Access-Control-Max-Age": "86400"
-	};
-}
-function getProtectedResourceMetadataURL(resource) {
-	const resourceUrl = new URL(resource);
-	if (resourceUrl.origin === "null") throw new Error("MCP resource_metadata requires an origin-based resource URL");
-	const resourcePath = resourceUrl.pathname === "/" ? "" : resourceUrl.pathname.replace(/\/$/, "");
-	return `${resourceUrl.origin}${PROTECTED_RESOURCE_METADATA_PATH}${resourcePath}${resourceUrl.search}`;
-}
-function makeWWWAuthenticate(authURL, resource) {
-	return `Bearer resource_metadata="${getProtectedResourceMetadataURL(resource ?? authURL)}"`;
-}
-function makeDpopWWWAuthenticate(algorithms) {
-	return `DPoP algs="${algorithms.map((alg) => alg.replace(/[\r\n"\\]/g, "")).join(" ")}"`;
-}
-function addExposeHeader(headers, headerName) {
-	const exposedHeaders = headers["Access-Control-Expose-Headers"];
-	if (!exposedHeaders) return {
-		...headers,
-		"Access-Control-Expose-Headers": headerName
-	};
-	const alreadyExposed = exposedHeaders.split(",").some((header) => header.trim().toLowerCase() === headerName.toLowerCase());
-	return {
-		...headers,
-		"Access-Control-Expose-Headers": alreadyExposed ? exposedHeaders : `${exposedHeaders}, ${headerName}`
-	};
-}
-function make401Response(wwwAuth, corsHeaders) {
-	return Response.json({
-		jsonrpc: "2.0",
-		error: {
-			code: -32e3,
-			message: "Unauthorized: Authentication required",
-			"www-authenticate": wwwAuth
-		},
-		id: null
-	}, {
-		status: 401,
-		headers: {
-			...addExposeHeader(corsHeaders, "WWW-Authenticate"),
-			"WWW-Authenticate": wwwAuth
-		}
-	});
-}
-function send401Node(res, wwwAuth, message, corsHeaders) {
-	const body = JSON.stringify({
-		jsonrpc: "2.0",
-		error: {
-			code: -32e3,
-			message
-		},
-		id: null
-	});
-	const existingExposedHeaders = res.get?.("Access-Control-Expose-Headers") ?? res.getHeader?.("Access-Control-Expose-Headers") ?? res.getHeader?.("access-control-expose-headers");
-	const headers = {
-		...addExposeHeader({
-			...corsHeaders,
-			...existingExposedHeaders ? { "Access-Control-Expose-Headers": Array.isArray(existingExposedHeaders) ? existingExposedHeaders.join(", ") : String(existingExposedHeaders) } : {}
-		}, "WWW-Authenticate"),
-		"WWW-Authenticate": wwwAuth
-	};
-	if (typeof res.set === "function") {
-		for (const [name, value] of Object.entries(headers)) res.set(name, value);
-		res.status?.(401).json(JSON.parse(body));
-	} else if (typeof res.writeHead === "function") {
-		res.writeHead(401, {
-			"Content-Type": "application/json",
-			...headers
-		});
-		res.end?.(body);
-	}
-}
-function createMcpResourceClient(options) {
-	const authURL = options.authURL.endsWith("/") ? options.authURL.slice(0, -1) : options.authURL;
-	const fetchFn = options.fetch ?? globalThis.fetch;
-	const corsHeaders = buildCorsHeaders(authURL, options.allowedOrigin);
-	const expectedAudience = options.resource ?? authURL;
-	const dpopReplayStore = options.dpop?.replayStore ?? createInMemoryDpopReplayStore();
-	const dpopSigningAlgorithms = options.dpop?.signingAlgorithms ?? DPOP_SIGNING_ALGORITHMS;
-	const selectChallenge = (authHeader, dpopHeaderPresent) => {
-		return parseAccessTokenAuthorization(authHeader)?.scheme === "DPoP" || dpopHeaderPresent ? makeDpopWWWAuthenticate(dpopSigningAlgorithms) : makeWWWAuthenticate(authURL, options.resource);
-	};
-	let discovery = null;
-	let jwks = null;
-	const loadVerifier = async () => {
-		if (discovery && jwks) return {
-			discovery,
-			jwks
-		};
-		const response = await fetchFn(`${authURL}/.well-known/oauth-authorization-server`);
-		if (!response.ok) throw new Error("Failed to fetch discovery metadata");
-		const metadata = await response.json();
-		if (!metadata.jwks_uri || !metadata.issuer) throw new Error("Discovery metadata missing jwks_uri or issuer");
-		discovery = {
-			issuer: metadata.issuer,
-			jwks_uri: metadata.jwks_uri
-		};
-		jwks = createRemoteJWKSet(new URL(metadata.jwks_uri));
-		return {
-			discovery,
-			jwks
-		};
-	};
-	const verifyJwtToken = async (token) => {
-		try {
-			const { discovery: meta, jwks: keySet } = await loadVerifier();
-			const { payload } = await jwtVerify(token, keySet, {
-				issuer: meta.issuer,
-				audience: expectedAudience
-			});
-			return payload;
-		} catch {
-			return null;
-		}
-	};
-	const verifyToken = async (token) => {
-		const session = await verifyJwtToken(token);
-		if (!session || getDpopJktFromPayload(session)) return null;
-		return session;
-	};
-	/**
-	* Verifies a request's access token and, when the token is DPoP-bound, its
-	* RFC 9449 sender-constraint. Returns `null` when there is no usable token
-	* or the JWT itself is invalid. Throws a `DpopBindingError` when a
-	* DPoP-bound token fails the binding check, so the caller can answer with a
-	* `WWW-Authenticate: DPoP` challenge rather than a bearer one.
-	*/
-	const verifyRequest = async (req) => {
-		const authorization = parseAccessTokenAuthorization(req.headers.get("Authorization"));
-		if (!authorization?.token || authorization.scheme === "Unknown") return null;
-		const session = await verifyJwtToken(authorization.token);
-		if (!session) return null;
-		await enforceDpopBinding({
-			payload: session,
-			authorization,
-			proofJwt: req.headers.get("DPoP"),
-			method: req.method,
-			url: req.url,
-			proofMaxAgeSeconds: options.dpop?.proofMaxAgeSeconds,
-			signingAlgorithms: dpopSigningAlgorithms,
-			replayStore: dpopReplayStore
-		});
-		return session;
-	};
-	const getHeader = (req, name) => {
-		const lower = name.toLowerCase();
-		const value = req.headers?.[lower] ?? req.headers?.[name] ?? req.headers?.get?.(name) ?? req.get?.(name);
-		if (Array.isArray(value)) return value[0];
-		return value;
-	};
-	const getNodeRequestUrl = (req) => {
-		const rawUrl = req.originalUrl ?? req.url ?? "/";
-		if (URL.canParse(rawUrl)) return rawUrl;
-		const fallbackUrl = new URL(authURL);
-		const host = getHeader(req, "host") ?? fallbackUrl.host;
-		return `${getHeader(req, "x-forwarded-proto")?.split(",")[0]?.trim() ?? req.protocol ?? fallbackUrl.protocol.replace(":", "")}://${host}${rawUrl.startsWith("/") ? rawUrl : `/${rawUrl}`}`;
-	};
-	const handler = (fn) => {
-		return async (req) => {
-			if (req.method === "OPTIONS") return new Response(null, {
-				status: 204,
-				headers: corsHeaders
-			});
-			let session;
-			try {
-				session = await verifyRequest(req);
-			} catch (error) {
-				if (isDpopBindingError(error)) return make401Response(makeDpopWWWAuthenticate(dpopSigningAlgorithms), corsHeaders);
-				throw error;
-			}
-			if (!session) return make401Response(selectChallenge(req.headers.get("Authorization"), req.headers.has("DPoP")), corsHeaders);
-			return fn(req, session);
-		};
-	};
-	const discoveryHandler = () => {
-		let cachedMetadata = null;
-		let cacheTime = 0;
-		const CACHE_TTL = 6e4;
-		return async (_req) => {
-			const now = Date.now();
-			if (cachedMetadata && now - cacheTime < CACHE_TTL) return Response.json(cachedMetadata, { headers: corsHeaders });
-			try {
-				const response = await fetchFn(`${authURL}/.well-known/oauth-authorization-server`);
-				if (!response.ok) return Response.json({ error: "Failed to fetch discovery metadata" }, {
-					status: 502,
-					headers: corsHeaders
-				});
-				cachedMetadata = await response.json();
-				cacheTime = now;
-				return Response.json(cachedMetadata, { headers: corsHeaders });
-			} catch {
-				return Response.json({ error: "Better Auth server unreachable" }, {
-					status: 502,
-					headers: corsHeaders
-				});
-			}
-		};
-	};
-	const protectedResourceHandler = (serverURL) => {
-		const metadata = {
-			resource: options.resource ?? new URL(serverURL).origin,
-			authorization_servers: [authURL],
-			bearer_methods_supported: ["header"],
-			dpop_signing_alg_values_supported: [...dpopSigningAlgorithms]
-		};
-		return async (_req) => {
-			return Response.json(metadata, { headers: corsHeaders });
-		};
-	};
-	const middleware = () => {
-		return async (req, res, next) => {
-			const authHeader = getHeader(req, "authorization");
-			const requestHeaders = new Headers();
-			if (authHeader) requestHeaders.set("Authorization", authHeader);
-			const dpop = getHeader(req, "dpop");
-			if (dpop) requestHeaders.set("DPoP", dpop);
-			const request = new Request(getNodeRequestUrl(req), {
-				method: req.method ?? "GET",
-				headers: requestHeaders
-			});
-			let session;
-			try {
-				session = await verifyRequest(request);
-			} catch (error) {
-				if (isDpopBindingError(error)) {
-					send401Node(res, makeDpopWWWAuthenticate(dpopSigningAlgorithms), "Invalid or expired token", corsHeaders);
-					return;
-				}
-				throw error;
-			}
-			if (!session) {
-				send401Node(res, selectChallenge(authHeader, !!getHeader(req, "dpop")), authHeader ? "Invalid or expired token" : "Unauthorized: Authentication required", corsHeaders);
-				return;
-			}
-			req.mcpSession = session;
-			next();
-		};
-	};
-	return {
-		verifyToken,
-		verifyRequest,
-		handler,
-		discoveryHandler,
-		protectedResourceHandler,
-		middleware,
-		authURL
-	};
-}
-//#endregion
-export { createMcpResourceClient, makeDpopWWWAuthenticate };