hidorakai002/ai-workspace-archive/docs

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: