feat(auth): implement generalized authentication layer and scope-based authorization

.changeset/add-mcp-auth-and-authorization.md

@@ -0,0 +1,11 @@
+---
+'@modelcontextprotocol/core': minor
+'@modelcontextprotocol/server': minor
+---
+
+Implement generalized authentication and authorization layer for MCP servers.
+
+- Added `Authenticator` and `BearerTokenAuthenticator` to `@modelcontextprotocol/server`.
+- Integrated scope-based authorization checks into `McpServer` for tools, resources, and prompts.
+- Fixed asynchronous error propagation in the core `Protocol` class to support proper 401/403 HTTP status mapping in transports.
+- Updated `WebStandardStreamableHTTPServerTransport` to correctly map authentication and authorization failures to their respective HTTP status codes.

README.md

@@ -136,6 +136,7 @@ Next steps:
 
 - Local SDK docs:
     - [docs/server.md](docs/server.md) – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns.
+    - [docs/auth.md](docs/auth.md) – implementing authentication and authorization in MCP servers.
     - [docs/client.md](docs/client.md) – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
     - [docs/faq.md](docs/faq.md) – frequently asked questions and troubleshooting
 - External references:

docs/auth.md

@@ -0,0 +1,110 @@
+# Authentication and Authorization
+
+The MCP TypeScript SDK provides optional, opt-in support for authentication (AuthN) and authorization (AuthZ). This enables you to protect your MCP server resources, tools, and prompts using industry-standard schemes like OAuth 2.1 Bearer tokens.
+
+## Key Concepts
+
+- **Authenticator**: Responsible for extracting and validating authentication information from an incoming request.
+- **AuthInfo**: A structure containing information about the authenticated entity (e.g., user name, active scopes).
+- **Authorizer**: Used by the MCP server to verify if the authenticated entity has the required scopes to access a specific resource, tool, or prompt.
+- **Scopes**: Optional strings associated with registered items that define the required permissions.
+
+## Implementing Authentication
+
+To enable authentication, provide an `authenticator` in the `ServerOptions` when creating your server.
+
+### Using Bearer Token Authentication
+
+The SDK includes a `BearerTokenAuthenticator` for validating OAuth 2.1 Bearer tokens.
+
+```typescript
+import { McpServer, BearerTokenAuthenticator } from "@modelcontextprotocol/server";
+
+const server = new McpServer({
+  name: "my-authenticated-server",
+  version: "1.0.0",
+}, {
+  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
+  })
+});
+```
+
+## Implementing Authorization
+
+Authorization is enforced using the `scopes` property when registering tools, resources, or prompts.
+
+### Scoped Tools
+
+```typescript
+server.tool(
+  "secure_tool",
+  { 
+    description: "A tool that requires specific scopes",
+    scopes: ["execute:tools"] 
+  },
+  async (args) => {
+    return { content: [{ type: "text", text: "Success!" }] };
+  }
+);
+```
+
+### Scoped Resources
+
+```typescript
+server.resource(
+  "secure_resource",
+  "secure://data",
+  { scopes: ["read:resources"] },
+  async (uri) => {
+    return { contents: [{ uri: uri.href, text: "Top secret data" }] };
+  }
+);
+```
+
+## Middleware Support
+
+For framework-specific integrations, use the provided middleware to pre-authenticate requests.
+
+### Express Middleware
+
+```typescript
+import express from "express";
+import { auth } from "@modelcontextprotocol/express";
+
+const app = express();
+app.use(auth({ authenticator }));
+
+app.post("/mcp", (req, res) => {
+  // req.auth is now populated
+  transport.handleRequest(req, res);
+});
+```
+
+### Hono Middleware
+
+```typescript
+import { Hono } from "hono";
+import { auth } from "@modelcontextprotocol/hono";
+
+const app = new Hono();
+app.use("/mcp/*", auth({ authenticator }));
+
+app.all("/mcp", async (c) => {
+  const authInfo = c.get("mcpAuthInfo");
+  return transport.handleRequest(c.req.raw, { authInfo });
+});
+```
+
+## Error Handling
+
+- **401 Unauthorized**: Returned when authentication is required but missing or invalid. Includes `WWW-Authenticate: Bearer` header.
+- **403 Forbidden**: Returned when the authenticated entity lacks the required scopes.

