Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

McpSchema unstable

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 is the stable public compatibility and authoring surface. It is not an exact dated wire contract: MCP protocol adapters use frozen schemas under internal/mcpSchema for decoding and encoding. This module groups the current public message model for application authors and provides helpers for optional fields and parameter metadata. Transport and server behavior live in other modules.

164 exports Since v4.0.0 Source

Client

McpReverseClient

interface unstable
Since v4.0.0

Version-neutral operations that an MCP server may request from its client.

Signature

interface McpReverseClient {
readonly createMessage: (request: {
readonly includeContext?: "none" | "thisServer" | "allServers";
readonly maxTokens: number;
readonly messages: readonly Array<SamplingMessage>;
readonly metadata?: {
[key: string]: unknown;
};
readonly modelPreferences?: {
readonly costPriority?: number;
readonly hints?: readonly Array<ModelHint>;
readonly intelligencePriority?: number;
readonly speedPriority?: number;
};
readonly stopSequences?: readonly Array<string>;
readonly systemPrompt?: string;
readonly temperature?: number;
readonly toolChoice?: {
readonly mode?: "required" | "auto" | "none";
};
readonly tools?: readonly Array<{
readonly _meta?: {
[key: string]: Json;
};
readonly annotations?: ToolAnnotations;
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly inputSchema: ToolJson;
readonly name: string;
readonly outputSchema?: JsonObject;
readonly title?: string;
}>;
}) => Effect<CreateMessageResult, McpReverseOperationUnsupported | McpReverseOperationError>;
readonly elicit: (request: ElicitRequestFormParams | ElicitRequestURLParams) => Effect<ElicitAcceptResult | ElicitDeclineResult, McpReverseOperationUnsupported | McpReverseOperationError>;
readonly listRoots: (request?: RequestMeta) => Effect<ListRootsResult, McpReverseOperationUnsupported | McpReverseOperationError>;
}

Constants

Represents the MCP error code for HTTP headers that do not match the corresponding request values.

When to use

Use when building an MCP error response for missing, malformed, or mismatched request-routing headers.

Signature

declare const HEADER_MISMATCH_ERROR_CODE: -32020
Since v4.0.0

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
Since v4.0.0

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

Elicitation

Since v4.0.0

Schema for a boolean field in an MCP elicitation form.

Signature

declare class ElicitationBoolean extends {
readonly default?: boolean;
readonly description?: string;
readonly title?: string;
readonly type: "boolean";
} {
constructor(...args: [props?: {
readonly default?: boolean;
readonly description?: string;
readonly title?: string;
readonly type?: "boolean";
}, options?: MakeOptions]);
}

Notifies a client that a URL-mode elicitation completed.

Signature

declare class ElicitationCompleteNotification extends {} {
constructor(_: never);
}
Since v4.0.0

Schema for every enumeration field in an MCP elicitation form.

Signature

declare const ElicitationEnum: Union<readonly [typeof LegacyTitledEnum, Union<readonly [typeof UntitledSingleSelectEnum, typeof TitledSingleSelectEnum]>, Union<readonly [typeof UntitledMultiSelectEnum, typeof TitledMultiSelectEnum]>]>
Since v4.0.0

Schema for a numeric field in an MCP elicitation form.

Signature

