docs: write the rest of the tutorial — 26 chapters, every example tested

The previous commit built the rails (docs_src/ + `--8<--` includes +
tests/docs_src/ driving every example through the in-memory Client) and
proved them on three pages. This is the rest of the book on those rails.

New chapters:

- Tutorial: first-steps, structured-output, resources, prompts, context,
  handling-errors, lifespan, media, completions, elicitation, progress,
  logging
- Running your server: index (stdio/HTTP/CLI/settings), asgi
- The Client: index, callbacks, transports, protocol-versions
- Advanced: multi-round-trip, low-level-server, pagination, middleware,
  authorization, oauth-clients, session-groups, deprecated
- nav lists all of them; deploy-docs and the fence-lint test cover the
  new directories

Every page is built from complete example files in docs_src/<chapter>/
included with `--8<--`, plus a test module in tests/docs_src/ that drives
each example through `Client(mcp)` in memory and asserts what the prose
claims (633 tests, 100% branch coverage). tests/docs_src/test_shape.py
enforces the global invariants: no orphan example, no include without a
file, no private `mcp.*` import, no deprecated or retired API in anything
a reader copies.

Corrections to the existing pages that fell out of writing the rest:

- testing.md: `raise_exceptions=True` does not surface a failing tool's
  traceback (a tool exception is always an `is_error` result); on the
  default in-memory connection it stops a non-tool failure being
  sanitised to "Internal server error". Say so, scoped to that
  connection.
- first-steps.md: the three primitive capabilities are not derived from
  what you register — an empty MCPServer declares the identical three.
  Only optional capabilities follow registration; the page and its test
  now prove it.
- mkdocs.yml: nav titles match each page's H1.

Author: maxisbey

docs/advanced/authorization.md

