name: migrate-v1-to-v2 description: Migrate MCP TypeScript SDK code from v1 (@modelcontextprotocol/sdk) to v2 (@modelcontextprotocol/core, /client, /server). Use when a user asks to migrate, upgrade, or port their MCP TypeScript code from v1 to v2.

MCP TypeScript SDK: v1 → v2 Migration

Apply these changes in order: dependencies → imports → API calls → type aliases.

1. Environment

• Node.js 20+ required (v18 dropped)
• ESM only (CJS dropped). If the project uses require(), convert to import/export or use dynamic import().

2. Dependencies

Remove the old package and install only what you need:

npm uninstall @modelcontextprotocol/sdk

@modelcontextprotocol/core is installed automatically as a dependency.

3. Import Mapping

Replace all @modelcontextprotocol/sdk/... imports using this table.

Client imports

Server imports

Types / shared imports

Notes:

• @modelcontextprotocol/client and @modelcontextprotocol/server both re-export shared types from @modelcontextprotocol/core, so import from whichever package you already depend on. Do not import from @modelcontextprotocol/core directly — it is an internal package.
• When multiple v1 imports map to the same v2 package, consolidate them into a single import statement.

4. Renamed Symbols

5. Removed / Renamed Type Aliases and Symbols

All other symbols from @modelcontextprotocol/sdk/types.js retain their original names (e.g., CallToolResultSchema, ListToolsResultSchema, etc.).

Error class changes

Two error classes now exist:

• ProtocolError (renamed from McpError): Protocol errors that cross the wire as JSON-RPC responses
• SdkError (new): Local SDK errors that never cross the wire

New SdkErrorCode enum values:

• SdkErrorCode.NotConnected = 'NOT_CONNECTED'
• SdkErrorCode.AlreadyConnected = 'ALREADY_CONNECTED'
• SdkErrorCode.NotInitialized = 'NOT_INITIALIZED'
• SdkErrorCode.CapabilityNotSupported = 'CAPABILITY_NOT_SUPPORTED'
• SdkErrorCode.RequestTimeout = 'REQUEST_TIMEOUT'
• SdkErrorCode.ConnectionClosed = 'CONNECTION_CLOSED'
• SdkErrorCode.SendFailed = 'SEND_FAILED'
• SdkErrorCode.ClientHttpNotImplemented = 'CLIENT_HTTP_NOT_IMPLEMENTED'
• SdkErrorCode.ClientHttpAuthentication = 'CLIENT_HTTP_AUTHENTICATION'
• SdkErrorCode.ClientHttpForbidden = 'CLIENT_HTTP_FORBIDDEN'
• SdkErrorCode.ClientHttpUnexpectedContent = 'CLIENT_HTTP_UNEXPECTED_CONTENT'
• SdkErrorCode.ClientHttpFailedToOpenStream = 'CLIENT_HTTP_FAILED_TO_OPEN_STREAM'
• SdkErrorCode.ClientHttpFailedToTerminateSession = 'CLIENT_HTTP_FAILED_TO_TERMINATE_SESSION'

Update error handling:

// v1
if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) { ... }

// v2
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) { ... }

Update HTTP transport error handling:

// v1
import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
if (error instanceof StreamableHTTPError) {
    console.log('HTTP status:', error.code);
}

// v2
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/client';
if (error instanceof SdkError && error.code === SdkErrorCode.ClientHttpFailedToOpenStream) {
    const status = (error.data as { status?: number })?.status;
}

OAuth error consolidation

Individual OAuth error classes replaced with single OAuthError class and OAuthErrorCode enum:

Removed: OAUTH_ERRORS constant.

Update OAuth error handling:

// v1
import { InvalidClientError, InvalidGrantError } from '@modelcontextprotocol/client';
if (error instanceof InvalidClientError) { ... }

// v2
import { OAuthError, OAuthErrorCode } from '@modelcontextprotocol/client';
if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient) { ... }

Unchanged APIs (only import paths changed): Client constructor and most methods, McpServer constructor, server.connect(), server.close(), all client transports (StreamableHTTPClientTransport, SSEClientTransport, StdioClientTransport), StdioServerTransport, all Zod schemas, all callback return types. Note: callTool() and request() signatures changed (schema parameter removed, see section 11).

6. McpServer API Changes

The variadic .tool(), .prompt(), .resource() methods are removed. Use the register* methods with a config object.

IMPORTANT: v2 requires schema objects implementing Standard Schema — raw shapes like { name: z.string() } are no longer supported. Wrap with z.object() (Zod v4), or use ArkType's type({...}), or Valibot. For raw JSON Schema, wrap with fromJsonSchema(schema, validator) from @modelcontextprotocol/server. Applies to inputSchema, outputSchema, and argsSchema.

Tools

// v1: server.tool(name, schema, callback) - raw shape worked
server.tool('greet', { name: z.string() }, async ({ name }) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
});

// v1: server.tool(name, description, schema, callback)
server.tool('greet', 'Greet a user', { name: z.string() }, async ({ name }) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
});

