[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

README.md

@@ -1,7 +1,6 @@
 # MCP TypeScript SDK
 
-> [!IMPORTANT]
-> **This is the `main` branch which contains v2 of the SDK (currently in development, pre-alpha).**
+> [!IMPORTANT] **This is the `main` branch which contains v2 of the SDK (currently in development, pre-alpha).**
 >
 > We anticipate a stable v2 release in Q1 2026. Until then, **v1.x remains the recommended version** for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade.
 >
@@ -30,6 +29,7 @@ This repository contains the TypeScript SDK implementation of the MCP specificat
 
 - MCP **server** libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)
 - MCP **client** libraries (transports, high-level helpers, OAuth helpers)
+- Optional **middleware packages** for specific runtimes/frameworks (Express, Hono, Node.js HTTP)
 - Runnable **examples** (under [`examples/`](examples/))
 
 ## Packages
@@ -41,6 +41,16 @@ This monorepo publishes split packages:
 
 Both packages have a **required peer dependency** on `zod` for schema validation. The SDK internally imports from `zod/v4`, but remains compatible with projects using Zod v3.25+.
 
+### Middleware packages (optional)
+
+The SDK also publishes small “middleware” packages under [`packages/middleware/`](packages/middleware/) that help you **wire MCP into a specific runtime or web framework**.
+
+They are intentionally thin adapters: they should not introduce new MCP functionality or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.
+
+- **`@modelcontextprotocol/node`**: Node.js Streamable HTTP transport wrapper for `IncomingMessage` / `ServerResponse`
+- **`@modelcontextprotocol/express`**: Express helpers (app defaults + Host header validation)
+- **`@modelcontextprotocol/hono`**: Hono helpers (app defaults + JSON body parsing hook + Host header validation)
+
 ## Installation
 
 ### Server
@@ -55,6 +65,23 @@ npm install @modelcontextprotocol/server zod
 npm install @modelcontextprotocol/client zod
 ```
 
+### Optional middleware packages
+
+The SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Hono, or Node.js `http`).
+
+These packages are intentionally thin adapters and should not introduce additional MCP features or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.
+
+```bash
+# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport:
+npm install @modelcontextprotocol/node
+
+# Express integration:
+npm install @modelcontextprotocol/express express
+
+# Hono integration:
+npm install @modelcontextprotocol/hono hono
+```
+
 ## Quick Start (runnable examples)
 
 The runnable examples live under `examples/` and are kept in sync with the docs.

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": {