Protocol types

JSON-RPC envelope, MCP message types, and error codes.

JSON-RPC

JsonRpcRequest dataclass

A JSON-RPC 2.0 request: has id and expects a response.

JsonRpcNotification dataclass

A JSON-RPC 2.0 notification: no id, no response expected.

JsonRpcResponse dataclass

A JSON-RPC 2.0 response: exactly one of result or error is set.

JsonRpcError dataclass

JSON-RPC 2.0 error object.

code is typed as int so server-defined codes outside the :class:JsonRpcErrorCode enum can still be represented faithfully.

JsonRpcErrorCode

Bases: IntEnum

JSON-RPC 2.0 standard error codes plus MCP-specific reservations.

The standard codes (-32700 through -32600 and -32603) are defined by JSON-RPC; MCP reserves the -32000 through -32099 range for server-defined errors. We map common MCP failure modes onto stable codes here so handlers don't drift.

parse_message

parse_message(payload: dict[str, Any]) -> JsonRpcMessage

Classify a parsed JSON object as request / notification / response.

Raises ValueError if the payload has no recognizable shape — caller should translate that to a JSON-RPC -32600 (Invalid Request) error.

Initialize handshake

Implementation dataclass

Identifies an MCP client or server: name + version, with an optional title.

Mirrors the spec's Implementation extends BaseMetadata. The two labels are not interchangeable, and the split is the spec's own:

• :attr:name is "intended for programmatic or logical use" — the stable identifier. This is what distinguishes two servers to a client, and what server-scoped state keys off.
• :attr:title is "intended for UI and end-user contexts" — the human-readable label. Optional; clients fall back to name when absent.

ClientCapabilities dataclass

Capability bundle the client advertises in initialize.

All fields are open-ended dicts because the MCP spec leaves room for future capability sub-keys. We round-trip them verbatim.

extensions class-attribute instance-attribute

extensions: dict[str, Any] | None = None

Protocol extensions the client implements, keyed by extension id — how a client says it supports MCP Apps (io.modelcontextprotocol/ui).

Advertisement is one-directional, client → server: the spec defines no matching server capability, so nothing is sent back. Parsed here for introspection only. Nothing gates on it — the spec merely SHOULD-s a check, and remembering it per session would mean widening the pluggable SessionStore Protocol, which is a breaking change not worth making for metadata that unsupporting clients are required to ignore anyway.

ServerCapabilities dataclass

Capability bundle the server advertises in the initialize response.

For v1 we ship tools and resources; prompts is reserved.

InitializeParams dataclass

Parsed initialize request params.

InitializeResult dataclass

The server's response to an initialize request.

Tools

Tool dataclass

An MCP tool descriptor as returned by tools/list.

input_schema and output_schema are JSON Schema documents. annotations carries the MCP ToolAnnotations hint bundle (e.g. readOnlyHint, destructiveHint).

meta is the base-protocol _meta bundle — distinct from the annotations hint bundle above, which is a closed, spec-defined set of client hints. _meta is where protocol extensions put their keys.

ToolContentBlock dataclass

A single content block in a :class:ToolResult.

type is normally "text"; "image" and "resource" are reserved for future use. The encoder writes only "text" blocks today.

ToolResult dataclass

The result of a successful tools/call.

structured_content is always JSON-shaped (clients parse it directly); content is the human-readable / token-efficient projection that the encoder produces (JSON or TOON, etc.).

is_error is True when the tool itself reported failure — it is distinct from a JSON-RPC protocol error: the JSON-RPC envelope is still a successful response, the failure detail lives inside the result.

meta is the base-protocol _meta bundle on the result envelope — per-call, unlike the static _meta a tools/list entry carries.

Resources

Resource dataclass

A concrete MCP resource as returned by resources/list.

uri is the canonical address (e.g. "invoices://1"); mime_type advertises how the contents will be encoded by resources/read.

ResourceTemplate dataclass

A parameterised resource address (RFC 6570 URI Template).

Returned by resources/templates/list. Clients fill in template variables and call resources/read with the resulting URI.

ResourceContents dataclass

One contents entry returned by resources/read.

Either text or blob is set — never both. blob is base64- encoded per the MCP spec.

Prompts

Prompt dataclass

An MCP prompt descriptor as returned by prompts/list.

A prompt is a server-defined template the client invokes by name to get back a sequence of LLM messages. Arguments are filled in at prompts/get time and threaded into the rendering callable as kwargs.

PromptArgument dataclass

One declared input to an MCP prompt.

Mirrors the spec's PromptArgument shape: a name plus optional description, with a flag indicating whether the client must supply it. Used in prompts/list to advertise the prompt's interface.

PromptMessage dataclass

One conversation turn returned by prompts/get.

The MCP spec accepts user or assistant for role and supports several content types (text, image, resource); v1 ships text only — the type is set on content so future content types slot in without changing this dataclass's shape.

text classmethod

text(role: str, text: str) -> PromptMessage

Convenience constructor for the common case of a text turn.

GetPromptResult dataclass

Result envelope returned by prompts/get.

description is optional — the spec uses it to surface the prompt's purpose to the client UI alongside the rendered messages.