// v2: server.registerTool(name, config, callback)
server.registerTool(
    'greet',
    {
        description: 'Greet a user',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => {
        return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
    }
);

Config object fields: title?, description?, inputSchema?, outputSchema?, annotations?, _meta?

Prompts

// v1: server.prompt(name, schema, callback) - raw shape worked
server.prompt('summarize', { text: z.string() }, async ({ text }) => {
    return { messages: [{ role: 'user', content: { type: 'text', text } }] };
});

// v2: server.registerPrompt(name, config, callback)
server.registerPrompt(
    'summarize',
    {
        argsSchema: z.object({ text: z.string() })
    },
    async ({ text }) => {
        return { messages: [{ role: 'user', content: { type: 'text', text } }] };
    }
);

Config object fields: title?, description?, argsSchema?

Resources

// v1: server.resource(name, uri, callback)
server.resource('config', 'config://app', async uri => {
    return { contents: [{ uri: uri.href, text: '{}' }] };
});

// v2: server.registerResource(name, uri, metadata, callback)
server.registerResource('config', 'config://app', {}, async uri => {
    return { contents: [{ uri: uri.href, text: '{}' }] };
});

Note: the third argument (metadata) is required — pass {} if no metadata.

Schema Migration Quick Reference

Removed core exports

7. Headers API

Transport constructors and RequestInfo.headers now use the Web Standard Headers object instead of plain objects.

// v1: plain object, bracket access
headers: { 'Authorization': 'Bearer token' }
extra.requestInfo?.headers['mcp-session-id']

// v2: Headers object, .get() access
headers: new Headers({ 'Authorization': 'Bearer token' })
ctx.http?.req?.headers.get('mcp-session-id')

8. Removed Server Features

SSE server transport

SSEServerTransport removed entirely. Migrate to NodeStreamableHTTPServerTransport (from @modelcontextprotocol/node). Client-side SSEClientTransport still available for connecting to legacy servers.

Server-side auth

All server OAuth exports removed: mcpAuthRouter, OAuthServerProvider, OAuthTokenVerifier, requireBearerAuth, authenticateClient, ProxyOAuthServerProvider, allowedMethods, and associated types. Use an external auth library (e.g., better-auth). See examples/server/src/ for demos.

Host header validation (Express)

hostHeaderValidation() and localhostHostValidation() moved from server package to @modelcontextprotocol/express. Signature changed: takes string[] instead of options object.

// v1
import { hostHeaderValidation } from '@modelcontextprotocol/sdk/server/middleware.js';
app.use(hostHeaderValidation({ allowedHosts: ['example.com'] }));

// v2
import { hostHeaderValidation } from '@modelcontextprotocol/express';
app.use(hostHeaderValidation(['example.com']));

The server package now exports framework-agnostic alternatives: validateHostHeader(), localhostAllowedHostnames(), hostHeaderValidationResponse().

9. setRequestHandler / setNotificationHandler API

The low-level handler registration methods now take a method string instead of a Zod schema.

// v1: schema-based
server.setRequestHandler(InitializeRequestSchema, async (request) => { ... });
server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => { ... });

// v2: method string
server.setRequestHandler('initialize', async (request) => { ... });
server.setNotificationHandler('notifications/message', (notification) => { ... });

Schema to method string mapping:

Request/notification params remain fully typed. Remove unused schema imports after migration.

10. Request Handler Context Types

RequestHandlerExtra → structured context types with nested groups. Rename extra → ctx in all handler callbacks.

ServerContext convenience methods (new in v2, no v1 equivalent):

11. Schema parameter removed from request(), send(), and callTool()

Protocol.request(), BaseContext.mcpReq.send(), and Client.callTool() no longer take a Zod result schema argument. The SDK resolves the schema internally from the method name.

// v1: schema required
import { CallToolResultSchema, ElicitResultSchema } from '@modelcontextprotocol/sdk/types.js';
const result = await client.request({ method: 'tools/call', params: { ... } }, CallToolResultSchema);
const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } }, ElicitResultSchema);
const tool = await client.callTool({ name: 'my-tool', arguments: {} }, CompatibilityCallToolResultSchema);

// v2: no schema argument
const result = await client.request({ method: 'tools/call', params: { ... } });
const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } });
const tool = await client.callTool({ name: 'my-tool', arguments: {} });

Remove unused schema imports: CallToolResultSchema, CompatibilityCallToolResultSchema, ElicitResultSchema, CreateMessageResultSchema, etc., when they were only used in request()/send()/callTool() calls.

12. Client Behavioral Changes

Client.listPrompts(), listResources(), listResourceTemplates(), listTools() now return empty results when the server lacks the corresponding capability (instead of sending the request). Set enforceStrictCapabilities: true in ClientOptions to throw an error instead.

13. Runtime-Specific JSON Schema Validators (Enhancement)

The SDK now auto-selects the appropriate JSON Schema validator based on runtime:

• Node.js → AjvJsonSchemaValidator (no change from v1)
• Cloudflare Workers (workerd) → CfWorkerJsonSchemaValidator (previously required manual config)

No action required for most users. Cloudflare Workers users can remove explicit jsonSchemaValidator configuration:

// v1 (Cloudflare Workers): Required explicit validator
new McpServer(
    { name: 'server', version: '1.0.0' },
    {
        jsonSchemaValidator: new CfWorkerJsonSchemaValidator()
    }
);

// v2 (Cloudflare Workers): Auto-selected, explicit config optional
new McpServer({ name: 'server', version: '1.0.0' }, {});

Access validators via _shims export: import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/server/_shims';

14. Migration Steps (apply in this order)

1. Update package.json: npm uninstall @modelcontextprotocol/sdk, install the appropriate v2 packages
2. Replace all imports from @modelcontextprotocol/sdk/... using the import mapping tables (sections 3-4), including StreamableHTTPServerTransport → NodeStreamableHTTPServerTransport
3. Replace removed type aliases (JSONRPCError → JSONRPCErrorResponse, etc.) per section 5
4. Replace .tool() / .prompt() / .resource() calls with registerTool / registerPrompt / registerResource per section 6
5. Wrap all raw Zod shapes with z.object(): Change inputSchema: { name: z.string() } → inputSchema: z.object({ name: z.string() }). Same for outputSchema in tools and argsSchema in prompts.
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, migrate to an external auth library
10. If relying on listTools()/listPrompts()/etc. throwing on missing capabilities, set enforceStrictCapabilities: true
11. Verify: build with tsc / run tests