feat(compat): add McpError/ErrorCode aliases, OAuthError.errorCode getter, and legacy OAuth error subclasses

v1-compat shims (all @deprecated, removed in v3):
- McpError -> ProtocolError, ErrorCode -> ProtocolErrorCode (re-export aliases)
- OAuthError.errorCode getter -> .code (warns once)
- 17 OAuth error subclasses (InvalidTokenError etc.) + CustomOAuthError as
  thin wrappers around OAuthError(OAuthErrorCode.X, ...), preserving v1
  constructor signature, static errorCode, and instanceof OAuthError

InvalidRequestError is defined in oauthErrorsCompat.ts but intentionally not
re-exported from core/public to avoid colliding with the JSON-RPC
InvalidRequestError interface from types.ts; the sdk meta-package
server/auth/errors.js subpath will surface it.

Author: felixweinberger

.changeset/error-compat-aliases.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Add v1-compat error aliases: `McpError`/`ErrorCode` (alias `ProtocolError`/`ProtocolErrorCode`, with `ConnectionClosed`/`RequestTimeout` from `SdkErrorCode`), `OAuthError.errorCode` getter (alias `.code`), `JSONRPCError`/`isJSONRPCError`, the 17 v1 OAuth error subclasses (`InvalidTokenError`, `ServerError`, …) as thin wrappers around `OAuthError` + `OAuthErrorCode`, and `StreamableHTTPError` (construct-only `@deprecated` shim; v2 throws `SdkError`).

packages/core/src/auth/errors.ts

@@ -107,6 +107,13 @@ export class OAuthError extends Error {
         this.name = 'OAuthError';
     }
 
+    /**
+     * v1 alias for {@linkcode OAuthError.code | .code}.
+     */
+    get errorCode(): string {
+        return this.code;
+    }
+
     /**
      * Converts the error to a standard OAuth error response object.
      */

packages/core/src/errors/oauthErrorsCompat.ts

