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