@@ -0,0 +1,121 @@
+# Authorization
+
+Over Streamable HTTP your MCP server is an ordinary web service, and you protect it the way you protect any web service: with OAuth 2.1 bearer tokens.
+
+In OAuth terms, your server is a **resource server**. It never signs anyone in and it never issues a token. It does one thing: look at the `Authorization` header on each request and decide whether the token in it is good.
+
+## The three parties
+
+* The **authorization server** signs people in and issues access tokens. You don't write this — it's your identity provider (Auth0, Keycloak, Entra, your own).
+* The **resource server** is your MCP server. It verifies the token on every request.
+* The **client** discovers which authorization server you trust, gets a token from it, and sends it back to you as `Authorization: Bearer <token>`.
+
+That's the whole triangle. Everything on this page is the middle bullet.
+
+## A token verifier
+
+The SDK has no opinion about what a valid token looks like. You tell it, by implementing **`TokenVerifier`**:
+
+```python title="server.py" hl_lines="12-14 19-24"
+--8<-- "docs_src/authorization/tutorial001.py"
+```
+
+* `TokenVerifier` is a protocol with one async method. `verify_token` gets the raw token from the `Authorization` header and returns an **`AccessToken`** if it's valid, `None` if it isn't. There is nothing else to implement.
+* This one looks the token up in a table. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint. That code is yours; the SDK only calls it.
+* `token_verifier=` and `auth=` always travel together. Pass one without the other and `MCPServer(...)` raises a `ValueError` before it ever serves a request.
+
+`AuthSettings` is the public face of your resource server:
+
+* `issuer_url` — the authorization server that issues your tokens.
+* `resource_server_url` — the public URL of this MCP endpoint. It names *which* resource a token is for, and it's where the discovery document lives.
+* `required_scopes` — every token must carry all of them.
+
+!!! tip
+    `examples/servers/simple-auth/` in the SDK repository has an `IntrospectionTokenVerifier` that calls
+    a real authorization server's RFC 7662 endpoint. It's the shape most production verifiers take.
+
+## What you get over HTTP
+
+Authorization lives in HTTP headers, so it exists only on the HTTP transports. Run it on the one you deploy: `mcp.run(transport="streamable-http")` puts it on `http://127.0.0.1:8000/mcp`, and **Running your server** has the rest. The app now has two routes:
+
+```text
+/mcp
+/.well-known/oauth-protected-resource/mcp
+```
+
+You registered one tool. The second route is the SDK's.
+
+### Discovery
+
+`GET` that well-known path and you get **RFC 9728 Protected Resource Metadata**, built straight from your `AuthSettings`:
+
+```json
+{
+  "resource": "http://127.0.0.1:8000/mcp",
+  "authorization_servers": ["https://auth.example.com/"],
+  "scopes_supported": ["notes:read"],
+  "bearer_methods_supported": ["header"]
+}
+```
+
+This document is how a client that has never heard of your server finds its way in: it reads `authorization_servers` and goes there for a token. You wrote none of it.
+
+!!! check
+    Call `/mcp` with no token — or with one your verifier returned `None` for — and the request is
+    stopped at the door:
+
+    ```text
+    HTTP/1.1 401 Unauthorized
+    WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"
+
+    {"error": "invalid_token", "error_description": "Authentication required"}
+    ```
+
+    Nothing was parsed and no tool ran. And that `resource_metadata` pointer in `WWW-Authenticate` is
+    what makes discovery automatic: 401 → metadata document → authorization server → token → retry.
+
+!!! warning
+    None of this protects `stdio`. A pipe has no `Authorization` header, so `token_verifier` is never
+    consulted there — a `stdio` server's security boundary is the process that launched it. The same
+    goes for the in-memory `Client(mcp)` you use in tests: it connects straight to the server object
+    and skips the HTTP layer, authorization included.
+
+## The caller's identity
+
+Inside any handler, **`get_access_token()`** is the `AccessToken` your verifier returned for the current request:
+
+```python title="server.py" hl_lines="4 32-35"
+--8<-- "docs_src/authorization/tutorial002.py"
+```
+
+* It works in tools, resources, and prompts, and there is nothing to pass around — the auth middleware stores it in a context variable per request.
+* You get back the **same object your verifier built**: `client_id`, `scopes`, `subject`, `expires_at`, and any extra `claims` you attached. That's the hook for per-tool rules — read the scopes and refuse.
+* Outside an authenticated HTTP request it returns `None`. In-memory and over `stdio` it is always `None`.
+
+Call `whoami` with `Authorization: Bearer alice-token` and the model reads:
+
+```text
+alice (scopes: notes:read)
+```
+
+## The half the SDK doesn't do
+
+The SDK gives you the resource-server half: verify, advertise, refuse. It does not give you a login page, a consent screen, or a token.
+
+To watch all three parties move, run `examples/servers/simple-auth/` from the SDK repository — a small authorization server and a resource server set up exactly like this page — and then point `examples/clients/simple-auth-client/` at it for the full discovery-and-token dance.
+
+!!! info
+    There is a second constructor argument, `auth_server_provider=`, that embeds a full authorization
+    server inside your MCP server. It predates the AS/RS separation that the MCP authorization spec
+    is built around. New servers should not reach for it.
+
+## Recap
+
+* Over Streamable HTTP your server is an OAuth 2.1 **resource server**: it verifies tokens, it never issues them.
+* `TokenVerifier` is the whole integration surface — one async method, token in, `AccessToken | None` out.
+* `token_verifier=` and `auth=AuthSettings(issuer_url=..., resource_server_url=..., required_scopes=[...])` always travel together.
+* The SDK publishes RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource/...` and answers unauthenticated requests with a 401 whose `WWW-Authenticate` header points at it. That is the entire discovery story.
+* `get_access_token()` in any handler is who's calling.
+* Authorization is an HTTP concern. `stdio` and the in-memory client never see it.
+
+The other side of the handshake — a client that discovers your authorization server and fetches the token for you — is **OAuth clients**.

docs/advanced/deprecated.md

@@ -0,0 +1,91 @@
+# Deprecated features
+
+The 2026-07-28 spec retires five things. The SDK still implements every one of them, and every one of them now carries a **deprecation warning**.
+
+No other page in these docs will show them to you. This is that page: find your warning, read the row, build on the replacement.
+
+## What is deprecated
+
+| 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 that matter as ordinary tool arguments or resource URIs. |
+| **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 — **Multi-round-trip requests**. |
+| **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 — **Logging**. |
+| **`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. |
+| **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()` — **Progress**. |
+
+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 the two places a **server** sends a **request** to the **client**. That whole direction is what 2026-07-28 replaces with **Multi-round-trip requests**.
+* `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"*.
+
+## Deprecated is advisory
+
+Nothing breaks today.
+
+Every method above keeps working against any session that negotiated **2025-11-25 or earlier**. Pin `mode="legacy"` on the client and you get exactly the pre-2026 behaviour. There are no wire changes and capability negotiation is unchanged.
+
+What changes is that you get a visible warning the first time each one runs:
+
+```text
+MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
+```
+
+`MCPDeprecationWarning` subclasses `UserWarning`, **not** `DeprecationWarning`. That is deliberate: Python's default filter only shows `DeprecationWarning` in code run directly as `__main__`, which is how libraries deprecate things and nobody notices for two years. This one shows up everywhere, with no `-W` flag.
+
+!!! warning
+    "Advisory" stops at the wire. Sampling and roots are server→client *requests*, and a
+    2026-07-28 session has no channel to carry one. Call `ctx.session.create_message()`
+    inside a tool on a modern connection and the warning still fires — and then the send
+    fails with an error:
+
+    ```text
+    Cannot send 'sampling/createMessage': this transport context has no back-channel
+    for server-initiated requests.
+    ```
+
+    Two signals, in that order. The `MCPDeprecationWarning` fires the moment you call the
+    method, on any connection. The error is what comes back when the SDK then tries to
+    send. These two only work end-to-end on a `mode="legacy"` connection whose client
+    registered the matching callback.
+
+## Silencing the warning
+
+Don't, in new code.
+
+But a server you maintain that genuinely serves pre-2026 clients has every right to a quiet log. Filter the category before the first deprecated call runs:
+
+```python
+import warnings
+
+from mcp import MCPDeprecationWarning
+
+warnings.filterwarnings("ignore", category=MCPDeprecationWarning)
+```
+
+That is the whole API. There is no per-method switch, and you don't want one — the point of one category is that one line silences it and one line brings it back.
+
+!!! check
+    Run the filter the other way and you get a free regression test. Add
+    `"error::mcp.MCPDeprecationWarning"` to the `filterwarnings` setting in your pytest
+    configuration and the deprecated call **raises** instead of warning. A tool named
+    `old_log` that still calls `ctx.info()` stops passing and starts reporting:
+
+    ```text
+    Error executing tool old_log: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
+    ```
+
+    One line of pytest configuration, and a deprecated call can never sneak back into your
+    codebase without failing a test.
+
+## Recap
+
+* The 2026-07-28 spec deprecates **roots**, server-initiated **sampling**, and protocol **logging** (all SEP-2577), restricts **progress** to server→client, and removes **`ping`**.
+* The replacement column points you onward: **Multi-round-trip requests** for sampling, **Logging** for logging, **Progress** for progress. Roots needs no chapter — pass the paths as arguments — and `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.
+* `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.
+
+If a warning brought you here and a row in the table answered it, you are done — every other page in these docs teaches the current API.