@ttoss/http-server-mcp 0.16.5 → 0.17.1

package/README.md

@@ -641,21 +641,23 @@ This package implements the [Model Context Protocol](https://spec.modelcontextpr
 
 ## AWS Lambda Deployment
 
-The default **stateless** mode (see [Stateless vs stateful mode](#stateless-vs-stateful-mode)) is built for serverless: a fresh transport is created per request, nothing is kept in memory between invocations, and responses are plain JSON (no SSE) — exactly the request/response shape API Gateway and Lambda Function URLs expect. Because the router is a regular Koa app, you wrap it with any Koa-to-Lambda adapter (e.g. [`serverless-http`](https://github.com/dougmoscrop/serverless-http)) and front it with an HTTP API Gateway or a Function URL.
+The default **stateless** mode (see [Stateless vs stateful mode](#stateless-vs-stateful-mode)) is built for serverless: a fresh transport is created per request, nothing is kept in memory between invocations, and responses are plain JSON (no SSE) — exactly the request/response shape API Gateway and Lambda Function URLs expect.
+
+Use [`@ttoss/http-server-serverless`](https://github.com/ttoss/ttoss/tree/main/packages/http-server-serverless) as the Lambda adapter. It wraps `serverless-http` and additionally populates `req.rawHeaders` from the API Gateway event before the request reaches Koa. Without this step, `@hono/node-server` — used internally by the MCP transport — drops all headers (including `Accept`) and every `initialize` request returns HTTP 406.
 
 ```mermaid
 flowchart LR
     Client[MCP Client] -->|POST /mcp| GW[API Gateway / Function URL]
     GW --> L[Lambda]
     subgraph L[Lambda]
-        H[serverless-http handler] --> App[Koa App + createMcpRouter]
+        H[toLambdaHandler] -->|rawHeaders populated| App[Koa App + createMcpRouter]
     end
 ```
 
 ```typescript
-import serverless from 'serverless-http';
 import { App, bodyParser } from '@ttoss/http-server';
 import { createMcpRouter, McpServer, z } from '@ttoss/http-server-mcp';
+import { toLambdaHandler } from '@ttoss/http-server-serverless';
 
 const mcpServer = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });
 
@@ -675,7 +677,7 @@ app.use(bodyParser());
 // Stateless by default — no sessionIdGenerator
 app.use(createMcpRouter(mcpServer).routes());
 
-export const handler = serverless(app.callback());
+export const handler = toLambdaHandler(app);
 ```
 
 Keep the following in mind:
@@ -689,6 +691,7 @@ Keep the following in mind:
 ## Related Packages
 
 - [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server) - HTTP server foundation
+- [@ttoss/http-server-serverless](https://github.com/ttoss/ttoss/tree/main/packages/http-server-serverless) - AWS Lambda adapter (required for MCP on Lambda)
 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
 
 ## Resources

package/dist/index.cjs

@@ -126,7 +126,9 @@ var getIdentity = () => {
 * 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`.
+* Accepts either `scope: string` (space-separated, standard JWT claim) or
+* `scopes: string[]` from `verifyToken`. If neither is present and `required`
+* is non-empty, throws with a descriptive message instead of a silent 403.
 *
 * @example
 * ```typescript
@@ -137,7 +139,13 @@ var getIdentity = () => {
 * ```
 */
 var checkScopes = required => {
-  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  const identity = getIdentity();
+  let scopeString = null;
+  if (typeof identity?.scope === "string") scopeString = identity.scope;else if (Array.isArray(identity?.scopes) && identity.scopes.every(s => {
+    return typeof s === "string";
+  })) scopeString = identity.scopes.join(" ");
+  if (scopeString === null && required.length > 0) throw new Error(`verifyToken returned no scope/scopes but requiredScopes is set (${required.join(", ")}). Return either scope: string or scopes: string[] from verifyToken.`);
+  const tokenScopes = scopeString ? scopeString.split(" ") : [];
   if (required.filter(s => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);

package/dist/index.d.cts

@@ -692,7 +692,11 @@ interface McpAuthOptions {
    * JWTs, opaque tokens). Resolve with the verified payload, or throw to reject.
    */
   verifyToken?: (token: string) => Promise<unknown>;
-  /** Scopes that must all be present on the token's `scope` claim, else `403`. */
+  /**
+   * Scopes that must all be present on the token, else `403`.
+   * `verifyToken` may return either `scope: string` (space-separated) or
+   * `scopes: string[]`; both are normalised internally.
+   */
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
@@ -793,7 +797,9 @@ declare const getIdentity: () => unknown;
  * 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`.
+ * Accepts either `scope: string` (space-separated, standard JWT claim) or
+ * `scopes: string[]` from `verifyToken`. If neither is present and `required`
+ * is non-empty, throws with a descriptive message instead of a silent 403.
  *
  * @example
  * ```typescript

package/dist/index.d.mts

@@ -692,7 +692,11 @@ interface McpAuthOptions {
    * JWTs, opaque tokens). Resolve with the verified payload, or throw to reject.
    */
   verifyToken?: (token: string) => Promise<unknown>;
-  /** Scopes that must all be present on the token's `scope` claim, else `403`. */
+  /**
+   * Scopes that must all be present on the token, else `403`.
+   * `verifyToken` may return either `scope: string` (space-separated) or
+   * `scopes: string[]`; both are normalised internally.
+   */
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
@@ -793,7 +797,9 @@ declare const getIdentity: () => unknown;
  * 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`.
+ * Accepts either `scope: string` (space-separated, standard JWT claim) or
+ * `scopes: string[]` from `verifyToken`. If neither is present and `required`
+ * is non-empty, throws with a descriptive message instead of a silent 403.
  *
  * @example
  * ```typescript

package/dist/index.mjs

@@ -123,7 +123,9 @@ var getIdentity = () => {
 * 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`.
+* Accepts either `scope: string` (space-separated, standard JWT claim) or
+* `scopes: string[]` from `verifyToken`. If neither is present and `required`
+* is non-empty, throws with a descriptive message instead of a silent 403.
 *
 * @example
 * ```typescript
@@ -134,7 +136,13 @@ var getIdentity = () => {
 * ```
 */
 var checkScopes = required => {
-  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  const identity = getIdentity();
+  let scopeString = null;
+  if (typeof identity?.scope === "string") scopeString = identity.scope;else if (Array.isArray(identity?.scopes) && identity.scopes.every(s => {
+    return typeof s === "string";
+  })) scopeString = identity.scopes.join(" ");
+  if (scopeString === null && required.length > 0) throw new Error(`verifyToken returned no scope/scopes but requiredScopes is set (${required.join(", ")}). Return either scope: string or scopes: string[] from verifyToken.`);
+  const tokenScopes = scopeString ? scopeString.split(" ") : [];
   if (required.filter(s => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.16.5",
+  "version": "0.17.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -36,7 +36,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
     "@ttoss/auth-core": "^0.7.0",
-    "@ttoss/http-server-auth": "^0.3.3",
+    "@ttoss/http-server-auth": "^0.3.4",
     "@ttoss/http-server": "^0.7.1"
   },
   "devDependencies": {