json-rpc envelope & error codes

68 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

OpenTelemetry trace context keys exempt from _meta prefix rules

As an exception to the `_meta` prefix requirement, the keys `traceparent`, `tracestate`, and `baggage` are reserved for OpenTelemetry trace context propagation. When present, their values MUST follow the W3C Trace Context and W3C Baggage formats respectively. The exception maintains compatibility with existing implementations and OpenTelemetry semantic conventions for MCP.

JSON-RPC request shape and ID rules in MCP

All messages between MCP clients and servers MUST follow JSON-RPC 2.0. A request has the shape `{ jsonrpc: "2.0"; id: string | number; method: string; params?: { [key: string]: unknown } }`. Requests MUST include a string or integer ID; unlike base JSON-RPC the ID MUST NOT be `null`; and the request ID MUST NOT match the ID of any other request the sender has issued and not yet received a response for.

Result response shape requires a resultType field

A result response has the shape `{ jsonrpc: "2.0"; id: string | number; result: { resultType: string; [key: string]: unknown } }`. Result responses MUST include the same ID as the corresponding request, MUST include a `result` field, and the `result` MUST include a `resultType` string field indicating the result type. The `result` MAY otherwise follow any JSON object structure.

resultType values: complete, input_required, and unknown handling

The `resultType` field enables polymorphic results. `"complete"` means the request completed successfully and the result holds the final content. `"input_required"` means the request is incomplete and more information is needed; the result contains an `InputRequiredResult` object. Extensions MAY add additional ResultType values; the supported set MUST be built from the core protocol values plus values of supported extensions advertised via capabilities. A `resultType` value unrecognized by the client MUST be considered invalid. For backward compatibility with servers on earlier protocol versions that omit `resultType`, clients MUST treat an absent `resultType` as `"complete"`.

Error response shape

An error response has the shape `{ jsonrpc: "2.0"; id?: string | number; error: { code: number; message: string; data?: unknown } }`. Error responses MUST include the same ID as the request they correspond to, except when the ID could not be read due to a malformed request. They MUST include an `error` field with a `code` and `message`, error codes MUST be integers, and they MAY include a `data` member of any type carrying additional information such as nested errors.

MCP error code range partitioning (-32000 to -32099)

MCP uses standard JSON-RPC 2.0 error codes (-32700, and -32600 to -32603) for general protocol failures. JSON-RPC reserves -32000 to -32099 for implementation-defined server errors, which MCP partitions: -32000 to -32019 is legacy (new codes MUST NOT be allocated there, new implementations SHOULD NOT use them, and apart from -32002 receivers MUST NOT assume any specific meaning); -32020 to -32099 is reserved for the MCP specification, where implementations MUST NOT emit undefined codes and MUST use defined codes only with their specified meanings. New error codes for purposes not defined by the spec SHOULD be allocated outside the JSON-RPC reserved range -32768 to -32000.

MCP-defined error codes -32020, -32021, -32022

The 2026-07-28 MCP specification defines these error codes: -32020 = HeaderMismatch, -32021 = MissingRequiredClientCapability, -32022 = UnsupportedProtocolVersion.

Retired error codes -32002 and -32042

Codes from earlier protocol versions remain reserved and will not be reused. Implementations of 2026-07-28 MUST NOT emit -32002 (resource not found, used in 2025-11-25 and earlier, now replaced by -32602) or -32042 (URL elicitation required, 2025-11-25 only). Clients SHOULD still accept -32002 from servers implementing earlier versions.

Local (SDK-internal) errors have no assigned codes

Errors purely local to an implementation, such as a request timeout raised inside an SDK, are not assigned codes by the MCP specification. Implementations surfacing local errors in JSON-RPC-shaped structures should ensure they cannot be mistaken for errors received from the peer. Future spec versions may define standard codes for common local error conditions in the reserved sub-range.

Notification shape: no ID, no response

Notifications are one-way messages sent from client to server or vice versa with the shape `{ jsonrpc: "2.0"; method: string; params?: { [key: string]: unknown } }`. Notifications MUST NOT include an ID, and the receiver MUST NOT send a response.

