v2 backcompat: server legacy package

.changeset/add-server-legacy-package.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server-legacy': minor
+---
+
+Add @modelcontextprotocol/server-legacy package with frozen v1 SSE transport and OAuth Authorization Server helpers for migration from v1 to v2.

.changeset/codemod-resolve-legacy-imports.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/codemod': minor
+---
+
+Codemod now resolves SSE server and OAuth auth imports to @modelcontextprotocol/server-legacy sub-paths instead of removing them. An info diagnostic suggests eventual migration to v2 equivalents.

.changeset/pre.json

@@ -17,6 +17,8 @@
     "@modelcontextprotocol/hono": "2.0.0-alpha.0",
     "@modelcontextprotocol/node": "2.0.0-alpha.0",
     "@modelcontextprotocol/server": "2.0.0-alpha.0",
+    "@modelcontextprotocol/server-legacy": "2.0.0-alpha.0",
+    "@modelcontextprotocol/codemod": "2.0.0-alpha.0",
     "@modelcontextprotocol/test-conformance": "2.0.0-alpha.0",
     "@modelcontextprotocol/test-helpers": "2.0.0-alpha.0",
     "@modelcontextprotocol/test-integration": "2.0.0-alpha.0"

.github/workflows/publish.yml

@@ -39,5 +39,5 @@ jobs:
 
             - name: Publish preview packages
               run:
-                  pnpm dlx pkg-pr-new publish --packageManager=npm --pnpm './packages/server' './packages/client'
+                  pnpm dlx pkg-pr-new publish --packageManager=npm --pnpm './packages/server' './packages/server-legacy' './packages/client'
                   './packages/codemod' './packages/middleware/express' './packages/middleware/fastify' './packages/middleware/hono' './packages/middleware/node'

docs/faq.md

@@ -71,7 +71,7 @@ The [server quickstart](./server-quickstart.md) walks you through building a wea
 
 ### Where are the server auth helpers?
 
-Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) are first-class in `@modelcontextprotocol/express`. The Authorization Server helpers (`mcpAuthRouter`, `ProxyOAuthServerProvider`, etc.) have been removed from the core SDK; new code should use a dedicated IdP/OAuth library. Example packages provide a demo with `better-auth`.
+All auth helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`, `mcpAuthRouter`, `ProxyOAuthServerProvider`, etc.) are available from `@modelcontextprotocol/server-legacy/auth` (deprecated, frozen v1 copy). New code should use a dedicated IdP/OAuth library. Example packages provide a demo with `better-auth`.
 
 ### Why did we remove `server` SSE transport?
 

docs/migration-SKILL.md

@@ -53,8 +53,8 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | `@modelcontextprotocol/sdk/server/index.js`          | `@modelcontextprotocol/server`                                                                                                                                                                                     |
 | `@modelcontextprotocol/sdk/server/stdio.js`          | `@modelcontextprotocol/server/stdio`                                                                                                                                                                                     |
 | `@modelcontextprotocol/sdk/server/streamableHttp.js` | `@modelcontextprotocol/node` (class renamed to `NodeStreamableHTTPServerTransport`) OR `@modelcontextprotocol/server` (web-standard `WebStandardStreamableHTTPServerTransport` for Cloudflare Workers, Deno, etc.) |
-| `@modelcontextprotocol/sdk/server/sse.js`            | REMOVED (migrate to Streamable HTTP)                                                                                                                                                                               |
-| `@modelcontextprotocol/sdk/server/auth/*`            | RS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) → `@modelcontextprotocol/express`; AS helpers removed (use external IdP/OAuth library)                                             |
+| `@modelcontextprotocol/sdk/server/sse.js`            | REMOVED (migrate to Streamable HTTP); legacy bridge: `@modelcontextprotocol/server-legacy/sse`                                                                                                                     |
+| `@modelcontextprotocol/sdk/server/auth/*`            | RS + AS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`, `mcpAuthRouter`, etc.) → `@modelcontextprotocol/server-legacy/auth` (deprecated, frozen v1 copy); migrate to an external IdP/OAuth library |
 | `@modelcontextprotocol/sdk/server/middleware.js`     | `@modelcontextprotocol/express` (signature changed, see section 8)                                                                                                                                                 |
 
 ### Types / shared imports
@@ -328,11 +328,11 @@ new URL(ctx.http?.req?.url).searchParams.get('debug')
 
 ### SSE server transport
 
-`SSEServerTransport` removed entirely. Migrate to `NodeStreamableHTTPServerTransport` (from `@modelcontextprotocol/node`). Client-side `SSEClientTransport` still available for connecting to legacy servers.
+`SSEServerTransport` removed entirely. Migrate to `NodeStreamableHTTPServerTransport` (from `@modelcontextprotocol/node`). Client-side `SSEClientTransport` still available for connecting to legacy servers. Legacy bridge: `import { SSEServerTransport } from '@modelcontextprotocol/server-legacy/sse'` (deprecated, frozen v1 copy).
 
 ### Server-side auth
 
-Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are first-class in `@modelcontextprotocol/express`. Authorization Server helpers (`mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) are removed from the core SDK; use an external IdP/OAuth library. See `examples/server/src/` for demos.
+All auth helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`, `mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) are available from `@modelcontextprotocol/server-legacy/auth` (deprecated, frozen v1 copy). Migrate to an external IdP/OAuth library for production use. See `examples/server/src/` for demos.
 
 ### Host header validation (Express)
 
@@ -544,6 +544,6 @@ Validator behavior:
 6. Replace plain header objects with `new Headers({...})` and bracket access (`headers['x']`) with `.get()` calls per section 7
 7. If using `hostHeaderValidation` from server, update import and signature per section 8
 8. If using server SSE transport, migrate to Streamable HTTP
-9. If using server auth from the SDK: RS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`) → `@modelcontextprotocol/express`; AS helpers → external IdP/OAuth library
+9. If using server auth from the SDK: all auth helpers → `@modelcontextprotocol/server-legacy/auth` (deprecated); migrate to external IdP/OAuth library
 10. If relying on `listTools()`/`listPrompts()`/etc. throwing on missing capabilities, set `enforceStrictCapabilities: true`
 11. Verify: build with `tsc` / run tests

docs/migration.md

@@ -113,6 +113,14 @@ const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: ()
 
 The SSE transport has been removed from the server. Servers should migrate to Streamable HTTP. The client-side SSE transport remains available for connecting to legacy SSE servers.
 
+If you need a temporary bridge during migration, `@modelcontextprotocol/server-legacy/sse` provides a frozen copy of the v1 `SSEServerTransport`:
+
+```typescript
+import { SSEServerTransport } from '@modelcontextprotocol/server-legacy/sse';
+```
+
+This package is deprecated and will not receive new features.
+
 ### `WebSocketClientTransport` removed
 
 `WebSocketClientTransport` has been removed. WebSocket is not a spec-defined MCP transport, and keeping it in the SDK encouraged transport proliferation without a conformance baseline.
@@ -135,7 +143,7 @@ const transport = new StreamableHTTPClientTransport(new URL('http://localhost:30
 
 ### Server auth split
 
-Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are now first-class in `@modelcontextprotocol/express`.
+Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are available from `@modelcontextprotocol/server-legacy/auth`. Migrate to a dedicated OAuth provider for production use.
 
 Authorization Server helpers (`mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) have been removed from the core SDK; new code should use a dedicated IdP/OAuth library. See the [examples](../examples/server/src/) for a working demo with `better-auth`.
 
@@ -812,6 +820,14 @@ The following individual error classes have been removed in favor of `OAuthError
 
 The `OAUTH_ERRORS` constant has also been removed.
 
+If you need the v1 OAuth error classes and `mcpAuthRouter` during migration, `@modelcontextprotocol/server-legacy/auth` provides a frozen copy:
+
+```typescript
+import { mcpAuthRouter, InvalidClientError } from '@modelcontextprotocol/server-legacy/auth';
+```
+
+This package is deprecated and will not receive new features. Use a dedicated OAuth provider in production.
+
 **Before (v1):**
 
 ```typescript

examples/server/README.md

@@ -25,20 +25,20 @@ pnpm tsx src/simpleStreamableHttp.ts
 
 ## Example index
 
-| Scenario                                  | Description                                                                                     | File                                                                                     |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Streamable HTTP server (stateful)         | Feature-rich server with tools/resources/prompts, logging, tasks, sampling, and optional OAuth. | [`src/simpleStreamableHttp.ts`](src/simpleStreamableHttp.ts)                             |
-| Streamable HTTP server (stateless)        | No session tracking; good for simple API-style servers.                                         | [`src/simpleStatelessStreamableHttp.ts`](src/simpleStatelessStreamableHttp.ts)           |
-| Resource-Server-only auth                 | Minimal OAuth RS using SDK's `mcpAuthMetadataRouter` + `requireBearerAuth` (no better-auth).    | [`src/resourceServerOnly.ts`](src/resourceServerOnly.ts)                                 |
-| JSON response mode (no SSE)               | Streamable HTTP with JSON-only responses and limited notifications.                             | [`src/jsonResponseStreamableHttp.ts`](src/jsonResponseStreamableHttp.ts)                 |
-| Server notifications over Streamable HTTP | Demonstrates server-initiated notifications via GET+SSE.                                        | [`src/standaloneSseWithGetStreamableHttp.ts`](src/standaloneSseWithGetStreamableHttp.ts) |
-| Output schema server                      | Demonstrates tool output validation with structured output schemas.                             | [`src/mcpServerOutputSchema.ts`](src/mcpServerOutputSchema.ts)                           |
-| Form elicitation server                   | Collects **non-sensitive** user input via schema-driven forms.                                  | [`src/elicitationFormExample.ts`](src/elicitationFormExample.ts)                         |
-| URL elicitation server                    | Secure browser-based flows for **sensitive** input (API keys, OAuth, payments).                 | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                           |
-| Sampling + tasks server                   | Demonstrates sampling and experimental task-based execution.                                    | [`src/toolWithSampleServer.ts`](src/toolWithSampleServer.ts)                             |
-| Task interactive server                   | Task-based execution with interactive server→client requests.                                   | [`src/simpleTaskInteractive.ts`](src/simpleTaskInteractive.ts)                           |
-| Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                      | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
-| SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                   | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
+| Scenario                                  | Description                                                                                                      | File                                                                                     |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Streamable HTTP server (stateful)         | Feature-rich server with tools/resources/prompts, logging, tasks, sampling, and optional OAuth.                  | [`src/simpleStreamableHttp.ts`](src/simpleStreamableHttp.ts)                             |
+| Streamable HTTP server (stateless)        | No session tracking; good for simple API-style servers.                                                          | [`src/simpleStatelessStreamableHttp.ts`](src/simpleStatelessStreamableHttp.ts)           |
+| Resource-Server-only auth                 | Minimal OAuth RS using `mcpAuthMetadataRouter` + `requireBearerAuth` from `server-legacy/auth` (no better-auth). | [`src/resourceServerOnly.ts`](src/resourceServerOnly.ts)                                 |
+| JSON response mode (no SSE)               | Streamable HTTP with JSON-only responses and limited notifications.                                              | [`src/jsonResponseStreamableHttp.ts`](src/jsonResponseStreamableHttp.ts)                 |
+| Server notifications over Streamable HTTP | Demonstrates server-initiated notifications via GET+SSE.                                                         | [`src/standaloneSseWithGetStreamableHttp.ts`](src/standaloneSseWithGetStreamableHttp.ts) |
+| Output schema server                      | Demonstrates tool output validation with structured output schemas.                                              | [`src/mcpServerOutputSchema.ts`](src/mcpServerOutputSchema.ts)                           |
+| Form elicitation server                   | Collects **non-sensitive** user input via schema-driven forms.                                                   | [`src/elicitationFormExample.ts`](src/elicitationFormExample.ts)                         |
+| URL elicitation server                    | Secure browser-based flows for **sensitive** input (API keys, OAuth, payments).                                  | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                           |
+| Sampling + tasks server                   | Demonstrates sampling and experimental task-based execution.                                                     | [`src/toolWithSampleServer.ts`](src/toolWithSampleServer.ts)                             |
+| Task interactive server                   | Task-based execution with interactive server→client requests.                                                    | [`src/simpleTaskInteractive.ts`](src/simpleTaskInteractive.ts)                           |
+| Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                                       | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
+| SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                                    | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
 
 ## OAuth demo flags (Streamable HTTP server)
 

examples/server/package.json

@@ -38,6 +38,7 @@
         "@modelcontextprotocol/hono": "workspace:^",
         "@modelcontextprotocol/node": "workspace:^",
         "@modelcontextprotocol/server": "workspace:^",
+        "@modelcontextprotocol/server-legacy": "workspace:^",
         "@valibot/to-json-schema": "catalog:devTools",
         "arktype": "catalog:devTools",
         "better-auth": "^1.4.17",

examples/server/src/elicitationUrlExample.ts

@@ -10,10 +10,11 @@
 import { randomUUID } from 'node:crypto';
 
 import { createProtectedResourceMetadataRouter, demoTokenVerifier, setupAuthServer } from '@modelcontextprotocol/examples-shared';
-import { createMcpExpressApp, getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/express';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ElicitRequestURLParams, ElicitResult } from '@modelcontextprotocol/server';
 import { isInitializeRequest, McpServer, UrlElicitationRequiredError } from '@modelcontextprotocol/server';
+import { getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/server-legacy/auth';
 import cors from 'cors';
 import type { Request, Response } from 'express';
 import express from 'express';

examples/server/src/resourceServerOnly.ts

@@ -11,16 +11,12 @@
  *        curl -H 'Authorization: Bearer demo-token' -X POST http://localhost:3000/mcp ...
  */
 
