docs: retitle hand-offs and link text to match the new nav

maxisbey · maxisbey · commit 63ba33df4928 · 2026-07-01T15:21:06.000Z
The pages chain into each other with end-of-page "Next: ..." hand-offs. Under the regrouped nav some of those pointed backward, or across a section boundary, or at a page by a title it no longer carries. Fix each one to hand off to the page that actually follows it in its section, or to the next section where it is the last page. Also: - "ASGI" (the page H1 and every link to it) becomes "Add to an existing app". The old title named a Python interface standard; the page's content is mounting into an existing Starlette/FastAPI app, the DNS-rebinding 421, and CORS -- none of which anyone finds under the word "ASGI". (#1798 is literally a user asking for a "Guide" to content that already exists on that page.) - The landing page and README stop calling the docs "the tutorial"; the section they named is now "Get started" and the body of the docs is a reference, not a course. - Three sentences that said "this tutorial" now say "these docs"; there is no longer a tutorial for them to be in. - A pre-existing factual error on completions.md is fixed while its closing line is retargeted: completions apply to prompt arguments and resource-template parameters, never to a tool's, but the sentence said "Suggestions help before a tool runs."
diff --git a/README.md b/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/tutorial/), 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/tutorial/) takes it from here.
 
 ## A client in 10 lines
 
diff --git a/docs/advanced/multi-round-trip.md b/docs/advanced/multi-round-trip.md
@@ -19,7 +19,7 @@ That's the whole protocol. Every leg is an ordinary request from the client to t
 
 ## The server side
 
-On `@mcp.tool()` you rarely build this by hand: declare a dependency that asks the user and the SDK returns the `InputRequiredResult` for you - that form is the **[Dependencies](../tutorial/dependencies.md)** tutorial. The two forms don't mix: a call has one `input_responses`/`request_state` channel, so a tool that uses `Resolve(...)` parameters cannot also return `InputRequiredResult` from its body. A declared `InputRequiredResult` return is rejected at registration (`InvalidSignature`), and an undeclared one fails the call at runtime. The manual form is the **low-level** `Server`, whose `on_call_tool` handler is allowed to return either result type:
+On `@mcp.tool()` you rarely build this by hand: declare a dependency that asks the user and the SDK returns the `InputRequiredResult` for you - that form is the **[Dependencies](../tutorial/dependencies.md)** page. The two forms don't mix: a call has one `input_responses`/`request_state` channel, so a tool that uses `Resolve(...)` parameters cannot also return `InputRequiredResult` from its body. A declared `InputRequiredResult` return is rejected at registration (`InvalidSignature`), and an undeclared one fails the call at runtime. The manual form is the **low-level** `Server`, whose `on_call_tool` handler is allowed to return either result type:
 
 ```python title="server.py" hl_lines="44-47"
 --8<-- "docs_src/mrtr/tutorial001.py"
diff --git a/docs/advanced/opentelemetry.md b/docs/advanced/opentelemetry.md
@@ -104,4 +104,4 @@ mcp._lowlevel_server.middleware[:] = [
   with no change to your server.
 * Client-to-server trace context propagates automatically when both sides run the SDK.
 
-Next, the thing that decides whether a request runs at all: **[Authorization](authorization.md)**.
+The thing that decides whether a request runs at all is **[Authorization](authorization.md)**.
diff --git a/docs/index.md b/docs/index.md
@@ -89,7 +89,7 @@ You wrote two Python functions with type hints and a docstring. The SDK does the
 
 ## Where to go next
 
-* The **[Tutorial](tutorial/index.md)** walks through everything a server can do, one small step at a time.
+* **[Get started](tutorial/index.md)** takes you from install to a working, tested server.
 * Migrating from v1? Start with the **[Migration Guide](migration.md)**.
 * Hunting for an exact signature? The **[API Reference](api/mcp/index.md)** is generated from the source.
 * Reading with an LLM? This documentation is also published in the [llms.txt](https://llmstxt.org/) format:
diff --git a/docs/run/asgi.md b/docs/run/asgi.md
@@ -1,4 +1,4 @@
-# ASGI
+# Add to an existing app
 
 `mcp.run("streamable-http")` starts a web server for you. Sometimes you don't want that: your MCP server is one piece of a larger web application, or you already have an ASGI deployment.
 
diff --git a/docs/run/index.md b/docs/run/index.md
@@ -67,7 +67,7 @@ Each transport has its own keyword arguments, all on `run()`:
 * `streamable_http_path`: where the MCP endpoint lives. Default `/mcp`.
 * `json_response=True`: answer with plain JSON instead of an SSE stream.
 * `stateless_http=True`: a fresh transport per request, no session tracking.
-* `event_store`, `retry_interval`, `transport_security`: resumability and DNS-rebinding protection. They can wait, until you deploy somewhere other than localhost; **[ASGI](asgi.md)** covers `transport_security`.
+* `event_store`, `retry_interval`, `transport_security`: resumability and DNS-rebinding protection. They can wait, until you deploy somewhere other than localhost; **[Add to an existing app](asgi.md)** covers `transport_security`.
 
 !!! warning
     Transport options go to `run()`, **not** to `MCPServer(...)`. The constructor describes what
@@ -78,7 +78,7 @@ Each transport has its own keyword arguments, all on `run()`:
     TypeError: MCPServer.__init__() got an unexpected keyword argument 'port'
     ```
 
