feat(compat): restore Resource-Server auth glue in @modelcontextprotocol/express

Adds first-class (not deprecated) OAuth Resource-Server helpers to the
Express adapter, restoring the v1 src/server/auth pieces that an MCP
server needs when it delegates to an external Authorization Server:

- requireBearerAuth: Express middleware that validates a Bearer token
  via a pluggable OAuthTokenVerifier, attaches AuthInfo to req.auth,
  and on failure emits RFC 6750 WWW-Authenticate challenges (with
  optional resource_metadata pointer per RFC 9728).
- mcpAuthMetadataRouter: serves RFC 9728 Protected Resource Metadata at
  /.well-known/oauth-protected-resource[/<path>] and mirrors the AS
  metadata at /.well-known/oauth-authorization-server, with permissive
  CORS and a GET/OPTIONS allow-list.
- getOAuthProtectedResourceMetadataUrl: builds the path-aware PRM URL
  for a given server URL.
- OAuthTokenVerifier interface, plus metadataHandler / allowedMethods
  building blocks.

Adapted to v2's single OAuthError + OAuthErrorCode (no per-code
subclasses) and to types re-exported via @modelcontextprotocol/server.
Adds cors as a runtime dependency and supertest as a dev dependency for
the integration tests.

Author: felixweinberger

.changeset/express-resource-server-auth.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/express': minor
+---
+
+Add OAuth Resource-Server glue to the Express adapter: `requireBearerAuth` middleware (token verification + RFC 6750 `WWW-Authenticate` challenges), `mcpAuthMetadataRouter` (serves RFC 9728 Protected Resource Metadata and mirrors RFC 8414 AS metadata at the resource origin), the `getOAuthProtectedResourceMetadataUrl` helper, and the `OAuthTokenVerifier` interface. These restore the v1 `src/server/auth` Resource-Server pieces as first-class v2 API so MCP servers can plug into an external Authorization Server with a few lines of Express wiring.

examples/server/src/elicitationUrlExample.ts

@@ -9,13 +9,8 @@
 
 import { randomUUID } from 'node:crypto';
 
-import {
-    createProtectedResourceMetadataRouter,
-    getOAuthProtectedResourceMetadataUrl,
-    requireBearerAuth,
-    setupAuthServer
-} from '@modelcontextprotocol/examples-shared';
-import { createMcpExpressApp } from '@modelcontextprotocol/express';
+import { createProtectedResourceMetadataRouter, demoTokenVerifier, setupAuthServer } from '@modelcontextprotocol/examples-shared';
+import { createMcpExpressApp, getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ElicitRequestURLParams, ElicitResult } from '@modelcontextprotocol/server';
 import { isInitializeRequest, McpServer, UrlElicitationRequiredError } from '@modelcontextprotocol/server';
@@ -235,18 +230,17 @@ let authMiddleware = null;
 const mcpServerUrl = new URL(`http://localhost:${MCP_PORT}/mcp`);
 const authServerUrl = new URL(`http://localhost:${AUTH_PORT}`);
 
