v2: Errors refactor (ProtocolError, SdkError, OAuthError)

[KKonstantinov]

Error Hierarchy Refactoring

This PR refactors the SDK's error system to create a clear distinction between protocol errors that cross the wire, local SDK errors, and OAuth errors.

Motivation and Context

The SDK previously used McpError with numeric codes (ErrorCode.RequestTimeout, ErrorCode.ConnectionClosed) for local timeout/connection errors. However, these errors never cross the wire as JSON-RPC responses - they are rejected locally. Using protocol error codes for local errors was semantically inconsistent.

Additionally, OAuth errors used many individual subclasses (e.g., InvalidClientError, InvalidGrantError, ServerError) that only differed in their error code. This was unnecessarily complex.

This change introduces a structured error hierarchy:

• ProtocolError (renamed from McpError): For errors that are serialized and sent as JSON-RPC error responses
• SdkError with SdkErrorCode enum: For local errors that are thrown/rejected locally and never leave the SDK
• OAuthError with OAuthErrorCode enum: For OAuth-related errors (consolidated from many subclasses)

classDiagram
    class Error {
        +string message
        +string name
    }

    class ProtocolError {
        +number code
        +string message
        +unknown data
        +toResponseObject()
        +fromError()
    }

    class SdkError {
        +SdkErrorCode code
        +string message
        +unknown data
    }

    class OAuthError {
        +OAuthErrorCode code
        +string message
        +string errorUri
        +toResponseObject()
        +fromResponse()
    }

    class ProtocolErrorCode {
        <<enumeration>>
        ParseError = -32700
        InvalidRequest = -32600
        MethodNotFound = -32601
        InvalidParams = -32602
        InternalError = -32603
        UrlElicitationRequired = -32042
    }

    class SdkErrorCode {
        <<enumeration>>
        NotConnected
        AlreadyConnected
        NotInitialized
        CapabilityNotSupported
        RequestTimeout
        ConnectionClosed
        SendFailed
    }

    class OAuthErrorCode {
        <<enumeration>>
        InvalidRequest
        InvalidClient
        InvalidGrant
        UnauthorizedClient
        ...17 codes total
    }

    Error <|-- ProtocolError : extends
    Error <|-- SdkError : extends
    Error <|-- OAuthError : extends

    ProtocolError --> ProtocolErrorCode : uses
    SdkError --> SdkErrorCode : uses
    OAuthError --> OAuthErrorCode : uses

    note for ProtocolError "Crosses the wire as JSON-RPC error response"
    note for SdkError "Local errors, never serialized"
    note for OAuthError "OAuth 2.0 errors per RFC 6749"

Loading

How Has This Been Tested?

• All existing tests pass (430+ core tests, 700+ integration tests)
• Updated test assertions to use new error types
• Verified typecheck passes across all packages

Breaking Changes

Yes, this is a breaking change. Users will need to update:

1. Protocol/SDK Error Changes

Imports: McpError → ProtocolError, ErrorCode → ProtocolErrorCode

Error handling for timeouts/connection errors: Use SdkError with SdkErrorCode:

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

// After:
if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) { ... }

New SdkErrorCode enum values:

• SdkErrorCode.NotConnected
• SdkErrorCode.AlreadyConnected
• SdkErrorCode.NotInitialized
• SdkErrorCode.CapabilityNotSupported
• SdkErrorCode.RequestTimeout
• SdkErrorCode.ConnectionClosed
• SdkErrorCode.SendFailed

2. OAuth Error Changes

Individual OAuth error classes replaced with single OAuthError class:

// Before:
import { InvalidClientError, InvalidGrantError } from '@modelcontextprotocol/core';
if (error instanceof InvalidClientError) { ... }

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

Removed classes: InvalidRequestError, InvalidClientError, InvalidGrantError, UnauthorizedClientError, UnsupportedGrantTypeError, InvalidScopeError, AccessDeniedError, ServerError, TemporarilyUnavailableError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, InvalidTokenError, MethodNotAllowedError, TooManyRequestsError, InvalidClientMetadataError, InsufficientScopeError, InvalidTargetError, CustomOAuthError

Removed constant: OAUTH_ERRORS

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Files changed:

• packages/core/src/errors/sdkErrors.ts (new) - SdkError class and SdkErrorCode enum
• packages/core/src/auth/errors.ts - Refactored to single OAuthError class with OAuthErrorCode enum
• packages/core/src/types/types.ts - Renamed McpError → ProtocolError, ErrorCode → ProtocolErrorCode
• packages/core/src/shared/protocol.ts - Use SdkError for timeouts/connection
• packages/server/src/server/server.ts - Use SdkError for capability errors
• packages/client/src/client/client.ts - Use SdkError for capability errors
• packages/client/src/client/auth.ts - Updated to use OAuthError with OAuthErrorCode
• Transport files - Use SdkError for "not connected" errors
• docs/migration.md - Updated with error migration guide
• docs/migration-SKILL.md - Updated with LLM-optimized migration tables

[changeset-bot]

⚠️ No Changeset found

Latest commit: f6f02e3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1454

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1454

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1454

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1454

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1454

commit: f6f02e3

[mattzcarey]

looks good

[mattzcarey]

LGTM