-import type { OAuthTokenVerifier } from '@modelcontextprotocol/express';
-import {
-    createMcpExpressApp,
-    getOAuthProtectedResourceMetadataUrl,
-    mcpAuthMetadataRouter,
-    requireBearerAuth
-} from '@modelcontextprotocol/express';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { AuthInfo, CallToolResult, OAuthMetadata } from '@modelcontextprotocol/server';
 import { McpServer, OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
+import type { OAuthTokenVerifier } from '@modelcontextprotocol/server-legacy/auth';
+import { getOAuthProtectedResourceMetadataUrl, mcpAuthMetadataRouter, requireBearerAuth } from '@modelcontextprotocol/server-legacy/auth';
 import type { Request, Response } from 'express';
 import * as z from 'zod/v4';
 

examples/server/src/simpleStreamableHttp.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
 import { createProtectedResourceMetadataRouter, demoTokenVerifier, setupAuthServer } from '@modelcontextprotocol/examples-shared';
-import { createMcpExpressApp, getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/express';
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type {
     CallToolResult,
@@ -12,6 +12,7 @@ import type {
     ResourceLink
 } from '@modelcontextprotocol/server';
 import { InMemoryTaskMessageQueue, InMemoryTaskStore, isInitializeRequest, McpServer } from '@modelcontextprotocol/server';
+import { getOAuthProtectedResourceMetadataUrl, requireBearerAuth } from '@modelcontextprotocol/server-legacy/auth';
 import cors from 'cors';
 import type { Request, Response } from 'express';
 import * as z from 'zod/v4';

examples/server/tsconfig.json

@@ -9,6 +9,7 @@
             "@modelcontextprotocol/server/stdio": ["./node_modules/@modelcontextprotocol/server/src/stdio.ts"],
             "@modelcontextprotocol/server/_shims": ["./node_modules/@modelcontextprotocol/server/src/shimsNode.ts"],
             "@modelcontextprotocol/express": ["./node_modules/@modelcontextprotocol/express/src/index.ts"],
+            "@modelcontextprotocol/server-legacy/auth": ["./node_modules/@modelcontextprotocol/server-legacy/src/auth/index.ts"],
             "@modelcontextprotocol/node": ["./node_modules/@modelcontextprotocol/node/src/index.ts"],
             "@modelcontextprotocol/hono": ["./node_modules/@modelcontextprotocol/hono/src/index.ts"],
             "@modelcontextprotocol/core": [