feat(server): handleHttp() per-request entry, SessionCompat, dual-conformance

Adds handleHttp(mcp): (Request) => Promise<Response> for stateless/serverless deployment, driven by Protocol.dispatch(). SessionCompat is opt-in 2025-11 mcp-session-id lifecycle. toNodeHttpHandler adapts to Node http.

SSE Last-Event-ID resumption is bound to the issuing session: the streamId is per-session (per-POST UUID or _GET_stream:<sessionId>), tracked in SessionCompat, and replayEvents rejects event IDs that don't belong to the requesting session. Requires EventStore.getStreamIdForEventId.

Dual conformance: CI runs the same suite against both connect(transport) and handleHttp() entry points (40/40 each).

Author: felixweinberger

package.json

@@ -42,6 +42,8 @@
         "test:conformance:server": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server",
         "test:conformance:server:all": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:all",
         "test:conformance:server:run": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:run",
+        "test:conformance:server:handlehttp": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:handlehttp",
+        "test:conformance:server:dual": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:dual",
         "test:conformance:all": "pnpm run test:conformance:client:all && pnpm run test:conformance:server:all"
     },
     "devDependencies": {

packages/core/src/shared/protocol.ts

@@ -8,6 +8,7 @@
 
 import { SdkError, SdkErrorCode } from '../errors/sdkErrors.js';
 import type {
+    JSONRPCNotification,
     JSONRPCRequest,
     MessageExtraInfo,
     Notification,
@@ -179,6 +180,14 @@ export abstract class Protocol<ContextT extends BaseContext> {
         return this._dispatcher.dispatch(request, env);
     }
 
+    /**
+     * Dispatch one inbound notification to its registered handler. Transport-free
+     * counterpart to {@linkcode Protocol.dispatch}; consumed by `handleHttp`.
+     */
+    dispatchNotification(notification: JSONRPCNotification): Promise<void> {
+        return this._dispatcher.dispatchNotification(notification);
+    }
+
     /**
      * Registers a handler to invoke when this protocol object receives a request with the given method.
      *

packages/middleware/node/src/streamableHttp.ts

@@ -21,6 +21,35 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
  */
 export type StreamableHTTPServerTransportOptions = WebStandardStreamableHTTPServerTransportOptions;
 
+/**
+ * Converts a web-standard `(Request) => Response` handler into a Node.js
+ * `(IncomingMessage, ServerResponse) => void` handler suitable for express,
+ * `http.createServer`, etc.
+ *
+ * The third parameter (express's `next`) is accepted for middleware compatibility but
+ * not invoked; errors are written to the response (`@hono/node-server` swallows handler
+ * rejections internally). Auth info is read from `req.auth`; a pre-parsed body is read from `req.body`
+ * (e.g. when `express.json()` ran before this handler).
+ *
+ * ```ts
+ * import { handleHttp } from '@modelcontextprotocol/server';
+ * import { toNodeHttpHandler } from '@modelcontextprotocol/node';
+ *
+ * app.all('/mcp', toNodeHttpHandler(handleHttp(mcp, { session })));
+ * ```
+ */
+export function toNodeHttpHandler(
+    handler: (req: Request, extra?: { authInfo?: AuthInfo; parsedBody?: unknown }) => Response | Promise<Response>
+): (req: IncomingMessage & { auth?: AuthInfo; body?: unknown }, res: ServerResponse, next?: (err?: unknown) => void) => Promise<void> {
+    return async (req, res, _next) => {
+        void _next;
+        const parsedBody = req.body;
+        const extra = req.auth !== undefined || parsedBody !== undefined ? { authInfo: req.auth, parsedBody } : undefined;
+        const listener = getRequestListener(webReq => handler(webReq, extra), { overrideGlobalObjects: false });
+        await listener(req, res);
+    };
+}
+
 /**
  * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
  * It supports both SSE streaming and direct HTTP responses.

packages/middleware/node/test/streamableHttp.test.ts

@@ -18,7 +18,31 @@ import { listenOnRandomPort } from '@modelcontextprotocol/test-helpers';
 import * as z from 'zod/v4';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { NodeStreamableHTTPServerTransport } from '../src/streamableHttp.js';
+import { NodeStreamableHTTPServerTransport, toNodeHttpHandler } from '../src/streamableHttp.js';
+
+describe('toNodeHttpHandler', () => {
+    it('does not treat express next() as parsedBody; reads req.body instead', async () => {
+        let capturedExtra: { parsedBody?: unknown } | undefined;
+        const handler = toNodeHttpHandler(async (_req, extra) => {
+            capturedExtra = extra;
+            return Response.json({ ok: true });
+        });
+        const port = await getFreePort();
+        const server = createServer((req, res) => {
+            (req as IncomingMessage & { body?: unknown }).body = { jsonrpc: '2.0', method: 'ping', id: 1 };
+            // Express-style call: third arg is the next() function.
+            void handler(req as IncomingMessage & { auth?: AuthInfo; body?: unknown }, res, () => {});
+        });
+        await new Promise<void>(r => server.listen(port, r));
+        try {
+            await fetch(`http://localhost:${port}/`, { method: 'POST' });
+            expect(capturedExtra?.parsedBody).toEqual({ jsonrpc: '2.0', method: 'ping', id: 1 });
+            expect(typeof capturedExtra?.parsedBody).not.toBe('function');
+        } finally {
+            await new Promise<void>(r => server.close(() => r()));
+        }
+    });
+});
 
 async function getFreePort() {
     return new Promise(res => {

packages/server/src/index.ts

@@ -31,6 +31,10 @@ export { Server } from './server/server.js';
 // StdioServerTransport is exported from the './stdio' subpath — server stdio has only type-level Node
 // imports (erased at compile time), but matching the client's `./stdio` subpath gives consumers a
 // consistent shape across packages.
+export type { Dispatchable, HandleHttpOptions, HandleHttpRequestExtra } from './server/handleHttp.js';
+export { handleHttp } from './server/handleHttp.js';
+export type { SessionCompatOptions, SessionValidation } from './server/sessionCompat.js';
+export { SessionCompat } from './server/sessionCompat.js';
 export type {
     EventId,
     EventStore,

packages/server/src/server/handleHttp.ts

@@ -0,0 +1,51 @@
+import type { DispatchOutput, JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, RequestEnv } from '@modelcontextprotocol/core';
+
+import type { ShttpHandlerOptions, ShttpRequestExtra } from './shttpHandler.js';
+import { shttpHandler } from './shttpHandler.js';
+
+async function* unwrap(gen: AsyncIterable<DispatchOutput>): AsyncGenerator<JSONRPCMessage, void, void> {
+    for await (const out of gen) yield out.message;
+}
+
+/**
+ * Minimal contract {@linkcode handleHttp} requires. Satisfied by `McpServer`,
+ * `Server`, and any `Protocol` subclass.
+ */
+export interface Dispatchable {
+    dispatch(request: JSONRPCRequest, env?: RequestEnv): AsyncIterable<DispatchOutput>;
+    dispatchNotification(notification: JSONRPCNotification): Promise<void>;
+}
+
+/**
+ * Mounts an `McpServer` (or any `Protocol`) as a web-standard
+ * `(Request) => Response` handler. Use this to drive a server from an HTTP framework
+ * without instantiating a transport class:
+ *
+ * ```ts
+ * import { McpServer, handleHttp, SessionCompat } from '@modelcontextprotocol/server';
+ * import { toNodeHttpHandler } from '@modelcontextprotocol/node';
+ *
+ * const mcp = new McpServer({ name: 's', version: '1.0.0' });
+ * mcp.tool('search', schema, handler);
+ *
+ * app.all('/mcp', toNodeHttpHandler(handleHttp(mcp, { session: new SessionCompat() })));
+ * ```
+ *
+ * `mcp.connect(transport)` is not called; each HTTP request flows through
+ * `mcp.dispatch()` directly. Supply a `SessionCompat` via `options.session`
+ * to serve clients that send `Mcp-Session-Id` (the pre-2026-06 stateful flow).
+ */
+export function handleHttp(
+    mcp: Dispatchable,
+    options: ShttpHandlerOptions = {}
+): (req: Request, extra?: ShttpRequestExtra) => Promise<Response> {
+    return shttpHandler(
+        {
+            onrequest: (req, env?: RequestEnv) => unwrap(mcp.dispatch(req, env)),
+            onnotification: n => mcp.dispatchNotification(n)
+        },
+        options
+    );
+}
+
+export { type ShttpHandlerOptions as HandleHttpOptions, type ShttpRequestExtra as HandleHttpRequestExtra } from './shttpHandler.js';

packages/server/src/server/mcp.ts

@@ -6,15 +6,19 @@ import type {
     CompleteRequestResourceTemplate,
     CompleteResult,
     CreateTaskResult,
+    DispatchOutput,
     GetPromptResult,
     Implementation,
+    JSONRPCNotification,
+    JSONRPCRequest,
     ListPromptsResult,
     ListResourcesResult,
     ListToolsResult,
     LoggingMessageNotification,
     Prompt,
     PromptReference,
     ReadResourceResult,
+    RequestEnv,
     Resource,
     ResourceTemplateReference,
     Result,
@@ -111,6 +115,19 @@ export class McpServer {
         return await this.server.connect(transport);
     }
 
+    /**
+     * Transport-free per-request entry; forwards to {@linkcode Server}`.dispatch`.
+     * Exposed so `handleHttp(mcp, ...)` accepts an {@linkcode McpServer} directly.
+     */
+    dispatch(request: JSONRPCRequest, env?: RequestEnv): AsyncGenerator<DispatchOutput, void, void> {
+        return this.server.dispatch(request, env);
+    }
+
+    /** Forwards to {@linkcode Server}`.dispatchNotification` for the `handleHttp` path. */
+    dispatchNotification(notification: JSONRPCNotification): Promise<void> {
+        return this.server.dispatchNotification(notification);
+    }
+
     /**
      * Closes the connection.
      */