declare class ElicitationNumber extends {
readonly default?: number;
readonly description?: string;
readonly maximum?: number;
readonly minimum?: number;
readonly title?: string;
readonly type: "number" | "integer";
} {
constructor(...args: [props: {
readonly default?: number;
readonly description?: string;
readonly maximum?: number;
readonly minimum?: number;
readonly title?: string;
readonly type: "number" | "integer";
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for a string field in an MCP elicitation form.

Signature

declare class ElicitationString extends {
readonly default?: string;
readonly description?: string;
readonly format?: "date" | "uri" | "email" | "date-time";
readonly maxLength?: number;
readonly minLength?: number;
readonly title?: string;
readonly type: "string";
} {
constructor(...args: [props?: {
readonly default?: string;
readonly description?: string;
readonly format?: "date" | "uri" | "email" | "date-time";
readonly maxLength?: number;
readonly minLength?: number;
readonly title?: string;
readonly type?: "string";
}, options?: MakeOptions]);
}

Schema for form-mode MCP elicitation requests.

Signature

declare class ElicitRequestFormParams extends {
readonly _meta?: {
[key: string]: Json;
readonly progressToken?: string | number;
};
readonly message: string;
readonly mode?: "form";
readonly requestedSchema: {
readonly $schema?: string;
readonly properties: {
[key: string]: ElicitationString | ElicitationNumber | ElicitationBoolean | UntitledSingleSelectEnum | TitledSingleSelectEnum | UntitledMultiSelectEnum | TitledMultiSelectEnum | LegacyTitledEnum;
};
readonly required?: readonly Array<string>;
readonly type: "object";
};
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
readonly progressToken?: string | number;
};
readonly message: string;
readonly mode?: "form";
readonly requestedSchema: {
readonly $schema?: string;
readonly properties: {
[key: string]: ElicitationString | ElicitationNumber | ElicitationBoolean | UntitledSingleSelectEnum | TitledSingleSelectEnum | UntitledMultiSelectEnum | TitledMultiSelectEnum | LegacyTitledEnum;
};
readonly required?: readonly Array<string>;
readonly type?: "object";
};
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for every MCP elicitation request mode.

Signature

declare const ElicitRequestParams: Union<readonly [typeof ElicitRequestFormParams, typeof ElicitRequestURLParams]>

Schema for URL-mode MCP elicitation requests.

Signature

declare class ElicitRequestURLParams extends {
readonly _meta?: {
[key: string]: Json;
readonly progressToken?: string | number;
};
readonly elicitationId: string;
readonly message: string;
readonly mode: "url";
readonly url: string;
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
readonly progressToken?: string | number;
};
readonly elicitationId: string;
readonly message: string;
readonly mode: "url";
readonly url: string;
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for the legacy titled single-select elicitation field.

Signature

declare class LegacyTitledEnum extends {
readonly default?: string;
readonly description?: string;
readonly enum: readonly Array<string>;
readonly enumNames?: readonly Array<string>;
readonly title?: string;
readonly type: "string";
} {
constructor(...args: [props: {
readonly default?: string;
readonly description?: string;
readonly enum: readonly Array<string>;
readonly enumNames?: readonly Array<string>;
readonly title?: string;
readonly type?: "string";
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for every multi-select field in an MCP elicitation form.

Signature

declare const MultiSelectEnum: Union<readonly [typeof UntitledMultiSelectEnum, typeof TitledMultiSelectEnum]>

Schema for primitive field definitions accepted by MCP elicitation forms.

Signature

declare const PrimitiveSchemaDefinition: Union<readonly [Union<readonly [typeof LegacyTitledEnum, Union<readonly [typeof UntitledSingleSelectEnum, typeof TitledSingleSelectEnum]>, Union<readonly [typeof UntitledMultiSelectEnum, typeof TitledMultiSelectEnum]>]>, typeof ElicitationString, typeof ElicitationNumber, typeof ElicitationBoolean]>
Since v4.0.0

Schema for every single-select field in an MCP elicitation form.

Signature

declare const SingleSelectEnum: Union<readonly [typeof UntitledSingleSelectEnum, typeof TitledSingleSelectEnum]>
Since v4.0.0

Schema for a titled multi-select field in an MCP elicitation form.

Signature

declare class TitledMultiSelectEnum extends {
readonly default?: readonly Array<string>;
readonly description?: string;
readonly items: {
readonly anyOf: readonly Array<{
readonly const: string;
readonly title: string;
}>;
};
readonly maxItems?: number;
readonly minItems?: number;
readonly title?: string;
readonly type: "array";
} {
constructor(...args: [props: {
readonly default?: readonly Array<string>;
readonly description?: string;
readonly items: {
readonly anyOf: readonly Array<{
readonly const: string;
readonly title: string;
}>;
};
readonly maxItems?: number;
readonly minItems?: number;
readonly title?: string;
readonly type?: "array";
}, options?: MakeOptions]);
}

Schema for a titled single-select field in an MCP elicitation form.

Signature

declare class TitledSingleSelectEnum extends {
readonly default?: string;
readonly description?: string;
readonly oneOf: readonly Array<{
readonly const: string;
readonly title: string;
}>;
readonly title?: string;
readonly type: "string";
} {
constructor(...args: [props: {
readonly default?: string;
readonly description?: string;
readonly oneOf: readonly Array<{
readonly const: string;
readonly title: string;
}>;
readonly title?: string;
readonly type?: "string";
}, options?: MakeOptions]);
}

Schema for an untitled multi-select field in an MCP elicitation form.

Signature

declare class UntitledMultiSelectEnum extends {
readonly default?: readonly Array<string>;
readonly description?: string;
readonly items: {
readonly enum: readonly Array<string>;
readonly type: "string";
};
readonly maxItems?: number;
readonly minItems?: number;
readonly title?: string;
readonly type: "array";
} {
constructor(...args: [props: {
readonly default?: readonly Array<string>;
readonly description?: string;
readonly items: {
readonly enum: readonly Array<string>;
readonly type?: "string";
};
readonly maxItems?: number;
readonly minItems?: number;
readonly title?: string;
readonly type?: "array";
}, options?: MakeOptions]);
}

Schema for an untitled single-select field in an MCP elicitation form.

Signature

declare class UntitledSingleSelectEnum extends {
readonly default?: string;
readonly description?: string;
readonly enum: readonly Array<string>;
readonly title?: string;
readonly type: "string";
} {
constructor(...args: [props: {
readonly default?: string;
readonly description?: string;
readonly enum: readonly Array<string>;
readonly title?: string;
readonly type?: "string";
}, options?: MakeOptions]);
}

Errors

Since v4.0.0

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;
}
Since v4.0.0

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]);
}
Since v4.0.0

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

unstable
Since v4.0.0

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]>

A reverse MCP operation failed while being sent or projected through a version adapter.

Signature

declare class McpReverseOperationError extends YieldableError<this> & {
readonly _tag: "McpReverseOperationError";
} & Readonly<{
readonly cause: unknown;
readonly operation: "sampling/createMessage" | "roots/list" | "elicitation/create";
}> {
constructor(args: {
readonly cause: unknown;
readonly operation: "sampling/createMessage" | "roots/list" | "elicitation/create";
});
}

Raised when the negotiated MCP revision or client capabilities do not support a server-initiated operation.

Signature

declare class McpReverseOperationUnsupported extends YieldableError<this> & {
readonly _tag: "McpReverseOperationUnsupported";
} & Readonly<{
readonly operation: "sampling/createMessage" | "roots/list" | "elicitation/create";
readonly protocolVersion: ProtocolVersion;
readonly reason: string;
}> {
constructor(args: {
readonly operation: "sampling/createMessage" | "roots/list" | "elicitation/create";
readonly protocolVersion: ProtocolVersion;
readonly reason: string;
});
}
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

Since v4.0.0

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 unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

ContentBlock

type unstable
Since v4.0.0

Type represented by the MCP content block schema.

Signature

type ContentBlock = typeof ContentBlock.Type

Cursor

type unstable
Since v4.0.0

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

ElicitationEnum

type unstable
Since v4.0.0

Type represented by the elicitation enumeration field schema.

Signature

type ElicitationEnum = typeof ElicitationEnum.Type

ElicitRequestParams

type unstable
Since v4.0.0

Type represented by the MCP elicitation request parameters schema.

Signature

type ElicitRequestParams = typeof ElicitRequestParams.Type

ElicitResult

type unstable
Since v4.0.0

Type represented by the MCP elicitation result schema.

Signature

type ElicitResult = typeof ElicitResult.Type
Since v4.0.0

Indicates that an MCP operation requires additional keyed input from the client.

When to use

Use when a handler cannot complete until the client supplies roots, sampling, or elicitation input in a later request.

Details

requestState is opaque to the client and is returned unchanged with the keyed input responses.

Signature

declare class InputRequired extends Readonly<{
readonly inputRequests?: Readonly<Record<string, McpInputRequest>>;
readonly requestState?: string;
}> & {
readonly _tag: "InputRequired";
} & Pipeable {
constructor(fields: {
readonly inputRequests: Readonly<Record<string, McpInputRequest>>;
readonly requestState?: string;
} | {
readonly inputRequests?: Readonly<Record<string, McpInputRequest>>;
readonly requestState: string;
});
}

McpError

type unstable
Since v4.0.0

Type represented by the MCP protocol error schema.

Signature

type McpError = typeof McpError.Type

McpInputRequest

type unstable
Since v4.0.0

Version-neutral request for additional MCP client input.

Signature

type McpInputRequest = {
readonly method: "roots/list";
readonly params?: Schema.JsonObject;
} | {
readonly method: "sampling/createMessage";
readonly params: Schema.JsonObject;
} | {
readonly method: "elicitation/create";
readonly params: Schema.JsonObject;
}

McpInputResponse

type unstable
Since v4.0.0

Version-neutral response supplied by an MCP client for a prior input request.

Signature

type McpInputResponse = Schema.JsonObject

MultiSelectEnum

type unstable
Since v4.0.0

Type represented by the multi-select elicitation field schema.

Signature

type MultiSelectEnum = typeof MultiSelectEnum.Type

optionalWithDefault

interface unstable
Since v4.0.0

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);
}
Since v4.0.0

Type represented by the primitive elicitation field schema.

Signature

type PrimitiveSchemaDefinition = typeof PrimitiveSchemaDefinition.Type

ProgressToken

type unstable
Since v4.0.0

Type represented by the MCP progress token schema.

Signature

type ProgressToken = typeof ProgressToken.Type

RequestId

type unstable
Since v4.0.0

Type represented by the JSON-RPC request identifier schema.

Signature

type RequestId = typeof RequestId.Type

Role

type unstable
Since v4.0.0

Type represented by the MCP role schema.

Details

Valid roles are "user" and "assistant".

Signature

type Role = typeof Role.Type
Since v4.0.0

Type represented by the MCP sampling message content block schema.

Signature

type SamplingMessageContentBlock = typeof SamplingMessageContentBlock.Type

SingleSelectEnum

type unstable
Since v4.0.0

Type represented by the single-select elicitation field schema.

Signature

type SingleSelectEnum = typeof SingleSelectEnum.Type

Parameters

param

unstable
Since v4.0.0

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 unstable
Since v4.0.0

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

unstable
Since v4.0.0

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);
}
Since v4.0.0

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);
}
Since v4.0.0

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