@@ -0,0 +1,77 @@
+/**
+ * v1-compat: OAuth error subclasses.
+ *
+ * v1 shipped one `Error` subclass per OAuth error code (e.g. `InvalidTokenError`).
+ * v2 also exposes the consolidated {@link OAuthError} + {@link OAuthErrorCode} enum.
+ * These thin wrappers preserve `throw new InvalidTokenError(msg)` and `instanceof`
+ * patterns from v1 and set `.code` to the matching enum value.
+ */
+
+import { OAuthError, OAuthErrorCode } from '../auth/errors.js';
+
+type OAuthErrorSubclass = {
+    new (message: string, errorUri?: string): OAuthError;
+    /** v1 static field. v2-preferred is the instance `.code` property. */
+    errorCode: string;
+};
+
+function sub(code: OAuthErrorCode, name: string): OAuthErrorSubclass {
+    return class extends OAuthError {
+        static errorCode = code as string;
+        constructor(message: string, errorUri?: string) {
+            super(code, message, errorUri);
+            this.name = name;
+        }
+    };
+}
+
+/* eslint-disable @typescript-eslint/naming-convention */
+
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidRequest, ...)`. */
+export const InvalidRequestError = sub(OAuthErrorCode.InvalidRequest, 'InvalidRequestError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidClient, ...)`. */
+export const InvalidClientError = sub(OAuthErrorCode.InvalidClient, 'InvalidClientError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidGrant, ...)`. */
+export const InvalidGrantError = sub(OAuthErrorCode.InvalidGrant, 'InvalidGrantError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.UnauthorizedClient, ...)`. */
+export const UnauthorizedClientError = sub(OAuthErrorCode.UnauthorizedClient, 'UnauthorizedClientError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.UnsupportedGrantType, ...)`. */
+export const UnsupportedGrantTypeError = sub(OAuthErrorCode.UnsupportedGrantType, 'UnsupportedGrantTypeError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidScope, ...)`. */
+export const InvalidScopeError = sub(OAuthErrorCode.InvalidScope, 'InvalidScopeError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.AccessDenied, ...)`. */
+export const AccessDeniedError = sub(OAuthErrorCode.AccessDenied, 'AccessDeniedError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.ServerError, ...)`. */
+export const ServerError = sub(OAuthErrorCode.ServerError, 'ServerError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.TemporarilyUnavailable, ...)`. */
+export const TemporarilyUnavailableError = sub(OAuthErrorCode.TemporarilyUnavailable, 'TemporarilyUnavailableError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.UnsupportedResponseType, ...)`. */
+export const UnsupportedResponseTypeError = sub(OAuthErrorCode.UnsupportedResponseType, 'UnsupportedResponseTypeError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.UnsupportedTokenType, ...)`. */
+export const UnsupportedTokenTypeError = sub(OAuthErrorCode.UnsupportedTokenType, 'UnsupportedTokenTypeError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidToken, ...)`. */
+export const InvalidTokenError = sub(OAuthErrorCode.InvalidToken, 'InvalidTokenError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.MethodNotAllowed, ...)`. */
+export const MethodNotAllowedError = sub(OAuthErrorCode.MethodNotAllowed, 'MethodNotAllowedError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.TooManyRequests, ...)`. */
+export const TooManyRequestsError = sub(OAuthErrorCode.TooManyRequests, 'TooManyRequestsError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidClientMetadata, ...)`. */
+export const InvalidClientMetadataError = sub(OAuthErrorCode.InvalidClientMetadata, 'InvalidClientMetadataError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InsufficientScope, ...)`. */
+export const InsufficientScopeError = sub(OAuthErrorCode.InsufficientScope, 'InsufficientScopeError');
+/** Equivalent to `new OAuthError(OAuthErrorCode.InvalidTarget, ...)`. */
+export const InvalidTargetError = sub(OAuthErrorCode.InvalidTarget, 'InvalidTargetError');
+
+/**
+ * v1 base class for custom OAuth error codes.
+ *
+ * v1 pattern was `class MyErr extends CustomOAuthError { static errorCode = 'my_code' }`;
+ * this preserves that by reading `static errorCode` from the concrete subclass.
+ * v2-preferred is to construct {@link OAuthError} directly with a custom code string.
+ */
+export class CustomOAuthError extends OAuthError {
+    static errorCode: string;
+    constructor(message: string, errorUri?: string) {
+        super((new.target as typeof CustomOAuthError).errorCode, message, errorUri);
+    }
+}

packages/core/src/errors/streamableHttpErrorCompat.ts

@@ -0,0 +1,23 @@
+import { deprecate } from '../util/deprecate.js';
+
+/**
+ * @deprecated v1-compat shim. v2 client transports throw {@linkcode SdkError} with a
+ * `SdkErrorCode.ClientHttp*` code and the HTTP status under `data.status`; they do not
+ * throw this class. This shim is **construct-only**: it preserves the v1 shape (`.code`
+ * is the HTTP status number) so existing `throw new StreamableHTTPError(...)` and `.code`
+ * usages compile, but `catch`-side code testing `instanceof StreamableHTTPError` will not
+ * match SDK-thrown errors. Update catch-side code to `instanceof SdkError`.
+ */
+export class StreamableHTTPError extends Error {
+    constructor(
+        public readonly code: number,
+        message?: string
+    ) {
+        super(message ?? `HTTP ${code}`);
+        this.name = 'StreamableHTTPError';
+        deprecate(
+            'StreamableHTTPError',
+            'StreamableHTTPError is not thrown by v2; catch SdkError with a SdkErrorCode.ClientHttp* code instead.'
+        );
+    }
+}

packages/core/src/exports/public/index.ts

@@ -100,13 +100,64 @@ export { ProtocolErrorCode } from '../../types/enums.js';
 // Error classes
 export { ProtocolError, UrlElicitationRequiredError } from '../../types/errors.js';
 
+// --- v1-compat aliases ---
+import { SdkErrorCode as _SdkErrorCode } from '../../errors/sdkErrors.js';
+import { ProtocolErrorCode as _ProtocolErrorCode } from '../../types/enums.js';
+/**
+ * v1 name. v2 also exposes the underlying split: {@linkcode ProtocolErrorCode} for
+ * protocol-level (wire) errors and {@linkcode SdkErrorCode} for local SDK errors.
+ * Note `ConnectionClosed`/`RequestTimeout` moved to `SdkErrorCode` in v2 and are now
+ * thrown as `SdkError`, not `ProtocolError`.
+ */
+export const ErrorCode = {
+    ..._ProtocolErrorCode,
+    /** Now {@linkcode SdkErrorCode.ConnectionClosed}; thrown as `SdkError`, not `McpError`. */
+    ConnectionClosed: _SdkErrorCode.ConnectionClosed,
+    /** Now {@linkcode SdkErrorCode.RequestTimeout}; thrown as `SdkError`, not `McpError`. */
+    RequestTimeout: _SdkErrorCode.RequestTimeout
+} as const;
+/** See {@linkcode ErrorCode} const. */
+export type ErrorCode = _ProtocolErrorCode | typeof _SdkErrorCode.ConnectionClosed | typeof _SdkErrorCode.RequestTimeout;
+export {
+    /** v1 name. v2 also exposes this as {@linkcode ProtocolError}. */
+    ProtocolError as McpError
+} from '../../types/errors.js';
+// Note: InvalidRequestError is intentionally omitted here — it collides with the
+// JSON-RPC `InvalidRequestError` interface re-exported from types.ts below. v1 users
+// imported it from `server/auth/errors.js`, which the sdk meta-package subpath provides.
+export {
+    AccessDeniedError,
+    CustomOAuthError,
+    InsufficientScopeError,
+    InvalidClientError,
+    InvalidClientMetadataError,
+    InvalidGrantError,
+    InvalidScopeError,
+    InvalidTargetError,
+    InvalidTokenError,
+    MethodNotAllowedError,
+    ServerError,
+    TemporarilyUnavailableError,
+    TooManyRequestsError,
+    UnauthorizedClientError,
+    UnsupportedGrantTypeError,
+    UnsupportedResponseTypeError,
+    UnsupportedTokenTypeError
+} from '../../errors/oauthErrorsCompat.js';
+export { StreamableHTTPError } from '../../errors/streamableHttpErrorCompat.js';
+/** v1 name. v2 also exposes this as {@linkcode JSONRPCErrorResponse}. */
+export type { JSONRPCErrorResponse as JSONRPCError } from '../../types/spec.types.js';
+// --- end v1-compat ---
+
 // Type guards and message parsing
 export {
     assertCompleteRequestPrompt,
     assertCompleteRequestResourceTemplate,
     isCallToolResult,
     isInitializedNotification,
     isInitializeRequest,
+    /** v1 name. v2 also exposes this as {@linkcode isJSONRPCErrorResponse}. */
+    isJSONRPCErrorResponse as isJSONRPCError,
     isJSONRPCErrorResponse,
     isJSONRPCNotification,
     isJSONRPCRequest,

packages/core/src/index.ts

@@ -48,5 +48,5 @@ export * from './validators/fromJsonSchema.js';
  */
 
 // Core types only - implementations are exported via separate entry points
-export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
 export { deprecate } from './util/deprecate.js';
+export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';

packages/core/test/errors/compat.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+    ErrorCode,
+    InvalidTokenError,
+    McpError,
+    OAuthError,
+    OAuthErrorCode,
+    ProtocolError,
+    ProtocolErrorCode,
+    SdkErrorCode,
+    StreamableHTTPError
+} from '../../src/exports/public/index.js';
+import { CustomOAuthError, ServerError } from '../../src/errors/oauthErrorsCompat.js';
+
+describe('v1-compat error aliases', () => {
+    it('McpError / ErrorCode alias ProtocolError / ProtocolErrorCode (+ ConnectionClosed/RequestTimeout from SdkErrorCode)', () => {
+        expect(McpError).toBe(ProtocolError);
+        expect(ErrorCode.InvalidParams).toBe(ProtocolErrorCode.InvalidParams);
+        expect(ErrorCode.ConnectionClosed).toBe(SdkErrorCode.ConnectionClosed);
+        expect(ErrorCode.RequestTimeout).toBe(SdkErrorCode.RequestTimeout);
+        const e = new McpError(ErrorCode.InvalidParams, 'x');
+        expect(e).toBeInstanceOf(ProtocolError);
+        expect(e.code).toBe(ProtocolErrorCode.InvalidParams);
+    });
+
+    it('OAuthError.errorCode getter returns .code (no warning)', () => {
+        const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const e = new OAuthError(OAuthErrorCode.InvalidToken, 'bad');
+        expect(e.errorCode).toBe(OAuthErrorCode.InvalidToken);
+        expect(e.errorCode).toBe('invalid_token');
+        expect(spy).not.toHaveBeenCalled();
+        spy.mockRestore();
+    });
+
+    it('InvalidTokenError is an OAuthError with .code = InvalidToken (no warning)', () => {
+        const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const e = new InvalidTokenError('expired');
+        expect(e).toBeInstanceOf(OAuthError);
+        expect(e.code).toBe(OAuthErrorCode.InvalidToken);
+        expect(e.message).toBe('expired');
+        expect(spy).not.toHaveBeenCalled();
+        spy.mockRestore();
+    });
+
+    it('subclass static errorCode and toResponseObject() match v1 wire format', () => {
+        expect(ServerError.errorCode).toBe('server_error');
+        const e = new ServerError('boom');
+        expect(e.toResponseObject()).toEqual({ error: 'server_error', error_description: 'boom' });
+    });
+
+    it('CustomOAuthError reads static errorCode from concrete subclass', () => {
+        class MyError extends CustomOAuthError {
+            static override errorCode = 'my_custom_code';
+        }
+        const e = new MyError('nope');
+        expect(e).toBeInstanceOf(OAuthError);
+        expect(e.code).toBe('my_custom_code');
+    });
+
+    it('StreamableHTTPError preserves v1 shape and warns once (construct-only shim)', () => {
+        const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const e = new StreamableHTTPError(503, 'Service Unavailable');
+        expect(e.code).toBe(503);
+        expect(e.name).toBe('StreamableHTTPError');
+        new StreamableHTTPError(404);
+        expect(spy).toHaveBeenCalledTimes(1);
+        spy.mockRestore();
+    });
+});