Fix unknown-method error code and add a protocol version registry (#2836)

tests/client/test_auth.py

@@ -819,6 +819,24 @@ class TestProtectedResourceMetadata:
         assert "resource=" in content
 
 
+@pytest.mark.parametrize(
+    ("protocol_version", "expected"),
+    [
+        ("2025-03-26", False),
+        ("2025-06-18", True),
+        ("2025-11-25", True),
+        # Unrecognized strings gate conservatively, even ones sorting after 2025-06-18.
+        ("zzz", False),
+        ("9999-99-99", False),
+    ],
+)
+def test_should_include_resource_param_by_protocol_version(
+    oauth_provider: OAuthClientProvider, protocol_version: str, expected: bool
+) -> None:
+    """Resource param is included only for recognized versions >= 2025-06-18."""
+    assert oauth_provider.context.should_include_resource_param(protocol_version) is expected
+
+
 @pytest.mark.anyio
 async def test_validate_resource_rejects_mismatched_resource(
     client_metadata: OAuthClientMetadata, mock_storage: MockTokenStorage

tests/client/test_client.py

@@ -113,6 +113,12 @@ async def test_client_is_initialized(app: MCPServer):
         assert client.initialize_result.server_info.name == "test"
 
 
+async def test_client_initialize_result_exposes_negotiated_protocol_version(app: MCPServer):
+    """The negotiated protocol version is readable after initialization."""
+    async with Client(app) as client:
+        assert client.initialize_result.protocol_version == types.LATEST_PROTOCOL_VERSION
+
+
 async def test_client_with_simple_server(simple_server: Server):
     """Test that from_server works with a basic Server instance."""
     async with Client(simple_server) as client:

tests/interaction/lowlevel/test_completion.py

@@ -128,4 +128,6 @@ async def test_complete_without_handler_is_method_not_found(connect: Connect) ->
         with pytest.raises(MCPError) as exc_info:
             await client.complete(PromptReference(name="anything"), argument={"name": "topic", "value": ""})
 
-    assert exc_info.value.error == snapshot(ErrorData(code=METHOD_NOT_FOUND, message="Method not found"))
+    assert exc_info.value.error == snapshot(
+        ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="completion/complete")
+    )

tests/interaction/lowlevel/test_resources.py

@@ -236,7 +236,9 @@ async def test_subscribe_without_a_subscribe_handler_is_method_not_found(connect
         with pytest.raises(MCPError) as exc_info:
             await client.subscribe_resource("file:///watched.txt")
 
-    assert exc_info.value.error == snapshot(ErrorData(code=METHOD_NOT_FOUND, message="Method not found"))
+    assert exc_info.value.error == snapshot(
+        ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="resources/subscribe")
+    )
 
 
 @requirement("resources:unsubscribe")

tests/interaction/mcpserver/test_context.py

@@ -262,7 +262,9 @@ async def test_set_logging_level_is_rejected_and_messages_are_never_filtered(con
 
         await client.call_tool("chatter", {})
 
-    assert exc_info.value.error == snapshot(ErrorData(code=METHOD_NOT_FOUND, message="Method not found"))
+    assert exc_info.value.error == snapshot(
+        ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="logging/setLevel")
+    )
     assert received == snapshot(
         [
             LoggingMessageNotificationParams(level="debug", data="noise"),

tests/server/test_runner.py

@@ -168,6 +168,45 @@ async def test_runner_gates_requests_before_initialize(server: SrvT):
         assert await client.send_raw_request("ping", None) == {}
 
 
+@pytest.mark.anyio
+async def test_runner_unknown_method_before_initialize_raises_method_not_found(server: SrvT):
+    """An unknown method is METHOD_NOT_FOUND even before initialize: JSON-RPC
+    2.0 reserves -32601 for it, and clients probing a server before the
+    handshake key off that code. The init gate only applies to methods the
+    server actually serves."""
+    async with connected_runner(server, initialized=False) as (client, _):
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("x/unknown", None)
+        assert exc.value.error == ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="x/unknown")
+
+
+@pytest.mark.anyio
+async def test_runner_spec_method_without_handler_before_initialize_raises_method_not_found(server: SrvT):
+    """A spec method the server doesn't serve is METHOD_NOT_FOUND even before
+    initialize: -32601 means "not available on this server", so probing
+    clients get the same answer in every initialization state (the fixture
+    server registers no resources handlers)."""
+    async with connected_runner(server, initialized=False) as (client, _):
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("resources/list", None)
+        assert exc.value.error == ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="resources/list")
+
+
+@pytest.mark.anyio
+async def test_runner_custom_method_with_handler_is_still_gated_before_initialize(server: SrvT):
+    """A custom-registered method is a known method: before initialize it is
+    rejected by the init gate, not answered with METHOD_NOT_FOUND."""
+
+    async def greet(ctx: Ctx, params: RequestParams | None) -> Any:
+        raise NotImplementedError  # the gate rejects the request first
+
+    server.add_request_handler("custom/greet", RequestParams, greet)
+    async with connected_runner(server, initialized=False) as (client, _):
+        with pytest.raises(MCPError) as exc:
+            await client.send_raw_request("custom/greet", None)
+        assert exc.value.error == ErrorData(code=INVALID_PARAMS, message="Invalid request parameters", data="")
+
+
 @pytest.mark.anyio
 async def test_runner_routes_to_handler_and_builds_context(server: SrvT):
     async with connected_runner(server) as (client, runner):
@@ -186,7 +225,7 @@ async def test_runner_spec_method_with_no_handler_raises_method_not_found(server
     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
+    assert exc.value.error == ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="resources/list")
 
 
 @pytest.mark.anyio
@@ -196,7 +235,7 @@ async def test_runner_non_spec_method_with_no_handler_raises_method_not_found(se
     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
+    assert exc.value.error == ErrorData(code=METHOD_NOT_FOUND, message="Method not found", data="nonexistent/method")
 
 
 @pytest.mark.anyio

tests/server/test_session.py

@@ -11,6 +11,7 @@ from typing import Any, cast
 import pytest
 
 from mcp import types
+from mcp.server import Server, ServerRequestContext
 from mcp.server.connection import Connection
 from mcp.server.session import ServerSession
 from mcp.shared.dispatcher import CallOptions
@@ -26,6 +27,8 @@ from mcp.types import (
     SamplingToolsCapability,
 )
 
+from .test_runner import connected_runner
+
 
 class StubDispatcher:
     """Records `send_raw_request` / `notify` calls and returns a canned result."""
@@ -158,3 +161,64 @@ def test_check_client_capability_delegates_to_connection():
     session = _make_session(dispatcher, capabilities=ClientCapabilities(sampling=SamplingCapability()))
     assert session.check_client_capability(ClientCapabilities(sampling=SamplingCapability())) is True
     assert session.check_client_capability(ClientCapabilities(experimental={"x": {}})) is False
+
+
+def _runner_server(seen_versions: list[str | None]) -> Server[dict[str, Any]]:
+    """A lowlevel Server whose tools/list handler records `ctx.session.protocol_version`."""
+
+    async def list_tools(
+        ctx: ServerRequestContext[dict[str, Any], Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        seen_versions.append(ctx.session.protocol_version)
+        return types.ListToolsResult(tools=[])
+
+    return Server(name="test-server", version="0.0.1", on_list_tools=list_tools)
+
+
+def _init_params(protocol_version: str) -> dict[str, Any]:
+    return InitializeRequestParams(
+        protocol_version=protocol_version,
+        capabilities=ClientCapabilities(),
+        client_info=Implementation(name="test-client", version="1.0"),
+    ).model_dump(by_alias=True, exclude_none=True)
+
+
+@pytest.mark.anyio
+async def test_protocol_version_is_none_before_initialize():
+    """No negotiated version is readable before the initialize handshake."""
+    async with connected_runner(_runner_server([]), initialized=False) as (_client, runner):
+        assert runner.session.protocol_version is None
+
+
+@pytest.mark.anyio
+async def test_protocol_version_is_negotiated_version_after_initialize():
+    """A supported requested version is echoed back and readable on the session,
+    both directly and from inside a handler via `ctx.session`."""
+    seen: list[str | None] = []
+    async with connected_runner(_runner_server(seen), initialized=False) as (client, runner):
+        result = await client.send_raw_request("initialize", _init_params("2025-03-26"))
+        assert result["protocolVersion"] == "2025-03-26"
+        assert runner.session.protocol_version == "2025-03-26"
+        await client.send_raw_request("tools/list", None)
+        assert seen == ["2025-03-26"]
+
+
+@pytest.mark.anyio
+async def test_protocol_version_reads_latest_when_requested_version_unsupported():
+    """An unsupported requested version negotiates down to LATEST_PROTOCOL_VERSION."""
+    async with connected_runner(_runner_server([]), initialized=False) as (client, runner):
+        result = await client.send_raw_request("initialize", _init_params("1999-01-01"))
+        assert result["protocolVersion"] == LATEST_PROTOCOL_VERSION
+        assert runner.session.protocol_version == LATEST_PROTOCOL_VERSION
+
+
+@pytest.mark.anyio
+async def test_protocol_version_is_none_on_stateless_connection():
+    """Stateless connections never see a handshake: requests flow, but the
+    negotiated version legitimately stays None."""
+    seen: list[str | None] = []
+    async with connected_runner(_runner_server(seen), initialized=False, stateless=True) as (client, runner):
+        result = await client.send_raw_request("tools/list", None)
+        assert result == {"tools": []}
+        assert seen == [None]
+        assert runner.session.protocol_version is None

tests/shared/test_session.py

@@ -9,6 +9,7 @@ from mcp.shared.memory import create_client_server_memory_streams
 from mcp.shared.message import SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.types import (
+    METHOD_NOT_FOUND,
     PARSE_ERROR,
     CancelledNotification,
     CancelledNotificationParams,
@@ -16,6 +17,7 @@ from mcp.types import (
     EmptyResult,
     ErrorData,
     JSONRPCError,
+    JSONRPCNotification,
     JSONRPCRequest,
     JSONRPCResponse,
     ServerNotification,
@@ -403,3 +405,43 @@ async def test_null_id_error_does_not_affect_pending_request():
     # 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

tests/shared/test_streamable_http.py

@@ -1696,6 +1696,87 @@ async def test_close_sse_stream_callback_not_provided_for_old_protocol_version()
     assert session_msg_new.metadata.close_standalone_sse_stream is not None
 
 
+@pytest.mark.anyio
+async def test_priming_event_not_sent_for_unknown_protocol_version() -> None:
+    """_maybe_send_priming_event treats unrecognized version strings conservatively.
+
+    A garbage version must not be mistaken for a future one (lexicographically
+    "zzz" sorts after every date-shaped revision).
+    """
+    transport = StreamableHTTPServerTransport(
+        "/mcp",
+        event_store=SimpleEventStore(),
+    )
+
+    write_stream, read_stream = anyio.create_memory_object_stream[dict[str, Any]](1)
+
+    try:
+        await transport._maybe_send_priming_event("test-request-id", write_stream, "zzz")
+
+        # Nothing should have been written to the stream
+        assert write_stream.statistics().current_buffer_used == 0
+    finally:
+        await write_stream.aclose()
+        await read_stream.aclose()
+
+
+@pytest.mark.anyio
+async def test_close_sse_stream_callback_not_provided_for_unknown_protocol_version() -> None:
+    """close_sse_stream callbacks are withheld when the client's version is unrecognized."""
+    transport = StreamableHTTPServerTransport(
+        "/mcp",
+        event_store=SimpleEventStore(),
+    )
+
+    mock_message = JSONRPCRequest(jsonrpc="2.0", id="test-1", method="tools/list")
+    mock_request = MagicMock()
+
+    session_msg = transport._create_session_message(mock_message, mock_request, "test-request-id", "zzz")
+
+    assert session_msg.metadata is not None
+    assert isinstance(session_msg.metadata, ServerMessageMetadata)
+    assert session_msg.metadata.close_sse_stream is None
+    assert session_msg.metadata.close_standalone_sse_stream is None
+
+
+@pytest.mark.anyio
+async def test_initialize_with_unknown_protocol_version_gets_no_priming_event(
+    event_app: tuple[SimpleEventStore, Starlette],
+) -> None:
+    """A garbage protocolVersion in initialize params must not trigger priming.
+
+    The priming decision reads the raw body params before any validation, so an
+    unrecognized string must gate conservatively (old-client behavior), not
+    compare lexicographically past "2025-11-25".
+    """
+    event_store, app = event_app
+    init_request = {
+        "jsonrpc": "2.0",
+        "method": "initialize",
+        "params": {
+            "clientInfo": {"name": "test-client", "version": "1.0"},
+            "protocolVersion": "zzz",
+            "capabilities": {},
+        },
+        "id": "init-1",
+    }
+    async with make_client(app) as client:
+        response = await client.post(
+            "/mcp",
+            headers={
+                "Accept": "application/json, text/event-stream",
+                "Content-Type": "application/json",
+            },
+            json=init_request,
+        )
+        assert response.status_code == 200
+
+    # The store must have seen traffic (the initialize response), but no
+    # priming event — priming events are stored with a None payload.
+    assert event_store._events
+    assert all(message is not None for _, _, message in event_store._events)
+
+
 @pytest.mark.anyio
 async def test_streamable_http_client_receives_priming_event(
     event_app: tuple[SimpleEventStore, Starlette],

tests/shared/test_version.py

@@ -0,0 +1,59 @@
+"""Tests for the protocol-version registry and comparison helpers."""
+
+import pytest
+
+from mcp.shared.version import (
+    KNOWN_PROTOCOL_VERSIONS,
+    SUPPORTED_PROTOCOL_VERSIONS,
+    is_version_at_least,
+)
+
+
+@pytest.mark.parametrize(
+    ("version", "minimum", "expected"),
+    [
+        # equal
+        ("2025-11-25", "2025-11-25", True),
+        ("2024-11-05", "2024-11-05", True),
+        # above
+        ("2025-11-25", "2025-06-18", True),
+        ("2025-06-18", "2024-11-05", True),
+        # below
+        ("2025-06-18", "2025-11-25", False),
+        ("2024-11-05", "2025-03-26", False),
+    ],
+)
+def test_is_version_at_least_ordering(version: str, minimum: str, expected: bool) -> None:
+    """Known revisions order by registry position: equal, newer, and older pairs."""
+    assert is_version_at_least(version, minimum) is expected
+
+
+@pytest.mark.parametrize("version", ["zzz", "", "2025-11-26", "draft", "9999-99-99"])
+def test_is_version_at_least_unknown_version_is_false(version: str) -> None:
+    """Unrecognized peer strings compare conservatively, never accidentally."""
+    assert is_version_at_least(version, "2024-11-05") is False
+
+
+def test_is_version_at_least_unknown_minimum_raises() -> None:
+    """An unknown minimum is programmer error, not peer input."""
+    with pytest.raises(ValueError, match="zzz"):
+        is_version_at_least("2025-11-25", "zzz")
+
+
+@pytest.mark.parametrize(
+    ("version", "minimum"), [(v, m) for v in KNOWN_PROTOCOL_VERSIONS for m in KNOWN_PROTOCOL_VERSIONS]
+)
+def test_is_version_at_least_matches_lexicographic_for_known_versions(version: str, minimum: str) -> None:
+    """Drop-in equivalence: for every known (date-shaped) revision pair the helper
+    agrees with the string comparison it replaced."""
+    assert is_version_at_least(version, minimum) is (version >= minimum)
+
+
+def test_supported_versions_are_known() -> None:
+    """Every negotiable revision must be in the ordering registry."""
+    assert set(SUPPORTED_PROTOCOL_VERSIONS) <= set(KNOWN_PROTOCOL_VERSIONS)
+
+
+def test_known_versions_are_strictly_ordered() -> None:
+    """The registry tuple is the ordering source of truth: ascending, no duplicates."""
+    assert list(KNOWN_PROTOCOL_VERSIONS) == sorted(set(KNOWN_PROTOCOL_VERSIONS))