Signature

type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>
Since v4.0.0

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);
}
Since v4.0.0

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

Signature

type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>
Since v4.0.0

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

unstable
Since v4.0.0

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

Signature

declare class ClientRpcs extends {} {
constructor(_: never);
}
Since v4.0.0

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

Signature

type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>

Complete

unstable
Since v4.0.0

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

Signature

declare class Complete extends {} {
constructor(_: never);
}
Since v4.0.0

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

unstable
Since v4.0.0

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 unstable
Since v4.0.0

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 unstable
Since v4.0.0

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

Signature

type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded

FromServerEncoded

type unstable
Since v4.0.0

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

Signature

type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded

GetPrompt

unstable
Since v4.0.0

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

Signature

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

Initialize

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

Signature

declare class ListPrompts extends {} {
constructor(_: never);
}
Since v4.0.0

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

Signature

declare class ListResources extends {} {
constructor(_: never);
}
Since v4.0.0

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

Signature

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

ListRoots

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

Signature

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

NotificationEncoded

type unstable
Since v4.0.0

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

unstable
Since v4.0.0

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);
}
Since v4.0.0

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);
}
Since v4.0.0

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

Signature

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

RequestEncoded

type unstable
Since v4.0.0

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);
}
Since v4.0.0

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

Signature

