Skip to content

jsonrpc

This module follows the JSON-RPC 2.0 specification: https://www.jsonrpc.org/specification.

RequestId module-attribute 

RequestId = Annotated[int, Field(strict=True)] | str

The ID of a JSON-RPC request.

JSONRPC_VERSION module-attribute 

JSONRPC_VERSION: Final[Literal['2.0']] = '2.0'

The JSON-RPC version string carried by every MCP message envelope.

JSONRPCRequest

Bases: BaseModel

A JSON-RPC request that expects a response.

Source code in src/mcp-types/mcp_types/jsonrpc.py 
16
17
18
19
20
21
22
class JSONRPCRequest(BaseModel):
    """A JSON-RPC request that expects a response."""

    jsonrpc: Literal["2.0"]
    id: RequestId
    method: str
    params: dict[str, Any] | None = None

JSONRPCNotification

Bases: BaseModel

A JSON-RPC notification which does not expect a response.

Source code in src/mcp-types/mcp_types/jsonrpc.py 
25
26
27
28
29
30
class JSONRPCNotification(BaseModel):
    """A JSON-RPC notification which does not expect a response."""

    jsonrpc: Literal["2.0"]
    method: str
    params: dict[str, Any] | None = None

JSONRPCResponse

Bases: BaseModel

A successful (non-error) response to a request.

Named JSONRPCResultResponse in the 2025-11-25+ schemas; the SDK keeps the original name.

Source code in src/mcp-types/mcp_types/jsonrpc.py 
33
34
35
36
37
38
39
40
41
class JSONRPCResponse(BaseModel):
    """A successful (non-error) response to a request.

    Named `JSONRPCResultResponse` in the 2025-11-25+ schemas; the SDK keeps the original name.
    """

    jsonrpc: Literal["2.0"]
    id: RequestId
    result: dict[str, Any]

HEADER_MISMATCH module-attribute 

HEADER_MISMATCH = -32020

HTTP headers do not match the request body, or required headers are missing/malformed (protocol 2026-07-28).

MISSING_REQUIRED_CLIENT_CAPABILITY module-attribute 

MISSING_REQUIRED_CLIENT_CAPABILITY = -32021

The server requires a client capability the request did not declare (protocol 2026-07-28).

UNSUPPORTED_PROTOCOL_VERSION module-attribute 

UNSUPPORTED_PROTOCOL_VERSION = -32022

The request's protocol version is not supported by the server (protocol 2026-07-28).

URL_ELICITATION_REQUIRED module-attribute 

URL_ELICITATION_REQUIRED = -32042

A URL-mode elicitation is required before the request can be processed (protocol 2025-11-25 only).

CONNECTION_CLOSED module-attribute 

CONNECTION_CLOSED = -32000

SDK-only: the connection closed before a response arrived; never emitted on the wire.

REQUEST_TIMEOUT module-attribute 

REQUEST_TIMEOUT = -32001

SDK-only: a request timed out waiting for its response.

PARSE_ERROR module-attribute 

PARSE_ERROR = -32700

Standard JSON-RPC: invalid JSON was received.

INVALID_REQUEST module-attribute 

INVALID_REQUEST = -32600

Standard JSON-RPC: the message is not a valid request object.

METHOD_NOT_FOUND module-attribute 

METHOD_NOT_FOUND = -32601

Standard JSON-RPC: the requested method does not exist or is not available.

INVALID_PARAMS module-attribute 

INVALID_PARAMS = -32602

Standard JSON-RPC: invalid method parameters.

INTERNAL_ERROR module-attribute 

INTERNAL_ERROR = -32603

Standard JSON-RPC: an internal error occurred on the receiver.

The SDK uses the generic ErrorData envelope; the schema's per-code wrapper types are not constructed.

ErrorData

Bases: BaseModel

Error information for JSON-RPC error responses.

Source code in src/mcp-types/mcp_types/jsonrpc.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class ErrorData(BaseModel):
    """Error information for JSON-RPC error responses."""

    code: int
    """The error type that occurred."""

    message: str
    """A short description of the error.

    The message SHOULD be limited to a concise single sentence.
    """

    data: Any = None
    """Additional information about the error.

    The value of this member is defined by the sender (e.g. detailed error information, nested errors, etc.).
    """

code instance-attribute 

code: int

The error type that occurred.

message instance-attribute 

message: str

A short description of the error.

The message SHOULD be limited to a concise single sentence.

data class-attribute instance-attribute 

data: Any = None

Additional information about the error.

The value of this member is defined by the sender (e.g. detailed error information, nested errors, etc.).

JSONRPCError

Bases: BaseModel

A response to a request that indicates an error occurred.

Source code in src/mcp-types/mcp_types/jsonrpc.py 
109
110
111
112
113
114
115
116
117
118
119
class JSONRPCError(BaseModel):
    """A response to a request that indicates an error occurred."""

    jsonrpc: Literal["2.0"]
    id: RequestId | None
    """The id of the request this error responds to.

    Required but nullable per JSON-RPC 2.0: `None` encodes `"id": null` (the id could not be determined).
    """

    error: ErrorData

id instance-attribute 

id: RequestId | None

The id of the request this error responds to.

Required but nullable per JSON-RPC 2.0: None encodes "id": null (the id could not be determined).

JSONRPCMessage module-attribute 

JSONRPCMessage = (
    JSONRPCRequest
    | JSONRPCNotification
    | JSONRPCResponse
    | JSONRPCError
)

Any JSON-RPC envelope that can be decoded off the wire or encoded to be sent.