MCP TypeScript SDK — Migration Guides
Pick the guide for your starting point.
Upgrading from v1.x (@modelcontextprotocol/sdk)
You are on the monolithic @modelcontextprotocol/sdk package and want to move to the
v2 packages (@modelcontextprotocol/client, @modelcontextprotocol/server, …).
Start by running the codemod:
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
Run it at the package root (.) — real projects import the SDK from test/,
scripts/, and fixtures too, and those rewrites are missed when you point it at ./src.
The codemod handles most mechanical renames. The guide covers what it can't. The
codemod handles the v1→v2 SDK surface upgrade only — adopting the 2026-07-28 protocol
revision (createMcpHandler, multi-round-trip requests, versionNegotiation) is
architectural and not codemod-automatable; see support-2026-07-28.md.
Already on v2, adopting protocol revision 2026-07-28
You are already on the v2 packages and want your server or client to speak the
2026-07-28 protocol revision (per-request _meta envelope, createMcpHandler,
serveStdio, versionNegotiation, multi-round-trip requests, per-era wire codecs).
This guide also covers code written against an earlier v2 alpha that read
wire-only members (resultType, envelope keys) directly.
Using an LLM agent to migrate
upgrade-to-v2.md is the agent skill — it carries skill frontmatter and is structured for mechanical application. Point the agent at the codemod first; the guide is the codemod's companion for what's left.
See also
Source: docs/migration/index.md