ClientSession.discover() with the error ladder; Client mode='auto'

- discover() probes server/discover via the dispatcher (bypassing the stamp),
  validates the response as DiscoverResult before reading any field, then
  .adopt()s it
- Error ladder: -32022 retries once with the intersection of MODERN and
  data.supported (re-raises if empty or on second failure); -32601 and
  REQUEST_TIMEOUT fall back to .initialize(); anything else propagates
- Idempotent (mirrors .initialize())
- Client.mode gains 'auto' which calls .discover() in __aenter__
- 9 unit tests cover each ladder rung, idempotency, malformed -32022 data,
  and the response-validation gate; 1 end-to-end test drives mode='auto'
  over the in-process ASGI bridge

Author: maxisbey

src/mcp/client/client.py

@@ -107,10 +107,10 @@ async def main():
     client_info: Implementation | None = None
     """Client implementation info to send to server."""
 
-    mode: Literal["legacy"] | str = "legacy"
-    """'legacy' performs the initialize handshake. A protocol-version string (e.g. '2026-07-28') adopts that
-    version directly without a handshake — supply prior_discover to reuse a known DiscoverResult, or omit it
-    to synthesize a minimal one."""
+    mode: Literal["legacy", "auto"] | str = "legacy"
+    """'legacy' performs the initialize handshake. 'auto' probes server/discover and falls back to initialize()
+    on legacy servers. A protocol-version string (e.g. '2026-07-28') adopts that version directly without a
+    handshake — supply prior_discover to reuse a known DiscoverResult, or omit it to synthesize a minimal one."""
 
     prior_discover: types.DiscoverResult | None = None
     """A previously-obtained DiscoverResult to install via .adopt() when mode is a version pin.
@@ -155,6 +155,8 @@ async def __aenter__(self) -> Client:
 
             if self.mode == "legacy":
                 await self._session.initialize()
+            elif self.mode == "auto":
+                await self._session.discover()
             else:
                 self._session.adopt(self.prior_discover or _synthesize_discover(self.mode))
 

src/mcp/client/session.py

@@ -34,12 +34,15 @@
     INTERNAL_ERROR,
     METHOD_NOT_FOUND,
     PROTOCOL_VERSION_META_KEY,
+    REQUEST_TIMEOUT,
+    UNSUPPORTED_PROTOCOL_VERSION,
     RequestId,
     RequestParamsMeta,
 )
 from mcp.types import methods as _methods
 
 DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
+DISCOVER_TIMEOUT_SECONDS = 10.0
 
 logger = logging.getLogger("client")
 
@@ -368,6 +371,67 @@ def adopt(self, result: types.InitializeResult | types.DiscoverResult) -> None:
             self._stamp = _make_handshake_stamp(result.protocol_version)
             self._initialize_result = result
 
+    async def discover(self) -> types.InitializeResult:
+        """Probe `server/discover` and adopt the result, falling back to `initialize()`.
+
+        Sends a single `server/discover` proposing the newest modern protocol
+        version. The error ladder, in order:
+
+        - `UNSUPPORTED_PROTOCOL_VERSION` (-32022): the server's `supported`
+          list is intersected with `MODERN_PROTOCOL_VERSIONS` and the probe is
+          retried once at the highest mutual version. No mutual version, or a
+          second failure, raises the server's `MCPError`.
+        - `METHOD_NOT_FOUND` (-32601) or `REQUEST_TIMEOUT` (-32001): the server
+          is treated as legacy and `initialize()` runs instead — exactly as
+          ``mode='legacy'`` would.
+        - Any other error: re-raised.
+
+        Returns the synthesized `InitializeResult` (also available afterwards
+        via `initialize_result`).
+        """
+        if self._initialize_result is not None:
+            return self._initialize_result
+
+        client_info = self._client_info.model_dump(by_alias=True, mode="json", exclude_none=True)
+        capabilities = self._build_capabilities().model_dump(by_alias=True, mode="json", exclude_none=True)
+
+        async def probe(version: str) -> dict[str, Any]:
+            params = {
+                "_meta": {
+                    PROTOCOL_VERSION_META_KEY: version,
+                    CLIENT_INFO_META_KEY: client_info,
+                    CLIENT_CAPABILITIES_META_KEY: capabilities,
+                }
+            }
+            opts: CallOptions = {
+                "timeout": DISCOVER_TIMEOUT_SECONDS,
+                "cancel_on_abandon": False,
+                "headers": {MCP_PROTOCOL_VERSION_HEADER: version},
+            }
+            return await self._dispatcher.send_raw_request("server/discover", params, opts)
+
+        try:
+            raw = await probe(MODERN_PROTOCOL_VERSIONS[-1])
+        except MCPError as e:
+            if e.code == UNSUPPORTED_PROTOCOL_VERSION:
+                try:
+                    data = types.UnsupportedProtocolVersionErrorData.model_validate(e.error.data)
+                except ValidationError:
+                    raise e from None
+                mutual = [v for v in MODERN_PROTOCOL_VERSIONS if v in data.supported]
+                if not mutual:
+                    raise
+                raw = await probe(mutual[-1])
+            elif e.code in (METHOD_NOT_FOUND, REQUEST_TIMEOUT):
+                return await self.initialize()
+            else:
+                raise
+
+        result = types.DiscoverResult.model_validate(raw)
+        self.adopt(result)
+        assert self._initialize_result is not None
+        return self._initialize_result
+
     @property
     def initialize_result(self) -> types.InitializeResult | None:
         """The server's InitializeResult. None until `initialize()` or `adopt()`.

