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 ¶
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.
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.
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).
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.
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
¶
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.