Skip to content

Define error code allocation policy and renumber draft error codes #2907

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
felixweinberger merged 12 commits into from
Jun 18, 2026
Merged

Define error code allocation policy and renumber draft error codes #2907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f505a6c
Define error code allocation policy and renumber draft error codes
felixweinberger Jun 12, 2026
73ab7d2
Extend implementation-defined sub-range to -32019
felixweinberger Jun 12, 2026
146b1f4
Update docs/specification/draft/basic/index.mdx
felixweinberger Jun 12, 2026
05895d7
Update docs/specification/draft/basic/index.mdx
felixweinberger Jun 12, 2026
74ac874
Update docs/specification/draft/basic/index.mdx
felixweinberger Jun 12, 2026
6bdff79
Leave room for future spec-defined local error codes
felixweinberger Jun 12, 2026
205e6c0
Tighten error code policy wording per review
felixweinberger Jun 15, 2026
3f732fb
Apply review feedback on range guidance
felixweinberger Jun 16, 2026
6ecfdcf
Merge branch 'main' into fweinberger/error-code-allocation
felixweinberger Jun 16, 2026
a1536e0
Merge remote-tracking branch 'origin/main' into fweinberger/error-cod…
felixweinberger Jun 17, 2026
e3f281c
Merge remote-tracking branch 'origin/main' into fweinberger/error-cod…
felixweinberger Jun 17, 2026
0bce6bc
Only carve out -32002 in the legacy sub-range receiver rule
felixweinberger Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion docs/specification/draft/basic/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,54 @@ can use to determine how to parse and handle the `result` object.
- Error responses **MUST** include an `error` field with a `code` and `message`.
- Error codes **MUST** be integers.

#### Error Codes

MCP uses the standard JSON-RPC 2.0 error codes (`-32700`, `-32600` to `-32603`)

@PederHP PederHP Jun 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should mention -32768 to -32000 are reserved by JSON-RPC 2.0 for pre-defined errors, even if only the listed codes are currently in use.

@felixweinberger felixweinberger Jun 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, it's a fair point but I wonder if we want to essentially restate JSONRPC specification inside MCP?

That seems like a slippery slope potentially where we pull in every external definition (say, SSE, HTTP, JSONRPC).

Not sure if we have a general view on this, maybe @localden has a view here?

I'm happy to add the spec language pointing out the JSONRPC reserved range as an FYI here at the cost of duplicating JSONRPC itself a little here.

@PederHP PederHP Jun 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that we generally shouldn't restate JSON-RPC spec, but we're already doing so with the error codes in use. And the practical reason is to deter developers who might never read the JSON-RPC spec, but do read this one, from being clever and using a reserved error code (unknowingly). But it's not a big deal. Just think it could reduce the risk of exactly the kind of clever error tricks, that cause trouble down the line

for general protocol failures.

JSON-RPC 2.0 reserves the range `-32000` to `-32099` for implementation-defined
server errors. MCP partitions this range as follows:

- **`-32000` to `-32019` — legacy.** Codes in this sub-range were allocated by
implementations before this policy was introduced. New codes **MUST NOT** be
allocated in this sub-range, and new implementations **SHOULD NOT** use codes
from this sub-range at all. Apart from `-32002` (see below), receivers
**MUST NOT** assume any specific meaning for these codes.
- **`-32020` to `-32099` — reserved for the MCP specification.** Error codes
in this sub-range are defined exclusively by the MCP specification and
recorded in the [schema](/specification/draft/schema). Implementations
**MUST NOT** emit any code from this sub-range that is not defined by this
specification and **MUST** use defined codes only with their specified
meanings.

@localden localden Jun 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
specified meanings.

MCP defines the following error codes:

