Use spec error codes for unhandled elicitation/create and roots/list

A client constructed without an elicitation_callback or
list_roots_callback still answers the server's request, via a default
callback that returns a JSON-RPC error. Both defaults used -32600
(invalid request). The spec assigns a specific code to each case:

- elicitation/create: -32602 (invalid params). A client with no
  callback declares no elicitation modes, so every incoming request
  names an undeclared mode, which clients MUST answer with -32602.
- roots/list: -32601 (method not found), the code clients SHOULD use
  when they do not support roots.

The default sampling callback keeps -32600: the spec assigns no code
to a client that does not support sampling. Error messages are
unchanged.

Update the affected tests and the interaction-requirement entries that
recorded the old codes, fix the code named in the client callbacks doc
page, and add a migration note.

Author: maxisbey

docs/client/callbacks.md

@@ -101,7 +101,7 @@ Pass all three callbacks and you get `['elicitation', 'sampling', 'roots']`. Pas
     MCPError: Elicitation not supported
     ```
 
-    That is a protocol error (`-32600`, *invalid request*), not a tool error: there is nothing for
+    That is a protocol error (`-32602`, *invalid params*), not a tool error: there is nothing for
     the model to read and retry. It's why `client_features` is worth having: a well-behaved server
     checks before it asks.
 

docs/migration.md

@@ -410,6 +410,12 @@ For an in-process `Client(server)` (where `server` is a `Server` or `MCPServer`
 
 `Client.send_ping()` is deprecated (ping is removed in 2026-07-28); pin `mode='legacy'` if you need it.
 
+### Unhandled `elicitation/create` returns `-32602`; unhandled `roots/list` returns `-32601`
+
+When a server sends `elicitation/create` to a client that registered no `elicitation_callback`, or `roots/list` to a client that registered no `list_roots_callback`, the SDK still answers on the client's behalf with a JSON-RPC error. In v1 both answers used code `-32600` (`INVALID_REQUEST`). They now use the code the spec assigns to each case: `elicitation/create` is answered with `-32602` (`INVALID_PARAMS`), per the [elicitation error-handling section](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#error-handling) (a client with no callback declared no elicitation modes, and a request for an undeclared mode MUST be answered with `-32602`), and `roots/list` is answered with `-32601` (`METHOD_NOT_FOUND`), per the [roots error-handling section](https://modelcontextprotocol.io/specification/2025-11-25/client/roots#error-handling). The error messages (`Elicitation not supported`, `List roots not supported`) are unchanged, and `sampling/createMessage` without a `sampling_callback` still answers `-32600` — the spec assigns no code to that case.
+
+Server-side code that branched on `error.code == INVALID_REQUEST` to detect a client without elicitation or roots support should switch to `INVALID_PARAMS` and `METHOD_NOT_FOUND` respectively — or, better, check the client's declared capabilities before sending, which is the condition these codes describe.
+
 ### `call_tool` can return `InputRequiredResult` (opt-in)
 
 For protocol 2026-07-28, a `tools/call` request may return an `InputRequiredResult` asking the client to supply additional input and retry. By default `call_tool` (on `ClientSession`, `Client`, and `ClientSessionGroup`) still returns `CallToolResult` and raises `RuntimeError` if the server requests input. Pass `allow_input_required=True` to receive the `InputRequiredResult` instead, then retry with `input_responses=` / `request_state=`.

src/mcp/client/session.py

@@ -149,6 +149,8 @@ async def _default_sampling_callback(
     context: ClientRequestContext,
     params: types.CreateMessageRequestParams,
 ) -> types.CreateMessageResult | types.CreateMessageResultWithTools | types.ErrorData:
+    # Unlike elicitation (INVALID_PARAMS) and roots (METHOD_NOT_FOUND) below, the spec assigns no
+    # error code to a client that does not support sampling; INVALID_REQUEST is the SDK's choice.
     return types.ErrorData(
         code=types.INVALID_REQUEST,
         message="Sampling not supported",
@@ -160,7 +162,7 @@ async def _default_elicitation_callback(
     params: types.ElicitRequestParams,
 ) -> types.ElicitResult | types.ErrorData:
     return types.ErrorData(
-        code=types.INVALID_REQUEST,
+        code=types.INVALID_PARAMS,
         message="Elicitation not supported",
     )
 
@@ -169,7 +171,7 @@ async def _default_list_roots_callback(
     context: ClientRequestContext,
 ) -> types.ListRootsResult | types.ErrorData:
     return types.ErrorData(
-        code=types.INVALID_REQUEST,
+        code=types.METHOD_NOT_FOUND,
         message="List roots not supported",
     )
 

tests/client/test_list_roots_callback.py

@@ -1,5 +1,5 @@
 import pytest
-from mcp_types import INVALID_REQUEST, ListRootsResult, Root, TextContent
+from mcp_types import METHOD_NOT_FOUND, ListRootsResult, Root, TextContent
 from pydantic import FileUrl
 
 from mcp import Client
@@ -44,4 +44,4 @@ async def test_list_roots(context: Context, message: str):
     async with Client(server, mode="legacy") as client:
         with pytest.raises(MCPError) as exc_info:
             await client.call_tool("test_list_roots", {"message": "test message"})
-    assert exc_info.value.error.code == INVALID_REQUEST
+    assert exc_info.value.error.code == METHOD_NOT_FOUND

tests/docs_src/test_client_callbacks.py

@@ -3,6 +3,7 @@
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import (
+    INVALID_PARAMS,
     INVALID_REQUEST,
     CreateMessageRequestParams,
     CreateMessageResult,
@@ -74,7 +75,7 @@ async def test_without_the_callback_the_servers_request_is_refused() -> None:
     async with Client(tutorial001.mcp, mode="legacy") as client:
         with pytest.raises(MCPError, match="Elicitation not supported") as exc_info:
             await client.call_tool("issue_card")
-    assert exc_info.value.error.code == INVALID_REQUEST
+    assert exc_info.value.error.code == INVALID_PARAMS
 
 
 async def test_registering_the_callback_declares_the_capability() -> None:

tests/interaction/_requirements.py

@@ -1757,9 +1757,6 @@ def __post_init__(self) -> None:
             "An elicitation request to a client that did not declare the elicitation capability is "
             "answered with -32602 Invalid params."
         ),
-        divergence=Divergence(
-            note="The client's default callback answers with -32600 Invalid request instead of -32602.",
-        ),
         arm_exclusions=(
             ArmExclusion(reason="server-initiated-request", transport="streamable-http-stateless"),
             ArmExclusion(reason="server-initiated-request", spec_version="2026-07-28"),
@@ -1967,9 +1964,6 @@ def __post_init__(self) -> None:
             "A roots/list request to a client that did not declare the roots capability is answered with "
             "-32601 Method not found."
         ),
-        divergence=Divergence(
-            note="The client's default callback answers with -32600 Invalid request instead of -32601.",
-        ),
         arm_exclusions=(
             ArmExclusion(reason="server-initiated-request", transport="streamable-http-stateless"),
             ArmExclusion(reason="server-initiated-request", spec_version="2026-07-28"),

tests/interaction/lowlevel/test_elicitation.py

@@ -9,6 +9,7 @@
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import (
+    INVALID_PARAMS,
     CallToolResult,
     ElicitCompleteNotification,
     ElicitCompleteNotificationParams,
@@ -160,14 +161,13 @@ async def answer_form(context: ClientRequestContext, params: types.ElicitRequest
 
 @requirement("elicitation:form:not-supported")
 @requirement("elicitation:capability:server-respects-mode")
-async def test_elicit_form_without_callback_is_error(connect: Connect) -> None:
-    """Eliciting from a client that configured no elicitation callback fails with an error.
-
-    The client's default callback answers with an Invalid request error, which the server-side
-    elicit call raises as an MCPError; the tool reports the code and message it caught. The spec
-    requires -32602 for an undeclared mode (see the divergence note on the requirement). The
-    request reaching the client also shows the server does not check the client's declared
-    elicitation capability before sending (see the divergence on `server-respects-mode`).
+async def test_elicit_form_without_callback_fails_with_invalid_params(connect: Connect) -> None:
+    """Eliciting from a client that configured no elicitation callback fails with `INVALID_PARAMS`.
+
+    Spec-mandated (MUST): an elicitation/create whose mode the client never declared is answered
+    with -32602 Invalid params, and a client with no callback declared no elicitation modes at all.
+    The request reaching the client at all also shows the server does not check the client's
+    declared elicitation capability before sending (see the divergence on `server-respects-mode`).
     """
 
     async def list_tools(
@@ -177,20 +177,25 @@ async def list_tools(
             tools=[types.Tool(name="ask", description="Ask the user.", input_schema={"type": "object"})]
         )
 
+    errors: list[ErrorData] = []
+
     async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
         assert params.name == "ask"
         try:
             await ctx.session.elicit_form("Anyone there?", {"type": "object", "properties": {}})
         except MCPError as exc:
-            return CallToolResult(content=[TextContent(text=f"{exc.error.code}: {exc.error.message}")])
+            errors.append(exc.error)
+            return CallToolResult(content=[TextContent(text=exc.error.message)])
         raise NotImplementedError  # elicit_form cannot succeed without a client callback
 
     server = Server("asker", on_list_tools=list_tools, on_call_tool=call_tool)
 
     async with connect(server) as client:
         result = await client.call_tool("ask", {})
 
-    assert result == snapshot(CallToolResult(content=[TextContent(text="-32600: Elicitation not supported")]))
+    assert result == snapshot(CallToolResult(content=[TextContent(text="Elicitation not supported")]))
+    (error,) = errors
+    assert error.code == INVALID_PARAMS
 
 
 @requirement("elicitation:url:action:accept-no-content")

tests/interaction/lowlevel/test_roots.py

@@ -4,7 +4,7 @@
 import mcp_types as types
 import pytest
 from inline_snapshot import snapshot
-from mcp_types import INTERNAL_ERROR, CallToolResult, ErrorData, ListRootsResult, Root, TextContent
+from mcp_types import INTERNAL_ERROR, METHOD_NOT_FOUND, CallToolResult, ErrorData, ListRootsResult, Root, TextContent
 from pydantic import FileUrl
 
 from mcp import MCPError
@@ -80,32 +80,38 @@ async def list_roots(context: ClientRequestContext) -> ListRootsResult:
 
 
 @requirement("roots:list:not-supported")
-async def test_list_roots_without_callback_is_error(connect: Connect) -> None:
-    """A roots/list request to a client with no roots callback fails with an error the handler can observe.
+async def test_list_roots_without_callback_fails_with_method_not_found(connect: Connect) -> None:
+    """A roots/list request to a client with no roots callback fails with `METHOD_NOT_FOUND`.
 
-    The client's default callback answers with INVALID_REQUEST rather than leaving the server
-    hanging; the spec names -32601 for this case (see the divergence note on the requirement).
+    Spec-recommended (SHOULD): a client that does not support roots answers roots/list with
+    -32601 Method not found. The error reaches the requesting server handler as an `MCPError`
+    rather than leaving it hanging.
     """
 
     async def list_tools(
         ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
     ) -> types.ListToolsResult:
         return types.ListToolsResult(tools=[types.Tool(name="show_roots", input_schema={"type": "object"})])
 
+    errors: list[ErrorData] = []
+
     async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
         assert params.name == "show_roots"
         try:
             await ctx.session.list_roots()  # pyright: ignore[reportDeprecated]
         except MCPError as exc:
-            return CallToolResult(content=[TextContent(text=f"{exc.error.code}: {exc.error.message}")])
+            errors.append(exc.error)
+            return CallToolResult(content=[TextContent(text=exc.error.message)])
         raise NotImplementedError  # list_roots cannot succeed without a client callback
 
     server = Server("rooted", on_list_tools=list_tools, on_call_tool=call_tool)
 
     async with connect(server) as client:
         result = await client.call_tool("show_roots", {})
 
-    assert result == snapshot(CallToolResult(content=[TextContent(text="-32600: List roots not supported")]))
+    assert result == snapshot(CallToolResult(content=[TextContent(text="List roots not supported")]))
+    (error,) = errors
+    assert error.code == METHOD_NOT_FOUND
 
 
 @requirement("roots:list:client-error")