type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>
Since v4.0.0

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);
}
Since v4.0.0

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

Signature

type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>
Since v4.0.0

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 unstable
Since v4.0.0

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

Signature

type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded
Since v4.0.0

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

Signature

type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>

Subscribe

unstable
Since v4.0.0

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 unstable
Since v4.0.0

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

unstable
Since v4.0.0

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);
}

Sampling

Schema for content blocks accepted in MCP sampling messages.

Signature

declare const SamplingMessageContentBlock: Union<readonly [typeof TextContent, typeof ImageContent, typeof AudioContent, typeof ToolUseContent, typeof ToolResultContent]>

ToolChoice

unstable
Since v4.0.0

Schema for controlling tool selection during MCP sampling.

Signature

declare class ToolChoice extends {
readonly mode?: "required" | "auto" | "none";
} {
constructor(...args: [props?: {
readonly mode?: "required" | "auto" | "none";
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for the result of a tool use supplied in a sampling message.

Signature

declare class ToolResultContent extends {
readonly _meta?: {
[key: string]: Json;
};
readonly content: readonly Array<TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink>;
readonly isError?: boolean;
readonly structuredContent?: Json;
readonly toolUseId: string;
readonly type: "tool_result";
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly content: readonly Array<{
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly text: string;
readonly type?: "text";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "image";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "audio";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
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 lastModified?: string;
readonly priority?: number;
};
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly mimeType?: string;
readonly name: string;
readonly size?: number;
readonly title?: string;
readonly type?: "resource_link";
readonly uri: string;
}>;
readonly isError?: boolean;
readonly structuredContent?: unknown;
readonly toolUseId: string;
readonly type?: "tool_result";
}, options?: MakeOptions]);
}
Since v4.0.0

