Skip to content

McpSchema

Defines schemas for Model Context Protocol messages.

MCP clients and servers use these schemas to describe the JSON-RPC requests, notifications, results, and errors that can cross the protocol boundary. This module focuses on message shapes: it defines the shared protocol data model, groups related messages for the RPC layer, and provides helpers for optional fields and parameter metadata. Transport and server behavior live in other modules.

122 exports Added in v4.0.0 Source

Constants

Represents the JSON-RPC error code for internal server errors.

When to use

Use when building an MCP/JSON-RPC error response for an unexpected server-side failure.

Signature

declare const INTERNAL_ERROR_CODE: -32603;

Represents the JSON-RPC error code for invalid method parameters.

When to use

Use when building an MCP/JSON-RPC error response for decoded request parameters that fail method-specific validation.

Signature

declare const INVALID_PARAMS_ERROR_CODE: -32602;

Represents the JSON-RPC error code for requests that are not valid request objects.

When to use

Use when building an MCP/JSON-RPC error response for a syntactically parsed request object that fails request-shape validation.

Signature

declare const INVALID_REQUEST_ERROR_CODE: -32600;

Represents the JSON-RPC error code for requests whose method does not exist or is not available.

When to use

Use when building an MCP/JSON-RPC error response for a request whose method is unknown or unavailable.

Signature

declare const METHOD_NOT_FOUND_ERROR_CODE: -32601;

Represents the JSON-RPC error code for invalid JSON that could not be parsed.

When to use

Use when building an MCP/JSON-RPC error response before a request object is available because the JSON payload could not be parsed.

Signature

declare const PARSE_ERROR_CODE: -32700;

Errors

Represents an MCP/JSON-RPC error for unexpected internal server failures.

When to use

Use to report an unexpected server-side failure while handling a valid request.

Details

Uses the standard JSON-RPC internal error code -32603 and includes InternalError.notImplemented for unimplemented handlers.

Signature

declare class InternalError extends {
  readonly _tag: "InternalError";
  readonly code: -32603;
  readonly data?: any;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "InternalError";
    readonly code?: -32603;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
  static readonly notImplemented: InternalError;
}

Represents an MCP/JSON-RPC error for invalid method parameters.

When to use

Use to report a request whose method parameters do not match the method schema.

Details

Uses the standard JSON-RPC invalid params code -32602.

Signature

declare class InvalidParams extends {
  readonly _tag: "InvalidParams";
  readonly code: -32602;
  readonly data?: any;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "InvalidParams";
    readonly code?: -32602;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
}

Represents an MCP/JSON-RPC error for a request object that is not valid.

When to use

Use to report a syntactically parsed JSON-RPC request that is not a valid request object.

Details

Uses the standard JSON-RPC invalid request code -32600.

Signature

declare class InvalidRequest extends {
  readonly _tag: "InvalidRequest";
  readonly code: -32600;
  readonly data?: any;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "InvalidRequest";
    readonly code?: -32600;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
}

McpError

Added in v4.0.0 Source

Schema for MCP protocol errors returned in JSON-RPC failure responses, including standard protocol errors and custom McpErrorBase values.

Signature

declare const McpError: Union<
  readonly [
    typeof ParseError,
    typeof InvalidRequest,
    typeof MethodNotFound,
    typeof InvalidParams,
    typeof InternalError,
    typeof McpErrorBase,
  ]
>;

Represents an MCP/JSON-RPC error for an unavailable method.

When to use

Use to report a JSON-RPC method that does not exist or is not available.

Details

Uses the standard JSON-RPC method-not-found code -32601.

Signature

declare class MethodNotFound extends {
  readonly _tag: "MethodNotFound";
  readonly code: -32601;
  readonly data?: any;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "MethodNotFound";
    readonly code?: -32601;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
}

ParseError

Added in v4.0.0 Source

Represents an MCP/JSON-RPC error for invalid JSON that could not be parsed.

When to use

Use to report a JSON parse failure before a valid JSON-RPC request object is available.

Details

Uses the standard JSON-RPC parse error code -32700.

Signature

declare class ParseError extends {
  readonly _tag: "ParseError";
  readonly code: -32700;
  readonly data?: any;
  readonly message: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ParseError";
    readonly code?: -32700;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
}

Guards

isParam

Added in v4.0.0 Source

Returns true when a schema was created with param and therefore carries a resource URI template parameter name.

Signature

declare function isParam(schema: Constraint): schema is Param<string, Top>;

Logging

LoggingLevel

Added in v4.0.0 Source

Schema for log message severity levels, mapped to syslog message severities as specified in RFC 5424 section 6.2.1: https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.

Signature

declare const LoggingLevel: Schema.Literals<
  ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]
>;

LoggingLevel type

Added in v4.0.0 Source

Type represented by the MCP logging level schema, mapped to syslog message severities as specified in RFC 5424 section 6.2.1: https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.

Signature

type LoggingLevel = typeof LoggingLevel.Type;

Sent from the server to the client carrying a log message.

Details

The notification includes the severity level, optional logger name, and JSON-serializable log data.

Signature

declare class LoggingMessageNotification extends ({}) {
  constructor(_: never);
}

SetLevel

Added in v4.0.0 Source

Sent from the client to the server to enable or adjust logging.

Signature

declare class SetLevel extends ({}) {
  constructor(_: never);
}

Middleware

RPC middleware that provides McpServerClient to handlers for initialized MCP clients.

Signature

declare class McpServerClientMiddleware extends Shape<"effect/ai/McpSchema/McpServerClientMiddleware", RpcMiddleware<McpServerClient, never, never>, this> & {
  readonly "~effect/rpc/RpcMiddleware": {
    readonly clientError: never;
    readonly error: Never;
    readonly provides: McpServerClient;
    readonly requires: never;
  };
} {
  constructor(_: never);
}

Models

Cursor type

Added in v4.0.0 Source

Type represented by the MCP cursor schema.

Details

A cursor is an opaque string token used to continue paginated requests.

Signature

type Cursor = typeof Cursor.Type;

optionalWithDefault interface

Added in v4.0.0 Source

Schema type returned by optionalWithDefault.

Details

It represents an optional struct field that supplies a default value when the field is absent during decoding or construction.

Signature

interface optionalWithDefault<
  S extends Schema.Constraint & Schema.WithoutConstructorDefault,
> extends withConstructorDefault<
  Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>
> {
  constructor(_: never);
}

ProgressToken type

Added in v4.0.0 Source

Type represented by the MCP progress token schema.

Signature

type ProgressToken = typeof ProgressToken.Type;

RequestId type

Added in v4.0.0 Source

Type represented by the JSON-RPC request identifier schema.

Signature

type RequestId = typeof RequestId.Type;

Role type

Added in v4.0.0 Source

Type represented by the MCP role schema.

Details

Valid roles are "user" and "assistant".

Signature

type Role = typeof Role.Type;

Parameters

param

Added in v4.0.0 Source

Creates a parameter for a resource URI template.

Signature

declare function param<Name extends string, S extends Constraint>(
  name: Name,
  schema: S,
): Param<Name, S>;

Param interface

Added in v4.0.0 Source

Schema wrapper used for resource URI template parameters.

Details

A Param behaves like the wrapped schema while carrying the parameter name used for template compilation and completion lookup.

Signature

interface Param<Name extends string, S extends Schema.Constraint> extends BottomLazy<
  S["ast"],
  Param<Name, S>,
  S["~type.parameters"],
  S["~type.mutability"],
  S["~type.optionality"],
  S["~type.constructor.default"],
  S["~encoded.mutability"],
  S["~encoded.optionality"]
> {
  constructor(_: never);
  readonly "~effect/ai/McpSchema/ParamSchema": "~effect/ai/McpSchema/ParamSchema";
  readonly "~type.make": S["~type.make"];
  readonly "~type.make.in": S["~type.make.in"];
  readonly DecodingServices: S["DecodingServices"];
  readonly Encoded: S["Encoded"];
  readonly EncodingServices: S["EncodingServices"];
  readonly Iso: S["Iso"];
  readonly name: Name;
  readonly Rebuild: Param<Name, S>;
  readonly schema: S;
  readonly Type: S["Type"];
}

Protocols

CallTool

Added in v4.0.0 Source

Represents a client request to invoke a tool provided by the server.

When to use

Use when you need to represent a client request that already knows the tool name and asks the server to execute it with argument values.

See

  • ListTools for discovering available tools before calling one
  • CallToolResult for the successful tool-call result shape

Signature

declare class CallTool extends ({}) {
  constructor(_: never);
}

Sent from either peer to cancel a previously issued request in the same direction.

Details

The payload identifies the request to cancel and may include a human-readable reason.

Signature

declare class CancelledNotification extends ({}) {
  constructor(_: never);
}

ClientFailureEncoded type

Added in v4.0.0 Source

Encoded failure response sent by a client for a server-initiated request.

Signature

type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>;

Encoded union of all client-to-server MCP notification messages.

Signature

type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>;

RPC group for notifications that MCP clients send to the server, such as cancellation, progress, initialization completion, and roots list changes.

Signature

declare class ClientNotificationRpcs extends ({}) {
  constructor(_: never);
}

ClientRequestEncoded type

Added in v4.0.0 Source

Encoded union of all client-to-server MCP request messages.

Signature

type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>;

RPC group for requests that MCP clients send to the server.

Details

The group includes initialization, resource, prompt, tool, logging, completion, and ping requests, and installs McpServerClientMiddleware for handlers.

Signature

declare class ClientRequestRpcs extends ({}) {
  constructor(_: never);
}

ClientRpcs

Added in v4.0.0 Source

RPC group combining all client-to-server MCP requests and notifications.

Signature

declare class ClientRpcs extends ({}) {
  constructor(_: never);
}

ClientSuccessEncoded type

Added in v4.0.0 Source

Encoded success response sent by a client for a server-initiated request.

Signature

type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>;

Complete

Added in v4.0.0 Source

Sent from the client to the server to ask for completion options.

Signature

declare class Complete extends ({}) {
  constructor(_: never);
}

Represents a server request for the client to sample an LLM.

When to use

Use when you need to request model sampling from an MCP client on behalf of a server.

Details

The client chooses the model and should ask the user to approve the sampling request before it begins.

Signature

declare class CreateMessage extends ({}) {
  constructor(_: never);
}

Elicit

Added in v4.0.0 Source

Sent from the server asking the client to collect structured input from the user.

Details

The client responds with accepted content, an explicit decline, or a cancellation.

Signature

declare class Elicit extends ({}) {
  constructor(_: never);
}

FailureEncoded type

Added in v4.0.0 Source

Encoded failure response for an RPC in Group, containing the original request id and encoded error.

Signature

