Document the client-side story for caching hints

The caching page covered only server authoring. Add a 'What the client
sees' section: the hints arrive as parsed ttl_ms/cache_scope fields on
every cacheable result, the SDK does not act on them, and the supported
path today is reading the fields and doing your own freshness and scope
bookkeeping. Covers the legacy-server case (absent fields show the
conservative model defaults) and the model_fields_set wire-presence
check, with a tested example.

Author: maxisbey

docs/advanced/caching.md

@@ -35,6 +35,22 @@ This is also the escape hatch for dynamics the constructor can't know: a handler
 
 One caveat on paginated lists: the protocol requires the **same `cacheScope` on every page** of one list. The constructor map satisfies that by construction — it's keyed by method, not by page. But a handler that overrides the scope itself owns that consistency: override it on *every* page, never only when a cursor is present, or page one and page two will disagree.
 
+## What the client sees
+
+On the client, the hints arrive as plain fields on every cacheable result — `ttl_ms` and `cache_scope`, already parsed:
+
+```python title="client.py" hl_lines="15"
+--8<-- "docs_src/caching/tutorial003.py"
+```
+
+The SDK parses; it does not (yet) act. There is no built-in response cache: calling `list_tools()` twice makes two round trips, whatever the TTL said. The spec makes honoring optional — a client that ignores the hints entirely is fully conformant — so until the SDK grows a response cache, the supported path is to read the fields and do your own bookkeeping:
+
+* **Freshness** is `now < t_received + ttl_ms / 1000`: record the clock when the response arrives, and treat the result as reusable until the TTL runs out. `ttl_ms == 0` means *immediately stale* — don't reuse it at all.
+* **Scope is a sharing rule, not a suggestion.** A `"private"` result may be reused only within the same authorization context — same access token, same cache. Never put `"private"` results in a cache shared across users.
+* **Notifications beat TTL.** If the server sends `list_changed` while your copy is still fresh, the copy is stale now — re-fetch.
+
+Against an **older server** (pre-2026 protocol), the fields are simply absent from the wire, and the models show their conservative defaults: `ttl_ms == 0`, `cache_scope == "private"` — stale and unshared, the right assumption for a server that declared nothing. If you need to distinguish "the server said 0" from "the server said nothing", check `"ttl_ms" in result.model_fields_set`: it's only set when the field actually arrived.
+
 ## Older clients
 
 Clients on pre-2026 protocol versions never see either field — the SDK strips them at serialization for those connections. Configure your hints once; there is nothing version-specific to write.
@@ -45,3 +61,4 @@ Clients on pre-2026 protocol versions never see either field — the SDK strips
 * `cache_hints={method: CacheHint(...)}` at construction (both `MCPServer` and `Server`) sets server-wide values per method.
 * A handler that sets the fields on its result overrides the map, per field.
 * `"public"` is a promise that the result is identical for every caller. It is not access control.
+* Clients read the hints as `result.ttl_ms` / `result.cache_scope` and own the caching decision themselves — the SDK has no built-in response cache yet.

docs_src/caching/tutorial003.py

@@ -0,0 +1,15 @@
+from mcp import Client
+from mcp.server import CacheHint, MCPServer
+
+mcp = MCPServer("Weather", cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")})
+
+
+@mcp.tool()
+def forecast(city: str) -> str:
+    return f"Sunny in {city}"
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        tools = await client.list_tools()
+        print(f"{len(tools.tools)} tools, fresh for {tools.ttl_ms / 1000:.0f}s, scope={tools.cache_scope}")

tests/docs_src/test_caching.py

@@ -5,7 +5,7 @@
 import pytest
 from inline_snapshot import snapshot
 
-from docs_src.caching import tutorial001, tutorial002
+from docs_src.caching import tutorial001, tutorial002, tutorial003
 from mcp import Client
 from mcp.server import CacheHint, MCPServer
 
@@ -53,3 +53,18 @@ async def test_the_handler_value_wins_over_the_map_per_field() -> None:
         tools = await client.list_tools()
     assert tools.ttl_ms == 1_000
     assert tools.cache_scope == "public"
+
+
+async def test_the_client_program_on_the_page_reads_the_hints(capsys: pytest.CaptureFixture[str]) -> None:
+    """tutorial003: `main()` is the literal client program on the page - the hints
+    arrive as parsed fields on the result."""
+    await tutorial003.main()
+    assert capsys.readouterr().out == "1 tools, fresh for 60s, scope=public\n"
+
+
+async def test_the_wire_presence_check_the_page_recommends_works() -> None:
+    """The page's claim: `"ttl_ms" in result.model_fields_set` distinguishes a
+    server that sent the field from one that said nothing (model defaults)."""
+    async with Client(tutorial003.mcp) as client:
+        tools = await client.list_tools()
+    assert "ttl_ms" in tools.model_fields_set