fix: ServerSession.send_request fails fast without a back channel; narrow metadata

With no related request to ride on and no standalone channel (stateless
HTTP), a server-to-client request could never receive its response; raise
NoBackChannelError instead of parking forever, matching
Connection.send_raw_request.

Narrow the metadata parameter to ServerMessageMetadata | None: only
related_request_id is honored, so accepting the full MessageMetadata
union silently discarded ClientMessageMetadata.

Author: maxisbey

src/mcp/server/session.py

@@ -17,9 +17,9 @@
 from mcp.server.connection import Connection
 from mcp.server.validation import validate_sampling_tools, validate_tool_use_result_messages
 from mcp.shared.dispatcher import CallOptions, ProgressFnT
-from mcp.shared.exceptions import StatelessModeNotSupported
+from mcp.shared.exceptions import NoBackChannelError, StatelessModeNotSupported
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
-from mcp.shared.message import MessageMetadata, ServerMessageMetadata
+from mcp.shared.message import ServerMessageMetadata
 
 __all__ = ["ServerSession"]
 
@@ -55,22 +55,31 @@ async def send_request(
         request: types.ServerRequest,
         result_type: type[ResultT],
         request_read_timeout_seconds: float | None = None,
-        metadata: MessageMetadata = None,
+        metadata: ServerMessageMetadata | None = None,
         progress_callback: ProgressFnT | None = None,
     ) -> ResultT:
         """Send a typed server-to-client request and validate the result.
 
         `metadata.related_request_id` (when supplied) routes the outgoing
         message onto the originating request's response stream over
-        streamable HTTP.
+        streamable HTTP; it is the only metadata field honored here.
+
+        Raises:
+            NoBackChannelError: If there is no related request to ride on and
+                the connection has no standalone channel (stateless HTTP), so
+                a response could never arrive.
         """
         data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
         opts: CallOptions = {}
         if request_read_timeout_seconds is not None:
             opts["timeout"] = request_read_timeout_seconds
         if progress_callback is not None:
             opts["on_progress"] = progress_callback
-        related = metadata.related_request_id if isinstance(metadata, ServerMessageMetadata) else None
+        related = metadata.related_request_id if metadata is not None else None
+        if related is None and not self._connection.has_standalone_channel:
+            # Fail fast instead of parking forever on a response that cannot
+            # arrive; matches `Connection.send_raw_request`.
+            raise NoBackChannelError(data["method"])
         result = await self._dispatcher.send_raw_request(
             data["method"], data.get("params"), opts or None, _related_request_id=related
         )

tests/server/test_session.py

@@ -14,6 +14,7 @@
 from mcp.server.connection import Connection
 from mcp.server.session import ServerSession
 from mcp.shared.dispatcher import CallOptions
+from mcp.shared.exceptions import NoBackChannelError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ServerMessageMetadata
 from mcp.types import (
@@ -48,8 +49,13 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
         raise NotImplementedError
 
 
-def _make_session(dispatcher: StubDispatcher, *, capabilities: ClientCapabilities | None = None) -> ServerSession:
-    conn = Connection(dispatcher, has_standalone_channel=True)
+def _make_session(
+    dispatcher: StubDispatcher,
+    *,
+    capabilities: ClientCapabilities | None = None,
+    has_standalone_channel: bool = True,
+) -> ServerSession:
+    conn = Connection(dispatcher, has_standalone_channel=has_standalone_channel)
     if capabilities is not None:
         conn.client_params = InitializeRequestParams(
             protocol_version=LATEST_PROTOCOL_VERSION,
@@ -93,6 +99,22 @@ async def test_send_request_omits_call_options_when_none_given():
     assert related is None
 
 
+@pytest.mark.anyio
+async def test_send_request_without_back_channel_or_related_id_fails_fast():
+    """No standalone channel and no related request to ride on: raise instead
+    of parking forever on a response that cannot arrive."""
+    dispatcher = StubDispatcher(result={})
+    session = _make_session(dispatcher, has_standalone_channel=False)
+    with pytest.raises(NoBackChannelError):
+        await session.send_request(types.PingRequest(), types.EmptyResult)
+    assert dispatcher.requests == []
+    # With a related request id the message rides that request's stream.
+    await session.send_request(
+        types.PingRequest(), types.EmptyResult, metadata=ServerMessageMetadata(related_request_id=3)
+    )
+    assert dispatcher.requests[0][3] == 3
+
+
 @pytest.mark.anyio
 async def test_send_request_validates_result_alias_only():
     """Peer results validate alias-only; a snake_case key from the wire is