-setupAuthServer({ authServerUrl, mcpServerUrl, strictResource: true, demoMode: true });
+setupAuthServer({ authServerUrl, mcpServerUrl, demoMode: true });
 
 // Add protected resource metadata route to the MCP server
 // This allows clients to discover the auth server
 // Pass the resource path so metadata is served at /.well-known/oauth-protected-resource/mcp
 app.use(createProtectedResourceMetadataRouter('/mcp'));
 
 authMiddleware = requireBearerAuth({
+    verifier: demoTokenVerifier,
     requiredScopes: [],
-    resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl),
-    strictResource: true,
-    expectedResource: mcpServerUrl
+    resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
 });
 
 /**

examples/server/src/simpleStreamableHttp.ts

@@ -1,12 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
-import {
-    createProtectedResourceMetadataRouter,
-    getOAuthProtectedResourceMetadataUrl,
-    requireBearerAuth,
-    setupAuthServer
-} from '@modelcontextprotocol/examples-shared';
-import { createMcpExpressApp } from '@modelcontextprotocol/express';
+import { createProtectedResourceMetadataRouter, demoTokenVerifier, setupAuthServer } from '@modelcontextprotocol/examples-shared';
+import { createMcpExpressApp, getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type {
     CallToolResult,
@@ -25,7 +20,6 @@ import { InMemoryEventStore } from './inMemoryEventStore.js';
 
 // Check for OAuth flag
 const useOAuth = process.argv.includes('--oauth');
-const strictOAuth = process.argv.includes('--oauth-strict');
 const dangerousLoggingEnabled = process.argv.includes('--dangerous-logging-enabled');
 
 // Create shared task store for demonstration
@@ -624,18 +618,17 @@ if (useOAuth) {
     const mcpServerUrl = new URL(`http://localhost:${MCP_PORT}/mcp`);
     const authServerUrl = new URL(`http://localhost:${AUTH_PORT}`);
 
-    setupAuthServer({ authServerUrl, mcpServerUrl, strictResource: strictOAuth, demoMode: true, dangerousLoggingEnabled });
+    setupAuthServer({ authServerUrl, mcpServerUrl, demoMode: true, dangerousLoggingEnabled });
 
     // Add protected resource metadata route to the MCP server
     // This allows clients to discover the auth server
     // Pass the resource path so metadata is served at /.well-known/oauth-protected-resource/mcp
     app.use(createProtectedResourceMetadataRouter('/mcp'));
 
     authMiddleware = requireBearerAuth({
+        verifier: demoTokenVerifier,
         requiredScopes: [],
-        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl),
-        strictResource: strictOAuth,
-        expectedResource: mcpServerUrl
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
     });
 }
 
@@ -651,8 +644,8 @@ const mcpPostHandler = async (req: Request, res: Response) => {
         console.log('Request body:', req.body);
     }
 
-    if (useOAuth && req.app.locals.auth) {
-        console.log('Authenticated user:', req.app.locals.auth);
+    if (useOAuth && req.auth) {
+        console.log('Authenticated user:', req.auth);
     }
     try {
         let transport: NodeStreamableHTTPServerTransport;
@@ -742,8 +735,8 @@ const mcpGetHandler = async (req: Request, res: Response) => {
         return;
     }
 
-    if (useOAuth && req.app.locals.auth) {
-        console.log('Authenticated SSE connection from user:', req.app.locals.auth);
+    if (useOAuth && req.auth) {
+        console.log('Authenticated SSE connection from user:', req.auth);
     }
 
     // Check for Last-Event-ID header for resumability

examples/shared/src/authMiddleware.ts

@@ -9,6 +9,9 @@
  * See: https://www.better-auth.com/docs/plugins/mcp
  */
 
+import type { OAuthTokenVerifier } from '@modelcontextprotocol/express';
+import type { AuthInfo } from '@modelcontextprotocol/server';
+import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
 import { toNodeHandler } from 'better-auth/node';
 import { oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata } from 'better-auth/plugins';
 import cors from 'cors';
@@ -21,7 +24,6 @@ import { createDemoAuth, DEMO_USER_CREDENTIALS } from './auth.js';
 export interface SetupAuthServerOptions {
     authServerUrl: URL;
     mcpServerUrl: URL;
-    strictResource?: boolean;
     /**
      * Examples should be used for **demo** only and not for production purposes, however this mode disables some logging and other features.
      */
@@ -284,60 +286,29 @@ export function createProtectedResourceMetadataRouter(resourcePath = '/mcp'): Ro
 }
 
 /**
- * Verifies an access token using better-auth's getMcpSession.
- * This can be used by MCP servers to validate tokens.
+ * Demo {@link OAuthTokenVerifier} backed by better-auth's `getMcpSession`.
+ * Pass this to `requireBearerAuth({ verifier: demoTokenVerifier, ... })` from
+ * `@modelcontextprotocol/express` to validate Bearer tokens against the demo
+ * Authorization Server started by `setupAuthServer`.
  */
