docs: restructure into topical sections and add the four most-asked-for pages

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
 

README.md

@@ -24,7 +24,7 @@
 
 **The documentation lives at <https://py.sdk.modelcontextprotocol.io/v2/>.**
 
-It has the full [tutorial](https://py.sdk.modelcontextprotocol.io/v2/tutorial/), the [API reference](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/).
+It has a [Get started guide](https://py.sdk.modelcontextprotocol.io/v2/get-started/), the [API reference](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/).
 
 ## What is MCP?
 
@@ -82,7 +82,7 @@ Call `add` with `a=1`, `b=2` and you get `3` back.
 
 Notice what you did **not** write: no JSON Schema (`a: int, b: int` _is_ the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.
 
-[The tutorial](https://py.sdk.modelcontextprotocol.io/v2/tutorial/) takes it from here.
+[Get started](https://py.sdk.modelcontextprotocol.io/v2/get-started/) takes it from here.
 
 ## A client in 10 lines
 

RELEASE.md

@@ -35,7 +35,7 @@ the publish job — `skip-existing` makes it skip whatever already landed. The
 
 1. Update the pre-release version examples in `README.md` and the docs
    (grep the outgoing version — the pins live in the README Installation
-   section, `docs/index.md`, and `docs/installation.md`) so the tagged
+   section, `docs/index.md`, `docs/get-started/installation.md`, and `docs/get-started/real-host.md`) so the tagged
    commit — and therefore the README PyPI publishes — names the version
    being released. When entering a new phase (alpha → beta → rc), update
    the banner wording too.

docs/advanced/index.md

@@ -0,0 +1,29 @@
+# Advanced
+
+Everything an ordinary server or client needs has a topical home in the sections above.
+This section is the escape hatches 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)** because 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)** because both are things a
+  handler *does*.
+* **URI templates** is under **[Servers](../servers/index.md)**, next to Resources.
+* **[Protocol versions](../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/advanced/low-level-server.md

@@ -12,7 +12,7 @@ For everything else, stay on `MCPServer`.
 
 ## The same tool, by hand
 
-This is `search_books` from **[Tools](../tutorial/tools.md)** (the nine-line `@mcp.tool()` file) with the sugar removed:
+This is the `search_books` tool that **[Tools](../servers/tools.md)** writes in nine lines of `@mcp.tool()`, with the sugar removed:
 
 ```python title="server.py" hl_lines="23 27 33"
 --8<-- "docs_src/lowlevel/tutorial001.py"
@@ -56,12 +56,12 @@ asyncio.run(main())
 
 The same text the `@mcp.tool()` version produced. Two honest differences:
 
-* `result.structured_content` is `None`. The high-level server wrapped your `-> str` into `{"result": ...}`; here nobody builds what you didn't build.
+* `result.structured_content` is `None`. The high-level server wraps a `-> str` into `{"result": ...}` for you; here nobody builds what you didn't build.
 * `list_tools` returns the schema **you** typed, character for character. The high-level version had `"title": "Query"` on every property and a `"title": "search_booksArguments"` at the root: Pydantic artifacts. Down here, if it's on the wire, you put it there.
 
 ## Nothing is checked for you
 
-In **[Tools](../tutorial/tools.md)** you saw a bad argument get rejected before your function ran. That was `MCPServer` validating the call against the schema it generated.
+`MCPServer` rejects a bad argument before your function ever runs, validating the call against the schema it generated (**[Tools](../servers/tools.md)**).
 
 `Server` does not do that. Your `input_schema` is *advertised* to the client; it is never *applied* to `params.arguments`.
 
@@ -72,9 +72,9 @@ In **[Tools](../tutorial/tools.md)** you saw a bad argument get rejected before
     MCPError: Internal server error
     ```
 
-    A JSON-RPC error, code `-32603`, with a deliberately generic message: the SDK won't leak your traceback to a remote caller. The model never finds out what it did wrong, so it can't retry. (In a test, `raise_exceptions=True` surfaces the real exception instead; see **[Testing](../tutorial/testing.md)**.)
+    A JSON-RPC error, code `-32603`, with a deliberately generic message: the SDK won't leak your traceback to a remote caller. The model never finds out what it did wrong, so it can't retry. (In a test, `raise_exceptions=True` surfaces the real exception instead; see **[Testing](../get-started/testing.md)**.)
 
-That generalises. An exception raised from a low-level handler is **always** a protocol error, never an `is_error=True` tool result. If you want the model to read the failure and recover, validate `params.arguments` yourself and return `CallToolResult(content=[TextContent(...)], is_error=True)`. The two kinds of failure are the subject of **[Handling errors](../tutorial/handling-errors.md)**.
+That generalises. An exception raised from a low-level handler is **always** a protocol error, never an `is_error=True` tool result. If you want the model to read the failure and recover, validate `params.arguments` yourself and return `CallToolResult(content=[TextContent(...)], is_error=True)`. The two kinds of failure are the subject of **[Handling errors](../servers/handling-errors.md)**.
 
 ## Two tools, one handler
 
@@ -106,7 +106,7 @@ Call it and the result carries both representations:
 }
 ```
 
-The server never compares the two fields. This SDK's `Client` does: return `structured_content` that doesn't satisfy the `output_schema` you declared and `call_tool` raises a `RuntimeError` that starts with `Invalid structured content returned by tool search_books` and goes on to quote the `jsonschema` failure. Promising a schema is cheap; keeping it is on you. The whole ladder of return types and schemas is in **[Structured Output](../tutorial/structured-output.md)**.
+The server never compares the two fields. This SDK's `Client` does: return `structured_content` that doesn't satisfy the `output_schema` you declared and `call_tool` raises a `RuntimeError` that starts with `Invalid structured content returned by tool search_books` and goes on to quote the `jsonschema` failure. Promising a schema is cheap; keeping it is on you. The whole ladder of return types and schemas is in **[Structured Output](../servers/structured-output.md)**.
 
 ## `_meta`: for the application, not the model
 
@@ -147,7 +147,7 @@ No `resources`, no `prompts`: there is nothing to back them. Pass `on_list_promp
 
 * The lifespan is a `Callable[[Server[Catalog]], AbstractAsyncContextManager[Catalog]]`; `@asynccontextmanager` on an `async` generator gives you exactly that.
 * Whatever it `yield`s becomes `ctx.lifespan_context`, and because the handlers are annotated `ServerRequestContext[Catalog]`, `.search(...)` autocompletes and type-checks.
-* It is entered once when the server starts and exited once when it stops. Startup, teardown, and `MCPServer`'s version of the same idea are in **[Lifespan](../tutorial/lifespan.md)**.
+* It is entered once when the server starts and exited once when it stops. Startup, teardown, and `MCPServer`'s version of the same idea are in **[Lifespan](../handlers/lifespan.md)**.
 
 Without a `lifespan=`, `ctx.lifespan_context` is an empty `dict`.
 
@@ -179,11 +179,11 @@ The handshake belongs to the runner. `server/discover`, `ping`, and every other
 
 ## The other handlers
 
-Each of these is one idea you now have the vocabulary for; each has its own chapter.
+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](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`](multi-round-trip.md#protecting-requeststate)**).
+* `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](subscriptions.md)** for the full composition.
+* `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.
 * `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/advanced/middleware.md

@@ -84,7 +84,7 @@ In increasing order of how much you should hesitate:
 The SDK ships exactly one middleware, and it is already on your server's list: the one that
 emits an OpenTelemetry span for every message. You don't append it, and most of the time you
 don't think about it. It is a no-op until you install an exporter, and it has its own page:
-**[OpenTelemetry](opentelemetry.md)**.
+**[OpenTelemetry](../run/opentelemetry.md)**.
 
 !!! info
     If you have written ASGI middleware, you already know this shape. Starlette's
@@ -101,8 +101,8 @@ don't think about it. It is a no-op until you install an exporter, and it has it
 * `ctx.request_id is None` is how you tell a notification from a request.
 * Raise instead of calling `call_next` to refuse one message; the connection survives.
 * The SDK's own OpenTelemetry tracing is a middleware too, already on the list. See
-  **[OpenTelemetry](opentelemetry.md)**.
+  **[OpenTelemetry](../run/opentelemetry.md)**.
 * The whole surface is provisional. Observe with it; don't build on it.
 
-That is everything that wraps a request. **[Authorization](authorization.md)** is what decides whether the request
+That is everything that wraps a request. **[Authorization](../run/authorization.md)** is what decides whether the request
 gets to run at all.

docs/advanced/pagination.md

@@ -48,7 +48,7 @@ Every `list_*` method on `Client` (`list_tools`, `list_resources`, `list_resourc
 
 Run its `main()` and it prints `100 resources`: ten pages of ten, stitched together by a loop that never knew there were ten pages.
 
-This is the same loop **[The Client](../client/index.md)** chapter showed you, and it costs nothing against a server that doesn't page: `next_cursor` is `None` on the first response and the loop runs once.
+This is the same loop **[The Client](../client/index.md)** shows for every `list_*` verb, and it costs nothing against a server that doesn't page: `next_cursor` is `None` on the first response and the loop runs once.
 
 ## The three rules
 

docs/advanced/caching.md → docs/client/caching.md

@@ -13,7 +13,7 @@ Out of the box every result says `ttlMs: 0, cacheScope: "private"`: immediately
 * The map is keyed by **method name**, and the six cacheable methods are the only legal keys. The parameter is typed `Mapping[CacheableMethod, CacheHint]`, so your editor autocompletes the keys and flags a typo before you run; anything that slips past the type checker raises at construction.
 * A method you don't mention keeps the defaults. The map is a set of overrides, not a manifest.
 * `CacheHint(ttl_ms=5_000)` left `scope` unset, so it stays `"private"`: five seconds of freshness, per caller. Scope and TTL are independent decisions.
-* `"server/discover"` is a legal key too, since the handshake result is cacheable like any list.
+* `"server/discover"` is a legal key too, since the discovery result is cacheable like any list.
 
 !!! warning
     `cacheScope: "public"` means *anyone* may be served your cached response. A shared
@@ -85,7 +85,7 @@ Cache keys also carry the **server's identity**: the URL string you dialed, with
 ### What the cache never does
 
 * **Session-tier calls bypass it.** `client.session.list_tools()` and friends always make the round trip; the cache lives on the `Client` verbs.
-* **`server/discover` stays out of it.** The discover result is delivered once, at connect, and never enters the response cache, even when it carries a `ttlMs`. If you persist one yourself to skip the reconnect probe ([`prior_discover`](../client/protocol-versions.md#reconnecting-with-prior_discover)), its freshness is your bookkeeping: `DiscoverResult` carries `ttl_ms` and `cache_scope`, already parsed, for exactly that purpose.
+* **`server/discover` stays out of it.** The discover result is delivered once, at connect, and never enters the response cache, even when it carries a `ttlMs`. If you persist one yourself to skip the reconnect probe ([`prior_discover`](../protocol-versions.md#reconnecting-with-prior_discover)), its freshness is your bookkeeping: `DiscoverResult` carries `ttl_ms` and `cache_scope`, already parsed, for exactly that purpose.
 * **Continuation pages are never cached.** Only cursor-less calls participate. A continuation page rejected for an expired cursor does *evict* the cached listing, because the listing changed under it.
 * **Multi-round-trip reads are never cached.** A `read_resource` seeded with `input_responses`/`request_state`, or one that resolves through input rounds, never enters the cache (a spec MUST).
 * **Notification eviction needs notifications.** Eviction is only as good as the transport's delivery, and the modern in-process path (`Client(server)` with the default `mode="auto"`) does not deliver standalone notifications today.