fix: ServerRunner validates spec methods against ClientRequest before lookup

Parity with BaseSession._receive_loop: a spec method with malformed params
surfaces as INVALID_PARAMS via the dispatcher's ValidationError boundary
even when no handler is registered (the existing server validates against
the discriminated union before any handler lookup).

Gated on the set of spec method names (derived from the ClientRequest union
discriminator) so custom methods registered via add_request_handler still
route. The existing server rejects those too, but nothing pins that and
routing them is strictly better.

DirectDispatcher gains the same ValidationError -> INVALID_PARAMS mapping
JSONRPCDispatcher has, so runner-over-direct unit tests see the same shape.

Author: maxisbey

src/mcp/server/runner.py

@@ -19,7 +19,7 @@
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from functools import partial, reduce
-from typing import Any, Generic, cast
+from typing import Any, Generic, cast, get_args
 
 import anyio.abc
 from opentelemetry.trace import SpanKind, StatusCode
@@ -37,9 +37,11 @@
     INVALID_PARAMS,
     LATEST_PROTOCOL_VERSION,
     METHOD_NOT_FOUND,
+    ClientRequest,
     Implementation,
     InitializeRequestParams,
     InitializeResult,
+    client_request_adapter,
 )
 
 __all__ = ["CallNext", "ServerMiddleware", "ServerRunner", "otel_middleware"]
@@ -51,6 +53,13 @@
 
 _INIT_EXEMPT: frozenset[str] = frozenset({"ping"})
 
+_SPEC_CLIENT_METHODS: frozenset[str] = frozenset(
+    cast(type[BaseModel], arm).model_fields["method"].default for arm in get_args(ClientRequest)
+)
+"""Method names in the spec `ClientRequest` union, derived from the
+discriminator literal on each arm. Used to gate upfront validation so custom
+methods registered via `add_request_handler` are not rejected."""
+
 
 def otel_middleware(next_on_request: OnRequest) -> OnRequest:
     """Dispatch-tier middleware that wraps each request in an OpenTelemetry span.
@@ -161,6 +170,20 @@ async def _on_request(
         method: str,
         params: Mapping[str, Any] | None,
     ) -> dict[str, Any]:
+        # TODO(maxisbey): pinned compat. `BaseSession._receive_loop` validates
+        # every inbound request against the spec `ClientRequest` discriminated
+        # union *before* handler lookup, so a spec method with malformed params
+        # surfaces as INVALID_PARAMS via the dispatcher's ValidationError
+        # boundary even when no handler is registered. v2 wanted to decouple
+        # the runner from the spec union; revisit once the suite's divergence
+        # entry is resolved. Gated on spec methods so custom methods registered
+        # via `add_request_handler` still route (the existing server rejects
+        # those too, but nothing pins that and routing them is strictly better).
+        if method in _SPEC_CLIENT_METHODS:
+            payload: dict[str, Any] = {"method": method}
+            if params is not None:
+                payload["params"] = dict(params)
+            client_request_adapter.validate_python(payload)
         if method == "initialize":
             return self._handle_initialize(params)
         if not self._initialized and method not in _INIT_EXEMPT:

src/mcp/shared/direct_dispatcher.py

@@ -21,12 +21,13 @@
 
 import anyio
 import anyio.abc
+from pydantic import ValidationError
 
 from mcp.shared.dispatcher import CallOptions, OnNotify, OnRequest, ProgressFnT
 from mcp.shared.exceptions import MCPError, NoBackChannelError
 from mcp.shared.message import MessageMetadata
 from mcp.shared.transport_context import TransportContext
-from mcp.types import INTERNAL_ERROR, REQUEST_TIMEOUT, RequestId
+from mcp.types import INTERNAL_ERROR, INVALID_PARAMS, REQUEST_TIMEOUT, RequestId
 
 __all__ = ["DirectDispatcher", "create_direct_dispatcher_pair"]
 
@@ -149,6 +150,10 @@ async def _dispatch_request(
                     return await self._on_request(dctx, method, params)
                 except MCPError:
                     raise
+                except ValidationError as e:
+                    # Same shape JSONRPCDispatcher writes, so runner-over-direct
+                    # tests see what runner-over-JSONRPC would.
+                    raise MCPError(code=INVALID_PARAMS, message="Invalid request parameters", data="") from e
                 except Exception as e:
                     raise MCPError(code=INTERNAL_ERROR, message=str(e)) from e
         except TimeoutError:

tests/server/test_runner.py

@@ -161,13 +161,32 @@ async def test_runner_routes_to_handler_and_builds_context(server: SrvT):
 
 
 @pytest.mark.anyio
-async def test_runner_unknown_method_raises_method_not_found(server: SrvT):
+async def test_runner_spec_method_with_no_handler_raises_method_not_found(server: SrvT):
+    async with connected_runner(server) as (client, _):
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("resources/list", None)
+    assert exc.value.error.code == METHOD_NOT_FOUND
+
+
+@pytest.mark.anyio
+async def test_runner_non_spec_method_with_no_handler_raises_method_not_found(server: SrvT):
+    """Upfront validation is gated to spec methods, so a non-spec method
+    skips it and reaches handler lookup."""
     async with connected_runner(server) as (client, _):
         with pytest.raises(MCPError) as exc:
             await client.send_raw_request("nonexistent/method", None)
     assert exc.value.error.code == METHOD_NOT_FOUND
 
 
+@pytest.mark.anyio
+async def test_runner_malformed_params_for_unregistered_spec_method_raises_invalid_params(server: SrvT):
+    """A spec method with malformed params is INVALID_PARAMS even with no handler."""
+    async with connected_runner(server) as (client, _):
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("tools/call", {"name": 123})
+    assert exc.value.error == ErrorData(code=INVALID_PARAMS, message="Invalid request parameters", data="")
+
+
 @pytest.mark.anyio
 async def test_runner_on_notify_initialized_sets_flag_and_connection_event(server: SrvT):
     async with connected_runner(server, initialized=False) as (client, runner):
@@ -287,6 +306,9 @@ async def test_runner_stateless_skips_init_gate(server: SrvT):
 
 @pytest.mark.anyio
 async def test_server_add_request_handler_routes_custom_method_with_validated_params(server: SrvT):
+    """Custom methods outside the spec `ClientRequest` union skip upfront
+    validation and route to the registered handler."""
+
     class GreetParams(RequestParams):
         name: str
 
@@ -358,7 +380,7 @@ async def test_otel_middleware_records_error_status_on_mcp_error(server: SrvT, s
     async with connected_runner(server, dispatch_middleware=[otel_middleware]) as (client, _):
         spans.clear()
         with pytest.raises(MCPError) as exc:
-            await client.send_raw_request("nonexistent/method", None)
+            await client.send_raw_request("resources/list", None)
         assert exc.value.error.code == METHOD_NOT_FOUND
     [span] = spans.finished()
     assert span.status.status_code == StatusCode.ERROR