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.
Constants
INTERNAL_ERROR_CODE
Signature
declare const INTERNAL_ERROR_CODE: -32603;INVALID_PARAMS_ERROR_CODE
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;INVALID_REQUEST_ERROR_CODE
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;METHOD_NOT_FOUND_ERROR_CODE
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;PARSE_ERROR_CODE
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
InternalError
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;
}InvalidParams
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]);
}InvalidRequest
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]);
}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,
]
>;MethodNotFound
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
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
Logging
LoggingLevel
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
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;LoggingMessageNotification
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);
}Sent from the client to the server to enable or adjust logging.
Signature
declare class SetLevel extends ({}) {
constructor(_: never);
}Middleware
McpServerClientMiddleware
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
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
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
Type represented by the MCP progress token schema.
Signature
type ProgressToken = typeof ProgressToken.Type;Type represented by the JSON-RPC request identifier schema.
Signature
type RequestId = typeof RequestId.Type;Type represented by the MCP role schema.
Details
Valid roles are "user" and "assistant".
Signature
type Role = typeof Role.Type;Parameters
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>;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
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
ListToolsfor discovering available tools before calling oneCallToolResultfor the successful tool-call result shape
Signature
declare class CallTool extends ({}) {
constructor(_: never);
}CancelledNotification
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
Encoded failure response sent by a client for a server-initiated request.
Signature
type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>;ClientNotificationEncoded type
Encoded union of all client-to-server MCP notification messages.
Signature
type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>;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
Encoded union of all client-to-server MCP request messages.
Signature
type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>;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
RPC group combining all client-to-server MCP requests and notifications.
Signature
declare class ClientRpcs extends ({}) {
constructor(_: never);
}ClientSuccessEncoded type
Encoded success response sent by a client for a server-initiated request.
Signature
type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>;Sent from the client to the server to ask for completion options.
Signature
declare class Complete extends ({}) {
constructor(_: never);
}CreateMessage
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);
}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
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
Encoded MCP messages accepted from a client by the server protocol: client requests and client notifications.
Signature
type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded;FromServerEncoded type
Encoded MCP messages emitted by the server protocol to a client: server responses and server notifications.
Signature
type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded;Sent from the client to get a prompt provided by the server.
Signature
declare class GetPrompt extends ({}) {
constructor(_: never);
}Initialize
Sent from the client to the server when it first connects, asking it to begin initialization.
Signature
declare class Initialize extends ({}) {
constructor(_: never);
}InitializedNotification
Sent from the client to the server after initialization has finished.
Signature
declare class InitializedNotification extends ({}) {
constructor(_: never);
}ListPrompts
Sent from the client to request a list of prompts and prompt templates the server has.
Signature
declare class ListPrompts extends ({}) {
constructor(_: never);
}ListResources
Sent from the client to request a list of resources the server has.
Signature
declare class ListResources extends ({}) {
constructor(_: never);
}ListResourceTemplates
Sent from the client to request a list of resource templates the server has.
Signature
declare class ListResourceTemplates extends ({}) {
constructor(_: never);
}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);
}Sent from the client to request a list of tools the server has.
Signature
declare class ListTools extends ({}) {
constructor(_: never);
}NotificationEncoded type
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;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);
}ProgressNotification
Sent from either peer to report progress for a long-running request.
Signature
declare class ProgressNotification extends ({}) {
constructor(_: never);
}PromptListChangedNotification
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
Sent from the client to the server, to read a specific resource URI.
Signature
declare class ReadResource extends ({}) {
constructor(_: never);
}RequestEncoded type
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;ResourceListChangedNotification
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);
}ResourceUpdatedNotification
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);
}RootsListChangedNotification
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
Encoded failure response sent by the server for a client-initiated request.
Signature
type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>;ServerNotificationEncoded type
Encoded union of all server-to-client MCP notification messages.
Signature
type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>;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
Encoded union of all server-to-client MCP request messages.
Signature
type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>;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
Encoded server response to a client request, either success or failure.
Signature
type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded;ServerSuccessEncoded type
Encoded success response sent by the server for a client-initiated request.
Signature
type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>;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
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;ToolListChangedNotification
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
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
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
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);
}BlobResourceContents
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);
}CallToolResult
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]);
}ClientCapabilities
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]);
}CompleteResult
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
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,
]
>;CreateMessageResult
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]);
}Schema for opaque cursor tokens used in pagination.
Signature
declare const Cursor: typeof Schema.String;ElicitAcceptResult
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]);
}ElicitationDeclined
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]);
}ElicitDeclineResult
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
Schema for every client response to an elicitation request.
Signature
declare const ElicitResult: Union<readonly [typeof ElicitAcceptResult, typeof ElicitDeclineResult]>;EmbeddedResource
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);
}GetPromptResult
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
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);
}Implementation
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);
}InitializeResult
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);
}ListPromptsResult
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]);
}ListResourcesResult
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]);
}ListResourceTemplatesResult
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]);
}ListRootsResult
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]);
}ListToolsResult
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
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]);
}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);
}ModelPreferences
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]);
}NotificationMeta
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);
}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>>;optionalWithDefault
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>;PaginatedRequestMeta
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);
}PaginatedResultMeta
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);
}ProgressToken
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]>;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]);
}PromptArgument
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);
}PromptMessage
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);
}PromptReference
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);
}ReadResourceResult
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);
}Schema for JSON-RPC request identifiers, allowing string or number ids.
Signature
declare const RequestId: Schema.Union<[typeof Schema.String, typeof Schema.Finite]>;RequestMeta
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);
}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]);
}ResourceContents
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);
}ResourceLink
Represents a readable resource included in a prompt or tool call result.
Gotchas
Resource links returned by tools are not guaranteed to appear in the results of resources/list requests.
Signature
declare class ResourceLink 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 type: "resource_link";
readonly uri: string;
} {
constructor(_: never);
}ResourceReference
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);
}ResourceTemplate
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
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);
}Schema for MCP conversation roles, allowing user and assistant.
Signature
declare const Role: Schema.Literals<["user", "assistant"]>;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]);
}SamplingMessage
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);
}ServerCapabilities
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
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);
}TextResourceContents
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);
}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]);
}ToolAnnotations
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
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);
}McpServerClient
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);
}
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.