fix: address PR feedback and CI failures in TypeScript SDK

Author: sairajm

docs/auth.md

@@ -24,17 +24,16 @@ const server = new McpServer({
   name: "my-authenticated-server",
   version: "1.0.0",
 }, {
-  authenticator: new BearerTokenAuthenticator({
-    validate: async (token) => {
-      // Validate the token (e.g., verify with an OAuth provider)
-      if (token === "valid-token") {
-        return {
-          name: "john_doe",
-          scopes: ["read:resources", "execute:tools"]
-        };
-      }
-      return undefined; // Invalid token
+  authenticator: new BearerTokenAuthenticator(async (token) => {
+    // Validate the token (e.g., verify with an OAuth provider)
+    if (token === "valid-token") {
+      return {
+        token,
+        clientId: "john_doe",
+        scopes: ["read:resources", "execute:tools"]
+      };
     }
+    return undefined; // Invalid token
   })
 });
 ```

docs/server.md

@@ -453,11 +453,9 @@ Quick example:
 
 ```ts
 const server = new McpServer({ name: 'my-server', version: '1.0.0' }, {
-    authenticator: new BearerTokenAuthenticator({
-        validate: async (token) => {
-            if (token === 'secret') return { name: 'admin', scopes: ['all'] };
-            return undefined;
-        }
+    authenticator: new BearerTokenAuthenticator(async (token) => {
+        if (token === 'secret') return { token, clientId: 'admin', scopes: ['all'] };
+        return undefined;
     })
 });
 

packages/core/src/types/types.ts

@@ -233,6 +233,8 @@ export enum ProtocolErrorCode {
     InternalError = -32_603,
 
     // MCP-specific error codes
+    Unauthorized = 401,
+    Forbidden = 403,
     ResourceNotFound = -32_002,
     UrlElicitationRequired = -32_042
 }

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

@@ -1,4 +1,4 @@
-import { Request, Response, NextFunction } from 'express';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
 import { Authenticator, AuthInfo } from '@modelcontextprotocol/server';
 
 /**
@@ -23,13 +23,11 @@ export interface AuthMiddlewareOptions {
  *
  * @example
  * ```ts
- * const authenticator = new BearerTokenAuthenticator({
- *   validate: async (token) => ({ name: 'user', scopes: ['read'] })
- * });
+ * const authenticator = new BearerTokenAuthenticator((token) => Promise.resolve({ token, clientId: 'user', scopes: ['read'] }));
  * app.use(auth({ authenticator }));
  * ```
  */
-export function auth(options: AuthMiddlewareOptions) {
+export function auth(options: AuthMiddlewareOptions): RequestHandler {
     return async (req: Request & { auth?: AuthInfo }, res: Response, next: NextFunction) => {
         try {
             const headers: Record<string, string> = {};
@@ -53,6 +51,7 @@ export function auth(options: AuthMiddlewareOptions) {
             // If authentication fails, we let the MCP server handle it later,
             // or the developer can choose to reject here.
             // By default, we just proceed to allow the MCP server to decide (e.g., if auth is optional).
+            console.error('[MCP Express Auth Middleware] Authentication failed:', error);
             next();
         }
     };

packages/server/src/server/mcp.ts

@@ -211,7 +211,7 @@ export class McpServer {
                 // Authorization check
                 if (tool.scopes && tool.scopes.length > 0) {
                     if (!ctx.http?.authInfo || !Authorizer.isAuthorized(ctx.http.authInfo, tool.scopes)) {
-                        throw new ProtocolError(ProtocolErrorCode.InvalidRequest, 'Forbidden');
+                        throw new ProtocolError(ProtocolErrorCode.Forbidden, 'Forbidden');
                     }
                 }
 
@@ -229,10 +229,13 @@ export class McpServer {
                 return result;
             } catch (error) {
                 if (error instanceof ProtocolError) {
-                    if (error.message.includes('Forbidden') || error.message.includes('Unauthorized')) {
+                    if (
+                        error.code === ProtocolErrorCode.Forbidden ||
+                        error.code === ProtocolErrorCode.Unauthorized ||
+                        error.code === ProtocolErrorCode.UrlElicitationRequired
+                    ) {
                         throw error;
                     }
-                    throw error;
                 }
                 return this.createToolError(error instanceof Error ? error.message : String(error));
             }

packages/server/src/server/server.ts

@@ -180,7 +180,7 @@ export class Server extends Protocol<ServerContext> {
             });
 
             if (!authInfo) {
-                throw new ProtocolError(ProtocolErrorCode.InvalidRequest, 'Unauthorized');
+                throw new ProtocolError(ProtocolErrorCode.Unauthorized, 'Unauthorized');
             }
 
             // Inject authInfo into extra for buildContext

packages/server/src/server/streamableHttp.ts

@@ -824,19 +824,23 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                     }));
                 } catch (error) {
                     if (error instanceof ProtocolError) {
-                        const message = error.message;
-                        if (message.includes('Unauthorized')) {
+                        if (error.code === ProtocolErrorCode.Unauthorized) {
                             const response = this.createJsonErrorResponse(401, error.code, 'Unauthorized', { headers: { 'WWW-Authenticate': 'Bearer' } });
                             this._streamMapping.delete(streamId);
                             return response;
                         }
-                        if (message.includes('Forbidden')) {
-                            const response = this.createJsonErrorResponse(403, error.code, message);
+                        if (error.code === ProtocolErrorCode.Forbidden) {
+                            const response = this.createJsonErrorResponse(403, error.code, error.message);
                             this._streamMapping.delete(streamId);
                             return response;
                         }
+                        if (error.code === ProtocolErrorCode.UrlElicitationRequired) {
+                            throw error;
+                        }
                     }
                     console.error('Transport caught error in onmessage:', error);
+                    // Standard tools should return a CallToolResult with isError: true.
+                    // For onmessage we only rethrow auth-related errors and UrlElicitationRequired.
                     throw error;
                 }
             }
@@ -846,13 +850,11 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             return new Response(readable, { status: 200, headers });
         } catch (error) {
             if (error instanceof ProtocolError) {
-                const message = error.message;
-                if (message.includes('Unauthorized')) {
+                if (error.code === ProtocolErrorCode.Unauthorized) {
                     return this.createJsonErrorResponse(401, error.code, 'Unauthorized', { headers: { 'WWW-Authenticate': 'Bearer' } });
                 }
-                if (message.includes('Forbidden')) {
-                    console.log('[Transport] Mapping Forbidden to 403');
-                    return this.createJsonErrorResponse(403, error.code, message);
+                if (error.code === ProtocolErrorCode.Forbidden) {
+                    return this.createJsonErrorResponse(403, error.code, error.message);
                 }
             }
             // return JSON-RPC formatted error