Return METHOD_NOT_FOUND for requests with unknown methods

A peer request whose method is not in the session's receive union
previously failed union validation and was answered with -32602
(INVALID_PARAMS). JSON-RPC 2.0 reserves -32601 (METHOD_NOT_FOUND) for
unknown methods, and peers probing for optional features key off that
code. Check the method against the union's discriminator literals
before validating and answer unknown ones with -32601, carrying the
method name in the error data. Unknown notification methods are still
dropped without a response.

Author: maxisbey

src/mcp/client/session.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Protocol
+from typing import Any, Protocol, cast, get_args
 
 import anyio.lowlevel
-from pydantic import TypeAdapter
+from pydantic import BaseModel, TypeAdapter
 
 from mcp import types
 from mcp.client._transport import ReadStream, WriteStream
@@ -95,6 +95,13 @@ async def _default_logging_callback(
 
 ClientResponse: TypeAdapter[types.ClientResult | types.ErrorData] = TypeAdapter(types.ClientResult | types.ErrorData)
 
+_SERVER_REQUEST_METHODS: frozenset[str] = frozenset(
+    cast(type[BaseModel], arm).model_fields["method"].default for arm in get_args(types.ServerRequest)
+)
+"""Method names in the spec `ServerRequest` union, derived from the
+discriminator literal on each arm. Requests for any other method are answered
+with METHOD_NOT_FOUND instead of failing union validation."""
+
 
 class ClientSession(
     BaseSession[
@@ -134,6 +141,10 @@ def __init__(
     def _receive_request_adapter(self) -> TypeAdapter[types.ServerRequest]:
         return types.server_request_adapter
 
+    @property
+    def _receive_request_methods(self) -> frozenset[str]:
+        return _SERVER_REQUEST_METHODS
+
     @property
     def _receive_notification_adapter(self) -> TypeAdapter[types.ServerNotification]:
         return types.server_notification_adapter

src/mcp/shared/session.py

@@ -20,6 +20,7 @@
 from mcp.types import (
     CONNECTION_CLOSED,
     INVALID_PARAMS,
+    METHOD_NOT_FOUND,
     REQUEST_TIMEOUT,
     CancelledNotification,
     ClientNotification,
@@ -286,6 +287,12 @@ def _receive_request_adapter(self) -> TypeAdapter[ReceiveRequestT]:
         """Each subclass must provide its own request adapter."""
         raise NotImplementedError
 
+    @property
+    def _receive_request_methods(self) -> frozenset[str]:
+        """Method names in the receive-request union; anything else is
+        answered with METHOD_NOT_FOUND before validation is attempted."""
+        raise NotImplementedError
+
     @property
     def _receive_notification_adapter(self) -> TypeAdapter[ReceiveNotificationT]:
         raise NotImplementedError
@@ -297,6 +304,18 @@ async def _receive_loop(self) -> None:
                 async def _handle_session_message(message: SessionMessage) -> None:
                     sender_context: contextvars.Context | None = getattr(self._read_stream, "last_context", None)
                     if isinstance(message.message, JSONRPCRequest):
+                        if message.message.method not in self._receive_request_methods:
+                            # Unknown methods are METHOD_NOT_FOUND (-32601) per
+                            # JSON-RPC 2.0, not validation failures (-32602).
+                            error_response = JSONRPCError(
+                                jsonrpc="2.0",
+                                id=message.message.id,
+                                error=ErrorData(
+                                    code=METHOD_NOT_FOUND, message="Method not found", data=message.message.method
+                                ),
+                            )
+                            await self._write_stream.send(SessionMessage(message=error_response))
+                            return
                         try:
                             validated_request = self._receive_request_adapter.validate_python(
                                 message.message.model_dump(by_alias=True, mode="json", exclude_none=True),

tests/shared/test_session.py

@@ -9,13 +9,15 @@
 from mcp.shared.message import SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.types import (
+    METHOD_NOT_FOUND,
     PARSE_ERROR,
     CancelledNotification,
     CancelledNotificationParams,
     ClientResult,
     EmptyResult,
     ErrorData,
     JSONRPCError,
+    JSONRPCNotification,
     JSONRPCRequest,
     JSONRPCResponse,
     ServerNotification,
@@ -403,3 +405,43 @@ async def make_request(client_session: ClientSession):
     # Pending request completed successfully
     assert len(result_holder) == 1
     assert isinstance(result_holder[0], EmptyResult)
+
+
+@pytest.mark.anyio
+async def test_receive_loop_answers_unknown_request_method_with_method_not_found():
+    """A peer request whose method is not in the receive union gets -32601
+    (METHOD_NOT_FOUND) on the wire, not a validation failure (-32602)."""
+    async with create_client_server_memory_streams() as (client_streams, server_streams):
+        client_read, client_write = client_streams
+        server_read, server_write = server_streams
+
+        async with ClientSession(read_stream=client_read, write_stream=client_write):
+            await server_write.send(SessionMessage(message=JSONRPCRequest(jsonrpc="2.0", id=7, method="x/unknown")))
+            with anyio.fail_after(5):  # pragma: no branch
+                out = await server_read.receive()
+
+    assert isinstance(out, SessionMessage)
+    assert isinstance(out.message, JSONRPCError)
+    assert out.message.id == 7
+    assert out.message.error == ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="x/unknown")
+
+
+@pytest.mark.anyio
+async def test_receive_loop_drops_unknown_notification_method_without_response():
+    """An unknown notification method is dropped silently: JSON-RPC forbids
+    responses to notifications, and the receive loop keeps serving."""
+    async with create_client_server_memory_streams() as (client_streams, server_streams):
+        client_read, client_write = client_streams
+        server_read, server_write = server_streams
+
+        async with ClientSession(read_stream=client_read, write_stream=client_write):
+            await server_write.send(SessionMessage(message=JSONRPCNotification(jsonrpc="2.0", method="x/unknown")))
+            # The next wire output must be the answer to this follow-up ping,
+            # proving the notification produced no response and the loop survived.
+            await server_write.send(SessionMessage(message=JSONRPCRequest(jsonrpc="2.0", id=1, method="ping")))
+            with anyio.fail_after(5):  # pragma: no branch
+                out = await server_read.receive()
+
+    assert isinstance(out, SessionMessage)
+    assert isinstance(out.message, JSONRPCResponse)
+    assert out.message.id == 1