Schema for a tool-use request produced during MCP sampling.

Signature

declare class ToolUseContent extends {
readonly _meta?: {
[key: string]: Json;
};
readonly id: string;
readonly input: {
[key: string]: unknown;
};
readonly name: string;
readonly type: "tool_use";
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly id: string;
readonly input: {
[key: string]: unknown;
};
readonly name: string;
readonly type?: "tool_use";
}, options?: MakeOptions]);
}

Schemas

Annotations

unstable
Since v4.0.0

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 lastModified?: string;
readonly priority?: number;
} {
constructor(_: never);
}
Since v4.0.0

Represents audio content provided to or from an LLM.

Signature

declare class AudioContent extends {
readonly _meta?: {
[key: string]: Json;
};
readonly annotations?: Annotations;
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type: "audio";
} {
constructor(_: never);
}
Since v4.0.0

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);
}
Since v4.0.0

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?: Json;
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly content: readonly Array<{
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly text: string;
readonly type?: "text";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "image";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "audio";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
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 lastModified?: string;
readonly priority?: number;
};
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly mimeType?: string;
readonly name: string;
readonly size?: number;
readonly title?: string;
readonly type?: "resource_link";
readonly uri: string;
}>;
readonly isError?: boolean;
readonly structuredContent?: unknown;
}, options?: MakeOptions]);
}
Since v4.0.0

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 form?: {};
readonly url?: {};
};
readonly experimental?: {
[key: string]: {};
};
readonly extensions?: {
[key: `${string}/${string}`]: Json;
};
readonly roots?: {
readonly listChanged?: boolean;
};
readonly sampling?: {
readonly context?: {};
readonly tools?: {};
};
} {
constructor(...args: [props?: {
readonly elicitation?: {
readonly form?: {};
readonly url?: {};
};
readonly experimental?: {
[key: string]: {};
};
readonly extensions?: {
[key: `${string}/${string}`]: unknown;
};
readonly roots?: {
readonly listChanged?: boolean;
};
readonly sampling?: {
readonly context?: {};
readonly tools?: {};
};
}, options?: MakeOptions]);
}
Since v4.0.0

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

Signature

declare class CompleteResult extends {
readonly _meta?: {
[key: string]: Json;
};
readonly completion: {
readonly hasMore?: boolean;
readonly total?: number;
readonly values: readonly Array<string>;
};
} {
constructor(_: never);
static readonly empty: CompleteResult;
}
Since v4.0.0

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]>
Since v4.0.0

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 _meta?: {
[key: string]: Json;
};
readonly content: TextContent | ImageContent | AudioContent | ToolUseContent | ToolResultContent | readonly Array<TextContent | ImageContent | AudioContent | ToolUseContent | ToolResultContent>;
readonly model: string;
readonly role: "user" | "assistant";
readonly stopReason?: string;
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly content: {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly text: string;
readonly type?: "text";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "image";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<"user" | "assistant">;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "audio";
} | ToolUseContent | ToolResultContent | readonly Array<{
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly text: string;
readonly type?: "text";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "image";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "audio";
} | ToolUseContent | ToolResultContent>;
readonly model: string;
readonly role: "user" | "assistant";
readonly stopReason?: string;
}, options?: MakeOptions]);
}

Cursor

unstable
Since v4.0.0

Schema for opaque cursor tokens used in pagination.

Signature

declare const Cursor: typeof Schema.String
Since v4.0.0

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?: {
[key: string]: string | number | boolean | readonly Array<string>;
};
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly action: "accept";
readonly content?: {
[key: string]: string | number | boolean | readonly Array<string>;
};
}, options?: MakeOptions]);
}
Since v4.0.0

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: ElicitRequestFormParams | ElicitRequestURLParams;
} & YieldableError<this> {
constructor(...args: [props: {
readonly _tag?: "ElicitationDeclined";
readonly cause?: unknown;
readonly request: ElicitRequestFormParams | ElicitRequestURLParams;
}, options?: MakeOptions]);
}
Since v4.0.0

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]);
}
Since v4.0.0