-`run()` is the short road. The moment you need more (your server mounted inside an existing app, two servers in one process, CORS for browser clients), you build the ASGI app yourself and hand it to any ASGI host. That is **[ASGI](asgi.md)**.
+`run()` is the short road. The moment you need more (your server mounted inside an existing app, two servers in one process, CORS for browser clients), you build the ASGI app yourself and hand it to any ASGI host. That is **[Add to an existing app](asgi.md)**.
 
 ## Server settings
 
@@ -143,4 +143,4 @@ uv run mcp install server.py -v API_KEY=abc123 -f .env
 * `mcp dev` for the Inspector, `mcp run` to execute a file, `mcp install` for Claude Desktop, `mcp version` for the version.
 * The transport never changes what your server *is*: all three files on this page expose the identical tool.
 
-When `run()` itself is the limit (your server inside an app that already exists), the next step is **[ASGI](asgi.md)**.
+When `run()` itself is the limit (your server inside an app that already exists), the next step is **[Add to an existing app](asgi.md)**.
diff --git a/docs/tutorial/completions.md b/docs/tutorial/completions.md
@@ -122,4 +122,4 @@ Drop `context_arguments=` and the same call returns `[]`. The handler can't know
 * `context.arguments` holds the already-resolved values; the client supplies them as `context_arguments=`.
 * The `completions` capability appears the moment you register the handler. Without it, the request is `Method not found`.
 
-Suggestions help *before* a tool runs. To ask the user a question in the *middle* of one, you want **[Elicitation](elicitation.md)**.
+Suggestions help while the user is still *filling in* a prompt or template; to ask them a question in the *middle* of a tool call, you want **[Elicitation](elicitation.md)**. Next: everything a tool can return besides text, in **[Images, audio & icons](media.md)**.
diff --git a/docs/tutorial/dependencies.md b/docs/tutorial/dependencies.md
@@ -142,4 +142,4 @@ That's the right default for a precondition: no answer, no order. When declining
 * Bad graphs fail at registration with `InvalidSignature`, not mid-call.
 * Return `Elicit(message, Model)` to ask the user, only when you have to. Unwrapped annotations abort on decline; `ElicitationResult[T]` lets the tool branch.
 
