modelcontextprotocol / modelcontextprotocol/python-sdk

Introduce typed error classes with metadata

Open
#1,742 1 comment 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

breaking change enhancement P2 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing where the SDK currently exposes generic exceptions from httpx, anyio, and task groups. Define the scope and metadata requirements for the proposed McpError hierarchy, including fault attribution, retryability, HTTP status codes, and response bodies. Done means the design is resolved and the affected error paths consistently expose typed SDK-native errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.