type FailureEncoded<Group extends RpcGroup.Any> =
  RpcGroup.Rpcs<Group> extends infer Rpc
    ? Rpc extends Rpc.Rpc<
        infer _Tag,
        infer _Payload,
        infer _Success,
        infer _Error,
        infer _Middleware
      >
      ? {
          readonly _tag: "Failure";
          readonly error: _Error["Encoded"];
          readonly id: string | number;
        }
      : never
    : never;

FromClientEncoded type

Added in v4.0.0 Source

Encoded MCP messages accepted from a client by the server protocol: client requests and client notifications.

Signature

type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded;

FromServerEncoded type

Added in v4.0.0 Source

Encoded MCP messages emitted by the server protocol to a client: server responses and server notifications.

Signature

type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded;

GetPrompt

Added in v4.0.0 Source

Sent from the client to get a prompt provided by the server.

Signature

declare class GetPrompt extends ({}) {
  constructor(_: never);
}

Initialize

Added in v4.0.0 Source

Sent from the client to the server when it first connects, asking it to begin initialization.

Signature

declare class Initialize extends ({}) {
  constructor(_: never);
}

Sent from the client to the server after initialization has finished.

Signature

declare class InitializedNotification extends ({}) {
  constructor(_: never);
}

ListPrompts

Added in v4.0.0 Source

Sent from the client to request a list of prompts and prompt templates the server has.

Signature

declare class ListPrompts extends ({}) {
  constructor(_: never);
}

Sent from the client to request a list of resources the server has.

Signature

declare class ListResources extends ({}) {
  constructor(_: never);
}

Sent from the client to request a list of resource templates the server has.

Signature

declare class ListResourceTemplates extends ({}) {
  constructor(_: never);
}

ListRoots

Added in v4.0.0 Source

Sent from the server to request a list of root URIs from the client. Roots allow servers to ask for specific directories or files to operate on. A common example for roots is providing a set of repositories or directories a server should operate on.

Details

This request is typically used when the server needs to understand the file system structure or access specific locations that the client has permission to read from.

Signature

declare class ListRoots extends ({}) {
  constructor(_: never);
}

ListTools

Added in v4.0.0 Source

Sent from the client to request a list of tools the server has.

Signature

declare class ListTools extends ({}) {
  constructor(_: never);
}

NotificationEncoded type

Added in v4.0.0 Source

Encoded notification message for an RPC in Group, including the method and encoded payload without a request id.

Signature

type NotificationEncoded<Group extends RpcGroup.Any> =
  RpcGroup.Rpcs<Group> extends infer Rpc
    ? Rpc extends Rpc.Rpc<
        infer _Tag,
        infer _Payload,
        infer _Success,
        infer _Error,
        infer _Middleware
      >
      ? {
          readonly _tag: "Notification";
          readonly method: _Tag;
          readonly payload: _Payload["Encoded"];
        }
      : never
    : never;

Ping

Added in v4.0.0 Source

Represents an MCP ping request used to check whether the peer is still alive.

When to use

Use to implement client or server liveness checks.

Details

The receiver should respond promptly; otherwise the sender may disconnect.

Signature

declare class Ping extends ({}) {
  constructor(_: never);
}

Sent from either peer to report progress for a long-running request.

Signature

declare class ProgressNotification extends ({}) {
  constructor(_: never);
}

Represents a notification that the server's prompt list changed.

When to use

Use to notify clients that prompts/list should be requested again.

Details

Servers may send this notification without a previous client subscription.

Signature

declare class PromptListChangedNotification extends ({}) {
  constructor(_: never);
}

ReadResource

Added in v4.0.0 Source

Sent from the client to the server, to read a specific resource URI.

Signature

declare class ReadResource extends ({}) {
  constructor(_: never);
}

RequestEncoded type

Added in v4.0.0 Source

Encoded JSON-RPC request message for an RPC in Group, including the request id, method, and encoded payload.

Signature

type RequestEncoded<Group extends RpcGroup.Any> =
  RpcGroup.Rpcs<Group> extends infer Rpc
    ? Rpc extends Rpc.Rpc<
        infer _Tag,
        infer _Payload,
        infer _Success,
        infer _Error,
        infer _Middleware
      >
      ? {
          readonly _tag: "Request";
          readonly id: string | number;
          readonly method: _Tag;
          readonly payload: _Payload["Encoded"];
        }
      : never
    : never;

Represents a notification that the server's resource list changed.

When to use

Use to notify clients that resources/list should be requested again.

Details

Servers may send this notification without a previous client subscription.

Signature

declare class ResourceListChangedNotification extends ({}) {
  constructor(_: never);
}

Sent from the server when a subscribed resource URI has changed.

Details

The URI may identify a sub-resource of the resource that the client originally subscribed to.

Signature

declare class ResourceUpdatedNotification extends ({}) {
  constructor(_: never);
}

Represents a notification that the client's root list changed.

When to use

Use to tell the server that it should request an updated roots list.

Details

Send this when the client adds, removes, or modifies a root.

Signature

declare class RootsListChangedNotification extends ({}) {
  constructor(_: never);
}

ServerFailureEncoded type

Added in v4.0.0 Source

Encoded failure response sent by the server for a client-initiated request.

Signature

type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>;

Encoded union of all server-to-client MCP notification messages.

Signature

type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>;

RPC group for notifications that an MCP server can send to a client, including cancellation, progress, logging, and list or resource update notifications.

Signature

declare class ServerNotificationRpcs extends ({}) {
  constructor(_: never);
}

ServerRequestEncoded type