_meta key name format rules

A `_meta` key name has two segments: an optional prefix and a name. If specified, the prefix MUST be a series of labels separated by dots followed by a slash; labels MUST start with a letter and end with a letter or digit, with interior letters, digits, or hyphens. Implementations SHOULD use reverse DNS notation (e.g. `com.example/`). Any prefix whose second label is `modelcontextprotocol` or `mcp` is reserved for MCP (e.g. `io.modelcontextprotocol/`, `dev.mcp/`, `org.modelcontextprotocol.api/`, `com.mcp.tools/`), but `com.example.mcp/` is NOT reserved because the second label is `example`. The name, unless empty, MUST begin and end with an alphanumeric character and MAY contain hyphens, underscores, dots, and alphanumerics in between. Implementations MUST NOT make assumptions about values at MCP-reserved keys.

Reserved _meta keys list

The specification reserves these `_meta` keys: `progressToken` (opts the request into progress notifications), `io.modelcontextprotocol/protocolVersion` (protocol version for a request), `io.modelcontextprotocol/clientInfo` (client name and version), `io.modelcontextprotocol/clientCapabilities` (client capabilities relevant to a request), `io.modelcontextprotocol/logLevel` (minimum log level the server should emit for a request), `io.modelcontextprotocol/subscriptionId` (correlates a notification with its originating subscription), and `traceparent`, `tracestate`, `baggage` (OpenTelemetry trace context propagation). Official extensions define additional `_meta` keys under `io.modelcontextprotocol/`; third-party extensions use their own vendor prefix.

Missing required _meta field must be rejected with -32602 / HTTP 400

A request missing any required `io.modelcontextprotocol/*` `_meta` field (protocolVersion or clientCapabilities) is malformed; the server MUST reject it with JSON-RPC error code -32602 (Invalid params), and on HTTP the response status MUST be 400 Bad Request.

Invalid cancellation notifications are ignored, not errored

Invalid cancellation notifications SHOULD be ignored, including unknown request IDs, already completed requests, and malformed notifications. No error response is returned, preserving the fire-and-forget nature of notifications while tolerating race conditions in asynchronous communication.

Servers MUST NOT initiate JSON-RPC requests (2026-07-28)

In MCP revision 2026-07-28, every interaction begins with the client: the client sends JSON-RPC requests and notifications, and the server answers each request with a JSON-RPC response (result or error), optionally preceded by notifications scoped to that request. Servers MUST NOT initiate JSON-RPC requests, and clients do not send JSON-RPC responses.

Retry MUST use a different JSON-RPC id

The JSON-RPC `id` MUST be different between the initial request and the MRTR retry, because they are independent requests. The initial request is terminated when the server returns the `InputRequiredResult`.

MRTR error handling: validate InputResponses, ignore unknown fields

Servers SHOULD validate that data provided by the client is a valid `InputResponses` object and that its contents can be correctly parsed. Protocol errors (malformed JSON, invalid schema, internal server errors) SHOULD return a JSON-RPC error response with an appropriate error code and message. If additional, unexpected parameters appear in the `InputResponses` object, the server SHOULD ignore anything it does not recognize or need.

JSON-RPC messages MUST be UTF-8 encoded

MCP encodes messages using JSON-RPC, and JSON-RPC messages MUST be UTF-8 encoded on every transport.

Only two message directions exist: client requests/notifications, server responses/notifications

A transport binding MUST deliver client-sent requests and notifications to the server, and server-sent responses and notifications to the client. No other message direction exists: in this revision servers do not initiate JSON-RPC requests and clients do not send JSON-RPC responses.

Legacy fallback MUST NOT be keyed to a specific error code

The fallback from modern MCP to the legacy `initialize` handshake MUST NOT be keyed to one specific error code: legacy servers respond to unknown pre-initialize requests with implementation-defined errors (commonly -32601 Method not found or -32602 Invalid params) or not at all.

Resource not found error code changed to -32602

The resource not found error code changed from `-32002` to `-32602` (Invalid Params) to align with the JSON-RPC specification.

MCP error code allocation policy: -32000..-32019 vs -32020..-32099

