Skip to content

Introduce typed error classes with metadata #1742

@maxisbey

Description

@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

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Moderate issues affecting some users, edge cases, potentially valuable featurebreaking changeWill break existing deployments when updated without changesenhancementRequest for a new feature that's not currently supportedv2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions