Remove the client-side related_request_id surface

ServerMessageMetadata.related_request_id exists for the server's
streamable-HTTP transport to route outbound messages onto the originating
request's SSE stream. No client transport has ever serialized it, so
ClientSession's related_request_id parameter and ServerMessageMetadata
acceptance were dead inheritance from the shared v1 BaseSession.

- send_notification loses its related_request_id parameter
- send_request's metadata narrows to ClientMessageMetadata | None
  (resumption hints, the live part)
- the isinstance(dispatcher) downcasts those parameters forced are gone

Progress and response correlation (progressToken in params, JSON-RPC id)
are payload-level mechanisms and are unaffected.

Author: maxisbey

docs/migration.md

@@ -1187,6 +1187,7 @@ Behavior changes:
 - **Error responses with a null `id`** — the JSON-RPC shape for a peer reporting a parse error — are now dropped with a debug log. v1 surfaced them to `message_handler` as an `MCPError`.
 - **A raising request callback** is answered with `code=0` and the exception text. v1 flattened every callback exception to `INVALID_PARAMS`. Callbacks that want a specific error response should return `ErrorData` (unchanged) or raise `MCPError`. One carve-out: a callback that raises pydantic's `ValidationError` is still answered with `INVALID_PARAMS` (`"Invalid request parameters"`, empty `data`) because the dispatcher cannot distinguish it from inbound-params validation — this conflation is pre-existing v1 behavior, and a revisit is pending.
 - **`send_request` before entering the context manager** raises `RuntimeError` immediately; v1 wrote to the transport and hung until the timeout. `send_notification` before entry still works.
+- **`send_notification` no longer takes `related_request_id`, and `send_request` no longer accepts `ServerMessageMetadata`.** The hint was never serialized by any client transport in v1 or v2 — it exists for the server's streamable-HTTP stream routing. Progress and response correlation via `progressToken` and the request id is unaffected.
 
 `mcp.shared.session` is now a compatibility module: `ProgressFnT` is re-exported (its home is `mcp.shared.dispatcher`), and `RequestResponder` remains as a typing-only stub so `MessageHandlerFnT` annotations keep importing — it has been unreachable at runtime since the server-side swap. `RequestResponder.respond()` no longer exists.
 

src/mcp/client/session.py

@@ -18,7 +18,7 @@
 from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher
 from mcp.shared.exceptions import MCPError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
-from mcp.shared.message import ClientMessageMetadata, MessageMetadata, ServerMessageMetadata, SessionMessage
+from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import ProgressFnT, RequestResponder
 from mcp.shared.transport_context import TransportContext
 from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
