docs: regroup the nav into topical sections

The docs render as one flat 15-chapter "Tutorial - User Guide" plus a
15-item "Advanced" grab-bag (whose sidebar heading is a dead label: it has
no index page), and the section a deploying user needs most, "Running your
server", has exactly one child, titled "ASGI".

Regroup the same 40 pages into sections a reader would actually scan for:

  Get started           install -> first server -> test it
  Servers               one page per thing a server exposes; Tools first
  Inside your handler   the Context, dependencies, and everything a
                        running handler can do
  Running your server   now also owns Authorization and OpenTelemetry
  Clients               now also owns OAuth, identity assertion,
                        connecting to multiple servers, and the cache
  Advanced              only the genuine escape hatches (5, was 15),
                        with a real, clickable index page

"Protocol versions" and "Deprecated features" become their own top-level
entries. The first is the one page that squarely explains the two protocol
eras and was buried as the last child of "The Client", where a server
author never looks. The second is the SEP-2577 retirement table, filed
dead last in "Advanced".

Not a single file moves. MkDocs nav sections, nav titles, and file paths
are three independent things, so this is an mkdocs.yml edit plus three
new ~200-word section index pages (docs/servers/, docs/handlers/,
docs/advanced/). Every existing URL, every `--8<--` include, and every
docs_src test is untouched, and Material's breadcrumbs follow the nav,
not the directory.

docs/tutorial/index.md is rewritten from a "how these docs are built"
meta page into the Get started doorway; its tested-examples promise is
kept. tests/test_examples.py gains the two new docs directories so their
fenced code blocks stay lint-covered, and AGENTS.md's description of how
the docs are organised is updated to match.

Author: maxisbey

AGENTS.md

@@ -138,9 +138,10 @@ rather than adding new standalone sections.
 ## Documentation
 
 When a change affects public API or user-visible behaviour, update the relevant
-page(s) under `docs/` in the same PR. Docs are organised by topic
-(`tutorial/`, `client/`, `run/`, `advanced/`) — find the page covering the
-feature you touched rather than adding a new one.
+page(s) under `docs/` in the same PR. Docs are organised by the `nav:` sections
+in `mkdocs.yml` (Get started, Servers, Inside your handler, Running your server,
+Clients, Advanced), not by the on-disk directory names — find the page covering
+the feature you touched in `mkdocs.yml` rather than adding a new one.
 
 ## Formatting & Type Checking
 

docs/advanced/index.md

@@ -0,0 +1,28 @@
+# Advanced
+
+Everything an ordinary server or client needs has a topical home in the sections above.
+This section is the escape hatches — the things you reach for when `MCPServer`'s
+convenience layer is in the way:
+
+* **[The low-level Server](low-level-server.md)** — the class `MCPServer` is built on.
+  Hand-written schemas, `on_*` handlers, nothing checked for you, and custom JSON-RPC
+  methods of your own.
+* **[Pagination](pagination.md)** and **[Middleware](middleware.md)** — two things you
+  can *only* do on the low-level `Server`.
+* **[Extensions](extensions.md)** and **[MCP Apps](apps.md)** — the protocol's
+  extension surface: compose extension packages into a server, or write your own.
+
+A few things you might reasonably look for here live where you'd actually use them
+instead:
+
+* **Authorization** is under **[Running your server](../run/index.md)** — you protect a
+  server where you deploy it.
+* **OAuth**, **identity assertion**, connecting to **multiple servers**, and the
+  response **cache** are all under **[Clients](../client/index.md)**.
+* **Multi-round-trip requests** and **Subscriptions** are under
+  **[Inside your handler](../handlers/index.md)** — both are things a handler *does*.
+* **URI templates** is under **[Servers](../servers/index.md)**, next to Resources.
+* **[Protocol versions](../client/protocol-versions.md)** and
+  **[Deprecated features](deprecated.md)** each have their own top-level page.
+
+If you're not sure whether you need this section, you don't.

docs/handlers/index.md