| Code | Name |
| -------- | ----------------------------------------------------------------------------------------------------- |
| `-32020` | [`HeaderMismatch`](/specification/draft/schema#headermismatcherror) |
| `-32021` | [`MissingRequiredClientCapability`](/specification/draft/schema#missingrequiredclientcapabilityerror) |
| `-32022` | [`UnsupportedProtocolVersion`](/specification/draft/schema#unsupportedprotocolversionerror) |

Codes defined by earlier protocol versions remain reserved and will not be
Comment thread
felixweinberger marked this conversation as resolved.
reused. Implementations of this protocol version **MUST NOT** emit these codes:

- `-32002` — resource not found (2025-11-25 and earlier; replaced by `-32602`).
Clients [**SHOULD** still
accept `-32002`](/specification/draft/server/resources#error-handling) from
servers implementing earlier versions.
- `-32042` — URL elicitation required (2025-11-25 only).

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

New error codes for purposes not defined by this specification **SHOULD** be
allocated outside the JSON-RPC reserved range (`-32768` to `-32000`); the
remainder of the integer space is available for application-defined errors.

### Notifications

[Notifications](/specification/draft/schema#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
Expand Down Expand Up @@ -318,7 +366,7 @@ A server **MUST NOT** rely on capabilities the client has not declared. If
processing a request requires a capability the client did not include in
`io.modelcontextprotocol/clientCapabilities`, the server **MUST** return a
[`MissingRequiredClientCapabilityError`](/specification/draft/schema#missingrequiredclientcapabilityerror)
(`-32003`) whose `data.requiredCapabilities` lists the missing capabilities. On
(`-32021`) whose `data.requiredCapabilities` lists the missing capabilities. On
HTTP, the response status **MUST** be `400 Bad Request`.

On notifications delivered via a [`subscriptions/listen`][subscriptions-listen] stream,
Expand Down
15 changes: 8 additions & 7 deletions docs/specification/draft/basic/transports/streamable-http.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@ that contains invalid characters (see [Value Encoding](#value-encoding)).
Any server that processes the message body **MUST** validate that encoded
header values, after decoding if Base64-encoded, match the corresponding
values in the request body. Servers **MUST** reject requests with a
`400 Bad Request` HTTP status and JSON-RPC error code `-32001`
`400 Bad Request` HTTP status and JSON-RPC error code `-32020`
(`HeaderMismatch`) if any validation fails.

| Scenario | Client Behavior | Server Behavior |
Expand Down Expand Up @@ -592,12 +592,13 @@ When rejecting a request due to header validation failure, servers **MUST**
return HTTP status `400 Bad Request` and **MUST** include a JSON-RPC error
response using the following error code:

| Code | Name | Description |
| -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-32001` | `HeaderMismatch` | The HTTP headers do not match the corresponding values in the request body, or required headers are missing/malformed. |
| Code | Name | Description |
| -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-32020` | [`HeaderMismatch`](/specification/draft/schema#headermismatcherror) | The HTTP headers do not match the corresponding values in the request body, or required headers are missing/malformed. |

This error code is in the JSON-RPC implementation-defined server error range
(`-32000` to `-32099`).
This error code is allocated from the sub-range the MCP specification
reserves for protocol-defined errors. See
[Error Codes](/specification/draft/basic/index#error-codes).

**Example error response:**

Expand All @@ -606,7 +607,7 @@ This error code is in the JSON-RPC implementation-defined server error range
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"code": -32020,
"message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/specification/draft/basic/versioning.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ listing the versions it does support:
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32004,
"code": -32022,
"message": "Unsupported protocol version",
"data": {
"supported": ["2026-07-28", "2025-11-25"],
Expand Down
7 changes: 7 additions & 0 deletions docs/specification/draft/changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,13 @@ the previous revision, [2025-11-25](/specification/2025-11-25).
request, so a server-initiated completion signal — and the identifier used to
correlate it — no longer fit the protocol. Servers needing to correlate an
elicitation across retries encode their own identifier in `requestState`.
12. Define an [error code allocation policy](/specification/draft/basic/index#error-codes)
partitioning the JSON-RPC server-error range: `-32000` to `-32019` remains
implementation-defined (existing SDK usage is grandfathered), `-32020` to `-32099` is
reserved for the MCP specification. Renumber the error codes introduced in this draft
accordingly — `HeaderMismatch` `-32001` → `-32020`, `MissingRequiredClientCapability`
`-32003` → `-32021`, `UnsupportedProtocolVersion` `-32004` → `-32022` — and add
`HeaderMismatchError` to the schema, which previously existed only in transport prose.

## Deprecated

Expand Down
Loading
Loading