docs/server.md

@@ -11,6 +11,7 @@ Building a server takes three steps:
 1. Create an {@linkcode @modelcontextprotocol/server!server/mcp.McpServer | McpServer} and register your [tools, resources, and prompts](#tools-resources-and-prompts).
 2. Create a transport — [Streamable HTTP](#streamable-http) for remote servers or [stdio](#stdio) for local, process‑spawned integrations.
 3. Wire the transport into your HTTP framework (or use stdio directly) and call `server.connect(transport)`.
+1. (Optional) Configure [authentication and authorization](#authentication-and-authorization) to protect your server.
 
 The sections below cover each of these. For a feature‑rich starting point, see [`simpleStreamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts) — remove what you don't need and register your own tools, resources, and prompts. For stateless or JSON‑response‑mode alternatives, see the examples linked in [Transports](#transports) below.
 
@@ -444,6 +445,25 @@ Task-based execution enables "call-now, fetch-later" patterns for long-running o
 > [!WARNING]
 > The tasks API is experimental and may change without notice.
 
+## Authentication and Authorization
+
+The MCP TypeScript SDK provides optional, opt-in support for authentication (AuthN) and authorization (AuthZ). For a comprehensive guide, see the [Authentication and Authorization guide](./auth.md).
+
+Quick example:
+
+```ts
+const server = new McpServer({ name: 'my-server', version: '1.0.0' }, {
+    authenticator: new BearerTokenAuthenticator(async (token) => {
+        if (token === 'secret') return { token, clientId: 'admin', scopes: ['all'] };
+        return undefined;
+    })
+});
+
+server.tool('secure-tool', { scopes: ['all'] }, async (args) => {
+    return { content: [{ type: 'text', text: 'Success' }] };
+});
+```
+
 ## Deployment
 
 ### DNS rebinding protection

packages/core/src/shared/protocol.ts

@@ -704,16 +704,24 @@ export abstract class Protocol<ContextT extends BaseContext> {
         };
 
         const _onmessage = this._transport?.onmessage;
-        this._transport.onmessage = (message, extra) => {
-            _onmessage?.(message, extra);
-            if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) {
-                this._onresponse(message);
-            } else if (isJSONRPCRequest(message)) {
-                this._onrequest(message, extra);
-            } else if (isJSONRPCNotification(message)) {
-                this._onnotification(message);
-            } else {
-                this._onerror(new Error(`Unknown message type: ${JSON.stringify(message)}`));
+        this._transport.onmessage = async (message, extra) => {
+            try {
+                if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) {
+                    await _onmessage?.(message, extra);
+                    this._onresponse(message);
+                } else if (isJSONRPCRequest(message)) {
+                    await this._onrequest(message, extra);
+                } else if (isJSONRPCNotification(message)) {
+                    await this._onnotification(message);
+                } else {
+                    await _onmessage?.(message, extra);
+                    this._onerror(new Error(`Unknown message type: ${JSON.stringify(message)}`));
+                }
+            } catch (error) {
+                if (error instanceof ProtocolError && (error.code === ProtocolErrorCode.Unauthorized || error.code === ProtocolErrorCode.Forbidden)) {
+                    throw error;
+                }
+                this._onerror(error instanceof Error ? error : new Error(String(error)));
             }
         };
 
@@ -758,7 +766,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
             .catch(error => this._onerror(new Error(`Uncaught error in notification handler: ${error}`)));
     }
 
-    private _onrequest(request: JSONRPCRequest, extra?: MessageExtraInfo): void {
+    protected async _onrequest(request: JSONRPCRequest, extra?: MessageExtraInfo): Promise<void> {
         const handler = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
 
         // Capture the current transport at request time to ensure responses go to the correct client
@@ -838,7 +846,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
         const ctx = this.buildContext(baseCtx, extra);
 
         // Starting with Promise.resolve() puts any synchronous errors into the monad as well.
-        Promise.resolve()
+        return Promise.resolve()
             .then(() => {
                 // If this request asked for task creation, check capability first
                 if (taskCreationParams) {
@@ -879,6 +887,10 @@ export abstract class Protocol<ContextT extends BaseContext> {
                         return;
                     }
 
+                    if (error instanceof ProtocolError && (error.message.includes('Unauthorized') || error.message.includes('Forbidden'))) {
+                        throw error;
+                    }
+
                     const errorResponse: JSONRPCErrorResponse = {
                         jsonrpc: '2.0',
                         id: request.id,
@@ -903,7 +915,13 @@ export abstract class Protocol<ContextT extends BaseContext> {
                         : capturedTransport?.send(errorResponse));
                 }
             )
-            .catch(error => this._onerror(new Error(`Failed to send response: ${error}`)))
+            .catch(error => {
+                if (error instanceof ProtocolError && (error.message.includes('Unauthorized') || error.message.includes('Forbidden'))) {
+                    throw error;
+                }
+                // Do not report as protocol error if it's already an auth error we're escaping
+                this._onerror(new Error(`Failed to send response: ${error}`));
+            })
             .finally(() => {
                 this._requestHandlerAbortControllers.delete(request.id);
             });

packages/core/src/shared/transport.ts

@@ -114,7 +114,7 @@ export interface Transport {
      *
      * The {@linkcode MessageExtraInfo.requestInfo | requestInfo} can be used to get the original request information (headers, etc.)
      */
-    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void | Promise<void>;
 
     /**
      * The session ID generated for this connection.

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/express.ts

@@ -2,6 +2,8 @@ import type { Express } from 'express';
 import express from 'express';
 
 import { hostHeaderValidation, localhostHostValidation } from './middleware/hostHeaderValidation.js';
+export { auth } from './middleware/auth.js';
+export type { AuthMiddlewareOptions } from './middleware/auth.js';
 
 /**
  * Options for creating an MCP Express application.

packages/middleware/express/src/index.ts

@@ -1,2 +1,3 @@
 export * from './express.js';
+export { auth } from './middleware/auth.js';
 export * from './middleware/hostHeaderValidation.js';

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

@@ -0,0 +1,58 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { Authenticator, AuthInfo } from '@modelcontextprotocol/server';
+
+/**
+ * Options for the MCP Express authentication middleware.
+ */
+export interface AuthMiddlewareOptions {
+    /**
+     * The authenticator to use for validating requests.
+     */
+    authenticator: Authenticator;
+}
+
+/**
+ * Creates an Express middleware for MCP authentication.
+ *
+ * This middleware extracts authentication information from the request using the provided authenticator
+ * and attaches it to the request object as `req.auth`. The MCP Express transport will then
+ * pick up this information automatically.
+ *
+ * @param options - Middleware options
+ * @returns An Express middleware function
+ *
+ * @example
+ * ```ts
+ * const authenticator = new BearerTokenAuthenticator((token) => Promise.resolve({ token, clientId: 'user', scopes: ['read'] }));
+ * app.use(auth({ authenticator }));
+ * ```
+ */
+export function auth(options: AuthMiddlewareOptions): RequestHandler {
+    return async (req: Request & { auth?: AuthInfo }, res: Response, next: NextFunction) => {
+        try {
+            const headers: Record<string, string> = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === 'string') {
+                    headers[key] = value;
+                } else if (Array.isArray(value)) {
+                    headers[key] = value.join(', ');
+                }
+            }
+
+            const authInfo = await options.authenticator.authenticate({
+                method: req.method,
+                headers,
+            });
+            if (authInfo) {
+                req.auth = authInfo;
+            }
+            next();
+        } catch (error) {
+            // 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/middleware/hono/src/hono.ts

@@ -2,6 +2,8 @@ import type { Context } from 'hono';
 import { Hono } from 'hono';
 
 import { hostHeaderValidation, localhostHostValidation } from './middleware/hostHeaderValidation.js';
+export { auth } from './middleware/auth.js';
+export type { AuthMiddlewareOptions } from './middleware/auth.js';
 
 /**
  * Options for creating an MCP Hono application.

packages/middleware/hono/src/index.ts

@@ -1,2 +1,3 @@
 export * from './hono.js';
+export { auth } from './middleware/auth.js';
 export * from './middleware/hostHeaderValidation.js';