-Next: what happens when your tool fails, and how to choose who finds out, in **[Handling errors](handling-errors.md)**.
+Next: state your server builds once at startup, and how a handler reaches it, in the **[Lifespan](lifespan.md)**.
diff --git a/docs/tutorial/elicitation.md b/docs/tutorial/elicitation.md
@@ -169,4 +169,4 @@ Now swap in the URL-mode `server.py` and point the same `main()` at `pay_deposit
 * The client answers with one `elicitation_callback`, branching on the params type; registering it is what declares the capability.
 * On a 2026-07-28 connection the server returns the question instead of pushing it; the same callback is fed by **[Multi-round-trip requests](../advanced/multi-round-trip.md)**.
 
-A tool that can ask is good. A tool that says how far along it is (**[Progress](progress.md)**) is next.
+Everything underneath that return — the retry loop, protecting `requestState`, driving it yourself — is **[Multi-round-trip requests](../advanced/multi-round-trip.md)**.
diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md
@@ -113,8 +113,8 @@ That dictionary is the server's half of the handshake:
 Notice what isn't there. `completions` (argument autocomplete for resource templates and prompts) needs a handler you write, this server doesn't have one, so the capability is absent and a well-behaved client won't ask. That's the rule for everything optional: register the thing and the capability appears; **[Completions](completions.md)** proves it.
 
 !!! info
-    `Client(mcp)` is the same in-memory client every example in this tutorial is tested with, and
-    it's how you'll test yours. It gets a whole chapter: **[Testing](testing.md)**.
+    `Client(mcp)` is the same in-memory client every example in these docs is tested with, and
+    it's how you'll test yours. It gets a whole page: **[Testing](testing.md)**.
 
 ## What you did not write
 
@@ -136,4 +136,4 @@ That ratio is the whole point of the SDK.
 * The server's **capabilities** are declared for you, and a client only asks for what a server declares.
 * `Client(mcp)` connects to the server object in memory: your test harness from day one.
 
-Each primitive now gets its own chapter, starting with the one the model drives: **[Tools](tools.md)**.
+Next: **[Testing](testing.md)** — one page, one in-memory client, and you're never guessing whether it works. Then each primitive gets its own page, starting with the one the model drives: **[Tools](tools.md)**.
diff --git a/docs/tutorial/handling-errors.md b/docs/tutorial/handling-errors.md
@@ -129,4 +129,4 @@ It means a whole class of `raise` statements you don't write: don't re-validate
 * Bad arguments are rejected against the schema before your function runs; you don't `raise` for those.
 * `from mcp import MCPError`; the error-code constants come from `mcp_types`.
 
-Errors handled. Next: the things your server sets up once, before the first call ever arrives, the **[Lifespan](lifespan.md)**.
+Errors handled. That is everything a server *exposes*. What every handler can read, and do back to the client while it runs, is the next section: **[Inside your handler](../handlers/index.md)**.
diff --git a/docs/tutorial/lifespan.md b/docs/tutorial/lifespan.md
@@ -99,4 +99,4 @@ Strip the server down to the lifecycle: give `Database` a `connected` flag, flip
 * `ctx: Context[AppContext]` makes that access fully typed in tools. Resources and prompts take the bare `Context`.
 * No `lifespan=` means an empty `dict`, never `None`.
 
-Next: tools that return more than text, **[Media](media.md)**.
+Next: a handler that stops mid-call to ask the user for something only they know, in **[Elicitation](elicitation.md)**.
diff --git a/docs/tutorial/logging.md b/docs/tutorial/logging.md
@@ -2,7 +2,7 @@
 
 Log from a tool the way you log from any other Python function: with the standard library.
 
-MCP has a protocol-level **logging capability**: a server could push its log messages to the client as notifications, through methods on the `Context` object. The 2026-07-28 revision of the spec **deprecates that capability and does not replace it**, so this tutorial doesn't teach it. The full list of what's deprecated and what to do instead is in **[Deprecated features](../advanced/deprecated.md)**.
+MCP has a protocol-level **logging capability**: a server could push its log messages to the client as notifications, through methods on the `Context` object. The 2026-07-28 revision of the spec **deprecates that capability and does not replace it**, so these docs don't teach it. The full list of what's deprecated and what to do instead is in **[Deprecated features](../advanced/deprecated.md)**.
 
 What you do instead is what you do in every other Python program: the standard library.
 
@@ -75,4 +75,4 @@ went to standard error: the terminal, not the wire.
 * Standard error is yours; stdout belongs to the protocol. Never `print()` in a stdio server.
 * `MCPServer(..., log_level="DEBUG")` sets the level, and a logging configuration you made first is left alone.
 
-Next: the in-memory client that has been running every example on these pages, and how to point it at your own server, in **[Testing](testing.md)**.
+Next: telling connected clients that something on your server changed — the tool list, a resource — with **[Subscriptions](../advanced/subscriptions.md)**.
diff --git a/docs/tutorial/media.md b/docs/tutorial/media.md
@@ -105,4 +105,4 @@ A tool's icons are on the `Tool` object from `tools/list`, a resource's on the `
 * An `Icon` is a pointer: a `src` URI plus optional `mime_type`, `sizes`, and `theme`.
 * `icons=[...]` works on the server, on tools, on resources, and on prompts, and clients find them on the matching objects.
 
-That is everything a tool can put *into* a result. Helping the user fill in a prompt's or a resource template's arguments *before* anything runs is **[Completions](completions.md)**.
+That is everything a tool can put *into* a result. What happens when a tool *fails* — and who should find out — is **[Handling errors](handling-errors.md)**.
diff --git a/docs/tutorial/prompts.md b/docs/tutorial/prompts.md
@@ -147,4 +147,4 @@ The `prompts/list` entry now carries everything a client needs to draw a good fo
 * `title=` and `Field(description=...)` are what a client puts in its UI.
 * A missing required argument fails the whole request. There is no per-prompt error result.
 
-Next up: the one extra parameter a tool, resource or prompt can ask the SDK for, **[The Context](context.md)**.
+Next up: server-side autocomplete for a prompt's (or a resource template's) arguments, in **[Completions](completions.md)**.
diff --git a/docs/tutorial/resources.md b/docs/tutorial/resources.md
@@ -138,4 +138,4 @@ A client can also **subscribe** to a resource and be notified when it changes; t
 * `str` becomes text, `bytes` becomes a base64 blob, anything else becomes JSON text. `mime_type=` is how you label it.
 * Tools are for the model to act. Resources are for the application to read.
 
-Next: the third primitive, the one a person picks from a menu, **[Prompts](prompts.md)**.
+The third primitive, the one a person picks from a menu, is **[Prompts](prompts.md)**.
diff --git a/docs/tutorial/testing.md b/docs/tutorial/testing.md
@@ -98,9 +98,9 @@ Leave it on in tests. It has no meaning in production code.
     there: a legacy connection never sanitises in the first place, and the flag re-raises the
     failure inside the server task instead of in your test.
 
-That one line is also why the rest of this tutorial can promise you that its examples work: every
+That one line is also why these docs can promise you that their examples work: every
 example file is exercised by the SDK's own test suite through exactly this client. You're using the
 same tool the SDK uses on itself.
 
-The tutorial ends here. Putting your tested server in front of a real client, over a real
+You have a working, tested server. Putting it in front of a real client, over a real
 transport, is **[Running your server](../run/index.md)**.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# ASGI`
	`1`	`+# Add to an existing app`
`2`	`2`
`3`	`3`	`mcp.run("streamable-http")` starts a web server for you. Sometimes you don't want that: your MCP server is one piece of a larger web application, or you already have an ASGI deployment.
`4`	`4`