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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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

[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(errorinstanceofMcpError&&error.code===ErrorCode.RequestTimeout){ ... }// After:if(errorinstanceofSdkError&&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(errorinstanceofInvalidClientError){ ... }// After:import{OAuthError,OAuthErrorCode}from'@modelcontextprotocol/core';if(errorinstanceofOAuthError&&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