Added in v4.0.0 Source

Encoded union of all server-to-client MCP request messages.

Signature

type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>;

RPC group for requests that an MCP server can send to a client, including ping, sampling, roots listing, and elicitation.

Signature

declare class ServerRequestRpcs extends ({}) {
  constructor(_: never);
}

ServerResultEncoded type

Added in v4.0.0 Source

Encoded server response to a client request, either success or failure.

Signature

type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded;

ServerSuccessEncoded type

Added in v4.0.0 Source

Encoded success response sent by the server for a client-initiated request.

Signature

type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>;

Subscribe

Added in v4.0.0 Source

Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.

Signature

declare class Subscribe extends ({}) {
  constructor(_: never);
}

SuccessEncoded type

Added in v4.0.0 Source

Encoded success response for an RPC in Group, containing the original request id and encoded result.

Signature

type SuccessEncoded<Group extends RpcGroup.Any> =
  RpcGroup.Rpcs<Group> extends infer Rpc
    ? Rpc extends Rpc.Rpc<
        infer _Tag,
        infer _Payload,
        infer _Success,
        infer _Error,
        infer _Middleware
      >
      ? {
          readonly _tag: "Success";
          readonly id: string | number;
          readonly result: _Success["Encoded"];
        }
      : never
    : never;

Represents a notification that the server's tool list changed.

When to use

Use to notify clients that tools/list should be requested again.

Details

Servers may send this notification without a previous client subscription.

Signature

declare class ToolListChangedNotification extends ({}) {
  constructor(_: never);
}

Unsubscribe

Added in v4.0.0 Source

Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.

Signature

declare class Unsubscribe extends ({}) {
  constructor(_: never);
}

Schemas

Annotations

Added in v4.0.0 Source

Schema for optional client-facing annotations on MCP objects.

When to use

Use to describe intended audience and priority metadata for objects shown or processed by a client.

Signature

declare class Annotations extends {
  readonly audience?: readonly Array<"user" | "assistant">;
  readonly priority?: number;
} {
  constructor(_: never);
}

AudioContent

Added in v4.0.0 Source

Represents audio content provided to or from an LLM.

Signature

declare class AudioContent extends {
  readonly annotations?: Annotations;
  readonly data: Uint8Array<ArrayBufferLike>;
  readonly mimeType: string;
  readonly type: "audio";
} {
  constructor(_: never);
}

Schema for binary resource contents represented as a Uint8Array.

Signature

declare class BlobResourceContents extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly blob: Uint8Array<ArrayBufferLike>;
  readonly mimeType?: string;
  readonly uri: string;
} {
  constructor(_: never);
}

Schema for the server's response to a tool call.

Details

Any errors that originate from the tool SHOULD be reported inside the result object, with isError set to true, _not_ as an MCP protocol-level error response. Otherwise, the LLM would not be able to see that an error occurred and self-correct. However, any errors in _finding_ the tool, an error indicating that the server does not support tool calls, or any other exceptional conditions, should be reported as an MCP error response.

Signature

declare class CallToolResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly content: readonly Array<TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink>;
  readonly isError?: boolean;
  readonly structuredContent?: any;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly content: readonly Array<{
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly text: string;
      readonly type?: "text";
    } | {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly data: Uint8Array<ArrayBufferLike>;
      readonly mimeType: string;
      readonly type?: "image";
    } | {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly data: Uint8Array<ArrayBufferLike>;
      readonly mimeType: string;
      readonly type?: "audio";
    } | {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly resource: {
        readonly _meta?: {
          [key: string]: unknown;
        };
        readonly mimeType?: string;
        readonly text: string;
        readonly uri: string;
      } | {
        readonly _meta?: {
          [key: string]: unknown;
        };
        readonly blob: Uint8Array<ArrayBufferLike>;
        readonly mimeType?: string;
        readonly uri: string;
      };
      readonly type?: "resource";
    } | {
      readonly _meta?: {
        [key: string]: unknown;
      };
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly description?: string;
      readonly mimeType?: string;
      readonly name: string;
      readonly size?: number;
      readonly title?: string;
      readonly type?: "resource_link";
      readonly uri: string;
    }>;
    readonly isError?: boolean;
    readonly structuredContent?: any;
  }, options?: MakeOptions]);
}

Describes capabilities advertised by an MCP client.

When to use

Use to describe which optional MCP features a client supports during initialization.

Details

Known capabilities are represented by this schema, but the capability set is open and clients may define additional capabilities.

Signature

declare class ClientCapabilities extends {
  readonly elicitation?: {};
  readonly experimental?: {
    [key: string]: {};
  };
  readonly extensions?: {
    [key: `${string}/${string}`]: Json;
  };
  readonly roots?: {
    readonly listChanged?: boolean;
  };
  readonly sampling?: {};
} {
  constructor(...args: [props?: {
    readonly elicitation?: {};
    readonly experimental?: {
      [key: string]: {};
    };
    readonly extensions?: {
      [key: `${string}/${string}`]: unknown;
    };
    readonly roots?: {
      readonly listChanged?: boolean;
    };
    readonly sampling?: {};
  }, options?: MakeOptions]);
}

Schema for the server's response to a completion/complete request.

Signature

declare class CompleteResult extends {
  readonly completion: {
    readonly hasMore?: boolean;
    readonly total?: number;
    readonly values: readonly Array<string>;
  };
} {
  constructor(_: never);
  static readonly empty: CompleteResult;
}

ContentBlock

