refactor(server): derive scope-challenge resource_metadata from AuthInfo

Rework the scope-challenge configuration surface so the RFC 9728 metadata
URL is configured exactly once and every WWW-Authenticate header a server
emits is built by one formatter:

- Scope-challenge 403s now build their WWW-Authenticate header via the
  bearer-auth formatter (buildWwwAuthenticateHeader, now exported from
  bearerAuth.ts), giving identical parameter order and quoting to the
  bearer-auth 401/403 answers. The formatter now quotes the scope and
  resource_metadata parameter values too. The JSON-RPC error body is
  unchanged.
- AuthInfo gains an optional resourceMetadataUrl field; requireBearerAuth /
  verifyBearerToken stamp their configured resourceMetadataUrl onto the
  AuthInfo they return, so the URL flows inward with the verified token.
  The scope preflight reads it from there, falls back to the well-known
  location for the token's RFC 8707 resource identifier, and omits the
  parameter otherwise (matching the bearer-auth optional precedent).
- Remove ScopeChallengeConfig and the scopeChallenge option from
  createMcpHandler and the Streamable HTTP transports: the preflight is
  active whenever a registered primitive carries a scopeChallenge callback,
  fixing the silent no-op when the handler-level config was omitted.
- Update the authorization guide, examples, conformance server, tests, and
  the changeset for the single-config shape; add coverage for the
  stamped-URL flow, the RFC 8707 fallback, and parameter omission.

Author: claude

.changeset/scope-challenge-server.md

@@ -10,4 +10,13 @@ exact scope set for an `insufficient_scope` response. `requireScopes` provides a
 small helper for static all-of checks.
 
 `createMcpHandler` and Streamable HTTP transports return HTTP 403 with an
-`insufficient_scope` challenge before handler execution or SSE setup.
+`insufficient_scope` challenge before handler execution or SSE setup. The
+preflight is active whenever a registered primitive carries a `scopeChallenge`
+callback — there is no handler- or transport-level configuration. The
+challenge's `WWW-Authenticate` header is built by the same formatter as the
+bearer-auth 401/403 answers, and its `resource_metadata` parameter is derived
+from the verified `AuthInfo`: `requireBearerAuth` / `verifyBearerToken` now
+stamp their configured `resourceMetadataUrl` onto the `AuthInfo` they return
+(new optional `AuthInfo.resourceMetadataUrl` field), with a fallback to the
+well-known location for the token's RFC 8707 `resource` identifier; the
+parameter is omitted when neither is available.

docs/serving/authorization.md

@@ -34,13 +34,7 @@ const auth = requireBearerAuth({
 });
 
 const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts: ['api.example.com'] });
