v2 backcompat: server legacy package (#2206)

Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

Author: KKonstantinov

.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`.
+Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) are first-class in `@modelcontextprotocol/express`. Authorization Server helpers (`mcpAuthRouter`, `ProxyOAuthServerProvider`, etc.) are available from `@modelcontextprotocol/server-legacy/auth` (deprecated, frozen v1 copy). New code should use a dedicated IdP/OAuth library for the AS. 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 helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) → `@modelcontextprotocol/express`; AS helpers (`mcpAuthRouter`, `OAuthServerProvider`, etc.) → `@modelcontextprotocol/server-legacy/auth` (deprecated); migrate AS 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.
+Resource Server helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `getOAuthProtectedResourceMetadataUrl`, `OAuthTokenVerifier`) are first-class in `@modelcontextprotocol/express`. Authorization Server helpers (`mcpAuthRouter`, `OAuthServerProvider`, `ProxyOAuthServerProvider`, `authenticateClient`, `allowedMethods`, etc.) are available from `@modelcontextprotocol/server-legacy/auth` (deprecated, frozen v1 copy). Migrate AS 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: RS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`, `OAuthTokenVerifier`) → `@modelcontextprotocol/express`; AS helpers → `@modelcontextprotocol/server-legacy/auth` (deprecated); migrate AS 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 first-class in `@modelcontextprotocol/express`.
 
 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 `@modelcontextprotocol/express` (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)
 

packages/codemod/scripts/generateVersions.ts

@@ -9,7 +9,8 @@ const PACKAGE_DIRS: Record<string, string> = {
     '@modelcontextprotocol/client': 'client',
     '@modelcontextprotocol/server': 'server',
     '@modelcontextprotocol/node': 'middleware/node',
-    '@modelcontextprotocol/express': 'middleware/express'
+    '@modelcontextprotocol/express': 'middleware/express',
+    '@modelcontextprotocol/server-legacy': 'server-legacy'
 };
 
 const versions: Record<string, string> = {};

packages/codemod/src/generated/versions.ts

@@ -3,5 +3,6 @@ export const V2_PACKAGE_VERSIONS: Record<string, string> = {
     '@modelcontextprotocol/client': '^2.0.0-alpha.2',
     '@modelcontextprotocol/server': '^2.0.0-alpha.2',
     '@modelcontextprotocol/node': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/express': '^2.0.0-alpha.2'
+    '@modelcontextprotocol/express': '^2.0.0-alpha.2',
+    '@modelcontextprotocol/server-legacy': '^2.0.0-alpha.2'
 };