Address example-suite review findings

- legacy_elicitation (lowlevel): thread related_request_id through
  elicit_form/elicit_url so the request rides the originating POST's
  stream, and make elicitation ids unique per request.
- legacy_routing: complete the CORS recipe (allow_methods/allow_headers)
  in both server variants.
- Harness: HTTP-only stories exit with a friendly message instead of
  hanging when run without --http; drop the unused manifest smoke key;
  declare the tomli marker dependency on the examples package.
- Docs: one two-variant run recipe everywhere, index rows describe the
  real Python surface, and assorted README corrections.

Author: maxisbey

examples/README.md

@@ -13,6 +13,10 @@
   Exercises every server capability in one process.
 - [`mcpserver/`](mcpserver/) — single-file v1-era examples retained for the
   migration guide; superseded by `stories/` and slated for removal.
+- [`clients/`](clients/) and the remaining [`servers/`](servers/) directories
+  (`simple-*`, `sse-polling-demo`, `structured-output-lowlevel`) — standalone
+  v1-era projects still linked from `README.v2.md`; retained pending
+  consolidation into `stories/`.
 
 For real-world servers see the
 [servers repository](https://github.com/modelcontextprotocol/servers).

examples/pyproject.toml

@@ -3,7 +3,10 @@ name = "mcp-example-stories"
 version = "0.0.0"
 description = "Self-verifying example suite for the MCP Python SDK (dev-only, not published)"
 requires-python = ">=3.10"
-dependencies = ["mcp"]
+dependencies = [
+    "mcp",
+    "tomli>=2.0; python_version < '3.11'",
+]
 
 [build-system]
 requires = ["hatchling"]

examples/stories/README.md

@@ -120,7 +120,7 @@ opens with a banner saying what replaces it.
 | [`error_handling`](error_handling/) | `is_error` results vs `MCPError`; `ToolError` | current |
 | [`serve_one`](serve_one/) | building a `Connection` by hand and calling `serve_one` directly | current |
 | **— HTTP hosting —** | | |
-| [`stateless_legacy`](stateless_legacy/) | `streamable_http_app()` default posture; the one-liner deploy | current |
+| [`stateless_legacy`](stateless_legacy/) | `streamable_http_app(stateless_http=True)`; the one-liner deploy | current |
 | [`json_response`](json_response/) | `json_response=True` mode; raw 2026 POST envelope on the wire | current |
 | [`legacy_routing`](legacy_routing/) | `classify_inbound_request()` era routing in front of a sessionful 1.x deploy | current |
 | [`starlette_mount`](starlette_mount/) | mounting `streamable_http_app()` under a Starlette/FastAPI sub-path | current |

examples/stories/_harness.py

@@ -92,6 +92,11 @@ def run_client(main: Callable[..., Awaitable[None]]) -> None:
     targets = target_from_args(file)
     build_auth: AuthBuilder | None = globals_.get("build_auth")
     transport = "http" if "--http" in sys.argv else "stdio"
+    if cfg["server_export"] == "app" and transport != "http":
+        raise SystemExit(
+            f"{name} exports an ASGI app (no stdio entry point); start its server, then run:\n"
+            f"  python -m stories.{name}.client --http http://127.0.0.1:8000{cfg['mcp_path']}"
+        )
     # The era is an axis of the story matrix, so ``mode=`` is always passed explicitly
     # 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.

examples/stories/bearer_auth/README.md

@@ -19,9 +19,10 @@ uv run python -m stories.bearer_auth.server --port 8000 &
 # connect with the demo bearer token
 uv run python -m stories.bearer_auth.client --http http://127.0.0.1:8000/mcp
 
-# lowlevel-API variant of the same app
-uv run python -m stories.bearer_auth.server_lowlevel --port 8001 &
-uv run python -m stories.bearer_auth.client --http http://127.0.0.1:8001/mcp
+# lowlevel server variant — same port, so stop the first server
+kill %1
+uv run python -m stories.bearer_auth.server_lowlevel --port 8000 &
+uv run python -m stories.bearer_auth.client --http http://127.0.0.1:8000/mcp
 ```
 
 `Client(url)` has no `auth=` passthrough, so a target built from a bare URL

examples/stories/dual_era/README.md

@@ -14,7 +14,8 @@ stays era-agnostic.
 uv run python -m stories.dual_era.server --http --port 8000 &
 uv run python -m stories.dual_era.client --http http://127.0.0.1:8000/mcp
 
-# lowlevel server variant
+# lowlevel server variant — same port, so stop the first server
+kill %1
 uv run python -m stories.dual_era.server_lowlevel --http --port 8000 &
 uv run python -m stories.dual_era.client --http http://127.0.0.1:8000/mcp
 ```

examples/stories/json_response/README.md

@@ -59,5 +59,6 @@ curl -s http://127.0.0.1:8000/mcp \
 
 ## See also
 
-`stateless_legacy/` (the default posture), `legacy_routing/` (route by era at
-the entry), `streaming/` (progress that *is* delivered — over stdio/SSE).
+`stateless_legacy/` (the one-liner `stateless_http=True` deploy),
+`legacy_routing/` (route by era at the entry), `streaming/` (progress that *is*
+delivered — over stdio/SSE).

examples/stories/legacy_elicitation/client.py

@@ -7,8 +7,9 @@
 
 async def on_elicit(context: ClientRequestContext, params: types.ElicitRequestParams) -> types.ElicitResult:
     if isinstance(params, types.ElicitRequestURLParams):
-        # A real client would open params.url in a browser, then wait for the matching
-        # notifications/elicitation/complete before resolving.
+        # A real client would ask consent and open params.url in a browser, returning
+        # `accept` right away; the server's notifications/elicitation/complete arrives
+        # afterward (once the out-of-band flow finishes) for the client to correlate.
         assert params.url.startswith("https://example.com/")
         return types.ElicitResult(action="accept")
     assert "username" in params.requested_schema["properties"]

examples/stories/legacy_elicitation/server.py

@@ -24,7 +24,8 @@ async def register_user(ctx: Context) -> str:
 
     @mcp.tool(description="Link a third-party account by directing the user to a sign-in URL.")
     async def link_account(provider: str, ctx: Context) -> str:
-        elicitation_id = f"link-{provider}"
+        # elicitation_id must be unique per elicitation, not per provider — scope it to this request.
+        elicitation_id = f"link-{provider}-{ctx.request_context.request_id}"
         answer = await ctx.elicit_url(
             f"Sign in to {provider} to link your account",
             url=f"https://example.com/oauth/{provider}/authorize",

examples/stories/legacy_elicitation/server_lowlevel.py

@@ -39,19 +39,23 @@ async def list_tools(
 
     async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
         if params.name == "register_user":
-            answer = await ctx.session.elicit_form("Please provide your registration details:", REGISTRATION_SCHEMA)
+            answer = await ctx.session.elicit_form(
+                "Please provide your registration details:", REGISTRATION_SCHEMA, related_request_id=ctx.request_id
+            )
             if answer.action != "accept" or answer.content is None:
                 return types.CallToolResult(content=[types.TextContent(text=f"registration {answer.action}")])
             text = f"registered {answer.content['username']} (plan: {answer.content.get('plan') or 'free'})"
             return types.CallToolResult(content=[types.TextContent(text=text)])
 
         assert params.name == "link_account" and params.arguments is not None
         provider = params.arguments["provider"]
-        elicitation_id = f"link-{provider}"
+        # elicitation_id must be unique per elicitation, not per provider — scope it to this request.
+        elicitation_id = f"link-{provider}-{ctx.request_id}"
         answer = await ctx.session.elicit_url(
             f"Sign in to {provider} to link your account",
             url=f"https://example.com/oauth/{provider}/authorize",
             elicitation_id=elicitation_id,
+            related_request_id=ctx.request_id,
         )
         if answer.action != "accept":
             return types.CallToolResult(content=[types.TextContent(text=f"link {answer.action}")])