Added in v4.0.0 Source

Schema for MCP content blocks that can appear in prompt messages or tool results.

Signature

declare const ContentBlock: Union<
  readonly [
    typeof TextContent,
    typeof ImageContent,
    typeof AudioContent,
    typeof EmbeddedResource,
    typeof ResourceLink,
  ]
>;

Represents a client response to an MCP sampling request.

When to use

Use to return the message produced by client-side model sampling.

Details

The client should let the user inspect the sampled message before returning it to the server.

Signature

declare class CreateMessageResult extends {
  readonly content: TextContent | ImageContent | AudioContent;
  readonly model: string;
  readonly role: "user" | "assistant";
  readonly stopReason?: string;
} {
  constructor(...args: [props: {
    readonly content: {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly text: string;
      readonly type?: "text";
    } | {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly data: Uint8Array<ArrayBufferLike>;
      readonly mimeType: string;
      readonly type?: "image";
    } | {
      readonly annotations?: {
        readonly audience?: readonly Array<"user" | "assistant">;
        readonly priority?: number;
      };
      readonly data: Uint8Array<ArrayBufferLike>;
      readonly mimeType: string;
      readonly type?: "audio";
    };
    readonly model: string;
    readonly role: "user" | "assistant";
    readonly stopReason?: string;
  }, options?: MakeOptions]);
}

Cursor

Added in v4.0.0 Source

Schema for opaque cursor tokens used in pagination.

Signature

declare const Cursor: typeof Schema.String;

Schema for an accepted client response to an elicitation request.

Signature

declare class ElicitAcceptResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly action: "accept";
  readonly content: any;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly action: "accept";
    readonly content: any;
  }, options?: MakeOptions]);
}

Error raised when an MCP elicitation request is declined or fails before accepted content is returned.

Details

The error stores the original elicitation request and, when available, the underlying cause.

Signature

declare class ElicitationDeclined extends {
  readonly _tag: "ElicitationDeclined";
  readonly cause?: unknown;
  readonly request: {
    readonly message: string;
    readonly requestedSchema: any;
  };
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ElicitationDeclined";
    readonly cause?: unknown;
    readonly request: {
      readonly message: string;
      readonly requestedSchema: any;
    };
  }, options?: MakeOptions]);
}

Schema for a declined or canceled client response to an elicitation request.

Signature

declare class ElicitDeclineResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly action: "cancel" | "decline";
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly action: "cancel" | "decline";
  }, options?: MakeOptions]);
}

ElicitResult

Added in v4.0.0 Source

Schema for every client response to an elicitation request.

Signature

declare const ElicitResult: Union<readonly [typeof ElicitAcceptResult, typeof ElicitDeclineResult]>;

Represents resource contents embedded into a prompt or tool call result.

Details

It is up to the client how best to render embedded resources for the benefit of the LLM and/or the user.

Signature

declare class EmbeddedResource extends {
  readonly annotations?: Annotations;
  readonly resource: TextResourceContents | BlobResourceContents;
  readonly type: "resource";
} {
  constructor(_: never);
}

Represents the server response to a prompts/get request from the client.

Signature

declare class GetPromptResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly description?: string;
  readonly messages: readonly Array<PromptMessage>;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly description?: string;
    readonly messages: readonly Array<{
      readonly content: {
        readonly annotations?: {
          readonly audience?: readonly Array<... | ...>;
          readonly priority?: number;
        };
        readonly text: string;
        readonly type?: "text";
      } | {
        readonly annotations?: {
          readonly audience?: readonly Array<... | ...>;
          readonly priority?: number;
        };
        readonly data: Uint8Array<ArrayBufferLike>;
        readonly mimeType: string;
        readonly type?: "image";
      } | {
        readonly annotations?: {
          readonly audience?: readonly Array<... | ...>;
          readonly priority?: number;
        };
        readonly data: Uint8Array<ArrayBufferLike>;
        readonly mimeType: string;
        readonly type?: "audio";
      } | {
        readonly annotations?: {
          readonly audience?: readonly Array<... | ...>;
          readonly priority?: number;
        };
        readonly resource: {
          readonly _meta?: {
            [key: string]: unknown;
          };
          readonly mimeType?: string;
          readonly text: string;
          readonly uri: string;
        } | {
          readonly _meta?: {
            [key: string]: unknown;
          };
          readonly blob: Uint8Array<ArrayBufferLike>;
          readonly mimeType?: string;
          readonly uri: string;
        };
        readonly type?: "resource";
      } | {
        readonly _meta?: {
          [key: string]: unknown;
        };
        readonly annotations?: {
          readonly audience?: readonly Array<... | ...>;
          readonly priority?: number;
        };
        readonly description?: string;
        readonly mimeType?: string;
        readonly name: string;
        readonly size?: number;
        readonly title?: string;
        readonly type?: "resource_link";
        readonly uri: string;
      };
      readonly role: "user" | "assistant";
    }>;
  }, options?: MakeOptions]);
}

ImageContent

Added in v4.0.0 Source

Represents image content provided to or from an LLM.

Signature

declare class ImageContent extends {
  readonly annotations?: Annotations;
  readonly data: Uint8Array<ArrayBufferLike>;
  readonly mimeType: string;
  readonly type: "image";
} {
  constructor(_: never);
}

Describes the name and version of an MCP implementation.

Signature

declare class Implementation extends {
  readonly name: string;
  readonly title?: string;
  readonly version: string;
} {
  constructor(_: never);
}

