Cover the remaining client-session branches and document the migration

Adds tests for ServerMessageMetadata routing, related-request-id
notifications, and params-absent inbound requests over direct dispatch,
plus the migration-guide entry for the ClientSession dispatcher swap.

Author: maxisbey

docs/migration.md

@@ -1164,7 +1164,23 @@ In practice, replace direct `ServerSession` use with `Server.run(read_stream, wr
 
 `BaseSession._in_flight` and the `RequestResponder` members that supported it (`cancel()`, the `cancelled` and `in_flight` properties, the `on_complete` constructor argument, and the internal `CancelScope`) have been removed. These existed to let `ServerSession` cancel a handler when a `CancelledNotification` arrived; `ServerSession` no longer drives a receive loop, so they were dead code. Inbound-cancellation handling for the server now lives in `JSONRPCDispatcher`.
 
-`BaseSession` is still used by `ClientSession`, which never relied on these members. `RequestResponder.respond()` is unchanged.
+`BaseSession` itself has since been removed entirely; see the next section.
+
+### `ClientSession` now runs on `JSONRPCDispatcher`; `BaseSession` removed
+
+`ClientSession` keeps its public surface — the `(read_stream, write_stream, ...)` constructor, every typed method, manual `initialize()`, and the async context-manager lifecycle — but the v1 receive loop (`BaseSession`) underneath it is gone. A new `ClientSession.from_dispatcher(dispatcher, ...)` constructor accepts a pre-built dispatcher (for example a `DirectDispatcher` for in-process embedding).
+
+Behavior changes:
+
+- **Request ids count from 1** (previously 0). Progress tokens, which reuse the request id, shift the same way. Ids are opaque per JSON-RPC; do not assign meaning to them.
+- **Timeouts**: the error message is now `Request 'tools/call' timed out` (previously `Timed out while waiting for response to CallToolRequest. Waited N seconds.`), and a timed-out or abandoned request is followed by `notifications/cancelled` on the wire, so the server stops the handler instead of leaving it running. The `initialize` request is never cancelled this way, and requests sent with resumption metadata are also exempt so they stay resumable.
+- **Server-initiated requests run concurrently.** Sampling/elicitation/roots callbacks no longer serialize the receive loop: a slow callback does not block other traffic, a callback may itself send requests without deadlocking, and a server's `notifications/cancelled` now actually interrupts the callback (the request is then answered with an error response).
+- **Notification callbacks are concurrent.** `logging_callback` and `message_handler` start in arrival order, but there is no completion-before-response guarantee (matching the TypeScript, C#, and Go SDKs). Callbacks that need strict sequencing must coordinate themselves.
+- **Unknown-id responses are ignored**, as the spec asks. v1 surfaced them to `message_handler` as a `RuntimeError`; nothing is surfaced now.
+- **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`.
+- **`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.
+
+`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.
 
 ### Experimental Tasks support removed
 

tests/client/test_session.py

@@ -900,9 +900,50 @@ async def server_on_notify(
         await tg.start(server_side.run, server_on_request, server_on_notify)
         async with session:
             results.append(await session.send_ping(meta=None))
+            # Server-to-client direction: direct dispatch delivers ping with no
+            # params member at all (no _meta injection outside JSON-RPC).
+            assert await server_side.send_raw_request("ping", None) == {}
             # related_request_id routing is JSON-RPC plumbing; on other
             # dispatchers the notification is sent without it.
             await session.send_notification(types.RootsListChangedNotification(), related_request_id=7)
         server_side.close()
     assert results == [types.EmptyResult()]
     assert notified == ["notifications/roots/list_changed"]
+
+
+@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."""
+    from mcp.shared.message import ServerMessageMetadata
+
+    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."""
+    from mcp.shared.message import ServerMessageMetadata
+
+    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