McpClientError

Errors produced by McpClient operations and transports.

Every failure is an McpClientError whose reason is one of the reason classes in this module: transport, protocol, HTTP, unsupported feature, closed connection, timeout, limit, configuration, validation or tool-reported errors.

15 exports Since v4.0.6 Source

Errors

McpClientError

Since v4.0.6

Error wrapping an MCP client or transport failure reason.

Details

Use Effect.catchReason or Effect.catchReasons to recover from selected reasons. The error's message and cause come from its reason.

Signature

declare class McpClientError extends {
  readonly _tag: "McpClientError";
  readonly reason: TransportError | ProtocolError | HttpError | UnsupportedError | ClosedError | TimeoutError | LimitError | ConfigurationError | ValidationError | ToolError;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "McpClientError";
    readonly reason: TransportError | ProtocolError | HttpError | UnsupportedError | ClosedError | TimeoutError | LimitError | ConfigurationError | ValidationError | ToolError;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError": "~effect/ai/McpClientError";
  readonly cause: TransportError | ProtocolError | HttpError | UnsupportedError | ClosedError | TimeoutError | LimitError | ConfigurationError | ValidationError | ToolError;
  message: string;
}

Example Recovering from a deadline failure

import { Effect } from "effect"
import { McpClientError } from "effect/ai"

const operation = Effect.fail(new McpClientError.McpClientError({
  reason: new McpClientError.TimeoutError({ operation: "tools/call" })
}))
const recovered = operation.pipe(
  Effect.catchReason("McpClientError", "TimeoutError", () => Effect.succeed("deferred"))
)

await Effect.runPromise(recovered) // => "deferred"

Guards

isMcpClientError

Since v4.0.6

Returns whether a value is an McpClientError.

Signature

declare function isMcpClientError(u: unknown): u is McpClientError

isMcpClientErrorReason

Since v4.0.6

Returns whether a value is one of the McpClientError reasons.

Signature

declare function isMcpClientErrorReason(u: unknown): u is McpClientErrorReason

Models

McpClientErrorReason

type

Since v4.0.6

Union of MCP client and transport failure reasons.

Signature

type McpClientErrorReason = TransportError | ProtocolError | HttpError | UnsupportedError | ClosedError | TimeoutError | LimitError | ConfigurationError | ValidationError | ToolError

Reasons

ClosedError

Since v4.0.6

The client, its transport or its legacy HTTP session is closed.

Signature

declare class ClosedError extends {
  readonly _tag: "ClosedError";
  readonly description?: string;
  readonly sessionExpired?: boolean;
} & YieldableError<this> {
  constructor(...args: [props?: {
    readonly _tag?: "ClosedError";
    readonly description?: string;
    readonly sessionExpired?: boolean;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

ConfigurationError

Since v4.0.6

Client or toolkit options are invalid.

Signature

declare class ConfigurationError extends {
  readonly _tag: "ConfigurationError";
  readonly cause?: unknown;
  readonly description: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ConfigurationError";
    readonly cause?: unknown;
    readonly description: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

HttpError

Since v4.0.6

The server answered an HTTP request with a non-success status. A JSON-RPC error in the response body supplies code, data and description.

Signature

declare class HttpError extends {
  readonly _tag: "HttpError";
  readonly code?: number;
  readonly data?: unknown;
  readonly description?: string;
  readonly retryAfter?: string;
  readonly status: number;
  readonly wwwAuthenticate?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "HttpError";
    readonly code?: number;
    readonly data?: unknown;
    readonly description?: string;
    readonly retryAfter?: string;
    readonly status: number;
    readonly wwwAuthenticate?: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

LimitError

Since v4.0.6

A message or a discovery scan exceeded a client limit.

Signature

declare class LimitError extends {
  readonly _tag: "LimitError";
  readonly description: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "LimitError";
    readonly description: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

ProtocolError

Since v4.0.6

The server returned a JSON-RPC error, or sent a message that is not valid JSON-RPC for the selected protocol.

Signature

declare class ProtocolError extends {
  readonly _tag: "ProtocolError";
  readonly cause?: unknown;
  readonly code?: number;
  readonly data?: unknown;
  readonly description?: string;
} & YieldableError<this> {
  constructor(...args: [props?: {
    readonly _tag?: "ProtocolError";
    readonly cause?: unknown;
    readonly code?: number;
    readonly data?: unknown;
    readonly description?: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

TimeoutError

Since v4.0.6

An operation did not complete within its deadline.

Signature

declare class TimeoutError extends {
  readonly _tag: "TimeoutError";
  readonly operation: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "TimeoutError";
    readonly operation: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

ToolError

Since v4.0.6

A tool reported an execution error with isError. The complete result is retained.

Signature

declare class ToolError extends {
  readonly _tag: "ToolError";
  readonly result: CallToolResult;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ToolError";
    readonly result: CallToolResult;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

TransportError

Since v4.0.6

The connection to the server failed: a process or HTTP request could not be started, written or read, or ended before the response.

Signature

declare class TransportError extends {
  readonly _tag: "TransportError";
  readonly cause?: unknown;
  readonly description?: string;
} & YieldableError<this> {
  constructor(...args: [props?: {
    readonly _tag?: "TransportError";
    readonly cause?: unknown;
    readonly description?: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

UnsupportedError

Since v4.0.6

The server or the selected protocol does not support the requested operation, or a tool result cannot be converted for a language model.

Signature

declare class UnsupportedError extends {
  readonly _tag: "UnsupportedError";
  readonly description: string;
  readonly result?: CallToolResult;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UnsupportedError";
    readonly description: string;
    readonly result?: CallToolResult;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

ValidationError

Since v4.0.6

A request payload, tool argument or result failed schema validation.

Signature

declare class ValidationError extends {
  readonly _tag: "ValidationError";
  readonly cause?: unknown;
  readonly description: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ValidationError";
    readonly cause?: unknown;
    readonly description: string;
  }, options?: MakeOptions]);
  readonly "~effect/ai/McpClientError/Reason": "~effect/ai/McpClientError/Reason";
  message: string;
}

Schemas

McpClientErrorReason

Since v4.0.6

Schema for the reasons carried by an McpClientError.

Signature

declare const McpClientErrorReason: Union<[typeof TransportError, typeof ProtocolError, typeof HttpError, typeof UnsupportedError, typeof ClosedError, typeof TimeoutError, typeof LimitError, typeof ConfigurationError, typeof ValidationError, typeof ToolError]>