Address story-suite review findings

- error_handling: use the public e.data property and drop the now-covered
  pragma on MCPError.data; remove the README workaround note
- serve_one: SingleExchangeContext.send_raw_request raises
  NoBackChannelError(method) per the DispatchContext contract
- parallel_calls README: stop claiming progress-token demux on a shared
  wire (the example uses two separate connections)
- roots/sampling READMEs: align Caveats and See-also with the SEP-2577
  deprecation banner instead of pointing at MRTR as a successor
- starlette_mount README: correct the forgotten-lifespan failure mode
  (immediate 500 with RuntimeError, not a hang)
- _harness: pin era from the manifest when a story is single-era
- README spec links: /specification/2026-07-28/ -> /specification/draft/

Author: maxisbey

examples/stories/_harness.py

@@ -157,6 +157,8 @@ def run_client(main: Callable[..., Awaitable[None]]) -> None:
     # even though it often matches the ``Client`` default of "auto". stdio is legacy-only
     # until the SDK's stdio entry can negotiate the era, so only --http gets a modern arm.
     era = "modern" if transport == "http" and "--legacy" not in sys.argv else "legacy"
+    if cfg["era"] in ("legacy", "modern"):
+        era = cfg["era"]
     if cfg["era"] == "dual-in-body":
         # The story pins its connection modes inside ``main`` itself, so hand it "auto"
         # (the ``Client`` default) and let those in-body pins decide. A hard version pin

examples/stories/error_handling/README.md

@@ -41,8 +41,6 @@ uv run python -m stories.error_handling.client --http --server server_lowlevel
 - `MCPServer` prefixes the execution-error message with
   `"Error executing tool {name}: "`; build a `CallToolResult` directly from a
   lowlevel handler if you need verbatim control.
-- `client.py` reads `e.error.data` rather than `e.data`; the convenience
-  property carries a `no cover` pragma that `strict-no-cover` would trip.
 
 ## Spec
 

examples/stories/error_handling/client.py

@@ -29,7 +29,7 @@ async def main(target: Target, *, mode: str = "auto") -> None:
         except MCPError as e:
             assert e.code == INVALID_PARAMS
             assert e.message == "this tool is gated"
-            assert e.error.data == {"reason": "demo"}
+            assert e.data == {"reason": "demo"}
         else:
             raise AssertionError("expected MCPError for a protocol-level rejection")
 

examples/stories/json_response/README.md

@@ -60,8 +60,8 @@ kill "$SERVER_PID"
 
 ## Spec
 
-[Streamable HTTP — 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http)
-· [SEP-2243 standard headers](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#standard-request-headers)
+[Streamable HTTP — 2026-07-28](https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http)
+· [SEP-2243 standard headers](https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http#standard-request-headers)
 
 ## See also
 

examples/stories/parallel_calls/README.md

@@ -4,8 +4,9 @@ Two `Client`s connected to the same server, each with a `call_tool` in flight
 at once. The `meet` tool is a rendezvous: a handler signals its own arrival,
 then blocks until every named peer has arrived too — so neither call can return
 unless the server runs both handlers concurrently. Each caller's
-`progress_callback=` sees only the notifications for *its* request — the SDK
-demultiplexes by progress token, not by arrival order.
+`progress_callback=` sees only the notifications for *its* request — each
+`Client` is a separate connection, so there's no shared wire for them to cross
+on.
 
 ## Run it
 
@@ -36,8 +37,9 @@ subprocess per connection, so two clients there could never rendezvous.
   sequentially would never set the second event, so the client would time out —
   the timeout *is* the concurrency assertion. No sleeps.
 - **`client.py` — `progress_callback=` per call.** Each call passes its own
-  callback; `received == {"a": ["a"], "b": ["b"]}` proves the SDK routes
-  in-flight progress per request.
+  callback; `received == {"a": ["a"], "b": ["b"]}` shows each connection
+  delivered its own progress, and — combined with the rendezvous — that both
+  calls were genuinely in flight at once.
 - **`server_lowlevel.py`** — same wire contract on the lowlevel `Server`,
   reporting via `ctx.session.report_progress(...)`.
 

examples/stories/roots/README.md

@@ -38,12 +38,12 @@ uv run python -m stories.roots.client --http --legacy --server server_lowlevel
 ## Caveats
 
 - **Legacy-era only.** `roots/list` is a server-initiated request with no
-  2026-07-28 wire carrier until the multi-round-trip runtime lands
-  ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)), so
-  this story runs with `era = "legacy"` and the harness pins the handshake path.
+  2026-07-28 wire carrier, so this story runs with `era = "legacy"` and the
+  harness pins the handshake path.
 - `ctx.session.list_roots()` is `@deprecated`; the
