feat(server): runtime-neutral OAuth discovery serving for web-standard hosts

The RFC 9728 Protected Resource Metadata and RFC 8414 Authorization Server
metadata documents could only be served through the Express metadata router,
so fetch-handler hosts (Cloudflare Workers, Deno, Bun, Hono) hand-rolled the
well-known routes, CORS, and method handling. The core moves to
@modelcontextprotocol/server as oauthMetadataResponse (a Response-or-undefined
matcher in the style of hostHeaderValidationResponse), built on the exported
buildOAuthProtectedResourceMetadata, with getOAuthProtectedResourceMetadataUrl
now defined here. The Express router adapts the same core with unchanged
behavior, proven by its untouched test suite.

The neutral core improves on the Express quirks where green-field allows:
matching happens before validation so unmatched traffic always falls through
(a misconfigured issuer surfaces on the discovery routes, or at startup via
an eager buildOAuthProtectedResourceMetadata call, never as a whole-server
outage), a single trailing slash is tolerated, HEAD is served per RFC 9110,
reflected CORS preflights carry Vary, and the insecure-issuer escape hatch is
an explicit dangerouslyAllowInsecureIssuerUrl option instead of a
module-scope environment read.

Author: felixweinberger

.changeset/web-standard-oauth-metadata.md

@@ -0,0 +1,17 @@
+---
+'@modelcontextprotocol/server': minor
+'@modelcontextprotocol/express': patch
+---
+
+Add runtime-neutral OAuth discovery serving to `@modelcontextprotocol/server`:
+`oauthMetadataResponse` serves the RFC 9728 Protected Resource Metadata and
+RFC 8414 Authorization Server metadata documents from web-standard
+`fetch(request)` hosts, built on the exported
+`buildOAuthProtectedResourceMetadata`, with
+`getOAuthProtectedResourceMetadataUrl` now defined here. The Express metadata
+router adapts the same core and is unchanged in behavior; the insecure-issuer
+escape hatch is an explicit `dangerouslyAllowInsecureIssuerUrl` option in the
+neutral core instead of a module-scope environment read. The web-standard
+matcher validates lazily so unmatched traffic always falls through, tolerates
+a trailing slash, supports HEAD, and marks reflected CORS preflights with
+`Vary`.

docs/migration/upgrade-to-v2.md