Schema for the server's response to an initialize request from the client.

Signature

declare class InitializeResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly capabilities: ServerCapabilities;
  readonly instructions?: string;
  readonly protocolVersion: string;
  readonly serverInfo: Implementation;
} {
  constructor(_: never);
}

Represents the server response to a prompts/list request from the client.

Signature

declare class ListPromptsResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly nextCursor?: string;
  readonly prompts: readonly Array<Prompt>;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly nextCursor?: string;
    readonly prompts: readonly Array<Prompt>;
  }, options?: MakeOptions]);
}

Schema for the server's response to a resources/list request from the client.

Signature

declare class ListResourcesResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly nextCursor?: string;
  readonly resources: readonly Array<Resource>;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly nextCursor?: string;
    readonly resources: readonly Array<Resource>;
  }, options?: MakeOptions]);
}

Schema for the server's response to a resources/templates/list request from the client.

Signature

declare class ListResourceTemplatesResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly nextCursor?: string;
  readonly resourceTemplates: readonly Array<ResourceTemplate>;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly nextCursor?: string;
    readonly resourceTemplates: readonly Array<ResourceTemplate>;
  }, options?: MakeOptions]);
}

Represents a client response containing the roots available to the server.

When to use

Use to return the directories or files that an MCP server may operate on.

Signature

declare class ListRootsResult extends {
  readonly roots: readonly Array<Root>;
} {
  constructor(...args: [props: {
    readonly roots: readonly Array<Root>;
  }, options?: MakeOptions]);
}

Schema for the server's response to a tools/list request from the client.

Signature

declare class ListToolsResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly nextCursor?: string;
  readonly tools: readonly Array<Tool>;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly nextCursor?: string;
    readonly tools: readonly Array<Tool>;
  }, options?: MakeOptions]);
}

McpErrorBase

Added in v4.0.0 Source

Schema for MCP and JSON-RPC error objects.

Details

It contains the numeric error code, a concise message, and optional sender-defined data.

Signature

declare class McpErrorBase extends {
  readonly code: number;
  readonly data?: any;
  readonly message: string;
} {
  constructor(...args: [props: {
    readonly code: number;
    readonly data?: any;
    readonly message: string;
  }, options?: MakeOptions]);
}

ModelHint

Added in v4.0.0 Source

Schema for model selection hints.

Details

Keys not declared here are currently left unspecified by the spec and are up to the client to interpret.

Signature

declare class ModelHint extends {
  readonly name?: string;
} {
  constructor(_: never);
}

Schema for the server's model selection preferences requested of the client during sampling.

Details

Because LLMs can vary along multiple dimensions, choosing the "best" model is rarely straightforward. Different models excel in different areas, some are faster but less capable, others are more capable but more expensive, and so on. This interface allows servers to express their priorities across multiple dimensions to help clients make an appropriate selection for their use case.

Gotchas

These preferences are always advisory. The client MAY ignore them. It is also up to the client to decide how to interpret these preferences and how to balance them against other considerations.

Signature

declare class ModelPreferences extends {
  readonly costPriority?: number;
  readonly hints?: readonly Array<ModelHint>;
  readonly intelligencePriority?: number;
  readonly speedPriority?: number;
} {
  constructor(...args: [props?: {
    readonly costPriority?: number;
    readonly hints?: readonly Array<{
      readonly name?: string;
    }>;
    readonly intelligencePriority?: number;
    readonly speedPriority?: number;
  }, options?: MakeOptions]);
}

Schema for optional MCP notification metadata.

Details

The _meta field is reserved for protocol, extension, or implementation metadata attached to a notification.

Signature

declare class NotificationMeta extends {
  readonly _meta?: {
    [key: string]: Json;
  };
} {
  constructor(_: never);
}

optional

Added in v4.0.0 Source

Creates an optional MCP struct-field schema from a required schema.

Details

The field may be absent, and explicit undefined values are omitted when encoding.

Signature

declare function optional<S extends Constraint>(schema: S): decodeTo<optional<S>, optionalKey<S>>;

Marks a struct field as optional and supplies defaultValue when the field is absent.

Details

The default is used during decoding and as the constructor default for the schema field.

Signature

declare const optionalWithDefault: <S extends Constraint & WithoutConstructorDefault>(
  schema: S,
  defaultValue: () => S["Type"],
) => optionalWithDefault<S>;

Schema for MCP request metadata used by paginated requests.

Details

It includes the base request metadata fields plus an optional cursor indicating where the server should continue listing results.

Signature

declare class PaginatedRequestMeta extends {
  readonly _meta?: {
    readonly progressToken?: string | number;
  };
  readonly cursor?: string;
} {
  constructor(_: never);
}

Schema for MCP result metadata returned by paginated operations.

Details

It includes the base result metadata fields plus an optional nextCursor, which indicates that more results may be available.

Signature

declare class PaginatedResultMeta extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly nextCursor?: string;
} {
  constructor(_: never);
}

Schema for MCP progress tokens that associate progress notifications with the original request.

Signature

declare const ProgressToken: Schema.Union<[typeof Schema.String, typeof Schema.Finite]>;

Prompt

Added in v4.0.0 Source

Represents a prompt or prompt template that the server offers.

Signature

