docs: act on review feedback; fix the ASGI chapter's deployment story

Each review finding was verified against the SDK before changing anything.

- The ASGI chapter taught deployments that do not work as written. With no
  `transport_security=`, `streamable_http_app()` auto-enables DNS-rebinding
  protection that accepts only localhost Host/Origin headers, so anything
  served behind a real hostname was answered `421 Invalid Host header` (and
  the CORS example's own browser origin `403 Invalid Origin header`) before
  MCP ran. The browser example also granted none of the `Mcp-*` request
  headers, so a browser's preflight blocked every request after the first.
  The page gains a "Localhost only, until you say otherwise" section, the
  CORS example now carries `TransportSecuritySettings(...)` and
  `allow_headers`, and two new tests pin the rejection statuses and the
  documented browser scenario end to end (the latter fails against the old
  example).
- progress.md implied the in-memory timing (callbacks complete before
  `call_tool` returns) holds on every transport. It is guaranteed by
  construction in memory; on a wire dispatcher callbacks run as their own
  tasks and can outlive the call. The info box now says so and a new test
  pins the wire behaviour. The "Try it" sentence a reviewer challenged is
  correct as written for the connection it narrates, so it is unchanged.
- tools.md's `ToolAnnotations` example paired `idempotent_hint=True` with
  `read_only_hint=True`, which the spec defines as meaningful only for
  non-read-only tools; it now shows `open_world_hint=False` and the prose
  explains the rule. Its `hl_lines` was also off by one, the only misaligned
  range out of all 70 in the book.
- elicitation: the booking example re-validates the date the user accepts by
  sending it back through the tool, and the "Try it" names which of the
  page's two servers each step runs against.
- installation.md leads with the pinned install command (the unpinned one
  installs v1.x), adds `mcp-types` to "What gets installed", and reuses the
  pydantic bullet for what pydantic does now that the protocol types live in
  `mcp-types`. The README's install command is pinned the same way.
- The three tutorial closing pointers that did not follow the nav order
  (media, progress, logging) now hand off to the next chapter, and testing.md
  gains the missing final hand-off; all 31 closers were checked.
- testing.md no longer calls inline-snapshot optional while showing a test
  that imports it.

Author: maxisbey

README.v2.md

@@ -44,10 +44,10 @@ Python 3.10+.
 ## Installation
 
 ```bash
-uv add "mcp[cli]"          # or: pip install "mcp[cli]"
+uv add "mcp[cli]==2.0.0a2"          # or: pip install "mcp[cli]==2.0.0a2"
 ```
 
-While v2 is in pre-release you must pin the version explicitly: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Use `uv add "mcp[cli]==2.0.0a2"` (check [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release), and `uv run --with "mcp==2.0.0a2"` for one-off commands.
+The pin matters while v2 is in pre-release: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Check [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release, and use `uv run --with "mcp==2.0.0a2"` for one-off commands.
 
 ## A server in 15 lines
 

docs/installation.md

@@ -2,29 +2,25 @@
 
 The Python SDK is on PyPI as [`mcp`](https://pypi.org/project/mcp/). It requires **Python 3.10+**.
 
+These docs describe **v2**, which is in alpha, so the version pin is not optional yet:
+
 === "uv"
 
     ```bash
-    uv add "mcp[cli]"
+    uv add "mcp[cli]==2.0.0a2"
     ```
 
 === "pip"
 
     ```bash
-    pip install "mcp[cli]"
+    pip install "mcp[cli]==2.0.0a2"
     ```
 
-!!! warning "Pin the version while v2 is in alpha"
-    v2 is published as pre-releases (`2.0.0a2`), and installers never select a pre-release unless
-    you opt in, so a bare `uv add mcp` gives you the latest **v1.x** release, which these docs do
-    not describe.
-
-    Pin the newest alpha explicitly. Find it in the
-    [release history](https://pypi.org/project/mcp/#history):
-
-    ```bash
-    uv add "mcp[cli]==2.0.0a2"
-    ```
+!!! warning "Why the pin"
+    Installers never select a pre-release unless you name one, so an unpinned `uv add "mcp[cli]"`
+    gives you the latest **v1.x** release, which these docs do not describe. Check the
+    [release history](https://pypi.org/project/mcp/#history) for the newest alpha before you copy
+    the line above.
 
     The same applies to one-off commands: `uv run --with "mcp==2.0.0a2" ...`, not `uv run --with mcp ...`.
 
@@ -35,8 +31,9 @@ The Python SDK is on PyPI as [`mcp`](https://pypi.org/project/mcp/). It requires
 
 You don't need to know any of this to use the SDK, but if you're wondering what each dependency is for:
 
+* `mcp-types`: every protocol type (requests, results, content blocks) as its own package, versioned in lockstep with the SDK. Every `from mcp_types import ...` in these docs is this package.
 * [`anyio`](https://anyio.readthedocs.io/): the async runtime. The whole SDK is written against anyio, so it runs on either `asyncio` or `trio`.
-* [`pydantic`](https://docs.pydantic.dev/): every protocol type, all schema generation, and all validation.
+* [`pydantic`](https://docs.pydantic.dev/): what every `mcp_types` model is built on, plus all schema generation and validation.
 * [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/): server configuration via `MCP_*` environment variables and `.env` files.
 * [`httpx`](https://www.python-httpx.org/) and [`httpx-sse`](https://pypi.org/project/httpx-sse/): the HTTP client behind the Streamable HTTP and SSE *client* transports.
 * [`starlette`](https://www.starlette.io/), [`uvicorn`](https://www.uvicorn.org/), [`sse-starlette`](https://pypi.org/project/sse-starlette/), and [`python-multipart`](https://pypi.org/project/python-multipart/): the HTTP *server* transports.

docs/run/asgi.md

@@ -29,12 +29,53 @@ Run the app on its own (`uvicorn server:app`) and you never think about either.
 
 !!! tip
     `streamable_http_app()` takes the same keyword arguments as `mcp.run("streamable-http", ...)`,
-    minus `port`: the port belongs to whatever serves the app. `host` is still there, but it binds
-    nothing here; it only sets the DNS-rebinding-protection default. **Running your server** covers
-    the options themselves.
+    minus `port`: the port belongs to whatever serves the app. `host` is still accepted but binds
+    nothing here; the next section is what it actually controls. **Running your server** covers the
+    options themselves.
 
 `mcp.sse_app()` does the same for the superseded SSE transport.
 
+## Localhost only, until you say otherwise
+
+`streamable_http_app()` cannot know which hostname it will be served behind, so it assumes the
+safest answer: localhost. With no `transport_security=`, the app switches on **DNS-rebinding
+protection** and accepts a request only if its `Host` header is `127.0.0.1:<port>`,
+`localhost:<port>`, or `[::1]:<port>`, and only if its `Origin` header, when there is one, is the
+`http://` form of the same. For `uvicorn server:app` on your machine that is exactly what you want:
+it stops a malicious web page from driving your local server through a DNS name it rebound to
+`127.0.0.1`.
+
+It also means that **deployed behind a real hostname, the app rejects every request until you
+configure it**. The check runs before MCP does, the client sees only a generic transport error, and
+the reason is a single warning in the *server's* log:
+
+```text
+421 Misdirected Request    Invalid Host header      the Host is not in the allowlist
+403 Forbidden              Invalid Origin header    the Origin is not in the allowlist
+```
+
+`transport_security=` is how you configure it. Allowlist what you actually serve:
+
+```python
+from mcp.server.transport_security import TransportSecuritySettings
+
+security = TransportSecuritySettings(
+    allowed_hosts=["mcp.example.com", "mcp.example.com:*"],
+    allowed_origins=["https://app.example.com"],
+)
+app = mcp.streamable_http_app(transport_security=security)
+```
+
+* `allowed_hosts` entries are exact strings: `"mcp.example.com"` matches a bare `Host` header and
+  `"mcp.example.com:*"` matches any port. List both.
+* `allowed_origins` only matters for browsers (nothing else sends `Origin`). It is the server-side
+  twin of the CORS configuration below.
+* Behind a reverse proxy that already controls the `Host` header, switching the check off is the
+  honest configuration: `TransportSecuritySettings(enable_dns_rebinding_protection=False)`.
+* Passing a non-localhost `host=` (for example `host="mcp.example.com"`) does **not** allowlist that
+  hostname. It only stops the localhost default from arming the protection, which leaves every Host
+  and Origin accepted. Say what you mean with `transport_security=` instead.
+
 ## Mounting it
 
 The moment the MCP server is *part* of a bigger application, you put the app inside a `Mount`. And the moment you do that, the lifespan becomes your problem:
@@ -47,7 +88,7 @@ The moment the MCP server is *part* of a bigger application, you put the app ins
 * The `lifespan` function enters `mcp.session_manager.run()` for the lifetime of the **host** app. This is the line everyone forgets.
 * `mcp.session_manager` only exists *after* `streamable_http_app()` has been called. That is why the routes are built at module level and the manager is only touched inside the lifespan.
 
-Starlette's `Host` route works the same way: swap `Mount("/", ...)` for `Host("mcp.example.com", ...)` to route by hostname instead of by path. The lifespan rule does not change.
+Starlette's `Host` route works the same way: swap `Mount("/", ...)` for `Host("mcp.example.com", ...)` to route by hostname instead of by path. The lifespan rule does not change, and neither does the transport-security one. A `Host("mcp.example.com", ...)` route only ever receives requests addressed to that hostname, so without `allowed_hosts=["mcp.example.com", "mcp.example.com:*"]` it answers every one of them with a `421`.
 
 !!! warning "The host app owns the lifespan"
     `streamable_http_app()` wires `session_manager.run()` into the lifespan of the Starlette it
@@ -88,17 +129,16 @@ Now clients connect to `/notes`, not `/notes/mcp`.
 
 ## CORS for browser clients
 
-A browser-based client adds one hard requirement: it must be able to **read** the `Mcp-Session-Id` response header. Streamable HTTP returns the session ID there, and browsers hide response headers from JavaScript unless CORS exposes them by name.
-
-Wrap the host app in Starlette's `CORSMiddleware`:
+A browser-based client needs two permissions from you: to **send** its MCP request headers, and to **read** the one MCP sends back. Both are CORS configuration on the host app, and the transport-security allowlist above has to agree with it:
 
-```python title="server.py" hl_lines="28-35"
+```python title="server.py" hl_lines="27-30 33 35-49"
 --8<-- "docs_src/asgi/tutorial005.py"
 ```
 
-* `expose_headers=["Mcp-Session-Id"]` is the line that matters. Without it the browser receives the header and refuses to show it to your code, and the client can never make a second request.
+* `allow_headers` is the half everyone forgets. A browser **preflights** every MCP request, because `Content-Type: application/json` and the `Mcp-*` request headers are not on the CORS safelist, and a header the preflight doesn't grant is a request the browser never sends. (`allow_headers=["*"]` also works: Starlette answers a preflight with whatever it asked for.)
+* `expose_headers=["Mcp-Session-Id"]` is the read half. Streamable HTTP returns the session ID in that response header, and browsers hide response headers from JavaScript unless CORS exposes them by name. Without it the client can never make its second request.
+* `allow_origins` is your decision, not MCP's. Be precise, and mirror it in `allowed_origins=` above: the browser enforces CORS, but the server checks `Origin` itself, and an origin the transport doesn't trust gets a `403` even after a clean preflight.
 * `allow_methods` lists the three methods Streamable HTTP uses: `POST` to send messages, `GET` to open the server-to-client stream, `DELETE` to end the session.
-* `allow_origins` is your decision, not MCP's. Be precise here.
 
 ## Custom routes
 
@@ -120,11 +160,12 @@ Wrap the host app in Starlette's `CORSMiddleware`:
 ## Recap
 
 * `mcp.streamable_http_app()` returns a Starlette app with one route, `/mcp`. Any ASGI server can run it.
+* Out of the box the app answers only requests addressed to localhost. Deploying behind a real hostname means passing `transport_security=TransportSecuritySettings(...)`.
 * `Mount` (or `Host`) puts it inside a bigger Starlette or FastAPI app.
 * **Mounting disables the built-in lifespan.** The host app's lifespan must enter `mcp.session_manager.run()`, or the first request fails.
 * Several servers in one app means several mounts and one lifespan that enters every session manager.
 * `streamable_http_path="/"` moves the endpoint to the mount prefix itself.
-* Browser clients need CORS with `expose_headers=["Mcp-Session-Id"]`.
+* Browser clients need CORS: `allow_headers` for the `Mcp-*` request headers, `expose_headers=["Mcp-Session-Id"]` for the response.
 * `@mcp.custom_route()` adds plain, unauthenticated HTTP endpoints next to `/mcp`.
 
 Once the server is reachable at a real URL, **The Client** connects to it with that URL instead of a server object.

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.
+* `event_store`, `retry_interval`, `transport_security`: resumability and DNS-rebinding protection. They can wait, until you deploy somewhere other than localhost; **ASGI** covers `transport_security`.
 
 !!! warning
     Transport options go to `run()`, **not** to `MCPServer(...)`. The constructor describes what

docs/tutorial/elicitation.md

@@ -13,14 +13,15 @@ There are two modes:
 
 `ctx.elicit()` takes a message and a Pydantic model:
 
-```python title="server.py" hl_lines="9-11 20-23"
+```python title="server.py" hl_lines="9-11 20-23 25"
 --8<-- "docs_src/elicitation/tutorial001.py"
 ```
 
 * The **`Context`** parameter is what gives you `ctx.elicit`; any tool can take one. That object has its own chapter: **The Context**.
 * `AlternativeDate` is the **schema** of the answer you want.
 * The tool is `async def`. It has to be: it stops in the middle and waits for a person.
 * On any other date the tool returns straight away. It only asks when it has to.
+* The date the user accepts goes back through `book_table` itself. An answer is input like any other: an alternative that is also fully booked gets asked about again, not confirmed blind.
 
 ### What the client receives
 
@@ -113,7 +114,7 @@ Servers ask. Clients answer by passing an **`elicitation_callback`** to `Client(
 
 ### Try it
 
-Start `server.py` on Streamable HTTP (**Running your server** has the one-liner), then run the client's `main()` and ask `book_table` for Christmas day.
+Start the form-mode `server.py` (the first one on this page) on Streamable HTTP (**Running your server** has the one-liner), then run the client's `main()` and ask `book_table` for Christmas day.
 
 The callback prints the question it was sent:
 
@@ -127,7 +128,7 @@ It answers with `{"accept_alternative": True, "date": "2025-12-27"}`, and the to
 Booked a table for 2 on 2025-12-27.
 ```
 
-Call `pay_deposit` and the same callback takes the other branch: it prints the payment link and the tool comes back with *"Complete the payment in your browser."* One round trip, mid-call, in both directions.
+Now swap in the URL-mode `server.py` and point the same `main()` at `pay_deposit`: the same callback takes the other branch, prints the payment link, and the tool comes back with *"Complete the payment in your browser."* One round trip, mid-call, in both directions.
 
 !!! check
     Now remove `elicitation_callback=` from the `Client` and call `book_table` for Christmas day

docs/tutorial/logging.md

@@ -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: every request your server handles, traced and timed, in **Middleware**.
+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**.

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. What a tool can do *while it runs* (read the server's own resources, report progress, ask the user a question) lives on **The Context**.
+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**.

docs/tutorial/progress.md

@@ -52,8 +52,11 @@ The callback is an `async` function taking exactly what the server reported: `pr
 
 !!! info
     `Client(mcp)` connects straight to the server object, in memory, the same client the **Testing**
-    chapter is built on. Nothing here is a test-only shortcut: `progress_callback` is the same
-    parameter whatever transport the `Client` is using.
+    chapter is built on. `progress_callback` is the same parameter whatever transport the `Client`
+    uses; the *timing* you are about to see is the in-memory connection's. It runs your callback
+    inline, so every report lands before `call_tool` returns. Over a real transport the
+    notifications race the result, and a slow callback can still be running after `call_tool` has
+    returned.
 
 ### Try it
 
@@ -111,4 +114,4 @@ The callback receives `total=None`. A client can still show *activity* ("3 impor
 * No callback on the call means `report_progress` does nothing. Report unconditionally.
 * Omit `total` when you don't know it; the callback gets `None`.
 
-Progress is the running tool talking *at* the client. When it needs an answer *back*, that is **Elicitation**.
+Progress is what a running tool shows the *user*. The lines it logs for *you*, the person operating the server, are a different channel: **Logging** is next.

docs/tutorial/testing.md

@@ -29,9 +29,10 @@ To run the test below you'll need two extra (development) dependencies:
 !!! info
     These docs assume you already know [`pytest`](https://docs.pytest.org/en/stable/).
 
-    [`inline-snapshot`](https://15r10nk.github.io/inline-snapshot/latest/) is optional: it records
-    the output of a test as the `snapshot(...)` literal you see below, which makes a test that
-    asserts on a whole result object much faster to write. A plain `assert` works too.
+    [`inline-snapshot`](https://15r10nk.github.io/inline-snapshot/latest/) is what the test below
+    uses to assert on the whole result object in one line. It records the output of a test as the
+    `snapshot(...)` literal you see. If you'd rather not use it, drop the import and assert on the
+    fields you care about (`result.content[0].text == "3"`) like in any other test.
 
 Now the test:
 
@@ -100,3 +101,6 @@ Leave it on in tests. It has no meaning in production code.
 That one line is also why the rest of this tutorial can promise you that its 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
+transport, is **Running your server**.

docs/tutorial/tools.md

@@ -139,15 +139,17 @@ There is nothing else to configure.
 
 Everything the SDK infers, you can override in the decorator:
 
-```python title="server.py" hl_lines="7-10"
+```python title="server.py" hl_lines="8-11"
 --8<-- "docs_src/tools/tutorial005.py"
 ```
 
 * `title` is a human-readable name for UIs. Clients show *"Search the catalog"* instead of `search_books`.
 * `annotations` are behavioural **hints** for the client:
   * `read_only_hint=True`: this tool doesn't change anything.
-  * `idempotent_hint=True`: calling it twice is the same as calling it once.
-  * `destructive_hint=True`: this tool deletes or overwrites something.
+  * `open_world_hint=False`: it works on a closed set of things (this catalog), not the open web.
+  * The other two, `destructive_hint` and `idempotent_hint`, describe a tool that *writes*: may it
+    delete something, and is calling it twice the same as calling it once? The spec defines both
+    only for non-read-only tools, so they would say nothing on `search_books`.
 
 A well-behaved client uses them to decide things like *"do I need to ask the user before running this?"*. They are hints, not security. Never rely on a client honouring them.