@@ -397,7 +397,9 @@ A few transports need a decision the codemod can't make:
   `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`)
   → `@modelcontextprotocol/express`; the runtime-neutral core (`requireBearerAuth`
   for web-standard `fetch` hosts, `verifyBearerToken`, `bearerAuthChallengeResponse`,
-  `OAuthTokenVerifier`) is also exported from `@modelcontextprotocol/server`. Authorization Server helpers (`mcpAuthRouter`,
+  `OAuthTokenVerifier`, and the discovery serving `oauthMetadataResponse` /
+  `buildOAuthProtectedResourceMetadata` / `getOAuthProtectedResourceMetadataUrl`)
+  is also exported from `@modelcontextprotocol/server`. Authorization Server helpers (`mcpAuthRouter`,
   `OAuthServerProvider`, `ProxyOAuthServerProvider`, `allowedMethods`,
   `authenticateClient`, `metadataHandler`, `createOAuthMetadata`,
   `authorizationHandler` / `tokenHandler` / `revocationHandler` /

docs/serving/authorization.md

@@ -89,6 +89,16 @@ app.use(mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl: mcpServerUrl }
 
 The router mounts two well-known routes: `/.well-known/oauth-protected-resource/mcp` — the path-aware RFC 9728 location, the same string `getOAuthProtectedResourceMetadataUrl(mcpServerUrl)` put into the challenge — and `/.well-known/oauth-authorization-server`, a mirror of `oauthMetadata` for clients that probe your origin directly. An unauthenticated client follows `401` → `resource_metadata` → `authorization_servers` to find your AS, obtains a token, and retries.
 
+On a web-standard host, `oauthMetadataResponse` from `@modelcontextprotocol/server` serves the same two documents from a `fetch(request)` handler — it returns the matched document `Response` (with permissive CORS and `405` handling) or `undefined` to fall through to your own routing:
+
+```ts source="../../examples/guides/serving/authorization.examples.ts#oauthMetadataResponse_webStandard"
+import { oauthMetadataResponse } from '@modelcontextprotocol/server';
+
+async function webStandardFetch(request: Request): Promise<Response> {
+    return oauthMetadataResponse(request, { oauthMetadata, resourceServerUrl: mcpServerUrl }) ?? serveMcp(request);
+}
+```
+
 ## Read the caller in your handlers
 
 `requireBearerAuth` attaches the verified `AuthInfo` to `req.auth`, `toNodeHandler` forwards it, and tool handlers inside `buildServer` read it as `ctx.http.authInfo` — the exact object your verifier returned.

examples/guides/serving/authorization.examples.ts

@@ -83,3 +83,13 @@ function buildServer(): McpServer {
 
     return server;
 }
+
+//#region oauthMetadataResponse_webStandard
+import { oauthMetadataResponse } from '@modelcontextprotocol/server';
+
+async function webStandardFetch(request: Request): Promise<Response> {
+    return oauthMetadataResponse(request, { oauthMetadata, resourceServerUrl: mcpServerUrl }) ?? serveMcp(request);
+}
+//#endregion oauthMetadataResponse_webStandard
+
+declare function serveMcp(request: Request): Promise<Response>;

packages/middleware/express/src/auth/metadataRouter.ts

@@ -1,5 +1,9 @@
-import type { OAuthMetadata, OAuthProtectedResourceMetadata } from '@modelcontextprotocol/server';
-import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
+import type {
+    AuthMetadataOptions as NeutralAuthMetadataOptions,
+    OAuthMetadata,
+    OAuthProtectedResourceMetadata
+} from '@modelcontextprotocol/server';
+import { buildOAuthProtectedResourceMetadata, OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
 import cors from 'cors';
 import type { RequestHandler, Router } from 'express';
 import express from 'express';
@@ -12,19 +16,6 @@ if (allowInsecureIssuerUrl) {
     console.warn('MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL is enabled - HTTP issuer URLs are allowed. Do not use in production.');
 }
 
-function checkIssuerUrl(issuer: URL): void {
-    // RFC 8414 technically does not permit a localhost HTTPS exemption, but it is necessary for local testing.
-    if (issuer.protocol !== 'https:' && issuer.hostname !== 'localhost' && issuer.hostname !== '127.0.0.1' && !allowInsecureIssuerUrl) {
-        throw new Error('Issuer URL must be HTTPS');
-    }
-    if (issuer.hash) {
-        throw new Error(`Issuer URL must not have a fragment: ${issuer}`);
-    }
-    if (issuer.search) {
-        throw new Error(`Issuer URL must not have a query string: ${issuer}`);
-    }
-}
-
 /**
  * Express middleware that rejects HTTP methods not in the supplied allow-list
  * with a 405 Method Not Allowed and an OAuth-style error body. Used by
@@ -60,39 +51,14 @@ export function metadataHandler(metadata: OAuthMetadata | OAuthProtectedResource
 }
 
 /**
- * Options for {@link mcpAuthMetadataRouter}.
+ * Options for {@link mcpAuthMetadataRouter}. Same shape as the runtime-neutral
+ * `AuthMetadataOptions` in `@modelcontextprotocol/server`, except the
+ * insecure-issuer escape hatch is controlled here by the
+ * `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` environment variable instead of
+ * an option.
  */
-export interface AuthMetadataOptions {
-    /**
-     * Authorization Server metadata (RFC 8414) for the AS this MCP server
-     * relies on. Served at `/.well-known/oauth-authorization-server` so
-     * legacy clients that probe the resource origin still discover the AS.
-     */
-    oauthMetadata: OAuthMetadata;
-
-    /**
-     * The public URL of this MCP server, used as the `resource` value in the
-     * Protected Resource Metadata document. Any path component is reflected
-     * in the well-known route per RFC 9728.
-     */
-    resourceServerUrl: URL;
-
-    /**
-     * Optional documentation URL advertised as `resource_documentation`.
-     */
-    serviceDocumentationUrl?: URL;
-
-    /**
-     * Optional list of scopes this MCP server understands, advertised as
-     * `scopes_supported`.
-     */
-    scopesSupported?: string[];
-
-    /**
-     * Optional human-readable name advertised as `resource_name`.
-     */
-    resourceName?: string;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AuthMetadataOptions extends Omit<NeutralAuthMetadataOptions, 'dangerouslyAllowInsecureIssuerUrl'> {}
 
 /**
  * Builds an Express router that serves the two OAuth discovery documents an
@@ -101,7 +67,7 @@ export interface AuthMetadataOptions {
  *  - `/.well-known/oauth-protected-resource[/<path>]` — RFC 9728 Protected
  *    Resource Metadata, derived from the supplied options.
  *  - `/.well-known/oauth-authorization-server` — RFC 8414 Authorization
- *    Server Metadata, passed through verbatim from {@link AuthMetadataOptions.oauthMetadata}.
+ *    Server Metadata, passed through verbatim from the supplied `oauthMetadata`.
  *
  * Mount this router at the application root:
  *
@@ -114,18 +80,19 @@ export interface AuthMetadataOptions {
  * so unauthenticated clients can discover the AS from the 401 challenge.
  */
 export function mcpAuthMetadataRouter(options: AuthMetadataOptions): Router {
-    checkIssuerUrl(new URL(options.oauthMetadata.issuer));
+    // Explicit fields, not a spread: a wider object cannot smuggle in (or be
+    // clobbered on) the insecure-issuer flag — here it comes only from the env.
+    const protectedResourceMetadata = buildOAuthProtectedResourceMetadata({
+        oauthMetadata: options.oauthMetadata,
+        resourceServerUrl: options.resourceServerUrl,
+        serviceDocumentationUrl: options.serviceDocumentationUrl,
+        scopesSupported: options.scopesSupported,
+        resourceName: options.resourceName,
+        dangerouslyAllowInsecureIssuerUrl: allowInsecureIssuerUrl
+    });
 
     const router = express.Router();
 
-    const protectedResourceMetadata: OAuthProtectedResourceMetadata = {
-        resource: options.resourceServerUrl.href,
-        authorization_servers: [options.oauthMetadata.issuer],
-        scopes_supported: options.scopesSupported,
-        resource_name: options.resourceName,
-        resource_documentation: options.serviceDocumentationUrl?.href
-    };
-
     // Serve PRM at the path-aware URL per RFC 9728 §3.1.
     const rsPath = new URL(options.resourceServerUrl.href).pathname;
     router.use(`/.well-known/oauth-protected-resource${rsPath === '/' ? '' : rsPath}`, metadataHandler(protectedResourceMetadata));
@@ -136,18 +103,5 @@ export function mcpAuthMetadataRouter(options: AuthMetadataOptions): Router {
     return router;
 }
 
-/**
- * Builds the RFC 9728 Protected Resource Metadata URL for a given MCP server
- * URL by inserting `/.well-known/oauth-protected-resource` ahead of the path.
- *
- * @example
- * ```ts
- * getOAuthProtectedResourceMetadataUrl(new URL('https://api.example.com/mcp'))
- * // → 'https://api.example.com/.well-known/oauth-protected-resource/mcp'
- * ```
- */
-export function getOAuthProtectedResourceMetadataUrl(serverUrl: URL): string {
-    const u = new URL(serverUrl.href);
-    const rsPath = u.pathname && u.pathname !== '/' ? u.pathname : '';
-    return new URL(`/.well-known/oauth-protected-resource${rsPath}`, u).href;
-}
+// Re-exported from the runtime-neutral home in @modelcontextprotocol/server.
+export { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/server';

packages/server/src/index.ts

@@ -39,6 +39,14 @@ export type { BearerAuthOptions, OAuthTokenVerifier } from './server/middleware/
 export { bearerAuthChallengeResponse, requireBearerAuth, verifyBearerToken } from './server/middleware/bearerAuth';
 export type { HostHeaderValidationResult } from './server/middleware/hostHeaderValidation';
 export { hostHeaderValidationResponse, localhostAllowedHostnames, validateHostHeader } from './server/middleware/hostHeaderValidation';
+// OAuth discovery documents (RFC 9728 / RFC 8414) for web-standard hosts; the
+// Express metadata router in @modelcontextprotocol/express adapts the same core.
+export type { AuthMetadataOptions } from './server/middleware/oauthMetadata';
+export {
+    buildOAuthProtectedResourceMetadata,
+    getOAuthProtectedResourceMetadataUrl,
+    oauthMetadataResponse
+} from './server/middleware/oauthMetadata';
 export type { OriginValidationResult } from './server/middleware/originValidation';
 export { localhostAllowedOrigins, originValidationResponse, validateOriginHeader } from './server/middleware/originValidation';
 export type { PerRequestHTTPServerTransportOptions, PerRequestMessageExtra, PerRequestResponseMode } from './server/perRequestTransport';

packages/server/src/server/middleware/oauthMetadata.examples.ts

@@ -0,0 +1,23 @@
+/**
+ * Type-checked examples for `oauthMetadata.ts`.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import type { AuthMetadataOptions } from './oauthMetadata';
+import { oauthMetadataResponse } from './oauthMetadata';
+
+/**
+ * Example: serving the discovery documents from a fetch handler.
+ */
+function oauthMetadataResponse_fetchHandler(options: AuthMetadataOptions, serveMcp: (request: Request) => Promise<Response>) {
+    //#region oauthMetadataResponse_fetchHandler
+    async function fetchHandler(request: Request): Promise<Response> {
+        return oauthMetadataResponse(request, options) ?? serveMcp(request);
+    }
+    //#endregion oauthMetadataResponse_fetchHandler
+    return fetchHandler;
+}