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:

1. Which failure modes are affected (in-process server exceptions vs transport/protocol errors)
2. How this interacts with ExceptionGroup wrapping from async with Client(...)
3. Recommended patterns vs catching MCPError inside the context manager (as docs/troubleshooting.md already teaches)

Proposed work

• Trace current behavior on main for in-memory and HTTP clients
• Document the real semantics in docs/client/ and/or docs/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_exceptions in src/mcp/client/client.py
• ClientSession Error Handling #1401 ClientSession Error Handling (different surface; has an open PR)
• troubleshooting ExceptionGroup guidance