The error code allocation policy partitions the JSON-RPC server-error range: `-32000` to `-32019` remains implementation-defined (existing SDK usage is grandfathered), and `-32020` to `-32099` is reserved for the MCP specification.

Renumbered error codes: HeaderMismatch -32020, MissingRequiredClientCapability -32021, UnsupportedProtocolVersion -32022

Error codes introduced in the 2026-07-28 draft were renumbered into the MCP-reserved range: `HeaderMismatch` from `-32001` to `-32020`, `MissingRequiredClientCapability` from `-32003` to `-32021`, and `UnsupportedProtocolVersion` from `-32004` to `-32022`. `HeaderMismatchError` was added to the schema, having previously existed only in transport prose.

Required resultType field on all results

All results in 2026-07-28 carry a required `resultType` field: `"complete"` for ordinary results and `"input_required"` for multi round-trip interim results. Clients MUST treat results from earlier-protocol servers that omit the field as `"complete"`.

UnsupportedProtocolVersionError on version mismatch

Under 2026-07-28, protocol version mismatches are reported by returning `UnsupportedProtocolVersionError`. The `UnsupportedProtocolVersion` error code was renumbered from `-32004` to `-32022`.

OpenTelemetry trace context in _meta

The specification documents OpenTelemetry trace context propagation conventions for `_meta` keys: `traceparent`, `tracestate`, and `baggage` (SEP-414).

Elicitation error handling requirement

Servers SHOULD NOT assume elicitation requests will always succeed, and MUST handle cases where the user declines or cancels the elicitation, or where the client fails to process the request.

RFC 2119 / BCP 14 keyword interpretation in MCP

In the MCP specification, the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174), when and only when they appear in all capitals.

Prompt error codes: -32602 and -32603

For prompts, servers SHOULD return standard JSON-RPC errors: invalid prompt name -> -32602 (Invalid params); missing required arguments -> -32602 (Invalid params); internal errors -> -32603 (Internal error).

Resource not found error code -32602

If the requested resource does not exist, servers MUST return a JSON-RPC error with code -32602 (Invalid Params). Servers SHOULD return -32603 for internal errors. For backwards compatibility, clients SHOULD also accept -32002 as a resource-not-found error, since earlier protocol versions used that code. Example error: {"jsonrpc":"2.0","id":5,"error":{"code":-32602,"message":"Resource not found","data":{"uri":"file:///nonexistent.txt"}}}.

Empty contents array for missing resource is forbidden

Servers MUST NOT return an empty `contents` array for a non-existent resource, because an empty array is ambiguous: it could mean the resource exists but has no content, or that it does not exist at all. A -32602 error must be returned instead.

Tool protocol errors use JSON-RPC error -32602

