The Model Context Protocol's messages, errors and request services
(Effect's McpSchema).
MCP is a JSON-RPC protocol, so its values are TypedDict s in the wire
form, with MCP's camelCase keys (inputSchema, structuredContent);
each has a schema named in capitals (TOOL for Tool) that validates
it. Binary data (images, audio, blobs) stays base64 text, as on the wire.
Method describes one request or notification: its name, the schema of
its params and of its result (CREATE_MESSAGE.payload_schema). The MCP
errors (InvalidParams, InternalError, ...) carry their JSON-RPC
code. McpRequestContext is the request a handler serves and
McpServerClient the session it belongs to (for requests to the client,
such as mcp_server.elicit).
Values#
| Attribute | Type | Description |
|---|---|---|
PARSE_ERROR_CODE | Literal[-32700] = -32700 | |
INVALID_REQUEST_ERROR_CODE | Literal[-32600] = -32600 | |
METHOD_NOT_FOUND_ERROR_CODE | Literal[-32601] = -32601 | |
INVALID_PARAMS_ERROR_CODE | Literal[-32602] = -32602 | |
INTERNAL_ERROR_CODE | Literal[-32603] = -32603 | |
HEADER_MISMATCH_ERROR_CODE | Literal[-32020] = -32020 | |
MISSING_REQUIRED_CLIENT_CAPABILITY_ERROR_CODE | Literal[-32021] = -32021 | |
UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE | Literal[-32022] = -32022 | |
RESOURCE_NOT_FOUND_ERROR_CODE | Literal[-32002] = -32002 | What revisions before 2026-07-28 answer an unknown resource with. |
REQUEST_ID | UnionSchema[str | float, str | float, Never, Never] | |
JSON_OBJECT | RecordSchema[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None, str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None, Never, Never] | |
JSON_RPC_REQUEST | StructSchema[JsonRpcRequest, Never, Never] | |
JSON_RPC_NOTIFICATION | StructSchema[JsonRpcNotification, Never, Never] | |
JSON_RPC_ERROR_OBJECT | StructSchema[JsonRpcErrorObject, Never, Never] | |
JSON_RPC_SUCCESS | StructSchema[JsonRpcSuccess, Never, Never] | |
JSON_RPC_ERROR | StructSchema[JsonRpcError, Never, Never] | |
JSON_RPC_RESPONSE | UnionSchema[JsonRpcSuccess | JsonRpcError, Mapping[str, object], Never, Never] | |
JSON_RPC_MESSAGE | UnionSchema[JsonRpcNotification | JsonRpcSuccess | JsonRpcError, Mapping[str, object], Never, Never] | |
REQUEST_META_OBJECT | StructWithRestSchema[_ProgressMeta, Never, Never] | |
REQUEST_META | StructSchema[RequestMeta, Never, Never] | |
ICON | StructSchema[Icon, Never, Never] | |
IMPLEMENTATION | StructSchema[Implementation, Never, Never] | |
CLIENT_CAPABILITIES | StructSchema[ClientCapabilities, Never, Never] | |
SERVER_CAPABILITIES | StructSchema[ServerCapabilities, Never, Never] | |
INITIALIZE_PARAMS | StructSchema[InitializeParams, Never, Never] | |
INITIALIZE_RESULT | StructSchema[InitializeResult, Never, Never] | |
ANNOTATIONS | StructSchema[Annotations, Never, Never] | |
TEXT_CONTENT | StructSchema[TextContent, Never, Never] | |
IMAGE_CONTENT | StructSchema[ImageContent, Never, Never] | |
AUDIO_CONTENT | StructSchema[AudioContent, Never, Never] | |
RESOURCE_LINK | StructSchema[ResourceLink, Never, Never] | |
TEXT_RESOURCE_CONTENTS | StructSchema[TextResourceContents, Never, Never] | |
BLOB_RESOURCE_CONTENTS | StructSchema[BlobResourceContents, Never, Never] | |
RESOURCE_CONTENTS | UnionSchema[TextResourceContents | BlobResourceContents, Mapping[str, object], Never, Never] | |
EMBEDDED_RESOURCE | StructSchema[EmbeddedResource, Never, Never] | |
CONTENT_BLOCK | UnionSchema[TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource, Mapping[str, object], Never, Never] | |
TOOL_ANNOTATIONS | StructSchema[ToolAnnotations, Never, Never] | |
TOOL_JSON | StructWithRestSchema[_ToolJsonFields, Never, Never] | A tool's input schema: a JSON Schema object whose |
TOOL | StructSchema[Tool, Never, Never] | |
CALL_TOOL_RESULT | StructSchema[CallToolResult, Never, Never] | |
CALL_TOOL_PARAMS | StructSchema[CallToolParams, Never, Never] | |
RESOURCE | StructSchema[Resource, Never, Never] | |
RESOURCE_TEMPLATE | StructSchema[ResourceTemplate, Never, Never] | |
READ_RESOURCE_RESULT | StructSchema[ReadResourceResult, Never, Never] | |
PROMPT_ARGUMENT | StructSchema[PromptArgument, Never, Never] | |
PROMPT | StructSchema[Prompt, Never, Never] | |
PROMPT_MESSAGE | StructSchema[PromptMessage, Never, Never] | |
GET_PROMPT_RESULT | StructSchema[GetPromptResult, Never, Never] | |
COMPLETE_PARAMS | StructSchema[CompleteParams, Never, Never] | |
COMPLETE_RESULT | StructSchema[CompleteResult, Never, Never] | |
LOGGING_LEVEL | LiteralsSchema[Literal['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency']] | |
LOGGING_LEVELS | tuple[LoggingLevel, ...] = ('debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency') | The levels from least to most severe. |
SAMPLING_MESSAGE | StructSchema[SamplingMessage, Never, Never] | |
CREATE_MESSAGE_PARAMS | StructSchema[CreateMessageParams, Never, Never] | |
CREATE_MESSAGE_RESULT | StructSchema[CreateMessageResult, Never, Never] | |
ROOT | StructSchema[Root, Never, Never] | |
LIST_ROOTS_RESULT | StructSchema[ListRootsResult, Never, Never] | |
PRIMITIVE_SCHEMA_DEFINITION | UnionSchema[UntitledSingleSelectEnum | TitledSingleSelectEnum | UntitledMultiSelectEnum | TitledMultiSelectEnum | ElicitationString | ElicitationNumber | ElicitationBoolean, Mapping[str, object], Never, Never] | The property schemas a form may request; the enum forms are tried before the plain string so their keys survive decoding. |
REQUESTED_SCHEMA | StructSchema[RequestedSchema, Never, Never] | |
ELICIT_REQUEST_FORM_PARAMS | StructSchema[ElicitRequestFormParams, Never, Never] | |
ELICIT_REQUEST_URL_PARAMS | StructSchema[ElicitRequestURLParams, Never, Never] | |
ELICIT_REQUEST_PARAMS | S.Codec[ElicitRequestParams, Any] | |
ELICIT_RESULT | StructSchema[ElicitResult, Never, Never] | |
ListToolsResult | type[_ListToolsResult] | |
ListResourcesResult | type[_ListResourcesResult] | |
ListResourceTemplatesResult | type[_ListResourceTemplatesResult] | |
ListPromptsResult | type[_ListPromptsResult] | |
PING | Method[RequestMeta, dict[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None]] | |
INITIALIZE | Method[InitializeParams, InitializeResult] | |
LIST_TOOLS | Method[_Cursor, _ListToolsResult] | |
CALL_TOOL | Method[CallToolParams, CallToolResult] | |
LIST_RESOURCES | Method[_Cursor, _ListResourcesResult] | |
LIST_RESOURCE_TEMPLATES | Method[_Cursor, _ListResourceTemplatesResult] | |
READ_RESOURCE | Method[_Uri, ReadResourceResult] | |
SUBSCRIBE | Method[_Uri, dict[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None]] | |
UNSUBSCRIBE | Method[_Uri, dict[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None]] | |
LIST_PROMPTS | Method[_Cursor, _ListPromptsResult] | |
GET_PROMPT | Method[_GetPromptParams, GetPromptResult] | |
COMPLETE | Method[CompleteParams, CompleteResult] | |
SET_LEVEL | Method[_SetLevelParams, dict[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None]] | |
CREATE_MESSAGE | Method[CreateMessageParams, CreateMessageResult] | |
LIST_ROOTS | Method[RequestMeta, ListRootsResult] | |
ELICIT | Method[ElicitRequestFormParams | ElicitRequestURLParams, ElicitResult] | |
CLIENT_REQUESTS | Mapping[str, Method[Any, Any]] | The requests a client sends (Effect's |
SERVER_REQUESTS | Mapping[str, Method[Any, Any]] | The requests a server sends (Effect's |
SUBSCRIPTION_FILTER | StructSchema[SubscriptionFilter, Never, Never] | |
SUBSCRIPTIONS_LISTEN | Method[SubscriptionsListenParams, dict[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None]] | |
SKILL | StructSchema[Skill, Never, Never] | |
SKILL_FRONTMATTER | StructWithRestSchema[_SkillFrontmatterFields, Never, Never] | The frontmatter as the Agent Skills specification defines it
(https://agentskills.io/specification). |
SKILL_RESOURCE | StructSchema[SkillResource, Never, Never] |
Types#
| Type | Definition | Description |
|---|---|---|
RequestId | type RequestId = str | int | float | A JSON-RPC id: a string or a finite number, never a boolean. Read one
from a message only through |
JsonObject | type JsonObject = dict[str, JsonValue] | |
JsonRpcResponse | type JsonRpcResponse = JsonRpcSuccess | JsonRpcError | |
JsonRpcMessage | type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse | |
Role | type Role = Literal['user', 'assistant'] | |
ResourceContents | type ResourceContents = TextResourceContents | BlobResourceContents | |
ContentBlock | type ContentBlock = TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource | |
ToolJson | type ToolJson = dict[str, Any] | A JSON Schema with |
LoggingLevel | type LoggingLevel = Literal['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'] | |
PrimitiveSchemaDefinition | type PrimitiveSchemaDefinition = LegacyTitledEnum | UntitledSingleSelectEnum | TitledSingleSelectEnum | UntitledMultiSelectEnum | TitledMultiSelectEnum | ElicitationString | ElicitationNumber | ElicitationBoolean | |
ElicitRequestParams | type ElicitRequestParams = ElicitRequestFormParams | ElicitRequestURLParams | |
ReverseOperation | type ReverseOperation = Literal['roots/list', 'sampling/createMessage', 'elicitation/create'] | |
ReverseError | type ReverseError = McpReverseOperationUnsupported | McpReverseOperationError | |
McpInputRequest | type McpInputRequest = RootsInputRequest | SamplingInputRequest | ElicitationInputRequest | A request for client input, keyed in |
McpInputResponse | type McpInputResponse = Mapping[str, Any] | The client's answer to an |
SkillFrontmatter | type SkillFrontmatter = dict[str, JsonValue] | The YAML frontmatter of a |
Classes#
Functions#
parse_request_id#
parse_request_id(value) -> RequestId | Nonevalue as a request id (Effect's RequestId: a string or a finite
number), else None. True is not 1, and a list or an object
is no id at all.
| Parameter | Type | Description |
|---|---|---|
value | object |
Returns RequestId | None
def parse_request_id(value: object) -> RequestId | None:
"""``value`` as a request id (Effect's ``RequestId``: a string or a finite
number), else ``None``. ``True`` is not ``1``, and a list or an object
is no id at all."""
kind = type(value)
if kind is str or kind is int:
return cast("str | int", value)
if kind is float and math.isfinite(cast("float", value)):
return cast("float", value)
return Noneparam#
param[T](name, schema) -> Param[T]| Parameter | Type | Description |
|---|---|---|
name | str | |
schema | S.Codec[T, Any, Any, Any] |
Returns Param[T]
def param[T](name: str, schema: S.Codec[T, Any, Any, Any]) -> Param[T]:
return Param(name, schema)