-const node = toNodeHandler(
-    createMcpHandler(buildServer, {
-        scopeChallenge: {
-            resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
-        }
-    })
-);
+const node = toNodeHandler(createMcpHandler(buildServer));
 app.all('/mcp', auth, (req, res) => void node(req, res, req.body));
 ```
 
@@ -125,7 +119,9 @@ The per-request factory itself receives the same value as `ctx.authInfo`, so it
 
 ## Enforce per-operation scopes
 
-`requiredScopes` gates the whole endpoint. For scope step-up on an individual tool call, resource read, or prompt retrieval, set `scopeChallenge` on its registration and configure `scopeChallenge.resourceMetadataUrl` on `createMcpHandler` (or a directly constructed Streamable HTTP transport). The callback receives the full parsed request and verified `authInfo`. Return `undefined` to continue, or return the exact, complete scope set to send `403 insufficient_scope` before invocation or SSE. Throwing or rejecting fails closed.
+`requiredScopes` gates the whole endpoint. For scope step-up on an individual tool call, resource read, or prompt retrieval, set `scopeChallenge` on its registration — no handler or transport configuration is needed. The callback receives the full parsed request and verified `authInfo`. Return `undefined` to continue, or return the exact, complete scope set to send `403 insufficient_scope` before invocation or SSE. Throwing or rejecting fails closed.
+
+The challenge's `WWW-Authenticate` header is built by the same formatter as `requireBearerAuth`'s own `401`/`403` answers, and its `resource_metadata` parameter comes from the verified `AuthInfo`: the gate stamps its configured `resourceMetadataUrl` onto the `AuthInfo` it returns, so the metadata URL is configured exactly once — on `requireBearerAuth`. Without a stamped value the parameter falls back to the well-known location for the token's RFC 8707 `resource` identifier, or is omitted.
 
 Use `requireScopes` for a static exact all-of check. Use a callback when the required scope set depends on the request:
 
@@ -172,5 +168,5 @@ The callback runs before the primitive's input schema is validated or transforme
 - `requireBearerAuth` plus a `verifyAccessToken` you write turn an Express-mounted MCP route into an OAuth resource server; the SDK never issues tokens.
 - Missing, invalid, or expired tokens get `401 invalid_token`; a token missing a `requiredScopes` entry gets `403 insufficient_scope`; both carry a `WWW-Authenticate: Bearer` challenge.
 - `mcpAuthMetadataRouter` publishes the RFC 9728 document that challenge points at, plus a mirror of the AS metadata.
-- Verified auth flows `req.auth` → `ctx.http.authInfo`; per-operation callbacks can trigger HTTP `403` scope step-up before invocation.
+- Verified auth flows `req.auth` → `ctx.http.authInfo`; per-operation callbacks can trigger HTTP `403` scope step-up before invocation, advertising the metadata URL the gate stamped onto `AuthInfo`.
 - The v1 Authorization Server helpers are frozen in `@modelcontextprotocol/server-legacy/auth`.

examples/guides/serving/authorization.examples.ts

@@ -35,13 +35,7 @@ const auth = requireBearerAuth({
 });
 
 const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts: ['api.example.com'] });
-const node = toNodeHandler(
-    createMcpHandler(buildServer, {
-        scopeChallenge: {
-            resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
-        }
-    })
-);
+const node = toNodeHandler(createMcpHandler(buildServer));
 app.all('/mcp', auth, (req, res) => void node(req, res, req.body));
 //#endregion requireBearerAuth_basic
 

packages/core-internal/src/types/types.ts

@@ -751,6 +751,19 @@ export interface AuthInfo {
      */
     resource?: URL;
 
+    /**
+     * URL of the RFC 9728 Protected Resource Metadata document for the
+     * resource server that accepted this token.
+     *
+     * The bearer-auth helpers stamp their configured `resourceMetadataUrl`
+     * here when verification succeeds, so challenge responses built after
+     * authentication (for example per-operation `insufficient_scope` scope
+     * challenges) can advertise the same document as the authentication
+     * gate's own challenges without separate configuration. Verifiers may
+     * also populate it directly; a verifier-set value wins.
+     */
+    resourceMetadataUrl?: string;
+
     /**
      * Additional data associated with the token.
      * This field should be used for any additional data that needs to be attached to the auth info.

packages/server/src/index.ts

@@ -65,7 +65,7 @@ export { InMemoryServerEventBus } from './server/serverEventBus';
 // StdioServerTransport and the serveStdio entry are exported from the './stdio' subpath — server stdio
 // has only type-level Node imports (erased at compile time), but matching the client's `./stdio` subpath
 // gives consumers a consistent shape across packages.
-export type { ScopeChallenge, ScopeChallengeConfig, ScopeChallengeHandler } from './server/scopeChallenge';
+export type { ScopeChallenge, ScopeChallengeHandler } from './server/scopeChallenge';
 export { requireScopes } from './server/scopeChallenge';
 export type {
     EventId,

packages/server/src/server/createMcpHandler.ts

@@ -64,8 +64,7 @@ import { createListenRouter, DEFAULT_MAX_SUBSCRIPTIONS } from './listenRouter';
 import { McpServer } from './mcp';
 import type { PerRequestResponseMode } from './perRequestTransport';
 import { DEFAULT_MAX_REQUEST_BODY_SIZE, readRequestBody, requestBodyTooLargeMessage, resolveMaxRequestBodySize } from './requestBody';
-import type { ScopeChallengeConfig } from './scopeChallenge';
-import { createScopeChallengeResponse, findScopeChallenge } from './scopeChallenge';
+import { createScopeChallengeResponse, findScopeChallenge, scopeChallengeResourceMetadataUrl } from './scopeChallenge';
 import type { Server } from './server';
 import { installModernOnlyHandlers, seedClientIdentityFromEnvelope, serverIdentityOf } from './server';
 import type { ServerEventBus, ServerNotifier } from './serverEventBus';
@@ -214,8 +213,6 @@ export interface CreateMcpHandlerOptions {
      * @default 4194304 (4 MiB)
      */
     maxRequestBodySize?: number;
-    /** Enables per-operation OAuth scope challenges. */
-    scopeChallenge?: ScopeChallengeConfig;
 }
 
 /**
@@ -327,8 +324,7 @@ function createLegacyStatelessFallback(
     factory: McpServerFactory,
     onerror?: (error: Error) => void,
     keepAliveMs?: number,
-    maxRequestBodySize?: number,
-    scopeChallenge?: ScopeChallengeConfig
+    maxRequestBodySize?: number
 ): LegacyHttpHandler {
     return async (request, options) => {
         if (request.method.toUpperCase() !== 'POST') {
@@ -343,8 +339,7 @@ function createLegacyStatelessFallback(
             const transport = new WebStandardStreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
                 ...(keepAliveMs !== undefined && { keepAliveMs }),
-                ...(maxRequestBodySize !== undefined && { maxRequestBodySize }),
-                ...(scopeChallenge !== undefined && { scopeChallenge })
+                ...(maxRequestBodySize !== undefined && { maxRequestBodySize })
             });
             await product.connect(transport);
 
@@ -721,9 +716,7 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
     // The default posture is the stateless fallback; 'reject' is the only way
     // to turn legacy serving off (modern-only strict).
     const legacyHandler: LegacyHttpHandler | undefined =
-        legacy === 'reject'
-            ? undefined
-            : createLegacyStatelessFallback(factory, reportError, options.keepAliveMs, maxRequestBodySize, options.scopeChallenge);
+        legacy === 'reject' ? undefined : createLegacyStatelessFallback(factory, reportError, options.keepAliveMs, maxRequestBodySize);
 
     async function serveModern(route: InboundModernRoute, request: Request, authInfo: AuthInfo | undefined): Promise<Response> {
         const claimedRevision = route.classification.revision;
@@ -839,13 +832,18 @@ export function createMcpHandler(factory: McpServerFactory, options: CreateMcpHa
             }
         }
 
-        // Run scope preflight after Mcp-Param headers have been checked against the body.
-        if (route.messageKind === 'request' && product instanceof McpServer && options.scopeChallenge !== undefined) {
+        // Run scope preflight after Mcp-Param headers have been checked against
+        // the body. Active whenever the factory's instance registers a
+        // per-primitive scopeChallenge callback — no handler-level
+        // configuration exists: the challenge's resource_metadata parameter is
+        // derived from the verified AuthInfo (stamped by the bearer-auth gate,
+        // or the token's RFC 8707 resource identifier) and omitted otherwise.
+        if (route.messageKind === 'request' && product instanceof McpServer) {
             try {
                 const result = await findScopeChallenge([route.message], authInfo, context => product.resolveScopeChallenge(context));
                 if (result !== undefined) {
                     void product.close().catch(reportError);
-                    return createScopeChallengeResponse(options.scopeChallenge, result.challenge, result.requestId);
+                    return createScopeChallengeResponse(result.challenge, result.requestId, scopeChallengeResourceMetadataUrl(authInfo));
                 }
             } catch (error) {
                 void product.close().catch(reportError);

packages/server/src/server/middleware/bearerAuth.ts

@@ -50,6 +50,12 @@ export interface BearerAuthOptions {
      *
      * Typically built with `getOAuthProtectedResourceMetadataUrl`, exported
      * from this package.
+     *
+     * When verification succeeds the value is also stamped onto the returned
+     * {@link AuthInfo} (`authInfo.resourceMetadataUrl`, unless the verifier
+     * already set one), so challenges built after authentication — such as
+     * per-operation `insufficient_scope` scope challenges — advertise the
+     * same document without being configured separately.
      */
     resourceMetadataUrl?: string;
 }
@@ -62,18 +68,27 @@ function headerQuotedValue(value: string): string {
     return value.replaceAll(/[\\"]/g, String.raw`\$&`).replaceAll(/[^\u0020-\u007E]/g, ' ');
 }
 
-function buildWwwAuthenticateHeader(
+/**
+ * Build a `WWW-Authenticate: Bearer …` challenge header value (RFC 6750).
+ *
+ * The single formatter behind every challenge this package emits — the
+ * bearer-auth 401/403 answers and the per-operation scope-challenge 403 — so
+ * all challenges from one server agree on parameter order and quoting. Every
+ * parameter value is emitted as an HTTP quoted-string with `\` and `"`
+ * escaped and non-printable characters replaced.
+ */
+export function buildWwwAuthenticateHeader(
     errorCode: string,
     description: string,
-    requiredScopes: string[],
+    requiredScopes: readonly string[],
     resourceMetadataUrl: string | undefined
 ): string {
     let header = `Bearer error="${headerQuotedValue(errorCode)}", error_description="${headerQuotedValue(description)}"`;
     if (requiredScopes.length > 0) {
-        header += `, scope="${requiredScopes.join(' ')}"`;
+        header += `, scope="${headerQuotedValue(requiredScopes.join(' '))}"`;
     }
     if (resourceMetadataUrl) {
-        header += `, resource_metadata="${resourceMetadataUrl}"`;
+        header += `, resource_metadata="${headerQuotedValue(resourceMetadataUrl)}"`;
     }
     return header;
 }
