McpSchema.ts

McpSchema.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• annotations
  • EnabledWhen (class)
• autocomplete
  • Complete (class)
  • CompleteResult (class)
  • PromptReference (class)
  • ResourceReference (class)
• cancellation
  • CancelledNotification (class)
• client
  • McpServerClient (class)
• constants
  • INTERNAL_ERROR_CODE
  • INVALID_PARAMS_ERROR_CODE
  • INVALID_REQUEST_ERROR_CODE
  • METHOD_NOT_FOUND_ERROR_CODE
  • PARSE_ERROR_CODE
• elicitation
  • Elicit (class)
  • ElicitAcceptResult (class)
  • ElicitDeclineResult (class)
  • ElicitResult
  • ElicitationDeclined (class)
• errors
  • InternalError (class)
  • InvalidParams (class)
  • InvalidRequest (class)
  • McpError
  • MethodNotFound (class)
  • ParseError (class)
• initialization
  • Initialize (class)
  • InitializeResult (class)
  • InitializedNotification (class)
• logging
  • LoggingLevel
  • LoggingLevel (type alias)
  • LoggingMessageNotification (class)
  • SetLevel (class)
• middleware
  • McpServerClientMiddleware (class)
• models
  • Cursor (type alias)
  • ProgressToken (type alias)
  • RequestId (type alias)
  • Role (type alias)
  • optionalWithDefault (interface)
• parameters
  • Param (interface)
  • isParam
  • param
• ping
  • Ping (class)
• progress
  • ProgressNotification (class)
• protocols
  • ClientFailureEncoded (type alias)
  • ClientNotificationEncoded (type alias)
  • ClientNotificationRpcs (class)
  • ClientRequestEncoded (type alias)
  • ClientRequestRpcs (class)
  • ClientRpcs (class)
  • ClientSuccessEncoded (type alias)
  • FailureEncoded (type alias)
  • FromClientEncoded (type alias)
  • FromServerEncoded (type alias)
  • GetPrompt (class)
  • ListPrompts (class)
  • NotificationEncoded (type alias)
  • PromptListChangedNotification (class)
  • RequestEncoded (type alias)
  • ServerFailureEncoded (type alias)
  • ServerNotificationEncoded (type alias)
  • ServerNotificationRpcs (class)
  • ServerRequestEncoded (type alias)
  • ServerRequestRpcs (class)
  • ServerResultEncoded (type alias)
  • ServerSuccessEncoded (type alias)
  • SuccessEncoded (type alias)
• resources
  • BlobResourceContents (class)
  • ListResourceTemplates (class)
  • ListResourceTemplatesResult (class)
  • ListResources (class)
  • ListResourcesResult (class)
  • ReadResource (class)
  • ReadResourceResult (class)
  • Resource (class)
  • ResourceContents (class)
  • ResourceListChangedNotification (class)
  • ResourceTemplate (class)
  • ResourceUpdatedNotification (class)
  • Subscribe (class)
  • TextResourceContents (class)
  • Unsubscribe (class)
• roots
  • ListRoots (class)
  • ListRootsResult (class)
  • Root (class)
  • RootsListChangedNotification (class)
• sampling
  • CreateMessage (class)
  • CreateMessageResult (class)
  • ModelHint (class)
  • ModelPreferences (class)
  • SamplingMessage (class)
• schemas
  • Annotations (class)
  • AudioContent (class)
  • ClientCapabilities (class)
  • ContentBlock
  • Cursor
  • EmbeddedResource (class)
  • GetPromptResult (class)
  • ImageContent (class)
  • Implementation (class)
  • ListPromptsResult (class)
  • McpErrorBase (class)
  • NotificationMeta (class)
  • PaginatedRequestMeta (class)
  • PaginatedResultMeta (class)
  • ProgressToken
  • Prompt (class)
  • PromptArgument (class)
  • PromptMessage (class)
  • RequestId
  • RequestMeta (class)
  • ResourceLink (class)
  • ResultMeta (class)
  • Role
  • ServerCapabilities (class)
  • TextContent (class)
  • optional
  • optionalWithDefault