-  `# pyright: ignore[reportDeprecated]` is deliberate. There is no
-  non-deprecated server-side path until the multi-round-trip runtime lands.
+  `# pyright: ignore[reportDeprecated]` is deliberate. The non-deprecated
+  replacement is to accept directory paths as ordinary tool parameters (see the
+  banner above) — there is no successor server→client call.
 - `ctx.session.*` is the interim 2-hop path; a later release will shorten it.
 - `notifications/roots/list_changed` is intentionally not shown — removed in
   2026-07-28 (SEP-2575) and deprecated on the legacy path.
@@ -54,5 +54,5 @@ uv run python -m stories.roots.client --http --legacy --server server_lowlevel
 
 ## See also
 
-`legacy_elicitation/`, `sampling/` — sibling server→client requests on the same
-MRTR migration path.
+`legacy_elicitation/`, `sampling/` — sibling stories that exercise the same
+legacy server→client request shape.

examples/stories/sampling/README.md

@@ -41,12 +41,12 @@ uv run python -m stories.sampling.client --http --legacy --server server_lowleve
 ## Caveats
 
 - **Legacy-era only.** `sampling/createMessage` is a server-initiated request
-  with no 2026-07-28 wire carrier until the multi-round-trip runtime lands
-  ([#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898)), so
-  this story runs with `era = "legacy"` and the harness pins the handshake path.
+  with no 2026-07-28 wire carrier, so this story runs with `era = "legacy"` and
+  the harness pins the handshake path.
 - `ctx.session.create_message()` is `@deprecated`; the
-  `# pyright: ignore[reportDeprecated]` is deliberate. There is no
-  non-deprecated server-side path until the multi-round-trip runtime lands.
+  `# pyright: ignore[reportDeprecated]` is deliberate. The non-deprecated
+  replacement is to call your LLM provider directly from the server (see the
+  banner above) — there is no successor server→client call.
 - `ctx.session.*` is the interim 2-hop path; a later release will shorten it.
 - `Client` has no `sampling_capabilities=` kwarg, so the `sampling.tools`
   sub-capability (tools-in-sampling) is unreachable from the high-level client.
@@ -58,5 +58,5 @@ uv run python -m stories.sampling.client --http --legacy --server server_lowleve
 
 ## See also
 
-`legacy_elicitation/`, `roots/` — sibling server→client requests on the same
-MRTR migration path.
+`legacy_elicitation/`, `roots/` — sibling stories that exercise the same legacy
+server→client request shape.

examples/stories/serve_one/README.md

@@ -52,7 +52,7 @@ uv run python -m stories.serve_one.client
 ## Spec
 
 [Architecture — lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
-· [2026 versioning — discover](https://modelcontextprotocol.io/specification/2026-07-28/server/discover)
+· [2026 versioning — discover](https://modelcontextprotocol.io/specification/draft/server/discover)
 
 ## See also
 

examples/stories/serve_one/server.py

@@ -21,6 +21,7 @@
 from mcp.server.lowlevel import Server
 from mcp.server.runner import serve_connection, serve_one  # deep-path import; shorter re-export planned
 from mcp.server.stdio import stdio_server
+from mcp.shared.exceptions import NoBackChannelError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.transport_context import TransportContext
 
@@ -58,7 +59,7 @@ class SingleExchangeContext:
     cancel_requested: anyio.Event = field(default_factory=anyio.Event)
 
     async def send_raw_request(self, method: str, params: Mapping[str, Any] | None, opts: Any = None) -> dict[str, Any]:
-        raise NotImplementedError  # no back-channel on the single-exchange path
+        raise NoBackChannelError(method)
 
     async def notify(self, method: str, params: Mapping[str, Any] | None, opts: Any = None) -> None:
         return None

examples/stories/starlette_mount/README.md

@@ -32,8 +32,9 @@ kill "$SERVER_PID"
   slash required — Starlette's `Mount` forwards `/api` as an empty path that
   the inner `/` route won't match).
 - `server.py` `lifespan` — `mcp.session_manager.run()` **must** be entered by
-  the parent app. Forget it and every MCP request hangs (the sub-app's own
-  lifespan never fires under `Mount`).
+  the parent app. Forget it and every MCP request fails immediately with a 500
+  (`RuntimeError: Task group is not initialized. Make sure to use run().`) —
+  the sub-app's own lifespan never fires under `Mount`.
 - `server.py` `Route("/health", ...)` — non-MCP routes live alongside the
   mount; FastAPI users do the same with `app.mount("/api", mcp_app)`.