@ttoss/http-server-mcp 0.12.5 → 0.13.0

package/README.md

@@ -127,6 +127,137 @@ const data = await apiCall('GET', 'https://partner.api.com/data', {
 
 `apiCall` throws with a clear message when called with a relative path and no `apiBaseUrl` is configured in the context.
 
+## Authentication
+
+`createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Every incoming MCP request must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant MCP Server
+    participant Verifier
+
+    Client->>MCP Server: POST /mcp + Authorization: Bearer &lt;token&gt;
+    MCP Server->>Verifier: verify(token)
+    alt valid token
+        Verifier-->>MCP Server: identity payload
+        MCP Server->>MCP Server: run tool (identity available via getIdentity())
+        MCP Server-->>Client: 200 OK
+    else invalid or missing token
+        Verifier-->>MCP Server: error
+        MCP Server-->>Client: 401 Unauthorized
+    end
+```
+
+### Amazon Cognito
+
+Pass `cognitoUserPool` and the router creates a `CognitoJwtVerifier` (from `@ttoss/auth-core`) internally:
+
+```typescript
+import { createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: {
+      userPoolId: process.env.COGNITO_USER_POOL_ID!,
+      clientId: process.env.COGNITO_CLIENT_ID!,
+      tokenUse: 'access', // default
+    },
+  },
+});
+```
+
+### Custom verifier
+
+Pass an async `verifyToken` function for any other provider (Auth0, Keycloak, etc.):
+
+```typescript
+import { createMcpRouter } from '@ttoss/http-server-mcp';
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+
+const JWKS = createRemoteJWKSet(
+  new URL('https://your-auth-server/.well-known/jwks.json')
+);
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    verifyToken: async (token) => {
+      const { payload } = await jwtVerify(token, JWKS);
+      return payload;
+    },
+  },
+});
+```
+
+### Accessing the verified identity
+
+Inside any tool handler, call `getIdentity()` to retrieve the verified JWT payload:
+
+```typescript
+import { getIdentity, createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+
+mcpServer.registerTool(
+  'get-profile',
+  { description: 'Return the caller's profile', inputSchema: {} },
+  async () => {
+    const identity = getIdentity() as { sub: string; email: string };
+    return {
+      content: [{ type: 'text', text: `Hello, ${identity.email}` }],
+    };
+  }
+);
+```
+
+### Scope enforcement
+
+Scopes can be enforced at two levels.
+
+**Router-level** — gate the entire MCP endpoint. Any token missing a required scope receives a `403 Forbidden` before any tool runs:
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    requiredScopes: ['mcp:access'],
+  },
+});
+```
+
+**Per-tool** — use `checkScopes()` inside individual handlers for fine-grained control. It throws an error that the MCP SDK returns as a tool error to the client:
+
+```typescript
+import { checkScopes, getIdentity } from '@ttoss/http-server-mcp';
+
+mcpServer.registerTool(
+  'delete-user',
+  { description: 'Delete a user', inputSchema: { userId: z.string() } },
+  async ({ userId }) => {
+    checkScopes(['admin', 'write:users']); // throws if either scope is missing
+
+    const identity = getIdentity() as { sub: string };
+    // proceed with deletion...
+    return { content: [{ type: 'text', text: `Deleted ${userId}` }] };
+  }
+);
+```
+
+Cognito encodes scopes as a space-separated string in `payload.scope` (e.g. `"openid mcp:access admin"`).
+
+### OAuth Protected Resource Metadata
+
+For MCP clients that support OAuth auto-discovery, add `resourceServerUrl` and `authorizationServerUrl` to expose the `/.well-known/oauth-protected-resource` endpoint (RFC 9728):
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    resourceServerUrl: 'https://mcp.example.com',
+    authorizationServerUrl:
+      'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
+  },
+});
+```
+
 ## API Reference
 
 ### `createMcpRouter(server, options?)`
