Pin explicit anchors on every prose heading

Heading ids are now written into the docs source instead of derived from
the heading text, so links stay stable across rewording and across the
translated sites, and scripts/docs/check_anchors.py keeps it that way.
The ids match what the current site already renders. Also settles the
Streamable HTTP capitalisation the corpus used inconsistently.

Author: maxisbey

docs/advanced/apps.md

@@ -1,4 +1,4 @@
-# MCP Apps
+# MCP Apps {#mcp-apps}
 
 An **MCP App** is a tool with a face: alongside its data, the tool points at an HTML
 document the host renders as an interactive surface.
@@ -18,7 +18,7 @@ The SDK ships this as the built-in `Apps` extension (`io.modelcontextprotocol/ui
 If [Extensions](extensions.md) are new to you, skim that page first. One minute,
 then come back.
 
-## A clock with a face
+## A clock with a face {#a-clock-with-a-face}
 
 ```python title="server.py" hl_lines="19 22 30 32"
 --8<-- "docs_src/apps/tutorial001.py"
@@ -41,7 +41,7 @@ apps, use the official [`@modelcontextprotocol/ext-apps`](https://github.com/mod
 browser SDK inside your HTML. It gives you `ontoolresult`, `callServerTool`,
 `getHostContext`, and `onhostcontextchanged` instead of raw message events.
 
-## Graceful degradation
+## Graceful degradation {#graceful-degradation}
 
 Not every client renders apps. The spec is blunt about what that means for you:
 
@@ -66,7 +66,7 @@ client half of the negotiation, and the rich answer comes back.
     fallback text is useless, the tool is useless to every text-only client and to
     the model itself. Write the sentence.
 
-## Locking the iframe down
+## Locking the iframe down {#locking-the-iframe-down}
 
 The resource side carries the security metadata: what the iframe may load, which
 browser permissions it wants, how it would like to be framed:
@@ -102,7 +102,7 @@ may refuse. Feature-detect in your JS rather than assuming a grant.
     metadata has no slot for them, and hosts ignore them there. The SDK makes the
     mistake unrepresentable: `@apps.tool()` simply has no `csp` parameter.
 
-### Visibility
+### Visibility {#visibility}
 
 `visibility=["app"]` on a tool says "this exists for the iframe, not the model":
 
@@ -113,7 +113,7 @@ may refuse. Feature-detect in your JS rather than assuming a grant.
 Filtering is the **host's** job. Your server lists app-only tools in `tools/list`
 like any other; the host hides them from the model. Don't filter server-side.
 
-## The rules the SDK enforces
+## The rules the SDK enforces {#the-rules-the-sdk-enforces}
 
 All of these fail at startup, not in production:
 
@@ -130,7 +130,7 @@ All of these fail at startup, not in production:
 Neither the TypeScript ext-apps SDK nor FastMCP catches any of these today; we'd
 rather you find out before a host does.
 
-## Beyond inline HTML
+## Beyond inline HTML {#beyond-inline-html}
 
 `add_html_resource` covers the common case: a string of HTML. For anything else,
 HTML on disk or generated content, build the resource yourself and hand it over:
@@ -149,7 +149,7 @@ under any other MIME type is one no host will render.
     `@apps.tool(resource_uri="ui://x", meta={"ui/resourceUri": "ui://x"})`.
     The nested `ui` object is the spec shape; the flat key is on its way out.
 
-## See it run
+## See it run {#see-it-run}
 
 The `apps` story in `examples/stories/` is this page as a runnable pair: a server
 with a UI-bound clock tool and a client that negotiates Apps, reads the tool's

docs/advanced/extensions.md

@@ -1,4 +1,4 @@
-# Extensions
+# Extensions {#extensions}
 
 An **extension** is an opt-in bundle of MCP behaviour behind one identifier.
 
@@ -8,7 +8,7 @@ notifications. Each side advertises under its own `capabilities.extensions`, and
 changes for anyone who didn't ask for it. That is the contract ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)), and
 it has one golden rule: **extensions are off by default**.
 
-## Using an extension
+## Using an extension {#using-an-extension}
 
 Pass instances at construction:
 
@@ -30,11 +30,11 @@ The capability map rides `server/discover`, which is a **2026-07-28** path. A le
 the extension. Design for that: an extension *augments* a server, it must not be the
 only way the server is usable.
 
-## Writing your own
+## Writing your own {#writing-your-own}
 
 Subclass `Extension` and override only what you need. Every method has a default.
 
-### The identifier
+### The identifier {#the-identifier}
 
 ```python
 --8<-- "docs_src/extensions/tutorial002.py"
@@ -53,7 +53,7 @@ TypeError: Stamps.identifier must be a `vendor-prefix/name` string
 Use a domain you control as the prefix. `io.modelcontextprotocol/*` is for extensions
 specified by the MCP project itself.
 
-### Contributing tools
+### Contributing tools {#contributing-tools}
 
 The smallest useful extension is one tool and a settings map:
 
@@ -75,7 +75,7 @@ And `main()` is the proof, an in-memory client straight against `mcp`:
 --8<-- "docs_src/extensions/tutorial003.py"
 ```
 
-### Serving your own methods
+### Serving your own methods {#serving-your-own-methods}
 
 An extension can register **new request methods**: its own verbs, served next to the
 spec's:
@@ -105,7 +105,7 @@ runtime:
 * An empty `protocol_versions` set raises too: a method that can never be served
   is a bug, not a configuration.
 
-### The client side
+### The client side {#the-client-side}
 
 The same file's `main()` is the whole client story, both halves of it:
 
@@ -123,7 +123,7 @@ The same file's `main()` is the whole client story, both halves of it:
   only grows first-class methods for spec verbs. `send_request` accepts any
   `Request` subclass, so the vendor request passes as-is.
 
-### Intercepting `tools/call`
+### Intercepting `tools/call` {#intercepting-toolscall}
 
 The one interceptive hook. Override `intercept_tool_call` to observe, short-circuit,
 or veto a tool call:
@@ -152,7 +152,7 @@ or veto a tool call:
 The hook wraps `tools/call` and nothing else. For every-message concerns, use
 [Middleware](middleware.md). That is what it is for.
 
-## Using a client extension
+## Using a client extension {#using-a-client-extension}
 
 A **client extension** is the same contract from the consuming side: a bundle of
 client-side behaviour behind one identifier. Pass instances to
@@ -183,7 +183,7 @@ from mcp.client import advertise
 client = Client(mcp, extensions=[advertise("com.example/search")])
 ```
 
-## Writing a client extension
+## Writing a client extension {#writing-a-client-extension}
 
 Subclass `ClientExtension` and override only what you need. Three contribution
 kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
@@ -223,7 +223,7 @@ would reject. And when you want the claimed shape yourself instead of the resolv
 call `client.session.call_tool(..., allow_claimed=True)`; without that flag, a
 claimed shape reaching a session-tier caller raises `UnexpectedClaimedResult`.
 
-### Extension verbs
+### Extension verbs {#extension-verbs}
 
 An extension's own request methods need no client-side registration. A vendor request
 type subclasses `mcp.types.Request` and goes through `client.session.send_request`,
@@ -238,7 +238,7 @@ this for their verbs), the request type declares `name_param`:
 The session mirrors `params["jobId"]` into `Mcp-Name` on every send path, and a
 missing value fails loudly rather than silently omitting a required header.
 
-## What an extension cannot do
+## What an extension cannot do {#what-an-extension-cannot-do}
 
 The contribution surface is **closed** on purpose. On the server: settings, tools,
 resources, methods, one `tools/call` interceptor. On the client: settings, result

docs/advanced/index.md

@@ -1,4 +1,4 @@
-# Advanced
+# Advanced {#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

docs/advanced/low-level-server.md

@@ -1,4 +1,4 @@
-# The low-level Server
+# The low-level Server {#the-low-level-server}
 
 `@mcp.tool()` is a layer. Underneath it is a second server class, `Server`, that speaks raw MCP: you hand it the protocol objects and it puts them on the wire, unchanged.
 
@@ -10,7 +10,7 @@
 
 For everything else, stay on `MCPServer`.
 
-## The same tool, by hand
+## The same tool, by hand {#the-same-tool-by-hand}
 
 This is the `search_books` tool that **[Tools](../servers/tools.md)** writes in nine lines of `@mcp.tool()`, with the sugar removed:
 
@@ -29,7 +29,7 @@ Three things changed, and they are the whole low-level API:
 !!! info
     If you've used FastAPI, you already know this relationship. `MCPServer` is the decorators-and-type-hints layer; `Server` is the Starlette underneath. They are not rivals: `MCPServer` constructs a `Server` and registers handlers exactly like these on it.
 
-### Try it
+### Try it {#try-it}
 
 There is no Inspector for this one: `mcp dev` and `mcp run` only accept an `MCPServer`. The in-memory `Client` doesn't care; it takes a low-level `Server` exactly like it takes an `MCPServer`:
 
@@ -59,7 +59,7 @@ The same text the `@mcp.tool()` version produced. Two honest differences:
 * `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
+## Nothing is checked for you {#nothing-is-checked-for-you}
 
 `MCPServer` rejects a bad argument before your function ever runs, validating the call against the schema it generated (**[Tools](../servers/tools.md)**).
 
@@ -76,7 +76,7 @@ The same text the `@mcp.tool()` version produced. Two honest differences:
 
 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
+## Two tools, one handler {#two-tools-one-handler}
 
 `on_call_tool` is the single entry point for every tool on the server. You route on `params.name`:
 
@@ -87,7 +87,7 @@ That generalises. An exception raised from a low-level handler is **always** a p
 * `list_tools` advertises both. `call_tool` dispatches on the name.
 * The `else` branch matters: `Server` will happily forward a `tools/call` for a name you never listed straight into your handler. Raising there turns the call into the same `-32603` as above.
 
-## Structured output, by hand
+## Structured output, by hand {#structured-output-by-hand}
 
 Declare `output_schema` on the `Tool` and put `structured_content` on the result. Both are yours:
 
@@ -111,7 +111,7 @@ The `_meta` block is the server's identity stamp: the SDK adds it to every 2026-
 
 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
+## `_meta`: for the application, not the model {#\_meta-for-the-application-not-the-model}
 
 `content` is the part of the answer the model reads. `structured_content` is the same answer as typed data. `_meta` is the third channel: data that rides along with the result for the **client application**, without being part of the answer at all.
 
@@ -128,7 +128,7 @@ Use it for record IDs, trace IDs, anything your UI needs and your prompt doesn't
     `_meta` is a convention between you and the client application, not a guarantee about what reaches
     the model. The host decides what it renders. Never put a secret in any part of a tool result.
 
-## Capabilities follow your handlers
+## Capabilities follow your handlers {#capabilities-follow-your-handlers}
 
 A `Server` advertises exactly the method families you gave it handlers for. The `Bookshop` above passes `on_list_tools` and `on_call_tool` and nothing else, so a client connecting to it sees:
 
@@ -140,7 +140,7 @@ No `resources`, no `prompts`: there is nothing to back them. Pass `on_list_promp
 
 `MCPServer` always advertises tools, resources and prompts, whether you registered any or not, because its managers always exist. Down here the declaration *is* the constructor call.
 
-## The lifespan generic
+## The lifespan generic {#the-lifespan-generic}
 
 `Server` is generic in the type its lifespan yields. Annotate it once and the object is typed everywhere it surfaces:
 
@@ -154,7 +154,7 @@ No `resources`, no `prompts`: there is nothing to back them. Pass `on_list_promp
 
 Without a `lifespan=`, `ctx.lifespan_context` is an empty `dict`.
 
-## A method of your own
+## A method of your own {#a-method-of-your-own}
 
 The constructor covers the methods MCP defines. `add_request_handler` covers everything else:
 
@@ -180,7 +180,7 @@ The handshake belongs to the runner. `server/discover`, `ping`, and every other
 !!! tip
     `Server.middleware`, mentioned in that error, wraps **every** inbound message, including `initialize`. If what you want is to observe or rewrite traffic rather than answer a new method, start at **[Middleware](middleware.md)**.
 
-## The other handlers
+## The other handlers {#the-other-handlers}
 
 Each of these is one idea you now have the vocabulary for; each has its own page.
 
@@ -189,7 +189,7 @@ Each of these is one idea you now have the vocabulary for; each has its own page
 * `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
+## Recap {#recap}
 
 * The low-level `Server` takes its handlers as `on_*` **constructor parameters**; every handler is `async (ctx, params) -> result`.
 * You write the `input_schema` dict and you build the `CallToolResult`. Nothing is derived, wrapped, or validated for you.

docs/advanced/middleware.md

@@ -1,4 +1,4 @@
-# Middleware
+# Middleware {#middleware}
 
 A **middleware** is one async function that wraps every message your server receives.
 
@@ -14,7 +14,7 @@ You write it as `async (ctx, call_next)` and append it to `server.middleware`. T
 below uses the low-level `Server`; if `Server(name, on_call_tool=...)` is new to you, read
 **[The low-level Server](low-level-server.md)** first.
 
-## A timing middleware
+## A timing middleware {#a-timing-middleware}
 
 One server, one tool, one middleware that logs how long each message took:
 
@@ -31,7 +31,7 @@ One server, one tool, one middleware that logs how long each message took:
 * `server.middleware.append(...)` registers it. The list runs outermost-first, so
   `middleware[0]` is the one closest to the wire.
 
-### Try it
+### Try it {#try-it}
 
 Connect a client, list the tools, call one. Your log has **three** lines:
 
@@ -53,7 +53,7 @@ That is the point. Middleware wraps **every** inbound message:
 * Even a method the server has no handler for: `call_next` raises the
   `MCPError(-32601, "Method not found")` *through* your middleware on its way to the client.
 
-## What you can do inside one
+## What you can do inside one {#what-you-can-do-inside-one}
 
 In increasing order of how much you should hesitate:
 
@@ -88,7 +88,7 @@ In increasing order of how much you should hesitate:
     an elicitation) while handling `initialize` therefore **deadlocks the connection**: the
     response you are waiting for can never be read. Fire-and-forget notifications are fine.
 
-## The one middleware that ships on by default
+## The one middleware that ships on by default {#the-one-middleware-that-ships-on-by-default}
 
 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
@@ -101,7 +101,7 @@ don't think about it. It is a no-op until you install an exporter, and it has it
     the decoded message instead of the raw HTTP request. The two compose: Starlette middleware
     on `streamable_http_app()` sees HTTP; this sees MCP.
 
-## Recap
+## Recap {#recap}
 
 * A middleware is `async (ctx, call_next) -> result`, passed as `MCPServer(middleware=[...])` (or
   appended to `mcp.middleware`), and appended to `server.middleware` on the low-level `Server`.

docs/advanced/pagination.md

@@ -1,4 +1,4 @@
-# Pagination
+# Pagination {#pagination}
 
 Most servers never need this.
 
@@ -8,7 +8,7 @@ Pagination is for the server whose resource list is really a database: thousands
 
 `@mcp.resource()` has no hook for any of that. To page, you write the list handler yourself, on the **[low-level Server](low-level-server.md)**.
 
-## A server that pages
+## A server that pages {#a-server-that-pages}
 
 ```python title="server.py" hl_lines="12 15-16"
 --8<-- "docs_src/pagination/tutorial001.py"
@@ -24,7 +24,7 @@ Pagination is for the server whose resource list is really a database: thousands
     one-line resources can afford a page of 500; a list of fat prompt templates cannot.
     The client has no say in it, and that is by design.
 
-### Try it
+### Try it {#try-it}
 
 `Client(server)` connects to a low-level `Server` in memory exactly as it connects to an `MCPServer`.
 
@@ -34,7 +34,7 @@ Hand it back with `list_resources(cursor="10")` and the first resource is `book-
 
 The tenth page comes back with `next_cursor` set to `None`. Done.
 
-## The client loop
+## The client loop {#the-client-loop}
 
 Every `list_*` method on `Client` (`list_tools`, `list_resources`, `list_resource_templates`, `list_prompts`) takes a `cursor=` keyword. Draining a paged list is one `while True`:
 
@@ -50,7 +50,7 @@ Run its `main()` and it prints `100 resources`: ten pages of ten, stitched toget
 
 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
+## The three rules {#the-three-rules}
 
 **Cursors are opaque.** A client must never parse, build, or guess one. The only legal source of a cursor is the previous page's `next_cursor`, verbatim.
 
@@ -69,7 +69,7 @@ This is the same loop **[The Client](../client/index.md)** shows for every `list
 
     A cursor you didn't get from the server is a bug, not a feature request.
 
-## Recap
+## Recap {#recap}
 
 * `MCPServer` returns everything in one page. Pagination is opt-in, and you opt in on the low-level `Server`.
 * `on_list_resources` (and `on_list_tools`, `on_list_prompts`, `on_list_resource_templates`) receives `PaginatedRequestParams | None`; `params.cursor` is `None` for the first page.