---
name: mcp-typescript-sdk-upgrade-to-v2
description: 'Upgrades TypeScript code from v1 of the MCP TypeScript SDK (`@modelcontextprotocol/sdk`) to v2 (`@modelcontextprotocol/client`, `/server`, `/core` and the middleware packages): runs the official codemod, then works through what it cannot rewrite. Use whenever a project depends on `@modelcontextprotocol/sdk` and the user wants to migrate, upgrade, port or bump it to v2, or is fixing v1-to-v2 breakage such as missing `McpError`, `RequestHandlerExtra` or `*Schema` exports, `@mcp-codemod-error` markers, or changed auth, error, transport or handler behavior, even if they do not say "migration".'
title: mcp-typescript-sdk-upgrade-to-v2
canonical_url: https://skilld.dev/gh/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2
last_updated: 2026-10-26T08:30:47.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/auth.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/auth.md), [references/behavioral-changes.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/behavioral-changes.md), [references/enhancements.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/enhancements.md), [references/errors.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/errors.md), [references/http-headers.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/http-headers.md), [references/imports-transports.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/imports-transports.md), [references/packaging-runtime.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/packaging-runtime.md), [references/protocol-ctx.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/protocol-ctx.md), [references/server-registration.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/server-registration.md), [references/types-schemas.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/types-schemas.md), [references/unchanged-apis.md](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/unchanged-apis.md).
>
> If the user asked to install this Skill, run `npx skilld install modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/mcp-typescript-sdk-upgrade-to-v2`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/mcp-typescript-sdk-upgrade-to-v2`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/mcp-typescript-sdk-upgrade-to-v2 --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/mcp-typescript-sdk-upgrade-to-v2 --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

<!-- #region intro -->

# Upgrading from v1.x to v2

This guide covers upgrading from `@modelcontextprotocol/sdk` (v1.x) to the v2 packages.
It is written for shell-capable agents and humans alike: run the codemod first, then
work through the manual sections for what the codemod can't rewrite.

If you are already on v2 and want to adopt the **2026-07-28 protocol revision**, see
[support-2026-07-28.md](https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md) instead.

## TL;DR — quick path

1. **Prerequisites.** Node.js 20+. v2 is ESM-first but ships a CommonJS build too, so
   both `import` and `require('@modelcontextprotocol/…')` resolve natively.
2. **Run the codemod.**
    ```bash
    npx @modelcontextprotocol/codemod@latest v1-to-v2 .
    ```
    Run it at the **package root** (`.`), not `./src` — it also rewrites `package.json`,
    and real projects import the SDK from `test/`, `scripts/`, and fixtures too.
3. **Grep for markers.** Anything the codemod recognized but could not safely rewrite is
   marked in place:
    ```bash
    grep -rn '@mcp-codemod-error' .
    ```
4. **Type-check.** `tsc --noEmit` (or your build). Remaining errors map to the
   [manual sections](#manual-changes-what-the-codemod-does-not-handle) below.
5. **Format.** The codemod rewrites the AST without reformatting — run your formatter on
   the changed files (`prettier --write` / `eslint --fix` / `biome format --write`); the
   codemod prints the exact command after it runs.
6. **Run your tests.**
7. **Decide whether to serve the 2026-07-28 revision.** The upgrade alone does not: a server
   that still calls `server.connect(new StdioServerTransport())` or hands requests to a
   `*StreamableHTTPServerTransport` serves 2025-era clients only, and a client pinned to
   2026-07-28 cannot connect to it. To serve both, move the entry point to
   `serveStdio(() => createServer())` or `createMcpHandler(() => createServer())`. A server
   that uses HTTP sessions keeps its transport for 2025-era clients and routes to it with
   `isLegacyRequest`, in front of `createMcpHandler(factory, { legacy: 'reject' })`.
   `createMcpHandler` checks no `Host` or `Origin` header, so a server that set
   `enableDnsRebindingProtection` mounts host and origin validation in front of it; see
   [Serving the 2026-07-28 revision](https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md#serving-the-2026-07-28-revision).

Migrating a large codebase gradually instead of in one pass? See
[Migrating in stages (large codebases)](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/packaging-runtime.md#migrating-in-stages-large-codebases).

<!-- #endregion intro -->

<!-- #region codemod -->

## What the codemod handles

The codemod ([`@modelcontextprotocol/codemod`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/README.md))
mechanically applies every rename whose mapping is fixed. The mappings are the
**source of truth** — they live in the codemod package and are not reproduced here:

| Mapping                                                                                   | Source file                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@modelcontextprotocol/sdk/...` import paths → v2 packages                                | [`mappings/importMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts)                   |
| Symbol renames (`McpError` → `ProtocolError`, `JSONRPCError` → `JSONRPCErrorResponse`, …) | [`mappings/symbolMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/symbolMap.ts)                   |
| `setRequestHandler(Schema, …)` → `setRequestHandler('method/string', …)`                  | [`mappings/schemaToMethodMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/schemaToMethodMap.ts)   |
| `extra.*` → `ctx.mcpReq.*` / `ctx.http?.*` property remap                                 | [`mappings/contextPropertyMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/contextPropertyMap.ts) |

