Define error code allocation policy and renumber draft error codes#2907
Merged
Conversation
JSON-RPC 2.0 reserves -32000..-32099 for implementation-defined server errors, and existing SDKs already use the low end of that range (request timeouts, connection closed, session not found). The error codes introduced in this draft collided with that usage: -32001 (HeaderMismatch) is also used by SDKs for request timeouts and session-not-found responses. Partition the range instead: -32000..-32009 stays implementation-defined (existing usage grandfathered, no new codes), -32010..-32099 is reserved for the MCP specification, with allocations recorded in schema.ts and starting at -32020. Renumber the draft-introduced codes accordingly: - HeaderMismatch: -32001 -> -32020 - MissingRequiredClientCapability: -32003 -> -32021 - UnsupportedProtocolVersion: -32004 -> -32022 Also add HeaderMismatchError to the schema (it previously existed only in transport prose) with an example, and document the policy in the Error Codes section of the base protocol overview.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Simpler boundary: implementation-defined space is -32000..-32019, the MCP specification reserves -32020..-32099. Drops the reserved-but-unallocated buffer concept in favor of a single clean split.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
felixweinberger
requested review from
LucaButBoring,
guglielmo-san,
halter73 and
pja-ant
pja-ant
previously requested changes
Jun 12, 2026
Co-authored-by: Peter Alexander <pja@anthropic.com>
Co-authored-by: Peter Alexander <pja@anthropic.com>
Co-authored-by: Peter Alexander <pja@anthropic.com>
Per review feedback: the spec may want to standardize what clients receive for common local conditions (e.g. request timeouts) in the future, so the note no longer steers implementations away from numeric codes entirely.
guglielmo-san
approved these changes
Jun 12, 2026
maxisbey
approved these changes
Jun 12, 2026
localden
requested changes
Jun 13, 2026
| recorded in the [schema](/specification/draft/schema). Implementations | ||
| **MUST NOT** emit codes from this sub-range with meanings other than those | ||
| defined by the specification. | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| specified meanings. | |
…e-allocation # Conflicts: # docs/specification/draft/schema.mdx # schema/draft/examples/HeaderMismatchError/header-mismatch.json # schema/draft/schema.json
…e-allocation # Conflicts: # docs/specification/draft/changelog.mdx # docs/specification/draft/schema.mdx # schema/draft/schema.json
maxisbey
approved these changes
Jun 17, 2026
pja-ant
previously approved these changes
Jun 18, 2026
-32042 falls in the spec-reserved sub-range, not the legacy one, so it does not belong in that bullet's exception; it stays listed with the codes from earlier protocol versions below.
pja-ant
approved these changes
Jun 18, 2026
This was referenced Jun 18, 2026
chore: renumber draft error codes per modelcontextprotocol#2907
modelcontextprotocol/conformance#353
Merged
guglielmo-san
added a commit
to modelcontextprotocol/go-sdk
that referenced
this pull request
Jun 22, 2026
…ion (#1016) This PR updates the error codes to align with the updated specifications in modelcontextprotocol/modelcontextprotocol#2907 ErrServerClosing and ErrClientClosing are reverted to their 1.6.0 version codes, as they do not overlap anymore with the newly introduced error codes.
This was referenced Jun 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
10 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Partitions the JSON-RPC server-error range between implementations and the spec, and renumbers the error codes introduced in this draft so they no longer collide with existing SDK usage.
Motivation and Context
JSON-RPC 2.0 reserves
-32000..-32099for implementation-defined server errors, and our SDKs have long used the low end of that range for their own purposes:-32000/-32001are request-timeout/connection-closed in the TypeScript and Python SDKs,-32001is also "session not found" in the TypeScript and C# HTTP transports, and go-sdk uses-32001/-32005/-32006/-32007internally. The codes introduced in this draft (-32001HeaderMismatch via SEP-2243,-32003/-32004via SEP-2575/#2716) landed on top of that usage. SEP-2164 removed-32002from the spec citing exactly this reserved-range argument.Discussed with the Tier 1 SDK maintainers (Discord: https://discord.com/channels/1358869848138059966/1514317386570793060). The agreed approach:
-32000..-32019stays implementation-defined; existing SDK usage is grandfathered; no new codes there. Receivers must not assign cross-implementation semantics to these codes.-32020..-32099is reserved for the MCP specification, with every allocation recorded inschema.ts, allocated sequentially from-32020.Renumbering is draft-only — none of these codes exist in a released spec version, so this is non-breaking if it lands before 2026-07-28.
HeaderMismatch-32001-32020MissingRequiredClientCapability-32003-32021UnsupportedProtocolVersion-32004-32022HeaderMismatchErroris also added to the schema with a typed interface and example — it previously existed only in transport prose.Historical codes are documented as reserved-never-reused:
-32002(resource not found, ≤2025-11-25; clients still accept it per SEP-2164's compat note) and-32042(URL elicitation required, 2025-11-25 only — note it is in the released 2025-11-25schema.ts, tagged@internal).Follow-ups after merge: conformance pins for SEP-2243/SEP-2575 codes, go-sdk and csharp-sdk constants (both draft-gated; go-sdk can also undo its
ErrServerClosing/ErrClientClosingshuffle), inspector's-32099proxy code moves out of the reserved sub-range.How Has This Been Tested?
npm run check(schema TS/JSON/examples/MDX, docs format, links, SEPs) passes clean; schema artifacts regenerated vianpm run generate:schema.Breaking Changes
None against released versions — all renumbered codes are draft-only. Draft implementers (go-sdk, csharp-sdk, conformance) need to update constants.
Types of changes
Checklist
Additional context
The shift to
-32020+ (instead of-32010+ as floated on Discord) keeps the spec-reserved sub-range clear of Bedrock AgentCore's in-use-32001..-32011codes during their migration out of the reserved band.