declare class Prompt extends {
  readonly arguments?: readonly Array<PromptArgument>;
  readonly description?: string;
  readonly name: string;
  readonly title?: string;
} {
  constructor(...args: [props: {
    readonly arguments?: readonly Array<{
      readonly description?: string;
      readonly name: string;
      readonly required?: boolean;
      readonly title?: string;
    }>;
    readonly description?: string;
    readonly name: string;
    readonly title?: string;
  }, options?: MakeOptions]);
}

Describes an argument that a prompt can accept.

Signature

declare class PromptArgument extends {
  readonly description?: string;
  readonly name: string;
  readonly required?: boolean;
  readonly title?: string;
} {
  constructor(_: never);
}

Describes a message returned as part of a prompt.

Details

This is similar to SamplingMessage, but also supports the embedding of resources from the MCP server.

Signature

declare class PromptMessage extends {
  readonly content: TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;
  readonly role: "user" | "assistant";
} {
  constructor(_: never);
}

Schema for a prompt reference used in autocomplete requests.

Signature

declare class PromptReference extends {
  readonly name: string;
  readonly title?: string;
  readonly type: "ref/prompt";
} {
  constructor(_: never);
}

Schema for the server's response to a resources/read request from the client.

Signature

declare class ReadResourceResult extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly contents: readonly Array<TextResourceContents | BlobResourceContents>;
} {
  constructor(_: never);
}

RequestId

Added in v4.0.0 Source

Schema for JSON-RPC request identifiers, allowing string or number ids.

Signature

declare const RequestId: Schema.Union<[typeof Schema.String, typeof Schema.Finite]>;

RequestMeta

Added in v4.0.0 Source

Schema for optional MCP request metadata.

Details

Request metadata may include a progress token that asks the receiver to send out-of-band progress notifications for the request.

Signature

declare class RequestMeta extends {
  readonly _meta?: {
    readonly progressToken?: string | number;
  };
} {
  constructor(_: never);
}

Resource

Added in v4.0.0 Source

Schema for a known resource that the server is capable of reading.

Signature

declare class Resource extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly annotations?: Annotations;
  readonly description?: string;
  readonly mimeType?: string;
  readonly name: string;
  readonly size?: number;
  readonly title?: string;
  readonly uri: string;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly annotations?: {
      readonly audience?: readonly Array<"user" | "assistant">;
      readonly priority?: number;
    };
    readonly description?: string;
    readonly mimeType?: string;
    readonly name: string;
    readonly size?: number;
    readonly title?: string;
    readonly uri: string;
  }, options?: MakeOptions]);
}

Schema for the contents of a specific resource or sub-resource.

Signature

declare class ResourceContents extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly mimeType?: string;
  readonly uri: string;
} {
  constructor(_: never);
}

Schema for a reference to a resource or resource template definition.

Signature

declare class ResourceReference extends {
  readonly type: "ref/resource";
  readonly uri: string;
} {
  constructor(_: never);
}

Schema for a template description of resources available on the server.

Signature

declare class ResourceTemplate extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly annotations?: Annotations;
  readonly description?: string;
  readonly mimeType?: string;
  readonly name: string;
  readonly title?: string;
  readonly uriTemplate: string;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly annotations?: {
      readonly audience?: readonly Array<"user" | "assistant">;
      readonly priority?: number;
    };
    readonly description?: string;
    readonly mimeType?: string;
    readonly name: string;
    readonly title?: string;
    readonly uriTemplate: string;
  }, options?: MakeOptions]);
}

ResultMeta

Added in v4.0.0 Source

Schema for optional MCP result metadata.

Details

The _meta field is reserved for protocol, extension, or implementation metadata attached to a result.

Signature

declare class ResultMeta extends {
  readonly _meta?: {
    [key: string]: Json;
  };
} {
  constructor(_: never);
}

Role

Added in v4.0.0 Source

Schema for MCP conversation roles, allowing user and assistant.

Signature

declare const Role: Schema.Literals<["user", "assistant"]>;

Root

Added in v4.0.0 Source

Represents a root directory or file that the server can operate on.

Signature

declare class Root extends {
  readonly name?: string;
  readonly uri: string;
} {
  constructor(...args: [props: {
    readonly name?: string;
    readonly uri: string;
  }, options?: MakeOptions]);
}

Describes a message issued to or received from an LLM API.

Signature

declare class SamplingMessage extends {
  readonly content: TextContent | ImageContent | AudioContent;
  readonly role: "user" | "assistant";
} {
  constructor(_: never);
}

Describes capabilities advertised by an MCP server.

When to use

Use to describe which optional MCP features a server supports during initialization.

Details

Known capabilities are represented by this schema, but the capability set is open and servers may define additional capabilities.

Signature

declare class ServerCapabilities extends {
  readonly completions?: {};
  readonly experimental?: {
    [key: string]: {};
  };
  readonly extensions?: {
    [key: `${string}/${string}`]: Json;
  };
  readonly logging?: {};
  readonly prompts?: {
    readonly listChanged?: boolean;
  };
  readonly resources?: {
    readonly listChanged?: boolean;
    readonly subscribe?: boolean;
  };
  readonly tools?: {
    readonly listChanged?: boolean;
  };
} {
  constructor(_: never);
}

TextContent

Added in v4.0.0 Source

Represents text content provided to or from an LLM.

Signature

declare class TextContent extends {
  readonly annotations?: Annotations;
  readonly text: string;
  readonly type: "text";
} {
  constructor(_: never);
}

Schema for text resource contents represented as a string.

Signature

declare class TextResourceContents extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly mimeType?: string;
  readonly text: string;
  readonly uri: string;
} {
  constructor(_: never);
}

