P2: Session-group SSE connections still emit both deprecation warnings: one constructing SseServerParameters and one entering sse_client. Keep the targeted warning suppression active through enter_async_context(client) (or make sse_client warn when its context manager is constructed).

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/client/session_group.py, line 331:

<comment>Session-group SSE connections still emit both deprecation warnings: one constructing `SseServerParameters` and one entering `sse_client`. Keep the targeted warning suppression active through `enter_async_context(client)` (or make `sse_client` warn when its context manager is constructed).</comment>

<file context>
@@ -313,13 +325,17 @@ async def _establish_session(
+            elif isinstance(server_params, SseServerParameters):  # pyright: ignore[reportDeprecated]
+                # The caller already saw the deprecation warning when they built
+                # SseServerParameters; suppress the nested one from sse_client.
+                with warnings.catch_warnings():
+                    warnings.simplefilter("ignore", MCPDeprecationWarning)
+                    client = sse_client(  # pyright: ignore[reportDeprecated]
</file context>

P2: The suite-wide ignore masks this SDK's new deprecation warning at every call site, so future tests can accidentally introduce legacy HTTP+SSE usage without failing. The existing legacy-transport tests can keep a module- or test-level filterwarnings marker instead, which preserves the warning-as-error guard for all other code paths.

Check if this issue is valid — if so, understand the root cause and fix it. At pyproject.toml, line 271:

<comment>The suite-wide ignore masks this SDK's new deprecation warning at every call site, so future tests can accidentally introduce legacy HTTP+SSE usage without failing. The existing legacy-transport tests can keep a module- or test-level `filterwarnings` marker instead, which preserves the warning-as-error guard for all other code paths.</comment>

<file context>
@@ -266,6 +266,9 @@ filterwarnings = [
     "ignore:ping is removed as of 2026-07-28.*:mcp.MCPDeprecationWarning",
+    # SEP-2596 deprecates the HTTP+SSE transport; the SDK still ships it for
+    # servers/clients that haven't migrated, and the tests still exercise it.
+    "ignore:.*HTTP\\+SSE transport is deprecated as of 2025-03-26.*:mcp.MCPDeprecationWarning",
 ]
 
</file context>

P3: When the initial Streamable HTTP connection is refused, the recovery message still tells users to start the server with sse. That starts the legacy transport instead of the /mcp endpoint this client now targets, so following the error guidance leaves the retry unable to connect. Updating the fallback (and the module usage text) to streamable-http would keep the example runnable.

Check if this issue is valid — if so, understand the root cause and fix it. At examples/snippets/clients/url_elicitation_client.py, line 289:

<comment>When the initial Streamable HTTP connection is refused, the recovery message still tells users to start the server with `sse`. That starts the legacy transport instead of the `/mcp` endpoint this client now targets, so following the error guidance leaves the retry unable to connect. Updating the fallback (and the module usage text) to `streamable-http` would keep the example runnable.</comment>

<file context>
@@ -280,16 +280,16 @@ async def run_command_loop(session: ClientSession) -> None:
     print("=" * 60)
     print(f"\nConnecting to: {server_url}")
-    print("(Start server with: cd examples/snippets && uv run server elicitation sse)")
+    print("(Start server with: cd examples/snippets && uv run server elicitation streamable-http)")
 
     try:
</file context>

🟡 The decorator order on sse_client (@asynccontextmanager outermost, @deprecated inner) causes the runtime MCPDeprecationWarning to be attributed to CPython's contextlib.py instead of the user's call site, and the default warning filter then dedupes all call sites process-wide to a single warning. Swapping the two decorators (@deprecated outermost) restores correct call-site attribution; sse_client is the only @asynccontextmanager function in this PR carrying @deprecated — the other deprecated entry points attribute correctly.

What happens

Decorators apply bottom-up, so in src/mcp/client/sse.py the @deprecated wrapper wraps the raw async-generator function, and @asynccontextmanager wraps that. When a user calls sse_client(url), the call chain is: user frame → asynccontextmanager helper → _AsyncGeneratorContextManager.__init__ (self.gen = func(*args, **kwds)) → the deprecated wrapper. typing_extensions.deprecated emits warnings.warn(msg, stacklevel=2), and two frames up from the wrapper is _AsyncGeneratorContextManager.__init__ — so the warning is attributed to CPython's contextlib.py, not the caller's file and line.

Step-by-step proof (reproduced independently by three verifiers on Python 3.11):

1. Define sse_client exactly as in this PR (@asynccontextmanager over @deprecated(...)).
2. Call sse_client("http://x/sse") from a user module and capture the warning with warnings.catch_warnings(record=True).
3. Inspect the record: filename == "/usr/lib/python3.11/contextlib.py", lineno == 105. The user sees .../contextlib.py:105: MCPDeprecationWarning: The HTTP+SSE transport is deprecated... with no pointer to their own code.
4. Swap the decorator order (@deprecated outermost) and repeat: the record now points at the user's call line, and the returned object still works as an async context manager (async with sse_client(url) as streams verified to behave identically).

Downstream consequences

• Python's default "default" filter action dedupes per (message, category, module, lineno). Since every sse_client call in a process shares the contextlib.py:105 location, an application with several distinct call sites sees the warning once total, not once per call site — verified: two calls from different lines emitted one warning.
• module=-scoped filters (warnings.filterwarnings(..., module="myapp.legacy")) cannot target this warning, because its module resolves to contextlib, not the caller's module.
• This partially undercuts the PR's stated motivation ("nothing told users at the call site … a visible warning fires at runtime"): the warning fires, but it doesn't tell users where in their code the deprecated transport is used.

Why the PR's tests don't catch it

test_sse_client_warns_that_the_http_sse_transport_is_deprecated in tests/shared/test_sse.py uses pytest.warns and asserts only category and message text — never the attributed filename/lineno.

Why this is unique to sse_client

Every other entry point deprecated by this PR (SseServerParameters, SseServerTransport, sse_app, run_sse_async, the run(transport="sse") overload) is a plain class or method whose deprecated wrapper is invoked directly from the user's frame, so those warnings attribute correctly.

Fix

Swap the decorator order so @deprecated is outermost:

@deprecated(
    "The HTTP+SSE transport is deprecated as of 2025-03-26 (SEP-2596). Use streamable_http_client instead.",
    category=MCPDeprecationWarning,
)
@asynccontextmanager
async def sse_client(...):

The warning still fires eagerly at sse_client(url) construction (before any connection), the returned context manager is unchanged, and both pyright's reportDeprecated flagging and the existing pytest.warns tests are unaffected. (Alternatively, stacklevel=3 would work, but typing_extensions.deprecated doesn't expose that knob — the swap is the clean one-line fix.)

Severity

Nit: the warning does fire visibly with the correct category and its message names the transport, so nothing breaks — only the file/line attribution, per-call-site dedup, and module-scoped filtering are degraded relative to the PR's call-site-visibility goal. One-line fix, not worth blocking merge.

🟡 The migration of this client to Streamable HTTP left two stale instructions that still say to start the server in SSE mode: the module docstring (uv run server elicitation sse, ~line 20) and the ConnectionRefusedError handler (line 305). Following either starts the server on the legacy /sse endpoint while this client now connects to /mcp, so the connection fails — and the failure message then repeats the wrong command. Both should say streamable-http to match the updated hint in main().

What the bug is. This PR migrates examples/snippets/clients/url_elicitation_client.py from sse_client to streamable_http_client: the import changes, server_url becomes http://localhost:8000/mcp, and the startup hint printed in main() (line 289) is updated to uv run server elicitation streamable-http. But two other references to the old command in the same file were missed:

1. The module docstring (~line 20): uv run server elicitation sse
2. The ConnectionRefusedError handler (line 305): print(" cd examples/snippets && uv run server elicitation sse")

The code path that triggers it. The snippets server runner (examples/snippets/servers/__init__.py) dispatches its transport argument to mcp.run(transport), so uv run server elicitation sse really does start the server on the legacy HTTP+SSE transport, serving /sse and /messages/ — there is no /mcp endpoint in that mode.

Step-by-step proof.

1. A user reads the module docstring and runs cd examples/snippets && uv run server elicitation sse. The server starts, listening for legacy SSE clients at http://localhost:8000/sse.
2. They run the client. It calls streamable_http_client("http://localhost:8000/mcp") (lines 283, 292) and POSTs to /mcp.
3. The SSE-mode Starlette app has no /mcp route, so the request fails (404 → connection error surfaced to the user).
4. The client's error path prints Make sure the elicitation server is running: cd examples/snippets && uv run server elicitation sse — the exact command the user already ran. The recovery instruction loops them back into the failure.

Beyond the connection failure, following the stale instruction also puts the user on the transport this very PR is deprecating: the server run emits MCPDeprecationWarning, the opposite of what the snippet is meant to demonstrate post-migration.

Why nothing catches it. These are string literals in comments and print statements — no type checker, test, or the new deprecation warnings can flag them. The example only fails when run interactively against a real server, which CI doesn't do.

Impact and fix. Impact is confined to this example: the primary hint in main() (line 289) is correct, so a user who starts from the printed banner is fine; only users who follow the docstring or the error-path message get misdirected. The fix is a single root cause with two one-line string changes — replace sse with streamable-http in the docstring and in the ConnectionRefusedError handler, matching line 289 exactly (the runner accepts streamable-http as a transport argument, verified against examples/snippets/servers/__init__.py).

🟡 🟡 The @deprecated decorator on the run(transport="sse") overload has no runtime effect (PEP 702: a decorated @overload stub only informs static checkers), so at runtime a mcp.run(transport="sse") caller instead sees the nested run_sse_async warning — "Use run_streamable_http_async instead" — naming an async API they never called, when the direct migration is transport="streamable-http" in the same run() call. Fix by warnings.warn()-ing the overload's transport-oriented message in the case "sse" branch and suppressing the nested run_sse_async warning with catch_warnings, matching the pattern run_sse_async already uses for sse_app.

What the bug is. This PR stacks @overload over @deprecated on the run(transport: Literal["sse"]) overload (src/mcp/server/mcpserver/server.py:361-369). Per PEP 702 / typing_extensions, @deprecated applied to an @overload stub only informs static checkers: typing.overload registers the stub and returns a dummy that is never called, and the stub function object is discarded when the implementation def run(...) executes. So the overload's carefully worded message — 'transport="sse" is deprecated … Use transport="streamable-http" instead.' — is never emitted at runtime. Three independent verifiers reproduced this empirically with a minimal replica of the exact decorator structure: zero warnings fire from the overload decorator.

The code path that triggers it. mcp.run(transport="sse") reaches the implementation's case "sse" branch, which dispatches anyio.run(lambda: self.run_sse_async(**kwargs)). run_sse_async is genuinely decorated, so its warning fires — but that is the wrong message for this caller.

Step-by-step proof.

1. A user calls mcp.run(transport="sse") — a synchronous, top-level entry point.
2. The overload's @deprecated emits nothing (stub discarded; the implementation has no __deprecated__ attribute).
3. The case "sse" branch invokes run_sse_async via a lambda; its @deprecated wrapper fires: MCPDeprecationWarning: The HTTP+SSE transport is deprecated as of 2025-03-26 (SEP-2596). Use run_streamable_http_async instead.
4. The user is told to migrate to an async method they never touched, when the actual one-token fix is transport="streamable-http" in the call they already have. The warning is also attributed to the lambda inside server.py, not the user's call site.

Why existing code doesn't prevent it. The PR's stated design is that nested constructions suppress inner warnings "so the caller sees exactly one, naming the thing they called" — and the authors did add catch_warnings suppression for run_sse_async → sse_app and sse_app → SseServerTransport. The run() → run_sse_async hop is the one link in the chain with no explicit runtime warning above it, presumably because the overload decorator was assumed to fire at runtime. No test catches it: the case "sse" branch is # pragma: no cover, and the three new warning tests cover sse_client, SseServerTransport, and sse_app() only.

Impact. Limited: exactly one MCPDeprecationWarning still fires with the correct category, the correct SEP-2596 reference, and a workable (if indirect) migration path — and pyright still flags the call site correctly via the overload. Nothing breaks; the message is merely misdirected for the highest-level, most-documented entry point (run() is what mcp run --transport sse and every quickstart-style server use).

How to fix. In the implementation's case "sse" branch, explicitly warnings.warn() the overload's transport-oriented message (as MCPDeprecationWarning, with a stacklevel pointing at the caller), then suppress the nested run_sse_async warning with warnings.catch_warnings() + simplefilter("ignore", MCPDeprecationWarning) — the exact pattern run_sse_async already applies to its own nested sse_app() call. Keeping the @deprecated on the overload is still right for static checkers; it just needs a runtime counterpart.