Protocol errors for tools (unknown tool, malformed requests failing the CallToolRequest schema, server errors) are returned as standard JSON-RPC errors, e.g. {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Unknown tool: invalid_tool_name"}}.

Tool execution errors use isError: true in result

Tool execution errors (API failures, input validation errors such as a date out of range, business logic errors) are reported inside a successful JSON-RPC result with "isError": true, e.g. {"result":{"resultType":"complete","content":[{"type":"text","text":"Invalid departure date: must be in the future..."}],"isError":true}}. Clients MAY provide protocol errors to language models, but SHOULD provide tool execution errors to language models to enable self-correction.

Every request MUST include required _meta fields

In the 2026-07-28 MCP specification, every request MUST include the required `_meta` request metadata fields: `io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientInfo`, and `io.modelcontextprotocol/clientCapabilities`. Documentation examples often omit them for brevity.

Completion error codes: -32601, -32602, -32603

Servers SHOULD return standard JSON-RPC errors for completion failures: -32601 Method not found (capability not supported), -32602 Invalid params for an invalid prompt name or missing required arguments, and -32603 Internal error for internal failures.

Logging error codes -32602 and -32603

If the `io.modelcontextprotocol/logLevel` value carried in a request's `_meta` is not a recognized log level, the server SHOULD reject that request with a standard JSON-RPC error: -32602 (Invalid params) for an invalid log level, and -32603 (Internal error) for internal errors.

Invalid pagination cursor returns -32602 Invalid params

Invalid cursors SHOULD result in a JSON-RPC error with code -32602 (Invalid params).

Every request MUST include required _meta fields

Every MCP request MUST include the required `_meta` request metadata fields: `io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientInfo`, and `io.modelcontextprotocol/clientCapabilities`. Documentation examples often omit these for brevity, but they are mandatory.

UnsupportedProtocolVersionError on version mismatch

If a server does not support the protocol version requested by a client (sent inline via `_meta['io.modelcontextprotocol/protocolVersion']`), the client must handle an `UnsupportedProtocolVersionError`, defined in the 2026-07-28 schema.

Unknown method returns HTTP 404 with JSON-RPC -32601

If the server does not implement the requested RPC method, it MUST respond with HTTP 404 Not Found and a JSON-RPC error with code -32601 (Method not found). The JSON-RPC error body distinguishes this case from a 404 returned by a legacy HTTP+SSE server that does not host the modern MCP endpoint.

Error code -32020 HeaderMismatch

JSON-RPC error code -32020 is named HeaderMismatch: the HTTP headers do not match the corresponding values in the request body, or required headers are missing/malformed. Servers MUST return HTTP 400 Bad Request together with this JSON-RPC error. It is allocated from the sub-range reserved for MCP protocol-defined errors. Example body: {"jsonrpc":"2.0","id":1,"error":{"code":-32020,"message":"Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"}}.

Error object fields: code, message, data

The `Error` interface is `{ code: number; message: string; data?: unknown }`. `code` is the error type that occurred, `message` is a short description that SHOULD be limited to a concise single sentence, and `data` carries additional sender-defined information (detailed error information, nested errors, etc.).

Error code -32020 HEADER_MISMATCH

`HEADER_MISMATCH` is the error code -32020, returned when the HTTP headers of a request do not match the corresponding values in the request body, or when required headers are missing or malformed. The `HeaderMismatchError` shape is `{ jsonrpc: "2.0"; id?: RequestId; error: Error & { code: -32020 } }`. For HTTP, the response status code MUST be `400 Bad Request`.

HeaderMismatchError example payload

Example header mismatch error response: {"jsonrpc": "2.0", "id": 1, "error": {"code": -32020, "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"}}.

serverInfo in result _meta

`ResultMetaObject` may include `"io.modelcontextprotocol/serverInfo"?: Implementation`; servers SHOULD include it on every response unless configured otherwise. `Implementation` requires `name` and `version`. It is self-reported and unverified; clients SHOULD NOT use it to change behaviour or for security decisions.

Result requires resultType field

The `Result` interface is `{ _meta?: ResultMetaObject; resultType: string; [key: string]: unknown }`. Servers implementing protocol version 2026-07-28 MUST include `resultType`. For backward compatibility, when a client receives a result from a server on an earlier protocol version that omits `resultType`, the client MUST treat the absent field as `"complete"`.

NotificationParams shape

`NotificationParams` is `{ _meta?: NotificationMetaObject }` — unlike request params, `_meta` is optional on notifications.

_meta key naming rules (MetaObject)

`MetaObject` is `Record<string, unknown>`. Certain key names are reserved by MCP for protocol-level metadata and implementations MUST NOT make assumptions about values at those keys. Valid keys have two segments. Prefix: optional; if specified it MUST be a series of labels separated by dots followed by a slash; labels MUST start with a letter and end with a letter or digit, with interior letters, digits or hyphens; implementations SHOULD use reverse DNS notation (e.g. `com.example/`). Any prefix whose second label is `modelcontextprotocol` or `mcp` is reserved for MCP (e.g. `io.modelcontextprotocol/`, `dev.mcp/`, `org.modelcontextprotocol.api/`, `com.mcp.tools/`), but `com.example.mcp/` is NOT reserved. Name segment: unless empty, MUST start and end with an alphanumeric character `[a-z0-9A-Z]`; interior characters may be alphanumeric, hyphens, underscores or dots.

EmptyResult and JSON value aliases

`EmptyResult` is an alias of `Result` indicating success with no data. `JSONValue` is `string | number | boolean | null | JSONObject | JSONArray`; `JSONObject` is `{ [key: string]: JSONValue }`; `JSONArray` is `JSONValue[]`.

Internal error code -32603 (InternalError)

MCP's InternalError is a JSON-RPC error with code exactly -32603, a string `message` (SHOULD be a concise single sentence), and optional `data` of unknown type. It indicates the receiver encountered an unexpected condition preventing it from fulfilling the request. Example: {"code": -32603, "message": "Internal error"}.

Invalid params error code -32602 and when MCP returns it

InvalidParamsError has code exactly -32602 and means method parameters are invalid or malformed. In MCP it is returned for: Tools (unknown tool name or invalid tool arguments), Prompts (unknown prompt name or missing required arguments), Pagination (invalid or expired cursor values), Logging (invalid log level), Elicitation (server requests an elicitation mode not declared in client capabilities), and Sampling (missing tool result, or tool results mixed with other content).

Example -32602 error messages for unknown tool, bad arguments, unknown prompt, invalid cursor

Spec examples of -32602 errors: {"code": -32602, "message": "Unknown tool: invalid_tool_name"}; {"code": -32602, "message": "Invalid arguments for tool calculate: Missing required property 'expression'"}; {"code": -32602, "message": "Unknown prompt: invalid_prompt_name"}; {"code": -32602, "message": "Invalid cursor"}.

Invalid request error code -32600

InvalidRequestError has code exactly -32600 and is returned when the message structure does not conform to JSON-RPC 2.0 request requirements, e.g. missing required fields like `jsonrpc` or `method`, or using invalid types for these fields.

Method not found -32601 covers unadvertised server capabilities

MethodNotFoundError has code exactly -32601 and means the requested method does not exist or is not available. In MCP a server returns it when a client invokes a method the server does not implement — either a genuinely unknown method, or one gated behind a server capability the server did not advertise (e.g. calling `prompts/list` when the `prompts` capability was not advertised). Example: {"code": -32601, "message": "Prompts not supported", "data": {"reason": "Server does not support the prompts capability"}}.

Distinguish -32601 (server capability) from -32021 (client capability)

A request that requires a *client* capability the client did not declare is signalled with MissingRequiredClientCapabilityError (-32021), not with MethodNotFoundError (-32601). -32601 is used for methods the server does not implement or capabilities the server did not advertise.

MISSING_REQUIRED_CLIENT_CAPABILITY = -32021 shape and HTTP 400 MUST

The MCP-specific error code MISSING_REQUIRED_CLIENT_CAPABILITY is -32021, returned when processing a request requires a capability the client did not declare in `clientCapabilities`. The error object is `Error & { code: -32021; data: { requiredCapabilities: ClientCapabilities } }` inside a JSONRPCErrorResponse with `jsonrpc: "2.0"` and optional `id`. For HTTP, the response status code MUST be 400 Bad Request.

Parse error code -32700

ParseError has code exactly -32700 and is returned when invalid JSON was received and the server cannot parse the JSON text of a message. Example: {"code": -32700, "message": "Parse error: Invalid JSON"}.

Error object fields: code, message, data

Every MCP JSON-RPC error object has `code` (the error type), `message: string` (a short description; the message SHOULD be limited to a concise single sentence), and optional `data?: unknown` (additional information defined by the sender, e.g. detailed error information or nested errors).

JSONRPCErrorResponse envelope fields

A JSON-RPC error response in MCP has `jsonrpc: "2.0"`, an optional `id?: RequestId`, and an `error` object. Specialised error responses such as MissingRequiredClientCapabilityError and UnsupportedProtocolVersionError inherit `jsonrpc` and `id` from JSONRPCErrorResponse.

ListPromptsResultResponse and ListResourcesResultResponse envelopes

ListPromptsResultResponse has jsonrpc: "2.0", id: RequestId, and result: ListPromptsResult; ListResourcesResultResponse has jsonrpc: "2.0", id: RequestId, and result: ListResourcesResult. Both override JSONRPCResultResponse.result.

Give your agent this brain