Deprecate ServerSession.send_progress_notification

`ServerSession.send_progress_notification` takes an explicit progress token
decoupled from the request it belongs to, so it can keep emitting progress
for a request that has already completed -- which the spec forbids
("Progress notifications MUST stop after completion"). The request-scoped
`report_progress` (and `Context.report_progress`) is the supported path: it
reports against the inbound request's own token, no-ops when the caller did
not ask for progress, and stops when the request completes. The deprecated
method keeps working and emits `MCPDeprecationWarning`.

The warning message deliberately departs from the "<X> is deprecated as of
<version>" pattern used by the spec-driven deprecations: this one is an SDK
API decision, not a spec retirement (2026-07-28 does not retire
server-to-client progress).

For "stops when the request completes" to hold on every dispatcher,
`_DirectDispatchContext` now closes with its request the way
`_JSONRPCDispatchContext` already did: `close()` runs in the dispatch
handler's `finally`, after which `progress`/`notify` deliver nothing,
`can_send_request` is False, and `send_raw_request` raises
`NoBackChannelError` -- the closed state the `DispatchContext` protocol
documents. Two pre-existing tests that asserted `can_send_request` on a
context captured after its handler returned now sample it in-handler, and
the closed-state contract tests are parametrized over both dispatchers.

The interaction test that covered both the server and client side of late
progress is split in two. The server-side property is proved positively on
the wire through `report_progress`; it no longer relies on a session-bound
standalone stream, so it also runs on the stateless streamable-http arm.
The client-side late-drop test keeps using the deprecated explicit-token
method -- the only API that can still produce a late notification -- under
`pytest.warns`, and its arms are unchanged. The migration guide stops
recommending the deprecated method anywhere and documents the replacement.

Author: maxisbey

docs/advanced/deprecated.md

@@ -12,7 +12,7 @@ The table below names each deprecated feature, why it is going away, and the rep
 | **Server-initiated sampling**: `ctx.session.create_message()`, the `sampling_callback=` you pass to `Client(...)` | SEP-2577 retires the capability. | Return `InputRequiredResult` and let the client retry the call (see **Multi-round-trip requests**). |
 | **Protocol logging**: `ctx.log()`, `ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`, `ctx.session.send_log_message()`, `client.set_logging_level()` | SEP-2577 retires the capability. Nothing in-protocol replaces it. | Ordinary `import logging` to stderr (see **Logging**). |
 | **`ping`**: `client.send_ping()` | **Removed** from the protocol, not merely deprecated. There is no `ping` method in 2026-07-28. | Nothing. It only works against a `mode="legacy"` connection. |
-| **Client->server progress**: `client.send_progress_notification()` | 2026-07-28 makes progress server->client only. | Nothing to send. Your *server* reports progress with `ctx.report_progress()` (see **Progress**). |
+| **Client->server progress**: `client.send_progress_notification()` | 2026-07-28 makes progress server->client only. | Nothing to send. Your *server* reports progress with `ctx.report_progress()` (see **Progress**). The SDK separately deprecates the server-side explicit-token `ctx.session.send_progress_notification()` in favour of `report_progress` (same warning category, same replacement). |
 
 Three things fall out of that table:
 

docs/migration.md

@@ -905,7 +905,7 @@ async def handle_tool(name: str, arguments: dict) -> list[TextContent]:
 # After (v2)
 async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
     if ctx.meta and "progress_token" in ctx.meta:
-        await ctx.session.send_progress_notification(ctx.meta["progress_token"], 0.5, 100)
+        await ctx.session.report_progress(0.5, 100)
     ...
 
 server = Server("my-server", on_call_tool=handle_call_tool)
@@ -967,7 +967,7 @@ async def my_tool(ctx: Context[MyLifespanState]) -> str: ...
 
 ### `ProgressContext` and `progress()` context manager removed
 
-The `mcp.shared.progress` module (`ProgressContext`, `Progress`, and the `progress()` context manager) has been removed. This module had no real-world adoption — all users send progress notifications via `Context.report_progress()` or `session.send_progress_notification()` directly.
+The `mcp.shared.progress` module (`ProgressContext`, `Progress`, and the `progress()` context manager) has been removed. This module had no real-world adoption — all users send progress notifications via `Context.report_progress()` directly.
 
 **Before (v1):**
 