tests/client/test_client.py

@@ -14,6 +14,7 @@
 from mcp import MCPError, types
 from mcp.client._memory import InMemoryTransport
 from mcp.client.client import Client
+from mcp.client.streamable_http import streamable_http_client
 from mcp.server import Server, ServerRequestContext
 from mcp.server.mcpserver import MCPServer
 from mcp.types import (
@@ -37,6 +38,7 @@
     Tool,
     ToolsCapability,
 )
+from tests.interaction._connect import BASE_URL, mounted_app
 
 pytestmark = pytest.mark.anyio
 
@@ -359,3 +361,17 @@ async def check_context() -> str:
     assert result.content[0].text == "client_value", (  # type: ignore[union-attr]
         "Server handler did not see the sender's contextvars.Context"
     )
+
+
+async def test_client_auto_mode_probes_discover_then_adopts(simple_server: Server) -> None:
+    """`mode='auto'` over an in-process HTTP transport: the `server/discover` probe
+    reaches the modern entry and the negotiated protocol version is adopted without
+    an `initialize` handshake. Runs over HTTP because the in-memory runner gates
+    `server/discover` behind the init handshake."""
+    with anyio.fail_after(5):
+        async with (
+            mounted_app(simple_server) as (http, _),
+            Client(streamable_http_client(f"{BASE_URL}/mcp", http_client=http), mode="auto") as client,
+        ):
+            assert client.initialize_result.protocol_version == "2026-07-28"
+            assert (await client.list_resources()).resources[0].name == "Test Resource"

tests/client/test_session.py

@@ -25,7 +25,9 @@
     INVALID_PARAMS,
     LATEST_PROTOCOL_VERSION,
     METHOD_NOT_FOUND,
+    PROTOCOL_VERSION_META_KEY,
     REQUEST_TIMEOUT,
+    UNSUPPORTED_PROTOCOL_VERSION,
     CallToolResult,
     Implementation,
     InitializedNotification,
@@ -1435,3 +1437,195 @@ async def test_send_notification_after_close_is_dropped_silently():
     finally:
         for s in (s2c_send, s2c_recv, c2s_send, c2s_recv):
             s.close()