@@ -0,0 +1,27 @@
+# Inside your handler
+
+A handler's arguments come from the client. Everything *else* it can read, and
+everything it can do while it runs, is here.
+
+What it can read:
+
+* **[The Context](../tutorial/context.md)** — the one extra parameter any handler can
+  ask for: the live request, its headers, its session, and most of the verbs below.
+* **[Dependencies](../tutorial/dependencies.md)** — parameters the model never sees,
+  filled in by your own functions with `Resolve`.
+* **[Lifespan](../tutorial/lifespan.md)** — state your server builds once at startup,
+  and how a handler reaches it through the `Context`.
+
+What it can do while it runs:
+
+* Ask the user for more input — **[Elicitation](../tutorial/elicitation.md)**, and
+  **[Multi-round-trip requests](../advanced/multi-round-trip.md)**, the 2026-07-28
+  pattern that carries it.
+* Report **[Progress](../tutorial/progress.md)** on something slow.
+* Write logs — to standard error, for whoever operates the server — with
+  **[Logging](../tutorial/logging.md)**.
+* Tell subscribed clients that something changed —
+  **[Subscriptions](../advanced/subscriptions.md)**.
+
+If you haven't registered a handler yet, start with
+**[Tools](../tutorial/tools.md)** — every page here assumes you have one.

docs/servers/index.md

@@ -0,0 +1,30 @@
+# Servers
+
+An `MCPServer` exposes three primitives to a connected client. They differ by who
+decides to use them:
+
+* A **[tool](../tutorial/tools.md)** is an action the *model* picks and calls. This is
+  the page most people want first, and
+  **[Structured Output](../tutorial/structured-output.md)** is its reference companion:
+  everything about the shape of what a tool returns.
+* A **[resource](../tutorial/resources.md)** is read-only data the *application*
+  chooses to read. **[URI templates](../advanced/uri-templates.md)** is its reference
+  companion: the full addressing syntax and the path-safety rules.
+* A **[prompt](../tutorial/prompts.md)** is a message template a *person* invokes by
+  name, from a menu or a slash command.
+
+Around the three primitives, the rest of what a server declares:
+
+* **[Completions](../tutorial/completions.md)** — server-side autocomplete for prompt
+  and resource-template arguments.
+* **[Images, audio & icons](../tutorial/media.md)** — everything a tool can
+  return besides text, and the icons a client shows next to your server.
+* **[Handling errors](../tutorial/handling-errors.md)** — the difference between an
+  error the model can recover from and one it must never see.
+
+Every page here stands on its own; jump straight to the one you need. If you haven't
+built a server yet, start with **[First steps](../tutorial/first-steps.md)** instead.
+
+What happens *inside* the functions you register — the `Context`, dependency injection,
+asking the user for more input mid-call — is the next section,
+**[Inside your handler](../handlers/index.md)**.

docs/tutorial/index.md

@@ -1,8 +1,8 @@
-# Tutorial - User Guide
+# Get started
 
-This tutorial shows you how to use the MCP Python SDK, step by step.
-
-Each section gradually builds on the previous ones, but it's written so you can go straight to any specific section to solve a specific problem. It also works as a future reference: you can come back to exactly the part you need.
+New to MCP, or new to this SDK? Start here. These pages take you from nothing to a
+working, tested server: [install the SDK](../installation.md), build your
+[first server](first-steps.md), and [test it](testing.md) with an in-memory client.
 
 ## Run the code
 
@@ -18,7 +18,7 @@ It is **HIGHLY encouraged** that you write (or copy) the code, edit it, and run
 
 ## You will not be guessing
 
