Repository navigation
docs: clarify when Client(raise_exceptions=True) actually raises #3287
Description
Description
Client exposes raise_exceptions: bool = False with a code TODO asking when raise_exceptions=True actually raises:
https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/client.py (around the raise_exceptions field)
What's missing
There is no clear user-facing documentation of:
- Which failure modes are affected (in-process server exceptions vs transport/protocol errors)
- How this interacts with
ExceptionGroupwrapping fromasync with Client(...) - Recommended patterns vs catching
MCPErrorinside the context manager (asdocs/troubleshooting.mdalready teaches)
Proposed work
- Trace current behavior on
mainfor in-memory and HTTP clients - Document the real semantics in
docs/client/and/ordocs/troubleshooting.md - Add a small docs_src example and/or regression test if behavior is surprising
- Only change runtime behavior if docs reveal a clear bug; prefer docs-first
Related
- TODO(Marcelo) on
Client.raise_exceptionsinsrc/mcp/client/client.py - ClientSession Error Handling #1401 ClientSession Error Handling (different surface; has an open PR)
- troubleshooting ExceptionGroup guidance
Activity
HaoChiBao commentedon Aug 11, 2026
I'd like to take this docs-first clarification of
Client.raise_exceptions. Plan: trace current behavior onmain, document real semantics, add a small example/test only if needed, and avoid runtime changes unless a clear bug appears.I searched for open PRs/issues specifically about
Client.raise_exceptionsdocumentation and did not find an active duplicate (related error-handling issues like #1401 are a different surface and already have PRs).AI-assisted drafting disclosed; I will own the final write-up.
Ben-Home commentedon Aug 18, 2026