@@ -135,14 +266,19 @@ Creates a Koa router configured to handle MCP protocol requests.
 
 **Parameters:**
 
-- `server` (`McpServer`) - MCP server instance with registered tools and resources
-- `options` (`McpRouterOptions`) - Optional configuration
-  - `path` (`string`) - HTTP path for MCP endpoint (default: `'/mcp'`)
-  - `sessionIdGenerator` (`() => string`) - Session ID generator for stateful servers (default: `undefined` for stateless)
-  - `apiBaseUrl` (`string`) - Base URL prepended to relative paths in `apiCall`
-  - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) - Return headers to inject into every `apiCall` for this request (auth tokens, API keys, trace headers, etc.)
+- `server` (`McpServer`) — MCP server instance with registered tools and resources
+- `options` (`McpRouterOptions`) — Optional configuration
+  - `path` (`string`) — HTTP path for MCP endpoint (default: `'/mcp'`)
+  - `sessionIdGenerator` (`() => string`) — Session ID generator for stateful servers (default: `undefined` for stateless)
+  - `apiBaseUrl` (`string`) — Base URL prepended to relative paths in `apiCall`
+  - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) — Return headers to inject into every `apiCall` for this request
+  - `auth` (`McpAuthOptions`) — OAuth/JWT authentication; see [Authentication](#authentication)
+    - `auth.cognitoUserPool` — Cognito user pool config (`userPoolId`, `clientId`, `tokenUse`)
+    - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
+    - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
+    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`
 
-**Returns:** `Router` - Koa router instance
+**Returns:** `Router` — Koa router instance
 
 ### `apiCall(method, url, options?)`
 
@@ -150,12 +286,26 @@ Generic HTTP helper for use inside MCP tool handlers.
 
 **Parameters:**
 
-- `method` (`string`) - HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, …)
-- `url` (`string`) - Full URL **or** a path starting with `/` (prepended with `apiBaseUrl`)
-- `options.body` (`unknown`, optional) - Request body, serialised as JSON
-- `options.headers` (`Record<string, string>`, optional) - Per-call header overrides; merged on top of context-injected headers
+- `method` (`string`) — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, …)
+- `url` (`string`) — Full URL **or** a path starting with `/` (prepended with `apiBaseUrl`)
+- `options.body` (`unknown`, optional) — Request body, serialised as JSON
+- `options.headers` (`Record<string, string>`, optional) — Per-call header overrides; merged on top of context-injected headers
+
+**Returns:** `Promise<unknown>` — Parsed JSON response body
+
+### `getIdentity()`
+
+Returns the verified JWT payload for the current MCP request. Only available inside a tool handler when `auth` is configured. Returns `undefined` when called outside an authenticated context.
+
+**Returns:** `unknown` — Verified token payload (cast to your expected shape)
+
+### `checkScopes(required)`
+
+Asserts that the current request token contains all required scopes. Throws `Error: Insufficient scopes. Required: …` if any scope is missing — the MCP SDK catches this and returns a tool error to the client.
+
+**Parameters:**
 
-**Returns:** `Promise<unknown>` - Parsed JSON response body
+- `required` (`string[]`) — Scope strings that must all be present in `payload.scope`
 
 ### `registerToolFromSchema(server, params)`
 
@@ -165,11 +315,11 @@ Use this when tool definitions are shared between the MCP server and an AI SDK a
 
 **Parameters:**
 
-- `server` (`McpServer`) - The MCP server instance
-- `params.name` (`string`) - Unique tool name
-- `params.description` (`string`, optional) - Human-readable description
-- `params.inputSchema` (`JsonObjectSchema`, optional) - Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
-- `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) - Tool handler receiving the raw request arguments
+- `server` (`McpServer`) — The MCP server instance
+- `params.name` (`string`) — Unique tool name
+- `params.description` (`string`, optional) — Human-readable description
+- `params.inputSchema` (`JsonObjectSchema`, optional) — Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
+- `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) — Tool handler receiving the raw request arguments
 
 **Returns:** `void`
 

package/dist/index.cjs

@@ -4,6 +4,7 @@ Object.defineProperty(exports, Symbol.toStringTag, {
 });
 let node_async_hooks = require("node:async_hooks");
 let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let _ttoss_http_server = require("@ttoss/http-server");
 let zod = require("zod");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -97,6 +98,80 @@ const apiCall = async (method, url, options) => {
   return response.text();
 };
 /**
+* Returns the verified JWT payload for the current MCP request.
+* Only available inside a tool handler when `auth` is configured on the router.
+*/
+const getIdentity = () => {
+  return requestContextStore.getStore()?.identity;
+};
+/**
+* Asserts that the current request's token contains all required scopes.
+* Throws if any scope is missing — the MCP SDK catches this and returns a
+* tool error to the client. Use inside tool handlers for per-tool authorization.
+*
+* Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+*
+* @example
+* ```typescript
+* server.tool('delete-user', schema, async (args) => {
+*   checkScopes(['admin', 'write:users']);
+*   // proceed only if caller has both scopes
+* });
+* ```
+*/
+const checkScopes = required => {
+  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  if (required.filter(s => {
+    return !tokenScopes.includes(s);
+  }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
+};
+const buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+const registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  router.use(path, async (ctx, next) => {
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", "Bearer");
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (auth.requiredScopes?.length) {
+      const tokenScopes = (identity?.scope ?? "").split(" ");
+      if (auth.requiredScopes.filter(s => {
+        return !tokenScopes.includes(s);
+      }).length > 0) {
+        ctx.status = 403;
+        ctx.body = "Forbidden";
+        return;
+      }
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+/**
 * Creates a Koa router configured to handle MCP protocol requests
 *
 * @param server - The MCP server instance with registered tools and resources
@@ -138,10 +213,11 @@ const createMcpRouter = (server, options = {}) => {
     path = "/mcp",
     sessionIdGenerator,
     apiBaseUrl,
-    getApiHeaders
+    getApiHeaders,
+    auth
   } = options;
   const isStateful = sessionIdGenerator !== void 0;
-  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
   let sharedTransport;
   if (isStateful) {
     sharedTransport = new _modelcontextprotocol_sdk_server_streamableHttp_js.StreamableHTTPServerTransport({
@@ -159,8 +235,10 @@ const createMcpRouter = (server, options = {}) => {
     return result;
   };
   const router = new _ttoss_http_server.Router();
+  if (auth) registerAuthRoutes(router, path, auth, buildTokenVerifier(auth));
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    const identity = ctx.state.identity;
     const runRequest = async transport => {
       await transport.handleRequest(ctx.req, ctx.res, body);
       ctx.respond = false;
@@ -168,7 +246,8 @@ const createMcpRouter = (server, options = {}) => {
     if (isStateful && sharedTransport) {
       if (needsContext) await requestContextStore.run({
         apiBaseUrl,
-        apiHeaders
+        apiHeaders,
+        identity
       }, () => {
         return runRequest(sharedTransport);
       });else await runRequest(sharedTransport);
@@ -181,7 +260,8 @@ const createMcpRouter = (server, options = {}) => {
         await server.connect(transport);
         if (needsContext) await requestContextStore.run({
           apiBaseUrl,
-          apiHeaders
+          apiHeaders,
+          identity
         }, () => {
           return runRequest(transport);
         });else await runRequest(transport);
@@ -309,7 +389,9 @@ Object.defineProperty(exports, 'McpServer', {
   }
 });
 exports.apiCall = apiCall;
+exports.checkScopes = checkScopes;
 exports.createMcpRouter = createMcpRouter;
+exports.getIdentity = getIdentity;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {
   enumerable: true,

package/dist/index.d.cts

@@ -737,6 +737,79 @@ interface ApiCallOptions {
  * ```
  */
 declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
