@ttoss/http-server-mcp 0.23.1 → 0.24.1

package/README.md

@@ -593,10 +593,17 @@ Use this when tool definitions are shared between the MCP server and an AI SDK a
 - `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.validateArguments` (`boolean`, optional) — Enforce `inputSchema` on `tools/call` (default: `false`); see [Argument validation](#argument-validation)
 - `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) — Tool handler receiving the raw request arguments
 
 **Returns:** `void`
 
+#### Argument validation
+
+By default, `inputSchema` is **advertised but not enforced**: it round-trips verbatim over `tools/list` so clients know what to send, while arguments reach your handler unchecked. Pass `validateArguments: true` to reject mismatched calls with an MCP error before the handler runs.
+
+Enable it once you're confident `inputSchema` describes every value the tool genuinely accepts. Schemas derived from an OpenAPI document are a common source of _incomplete_ ones — a field a client may send as `null` to clear it, or one that accepts several shapes, is easily emitted as a bare `{ type: 'string' }`. Validating against a schema like that rejects calls the underlying API would have accepted. To describe those cases accurately, use `{ type: ['string', 'null'] }` for a nullable field and forward `oneOf`/`anyOf` verbatim rather than collapsing to one type.
+
 ## Examples
 
 ### Plain JSON Schema Tool (`registerToolFromSchema`)
@@ -787,7 +794,9 @@ app.listen(3000);
 
 ## Protocol Details
 
-This package implements the [Model Context Protocol](https://spec.modelcontextprotocol.io/) over HTTP using JSON responses (no SSE streaming). It uses the `StreamableHTTPServerTransport` from the MCP SDK with `enableJsonResponse: true` and adapts Koa's context-based middleware to work with the MCP SDK's Node.js request/response expectations.
+This package implements the [Model Context Protocol](https://spec.modelcontextprotocol.io/) over HTTP using JSON responses (no SSE streaming), and serves each request over the protocol revision it actually speaks.
+
+Requests are classified once at the boundary. Traffic from today's MCP clients is served over `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, adapting Koa's context-based middleware to the SDK's Node.js request/response expectations. Requests carrying the `2026-07-28` revision's per-request envelope are served by that revision's stateless core (`createMcpHandler`) instead. Both paths are served from the same `McpServer` instance and the same registered tools, so supporting the newer revision requires no configuration.
 
 **Supported HTTP methods:**
 
@@ -812,6 +821,8 @@ If you authenticate with `auth.verifyToken`, you do not need `sessionIdGenerator
 | Stateless (default)             | Bearer/API tokens, serverless, multi-instance | DB/verify hit per request             |
 | Stateful (`sessionIdGenerator`) | SSE events, context-preserving streams        | Needs session affinity / shared state |
 
+The `2026-07-28` revision has no session concept in its core, so requests speaking that revision are always served statelessly regardless of `sessionIdGenerator`.
+
 ## Testing an MCP server
 
 MCP requests are plain JSON-RPC POSTs to the router path. The `initialize` and `tools/list` methods are public by default, so they need no auth header; `tools/call` runs through `auth.verifyToken`. The client must send `Accept: application/json, text/event-stream` — the transport rejects requests that do not accept the event-stream media type.
@@ -864,7 +875,7 @@ Use the default when token auth is handled outside the OAuth flow (Cognito, API
 
 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.
+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, the adapter sitting between Koa and the MCP transport can drop all headers (including `Accept`), making every `initialize` request return HTTP 406.
 
 ```mermaid
 flowchart LR
@@ -913,7 +924,8 @@ Keep the following in mind:
 
 - [@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
+- [@modelcontextprotocol/server](https://github.com/modelcontextprotocol/typescript-sdk) - MCP server SDK (2026-07-28 core)
+- [@modelcontextprotocol/node](https://github.com/modelcontextprotocol/typescript-sdk) - Node.js request/response bridge for the SDK's fetch-based handler
 
 ## Resources
 

package/dist/index.cjs

@@ -2,13 +2,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-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 _ttoss_http_server_auth = require("@ttoss/http-server-auth");
 let node_async_hooks = require("node:async_hooks");
+let _modelcontextprotocol_node = require("@modelcontextprotocol/node");
+let _modelcontextprotocol_server = require("@modelcontextprotocol/server");
 let zod = require("zod");
-let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 
 //#region src/context.ts
 var requestContextStore = new node_async_hooks.AsyncLocalStorage();
@@ -24,30 +24,145 @@ var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
 
+//#endregion
+//#region src/serveMcpRequest.ts
+/**
+* Reads a header as `string | undefined`. Koa's `ctx.get` returns `''` for a
+* missing header, which the classifier would read as "header present but
+* empty" rather than absent.
+*/
+var header = (ctx, name) => {
+  const value = ctx.get(name);
+  return value === "" ? void 0 : value;
+};
+/**
+* Builds the per-request serving function used by `createMcpRouter`, routing
+* each request to the protocol revision it actually speaks.
+*
+* Requests are classified once at the boundary with the SDK's own
+* `classifyInboundRequest`:
+*
+* - **2025-era traffic** (everything without a `2026-07-28` per-request
+*   envelope — which is all traffic from today's MCP clients) is served over
+*   `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, the
+*   same wiring and the same plain-JSON responses this package has always
+*   produced.
+* - **`2026-07-28` traffic** is served by `createMcpHandler` with
+*   `legacy: 'reject'`, so the modern revision is handled by the SDK's
+*   stateless core rather than the transport above. Malformed requests are
+*   routed here too, so the SDK emits its own spec-defined rejection instead of
+*   this package inventing one.
+*
+* Splitting on the classifier — instead of letting `createMcpHandler` serve
+* both eras through its built-in legacy fallback — is what keeps 2025-era
+* responses byte-compatible. That fallback constructs its transport with only
+* `sessionIdGenerator: undefined` and no way to pass `enableJsonResponse`, so
+* every response it produces is SSE-framed (`text/event-stream`) regardless of
+* the handler's `responseMode`. Owning the legacy branch keeps `application/json`.
+*/
+var createMcpRequestServer = ({
+  server,
+  sessionIdGenerator
+}) => {
+  const isStateful = sessionIdGenerator !== void 0;
+  const modernHandler = (0, _modelcontextprotocol_node.toNodeHandler)((0, _modelcontextprotocol_server.createMcpHandler)(() => {
+    return server;
+  }, {
+    legacy: "reject"
+  }));
+  let sharedTransport;
+  if (isStateful) {
+    sharedTransport = new _modelcontextprotocol_node.NodeStreamableHTTPServerTransport({
+      sessionIdGenerator,
+      enableJsonResponse: true
+    });
+    server.connect(sharedTransport);
+  }
+  let statelessQueue = Promise.resolve();
+  const enqueueStateless = work => {
+    const result = statelessQueue.then(() => {
+      return work();
+    });
+    statelessQueue = result.catch(() => {});
+    return result;
+  };
+  const isLegacy = (ctx, body) => {
+    return (0, _modelcontextprotocol_server.classifyInboundRequest)({
+      httpMethod: ctx.method,
+      protocolVersionHeader: header(ctx, "mcp-protocol-version"),
+      mcpMethodHeader: header(ctx, "mcp-method"),
+      mcpNameHeader: header(ctx, "mcp-name"),
+      body
+    }).kind === "legacy";
+  };
+  return async (ctx, body) => {
+    if (!isLegacy(ctx, body)) {
+      await modernHandler(ctx.req, ctx.res, body);
+      return;
+    }
+    if (sharedTransport) {
+      await sharedTransport.handleRequest(ctx.req, ctx.res, body);
+      return;
+    }
+    await enqueueStateless(async () => {
+      const transport = new _modelcontextprotocol_node.NodeStreamableHTTPServerTransport({
+        sessionIdGenerator: void 0,
+        enableJsonResponse: true
+      });
+      try {
+        await server.connect(transport);
+        await transport.handleRequest(ctx.req, ctx.res, body);
+      } finally {
+        await transport.close();
+      }
+    });
+  };
+};
+
 //#endregion
 //#region src/registerToolFromSchema.ts
-var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
-var patchedServerSet = /* @__PURE__ */new WeakSet();
+/**
+* Converts a plain JSON Schema into the Standard Schema `registerTool` accepts.
+*
+* A Standard Schema keeps advertisement and enforcement in separate fields:
+* `~standard.jsonSchema` is what `tools/list` publishes, `~standard.validate`
+* is what `tools/call` runs. Replacing only `validate` therefore keeps the
+* schema fully visible to clients while leaving arguments unchecked.
+*/
+var toStandardSchema = ({
+  inputSchema,
+  validateArguments
+}) => {
+  const schema = (0, _modelcontextprotocol_server.fromJsonSchema)(inputSchema);
+  if (validateArguments) return schema;
+  return {
+    "~standard": {
+      ...schema["~standard"],
+      validate: value => {
+        return {
+          value
+        };
+      }
+    }
+  };
+};
 /**
 * Registers a tool on an MCP server using a **plain JSON Schema** object for
 * `inputSchema` instead of a Zod shape.
 *
-* This is useful when tool definitions are shared between the MCP server and an
-* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
-* plain JSON Schema at runtime. Using this helper eliminates the lossy
+* This is useful when tool definitions are shared between the MCP server and
+* an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
+* a plain JSON Schema at runtime. Using this helper eliminates the lossy
 * JSON-Schema→Zod conversion that would otherwise be required.
 *
-* Internally the helper:
-* 1. Registers the tool via the standard `McpServer.registerTool` API using a
-*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
-*    `tools/call` handler correctly routes requests and delivers raw args to
-*    your handler.
-* 2. Stores the original JSON Schema and patches the `tools/list` response
-*    handler so clients receive the verbatim JSON Schema over the wire.
+* Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
+* converts a JSON Schema into a Standard Schema that `registerTool` accepts
+* directly, so the schema round-trips verbatim over `tools/list`. Arguments
+* reach the handler unchecked unless `validateArguments` is enabled.
 *
 * @param server - The `McpServer` instance to register the tool on.
 * @param params - Tool configuration including name, description, inputSchema,
-*   and handler.
+*   validateArguments, and handler.
 *
 * @example
 * ```typescript
@@ -77,38 +192,18 @@ var registerToolFromSchema = (server, params) => {
       type: "object",
       properties: {}
     },
+    validateArguments = false,
     handler
   } = params;
-  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
-  rawSchemaRegistryMap.get(server).set(name, inputSchema);
   server.registerTool(name, {
     description,
-    inputSchema: zod.z.record(zod.z.string(), zod.z.unknown())
+    inputSchema: toStandardSchema({
+      inputSchema,
+      validateArguments
+    })
   }, async args => {
     return handler(args);
   });
-  if (!patchedServerSet.has(server)) {
-    patchedServerSet.add(server);
-    const rawServer = server.server;
-    const origHandler = rawServer?._requestHandlers?.get("tools/list");
-    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
-    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
-      const result = await origHandler(rawRequest, extra);
-      const schemas = rawSchemaRegistryMap.get(server);
-      if (!schemas) return result;
-      return {
-        ...result,
-        tools: result.tools.map(tool => {
-          const raw = schemas.get(tool.name);
-          if (raw !== void 0) return {
-            ...tool,
-            inputSchema: raw
-          };
-          return tool;
-        })
-      };
-    });
-  }
 };
 
 //#endregion
@@ -427,24 +522,11 @@ var createMcpRouter = (server, options = {}) => {
     getApiHeaders,
     auth
   } = options;
-  const isStateful = sessionIdGenerator !== 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({
-      sessionIdGenerator,
-      enableJsonResponse: true
-    });
-    server.connect(sharedTransport);
-  }
-  let statelessQueue = Promise.resolve();
-  const enqueueStateless = work => {
-    const result = statelessQueue.then(() => {
-      return work();
-    });
-    statelessQueue = result.catch(() => {});
-    return result;
-  };
+  const serveRequest = createMcpRequestServer({
+    server,
+    sessionIdGenerator
+  });
   const router = new _ttoss_http_server.Router();
   let authCheck;
   if (auth) {
@@ -482,36 +564,16 @@ var createMcpRouter = (server, options = {}) => {
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
     const identity = ctx.state.user;
-    const runRequest = async transport => {
-      await transport.handleRequest(ctx.req, ctx.res, body);
+    ctx.req.auth = identity;
+    const runRequest = async () => {
+      await serveRequest(ctx, body);
       ctx.respond = false;
     };
-    if (isStateful && sharedTransport) {
-      if (needsContext) await requestContextStore.run({
-        apiBaseUrl,
-        apiHeaders,
-        identity
-      }, () => {
-        return runRequest(sharedTransport);
-      });else await runRequest(sharedTransport);
-    } else await enqueueStateless(async () => {
-      const transport = new _modelcontextprotocol_sdk_server_streamableHttp_js.StreamableHTTPServerTransport({
-        sessionIdGenerator: void 0,
-        enableJsonResponse: true
-      });
-      try {
-        await server.connect(transport);
-        if (needsContext) await requestContextStore.run({
-          apiBaseUrl,
-          apiHeaders,
-          identity
-        }, () => {
-          return runRequest(transport);
-        });else await runRequest(transport);
-      } finally {
-        await transport.close();
-      }
-    });
+    if (needsContext) await requestContextStore.run({
+      apiBaseUrl,
+      apiHeaders,
+      identity
+    }, runRequest);else await runRequest();
   };
   const postHandler = async ctx => {
     try {
@@ -552,7 +614,7 @@ var createMcpRouter = (server, options = {}) => {
 Object.defineProperty(exports, 'McpServer', {
   enumerable: true,
   get: function () {
-    return _modelcontextprotocol_sdk_server_mcp_js.McpServer;
+    return _modelcontextprotocol_server.McpServer;
   }
 });
 exports.apiCall = apiCall;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
 /// <reference types="node" />
-import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -16,7 +16,6 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
@@ -704,10 +703,28 @@ interface RegisterToolFromSchemaParams {
    * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
    */
   inputSchema?: JsonObjectSchema;
+  /**
+   * Whether `tools/call` arguments are validated against `inputSchema` before
+   * the handler runs, rejecting a mismatch with an MCP error.
+   *
+   * Defaults to `false`, which forwards arguments to the handler unchecked —
+   * the behavior this helper has always had. `inputSchema` is still advertised
+   * verbatim over `tools/list` either way; this only controls enforcement.
+   *
+   * Enable it once you know `inputSchema` describes every value the tool
+   * genuinely accepts. Schemas generated from an OpenAPI document are a common
+   * source of *incomplete* ones — a field a client may send as `null` to clear
+   * it, or one accepting several shapes, is easy to emit as a bare
+   * `{ type: 'string' }`. Validating against a schema like that rejects calls
+   * the underlying API would have accepted.
+   *
+   * @default false
+   */
+  validateArguments?: boolean;
   /**
    * Tool handler invoked when the AI client calls the tool.
-   * Receives the raw request arguments as a plain object (no Zod validation is
-   * applied, so the shape matches whatever the client sends).
+   * Receives the request arguments, validated against `inputSchema` only when
+   * `validateArguments` is enabled.
    */
   handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
 }
@@ -715,22 +732,19 @@ interface RegisterToolFromSchemaParams {
  * Registers a tool on an MCP server using a **plain JSON Schema** object for
  * `inputSchema` instead of a Zod shape.
  *
- * This is useful when tool definitions are shared between the MCP server and an
- * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
- * plain JSON Schema at runtime. Using this helper eliminates the lossy
+ * This is useful when tool definitions are shared between the MCP server and
+ * an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
+ * a plain JSON Schema at runtime. Using this helper eliminates the lossy
  * JSON-Schema→Zod conversion that would otherwise be required.
  *
- * Internally the helper:
- * 1. Registers the tool via the standard `McpServer.registerTool` API using a
- *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
- *    `tools/call` handler correctly routes requests and delivers raw args to
- *    your handler.
- * 2. Stores the original JSON Schema and patches the `tools/list` response
- *    handler so clients receive the verbatim JSON Schema over the wire.
+ * Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
+ * converts a JSON Schema into a Standard Schema that `registerTool` accepts
+ * directly, so the schema round-trips verbatim over `tools/list`. Arguments
+ * reach the handler unchecked unless `validateArguments` is enabled.
  *
  * @param server - The `McpServer` instance to register the tool on.
  * @param params - Tool configuration including name, description, inputSchema,
- *   and handler.
+ *   validateArguments, and handler.
  *
  * @example
  * ```typescript
@@ -1024,6 +1038,10 @@ interface McpRouterOptions {
    * When provided, a single shared transport is created and sessions are tracked.
    * When undefined (default), the server operates in stateless mode where each
    * HTTP request uses its own transport instance.
+   *
+   * Applies to 2025-era traffic. The `2026-07-28` protocol revision has no
+   * session concept in its core, so requests speaking that revision are always
+   * served statelessly regardless of this option.
    */
   sessionIdGenerator?: () => string;
   /**

package/dist/index.d.mts

@@ -2,8 +2,8 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
 import { z } from "zod";
-import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
 import Cookies from "cookies";
@@ -18,7 +18,6 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
 declare interface ContextDelegatedRequest {
@@ -705,10 +704,28 @@ interface RegisterToolFromSchemaParams {
    * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
    */
   inputSchema?: JsonObjectSchema;
+  /**
+   * Whether `tools/call` arguments are validated against `inputSchema` before
+   * the handler runs, rejecting a mismatch with an MCP error.
+   *
+   * Defaults to `false`, which forwards arguments to the handler unchecked —
+   * the behavior this helper has always had. `inputSchema` is still advertised
+   * verbatim over `tools/list` either way; this only controls enforcement.
+   *
+   * Enable it once you know `inputSchema` describes every value the tool
+   * genuinely accepts. Schemas generated from an OpenAPI document are a common
+   * source of *incomplete* ones — a field a client may send as `null` to clear
+   * it, or one accepting several shapes, is easy to emit as a bare
+   * `{ type: 'string' }`. Validating against a schema like that rejects calls
+   * the underlying API would have accepted.
+   *
+   * @default false
+   */
+  validateArguments?: boolean;
   /**
    * Tool handler invoked when the AI client calls the tool.
-   * Receives the raw request arguments as a plain object (no Zod validation is
-   * applied, so the shape matches whatever the client sends).
+   * Receives the request arguments, validated against `inputSchema` only when
+   * `validateArguments` is enabled.
    */
   handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
 }
@@ -716,22 +733,19 @@ interface RegisterToolFromSchemaParams {
  * Registers a tool on an MCP server using a **plain JSON Schema** object for
  * `inputSchema` instead of a Zod shape.
  *
- * This is useful when tool definitions are shared between the MCP server and an
- * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
- * plain JSON Schema at runtime. Using this helper eliminates the lossy
+ * This is useful when tool definitions are shared between the MCP server and
+ * an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
+ * a plain JSON Schema at runtime. Using this helper eliminates the lossy
  * JSON-Schema→Zod conversion that would otherwise be required.
  *
- * Internally the helper:
- * 1. Registers the tool via the standard `McpServer.registerTool` API using a
- *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
- *    `tools/call` handler correctly routes requests and delivers raw args to
- *    your handler.
- * 2. Stores the original JSON Schema and patches the `tools/list` response
- *    handler so clients receive the verbatim JSON Schema over the wire.
+ * Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
+ * converts a JSON Schema into a Standard Schema that `registerTool` accepts
+ * directly, so the schema round-trips verbatim over `tools/list`. Arguments
+ * reach the handler unchecked unless `validateArguments` is enabled.
  *
  * @param server - The `McpServer` instance to register the tool on.
  * @param params - Tool configuration including name, description, inputSchema,
- *   and handler.
+ *   validateArguments, and handler.
  *
  * @example
  * ```typescript
@@ -1025,6 +1039,10 @@ interface McpRouterOptions {
    * When provided, a single shared transport is created and sessions are tracked.
    * When undefined (default), the server operates in stateless mode where each
    * HTTP request uses its own transport instance.
+   *
+   * Applies to 2025-era traffic. The `2026-07-28` protocol revision has no
+   * session concept in its core, so requests speaking that revision are always
+   * served statelessly regardless of this option.
    */
   sessionIdGenerator?: () => string;
   /**

package/dist/index.mjs

@@ -1,11 +1,11 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { z, z as z$1 } from "zod";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { NodeStreamableHTTPServerTransport, toNodeHandler } from "@modelcontextprotocol/node";
+import { McpServer, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
+import { z } from "zod";
 
 //#region src/context.ts
 var requestContextStore = new AsyncLocalStorage();
@@ -21,30 +21,145 @@ var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
 
+//#endregion
+//#region src/serveMcpRequest.ts
+/**
+* Reads a header as `string | undefined`. Koa's `ctx.get` returns `''` for a
+* missing header, which the classifier would read as "header present but
+* empty" rather than absent.
+*/
+var header = (ctx, name) => {
+  const value = ctx.get(name);
+  return value === "" ? void 0 : value;
+};
+/**
+* Builds the per-request serving function used by `createMcpRouter`, routing
+* each request to the protocol revision it actually speaks.
+*
+* Requests are classified once at the boundary with the SDK's own
+* `classifyInboundRequest`:
+*
+* - **2025-era traffic** (everything without a `2026-07-28` per-request
+*   envelope — which is all traffic from today's MCP clients) is served over
+*   `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, the
+*   same wiring and the same plain-JSON responses this package has always
+*   produced.
+* - **`2026-07-28` traffic** is served by `createMcpHandler` with
+*   `legacy: 'reject'`, so the modern revision is handled by the SDK's
+*   stateless core rather than the transport above. Malformed requests are
+*   routed here too, so the SDK emits its own spec-defined rejection instead of
+*   this package inventing one.
+*
+* Splitting on the classifier — instead of letting `createMcpHandler` serve
+* both eras through its built-in legacy fallback — is what keeps 2025-era
+* responses byte-compatible. That fallback constructs its transport with only
+* `sessionIdGenerator: undefined` and no way to pass `enableJsonResponse`, so
+* every response it produces is SSE-framed (`text/event-stream`) regardless of
+* the handler's `responseMode`. Owning the legacy branch keeps `application/json`.
+*/
+var createMcpRequestServer = ({
+  server,
+  sessionIdGenerator
+}) => {
+  const isStateful = sessionIdGenerator !== void 0;
+  const modernHandler = toNodeHandler(createMcpHandler(() => {
+    return server;
+  }, {
+    legacy: "reject"
+  }));
+  let sharedTransport;
+  if (isStateful) {
+    sharedTransport = new NodeStreamableHTTPServerTransport({
+      sessionIdGenerator,
+      enableJsonResponse: true
+    });
+    server.connect(sharedTransport);
+  }
+  let statelessQueue = Promise.resolve();
+  const enqueueStateless = work => {
+    const result = statelessQueue.then(() => {
+      return work();
+    });
+    statelessQueue = result.catch(() => {});
+    return result;
+  };
+  const isLegacy = (ctx, body) => {
+    return classifyInboundRequest({
+      httpMethod: ctx.method,
+      protocolVersionHeader: header(ctx, "mcp-protocol-version"),
+      mcpMethodHeader: header(ctx, "mcp-method"),
+      mcpNameHeader: header(ctx, "mcp-name"),
+      body
+    }).kind === "legacy";
+  };
+  return async (ctx, body) => {
+    if (!isLegacy(ctx, body)) {
+      await modernHandler(ctx.req, ctx.res, body);
+      return;
+    }
+    if (sharedTransport) {
+      await sharedTransport.handleRequest(ctx.req, ctx.res, body);
+      return;
+    }
+    await enqueueStateless(async () => {
+      const transport = new NodeStreamableHTTPServerTransport({
+        sessionIdGenerator: void 0,
+        enableJsonResponse: true
+      });
+      try {
+        await server.connect(transport);
+        await transport.handleRequest(ctx.req, ctx.res, body);
+      } finally {
+        await transport.close();
+      }
+    });
+  };
+};
+
 //#endregion
 //#region src/registerToolFromSchema.ts
-var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
-var patchedServerSet = /* @__PURE__ */new WeakSet();
+/**
+* Converts a plain JSON Schema into the Standard Schema `registerTool` accepts.
+*
+* A Standard Schema keeps advertisement and enforcement in separate fields:
+* `~standard.jsonSchema` is what `tools/list` publishes, `~standard.validate`
+* is what `tools/call` runs. Replacing only `validate` therefore keeps the
+* schema fully visible to clients while leaving arguments unchecked.
+*/
+var toStandardSchema = ({
+  inputSchema,
+  validateArguments
+}) => {
+  const schema = fromJsonSchema(inputSchema);
+  if (validateArguments) return schema;
+  return {
+    "~standard": {
+      ...schema["~standard"],
+      validate: value => {
+        return {
+          value
+        };
+      }
+    }
+  };
+};
 /**
 * Registers a tool on an MCP server using a **plain JSON Schema** object for
 * `inputSchema` instead of a Zod shape.
 *
-* This is useful when tool definitions are shared between the MCP server and an
-* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
-* plain JSON Schema at runtime. Using this helper eliminates the lossy
+* This is useful when tool definitions are shared between the MCP server and
+* an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
+* a plain JSON Schema at runtime. Using this helper eliminates the lossy
 * JSON-Schema→Zod conversion that would otherwise be required.
 *
-* Internally the helper:
-* 1. Registers the tool via the standard `McpServer.registerTool` API using a
-*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
-*    `tools/call` handler correctly routes requests and delivers raw args to
-*    your handler.
-* 2. Stores the original JSON Schema and patches the `tools/list` response
-*    handler so clients receive the verbatim JSON Schema over the wire.
+* Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
+* converts a JSON Schema into a Standard Schema that `registerTool` accepts
+* directly, so the schema round-trips verbatim over `tools/list`. Arguments
+* reach the handler unchecked unless `validateArguments` is enabled.
 *
 * @param server - The `McpServer` instance to register the tool on.
 * @param params - Tool configuration including name, description, inputSchema,
-*   and handler.
+*   validateArguments, and handler.
 *
 * @example
 * ```typescript
@@ -74,38 +189,18 @@ var registerToolFromSchema = (server, params) => {
       type: "object",
       properties: {}
     },
+    validateArguments = false,
     handler
   } = params;
-  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
-  rawSchemaRegistryMap.get(server).set(name, inputSchema);
   server.registerTool(name, {
     description,
-    inputSchema: z$1.record(z$1.string(), z$1.unknown())
+    inputSchema: toStandardSchema({
+      inputSchema,
+      validateArguments
+    })
   }, async args => {
     return handler(args);
   });
-  if (!patchedServerSet.has(server)) {
-    patchedServerSet.add(server);
-    const rawServer = server.server;
-    const origHandler = rawServer?._requestHandlers?.get("tools/list");
-    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
-    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
-      const result = await origHandler(rawRequest, extra);
-      const schemas = rawSchemaRegistryMap.get(server);
-      if (!schemas) return result;
-      return {
-        ...result,
-        tools: result.tools.map(tool => {
-          const raw = schemas.get(tool.name);
-          if (raw !== void 0) return {
-            ...tool,
-            inputSchema: raw
-          };
-          return tool;
-        })
-      };
-    });
-  }
 };
 
 //#endregion
@@ -424,24 +519,11 @@ var createMcpRouter = (server, options = {}) => {
     getApiHeaders,
     auth
   } = options;
-  const isStateful = sessionIdGenerator !== void 0;
   const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
-  let sharedTransport;
-  if (isStateful) {
-    sharedTransport = new StreamableHTTPServerTransport({
-      sessionIdGenerator,
-      enableJsonResponse: true
-    });
-    server.connect(sharedTransport);
-  }
-  let statelessQueue = Promise.resolve();
-  const enqueueStateless = work => {
-    const result = statelessQueue.then(() => {
-      return work();
-    });
-    statelessQueue = result.catch(() => {});
-    return result;
-  };
+  const serveRequest = createMcpRequestServer({
+    server,
+    sessionIdGenerator
+  });
   const router = new Router();
   let authCheck;
   if (auth) {
@@ -479,36 +561,16 @@ var createMcpRouter = (server, options = {}) => {
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
     const identity = ctx.state.user;
-    const runRequest = async transport => {
-      await transport.handleRequest(ctx.req, ctx.res, body);
+    ctx.req.auth = identity;
+    const runRequest = async () => {
+      await serveRequest(ctx, body);
       ctx.respond = false;
     };
-    if (isStateful && sharedTransport) {
-      if (needsContext) await requestContextStore.run({
-        apiBaseUrl,
-        apiHeaders,
-        identity
-      }, () => {
-        return runRequest(sharedTransport);
-      });else await runRequest(sharedTransport);
-    } else await enqueueStateless(async () => {
-      const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: void 0,
-        enableJsonResponse: true
-      });
-      try {
-        await server.connect(transport);
-        if (needsContext) await requestContextStore.run({
-          apiBaseUrl,
-          apiHeaders,
-          identity
-        }, () => {
-          return runRequest(transport);
-        });else await runRequest(transport);
-      } finally {
-        await transport.close();
-      }
-    });
+    if (needsContext) await requestContextStore.run({
+      apiBaseUrl,
+      apiHeaders,
+      identity
+    }, runRequest);else await runRequest();
   };
   const postHandler = async ctx => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -33,11 +33,12 @@
     "dist"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.12.0",
-    "@ttoss/http-server": "^0.7.1",
-    "@ttoss/http-server-auth": "^0.5.0"
+    "@ttoss/auth-core": "^0.13.0",
+    "@ttoss/http-server-auth": "^0.6.0",
+    "@ttoss/http-server": "^0.7.1"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",
@@ -46,9 +47,6 @@
     "tsdown": "^0.22.2",
     "@ttoss/config": "^1.37.17"
   },
-  "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true