Index of every page on this site: llms.txt
All skills
modelcontextprotocol avatar

/mcp-typescript-sdk-upgrade-to-v2

@5ee54ee
Run it yourself

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".

Use this Skill: https://skilld.dev/gh/modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈158 tokens for metadata: the name and description. ≈3.6k when used: this file. ≈31k more on demand in 11 files.

Description uses 7.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈631 characters, or 7.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

<!-- #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 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.
    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:
    grep -rn '@mcp-codemod-error' .
  4. Type-check. tsc --noEmit (or your build). Remaining errors map to the manual sections 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.

Migrating a large codebase gradually instead of in one pass? See Migrating in stages (large codebases).

<!-- #endregion intro --><!-- #region codemod -->

What the codemod handles

The codemod (@modelcontextprotocol/codemod) 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
Symbol renames (McpError → ProtocolError, JSONRPCError → JSONRPCErrorResponse, …) mappings/symbolMap.ts
setRequestHandler(Schema, …) → setRequestHandler('method/string', …) mappings/schemaToMethodMap.ts
extra.* → ctx.mcpReq.* / ctx.http?.* property remap 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).
  • 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); 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
  • 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
  • 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
  • OAuth error-class consolidation — instanceof InvalidGrantError → OAuthError + OAuthErrorCode is a judgment rewrite. → Auth
  • SdkErrorCode branch selection — the codemod renames StreamableHTTPError → SdkHttpError; deciding which SdkErrorCode branch a given catch should match is judgment. → 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
  • 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 and Errors sections by hand. → Low-level protocol
  • Behavioral adaptation — list auto-aggregation, capability empties, lazy validator compilation, output-schema validation rules. → 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 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 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) Code uses extra / ctx, setRequestHandler / setNotificationHandler, request(), ctx.mcpReq.send() or callTool()
Server registration API Code registers tools, prompts or resources, or passes raw Zod shapes as schemas
HTTP & headers Code reads HTTP request headers
Errors Code throws or catches McpError / ProtocolError, ErrorCode, SdkError or SdkHttpError
Auth Code uses OAuth (auth(), OAuthClientProvider, OAuth error classes) or bearer-token auth
Types & schemas Code imports Zod *Schema constants or removed type aliases, or depends on JSON Schema details
Behavioral changes The code compiles but tests or runtime behavior differ
Enhancements Optional: v2 features worth adopting once the upgrade is done
Unchanged APIs Checking whether an API changed at all before rewriting it
<!-- #region need-help -->

Need help?

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts23d3 checks · Risk SAFE
  • Gen Agent Trust Hub23d

    This skill is a migration guide for the Model Context Protocol (MCP) TypeScript SDK. It provides instructions and an official codemod tool to help users upgrade their projects from v1 to v2. No security issues were detected.

  • Socket26d

    No alerts

  • Snyk26d

    Risk: LOW · No issues

Signed by skilld at 5ee54ee. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month

README badge

README badge for modelcontextprotocol/typescript-sdk/mcp-typescript-sdk-upgrade-to-v2