modelcontextprotocol / modelcontextprotocol/python-sdk

docs: clarify when Client(raise_exceptions=True) actually raises

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

Nobody has claimed this yet.

P3 v1 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

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:

  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
  • #1401 ClientSession Error Handling (different surface; has an open PR)
  • troubleshooting ExceptionGroup guidance

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 with the raise_exceptions TODO in src/mcp/client/client.py and trace current behavior for in-memory and HTTP clients, including ExceptionGroup handling from async with Client(...). Compare this with the guidance in docs/troubleshooting.md, then document the confirmed semantics in docs/client/ and/or docs/troubleshooting.md. Done means users can identify affected failures and choose between the recommended patterns and catching MCPError inside the context manager.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.