Schema for every client response to an elicitation request.

Signature

declare const ElicitResult: Union<readonly [typeof ElicitAcceptResult, typeof ElicitDeclineResult]>
Since v4.0.0

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 _meta?: {
[key: string]: Json;
};
readonly annotations?: Annotations;
readonly resource: TextResourceContents | BlobResourceContents;
readonly type: "resource";
} {
constructor(_: never);
}
Since v4.0.0

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 _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly text: string;
readonly type?: "text";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "image";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
readonly priority?: number;
};
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type?: "audio";
} | {
readonly _meta?: {
[key: string]: unknown;
};
readonly annotations?: {
readonly audience?: readonly Array<... | ...>;
readonly lastModified?: string;
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 lastModified?: string;
readonly priority?: number;
};
readonly description?: string;
readonly icons?: readonly Array<Icon>;
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]);
}

Icon

unstable
Since v4.0.0

Schema for an icon that an MCP client can display.

Signature

declare class Icon extends {
readonly mimeType?: string;
readonly sizes?: readonly Array<string>;
readonly src: string;
readonly theme?: "light" | "dark";
} {
constructor(...args: [props: {
readonly mimeType?: string;
readonly sizes?: readonly Array<string>;
readonly src: string;
readonly theme?: "light" | "dark";
}, options?: MakeOptions]);
}
Since v4.0.0

Represents image content provided to or from an LLM.

Signature

declare class ImageContent extends {
readonly _meta?: {
[key: string]: Json;
};
readonly annotations?: Annotations;
readonly data: Uint8Array<ArrayBufferLike>;
readonly mimeType: string;
readonly type: "image";
} {
constructor(_: never);
}
Since v4.0.0

Describes the name and version of an MCP implementation.

Signature

declare class Implementation extends {
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly name: string;
readonly title?: string;
readonly version: string;
readonly websiteUrl?: string;
} {
constructor(_: never);
}
Since v4.0.0

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);
}
Since v4.0.0

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]);
}
Since v4.0.0

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]);
}
Since v4.0.0

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]);
}
Since v4.0.0

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]);
}
Since v4.0.0

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

unstable
Since v4.0.0

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);
}
Since v4.0.0

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]);
}
Since v4.0.0

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

unstable
Since v4.0.0

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<toType<optional<S>>, optionalKey<S>>
Since v4.0.0

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>
Since v4.0.0

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?: {
[key: string]: Json;
readonly progressToken?: string | number;
};
readonly cursor?: string;
} {
constructor(_: never);
}
Since v4.0.0

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);
}
Since v4.0.0

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

unstable
Since v4.0.0

Represents a prompt or prompt template that the server offers.

Signature

declare class Prompt extends {
readonly _meta?: {
[key: string]: Json;
};
readonly arguments?: readonly Array<PromptArgument>;
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly name: string;
readonly title?: string;
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly arguments?: readonly Array<{
readonly description?: string;
readonly name: string;
readonly required?: boolean;
readonly title?: string;
}>;
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly name: string;
readonly title?: string;
}, options?: MakeOptions]);
}
Since v4.0.0

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);
}
Since v4.0.0

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);
}
Since v4.0.0

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);
}
Since v4.0.0

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

unstable
Since v4.0.0

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

Signature

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

RequestMeta

unstable
Since v4.0.0

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?: {
[key: string]: Json;
readonly progressToken?: string | number;
};
} {
constructor(_: never);
}

Resource

unstable
Since v4.0.0

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 icons?: readonly Array<Icon>;
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 lastModified?: string;
readonly priority?: number;
};
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly mimeType?: string;
readonly name: string;
readonly size?: number;
readonly title?: string;
readonly uri: string;
}, options?: MakeOptions]);
}
Since v4.0.0

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);
}
Since v4.0.0

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);
}
Since v4.0.0

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 icons?: readonly Array<Icon>;
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 lastModified?: string;
readonly priority?: number;
};
readonly description?: string;
readonly icons?: readonly Array<Icon>;
readonly mimeType?: string;
readonly name: string;
readonly title?: string;
readonly uriTemplate: string;
}, options?: MakeOptions]);
}

ResultMeta

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Schema for MCP conversation roles, allowing user and assistant.

