Answer unknown methods with METHOD_NOT_FOUND before the initialize gate

The runner's pre-initialize gate rejected every non-exempt request with
INVALID_PARAMS, including methods the server does not know at all.
JSON-RPC 2.0 reserves -32601 for unknown methods regardless of session
state, and clients probing a server before the handshake key off that
code. Check for unknown methods before the gate; known-but-ungated
methods keep the existing rejection. METHOD_NOT_FOUND errors now carry
the method name in the error data.

Author: maxisbey

src/mcp/server/runner.py

@@ -243,12 +243,17 @@ async def _inner() -> HandlerResult:
             # (read loop parked), so awaiting the peer anywhere on this path deadlocks.
             if method == "initialize":
                 return self._handle_initialize(params)
+            # Unknown methods are METHOD_NOT_FOUND regardless of initialization
+            # state: JSON-RPC 2.0 reserves -32601 for them, and clients probing
+            # a server before the handshake key off that code.
+            if method not in _SPEC_CLIENT_METHODS and self.server.get_request_handler(method) is None:
+                raise MCPError(code=METHOD_NOT_FOUND, message="Method not found", data=method)
             if not self.connection.initialize_accepted and method not in _INIT_EXEMPT:
                 # Pinned compat: the same error shape the union validation produced.
                 raise MCPError(code=INVALID_PARAMS, message="Invalid request parameters", data="")
             entry = self.server.get_request_handler(method)
             if entry is None:
-                raise MCPError(code=METHOD_NOT_FOUND, message="Method not found")
+                raise MCPError(code=METHOD_NOT_FOUND, message="Method not found", data=method)
             # Absent params validate as {} (required fields still reject), so
             # the handler receives the model with its defaults, never None.
             typed_params = entry.params_type.model_validate({} if params is None else params, by_name=False)

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 list_resources(
         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 collect(params: LoggingMessageNotificationParams) -> None:
 
         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,33 @@ 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 knows."""
+    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_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 +213,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 +223,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