GitHub

mcp_schema

API reference for mcp_schema.

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

AttributeTypeDescription
PARSE_ERROR_CODELiteral[-32700] = -32700
INVALID_REQUEST_ERROR_CODELiteral[-32600] = -32600
METHOD_NOT_FOUND_ERROR_CODELiteral[-32601] = -32601
INVALID_PARAMS_ERROR_CODELiteral[-32602] = -32602
INTERNAL_ERROR_CODELiteral[-32603] = -32603
HEADER_MISMATCH_ERROR_CODELiteral[-32020] = -32020
MISSING_REQUIRED_CLIENT_CAPABILITY_ERROR_CODELiteral[-32021] = -32021
UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODELiteral[-32022] = -32022
RESOURCE_NOT_FOUND_ERROR_CODELiteral[-32002] = -32002

What revisions before 2026-07-28 answer an unknown resource with.

REQUEST_IDUnionSchema[str | float, str | float, Never, Never]
JSON_OBJECTRecordSchema[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_REQUESTStructSchema[JsonRpcRequest, Never, Never]
JSON_RPC_NOTIFICATIONStructSchema[JsonRpcNotification, Never, Never]
JSON_RPC_ERROR_OBJECTStructSchema[JsonRpcErrorObject, Never, Never]
JSON_RPC_SUCCESSStructSchema[JsonRpcSuccess, Never, Never]
JSON_RPC_ERRORStructSchema[JsonRpcError, Never, Never]
JSON_RPC_RESPONSEUnionSchema[JsonRpcSuccess | JsonRpcError, Mapping[str, object], Never, Never]
JSON_RPC_MESSAGEUnionSchema[JsonRpcNotification | JsonRpcSuccess | JsonRpcError, Mapping[str, object], Never, Never]
REQUEST_META_OBJECTStructWithRestSchema[_ProgressMeta, Never, Never]
REQUEST_METAStructSchema[RequestMeta, Never, Never]
ICONStructSchema[Icon, Never, Never]
IMPLEMENTATIONStructSchema[Implementation, Never, Never]
CLIENT_CAPABILITIESStructSchema[ClientCapabilities, Never, Never]
SERVER_CAPABILITIESStructSchema[ServerCapabilities, Never, Never]
INITIALIZE_PARAMSStructSchema[InitializeParams, Never, Never]
INITIALIZE_RESULTStructSchema[InitializeResult, Never, Never]
ANNOTATIONSStructSchema[Annotations, Never, Never]
TEXT_CONTENTStructSchema[TextContent, Never, Never]
IMAGE_CONTENTStructSchema[ImageContent, Never, Never]
AUDIO_CONTENTStructSchema[AudioContent, Never, Never]
RESOURCE_LINKStructSchema[ResourceLink, Never, Never]
TEXT_RESOURCE_CONTENTSStructSchema[TextResourceContents, Never, Never]
BLOB_RESOURCE_CONTENTSStructSchema[BlobResourceContents, Never, Never]
RESOURCE_CONTENTSUnionSchema[TextResourceContents | BlobResourceContents, Mapping[str, object], Never, Never]
EMBEDDED_RESOURCEStructSchema[EmbeddedResource, Never, Never]
CONTENT_BLOCKUnionSchema[TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource, Mapping[str, object], Never, Never]
TOOL_ANNOTATIONSStructSchema[ToolAnnotations, Never, Never]
TOOL_JSONStructWithRestSchema[_ToolJsonFields, Never, Never]

A tool's input schema: a JSON Schema object whose properties are schemas (objects) or booleans (JSON Schema 2020-12, 4.3.2).

TOOLStructSchema[Tool, Never, Never]
CALL_TOOL_RESULTStructSchema[CallToolResult, Never, Never]
CALL_TOOL_PARAMSStructSchema[CallToolParams, Never, Never]
RESOURCEStructSchema[Resource, Never, Never]
RESOURCE_TEMPLATEStructSchema[ResourceTemplate, Never, Never]
READ_RESOURCE_RESULTStructSchema[ReadResourceResult, Never, Never]
PROMPT_ARGUMENTStructSchema[PromptArgument, Never, Never]
PROMPTStructSchema[Prompt, Never, Never]
PROMPT_MESSAGEStructSchema[PromptMessage, Never, Never]
GET_PROMPT_RESULTStructSchema[GetPromptResult, Never, Never]
COMPLETE_PARAMSStructSchema[CompleteParams, Never, Never]
COMPLETE_RESULTStructSchema[CompleteResult, Never, Never]
LOGGING_LEVELLiteralsSchema[Literal['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency']]
LOGGING_LEVELStuple[LoggingLevel, ...] = ('debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency')

The levels from least to most severe.

SAMPLING_MESSAGEStructSchema[SamplingMessage, Never, Never]
CREATE_MESSAGE_PARAMSStructSchema[CreateMessageParams, Never, Never]
CREATE_MESSAGE_RESULTStructSchema[CreateMessageResult, Never, Never]
ROOTStructSchema[Root, Never, Never]
LIST_ROOTS_RESULTStructSchema[ListRootsResult, Never, Never]
PRIMITIVE_SCHEMA_DEFINITIONUnionSchema[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_SCHEMAStructSchema[RequestedSchema, Never, Never]
ELICIT_REQUEST_FORM_PARAMSStructSchema[ElicitRequestFormParams, Never, Never]
ELICIT_REQUEST_URL_PARAMSStructSchema[ElicitRequestURLParams, Never, Never]
ELICIT_REQUEST_PARAMSS.Codec[ElicitRequestParams, Any]
ELICIT_RESULTStructSchema[ElicitResult, Never, Never]
ListToolsResulttype[_ListToolsResult]
ListResourcesResulttype[_ListResourcesResult]
ListResourceTemplatesResulttype[_ListResourceTemplatesResult]
ListPromptsResulttype[_ListPromptsResult]
PINGMethod[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]]
INITIALIZEMethod[InitializeParams, InitializeResult]
LIST_TOOLSMethod[_Cursor, _ListToolsResult]
CALL_TOOLMethod[CallToolParams, CallToolResult]
LIST_RESOURCESMethod[_Cursor, _ListResourcesResult]
LIST_RESOURCE_TEMPLATESMethod[_Cursor, _ListResourceTemplatesResult]
READ_RESOURCEMethod[_Uri, ReadResourceResult]
SUBSCRIBEMethod[_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]]
UNSUBSCRIBEMethod[_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_PROMPTSMethod[_Cursor, _ListPromptsResult]
GET_PROMPTMethod[_GetPromptParams, GetPromptResult]
COMPLETEMethod[CompleteParams, CompleteResult]
SET_LEVELMethod[_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_MESSAGEMethod[CreateMessageParams, CreateMessageResult]
LIST_ROOTSMethod[RequestMeta, ListRootsResult]
ELICITMethod[ElicitRequestFormParams | ElicitRequestURLParams, ElicitResult]
CLIENT_REQUESTSMapping[str, Method[Any, Any]]

The requests a client sends (Effect's ClientRequestRpcs), by name.

SERVER_REQUESTSMapping[str, Method[Any, Any]]

The requests a server sends (Effect's ServerRequestRpcs), by name.

SUBSCRIPTION_FILTERStructSchema[SubscriptionFilter, Never, Never]
SUBSCRIPTIONS_LISTENMethod[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]]
SKILLStructSchema[Skill, Never, Never]
SKILL_FRONTMATTERStructWithRestSchema[_SkillFrontmatterFields, Never, Never]

The frontmatter as the Agent Skills specification defines it (https://agentskills.io/specification). mcp_server checks a skill against it before serving it; a skill received from a server is only checked for the name and description the extension requires.

SKILL_RESOURCEStructSchema[SkillResource, Never, Never]

Types

TypeDefinitionDescription
RequestIdtype RequestId = str | int | float

A JSON-RPC id: a string or a finite number, never a boolean. Read one from a message only through parse_request_id.

JsonObjecttype JsonObject = dict[str, JsonValue]
JsonRpcResponsetype JsonRpcResponse = JsonRpcSuccess | JsonRpcError
JsonRpcMessagetype JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse
Roletype Role = Literal['user', 'assistant']
ResourceContentstype ResourceContents = TextResourceContents | BlobResourceContents
ContentBlocktype ContentBlock = TextContent | ImageContent | AudioContent | ResourceLink | EmbeddedResource
ToolJsontype ToolJson = dict[str, Any]

A JSON Schema with "type": "object" at its root.

LoggingLeveltype LoggingLevel = Literal['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency']
PrimitiveSchemaDefinitiontype PrimitiveSchemaDefinition = LegacyTitledEnum | UntitledSingleSelectEnum | TitledSingleSelectEnum | UntitledMultiSelectEnum | TitledMultiSelectEnum | ElicitationString | ElicitationNumber | ElicitationBoolean
ElicitRequestParamstype ElicitRequestParams = ElicitRequestFormParams | ElicitRequestURLParams
ReverseOperationtype ReverseOperation = Literal['roots/list', 'sampling/createMessage', 'elicitation/create']
ReverseErrortype ReverseError = McpReverseOperationUnsupported | McpReverseOperationError
McpInputRequesttype McpInputRequest = RootsInputRequest | SamplingInputRequest | ElicitationInputRequest

A request for client input, keyed in InputRequired.input_requests.

McpInputResponsetype McpInputResponse = Mapping[str, Any]

The client's answer to an McpInputRequest, keyed as the request was.

SkillFrontmattertype SkillFrontmatter = dict[str, JsonValue]

The YAML frontmatter of a SKILL.md as JSON. SKILL_FRONTMATTER checks the fields the Agent Skills specification defines (name, description, license, compatibility, metadata, allowed-tools) and keeps the others unchanged.

Classes

Functions

parse_request_id

parse_request_id(value) -> 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.

ParameterTypeDescription
valueobject

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 None

param

param[T](name, schema) -> Param[T]
ParameterTypeDescription
namestr
schemaS.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)