Tool

Added in v4.0.0 Source

Schema for the definition of a tool the client can call.

Signature

declare class Tool extends {
  readonly _meta?: {
    [key: string]: Json;
  };
  readonly annotations?: ToolAnnotations;
  readonly description?: string;
  readonly inputSchema: any;
  readonly name: string;
  readonly outputSchema?: any;
  readonly title?: string;
} {
  constructor(...args: [props: {
    readonly _meta?: {
      [key: string]: unknown;
    };
    readonly annotations?: {
      readonly destructiveHint?: boolean;
      readonly idempotentHint?: boolean;
      readonly openWorldHint?: boolean;
      readonly readOnlyHint?: boolean;
      readonly title?: string;
    };
    readonly description?: string;
    readonly inputSchema: any;
    readonly name: string;
    readonly outputSchema?: any;
    readonly title?: string;
  }, options?: MakeOptions]);
}

Schema for additional properties describing a tool to clients.

Details

NOTE: all properties in ToolAnnotations are hints. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like title).

Gotchas

Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.

Signature

declare class ToolAnnotations extends {
  readonly destructiveHint?: boolean;
  readonly idempotentHint?: boolean;
  readonly openWorldHint?: boolean;
  readonly readOnlyHint?: boolean;
  readonly title?: string;
} {
  constructor(_: never);
}

Services

EnabledWhen

Added in v4.0.0 Source

Annotation to conditionally enable or disable tools based on client information.

Signature

declare class EnabledWhen extends Shape<
  "effect/unstable/ai/McpSchema/EnabledWhen",
  Predicate<{
    readonly _meta?: {
      readonly progressToken?: string | number;
    };
    readonly capabilities: ClientCapabilities;
    readonly clientInfo: Implementation;
    readonly protocolVersion: string;
  }>,
  this
> {
  constructor(_: never);
}

Service available while handling an MCP client request.

Details

It exposes the current client id, the client's initialize payload, and a scoped RPC client for server-initiated requests back to that client.

Signature

declare class McpServerClient extends Shape<"effect/ai/McpSchema/McpServerClient", {
  readonly clientId: number;
  readonly getClient: Effect<{
    "elicitation/create": <AsQueue extends boolean = false, Discard = false>(input: {
      readonly message: string;
      readonly requestedSchema: any;
    }, options?: {
      readonly context?: Context<never>;
      readonly discard?: Discard;
      readonly headers?: Input;
    }) => Effect<Discard extends true ? void : ElicitAcceptResult | ElicitDeclineResult, RpcClientError | Discard extends true ? never : ParseError | McpErrorBase | InvalidRequest | MethodNotFound | InvalidParams | InternalError, never>;
    ping: <AsQueue extends boolean = false, Discard = false>(input: {
      readonly _meta?: {
        readonly progressToken?: ... | ... | ...;
      };
    } | undefined, options?: {
      readonly context?: Context<never>;
      readonly discard?: Discard;
      readonly headers?: Input;
    }) => Effect<Discard extends true ? void : {}, RpcClientError | Discard extends true ? never : ParseError | McpErrorBase | InvalidRequest | MethodNotFound | InvalidParams | InternalError, never>;
    "roots/list": <AsQueue extends boolean = false, Discard = false>(input: {
      readonly _meta?: {
        readonly progressToken?: ... | ... | ...;
      };
    } | undefined, options?: {
      readonly context?: Context<never>;
      readonly discard?: Discard;
      readonly headers?: Input;
    }) => Effect<Discard extends true ? void : ListRootsResult, RpcClientError | Discard extends true ? never : ParseError | McpErrorBase | InvalidRequest | MethodNotFound | InvalidParams | InternalError, never>;
    "sampling/createMessage": <AsQueue extends boolean = false, Discard = false>(input: {
      readonly includeContext?: "none" | "thisServer" | "allServers";
      readonly maxTokens: number;
      readonly messages: readonly Array<{
        readonly content: {
          readonly annotations?: ...;
          readonly text: ...;
          readonly type?: ...;
        } | {
          readonly annotations?: ...;
          readonly data: ...;
          readonly mimeType: ...;
          readonly type?: ...;
        } | {
          readonly annotations?: ...;
          readonly data: ...;
          readonly mimeType: ...;
          readonly type?: ...;
        };
        readonly role: "user" | "assistant";
      }>;
      readonly metadata?: {
        [key: string]: unknown;
      };
      readonly modelPreferences?: {
        readonly costPriority?: number;
        readonly hints?: readonly Array<...>;
        readonly intelligencePriority?: number;
        readonly speedPriority?: number;
      };
      readonly stopSequences?: readonly Array<string>;
      readonly systemPrompt?: string;
      readonly temperature?: number;
    }, options?: {
      readonly context?: Context<never>;
      readonly discard?: Discard;
      readonly headers?: Input;
    }) => Effect<Discard extends true ? void : CreateMessageResult, RpcClientError | Discard extends true ? never : ParseError | McpErrorBase | InvalidRequest | MethodNotFound | InvalidParams | InternalError, never>;
  }, never, Scope>;
  readonly initializePayload: {
    readonly _meta?: {
      readonly progressToken?: string | number;
    };
    readonly capabilities: ClientCapabilities;
    readonly clientInfo: Implementation;
    readonly protocolVersion: string;
  };
  readonly protocolVersion: "2025-06-18";
}, this> {
  constructor(_: never);
}