+/**
+ * Returns the verified JWT payload for the current MCP request.
+ * Only available inside a tool handler when `auth` is configured on the router.
+ */
+declare const getIdentity: () => unknown;
+/**
+ * Asserts that the current request's token contains all required scopes.
+ * Throws if any scope is missing — the MCP SDK catches this and returns a
+ * tool error to the client. Use inside tool handlers for per-tool authorization.
+ *
+ * Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+ *
+ * @example
+ * ```typescript
+ * server.tool('delete-user', schema, async (args) => {
+ *   checkScopes(['admin', 'write:users']);
+ *   // proceed only if caller has both scopes
+ * });
+ * ```
+ */
+declare const checkScopes: (required: string[]) => void;
+/** Amazon Cognito user pool configuration for JWT verification. */
+interface CognitoUserPoolConfig {
+  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
+  userPoolId: string;
+  /**
+   * Which token type to verify.
+   * @default 'access'
+   */
+  tokenUse?: 'access' | 'id';
+  /** The app client ID registered in the User Pool. */
+  clientId: string;
+}
+/**
+ * Authentication options for the MCP router.
+ *
+ * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
+ * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
+ */
+interface McpAuthOptions {
+  /**
+   * Amazon Cognito user pool config. When provided, the router creates a
+   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
+   */
+  cognitoUserPool?: CognitoUserPoolConfig;
+  /**
+   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
+   * Receives the raw Bearer token string. Should resolve with the verified
+   * payload or reject/throw on failure.
+   */
+  verifyToken?: (token: string) => Promise<unknown>;
+  /**
+   * Router-level scope guard. All listed scopes must be present on the token
+   * for any MCP request to be allowed. Returns 403 if any scope is missing.
+   *
+   * Cognito encodes scopes as a space-separated string in `payload.scope`.
+   *
+   * @example ['mcp:access']
+   */
+  requiredScopes?: string[];
+  /**
+   * URL of this MCP server, used in the OAuth Protected Resource Metadata
+   * response (`/.well-known/oauth-protected-resource`). Both this field and
+   * `authorizationServerUrl` must be provided to enable the endpoint.
+   */
+  resourceServerUrl?: string;
+  /**
+   * URL of the OAuth Authorization Server that issues tokens for this resource.
+   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
+   * (RFC 9728) when combined with `resourceServerUrl`.
+   */
+  authorizationServerUrl?: string;
+}
 /**
  * Options for configuring the MCP router
  */