@@ -202,15 +202,13 @@ async def send_request(
         request: types.ClientRequest,
         result_type: type[ReceiveResultT],
         request_read_timeout_seconds: float | None = None,
-        metadata: MessageMetadata = None,
+        metadata: ClientMessageMetadata | None = None,
         progress_callback: ProgressFnT | None = None,
     ) -> ReceiveResultT:
         """Send a request and wait for its typed result.
 
         Args:
-            metadata: Transport hints: `ClientMessageMetadata` resumption fields
-                (streamable HTTP), or a `ServerMessageMetadata.related_request_id`
-                routing the message onto the originating request's stream.
+            metadata: Streamable HTTP resumption hints.
 
         Raises:
             MCPError: Error response, read timeout, or connection closed.
@@ -224,38 +222,21 @@ async def send_request(
             opts["timeout"] = timeout
         if progress_callback is not None:
             opts["on_progress"] = progress_callback
-        related_request_id: types.RequestId | None = None
-        if isinstance(metadata, ClientMessageMetadata):
+        if metadata is not None:
             if metadata.resumption_token is not None:
                 opts["resumption_token"] = metadata.resumption_token
             if metadata.on_resumption_token_update is not None:
                 opts["on_resumption_token"] = metadata.on_resumption_token_update
-        elif isinstance(metadata, ServerMessageMetadata):
-            related_request_id = metadata.related_request_id
         if method == "initialize":
             # The spec forbids cancelling initialize.
             opts["cancel_on_abandon"] = False
-        if related_request_id is not None and isinstance(self._dispatcher, JSONRPCDispatcher):
-            # Only JSON-RPC dispatchers have per-request streams to route onto.
-            raw = await self._dispatcher.send_raw_request(
-                method, data.get("params"), opts, _related_request_id=related_request_id
-            )
-        else:
-            raw = await self._dispatcher.send_raw_request(method, data.get("params"), opts)
+        raw = await self._dispatcher.send_raw_request(method, data.get("params"), opts)
         return result_type.model_validate(raw, by_name=False)
 
-    async def send_notification(
-        self,
-        notification: types.ClientNotification,
-        related_request_id: types.RequestId | None = None,
-    ) -> None:
+    async def send_notification(self, notification: types.ClientNotification) -> None:
         """Send a one-way notification. Usable before entering the context manager."""
         data = notification.model_dump(by_alias=True, mode="json", exclude_none=True)
-        # `is not None`: request ids are opaque and 0 is valid.
-        if related_request_id is not None and isinstance(self._dispatcher, JSONRPCDispatcher):
-            await self._dispatcher.notify(data["method"], data.get("params"), _related_request_id=related_request_id)
-        else:
-            await self._dispatcher.notify(data["method"], data.get("params"))
+        await self._dispatcher.notify(data["method"], data.get("params"))
 
     async def initialize(self) -> types.InitializeResult:
         sampling = (

tests/client/test_session.py

@@ -14,7 +14,7 @@
 from mcp.shared._context import RequestContext
 from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
 from mcp.shared.dispatcher import CallOptions, DispatchContext, OnNotify, OnRequest
-from mcp.shared.message import ServerMessageMetadata, SessionMessage
+from mcp.shared.message import SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.shared.transport_context import TransportContext
 from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
@@ -978,8 +978,7 @@ async def server_on_notify(
             results.append(await session.send_ping(meta=None))
             # Server-to-client: direct dispatch delivers ping with no params member (no _meta injection).
             assert await server_side.send_raw_request("ping", None) == {}
-            # related_request_id is JSON-RPC plumbing; other dispatchers send the notification without it.
-            await session.send_notification(types.RootsListChangedNotification(), related_request_id=7)
+            await session.send_notification(types.RootsListChangedNotification())
         server_side.close()
     assert results == [types.EmptyResult()]
     assert notified == ["notifications/roots/list_changed"]
@@ -1082,53 +1081,3 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
     assert scope.cancelled_caught
     # The failed enter must not leave the session half-entered.
     assert session._task_group is None
-
-
-@pytest.mark.anyio
-async def test_send_request_with_server_metadata_routes_related_request_id():
-    """ServerMessageMetadata.related_request_id is threaded onto the outgoing message."""
-    async with raw_client_session() as (session, to_client, from_client):
-        async with anyio.create_task_group() as tg:
-
-            async def call() -> None:
-                await session.send_request(
-                    types.PingRequest(), types.EmptyResult, metadata=ServerMessageMetadata(related_request_id=3)
-                )
-
-            tg.start_soon(call)
-            out = await from_client.receive()
-            assert isinstance(out.metadata, ServerMessageMetadata)
-            assert out.metadata.related_request_id == 3
-            assert isinstance(out.message, JSONRPCRequest)
-            await to_client.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=out.message.id, result={})))
-
-
-@pytest.mark.anyio
-async def test_send_notification_with_related_request_id_attaches_metadata():
-    """A related_request_id on a notification rides the originating request's stream."""
-    async with raw_client_session() as (session, _to_client, from_client):
-        await session.send_notification(
-            types.ProgressNotification(
-                params=types.ProgressNotificationParams(progress_token=1, progress=0.5),
-            ),
-            related_request_id=4,
-        )
-        out = await from_client.receive()
-    assert isinstance(out.metadata, ServerMessageMetadata)
-    assert out.metadata.related_request_id == 4
-
-
-@pytest.mark.anyio
-async def test_send_notification_with_related_request_id_zero_attaches_metadata():
-    """`related_request_id=0` still attaches metadata: 0 is a valid request id, so the session checks
-    `is not None`, not truthiness (regression pin). Wire-level: only the sent `SessionMessage` shows it."""
-    async with raw_client_session() as (session, _to_client, from_client):
-        await session.send_notification(
-            types.ProgressNotification(
-                params=types.ProgressNotificationParams(progress_token=1, progress=0.5),
-            ),
-            related_request_id=0,
-        )
-        out = await from_client.receive()
-    assert isinstance(out.metadata, ServerMessageMetadata)
-    assert out.metadata.related_request_id == 0