+
+
+# --- discover() ladder ---
+
+
+class _ScriptedDispatcher:
+    """Records every `send_raw_request` and plays back scripted answers in order.
+
+    A script entry that is an `Exception` is raised; a dict is returned."""
+
+    def __init__(self, *script: dict[str, Any] | Exception) -> None:
+        self.calls: list[tuple[str, Mapping[str, Any] | None]] = []
+        self.notifies: list[str] = []
+        self._script: list[dict[str, Any] | Exception] = list(script)
+
+    async def run(
+        self,
+        on_request: OnRequest,
+        on_notify: OnNotify,
+        *,
+        task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STATUS_IGNORED,
+    ) -> None:
+        task_status.started()
+        await anyio.sleep_forever()
+
+    async def send_raw_request(
+        self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None
+    ) -> dict[str, Any]:
+        self.calls.append((method, params))
+        item = self._script.pop(0)
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        self.notifies.append(method)
+
+
+def _discover_result_dict() -> dict[str, Any]:
+    return types.DiscoverResult(
+        supported_versions=["2026-07-28"],
+        capabilities=ServerCapabilities(),
+        server_info=Implementation(name="stub", version="0"),
+    ).model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+def _initialize_result_dict() -> dict[str, Any]:
+    return InitializeResult(
+        protocol_version=HANDSHAKE_PROTOCOL_VERSIONS[-1],
+        capabilities=ServerCapabilities(),
+        server_info=Implementation(name="stub", version="0"),
+    ).model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+@pytest.mark.anyio
+async def test_discover_adopts_the_returned_result_and_installs_the_modern_stamp() -> None:
+    """SDK-defined: a successful `server/discover` is adopted and subsequent requests
+    carry the modern `_meta` envelope (protocol version + client info + capabilities)."""
+    dispatcher = _ScriptedDispatcher(_discover_result_dict(), {})
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+            assert session.protocol_version == "2026-07-28"
+            await session.send_ping()
+    ping_method, ping_params = dispatcher.calls[-1]
+    assert ping_method == "ping"
+    assert ping_params is not None
+    assert ping_params["_meta"][PROTOCOL_VERSION_META_KEY] == "2026-07-28"
+
+
+@pytest.mark.anyio
+async def test_discover_retries_once_on_unsupported_version_then_adopts() -> None:
+    """Spec SHOULD: a -32022 reply that names a mutually-supported version
+    triggers exactly one retry at that version, and the retry's result is adopted."""
+    dispatcher = _ScriptedDispatcher(
+        MCPError(
+            UNSUPPORTED_PROTOCOL_VERSION,
+            "unsupported",
+            data={"supported": ["2026-07-28"], "requested": "2026-07-28"},
+        ),
+        _discover_result_dict(),
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+    assert session.protocol_version == "2026-07-28"
+    assert [m for m, _ in dispatcher.calls] == ["server/discover", "server/discover"]
+
+
+@pytest.mark.anyio
+async def test_discover_raises_when_retry_intersection_is_empty() -> None:
+    """Spec SHOULD: a -32022 reply whose `supported` list shares nothing with the
+    client's modern versions is unrecoverable — the original error is re-raised
+    without a second probe."""
+    dispatcher = _ScriptedDispatcher(
+        MCPError(
+            UNSUPPORTED_PROTOCOL_VERSION,
+            "unsupported",
+            data={"supported": ["1999-01-01"], "requested": "2026-07-28"},
+        ),
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            with pytest.raises(MCPError) as exc:
+                await session.discover()
+            assert exc.value.error.code == UNSUPPORTED_PROTOCOL_VERSION
+    assert [m for m, _ in dispatcher.calls] == ["server/discover"]
+
+
+@pytest.mark.anyio
+async def test_discover_falls_back_to_initialize_on_method_not_found() -> None:
+    """Spec SHOULD: a legacy server that answers -32601 to `server/discover` is
+    transparently driven through the handshake instead."""
+    dispatcher = _ScriptedDispatcher(
+        MCPError(METHOD_NOT_FOUND, "Method not found"),
+        _initialize_result_dict(),
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+    assert session.protocol_version in HANDSHAKE_PROTOCOL_VERSIONS
+    assert [m for m, _ in dispatcher.calls] == ["server/discover", "initialize"]
+    assert dispatcher.notifies == ["notifications/initialized"]
+
+
+@pytest.mark.anyio
+async def test_discover_falls_back_to_initialize_on_timeout() -> None:
+    """Spec SHOULD: a `REQUEST_TIMEOUT` from the dispatcher is treated the same as
+    method-not-found — the server is presumed legacy and `initialize()` runs."""
+    dispatcher = _ScriptedDispatcher(
+        MCPError(REQUEST_TIMEOUT, "timed out"),
+        _initialize_result_dict(),
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.discover()
+    assert session.protocol_version in HANDSHAKE_PROTOCOL_VERSIONS
+    assert [m for m, _ in dispatcher.calls] == ["server/discover", "initialize"]
+
+
+@pytest.mark.anyio
+async def test_discover_reraises_on_other_errors() -> None:
+    """SDK-defined: any error outside the retry/fallback ladder propagates verbatim
+    — `discover()` does not mask server failures by falling back to `initialize()`."""
+    dispatcher = _ScriptedDispatcher(MCPError(INTERNAL_ERROR, "boom"))
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            with pytest.raises(MCPError) as exc:
+                await session.discover()
+            assert exc.value.error.code == INTERNAL_ERROR
+    assert [m for m, _ in dispatcher.calls] == ["server/discover"]
+
+
+@pytest.mark.anyio
+async def test_discover_validates_the_response_shape_before_adopting() -> None:
+    """SDK-defined: the raw response is run through `DiscoverResult` validation
+    before any state is installed, so a malformed reply leaves the session
+    un-adopted rather than half-configured."""
+    dispatcher = _ScriptedDispatcher({"supportedVersions": ["2026-07-28"]})
+    session = ClientSession(dispatcher=dispatcher)
+    with anyio.fail_after(5):
+        async with session:
+            with pytest.raises(ValidationError):
+                await session.discover()
+            assert session.protocol_version is None
+
+
+@pytest.mark.anyio
+async def test_discover_is_idempotent_and_returns_the_cached_result() -> None:
+    """SDK-defined: a second `discover()` returns the already-adopted result without
+    re-probing — the script holds exactly one entry, so a second wire call would
+    `IndexError` on the empty script."""
+    dispatcher = _ScriptedDispatcher(_discover_result_dict())
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            first = await session.discover()
+            assert await session.discover() is first
+    assert [m for m, _ in dispatcher.calls] == ["server/discover"]
+
+
+@pytest.mark.anyio
+async def test_discover_reraises_unsupported_version_with_malformed_error_data() -> None:
+    """SDK-defined: a -32022 reply whose `data` is not a valid
+    `UnsupportedProtocolVersionErrorData` payload is unrecoverable — the original
+    error is re-raised without a retry probe."""
+    dispatcher = _ScriptedDispatcher(MCPError(UNSUPPORTED_PROTOCOL_VERSION, "unsupported", data="not-an-object"))
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            with pytest.raises(MCPError) as exc:
+                await session.discover()
+            assert exc.value.error.code == UNSUPPORTED_PROTOCOL_VERSION
+    assert [m for m, _ in dispatcher.calls] == ["server/discover"]