[v2] docs: Client callbacks page doesn't say list_changed needs client.listen() #3845

What happened?

I ran into the client side of this in goose (aaif-goose/goose#13055), which never received tools/list_changed from 2026-07-28 servers because it doesn't open subscriptions/listen, so I checked how the Python SDK docs explain it.

The Client callbacks page calls message_handler "the catch-all: every server notification the session surfaces reaches it". By default (mode="auto"), Client(...) negotiates 2026-07-28 with any server that supports it. On such a connection, spec-compliant servers send the list_changed notifications and notifications/resources/updated only on a subscriptions/listen stream the client opened (migration guide); MCPServer drops the v1-style send_*_list_changed() calls there. So a client that registers only message_handler, as v1 clients did, gets no change notifications from those servers.

The page mentions client.listen() only to say its acknowledgment is consumed by the stream. It doesn't say change notifications need one, and doesn't link Subscriptions. The Caching page already has this pointer.

What did you expect?

Two sentences in the message_handler paragraph, after "…is consumed by that stream.", for example:

On a 2026-07-28 connection, change notifications (notifications/tools/list_changed, its prompts and resources siblings, and notifications/resources/updated) arrive only on a stream you open with client.listen(...). They reach message_handler from there, for the kinds that stream asked for; Subscriptions has the details.

Related: #3173 (open, last updated in July) rewrites the same paragraph but doesn't add this; the sentence could go there instead. I'd like to fix this myself (a one-sentence docs PR) if you take an outside PR for it.

AI disclosure: text drafted with AI assistance; the goose finding is mine, and I checked the behavior against src/mcp/client/session.py and the docs myself.

Code to reproduce

# Docs feedback: https://github.com/modelcontextprotocol/python-sdk/blob/77001c9/docs/client/callbacks.md#the-notification-callbacks

SDK version

v2.3.0; docs checked on main @ 77001c9

Area

Documentation