feat(@mcp/express): mcpExpressHandler mount helper (handleHttp-backed)

packages/middleware/express/package.json

@@ -43,6 +43,7 @@
         "test:watch": "vitest"
     },
     "dependencies": {
+        "@hono/node-server": "catalog:runtimeServerOnly",
         "cors": "catalog:runtimeServerOnly"
     },
     "peerDependencies": {

packages/middleware/express/src/express.ts

@@ -1,8 +1,42 @@
-import type { Express } from 'express';
+import { getRequestListener } from '@hono/node-server';
+import type { AuthInfo, Dispatchable, HandleHttpOptions } from '@modelcontextprotocol/server';
+import { handleHttp } from '@modelcontextprotocol/server';
+import type { Express, RequestHandler } from 'express';
 import express from 'express';
 
 import { hostHeaderValidation, localhostHostValidation } from './middleware/hostHeaderValidation.js';
 
+/**
+ * Mounts an `McpServer` (or any `Protocol` subclass) as an Express `RequestHandler`.
+ * Each request flows through `mcp.dispatch()` directly via {@linkcode handleHttp};
+ * `mcp.connect()` and a transport instance are not used.
+ *
+ * Reads `req.auth` (set by {@linkcode index.requireBearerAuth | requireBearerAuth}) and `req.body` (set by
+ * `express.json()`, which {@linkcode createMcpExpressApp} installs by default).
+ *
+ * ```ts
+ * import { McpServer, SessionCompat } from '@modelcontextprotocol/server';
+ * import { createMcpExpressApp, mcpExpressHandler } from '@modelcontextprotocol/express';
+ *
+ * const mcp = new McpServer({ name: 's', version: '1.0.0' });
+ * const app = createMcpExpressApp();
+ * app.all('/mcp', mcpExpressHandler(mcp, { session: new SessionCompat() }));
+ * ```
+ */
+export function mcpExpressHandler(mcp: Dispatchable, options?: HandleHttpOptions): RequestHandler {
+    const handler = handleHttp(mcp, options);
+    return (req, res, _next) => {
+        void _next;
+        const authInfo = (req as { auth?: AuthInfo }).auth;
+        const parsedBody: unknown = req.body;
+        const extra = authInfo !== undefined || parsedBody !== undefined ? { authInfo, parsedBody } : undefined;
+        // overrideGlobalObjects: false keeps the native Response prototype intact for frameworks
+        // that subclass it (e.g. Next.js).
+        const listener = getRequestListener(webReq => handler(webReq, extra), { overrideGlobalObjects: false });
+        void listener(req, res);
+    };
+}
+
 /**
  * Options for creating an MCP Express application.
  */

packages/middleware/express/test/express.test.ts

@@ -1,9 +1,19 @@
 import type { NextFunction, Request, Response } from 'express';
+import supertest from 'supertest';
 import { vi } from 'vitest';
 
-import { createMcpExpressApp } from '../src/express.js';
+import { McpServer, SessionCompat } from '@modelcontextprotocol/server';
+
+import { createMcpExpressApp, mcpExpressHandler } from '../src/express.js';
 import { hostHeaderValidation, localhostHostValidation } from '../src/middleware/hostHeaderValidation.js';
 
+const INIT_MESSAGE = {
+    jsonrpc: '2.0',
+    method: 'initialize',
+    params: { clientInfo: { name: 'test-client', version: '1.0' }, protocolVersion: '2025-11-25', capabilities: {} },
+    id: 'init-1'
+};
+
 // Helper to create mock Express request/response/next
 function createMockReqResNext(host?: string) {
     const req = {
@@ -189,4 +199,44 @@ describe('@modelcontextprotocol/express', () => {
             expect(app).toBeDefined();
         });
     });
+
+    describe('mcpExpressHandler', () => {
+        function makeApp(options?: Parameters<typeof mcpExpressHandler>[1]) {
+            const mcp = new McpServer({ name: 'test-server', version: '1.0.0' });
+            const app = createMcpExpressApp({ host: '0.0.0.0', allowedHosts: ['127.0.0.1'] });
+            app.all('/mcp', mcpExpressHandler(mcp, { enableJsonResponse: true, ...options }));
+            return app;
+        }
+
+        test('serves initialize via mcp.dispatch() (stateless, no transport class)', async () => {
+            const res = await supertest(makeApp())
+                .post('/mcp')
+                .set('Accept', 'application/json, text/event-stream')
+                .set('Host', '127.0.0.1')
+                .send(INIT_MESSAGE);
+            expect(res.status).toBe(200);
+            expect(res.body.result).toMatchObject({ serverInfo: { name: 'test-server' } });
+            expect(res.headers['mcp-session-id']).toBeUndefined();
+        });
+
+        test('serves session lifecycle via SessionCompat', async () => {
+            const app = makeApp({ session: new SessionCompat() });
+            const initRes = await supertest(app)
+                .post('/mcp')
+                .set('Accept', 'application/json, text/event-stream')
+                .set('Host', '127.0.0.1')
+                .send(INIT_MESSAGE);
+            const sid = initRes.headers['mcp-session-id'] as string;
+            expect(sid).toBeTruthy();
+            const pingRes = await supertest(app)
+                .post('/mcp')
+                .set('Accept', 'application/json, text/event-stream')
+                .set('Host', '127.0.0.1')
+                .set('mcp-session-id', sid)
+                .set('mcp-protocol-version', '2025-11-25')
+                .send({ jsonrpc: '2.0', method: 'ping', params: {}, id: 'p-1' });
+            expect(pingRes.status).toBe(200);
+            expect(pingRes.body).toMatchObject({ jsonrpc: '2.0', id: 'p-1', result: {} });
+        });
+    });
 });