@@ -120,6 +135,14 @@ export async function verifyBearerToken(authorizationHeader: string | null | und
         throw new OAuthError(OAuthErrorCode.InvalidToken, 'Token has expired');
     }
 
+    // Hand the gate's discovery configuration inward with the verified token,
+    // so challenges built after authentication (per-operation scope
+    // challenges) advertise the same metadata document. A verifier-set value
+    // wins over the gate's configuration.
+    if (options.resourceMetadataUrl !== undefined && authInfo.resourceMetadataUrl === undefined) {
+        return { ...authInfo, resourceMetadataUrl: options.resourceMetadataUrl };
+    }
+
     return authInfo;
 }
 

packages/server/src/server/scopeChallenge.ts

@@ -1,5 +1,8 @@
 import type { AuthInfo, JSONRPCRequest, RequestId } from '@modelcontextprotocol/core-internal';
 
+import { buildWwwAuthenticateHeader } from './middleware/bearerAuth';
+import { getOAuthProtectedResourceMetadataUrl } from './middleware/oauthMetadata';
+
 /** OAuth scopes to request before handling an MCP request. */
 export interface ScopeChallenge {
     /** The exact, complete scope set to include in the challenge. Each scope must satisfy the OAuth `scope-token` grammar. */
@@ -14,12 +17,6 @@ export type ScopeChallengeHandler = (context: {
     authInfo?: AuthInfo;
 }) => ScopeChallenge | undefined | Promise<ScopeChallenge | undefined>;
 
-/** Configuration for HTTP `insufficient_scope` challenges. */
-export interface ScopeChallengeConfig {
-    /** URL of the RFC 9728 protected resource metadata. */
-    resourceMetadataUrl: string;
-}
-
 /** @internal */
 export function supportsScopeChallengeResolver(
     transport: unknown
@@ -90,22 +87,41 @@ export async function findScopeChallenge(
     return undefined;
 }
 
-function quoteAuthParam(value: string): string {
-    return value.replaceAll('\\', '\\\\').replaceAll('"', String.raw`\"`);
+/**
+ * The RFC 9728 Protected Resource Metadata URL to advertise on a scope
+ * challenge, derived from the verified {@link AuthInfo}: the URL the
+ * authentication gate stamped (`authInfo.resourceMetadataUrl`, set by the
+ * bearer-auth helpers from their `resourceMetadataUrl` option), falling back
+ * to the well-known location for the token's RFC 8707 `resource` identifier,
+ * or `undefined` when neither is available (the `resource_metadata` parameter
+ * is then omitted, matching the bearer-auth challenges).
+ *
+ * @internal
+ */
+export function scopeChallengeResourceMetadataUrl(authInfo: AuthInfo | undefined): string | undefined {
+    if (authInfo?.resourceMetadataUrl !== undefined) {
+        return authInfo.resourceMetadataUrl;
+    }
+    if (authInfo?.resource !== undefined) {
+        return getOAuthProtectedResourceMetadataUrl(authInfo.resource);
+    }
+    return undefined;
 }
 
 /** @internal */
 export function createScopeChallengeResponse(
-    config: ScopeChallengeConfig,
     challenge: ScopeChallenge,
-    responseId: RequestId | null
+    responseId: RequestId | null,
+    resourceMetadataUrl: string | undefined
 ): Response {
-    const wwwAuthenticate =
-        'Bearer' +
-        ' error="insufficient_scope"' +
-        `, scope="${quoteAuthParam(challenge.scopes.join(' '))}"` +
-        `, resource_metadata="${quoteAuthParam(config.resourceMetadataUrl)}"` +
-        (challenge.errorDescription === undefined ? '' : `, error_description="${quoteAuthParam(challenge.errorDescription)}"`);
+    // One formatter for every challenge this package emits: identical
+    // parameter order and quoting to the bearer-auth 401/403 answers.
+    const wwwAuthenticate = buildWwwAuthenticateHeader(
+        'insufficient_scope',
+        challenge.errorDescription ?? 'Insufficient scope',
+        challenge.scopes,
+        resourceMetadataUrl
+    );
 
     return Response.json(
         {

packages/server/src/server/streamableHttp.ts

@@ -20,8 +20,8 @@ import {
 } from '@modelcontextprotocol/core-internal';
 
 import { MAX_BATCH_SIZE, readRequestBody, requestBodyTooLargeMessage, resolveMaxRequestBodySize } from './requestBody';
-import type { ScopeChallengeConfig, ScopeChallengeHandler } from './scopeChallenge';
-import { createScopeChallengeResponse, findScopeChallenge } from './scopeChallenge';
+import type { ScopeChallengeHandler } from './scopeChallenge';
+import { createScopeChallengeResponse, findScopeChallenge, scopeChallengeResourceMetadataUrl } from './scopeChallenge';
 import { armSseKeepAlive, DEFAULT_SSE_KEEP_ALIVE_MS } from './sseKeepAlive';
 
 export type StreamId = string;
@@ -179,9 +179,6 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
      * @default {@linkcode SUPPORTED_PROTOCOL_VERSIONS}
      */
     supportedProtocolVersions?: string[];
-
-    /** Enables OAuth scope challenges. `McpServer.connect()` supplies the resolver. */
-    scopeChallenge?: ScopeChallengeConfig;
 }
 
 /**
@@ -272,7 +269,6 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
     private _supportedProtocolVersions: string[];
     private _keepAliveMs: number;
     private _maxRequestBodySize: number;
-    private _scopeChallenge?: ScopeChallengeConfig;
     private _scopeChallengeResolver?: ScopeChallengeHandler;
 
     sessionId?: string;
@@ -293,7 +289,6 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
         this._supportedProtocolVersions = options.supportedProtocolVersions ?? SUPPORTED_PROTOCOL_VERSIONS;
         this._keepAliveMs = options.keepAliveMs ?? DEFAULT_SSE_KEEP_ALIVE_MS;
         this._maxRequestBodySize = resolveMaxRequestBodySize(options.maxRequestBodySize);
-        this._scopeChallenge = options.scopeChallenge;
     }
 
     private startKeepAlive(
@@ -366,14 +361,22 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
     }
 
     private async _checkScopeChallenge(messages: JSONRPCMessage[], authInfo?: AuthInfo): Promise<Response | undefined> {
-        if (!this._scopeChallenge || !this._scopeChallengeResolver) {
+        // Active whenever a connected McpServer supplied a resolver (it
+        // resolves per-primitive scopeChallenge callbacks); the challenge's
+        // resource_metadata parameter is derived from the verified AuthInfo
+        // and omitted when unavailable.
+        if (!this._scopeChallengeResolver) {
             return undefined;
         }
         const requests: JSONRPCRequest[] = messages.filter(message => isJSONRPCRequest(message));
         const result = await findScopeChallenge(requests, authInfo, this._scopeChallengeResolver);
         return result === undefined
             ? undefined
-            : createScopeChallengeResponse(this._scopeChallenge, result.challenge, messages.length === 1 ? result.requestId : null);
+            : createScopeChallengeResponse(
+                  result.challenge,
+                  messages.length === 1 ? result.requestId : null,
+                  scopeChallengeResourceMetadataUrl(authInfo)
+              );
     }
 
     /**