Signature

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

Root

unstable
Since v4.0.0

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

Signature

declare class Root extends {
readonly _meta?: {
[key: string]: Json;
};
readonly name?: string;
readonly uri: string;
} {
constructor(...args: [props: {
readonly _meta?: {
[key: string]: unknown;
};
readonly name?: string;
readonly uri: string;
}, options?: MakeOptions]);
}
Since v4.0.0

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

Signature

declare class SamplingMessage extends {
readonly _meta?: {
[key: string]: Json;
};
readonly content: TextContent | ImageContent | AudioContent | ToolUseContent | ToolResultContent | readonly Array<TextContent | ImageContent | AudioContent | ToolUseContent | ToolResultContent>;
readonly role: "user" | "assistant";
} {
constructor(_: never);
}
Since v4.0.0

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

unstable
Since v4.0.0

Represents text content provided to or from an LLM.

Signature

declare class TextContent extends {
readonly _meta?: {
[key: string]: Json;
};
readonly annotations?: Annotations;
readonly text: string;
readonly type: "text";
} {
constructor(_: never);
}
Since v4.0.0

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

unstable
Since v4.0.0

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 icons?: readonly Array<Icon>;
readonly inputSchema: ToolJson;
readonly name: string;
readonly outputSchema?: JsonObject;
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 icons?: readonly Array<Icon>;
readonly inputSchema: unknown;
readonly name: string;
readonly outputSchema?: unknown;
readonly title?: string;
}, options?: MakeOptions]);
}
Since v4.0.0

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

unstable
Since v4.0.0

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

Signature

declare class EnabledWhen extends Shape<"effect/ai/McpSchema/EnabledWhen", Predicate<{
readonly capabilities: ClientCapabilities;
readonly clientInfo?: Implementation;
readonly protocolVersion: string;
}>, this> {
constructor(_: never);
}
Since v4.0.0

Protocol-neutral context available while handling an MCP request.

Details

Unlike McpServerClient, this service does not imply an initialized session or support for server-initiated requests.

Signature

declare class McpRequestContext extends Shape<"effect/ai/McpSchema/McpRequestContext", {
readonly clientCapabilities: ClientCapabilities;
readonly clientId: number;
readonly clientInfo?: Implementation;
readonly inputResponses?: Readonly<Record<string, JsonObject>>;
readonly protocolVersion: string;
readonly requestMetadata?: JsonObject | {
[key: string]: Json;
readonly progressToken?: string | number;
};
readonly requestState?: string;
}, this> {
constructor(_: never);
}
Since v4.0.0

Service available while handling an MCP client request.

Details

It exposes the current client id, normalized initialization data, and a scoped version-neutral facade for server-initiated requests.

Signature

declare class McpServerClient extends Shape<"effect/ai/McpSchema/McpServerClient", {
readonly clientCapabilities: ClientCapabilities;
readonly clientId: number;
readonly clientInfo: Implementation;
readonly getClient: Effect<McpReverseClient, never, Scope>;
readonly initializePayload: {
readonly _meta?: {
[key: string]: Json;
readonly progressToken?: string | number;
};
readonly capabilities: ClientCapabilities;
readonly clientInfo: Implementation;
readonly protocolVersion: string;
};
readonly protocolVersion: StatefulProtocolVersion;
readonly requestMetadata?: JsonObject;
}, this> {
constructor(_: never);
}

Tools

ToolJson

unstable
Since v4.0.0

Schema for ToolJson.

Signature

declare const ToolJson: Codec<ToolJson, ToolJson, never, never>

ToolJson

type unstable
Since v4.0.0

Object-root JSON Schema used by MCP tool inputs.

Details

Property definitions and additional root keywords are constrained to JSON values. The open root supports generated keywords such as $defs.

Signature

type ToolJson = Schema.JsonObject & {
readonly properties?: Readonly<Record<string, Schema.JsonObject>>;
readonly required?: ReadonlyArray<string>;
readonly type: "object";
}
Since v4.0.0

Schema for ToolOutputJson.

Signature

declare const ToolOutputJson: Codec<JsonObject, JsonObject, never, never>

ToolOutputJson

type unstable
Since v4.0.0

JSON Schema used by MCP tool outputs.

Details

Unlike tool inputs, tool outputs may use any JSON Schema root type.

Signature

type ToolOutputJson = Schema.JsonObject