-Every example in this tutorial is a complete file under [`docs_src/`](https://github.com/modelcontextprotocol/python-sdk/tree/main/docs_src) in the SDK's own repository, and every one of them is exercised by the SDK's test suite through an **in-memory client**:
+Every example in these docs is a complete file under [`docs_src/`](https://github.com/modelcontextprotocol/python-sdk/tree/main/docs_src) in the SDK's own repository, and every one of them is exercised by the SDK's test suite through an **in-memory client**:
 
 ```python
 import pytest
@@ -38,14 +38,14 @@ No subprocess, no port, no transport. `Client(mcp)` connects to the server objec
 
 If a change to the SDK breaks an example on one of these pages, CI goes red before the page does. The code you read here is the code that runs.
 
-You'll use this yourself in the [Testing](testing.md) chapter; it's how you test your own servers, too.
-
-## Install the SDK
-
-If you haven't yet, [install the SDK](../installation.md) first.
+You'll use this yourself in [Testing](testing.md); it's how you test your own servers, too.
 
-## Advanced User Guide
+## Where to go next
 
-There is also an **Advanced User Guide** you can read after this one.
+Once you have a server running, the rest of these docs are a reference, not a course.
+Every page stands on its own — jump straight to what you need:
 
-It builds on this tutorial, uses the same concepts, and teaches you the extra things: the low-level `Server`, middleware, authorization, the 2026-07-28 protocol negotiation. But you should read this first: everything in the Advanced guide assumes you know the basics.
+* What a server exposes — tools, resources, prompts — is **[Servers](../servers/index.md)**.
+* What's available inside the functions you register is **[Inside your handler](../handlers/index.md)**.
+* Getting it in front of clients — stdio, HTTP, your existing FastAPI app — is **[Running your server](../run/index.md)**.
+* Building the other side, an application that *uses* MCP servers, is **[Clients](../client/index.md)**.

mkdocs.yml

@@ -12,48 +12,53 @@ site_url: https://py.sdk.modelcontextprotocol.io/v2/
 
 nav:
   - MCP Python SDK: index.md
-  - Installation: installation.md
-  - Tutorial - User Guide:
+  - Get started:
       - tutorial/index.md
+      - Installation: installation.md
       - First steps: tutorial/first-steps.md
+      - Testing: tutorial/testing.md
+  - Servers:
+      - servers/index.md
       - Tools: tutorial/tools.md
       - Structured Output: tutorial/structured-output.md
       - Resources: tutorial/resources.md
+      - URI templates: advanced/uri-templates.md
       - Prompts: tutorial/prompts.md
+      - Completions: tutorial/completions.md
+      - "Images, audio & icons": tutorial/media.md
+      - Handling errors: tutorial/handling-errors.md
+  - Inside your handler:
+      - handlers/index.md
       - The Context: tutorial/context.md
       - Dependencies: tutorial/dependencies.md
-      - Handling errors: tutorial/handling-errors.md
       - Lifespan: tutorial/lifespan.md
-      - Media: tutorial/media.md
-      - Completions: tutorial/completions.md
       - Elicitation: tutorial/elicitation.md
+      - Multi-round-trip requests: advanced/multi-round-trip.md
       - Progress: tutorial/progress.md
       - Logging: tutorial/logging.md
-      - Testing: tutorial/testing.md
+      - Subscriptions: advanced/subscriptions.md
   - Running your server:
       - run/index.md
-      - ASGI: run/asgi.md
-  - The Client:
+      - Add to an existing app: run/asgi.md
+      - Authorization: advanced/authorization.md
+      - OpenTelemetry: advanced/opentelemetry.md
+  - Clients:
       - client/index.md
-      - Client callbacks: client/callbacks.md
-      - Client transports: client/transports.md
-      - Protocol versions: client/protocol-versions.md
+      - Callbacks: client/callbacks.md
+      - Transports: client/transports.md
+      - OAuth: advanced/oauth-clients.md
+      - Identity assertion: advanced/identity-assertion.md
+      - Multiple servers: advanced/session-groups.md
+      - Caching: advanced/caching.md
+  - Protocol versions: client/protocol-versions.md
+  - Deprecated features: advanced/deprecated.md
   - Advanced:
-      - Multi-round-trip requests: advanced/multi-round-trip.md
+      - advanced/index.md
       - The low-level Server: advanced/low-level-server.md
-      - URI templates: advanced/uri-templates.md
       - Pagination: advanced/pagination.md
-      - Caching hints: advanced/caching.md
-      - Subscriptions: advanced/subscriptions.md
       - Middleware: advanced/middleware.md
       - Extensions: advanced/extensions.md
       - MCP Apps: advanced/apps.md
-      - OpenTelemetry: advanced/opentelemetry.md
-      - Authorization: advanced/authorization.md
-      - OAuth clients: advanced/oauth-clients.md
-      - Identity assertion: advanced/identity-assertion.md
-      - Session groups: advanced/session-groups.md
-      - Deprecated features: advanced/deprecated.md
   - Migration Guide: migration.md
   - API Reference: api/
 

tests/test_examples.py

@@ -104,6 +104,8 @@ async def test_desktop(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
             "docs/index.md",
             "docs/installation.md",
             "docs/tutorial",
+            "docs/servers",
+            "docs/handlers",
             "docs/run",
             "docs/client",
             "docs/advanced",