Validate client results against the surface schema in server send_request

ServerSession.send_request and Connection.send_request now run the
client's response through validate_client_result before parsing into the
caller's result_type. KeyError (spec method without a row at the
negotiated version, or a non-spec method on Connection) is tolerated and
the existing model_validate proceeds; ValidationError propagates as today.

Adds validate_client_result to types.methods and refactors
parse_client_result to delegate its surface step to it.

Author: maxisbey

src/mcp/server/connection.py

@@ -38,6 +38,7 @@
     PingRequest,
     Request,
 )
+from mcp.types import methods as _methods
 
 __all__ = ["Connection"]
 
@@ -175,6 +176,13 @@ async def send_request(
             KeyError: `result_type` omitted for a non-spec request type.
         """
         raw = await self.send_raw_request(req.method, dump_params(req.params), opts)
+        # Literal fallback covers pre-handshake and stateless; matches runner.py.
+        version = self.protocol_version or "2025-11-25"
+        if req.method in _methods.MONOLITH_REQUESTS:
+            try:
+                _methods.validate_client_result(req.method, version, raw)
+            except KeyError:
+                pass
         cls = result_type if result_type is not None else _RESULT_FOR[type(req)]
         return cls.model_validate(raw, by_name=False)
 

src/mcp/server/session.py

@@ -20,6 +20,7 @@
 from mcp.shared.exceptions import NoBackChannelError, StatelessModeNotSupported
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.message import ServerMessageMetadata
+from mcp.types import methods as _methods
 
 __all__ = ["ServerSession"]
 
@@ -96,6 +97,12 @@ async def send_request(
         result = await self._dispatcher.send_raw_request(
             data["method"], data.get("params"), opts or None, _related_request_id=related
         )
+        # Literal fallback covers pre-handshake and stateless; matches runner.py.
+        version = self.protocol_version or "2025-11-25"
+        try:
+            _methods.validate_client_result(request.method, version, result)
+        except KeyError:
+            pass
         return result_type.model_validate(result, by_name=False)
 
     async def send_notification(

src/mcp/types/methods.py

@@ -41,6 +41,7 @@
     "serialize_server_result",
     "validate_client_notification",
     "validate_client_request",
+    "validate_client_result",
     "validate_server_result",
 ]
 
@@ -652,6 +653,24 @@ def parse_server_result(
     return result
 
 
+def validate_client_result(
+    method: str,
+    version: str,
+    data: Mapping[str, Any],
+    *,
+    surface: Mapping[tuple[str, str], type[BaseModel] | UnionType] = CLIENT_RESULTS,
+) -> None:
+    """Validate a client result against `surface` only.
+
+    Raises:
+        ValueError: `version` is not a known protocol version.
+        KeyError: `(method, version)` is not in `surface`.
+        pydantic.ValidationError: result fails surface validation.
+    """
+    _check_known_version(version)
+    _adapter(surface[(method, version)]).validate_python(data, by_name=False)
+
+
 def parse_client_result(
     method: str,
     version: str,
@@ -675,7 +694,6 @@ def parse_client_result(
         pydantic.ValidationError: result fails surface or monolith validation.
         RuntimeError: surface matched but `method` has no monolith row.
     """
-    _check_known_version(version)
-    _adapter(surface[(method, version)]).validate_python(data, by_name=False)
+    validate_client_result(method, version, data, surface=surface)
     result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(data, by_name=False)
     return result

tests/server/test_connection.py

@@ -8,11 +8,11 @@
 
 import logging
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, Literal
 
 import anyio
 import pytest
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 
 from mcp.server.connection import Connection
 from mcp.shared.dispatcher import CallOptions
@@ -29,6 +29,8 @@
     ListRootsRequest,
     ListRootsResult,
     PingRequest,
+    Request,
+    RequestParams,
     RootsCapability,
     SamplingCapability,
     SamplingContextCapability,
@@ -144,6 +146,54 @@ async def test_connection_send_request_nonconforming_result_raises_validation_er
         await conn.send_request(ListRootsRequest())
 
 
+@pytest.mark.anyio
+async def test_send_request_validates_the_client_result_against_the_surface_schema():
+    """A spec-method result that fails the per-version surface schema raises
+    `ValidationError` even when the caller's `result_type` would accept it."""
+    conn = Connection(StubOutbound(result={"roots": "nope"}), has_standalone_channel=True)
+    with pytest.raises(ValidationError):
+        await conn.send_request(ListRootsRequest(), result_type=EmptyResult)
+
+
+@pytest.mark.anyio
+async def test_send_request_passes_a_spec_valid_client_result():
+    """A spec-valid client result passes the surface gate and parses to the typed model."""
+    conn = Connection(StubOutbound(result={"roots": [{"uri": "file:///ws"}]}), has_standalone_channel=True)
+    conn.protocol_version = "2025-11-25"
+    result = await conn.send_request(ListRootsRequest())
+    assert isinstance(result, ListRootsResult)
+    assert str(result.roots[0].uri) == "file:///ws"
+
+
+class _CustomRequest(Request[RequestParams | None, Literal["custom/echo"]]):
+    method: Literal["custom/echo"] = "custom/echo"
+    params: RequestParams | None = None
+
+
+class _CustomResult(BaseModel):
+    value: int
+
+
+@pytest.mark.anyio
+async def test_send_request_skips_the_surface_gate_when_method_absent_at_version():
+    """Surface row absent for the negotiated version: gate is bypassed and only
+    the inferred result type validates."""
+    conn = Connection(StubOutbound(result={}), has_standalone_channel=True)
+    conn.protocol_version = "2026-07-28"
+    result = await conn.send_request(PingRequest())
+    assert isinstance(result, EmptyResult)
+
+
+@pytest.mark.anyio
+async def test_send_request_with_a_custom_method_skips_the_surface_gate():
+    """Non-spec methods are not blocked by the surface gate; `result_type` validates."""
+    conn = Connection(StubOutbound(result={"value": 7}), has_standalone_channel=True)
+    conn.protocol_version = "2025-11-25"
+    result = await conn.send_request(_CustomRequest(), result_type=_CustomResult)
+    assert isinstance(result, _CustomResult)
+    assert result.value == 7
+
+
 @pytest.mark.anyio
 async def test_connection_ping_sends_ping_on_standalone():
     out = StubOutbound()

tests/server/test_session.py

@@ -9,6 +9,7 @@
 from typing import Any, cast
 
 import pytest
+from pydantic import ValidationError
 
 from mcp import types
 from mcp.server import Server, ServerRequestContext
@@ -57,8 +58,10 @@ def _make_session(
     *,
     capabilities: ClientCapabilities | None = None,
     has_standalone_channel: bool = True,
+    protocol_version: str | None = None,
 ) -> ServerSession:
     conn = Connection(dispatcher, has_standalone_channel=has_standalone_channel)
+    conn.protocol_version = protocol_version
     if capabilities is not None:
         conn.client_params = InitializeRequestParams(
             protocol_version=LATEST_PROTOCOL_VERSION,
@@ -128,6 +131,33 @@ async def test_send_request_without_back_channel_or_related_id_fails_fast():
     assert dispatcher.requests[0][3] == 3
 
 
+@pytest.mark.anyio
+async def test_send_request_validates_the_client_result_against_the_surface_schema():
+    """A spec-method result that fails the per-version surface schema raises
+    `ValidationError` even when the caller's `result_type` would accept it."""
+    session = _make_session(StubDispatcher(result={"roots": "nope"}))
+    with pytest.raises(ValidationError):
+        await session.send_request(types.ListRootsRequest(), types.EmptyResult)
+
+
+@pytest.mark.anyio
+async def test_send_request_passes_a_spec_valid_client_result():
+    """A spec-valid client result passes the surface gate and parses to the typed model."""
+    session = _make_session(StubDispatcher(result={"roots": [{"uri": "file:///ws"}]}))
+    result = await session.send_request(types.ListRootsRequest(), types.ListRootsResult)
+    assert isinstance(result, types.ListRootsResult)
+    assert str(result.roots[0].uri) == "file:///ws"
+
+
+@pytest.mark.anyio
+async def test_send_request_skips_the_surface_gate_when_method_absent_at_version():
+    """Surface row absent for the negotiated version: gate is bypassed and only
+    `result_type` validates."""
+    session = _make_session(StubDispatcher(result={}), protocol_version="2026-07-28")
+    result = await session.send_request(types.PingRequest(), types.EmptyResult)
+    assert isinstance(result, types.EmptyResult)
+
+
 @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

tests/types/test_methods.py

@@ -732,18 +732,23 @@ def test_validate_functions_accept_reject_and_gate_like_their_parse_siblings():
     methods.validate_client_request("tools/call", "2025-11-25", {"name": "echo"})
     methods.validate_client_notification("notifications/cancelled", "2025-11-25", {"requestId": 1})
     methods.validate_server_result("tools/list", "2025-11-25", {"tools": []})
+    methods.validate_client_result("roots/list", "2025-11-25", {"roots": []})
     with pytest.raises(KeyError):
         methods.validate_client_request("custom/greet", "2025-11-25", None)
     with pytest.raises(KeyError):
         methods.validate_client_notification("custom/ping", "2025-11-25", None)
     with pytest.raises(KeyError):
         methods.validate_server_result("custom/greet", "2025-11-25", {})
+    with pytest.raises(KeyError):
+        methods.validate_client_result("roots/list", "2026-07-28", {})
     with pytest.raises(pydantic.ValidationError):
         methods.validate_client_request("tools/call", "2025-11-25", None)
     with pytest.raises(pydantic.ValidationError):
         methods.validate_client_notification("notifications/progress", "2025-11-25", {"progressToken": []})
     with pytest.raises(pydantic.ValidationError):
         methods.validate_server_result("tools/list", "2025-11-25", {"tools": 42})
+    with pytest.raises(pydantic.ValidationError):
+        methods.validate_client_result("roots/list", "2025-11-25", {"roots": 42})
     with pytest.raises(ValueError):
         methods.validate_client_request("ping", "2099-01-01", None)