modelcontextprotocol / modelcontextprotocol/python-sdk
Introduce typed error classes with metadata
Nobody has claimed this yet.
- 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) withfault,is_retryable,http_status_code,response_bodyMcpTransportErrorfor connection/network issuesMcpProtocolErrorfor invalid JSON-RPC responsesMcpAuthErrorfor 401/403 responses
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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