Introduce typed error classes with metadata

[maxisbey]

Summary

Replace generic exceptions with SDK-native error classes that include useful metadata like fault attribution, retryability, and HTTP details.

Problem

The SDK currently raises generic exceptions from various layers (httpx, anyio, task groups) with no context about:

• Whether the error is retryable
• Who is at fault (client, server, network, protocol violation)
• HTTP status codes and response bodies (often discarded)

This makes it hard for users to build robust error handling.

Goal

A hierarchy of typed errors like:

• McpError (base) with fault, is_retryable, http_status_code, response_body
• McpTransportError for connection/network issues
• McpProtocolError for invalid JSON-RPC responses
• McpAuthError for 401/403 responses

---

_{AI Disclaimer}

[jack-elliot-doherty]

Hi. I have a narrow client-side case that fits this issue.

Stilla currently uses MCP Python SDK 1.28.1 from the v1 line. In that version, tool-result validation happens in ClientSession._validate_tool_result(). Upstream main contains the v2 code. In v2, the equivalent public method is ClientSession.validate_tool_result().

Both implementations raise plain RuntimeError for three tool-result contract failures:

• A tool declares an output schema but returns no structured content.
• The structured content does not match the output schema.
• The tool’s output schema is invalid.

A client has no public exception type that identifies these failures. Without one, it must use broad RuntimeError handling or rely on implementation details such as the error text. Our downstream integration currently inspects that text. We also use a contract test that fails if an SDK update changes it. A dedicated exception type would be safer.

Would you accept a small PR that adds a public exception for these cases, for example ToolResultValidationError, while keeping RuntimeError as its base class for existing callers?

The PR would:

• Raise the new type for these three paths.
• Keep the current error messages.
• Keep the underlying jsonschema exception as the cause or context where one exists.
• Update the relevant Raises: documentation and output-schema validation tests.
• Export the exception from the public API at the location that maintainers prefer.

I see that v1.x accepts only security fixes and critical bug fixes. Should I target main only, or would you also consider a separate v1.x backport?

I am asking before I start because the contribution guide says that new public APIs need discussion and that contributors must wait for maintainer feedback or a ready for work label.

AI disclosure: I used AI assistance to draft and fact-check this proposal. I reviewed it, and I will own the contribution and its follow-up.