@@ -786,6 +859,38 @@ interface McpRouterOptions {
    * ```
    */
   getApiHeaders?: (ctx: Context$1) => Record<string, string>;
+  /**
+   * OAuth / JWT authentication configuration for the MCP endpoint.
+   *
+   * When set, every incoming MCP request must include a valid Bearer token in
+   * the `Authorization` header. Invalid or missing tokens receive a `401`
+   * response with `WWW-Authenticate: Bearer`. Tokens that fail a
+   * `requiredScopes` check receive `403`.
+   *
+   * The verified token payload is accessible inside tool handlers via
+   * {@link getIdentity}. Fine-grained per-tool scope checks can be done with
+   * {@link checkScopes}.
+   *
+   * @example Cognito
+   * ```typescript
+   * createMcpRouter(server, {
+   *   auth: {
+   *     cognitoUserPool: { userPoolId: 'us-east-1_xxx', clientId: 'yyy' },
+   *     requiredScopes: ['mcp:access'],
+   *   },
+   * });
+   * ```
+   *
+   * @example Custom verifier
+   * ```typescript
+   * createMcpRouter(server, {
+   *   auth: {
+   *     verifyToken: async (token) => myJwtLib.verify(token),
+   *   },
+   * });
+   * ```
+   */
+  auth?: McpAuthOptions;
 }
 /**
  * Creates a Koa router configured to handle MCP protocol requests
@@ -902,4 +1007,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, JsonObjectSchema, McpRouterOptions, type McpServer, RegisterToolFromSchemaParams, apiCall, createMcpRouter, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, type McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -737,6 +737,79 @@ interface ApiCallOptions {
  * ```
  */
 declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
+/**
+ * Returns the verified JWT payload for the current MCP request.
+ * Only available inside a tool handler when `auth` is configured on the router.
+ */
+declare const getIdentity: () => unknown;
+/**
+ * Asserts that the current request's token contains all required scopes.
+ * Throws if any scope is missing — the MCP SDK catches this and returns a
+ * tool error to the client. Use inside tool handlers for per-tool authorization.
+ *
+ * Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+ *
+ * @example
+ * ```typescript
+ * server.tool('delete-user', schema, async (args) => {
+ *   checkScopes(['admin', 'write:users']);
+ *   // proceed only if caller has both scopes
+ * });
+ * ```
+ */
+declare const checkScopes: (required: string[]) => void;
+/** Amazon Cognito user pool configuration for JWT verification. */
+interface CognitoUserPoolConfig {
+  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
+  userPoolId: string;
+  /**
+   * Which token type to verify.
+   * @default 'access'
+   */
+  tokenUse?: 'access' | 'id';
+  /** The app client ID registered in the User Pool. */
+  clientId: string;
+}
+/**
+ * Authentication options for the MCP router.
+ *
+ * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
+ * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
+ */
+interface McpAuthOptions {
+  /**
+   * Amazon Cognito user pool config. When provided, the router creates a
+   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
+   */
+  cognitoUserPool?: CognitoUserPoolConfig;
+  /**
+   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
+   * Receives the raw Bearer token string. Should resolve with the verified
+   * payload or reject/throw on failure.
+   */
+  verifyToken?: (token: string) => Promise<unknown>;
+  /**
+   * Router-level scope guard. All listed scopes must be present on the token
+   * for any MCP request to be allowed. Returns 403 if any scope is missing.
+   *
+   * Cognito encodes scopes as a space-separated string in `payload.scope`.
+   *
+   * @example ['mcp:access']
+   */
+  requiredScopes?: string[];
+  /**
+   * URL of this MCP server, used in the OAuth Protected Resource Metadata
+   * response (`/.well-known/oauth-protected-resource`). Both this field and
+   * `authorizationServerUrl` must be provided to enable the endpoint.
+   */
+  resourceServerUrl?: string;
+  /**
+   * URL of the OAuth Authorization Server that issues tokens for this resource.
+   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
+   * (RFC 9728) when combined with `resourceServerUrl`.
+   */
+  authorizationServerUrl?: string;
+}
 /**
  * Options for configuring the MCP router
  */
@@ -786,6 +859,38 @@ interface McpRouterOptions {
    * ```
    */
   getApiHeaders?: (ctx: Context$1) => Record<string, string>;
+  /**
+   * OAuth / JWT authentication configuration for the MCP endpoint.
+   *
+   * When set, every incoming MCP request must include a valid Bearer token in
+   * the `Authorization` header. Invalid or missing tokens receive a `401`
+   * response with `WWW-Authenticate: Bearer`. Tokens that fail a
+   * `requiredScopes` check receive `403`.
+   *
+   * The verified token payload is accessible inside tool handlers via
+   * {@link getIdentity}. Fine-grained per-tool scope checks can be done with
+   * {@link checkScopes}.
+   *
+   * @example Cognito
+   * ```typescript
+   * createMcpRouter(server, {
+   *   auth: {
+   *     cognitoUserPool: { userPoolId: 'us-east-1_xxx', clientId: 'yyy' },
+   *     requiredScopes: ['mcp:access'],
+   *   },
+   * });
+   * ```
+   *
+   * @example Custom verifier
+   * ```typescript
+   * createMcpRouter(server, {
+   *   auth: {
+   *     verifyToken: async (token) => myJwtLib.verify(token),
+   *   },
+   * });
+   * ```
+   */
+  auth?: McpAuthOptions;
 }
 /**
  * Creates a Koa router configured to handle MCP protocol requests
@@ -902,4 +1007,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, JsonObjectSchema, McpRouterOptions, type McpServer, RegisterToolFromSchemaParams, apiCall, createMcpRouter, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, type McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { z, z as z$1 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -94,6 +95,80 @@ const apiCall = async (method, url, options) => {
   return response.text();
 };
 /**
+* Returns the verified JWT payload for the current MCP request.
+* Only available inside a tool handler when `auth` is configured on the router.
+*/
+const getIdentity = () => {
+  return requestContextStore.getStore()?.identity;
+};
+/**
+* Asserts that the current request's token contains all required scopes.
+* Throws if any scope is missing — the MCP SDK catches this and returns a
+* tool error to the client. Use inside tool handlers for per-tool authorization.
+*
+* Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+*
+* @example
+* ```typescript
+* server.tool('delete-user', schema, async (args) => {
+*   checkScopes(['admin', 'write:users']);
+*   // proceed only if caller has both scopes
+* });
+* ```
+*/
+const checkScopes = required => {
+  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  if (required.filter(s => {
+    return !tokenScopes.includes(s);
+  }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
+};
+const buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+const registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  router.use(path, async (ctx, next) => {
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", "Bearer");
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (auth.requiredScopes?.length) {
+      const tokenScopes = (identity?.scope ?? "").split(" ");
+      if (auth.requiredScopes.filter(s => {
+        return !tokenScopes.includes(s);
+      }).length > 0) {
+        ctx.status = 403;
+        ctx.body = "Forbidden";
+        return;
+      }
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+/**
 * Creates a Koa router configured to handle MCP protocol requests
 *
 * @param server - The MCP server instance with registered tools and resources
@@ -135,10 +210,11 @@ const createMcpRouter = (server, options = {}) => {
     path = "/mcp",
     sessionIdGenerator,
     apiBaseUrl,
-    getApiHeaders
+    getApiHeaders,
+    auth
   } = options;
   const isStateful = sessionIdGenerator !== void 0;
-  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
   let sharedTransport;
   if (isStateful) {
     sharedTransport = new StreamableHTTPServerTransport({
@@ -156,8 +232,10 @@ const createMcpRouter = (server, options = {}) => {
     return result;
   };
   const router = new Router();
+  if (auth) registerAuthRoutes(router, path, auth, buildTokenVerifier(auth));
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    const identity = ctx.state.identity;
     const runRequest = async transport => {
       await transport.handleRequest(ctx.req, ctx.res, body);
       ctx.respond = false;
@@ -165,7 +243,8 @@ const createMcpRouter = (server, options = {}) => {
     if (isStateful && sharedTransport) {
       if (needsContext) await requestContextStore.run({
         apiBaseUrl,
-        apiHeaders
+        apiHeaders,
+        identity
       }, () => {
         return runRequest(sharedTransport);
       });else await runRequest(sharedTransport);
@@ -178,7 +257,8 @@ const createMcpRouter = (server, options = {}) => {
         await server.connect(transport);
         if (needsContext) await requestContextStore.run({
           apiBaseUrl,
-          apiHeaders
+          apiHeaders,
+          identity
         }, () => {
           return runRequest(transport);
         });else await runRequest(transport);
@@ -299,4 +379,4 @@ const registerToolFromSchema = (server, params) => {
 };
 
 //#endregion
-export { McpServer, apiCall, createMcpRouter, registerToolFromSchema, z };
+export { McpServer, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,6 +35,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
+    "@ttoss/auth-core": "^0.4.13",
     "@ttoss/http-server": "^0.5.14"
   },
   "devDependencies": {