Should McpClient normalize JSON-RPC errors across stdio and Streamable HTTP

[chidozieononiwu]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

We are adding Streamable HTTP coverage to the Azure MCP Server and found that unsupported MCP methods produce different client exceptions depending on transport when using C# MCP SDK 2.1.0:

stdio: McpProtocolException with McpErrorCode.MethodNotFound
Streamable HTTP: HttpRequestException with HTTP 404
The HTTP response appears to contain a valid JSON-RPC error envelope with error code -32601. We understand that SEP-2575 maps MethodNotFound to HTTP 404, and that the client currently preserves most 404 responses as HttpRequestException for backward compatibility.

Is this transport-dependent client behavior intentional and part of the expected public contract?

More generally:

Should callers catch both McpProtocolException and HttpRequestException for the same logical MCP error?
Should a valid JSON-RPC error envelope take precedence over the HTTP status when choosing the client exception?
Is there a documented mapping of server errors to client exceptions for stdio and Streamable HTTP?
Which error scenarios are intentionally transport-specific?
This affects how we write transport-agnostic error handling and tests. We want to ensure that accommodating this case does not hide other incorrectly handled scenarios.

[ryux1]

For C# SDK 2.1.0, the behavior you observed matches the current implementation, but it is an SDK compatibility choice rather than a transport-independent MCP contract.

StreamableHttpClientSessionTransport converts a parsed JSON-RPC error to McpProtocolException only when either:

• the HTTP status is 400; or
• the error code is one of the 2026 per-request metadata errors (HeaderMismatch, MissingRequiredClientCapability, or UnsupportedProtocolVersion).

Every other non-success status—including a 404 carrying -32601 MethodNotFound—continues through EnsureSuccessStatusCode... and becomes HttpRequestException. The source comment says this preserves compatibility with transport-level 404 behavior:
https://github.com/modelcontextprotocol/csharp-sdk/blob/main/src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

So, today:

1. A transport-agnostic caller must handle both exception types.
2. A valid JSON-RPC envelope does not universally take precedence over HTTP status in this SDK.
3. Do not translate every HTTP 404 into MethodNotFound in application code. On legacy Streamable HTTP, 404 can also mean an expired Mcp-Session-Id; it can additionally be an endpoint/router 404. Those cases are not logically equivalent.
4. HTTP authentication/authorization errors, generic non-400 4xx responses, 5xx responses, connection failures, and legacy session expiry are intentionally transport-level exceptions. JSON-RPC errors over stdio have no HTTP layer and surface as protocol exceptions.

SEP-2575 requires an unsupported 2026 RPC to use both HTTP 404 and JSON-RPC -32601, but it does not prescribe the .NET exception class:
https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2575-stateless-mcp.md

I do not see a complete public server-error-to-client-exception matrix in the current C# SDK docs. Given that the response is a valid addressed JSON-RPC error, normalizing it would make cross-transport callers simpler—but it would be a behavioral change and needs a narrowly scoped SDK issue/test that preserves the distinct session-expired and plain HTTP 404 paths. For Azure MCP Server tests on 2.1.0, I would assert both the exception type and the HTTP/JSON-RPC evidence per transport rather than collapsing all 404s into MethodNotFound.