• tools
  • CallTool (class)
  • CallToolResult (class)
  • ListTools (class)
  • ListToolsResult (class)
  • Tool (class)
  • ToolAnnotations (class)
  • ToolListChangedNotification (class)

---

annotations

EnabledWhen (class)

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

Signature

declare class EnabledWhen

Source

Since v4.0.0

autocomplete

Complete (class)

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

Signature

declare class Complete

Source

Since v4.0.0

CompleteResult (class)

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

Signature

declare class CompleteResult

Source

Since v4.0.0

PromptReference (class)

Schema for a prompt reference used in autocomplete requests.

Signature

declare class PromptReference

Source

Since v4.0.0

ResourceReference (class)

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

Signature

declare class ResourceReference

Source

Since v4.0.0

cancellation

CancelledNotification (class)

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

Source

Since v4.0.0

client

McpServerClient (class)

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

Source

Since v4.0.0

constants

INTERNAL_ERROR_CODE

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

Source

Since v4.0.0

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

Source

Since v4.0.0

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

Source

Since v4.0.0

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

Source

Since v4.0.0

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

Source

Since v4.0.0

elicitation

Elicit (class)

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

Source

Since v4.0.0

ElicitAcceptResult (class)

Schema for an accepted client response to an elicitation request.

Signature

declare class ElicitAcceptResult

Source

Since v4.0.0

ElicitDeclineResult (class)

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

Signature

declare class ElicitDeclineResult

Source

Since v4.0.0

ElicitResult

Schema for every client response to an elicitation request.

Signature

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

Source

Since v4.0.0

ElicitationDeclined (class)

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

Source

Since v4.0.0

errors

InternalError (class)

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

Source

Since v4.0.0

InvalidParams (class)

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

Source

Since v4.0.0

InvalidRequest (class)

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

Source

Since v4.0.0

McpError

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

Signature

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

Source

Since v4.0.0

MethodNotFound (class)

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

Source

Since v4.0.0

ParseError (class)

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

Source

Since v4.0.0

initialization

Initialize (class)

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

Signature

declare class Initialize

Source

Since v4.0.0

InitializeResult (class)

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

Signature

declare class InitializeResult

Source

Since v4.0.0

InitializedNotification (class)

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

Signature

declare class InitializedNotification

Source

Since v4.0.0

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

Source

Since v4.0.0

LoggingLevel (type alias)

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

Source

Since v4.0.0

LoggingMessageNotification (class)

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

Source

Since v4.0.0

SetLevel (class)

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

Signature

declare class SetLevel

Source

Since v4.0.0

middleware

McpServerClientMiddleware (class)

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

Signature

declare class McpServerClientMiddleware

Source

Since v4.0.0

models

Cursor (type alias)

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

Source

Since v4.0.0

ProgressToken (type alias)

Type represented by the MCP progress token schema.

Signature

type ProgressToken = typeof ProgressToken.Type

Source

Since v4.0.0

RequestId (type alias)

Type represented by the JSON-RPC request identifier schema.

Signature

type RequestId = typeof RequestId.Type

Source

Since v4.0.0

Role (type alias)

Type represented by the MCP role schema.

Details

Valid roles are "user" and "assistant".

Signature

type Role = typeof Role.Type

Source

Since v4.0.0

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

export interface optionalWithDefault<
  S extends Schema.Constraint & Schema.WithoutConstructorDefault
> extends Schema.withConstructorDefault<Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>> {}

Source

Since v4.0.0

parameters

Param (interface)

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

export interface Param<Name extends string, S extends Schema.Constraint> extends Schema.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"]
> {
  readonly Type: S["Type"]
  readonly Encoded: S["Encoded"]
  readonly DecodingServices: S["DecodingServices"]
  readonly EncodingServices: S["EncodingServices"]
  readonly Rebuild: Param<Name, S>
  readonly "~type.make.in": S["~type.make.in"]
  readonly "~type.make": S["~type.make"]
  readonly Iso: S["Iso"]
  readonly [ParamSchemaTypeId]: typeof ParamSchemaTypeId
  readonly name: Name
  readonly schema: S
}

