You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Shortest path for most servers:** bump `@modelcontextprotocol/sdk` to `^2.0.0` and stop. v1 import paths and APIs continue to work as `@deprecated` aliases (IDE strikethrough, no runtime warnings) that forward to the new implementation. If the user only wants to "get on v2", do that, run the build, and
9
-
report any IDE-flagged `@deprecated` usages as optional follow-ups.
8
+
## Path A (default) — Stay on the `/sdk` package
10
9
11
-
Apply the rest of this guide when the user wants a **full migration** to the new split packages with no `@deprecated` usages. Order: environment → dependencies → imports → API calls → type aliases.
10
+
`@modelcontextprotocol/sdk@^2` is a meta-package: v1 import paths and APIs continue to work as `@deprecated` aliases (IDE strikethrough, no runtime warnings). **Do not rewrite imports.**
11
+
12
+
1. Bump `"@modelcontextprotocol/sdk"` to `"^2.0.0"` in package.json.
4.**If it passes — STOP. Migration complete.** Report `@deprecated`-flagged usages as optional follow-ups, do not rewrite them.
16
+
5. If it fails, fix only the specific errors using the rename table in §5 and the not-shimmed list below. Do not apply §2 (uninstall sdk) or §3 (import rewriting).
17
+
18
+
**Not shimmed (need a one-line edit even on Path A):**`IsomorphicHeaders` → `Headers`; `StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport` (from `@modelcontextprotocol/node`); the 5-arg `server.tool(name, desc, schema, annotations, cb)` form → `registerTool`.
19
+
20
+
## Path B — Move to the split packages
21
+
22
+
Apply §2 onwards **only** if the user explicitly wants to drop `@modelcontextprotocol/sdk` and import from `@modelcontextprotocol/server` / `@modelcontextprotocol/client` directly (smaller bundle, no `@deprecated` strikethrough, or building a host/framework/transport). Order: environment → dependencies → imports → API calls → type aliases.
12
23
13
24
## 1. Environment
14
25
@@ -94,6 +105,7 @@ Notes:
94
105
|`isJSONRPCResponse` (deprecated in v1) |`isJSONRPCResultResponse` (**not** v2's new `isJSONRPCResponse`, which correctly matches both result and error) |
Copy file name to clipboardExpand all lines: docs/migration.md
+40-9Lines changed: 40 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,25 +4,51 @@ This guide covers the breaking changes introduced in v2 of the MCP TypeScript SD
4
4
5
5
> **Note:** This guide describes the v2.0.0 release as a whole. The compatibility shims it references land across the [v2-bc PR series](https://github.com/modelcontextprotocol/typescript-sdk/pulls?q=is%3Apr+label%3Av2-bc); on any individual PR's branch some referenced symbols may not yet exist.
6
6
7
-
## TL;DR — most servers just bump the version
7
+
## Upgrade paths
8
8
9
-
For **most MCP servers**, upgrading to v2 is a one-line change:
9
+
There are two ways to move to v2. **Pick one before reading further.**
10
+
11
+
### Path A — Stay on the `/sdk` package (recommended for most servers)
12
+
13
+
`@modelcontextprotocol/sdk@^2` is a meta-package that re-exports the new split packages at the v1 import paths. **Your existing imports work unchanged.**
10
14
11
15
```diff
16
+
// package.json
12
17
- "@modelcontextprotocol/sdk": "^1.0.0"
13
18
+ "@modelcontextprotocol/sdk": "^2.0.0"
14
19
```
15
20
16
-
In v2, `@modelcontextprotocol/sdk` is a meta-package that re-exports the new split packages at the v1 import paths. v1 APIs (deep-import paths like `@modelcontextprotocol/sdk/server/mcp.js`, variadic `server.tool()`, `McpError`, `RequestHandlerExtra`, etc.) continue to work as
17
-
**`@deprecated` aliases** — your IDE will show strikethrough and a hover note pointing at the new API, but there are no runtime warnings. You can ship on v2 immediately and migrate the deprecated usages at your own pace.
21
+
After bumping, run your typecheck. **If it passes, you're done — stop reading.** The v1 APIs (`@modelcontextprotocol/sdk/server/mcp.js`, `server.tool()` variadic, `McpError`, `RequestHandlerExtra`, `SSEServerTransport`, etc.) are `@deprecated` aliases that compile and run identically. Your IDE will show strikethrough and a hover note pointing at the new API, but there are no runtime warnings.
22
+
23
+
If typecheck fails, fix only the errors you see — the table in [What the meta-package doesn't shim](#what-the-meta-package-doesnt-shim) lists the handful of changes that still need a one-line edit.
24
+
25
+
**Do not rewrite imports to the split packages unless you're choosing Path B.**
26
+
27
+
### Path B — Move to the split packages
28
+
29
+
Choose this if you want to drop the `/sdk` dependency and import directly from `@modelcontextprotocol/server` / `@modelcontextprotocol/client`. Reasons:
18
30
19
-
Read on if you want to:
31
+
- Smaller bundle (you only ship what you use)
32
+
- No `@deprecated` strikethrough in your editor
33
+
- You're a host application, framework adapter, or custom transport author (these touch surface the meta-package doesn't fully cover)
20
34
21
-
- Migrate to the new split packages (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`) for smaller bundles
22
-
- Adopt the new API surface (no `@deprecated` strikethrough)
23
-
- Understand a specific breaking change
35
+
The rest of this guide is **Path B**. If you chose Path A, skip to [What the meta-package doesn't shim](#what-the-meta-package-doesnt-shim).
24
36
25
-
> **Clients and frameworks** (host applications, custom transports, proxies) typically need a few more changes than servers — see the [Custom methods](#setrequesthandler-and-setnotificationhandler-use-method-strings), [Error hierarchy](#error-hierarchy-refactoring), and [Server auth](#server-auth-split) sections.
37
+
> **Clients and frameworks** typically need a few more changes than servers — see the [Custom methods](#setrequesthandler-and-setnotificationhandler-use-method-strings), [Error hierarchy](#error-hierarchy-refactoring), and [Server auth](#server-auth-split) sections.
38
+
39
+
## What the meta-package doesn't shim
40
+
41
+
These are the changes you need regardless of which path you chose. Everything else in this guide is Path B only.
42
+
43
+
| What | Change |
44
+
|---|---|
45
+
|`zod` version | Must be `^4.2.0` — see [Prerequisites](#zod-must-be-420)|
46
+
| tsconfig `moduleResolution`| Must be `bundler`, `nodenext`, or `node16` — see [Prerequisites](#typescript-moduleresolution-must-be-bundler-nodenext-or-node16)|
47
+
|`IsomorphicHeaders` type | → standard `Headers` — see [§](#headers-object-instead-of-plain-objects)|
48
+
|`StreamableHTTPServerTransport` (Node) | → `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node` — see [§](#streamablehttpservertransport-renamed)|
49
+
|`server.tool(name, desc, schema, annotations, cb)` 5-arg form | → `registerTool(name, {description, inputSchema, annotations}, cb)` — see [§](#mcpservertool-prompt-resource-removed)|
50
+
51
+
These five were intentionally not shimmed because the codemod handles them mechanically (`npx @modelcontextprotocol/codemod-v2`).
26
52
27
53
## Prerequisites
28
54
@@ -183,6 +209,10 @@ const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: ()
183
209
184
210
### Server-side SSE transport removed
185
211
212
+
> **Path A users:** the meta-package re-exports `SSEServerTransport` and `SSEClientTransport` at their v1 paths. You don't need to change anything.
213
+
>
214
+
> **Path B users:** the v2 server package does not include SSE. Install `@modelcontextprotocol/server-auth-legacy` (which also bundles `LegacySSEServerTransport`) or migrate to Streamable HTTP per the example below.
215
+
186
216
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.
187
217
188
218
### `WebSocketClientTransport` removed
@@ -638,6 +668,7 @@ The following deprecated type aliases have been removed from `@modelcontextproto
638
668
|`isJSONRPCResponse`|`isJSONRPCResultResponse` (see note below) |
0 commit comments