[v2] Decouple server from express and hono - http framework-agnostic MCP server (modelcontextprotocol#1326)

Author: KKonstantinov

.github/workflows/publish.yml

@@ -38,4 +38,6 @@ jobs:
               run: pnpm run build:all
 
             - name: Publish preview packages
-              run: pnpm dlx pkg-pr-new publish --packageManager=npm --pnpm './packages/server' './packages/client'
+              run:
+                  pnpm dlx pkg-pr-new publish --packageManager=npm --pnpm './packages/server' './packages/client'
+                  './packages/middleware/express' './packages/middleware/hono' './packages/middleware/node'

.gitignore

@@ -133,6 +133,7 @@ dist/
 
 # IDE
 .idea/
+.cursor/
 
 # Conformance test results
 results/

CLAUDE.md

@@ -64,11 +64,15 @@ Transports (`packages/core/src/shared/transport.ts`) provide the communication l
 ### Client-Side Features
 
 - **Auth**: OAuth client support in `packages/client/src/client/auth.ts` and `packages/client/src/client/auth-extensions.ts`
-- **Middleware**: Request middleware in `packages/client/src/client/middleware.ts`
+- **Client middleware**: Request middleware in `packages/client/src/client/middleware.ts` (unrelated to the framework adapter packages below)
 - **Sampling**: Clients can handle `sampling/createMessage` requests from servers (LLM completions)
 - **Elicitation**: Clients can handle `elicitation/create` requests for user input (form or URL mode)
 - **Roots**: Clients can expose filesystem roots to servers via `roots/list`
 
+### Middleware packages (framework/runtime adapters)
+
+The repo also ships “middleware” packages under `packages/middleware/` (e.g. `@modelcontextprotocol/express`, `@modelcontextprotocol/hono`, `@modelcontextprotocol/node`). These are thin integration layers for specific frameworks/runtimes and should not add new MCP functionality.
+
 ### Experimental Features
 
 Located in `packages/*/src/experimental/`:
@@ -224,7 +228,8 @@ mcpServer.tool('tool-name', { param: z.string() }, async ({ param }, extra) => {
 
 ```typescript
 // Server
-const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+// (Node.js IncomingMessage/ServerResponse wrapper; exported by @modelcontextprotocol/node)
+const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
 await server.connect(transport);
 
 // Client

common/eslint-config/eslint.config.mjs

@@ -47,6 +47,7 @@ export default defineConfig(
             '@typescript-eslint/consistent-type-imports': ['error', { disallowTypeAnnotations: false }],
             'simple-import-sort/imports': 'warn',
             'simple-import-sort/exports': 'warn',
+            'import/consistent-type-specifier-style': ['error', 'prefer-top-level'],
             'import/no-extraneous-dependencies': [
                 'error',
                 {

common/vitest-config/vitest.config.js

@@ -15,10 +15,10 @@ export default defineConfig({
         deps: {
             moduleDirectories: ['node_modules', path.resolve(__dirname, '../../packages'), path.resolve(__dirname, '../../common')]
         },
-        poolOptions: {
-            threads: {
-                useAtomics: true
-            }
+    },
+    poolOptions: {
+        threads: {
+            useAtomics: true
         }
     },
     plugins: [tsconfigPaths()]

docs/faq.md

@@ -65,6 +65,15 @@ For production use, you can either:
 
 The SDK ships several runnable server examples under `examples/server/src`. Start from the server examples index in [`examples/server/README.md`](../examples/server/README.md) and the entry-point quick start in the root [`README.md`](../README.md).
 
+### Why did we remove `server` auth exports?
+
+Server authentication & authorization is outside of the scope of the SDK, and the recommendation is to use packages that focus on this area specifically (or a full-fledged Authorization Server for those who use such). Example packages provide an example with `better-auth`.
+
+### Why did we remove `server` SSE transport?
+
+The SSE transport has been deprecated for a long time, and `v2` will not support it on the server side any more. Client side will keep supporting it in order to be able to connect to legacy SSE servers via the `v2` SDK, but serving SSE from `v2` will not be possible. Servers
+wanting to switch to `v2` and using SSE should migrate to Streamable HTTP.
+
 ## v1 (legacy)
 
 ### Where do v1 documentation and v1-specific fixes live?

docs/server.md

@@ -70,7 +70,7 @@ For more detailed patterns (stateless vs stateful, JSON response mode, CORS, DNS
 MCP servers running on localhost are vulnerable to DNS rebinding attacks. Use `createMcpExpressApp()` to create an Express app with DNS rebinding protection enabled by default:
 
 ```typescript
-import { createMcpExpressApp } from '@modelcontextprotocol/server';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
 
 // Protection auto-enabled (default host is 127.0.0.1)
 const app = createMcpExpressApp();
@@ -85,7 +85,7 @@ const app = createMcpExpressApp({ host: '0.0.0.0' });
 When binding to `0.0.0.0` / `::`, provide an allow-list of hosts:
 
 ```typescript
-import { createMcpExpressApp } from '@modelcontextprotocol/server';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
 
 const app = createMcpExpressApp({
     host: '0.0.0.0',

examples/server/README.md

@@ -1,6 +1,9 @@
 # MCP TypeScript SDK Examples (Server)
 
-This directory contains runnable MCP **server** examples built with `@modelcontextprotocol/server`.
+This directory contains runnable MCP **server** examples built with `@modelcontextprotocol/server` plus framework adapters:
+
+- `@modelcontextprotocol/express`
+- `@modelcontextprotocol/hono`
 
 For client examples, see [`../client/README.md`](../client/README.md). For guided docs, see [`../../docs/server.md`](../../docs/server.md).
 
@@ -68,7 +71,7 @@ When deploying MCP servers in a horizontally scaled environment (multiple server
 
 ### Stateless mode
 
-To enable stateless mode, configure the `StreamableHTTPServerTransport` with:
+To enable stateless mode, configure the `NodeStreamableHTTPServerTransport` with:
 
 ```typescript
 sessionIdGenerator: undefined;

examples/server/package.json

@@ -35,11 +35,15 @@
     },
     "dependencies": {
         "@hono/node-server": "catalog:runtimeServerOnly",
-        "hono": "catalog:runtimeServerOnly",
         "@modelcontextprotocol/examples-shared": "workspace:^",
+        "@modelcontextprotocol/node": "workspace:^",
         "@modelcontextprotocol/server": "workspace:^",
+        "@modelcontextprotocol/express": "workspace:^",
+        "@modelcontextprotocol/hono": "workspace:^",
+        "better-auth": "^1.4.7",
         "cors": "catalog:runtimeServerOnly",
         "express": "catalog:runtimeServerOnly",
+        "hono": "catalog:runtimeServerOnly",
         "zod": "catalog:runtimeShared"
     },
     "devDependencies": {

examples/server/src/elicitationFormExample.ts

@@ -9,8 +9,10 @@
 
 import { randomUUID } from 'node:crypto';
 
-import { createMcpExpressApp, isInitializeRequest, McpServer, StreamableHTTPServerTransport } from '@modelcontextprotocol/server';
-import { type Request, type Response } from 'express';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+import { isInitializeRequest, McpServer } from '@modelcontextprotocol/server';
+import type { Request, Response } from 'express';
 
 // Factory to create a new MCP server per session.
 // Each session needs its own server+transport pair to avoid cross-session contamination.
@@ -327,7 +329,7 @@ async function main() {
     const app = createMcpExpressApp();
 
     // Map to store transports by session ID
-    const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
+    const transports: { [sessionId: string]: NodeStreamableHTTPServerTransport } = {};
 
     // MCP POST endpoint
     const mcpPostHandler = async (req: Request, res: Response) => {
@@ -337,13 +339,13 @@ async function main() {
         }
 
         try {
-            let transport: StreamableHTTPServerTransport;
+            let transport: NodeStreamableHTTPServerTransport;
             if (sessionId && transports[sessionId]) {
                 // Reuse existing transport for this session
                 transport = transports[sessionId];
             } else if (!sessionId && isInitializeRequest(req.body)) {
                 // New initialization request - create new transport
-                transport = new StreamableHTTPServerTransport({
+                transport = new NodeStreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
                     onsessioninitialized: sessionId => {
                         // Store the transport by session ID when session is initialized