Source

Since v4.0.0

isParam

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

Signature

declare const isParam: (schema: Schema.Constraint) => schema is Param<string, Schema.Top>

Source

Since v4.0.0

param

Creates a parameter for a resource URI template.

Signature

declare const param: <const Name extends string, S extends Schema.Constraint>(name: Name, schema: S) => Param<Name, S>

Source

Since v4.0.0

ping

Ping (class)

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

Source

Since v4.0.0

progress

ProgressNotification (class)

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

Signature

declare class ProgressNotification

Source

Since v4.0.0

protocols

ClientFailureEncoded (type alias)

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

Signature

type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>

Source

Since v4.0.0

ClientNotificationEncoded (type alias)

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

Signature

type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>

Source

Since v4.0.0

ClientNotificationRpcs (class)

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

Source

Since v4.0.0

ClientRequestEncoded (type alias)

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

Signature

type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>

Source

Since v4.0.0

ClientRequestRpcs (class)

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

Source

Since v4.0.0

ClientRpcs (class)

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

Signature

declare class ClientRpcs

Source

Since v4.0.0

ClientSuccessEncoded (type alias)

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

Signature

type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>

Source

Since v4.0.0

FailureEncoded (type alias)

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

Signature

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

Source

Since v4.0.0

FromClientEncoded (type alias)

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

Signature

type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded

Source

Since v4.0.0

FromServerEncoded (type alias)

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

Signature

type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded

Source

Since v4.0.0

GetPrompt (class)

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

Signature

declare class GetPrompt

Source

Since v4.0.0

ListPrompts (class)

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

Signature

declare class ListPrompts

Source

Since v4.0.0

NotificationEncoded (type alias)

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

Signature

type NotificationEncoded<Group> =
  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

Source

Since v4.0.0

PromptListChangedNotification (class)

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

Source

Since v4.0.0

RequestEncoded (type alias)

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

Signature

type RequestEncoded<Group> =
  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

Source

Since v4.0.0

ServerFailureEncoded (type alias)

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

Signature

type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>

Source

Since v4.0.0

ServerNotificationEncoded (type alias)

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

Signature

type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>

Source

Since v4.0.0

ServerNotificationRpcs (class)

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

Source

Since v4.0.0

ServerRequestEncoded (type alias)

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

Signature

type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>

Source

Since v4.0.0

ServerRequestRpcs (class)

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

Signature

declare class ServerRequestRpcs

Source

Since v4.0.0

ServerResultEncoded (type alias)

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

Signature

type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded

Source

Since v4.0.0

ServerSuccessEncoded (type alias)

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

Signature

type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>

Source

Since v4.0.0

SuccessEncoded (type alias)

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

Signature

type SuccessEncoded<Group> =
  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

Source

Since v4.0.0

resources

BlobResourceContents (class)

Schema for binary resource contents represented as a Uint8Array.

Signature

declare class BlobResourceContents

Source

Since v4.0.0

ListResourceTemplates (class)

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

Signature

declare class ListResourceTemplates

Source

Since v4.0.0

ListResourceTemplatesResult (class)

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

Signature

declare class ListResourceTemplatesResult

Source

Since v4.0.0

ListResources (class)

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

Signature

declare class ListResources

Source

Since v4.0.0

ListResourcesResult (class)

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

Signature

declare class ListResourcesResult

Source

Since v4.0.0

ReadResource (class)

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

Signature

declare class ReadResource

Source

Since v4.0.0

ReadResourceResult (class)

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

Signature

declare class ReadResourceResult

Source

Since v4.0.0

Resource (class)

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

Signature

declare class Resource

Source

Since v4.0.0

ResourceContents (class)

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

Signature

declare class ResourceContents

Source

Since v4.0.0

ResourceListChangedNotification (class)

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

Source

Since v4.0.0

ResourceTemplate (class)

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

Signature

declare class ResourceTemplate

Source

Since v4.0.0

ResourceUpdatedNotification (class)

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

Source

Since v4.0.0

Subscribe (class)

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

Signature

declare class Subscribe