@@ -987,21 +987,11 @@ async def my_tool(x: int, ctx: Context) -> str:
     return "done"
 ```
 
-**After — use `session.send_progress_notification()` (low-level):**
-
-```python
-await session.send_progress_notification(
-    progress_token=progress_token,
-    progress=25,
-    total=100,
-)
-```
-
 ### Handler progress reporting: prefer `ctx.report_progress()` over manual `progress_token`
 
 Reading `ctx.meta["progress_token"]` and calling `session.send_progress_notification(token, ...)` is specific to the JSON-RPC transport path. On the in-process modern path (`DirectDispatcher` / `Client(server)`), there is no wire token in `_meta`, so handlers that gate progress on the token's presence go silent.
 
-`ctx.report_progress(progress, total, message)` works on every dispatcher: it sends a progress notification when a token is present and routes the update through the dispatcher's progress channel otherwise, no-opping only when the caller did not request progress at all. `session.send_progress_notification(progress_token, ...)` is unchanged and still works on JSON-RPC transports for code that already holds a token.
+`ctx.report_progress(progress, total, message)` works on every dispatcher: it sends a progress notification when a token is present and routes the update through the dispatcher's progress channel otherwise, no-opping only when the caller did not request progress at all. `ServerSession.send_progress_notification(progress_token, ...)` is now deprecated; see **Progress API deprecations** below.
 
 ### `create_connected_server_and_client_session` removed
 
@@ -1498,11 +1488,23 @@ warnings.filterwarnings("ignore", category=MCPDeprecationWarning)
 
 No migration is required during the deprecation window. New code should avoid building on these features, since they may be removed in a future spec version.
 
-### Client-to-server progress deprecated (2026-07-28)
+### Progress API deprecations (2026-07-28)
 
 The 2026-07-28 spec restricts `notifications/progress` to the server-to-client direction only — `ProgressNotification` is no longer in `ClientNotification`. `Client.send_progress_notification()` and `ClientSession.send_progress_notification()` now carry `typing_extensions.deprecated` and emit `mcp.MCPDeprecationWarning` at runtime. They continue to work against servers negotiating 2025-11-25 or earlier.
 
-On the server side, prefer the new dispatcher-agnostic `ServerSession.report_progress(progress, total, message)` (and `Context.report_progress()` on `MCPServer`) over the raw `ServerSession.send_progress_notification(progress_token, …)`. `report_progress` encapsulates the "no-op when the caller did not request progress" rule and works on every dispatcher; the raw token-taking form remains for handlers that read `_meta.progressToken` directly.
+On the server side, `ServerSession.send_progress_notification(progress_token, ...)` is also deprecated. It takes an explicit progress token decoupled from any request's lifetime, so it can emit progress for a request that has already completed -- which the spec forbids ("Progress notifications MUST stop after completion"). Use `Context.report_progress(progress, total, message)` (or `ServerSession.report_progress(...)` from a low-level handler): it reports against the inbound request's own progress token, works on every dispatcher, no-ops when the caller did not request progress, and is closed with the request, so a late call after the handler has returned sends nothing.
+
+```python
+# Before
+token = ctx.meta.get("progress_token")
+if token is not None:
+    await ctx.session.send_progress_notification(token, 0.5, total=1.0)
+
+# After
+await ctx.report_progress(0.5, total=1.0)
+```
+
+The deprecated method still works during the advisory window and emits `mcp.MCPDeprecationWarning`.
 
 ## Bug Fixes
 

src/mcp/server/session.py

@@ -363,6 +363,11 @@ async def report_progress(self, progress: float, total: float | None = None, mes
         """
         await self._request_outbound.progress(progress, total, message)
 
+    @deprecated(
+        "send_progress_notification is deprecated; use report_progress, which is scoped to "
+        "the inbound request's progress token and stops when that request completes.",
+        category=MCPDeprecationWarning,
+    )
     async def send_progress_notification(
         self,
         progress_token: str | int,

src/mcp/shared/direct_dispatcher.py

@@ -61,12 +61,16 @@ class _DirectDispatchContext:
     """Always `None`: in-memory dispatch attaches no transport metadata."""
     _on_progress: ProgressFnT | None = None
     cancel_requested: anyio.Event = field(default_factory=anyio.Event)
+    _closed: bool = False
 
     @property
     def can_send_request(self) -> bool:
-        return self.transport.can_send_request
+        return self.transport.can_send_request and not self._closed
 
     async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        if self._closed:
+            logger.debug("dropped %s: dispatch context closed", method)
+            return
         await self._back_notify(method, params)
 
     async def send_raw_request(
@@ -80,8 +84,14 @@ async def send_raw_request(
         return await self._back_request(method, params, opts)
 
     async def progress(self, progress: float, total: float | None = None, message: str | None = None) -> None:
-        if self._on_progress is not None:
-            await self._on_progress(progress, total, message)
+        # Gated here, not via notify(): in-process progress never routes through
+        # notify() - it awaits the caller's callback inline (a pinned behaviour).
+        if self._closed or self._on_progress is None:
+            return
+        await self._on_progress(progress, total, message)
+
+    def close(self) -> None:
+        self._closed = True
 
 
 class DirectDispatcher:
@@ -241,6 +251,12 @@ async def _dispatch_request(
                     if unexpected:
                         logger.exception("request handler raised")
                     raise MCPError(code=error.code, message=error.message, data=error.data) from None
+                finally:
+                    # Close the back-channel: after the handler returns, a captured
+                    # context's `progress`/`notify` deliver nothing and its
+                    # `send_raw_request` raises `NoBackChannelError`, matching
+                    # JSONRPCDispatcher's handler-finally.
+                    dctx.close()
         except TimeoutError:
             raise MCPError(
                 code=REQUEST_TIMEOUT,

tests/interaction/_requirements.py

@@ -655,8 +655,11 @@ def __post_init__(self) -> None:
         ),
         divergence=Divergence(
             note=(
-                "The spec MUST is not enforced: progress values are not validated on either side, so a "
-                "handler that emits non-increasing values has them forwarded to the callback unchanged."
+                "Intentional, not a gap to close: no MCP SDK (typescript, go, csharp) validates "
+                "sender-side progress monotonicity, and this one does not either. The spec MUST "
+                "binds the handler author, not the transport; non-increasing values are forwarded "
+                "to the callback unchanged so the receiving application sees what the sender sent. "
+                "docs/tutorial/progress.md states the author's obligation."
             ),
         ),
     ),
@@ -665,13 +668,28 @@ def __post_init__(self) -> None:
         behavior="Progress notifications for a token stop once the associated request completes.",
         divergence=Divergence(
             note=(
-                "send_progress_notification does not check whether the token's request has already "
-                "completed; the late notification is sent and reaches the client."
+                "Holds on the supported path: report_progress is scoped to the inbound request's "
+                "dispatch context, which closes when the request completes, so a late report is a "
+                "no-op (proven by test_report_progress_after_the_request_completes_sends_nothing). "
+                "The deprecated explicit-token ServerSession.send_progress_notification has no "
+                "such gate and still delivers post-completion progress to the client (proven by "
+                "the test that pins the client-side late-drop). The gap closes when that method "
+                "is removed."
             ),
         ),
         arm_exclusions=(
-            ArmExclusion(reason="requires-session", transport="streamable-http-stateless"),
-            ArmExclusion(reason="requires-session", spec_version="2026-07-28"),
+            ArmExclusion(
+                reason="requires-session",
+                spec_version="2026-07-28",
+                note=(
+                    "The wire proof observes notifications/progress via the message handler; "
+                    "neither 2026-07-28 cell can produce one. The in-memory DirectDispatcher "
+                    "delivers progress as an in-process callback and never constructs the "
+                    "notification; the modern streamable-http dispatch context no-ops notify(). "
+                    "The DirectDispatcher half of the property is covered by "
+                    "tests/shared/test_dispatcher.py instead."
+                ),
+            ),
         ),
     ),
     "protocol:progress:late-dropped-by-client": Requirement(

tests/interaction/lowlevel/test_progress.py

@@ -3,10 +3,10 @@
 Server-to-client progress emitted during a request follows the same ordering guarantee as
 logging notifications (see test_logging.py) -- on the in-memory transport unconditionally, and
 over streamable HTTP only when sent with ``related_request_id`` so the notification rides the
-originating request's POST stream rather than the standalone GET stream. These tests pass
-``related_request_id`` so no synchronisation is needed. The client-to-server direction is a
-standalone notification with no response to await, so that test waits on an event set by the
-server's handler.
+originating request's POST stream rather than the standalone GET stream. These tests report
+through the request-scoped `report_progress`, which routes onto that stream, so no
+synchronisation is needed. The client-to-server direction is a standalone notification with no
+response to await, so that test waits on an event set by the server's handler.
 """
 
 import anyio
@@ -15,6 +15,7 @@
 from inline_snapshot import snapshot
 from mcp_types import CallToolResult, ProgressNotification, ProgressNotificationParams, ProgressToken, TextContent
 
+from mcp import MCPDeprecationWarning
 from mcp.server import Server, ServerRequestContext
 from mcp.server.session import ServerSession
 from mcp.shared.session import ProgressFnT
@@ -197,15 +198,86 @@ async def call(label: str, collect: ProgressFnT) -> None:
 
 
 @requirement("protocol:progress:stops-after-completion")
+async def test_report_progress_after_the_request_completes_sends_nothing(connect: Connect) -> None:
+    """Progress reported through `report_progress` after the request has completed never reaches
+    the client.
+
+    The handler captures its `ServerSession`; once `call_tool` has returned, the request's
+    dispatch context is closed, so the late `report_progress` is dropped before any I/O. The
+    message handler is teed every inbound progress notification (matched-to-callback or not), so
+    `seen_on_wire == [0.5]` is a positive full-equality proof: the in-handler report arrived and
+    nothing else ever did. The `list_tools` round-trip after the late report flushes anything a
+    regression would have put in flight, so the negative is not racy.
+
+    The arms here are all `JSONRPCDispatcher` (the two 2026-07-28 cells are excluded: neither can
+    put a `notifications/progress` message on the wire); the `DirectDispatcher` half of the same
+    close is proven by
+    `tests/shared/test_dispatcher.py::test_ctx_progress_and_notify_after_the_inbound_request_returns_are_dropped`,
+    which is parametrized over both dispatchers.
+
+    Steps:
+    1. The tool reports 0.5 through `report_progress` and captures `ctx.session`.
+    2. After `call_tool` returns, wait until 0.5 has been observed on the wire.
+    3. Call `report_progress(1.0)` on the captured session -- a no-op on the closed context.
+    4. A second `list_tools` round-trip flushes the single ordered stream.
+    5. Tear the connection down; assert the wire saw exactly [0.5].
+    """
+    captured: list[ServerSession] = []
+
+    async def list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[types.Tool(name="report", input_schema={"type": "object"})])
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        assert params.name == "report"
+        captured.append(ctx.session)
+        await ctx.session.report_progress(0.5)
+        return CallToolResult(content=[TextContent(text="done")])
+
+    server = Server("reporter", on_list_tools=list_tools, on_call_tool=call_tool)
+
+    received: list[float] = []
+    seen_on_wire: list[float] = []
+    first_seen = anyio.Event()
+
+    async def collect(progress: float, total: float | None, message: str | None) -> None:
+        received.append(progress)
+
+    async def message_handler(message: IncomingMessage) -> None:
+        assert isinstance(message, ProgressNotification)
+        seen_on_wire.append(message.params.progress)
+        first_seen.set()
+
+    async with connect(server, message_handler=message_handler) as client:
+        with anyio.fail_after(5):
+            await client.call_tool("report", {}, progress_callback=collect)
+            await first_seen.wait()
+            await captured[0].report_progress(1.0)
+            await client.list_tools()
+
+    assert received == [0.5]
+    assert seen_on_wire == [0.5]
+
+
 @requirement("protocol:progress:late-dropped-by-client")
-async def test_progress_sent_after_the_response_is_not_delivered_to_the_callback(connect: Connect) -> None:
-    """A progress notification sent after the response is emitted, and the client drops it from the callback.
-
-    This single body proves both halves: the server's `send_progress_notification` happily sends for
-    a token whose request has already completed (the spec MUST that progress stops is not enforced;
-    see the divergence on `stops-after-completion`), and the client, having removed the callback when
-    the call returned, does not deliver the late notification to it. The message handler observes the
-    late notification arriving so the test knows when to assert without polling.
+@requirement("protocol:progress:stops-after-completion")
+async def test_a_progress_notification_arriving_after_the_response_is_dropped_from_the_callback(
+    connect: Connect,
+) -> None:
+    """A progress notification that arrives after its request has completed is not delivered to
+    the original progress callback.
+
+    SDK-defined: the client removes the per-call progress callback when `call_tool` returns.
+    Producing a genuinely late notification requires the deprecated explicit-token
+    `ServerSession.send_progress_notification` -- the only API not tied to the request's
+    dispatch context -- used deliberately here under `pytest.warns`. The message handler
+    observes the late notification arriving so the test knows when to assert without polling.
+
+    The arrival itself pins the server-side half: the deprecated explicit-token method has no
+    completion gate, so the late notification still reaches the wire. That is the known
+    stops-after-completion divergence; the spec-conforming `report_progress` path is proven
+    separately by `test_report_progress_after_the_request_completes_sends_nothing`.
     """
     captured: list[tuple[ServerSession, ProgressToken]] = []
 
@@ -220,7 +292,7 @@ async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestPara
         token = ctx.meta.get("progress_token")
         assert token is not None
         captured.append((ctx.session, token))
-        await ctx.session.send_progress_notification(token, 0.5, related_request_id=str(ctx.request_id))
+        await ctx.session.report_progress(0.5)
         return CallToolResult(content=[TextContent(text="done")])
 
     server = Server("reporter", on_list_tools=list_tools, on_call_tool=call_tool)
@@ -241,7 +313,8 @@ async def message_handler(message: IncomingMessage) -> None:
             assert received == [0.5]
 
             server_session, token = captured[0]
-            await server_session.send_progress_notification(token, 1.0)
+            with pytest.warns(MCPDeprecationWarning, match=r"^send_progress_notification is deprecated"):
+                await server_session.send_progress_notification(token, 1.0)  # pyright: ignore[reportDeprecated]
             await late_progress_arrived.wait()
 
     assert received == [0.5]