docs: worked examples for ping and roots change notifications

Both are removed from the 2026-07-28 wire and only reachable through
decorated APIs, so they land on the deprecated-features page (the one
page whose tests allow the calls) as inline snippets whose claims are
restated and proved in test_deprecated.py. "`ping` is removed" runs
client.send_ping() and ctx.session.send_ping() on a legacy session and
shows the two different failures on a modern one. "Roots change
notifications" shows a legacy client sending
notifications/roots/list_changed and a low-level Server re-listing in
on_roots_list_changed, plus the silent drop without mode="legacy". Short
pointers from callbacks, sampling-and-roots, the low-level server page
and troubleshooting route readers there.

No-Verification-Needed: docs and tests only

Author: maxisbey

docs/advanced/low-level-server.md

@@ -175,7 +175,7 @@ ValueError: 'initialize' is handled by the server runner and cannot be overridde
 use Server.middleware to observe or wrap initialization
 ```
 
-The handshake belongs to the runner. `server/discover`, `ping`, and every other built-in are yours to replace.
+The handshake belongs to the runner. `server/discover`, `ping` (which only handshake-era peers still send), and every other built-in are yours to replace.
 
 !!! tip
     `Server.middleware`, mentioned in that error, wraps **every** inbound message, including `initialize`. If what you want is to observe or rewrite traffic rather than answer a new method, start at **[Middleware](middleware.md)**.
@@ -187,6 +187,7 @@ Each of these is one idea you now have the vocabulary for; each has its own page
 * `on_call_tool`, `on_get_prompt`, and `on_read_resource` may return an `InputRequiredResult` instead of their normal result to pause the call and ask the client for input; see **[Multi-round-trip requests](../handlers/multi-round-trip.md)**. True to this tier, nothing is installed for you: where `MCPServer` seals `requestState` by default, here the `request_state` you set crosses the wire exactly as written until you opt in with `server.middleware.append(RequestStateBoundary(RequestStateSecurity(keys=[...]), default_audience=server.name))`: one line (both names import from `mcp.server.request_state`) for the identical sealing and verification `MCPServer` performs (**[Protecting `requestState`](../handlers/multi-round-trip.md#protecting-requeststate)**).
 * `on_list_resources`, `on_read_resource`, `on_list_prompts`, `on_get_prompt`, `on_completion` are the same `(ctx, params) -> result` shape for the other primitives.
 * `on_subscriptions_listen` serves the 2026-07-28 `subscriptions/listen` stream. Pass a `ListenHandler` built over a `SubscriptionBus` and publish events to the bus from your other handlers; see **[Subscriptions](../handlers/subscriptions.md)** for the full composition.
+* `on_roots_list_changed=` receives `notifications/roots/list_changed` from a 2025-era client. It is deprecated with the rest of roots and passing it warns at construction; **[Deprecated features](../deprecated.md#roots-change-notifications)** runs it end to end.
 * `server.streamable_http_app()` returns the same Starlette app `MCPServer`'s does; deploy it the way **[Running your server](../run/index.md)** deploys any other ASGI app. There is no `server.run(transport=...)` down here: `server.run(read_stream, write_stream, server.create_initialization_options())` drives one connection over a pair of streams, and that one line is the whole story.
 
 ## Recap

docs/client/callbacks.md

@@ -129,6 +129,8 @@ You still need the callbacks to talk to servers that haven't moved. The signatur
 
 Pass them to `Client(...)` exactly like `elicitation_callback`.
 
+The `"listChanged": true` a roots callback declares is a promise to tell the server when your list changes. You keep it with `client.send_roots_list_changed()`, which only does anything on a `mode="legacy"` session and warns like the rest of the roots API; **[Deprecated features](../deprecated.md#roots-change-notifications)** shows both ends.
+
 ## The notification callbacks
 
 Two more. Neither declares anything.

docs/deprecated.md

@@ -8,17 +8,17 @@ The table below names each deprecated feature, why it is going away, and the rep
 
 | Deprecated | Why | What you do instead |
 |---|---|---|
-| **Roots**: `ctx.session.list_roots()`, `client.send_roots_list_changed()`, the `list_roots_callback=` you pass to `Client(...)` | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) retires the capability. | Take the paths as ordinary tool arguments or resource URIs, or embed a `ListRootsRequest` in an `InputRequiredResult` (see **[Multi-round-trip requests](handlers/multi-round-trip.md)**). |
+| **Roots**: `ctx.session.list_roots()`, `client.send_roots_list_changed()`, the `list_roots_callback=` you pass to `Client(...)`, the `on_roots_list_changed=` you pass to `Server(...)` | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) retires the capability. | Take the paths as ordinary tool arguments or resource URIs, or embed a `ListRootsRequest` in an `InputRequiredResult` (see **[Multi-round-trip requests](handlers/multi-round-trip.md)**). |
 | **Server-initiated sampling**: `ctx.session.create_message()`, the `sampling_callback=` you pass to `Client(...)` | SEP-2577 retires the capability. | Return `InputRequiredResult` and let the client retry the call (see **[Multi-round-trip requests](handlers/multi-round-trip.md)**). |
 | **Protocol logging**: `ctx.log()`, `ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`, `ctx.session.send_log_message()`, `client.set_logging_level()` | SEP-2577 retires the capability. Nothing in-protocol replaces it. | Ordinary `import logging` to stderr (see **[Logging](handlers/logging.md)**). |
-| **`ping`**: `client.send_ping()` | **Removed** from the protocol, not merely deprecated. There is no `ping` method in 2026-07-28. | Nothing. It only works against a `mode="legacy"` connection. |
+| **`ping`**: `client.send_ping()`, `ctx.session.send_ping()` | **Removed** from the protocol, not merely deprecated. There is no `ping` method in 2026-07-28. | Nothing. Both work only against a `mode="legacy"` connection, and only the client's warns. |
 | **Client->server progress**: `client.send_progress_notification()` | 2026-07-28 makes progress server->client only. | Nothing to send. Your *server* reports progress with `ctx.report_progress()` (see **[Progress](handlers/progress.md)**). |
 
 Three things fall out of that table:
 
 * Roots, sampling, and logging go together. One proposal, **SEP-2577**, deprecates all three capabilities at once.
 * Sampling and roots share a deeper problem: they are places a **server** sends a **request** to the **client**. That whole direction is what 2026-07-28 replaces with **[Multi-round-trip requests](handlers/multi-round-trip.md)**. It is the standalone RPC methods (`sampling/createMessage`, `roots/list`, and push-style `elicitation/create`) that are gone; the `CreateMessageRequest` / `ListRootsRequest` / `ElicitRequest` payload types survive, embedded in `InputRequiredResult.input_requests`, and on the client they hit the same callbacks.
-* `ping` is the odd one out. The protocol does not deprecate it, it removes it. The SDK method still warns (its message says *removed*, not *deprecated*) and calling it on a modern connection answers with *"Method not found"*.
+* `ping` is the odd one out. The protocol does not deprecate it, it removes it ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)), together with two single methods inside the deprecated capabilities: `logging/setLevel` and `notifications/roots/list_changed`. The client's `send_ping()` still warns, and a modern connection answers it with *"Method not found"*. **[`ping` is removed](#ping-is-removed)** and **[Roots change notifications](#roots-change-notifications)** below show `ping` and the roots notification on the one kind of session that still carries them.
 
 ## Deprecated is advisory
 
@@ -50,6 +50,154 @@ MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SE
     send. These two only work end-to-end on a `mode="legacy"` connection whose client
     registered the matching callback.
 
+## `ping` is removed
+
+A **ping** is an empty request either side sends to check that the other is still answering. It takes no arguments and its result is empty; the only information is that a result came back.
+
+The 2026-07-28 spec removes it, in both directions ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)). A modern connection has no channel for the server to send a request on, so a server's ping cannot be sent at all; in the other direction, any request that gets an answer has already proved the server is there. Beneath the protocol, whether the connection itself is healthy is the transport's business (HTTP keep-alive, SSE comments, whether the stdio process is still running), not a method's.
+
+Both SDK methods are still there for handshake-era sessions:
+
+```python title="client.py" hl_lines="11 16-17"
+from mcp import Client
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.tool()
+async def check_client(ctx: Context) -> str:
+    """A tool that still pings the client mid-call."""
+    await ctx.session.send_ping()
+    return "client answered"
+
+
+async def main() -> None:
+    async with Client(mcp, mode="legacy") as client:
+        await client.send_ping()
+        result = await client.call_tool("check_client", {})
+        print(client.protocol_version, result.structured_content)
+```
+
+* `ctx.session.send_ping()` is the server asking the client, from inside a handler. It carries no warning.
+* `mode="legacy"` runs the classic `initialize` handshake, so this is a `2025-11-25` session: the only kind either ping can cross.
+* `client.send_ping()` is the client asking the server, and it is the one that warns: `MCPDeprecationWarning` fires the moment you call it, on any connection.
+
+```text
+2025-11-25 {'result': 'client answered'}
+```
+
+Neither end registered a handler for the ping. `MCPServer` answers the client's and `Client` answers the server's, both with an `EmptyResult`: `{}` on the wire. (The low-level `Server` takes `on_ping=` if you want your own code to run when one arrives; only handshake-era peers ever reach it.)
+
+!!! check
+    Drop `mode="legacy"` and run it again. The connection lands on `2026-07-28`, and
+    `client.send_ping()` gives you two signals, in this order: the `MCPDeprecationWarning` the
+    moment you call it, then the server's answer to the request itself, raised as an `MCPError`:
+
+    ```text
+    MCPDeprecationWarning: ping is removed as of 2026-07-28; the method only works under mode='legacy'.
+    MCPError: Method not found
+    ```
+
+    The error's `data` field names the missing method: `'ping'`. The server answered; it is
+    telling you the method does not exist at the version you are speaking.
+
+    Delete the `client.send_ping()` line as well, so the script reaches `call_tool`, and the
+    failure moves to the server side. Nothing warns, because `ctx.session.send_ping()` carries no
+    deprecation, and nothing is sent, because a modern connection has no channel to carry a
+    request from the server. `call_tool` does not hand back an `is_error` result; it raises:
+
+    ```text
+    Cannot send 'ping': this transport context has no back-channel for server-initiated requests.
+    ```
+
+    In new code the fix for either failure is to delete the ping rather than pin
+    `mode="legacy"`: the `tools/call` and its result already showed that both ends were there.
+
+The server-side method keeps one use. If you hold a legacy `ServerSession` so you can notify that client later, sending a notification tells you nothing about whether it is still connected: one sent to a closed connection is dropped without an error. `await session.send_ping()` is a request, so it raises `MCPError` once the client has gone. There is no equivalent for a `2026-07-28` client: `send_ping()` on its session raises the no-back-channel error whether or not the client is still there.
+
+## Roots change notifications
+
+**Roots** are the workspace folders a client invites the server to work in. The server learns them by asking, with a `roots/list` request, and a 2025-era client can also announce that its list changed: it sends `notifications/roots/list_changed`, which carries no payload, and a server that cares responds by asking again.
+
+That exchange exists only on a handshake-era session. The 2026-07-28 spec deprecates the roots capability as a whole and removes this one notification outright, as it removes `ping`, because a modern server never holds a list that could go stale: it asks for roots at the moment it needs them, by returning the request inside its tool result (the `ListRoots()` dependency on **[Sampling and roots](handlers/sampling-and-roots.md)** does that for you). `MCPServer` has no hook for the notification for that reason, so the receiving end below is a low-level `Server`. What follows is for clients and servers that still talk to pre-2026 peers.
+
+Here are both ends in one module: a client that exposes a workspace and announces a new folder, and a server that keeps its own copy of the roots and refreshes it on every announcement:
+
+```python title="client.py" hl_lines="12 19 32 36"
+import anyio
+from pydantic import FileUrl
+
+from mcp import Client
+from mcp.client import ClientRequestContext
+from mcp.server import Server, ServerRequestContext
+from mcp.types import ListRootsResult, NotificationParams, Root
+
+workspace = [Root(uri=FileUrl("file:///home/ada/catalog"), name="catalog")]
+
+
+async def list_roots(context: ClientRequestContext) -> ListRootsResult:
+    return ListRootsResult(roots=workspace)
+
+
+async def open_folder(client: Client, uri: str, name: str) -> None:
+    """The user opened another folder: expose it, then tell the server."""
+    workspace.append(Root(uri=FileUrl(uri), name=name))
+    await client.send_roots_list_changed()
+
+
+workspace_folders: list[str] = []
+
+
+async def roots_changed(ctx: ServerRequestContext, params: NotificationParams | None) -> None:
+    """The client's roots changed: ask for the new list."""
+    result = await ctx.session.list_roots()
+    workspace_folders[:] = [str(root.uri) for root in result.roots]
+    print(workspace_folders)
+
+
+server = Server("Bookshop", on_roots_list_changed=roots_changed)
+
+
+async def main() -> None:
+    async with Client(server, mode="legacy", list_roots_callback=list_roots) as client:
+        await open_folder(client, "file:///home/ada/archive", "archive")
+        await anyio.sleep_forever()  # a host keeps its session open, and the server's roots/list arrives on it
+```
+
+* `list_roots` is the ordinary roots callback (**[Client callbacks](client/callbacks.md)** covers it). Registering it is what declares `"roots": {"listChanged": true}` in the handshake, and `listChanged` is precisely the promise to send this notification.
+* `open_folder` is what a host calls whenever the user adds a folder: update the list, then notify. A notification has no response, so the call returning means the frame left, not that the server has caught up.
+* `on_roots_list_changed=` sits with the other `on_*` handlers on **[the low-level Server](advanced/low-level-server.md)** and has the notification shape, `async (ctx, params) -> None`. `params` is empty: the client says *that* the list changed, never what it changed to.
+* The handler's job is to ask again. `ctx.session.list_roots()` sends `roots/list` back over the same session, the client's `list_roots` answers it, and `workspace_folders` is current. Like every server-to-client request it needs a back-channel, which a `stateless_http=True` deployment does not have (**[Serving legacy clients](run/legacy-clients.md)**).
+* `mode="legacy"` gives the notification somewhere to go: it forces the `initialize` handshake (**[Protocol versions](protocol-versions.md)**), and only a handshake-era session defines the method. `main()` then keeps the session open, as a real host does for as long as it runs; hang up straight after `open_folder` and the server's follow-up `roots/list` has nowhere to go.
+
+On the wire the notification is a method name and nothing else:
+
+```json
+{"jsonrpc": "2.0", "method": "notifications/roots/list_changed"}
+```
+
+Run `main()` and the server's handler prints the refreshed list a moment after `open_folder` returns:
+
+```text
+['file:///home/ada/catalog', 'file:///home/ada/archive']
+```
+
+Everything deprecated on the way warned with the same message: constructing `Server(...)` with `on_roots_list_changed=`, calling `send_roots_list_changed()`, and calling `ctx.session.list_roots()`.
+
+```text
+MCPDeprecationWarning: The roots capability is deprecated as of 2026-07-28 (SEP-2577).
+```
+
+!!! check
+    Drop `mode="legacy"` and run it again. The client now negotiates `2026-07-28` with the same
+    server. The client's warning fires exactly as before, `send_roots_list_changed()` returns
+    without error, and then nothing happens: `roots_changed` never runs and nothing is printed,
+    and nothing reaches the client to say so. The method is not part of that protocol version,
+    and a notification has no reply that could carry a refusal. If the announcement matters, the
+    connection has to be one you pinned with `mode="legacy"`.
+
 ## Silencing the warning
 
 Don't, in new code.
@@ -85,6 +233,8 @@ That is the whole API. There is no per-method switch, and you don't want one: th
 * The replacement column points you onward: **[Multi-round-trip requests](handlers/multi-round-trip.md)** for sampling and roots, **[Logging](handlers/logging.md)** for logging, **[Progress](handlers/progress.md)** for progress. `ping` needs nothing at all.
 * Deprecated is advisory: no wire changes, everything keeps working against pre-2026 sessions, and you get a visible `MCPDeprecationWarning` (a `UserWarning`, so it is on by default).
 * Sampling and roots additionally need a back-channel that a 2026-07-28 session does not have. On a modern connection they warn and then they raise.
+* `ping` is removed in both directions. Both SDK methods still round-trip on a `mode="legacy"` session (only the client's warns); on a modern connection the client's is answered *"Method not found"* and the server's raises the no-back-channel error.
+* A legacy client announces changed roots with `client.send_roots_list_changed()`; a low-level `Server(on_roots_list_changed=...)` handler receives it and requests `roots/list` again. At 2026-07-28 the notification does not exist: the call warns and goes nowhere.
 * `warnings.filterwarnings("ignore", category=MCPDeprecationWarning)` silences the whole category; `"error::mcp.MCPDeprecationWarning"` in pytest turns it into a test failure.
 * New code should not be built on any of these.
 

docs/handlers/sampling-and-roots.md

@@ -37,6 +37,8 @@ On the other side of the wire, the client answers both requests with the callbac
 
 `ctx.session.create_message(...)` and `ctx.session.list_roots()` still exist for code that drives the session directly. They only work where a back-channel exists (2025-era, non-stateless connections), and calling them raises a deprecation warning. The resolver markers above are the supported form: they pick the delivery from the negotiated version and don't warn.
 
+A 2025-era client can also announce that its roots changed. `MCPServer` has no hook for that notification, and a `ListRoots()` dependency asks afresh on every call, so there is nothing to refresh; the low-level `Server` handler that receives it is on **[Deprecated features](../deprecated.md#roots-change-notifications)**.
+
 ## Recap
 
 * Return `Sample(...)` or `ListRoots()` from a resolver; the tool receives the `CreateMessageResult` or `ListRootsResult` like any other dependency.