Source

Since v4.0.0

TextResourceContents (class)

Schema for text resource contents represented as a string.

Signature

declare class TextResourceContents

Source

Since v4.0.0

Unsubscribe (class)

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

Source

Since v4.0.0

roots

ListRoots (class)

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

Source

Since v4.0.0

ListRootsResult (class)

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

Source

Since v4.0.0

Root (class)

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

Signature

declare class Root

Source

Since v4.0.0

RootsListChangedNotification (class)

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

Source

Since v4.0.0

sampling

CreateMessage (class)

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

Source

Since v4.0.0

CreateMessageResult (class)

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

Source

Since v4.0.0

ModelHint (class)

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

Source

Since v4.0.0

ModelPreferences (class)

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

Source

Since v4.0.0

SamplingMessage (class)

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

Signature

declare class SamplingMessage

Source

Since v4.0.0

schemas

Annotations (class)

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

Source

Since v4.0.0

AudioContent (class)

Represents audio content provided to or from an LLM.

Signature

declare class AudioContent

Source

Since v4.0.0

ClientCapabilities (class)

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

Source

Since v4.0.0

ContentBlock

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

Signature

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

Source

Since v4.0.0

Cursor

Schema for opaque cursor tokens used in pagination.

Signature

declare const Cursor: Schema.String

Source

Since v4.0.0

EmbeddedResource (class)

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

Source

Since v4.0.0

GetPromptResult (class)

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

Signature

declare class GetPromptResult

Source

Since v4.0.0

ImageContent (class)

Represents image content provided to or from an LLM.

Signature

declare class ImageContent

Source

Since v4.0.0

Implementation (class)

Describes the name and version of an MCP implementation.

Signature

declare class Implementation

Source

Since v4.0.0

ListPromptsResult (class)

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

Signature

declare class ListPromptsResult

Source

Since v4.0.0

McpErrorBase (class)

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

Source

Since v4.0.0

NotificationMeta (class)

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

Source

Since v4.0.0

PaginatedRequestMeta (class)

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

Source

Since v4.0.0

PaginatedResultMeta (class)

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

Source

Since v4.0.0

ProgressToken

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

Signature

declare const ProgressToken: Schema.Union<[Schema.String, Schema.Number]>

Source

Since v4.0.0

Prompt (class)

Represents a prompt or prompt template that the server offers.

Signature

declare class Prompt

Source

Since v4.0.0

PromptArgument (class)

Describes an argument that a prompt can accept.

Signature

declare class PromptArgument

Source

Since v4.0.0

PromptMessage (class)

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

Source

Since v4.0.0

RequestId

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

Signature

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

Source

Since v4.0.0

RequestMeta (class)

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

Source

Since v4.0.0

ResourceLink (class)

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

Source

Since v4.0.0

ResultMeta (class)

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

Source

Since v4.0.0

Role

Schema for MCP conversation roles, allowing user and assistant.

Signature

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

Source

Since v4.0.0

ServerCapabilities (class)

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

Source

Since v4.0.0

TextContent (class)

Represents text content provided to or from an LLM.

Signature

declare class TextContent

Source

Since v4.0.0

optional

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 const optional: <S extends Schema.Constraint>(
  schema: S
) => Schema.decodeTo<Schema.optional<S>, Schema.optionalKey<S>>

Source

Since v4.0.0

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 Schema.Constraint & Schema.WithoutConstructorDefault>(
  schema: S,
  defaultValue: () => Schema.optionalKey<S>["Type"]
) => optionalWithDefault<S>

Source

Since v4.0.0

tools

CallTool (class)

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

Source

Since v4.0.0

CallToolResult (class)

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

Source

Since v4.0.0

ListTools (class)

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

Signature

declare class ListTools

Source

Since v4.0.0

ListToolsResult (class)

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

Signature

declare class ListToolsResult

Source

Since v4.0.0

Tool (class)

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

Signature

declare class Tool

Source

Since v4.0.0

ToolAnnotations (class)

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

Source

Since v4.0.0

ToolListChangedNotification (class)

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

Source

Since v4.0.0