-export async function verifyAccessToken(
-    token: string,
-    options?: { strictResource?: boolean; expectedResource?: URL }
-): Promise<{
-    token: string;
-    clientId: string;
-    scopes: string[];
-    expiresAt: number;
-}> {
-    const auth = getAuth();
+export const demoTokenVerifier: OAuthTokenVerifier = {
+    async verifyAccessToken(token: string): Promise<AuthInfo> {
+        const auth = getAuth();
 
-    try {
-        // Create a mock request with the Authorization header
         const headers = new Headers();
         headers.set('Authorization', `Bearer ${token}`);
 
-        // Use better-auth's getMcpSession API
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const session = await (auth.api as any).getMcpSession({
-            headers
-        });
-
+        const session = await (auth.api as any).getMcpSession({ headers });
         if (!session) {
-            throw new Error('Invalid token');
+            throw new OAuthError(OAuthErrorCode.InvalidToken, 'Invalid token');
         }
 
-        // OAuthAccessToken has:
-        // - accessToken, refreshToken: string
-        // - accessTokenExpiresAt, refreshTokenExpiresAt: Date
-        // - clientId, userId: string
-        // - scopes: string (space-separated)
         const scopes = typeof session.scopes === 'string' ? session.scopes.split(' ') : ['openid'];
         const expiresAt = session.accessTokenExpiresAt
             ? Math.floor(new Date(session.accessTokenExpiresAt).getTime() / 1000)
             : Math.floor(Date.now() / 1000) + 3600;
 
-        // Note: better-auth's OAuthAccessToken doesn't have a resource field
-        // Resource validation would need to be done at a different layer
-        if (options?.strictResource && options.expectedResource) {
-            // For now, we skip resource validation as it's not in the session
-            // In production, you'd store and validate this separately
-            console.warn('[Auth] Resource validation requested but not available in better-auth session');
-        }
-
-        return {
-            token,
-            clientId: session.clientId,
-            scopes,
-            expiresAt
-        };
-    } catch (error) {
-        throw new Error(`Token verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        return { token, clientId: session.clientId, scopes, expiresAt };
     }
-}
+};

examples/shared/src/authServer.ts

@@ -2,10 +2,6 @@
 export type { CreateDemoAuthOptions, DemoAuth } from './auth.js';
 export { createDemoAuth } from './auth.js';
 
-// Auth middleware
-export type { RequireBearerAuthOptions } from './authMiddleware.js';
-export { getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from './authMiddleware.js';
-
-// Auth server setup
+// Auth server setup + demo token verifier (pass to `requireBearerAuth` from @modelcontextprotocol/express)
 export type { SetupAuthServerOptions } from './authServer.js';
-export { createProtectedResourceMetadataRouter, getAuth, setupAuthServer, verifyAccessToken } from './authServer.js';
+export { createProtectedResourceMetadataRouter, demoTokenVerifier, getAuth, setupAuthServer } from './authServer.js';

examples/shared/src/index.ts

@@ -8,6 +8,7 @@
         "paths": {
             "*": ["./*"],
             "@modelcontextprotocol/server": ["./node_modules/@modelcontextprotocol/server/src/index.ts"],
+            "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
             "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"],
             "@modelcontextprotocol/core": [
                 "./node_modules/@modelcontextprotocol/server/node_modules/@modelcontextprotocol/core/src/index.ts"

examples/shared/tsconfig.json

@@ -41,19 +41,24 @@
         "test": "vitest run",
         "test:watch": "vitest"
     },
-    "dependencies": {},
+    "dependencies": {
+        "cors": "catalog:runtimeServerOnly"
+    },
     "peerDependencies": {
         "@modelcontextprotocol/server": "workspace:^",
-        "express": "catalog:runtimeServerOnly"
+        "express": "^4.18.0 || ^5.0.0"
     },
     "devDependencies": {
         "@modelcontextprotocol/server": "workspace:^",
         "@modelcontextprotocol/tsconfig": "workspace:^",
         "@modelcontextprotocol/vitest-config": "workspace:^",
         "@modelcontextprotocol/eslint-config": "workspace:^",
         "@eslint/js": "catalog:devTools",
+        "@types/cors": "catalog:devTools",
         "@types/express": "catalog:devTools",
         "@types/express-serve-static-core": "catalog:devTools",
+        "@types/supertest": "catalog:devTools",
+        "supertest": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
         "eslint": "catalog:devTools",
         "eslint-config-prettier": "catalog:devTools",