Context
Upstream spec PR modelcontextprotocol/modelcontextprotocol#2907 ("Define error code allocation policy and renumber draft error codes") partitions the JSON-RPC -32000..-32099 implementation-defined range and renumbers the three error codes introduced in the 2026-07-28 draft so they stop colliding with existing SDK usage:
| Code |
Old (current) |
New (#2907) |
HeaderMismatch |
-32001 |
-32020 |
MissingRequiredClientCapability |
-32003 |
-32021 |
UnsupportedProtocolVersion |
-32004 |
-32022 |
The renumber is draft-only and non-breaking as long as it lands before the 2026-07-28 revision is ratified — none of these codes exist in a released spec version. The PR body explicitly lists "csharp-sdk constants (draft-gated)" as a post-merge follow-up.
This renumber also resolves a real collision in our HTTP transport: StreamableHttpHandler returns -32001 (HTTP 404) for the legacy stateful "Session not found" case, which currently overlaps draft HeaderMismatch -32001 (HTTP 400). Moving HeaderMismatch to -32020 removes that overlap.
What to change (once #2907 merges)
src/ModelContextProtocol.Core/McpErrorCode.cs: HeaderMismatch = -32020, MissingRequiredClientCapability = -32021, UnsupportedProtocolVersion = -32022.- Doc comments referencing the literal codes in
UnsupportedProtocolVersionException.cs, MissingRequiredClientCapabilityException.cs, and the -32001/-32003/-32004 comments in McpClientImpl.cs, StreamableHttpClientSessionTransport.cs, AutoDetectingClientSessionTransport.cs, McpSessionHandler.cs.
- The
IsModernServerError-style recognition set in StreamableHttpClientSessionTransport.cs (currently matches UnsupportedProtocolVersion/MissingRequiredClientCapability/HeaderMismatch) — values update automatically via the enum, but verify the comments.
- The legacy
-32001 "Session not found" usage at StreamableHttpHandler.cs:292 can stay as-is; it no longer collides once HeaderMismatch moves.
- Bump the conformance pin / re-validate once upstream conformance ships matching code expectations (see also the conformance code-expectation PRs the #2907 author lists as follow-ups).
Blocked on
- #2907 merging upstream. Until then we keep the current codes so we stay aligned with the published draft schema and the other Tier-1 SDKs.
Tracking follow-up to #1610.
Context
Upstream spec PR modelcontextprotocol/modelcontextprotocol#2907 ("Define error code allocation policy and renumber draft error codes") partitions the JSON-RPC
-32000..-32099implementation-defined range and renumbers the three error codes introduced in the2026-07-28draft so they stop colliding with existing SDK usage:HeaderMismatch-32001-32020MissingRequiredClientCapability-32003-32021UnsupportedProtocolVersion-32004-32022The renumber is draft-only and non-breaking as long as it lands before the
2026-07-28revision is ratified — none of these codes exist in a released spec version. The PR body explicitly lists "csharp-sdk constants (draft-gated)" as a post-merge follow-up.This renumber also resolves a real collision in our HTTP transport:
StreamableHttpHandlerreturns-32001(HTTP 404) for the legacy stateful "Session not found" case, which currently overlaps draftHeaderMismatch-32001(HTTP 400). MovingHeaderMismatchto-32020removes that overlap.What to change (once #2907 merges)
src/ModelContextProtocol.Core/McpErrorCode.cs:HeaderMismatch = -32020,MissingRequiredClientCapability = -32021,UnsupportedProtocolVersion = -32022.UnsupportedProtocolVersionException.cs,MissingRequiredClientCapabilityException.cs, and the-32001/-32003/-32004comments inMcpClientImpl.cs,StreamableHttpClientSessionTransport.cs,AutoDetectingClientSessionTransport.cs,McpSessionHandler.cs.IsModernServerError-style recognition set inStreamableHttpClientSessionTransport.cs(currently matchesUnsupportedProtocolVersion/MissingRequiredClientCapability/HeaderMismatch) — values update automatically via the enum, but verify the comments.-32001"Session not found" usage atStreamableHttpHandler.cs:292can stay as-is; it no longer collides onceHeaderMismatchmoves.Blocked on
Tracking follow-up to #1610.