Motivation and Context

This SEP proposes formalizing MCP error semantics so clients, servers, and SDKs can identify the same protocol failure consistently across implementations.

I started looking into this while testing behavior across multiple MCP SDKs in different languages. The same logical failure can surface with different JSON-RPC error codes depending on the SDK or version,
which makes cross-SDK interoperability, client behavior, and conformance testing difficult.

I opened an earlier discussion about formalizing error codes here: #2212

That discussion did not get much traction at the time, so I paused the work before writing a SEP. I now think this is worth revisiting because interoperable error handling is important for MCP clients, SDKs, and future conformance tests.

Other mature ecosystems with many client libraries, server implementations, and SDKs have had to formalize their error semantics for the same reason: broad interoperability breaks down when every implementation invents or interprets errors differently.

• PostgreSQL uses stable SQLSTATE error classes and conditions, so applications can match errors programmatically instead of parsing messages.
• gRPC defines a shared status code model across language SDKs, making behavior predictable across clients and servers.
• Kubernetes pairs generic HTTP status codes with structured API-specific fields like reason, so clients can distinguish domain errors reliably.
• RFC 9457 Problem Details gives HTTP APIs a structured way to carry machine-readable problem types beyond the raw HTTP status.
• Stripe and Cloudflare similarly layer product-specific error codes on top of generic transport/status codes for retry, support, and client handling logic.

MCP currently relies mainly on JSON-RPC numeric error codes, but those are too coarse and have already drifted across SDKs. This SEP keeps JSON-RPC compatibility while adding a structured MCP-owned condition code in error.data, giving SDKs and clients a stable interoperability layer.

The SEP includes references and evidence from existing SDK behavior, along with prior-art patterns from other protocols and APIs. Please take a look and let me know whether this direction is worth pursuing.

How Has This Been Tested?

Breaking Changes

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context