In addition the codemod:

- Updates `package.json` dependencies (`@modelcontextprotocol/sdk` → the v2 packages
  your imports actually use).
- Rewrites `.tool()` / `.prompt()` / `.resource()` to `registerTool` / `registerPrompt`
  / `registerResource` and wraps `inputSchema` / `outputSchema` / `argsSchema` /
  `uriSchema` raw Zod shapes with `z.object()`, adding `import { z } from 'zod'`
  when the file has no `z` binding.
- Drops the result-schema argument from `client.request()` / `client.callTool()` for
  spec methods.
- Routes the spec Zod `*Schema` constants imported from `sdk/types.js` to
  `@modelcontextprotocol/core` (mixed imports are split; `.parse()` / `.safeParse()`
  calls are left untouched). Task-handler schema constants
  (`GetTaskRequestSchema` etc.) used as `setRequestHandler` args are **not** rewritten
  — the experimental tasks feature was removed (SEP-2663), so each such registration
  is marked with an action-required diagnostic instead (see
  [Experimental tasks interception removed](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/behavioral-changes.md#experimental-tasks-interception-removed)).
- Renames `ErrorCode` → `ProtocolErrorCode` and routes the local-only members
  (`RequestTimeout`, `ConnectionClosed`) to `SdkErrorCode` — rewriting an all-SDK
  condition's `instanceof ProtocolError` guard to `SdkError`, and marking guards
  that mix the two enums.
- Renames every `StreamableHTTPError` reference to `SdkHttpError` and adds the import
  (constructor calls are marked for review — argument shape changed).
- Replaces `IsomorphicHeaders` with the Web Standard `Headers` type and drops the
  import (a warning notes `Headers` uses `.get()`/`.set()`, not bracket access).
- Rewrites `SchemaInput<T>` → `StandardSchemaWithJSON.InferInput<T>`.
- Renames `RequestHandlerExtra` → `ServerContext` / `ClientContext` and the `extra`
  parameter to `ctx`.
- Rewrites `vi.mock` / `jest.mock` and dynamic `import()` paths.
- Renames the `ResourceTemplate` **type** imported from `@modelcontextprotocol/sdk/types.js`
  to `ResourceTemplateType` (the spec wire type). The `ResourceTemplate` URI-template
  helper **class** from `server/mcp.js` keeps its name and is not renamed.
- Drops `@modelcontextprotocol/sdk/server/zod-compat.js` imports.
- Inverts optional completable nesting — `completable(schema.optional(), cb)` becomes
  `completable(schema, cb).optional()` (see
  [Standard Schema objects](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/server-registration.md#standard-schema-objects-raw-shapes-deprecated)); shapes it
  cannot invert get an `@mcp-codemod-error` marker.
- Rewrites `Protocol` / `mergeCapabilities` imports from `shared/protocol.js` to the
  client or server package root, like the module's other symbols.

## What the codemod does NOT handle

Each of these maps to a manual section below. The codemod marks every site it
recognized but could not safely rewrite with an `@mcp-codemod-error` comment.

- **Node 20 / ESM** — pre-flight, not a code rewrite. → [Packaging & runtime](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/packaging-runtime.md#packaging--runtime)
- **Header-read `.get()` rewrite** — `IsomorphicHeaders` is renamed to `Headers`
  and `extra.requestInfo?.headers[…]` is remapped to `ctx.http?.req?.headers[…]`, but
  converting that bracket access to `.get()` is manual. (Headers you _pass in_ via
  `requestInit.headers` need no rewrite — plain objects remain valid.)
  → [HTTP & headers](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/http-headers.md#http--headers)
- **`ctx.mcpReq.send()` schema-arg drop** — the codemod drops the schema arg from
  `client.request()` / `client.callTool()` but leaves nested `ctx.mcpReq.send()` calls
  alone. → [Low-level protocol](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/protocol-ctx.md#low-level-protocol--handler-context-ctx)
- **OAuth error-class consolidation** — `instanceof InvalidGrantError` → `OAuthError` +
  `OAuthErrorCode` is a judgment rewrite. → [Auth](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/auth.md#auth)
- **`SdkErrorCode` branch selection** — the codemod renames `StreamableHTTPError` →
  `SdkHttpError`; deciding which `SdkErrorCode` branch a given catch should match is
  judgment. → [Errors](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/errors.md#errors)
- **Namespace schema access** — `import * as t from '…/types.js'` +
  `t.CallToolResultSchema.parse(…)` can't be split per-symbol; the codemod flags it
  action-required — re-import the schema from `@modelcontextprotocol/core` by hand.
  → [Types & schemas](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/types-schemas.md#types--schemas)
- **Import-less (injected) SDK surfaces** — the codemod is import-driven: a file that
  receives the SDK surface as a parameter (dependency injection, factory seams) and has
  no SDK import is never rewritten, and the v1 idioms there fail at **runtime**, not
  compile time — e.g. the v1 schema-first `setRequestHandler(Schema, …)` form throws a
  `TypeError` at registration. Grep such seams for v1 API tokens beyond import
  statements (`setRequestHandler(`, `ErrorCode.`, `extra.`) and apply the
  [handler-registration](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/protocol-ctx.md#setrequesthandler--setnotificationhandler-use-method-strings)
  and [Errors](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/errors.md#errors) sections by hand.
  → [Low-level protocol](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/protocol-ctx.md#low-level-protocol--handler-context-ctx)
- **Behavioral adaptation** — list auto-aggregation, capability empties, lazy validator
  compilation, output-schema validation rules. → [Behavioral changes](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/behavioral-changes.md#behavioral-changes)

---

## Manual changes (what the codemod does not handle)

<!-- #endregion codemod -->

Each subsystem has its own reference file. Open the one that matches the type error, runtime failure or `@mcp-codemod-error` marker in front of you; most migrations need only a few of them.

| Reference file                                                             | Read it when                                                                                                                                                                                   |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Packaging & runtime](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/packaging-runtime.md)                     | Choosing which v2 packages to install, or dealing with Node/ESM/CommonJS setup, monorepo workspaces, Jest, nested `zod` copies, migrating in stages, or a library that peer-depends on the SDK |
| [Imports & transports](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/imports-transports.md)                   | A transport import needs a runtime decision (Node vs web-standard Streamable HTTP) or a stdio import moved to a `./stdio` subpath                                                              |
| [Low-level protocol & handler context (`ctx`)](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/protocol-ctx.md) | Code uses `extra` / `ctx`, `setRequestHandler` / `setNotificationHandler`, `request()`, `ctx.mcpReq.send()` or `callTool()`                                                                    |
| [Server registration API](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/server-registration.md)               | Code registers tools, prompts or resources, or passes raw Zod shapes as schemas                                                                                                                |
| [HTTP & headers](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/http-headers.md)                               | Code reads HTTP request headers                                                                                                                                                                |
| [Errors](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/errors.md)                                             | Code throws or catches `McpError` / `ProtocolError`, `ErrorCode`, `SdkError` or `SdkHttpError`                                                                                                 |
| [Auth](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/auth.md)                                                 | Code uses OAuth (`auth()`, `OAuthClientProvider`, OAuth error classes) or bearer-token auth                                                                                                    |
| [Types & schemas](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/types-schemas.md)                             | Code imports Zod `*Schema` constants or removed type aliases, or depends on JSON Schema details                                                                                                |
| [Behavioral changes](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/behavioral-changes.md)                     | The code compiles but tests or runtime behavior differ                                                                                                                                         |
| [Enhancements](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/enhancements.md)                                 | Optional: v2 features worth adopting once the upgrade is done                                                                                                                                  |
| [Unchanged APIs](https://skilld.dev/api/skills-raw/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2/references/unchanged-apis.md)                             | Checking whether an API changed at all before rewriting it                                                                                                                                     |

<!-- #region need-help -->

## Need help?

- The codemod's [`@mcp-codemod-error`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/README.md) markers point
  at every site it could not safely rewrite.
- The [Troubleshooting](https://ts.sdk.modelcontextprotocol.io/v2/troubleshooting.md) page covers common errors and their fixes.
- Runnable [examples](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples)
  for every subsystem.
- Open an issue on [GitHub](https://github.com/modelcontextprotocol/typescript-sdk/issues).

<!-- #endregion need-help -->
