Flip Client default mode to 'auto'

The default Client(...) now probes server/discover and falls back to
initialize() (via negotiate_auto's denylist). For an in-process Server,
the default path is now DirectDispatcher per-request rather than the
legacy InMemoryTransport stream loop.

DirectDispatcher gains raise_handler_exceptions (matching
JSONRPCDispatcher's knob): True chains the original exception via
__cause__; False sanitizes to MCPError(INTERNAL_ERROR). modern_on_request
collapses to a pure envelope-builder (no exception ladder of its own),
and Client threads raise_exceptions into create_direct_dispatcher_pair.

Tests that exercise legacy-specific semantics — server-initiated
sampling/elicitation push, message_handler delivery, ping,
InMemoryTransport mechanics, JSON-RPC wire-shape recording — are pinned
to mode='legacy' explicitly (~64 sites across 26 test files plus the
client_via_http / connect_over_sse / auth-harness helpers). These are
census-driven, not failure-driven: ~23 sites would have passed under
'auto' but silently stopped testing their subject.

Client.send_ping() is deprecated (ping is removed from 2026-07-28); it
only works under mode='legacy'.

docs/migration.md gains a section explaining the default change and when
to pin mode='legacy'; docs/testing.md notes the same for test authors.

Author: maxisbey

docs/migration.md

@@ -352,7 +352,15 @@ version = session.protocol_version
 
 The raw handshake result is also retained: `session.initialize_result` is set after `initialize()` (≤2025-11-25 servers — including `stateless_http=True` servers, which still answer `initialize`); `session.discover_result` is set after `discover()` (2026-07-28+ servers). At most one is non-`None`.
 
-On the high-level `Client`, `client.server_capabilities`, `client.server_info`, and `client.protocol_version` are non-nullable inside the context manager. `client.instructions` remains `str | None` since the server may omit it. (The lowlevel `ClientSession` still lets you call methods before any handshake, as in v1; `Client` always handshakes on enter.)
+On the high-level `Client`, `client.server_capabilities`, `client.server_info`, and `client.protocol_version` are non-nullable inside the context manager. `client.instructions` remains `str | None` since the server may omit it. (The lowlevel `ClientSession` still lets you call methods before any handshake, as in v1; `Client` always connects on enter — by default it probes `server/discover` and falls back to the initialize handshake.)
+
+### `Client` defaults to `mode='auto'`
+
+In v1, connecting to a server always performed the `initialize` handshake. In v2, `Client` defaults to `mode='auto'`: on enter it probes `server/discover` and, if the server doesn't support it, falls back to the `initialize` handshake. Pass `mode='legacy'` to force the initialize handshake and reproduce v1's byte-identical pre-2026 behavior, or pass a modern protocol-version string (e.g. `mode='2026-07-28'`) to pin a version without probing.
+
+For an in-process `Client(server)` (where `server` is a `Server` or `MCPServer` instance), `mode='auto'` dispatches calls directly through `DirectDispatcher` with no JSON-RPC framing. Pass `mode='legacy'` if you need the in-memory JSON-RPC transport that v1 used.
+
+`Client.send_ping()` is deprecated (ping is removed in 2026-07-28); pin `mode='legacy'` if you need it.
 
 ### `McpError` renamed to `MCPError`
 
@@ -832,7 +840,7 @@ async with Client(server) as client:
     result = await client.call_tool("my_tool", {"x": 1})
 ```
 
-`Client` accepts the same callback parameters the old helper did (`sampling_callback`, `list_roots_callback`, `logging_callback`, `message_handler`, `elicitation_callback`, `client_info`) plus `raise_exceptions` to surface server-side errors.
+`Client` accepts the same callback parameters the old helper did (`sampling_callback`, `list_roots_callback`, `logging_callback`, `message_handler`, `elicitation_callback`, `client_info`) plus `raise_exceptions` to surface server-side errors and `mode` to control version negotiation (`'auto'` by default; `'legacy'` reproduces v1's initialize-only handshake).
 
 If you need direct access to the underlying `ClientSession` and memory streams (e.g., for low-level transport testing), `create_client_server_memory_streams` is still available in `mcp.shared.memory`:
 

docs/testing.md

@@ -74,4 +74,9 @@ async def test_call_add_tool(client: Client):
 1. If you are using `trio`, you should set `"trio"` as the `anyio_backend`. Check more information in the [anyio documentation](https://anyio.readthedocs.io/en/stable/testing.html#specifying-the-backends-to-run-on).
 2. The `client` fixture creates a connected client that can be reused across multiple tests.
 
+!!! note
+    `Client(app)` connects in-process and is era-neutral by default — it probes the server and picks the
+    appropriate protocol path. Pin `mode='legacy'` if your test exercises legacy-specific semantics
+    (sampling/elicitation push, `message_handler`).
+
 There you go! You can now extend your tests to cover more scenarios.

pyproject.toml

@@ -220,6 +220,9 @@ filterwarnings = [
     # 2026-07-28 restricts progress to server->client; the client send path is
     # advisory-deprecated and a handful of tests still exercise it.
     "ignore:Client-to-server progress is deprecated as of 2026-07-28.*:mcp.MCPDeprecationWarning",
+    # 2026-07-28 drops ping; Client.send_ping() is advisory-deprecated and the
+    # legacy interaction/transport tests still drive it.
+    "ignore:ping is removed as of 2026-07-28.*:mcp.MCPDeprecationWarning",
 ]
 
 [tool.markdown.lint]

src/mcp/client/client.py

@@ -78,10 +78,10 @@ async def connect(exit_stack: AsyncExitStack, mode: ConnectMode, raise_exception
             read_stream, write_stream = await exit_stack.enter_async_context(transport)
             return JSONRPCDispatcher(read_stream, write_stream)
         lifespan_state = await exit_stack.enter_async_context(server.lifespan(server))
-        client_disp, server_disp = create_direct_dispatcher_pair()
+        client_disp, server_disp = create_direct_dispatcher_pair(raise_handler_exceptions=raise_exceptions)
         tg = await exit_stack.enter_async_context(anyio.create_task_group())
         exit_stack.callback(server_disp.close)
-        on_request = modern_on_request(server, lifespan_state, raise_exceptions=raise_exceptions)
+        on_request = modern_on_request(server, lifespan_state)
         await tg.start(server_disp.run, on_request, _no_inbound_client_notifications)
         return client_disp
 
@@ -151,7 +151,7 @@ async def main():
     server: Server[Any] | MCPServer | Transport | str
     """The MCP server to connect to.
 
-    If the server is a `Server` or `MCPServer` instance, it will be wrapped in an `InMemoryTransport`.
+    If the server is a `Server` or `MCPServer` instance, it will be connected in-process.
     If the server is a URL string, it will be used as the URL for a `streamable_http_client` transport.
     If the server is a `Transport` instance, it will be used directly.
     """
@@ -181,11 +181,14 @@ async def main():
     client_info: Implementation | None = None
     """Client implementation info to send to server."""
 
-    # TODO(maxisbey): flip default to 'auto' once the in-proc test suite is era-decoupled.
-    mode: ConnectMode = "legacy"
-    """'legacy' performs the initialize handshake. 'auto' probes server/discover and falls back to initialize()
-    on legacy servers. A modern 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: ConnectMode = "auto"
+    """How to negotiate the protocol version.
+
+    'auto' (the default) probes `server/discover` and falls back to the initialize handshake on legacy servers;
+    for an in-process `Server`/`MCPServer` it dispatches directly without JSON-RPC framing. 'legacy' forces the
+    initialize handshake (byte-identical pre-2026 behavior). A modern protocol-version string (e.g. '2026-07-28')
+    adopts that version directly without a probe — 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.
@@ -301,6 +304,10 @@ def instructions(self) -> str | None:
         """Server-provided instructions text, if any."""
         return self.session.instructions
 
+    @deprecated(
+        "ping is removed as of 2026-07-28; the method only works under mode='legacy'.",
+        category=MCPDeprecationWarning,
+    )
     async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
         """Send a ping request to the server."""
         return await self.session.send_ping(meta=meta)

src/mcp/server/runner.py

@@ -496,18 +496,14 @@ async def serve_one(
         await aclose_shielded(connection)
 
 
-def modern_on_request(
-    server: Server[LifespanT], lifespan_state: LifespanT, *, raise_exceptions: bool = False
-) -> OnRequest:
+def modern_on_request(server: Server[LifespanT], lifespan_state: LifespanT) -> OnRequest:
     """Return an `OnRequest` callback that serves each call via `serve_one` with a fresh per-request `Connection`.
 
     Wire this into the server side of a `DirectDispatcher` peer-pair to drive an
     in-process server on the modern per-request-envelope path (each request
     carries protocol version, client info, and capabilities in `params._meta`;
-    no `initialize` handshake). ``raise_exceptions`` lets unmapped handler
-    exceptions propagate to the caller for debuggable in-process testing;
-    otherwise they are sanitized to `MCPError(INTERNAL_ERROR)` so the in-process
-    path matches the wire path's leak guard.
+    no `initialize` handshake). Like `serve_one`, this raises whatever the
+    handler chain raises - the dispatcher owns the exception-to-error mapping.
     """
 
     async def handle(
@@ -519,16 +515,6 @@ async def handle(
             meta.get(CLIENT_INFO_META_KEY),
             meta.get(CLIENT_CAPABILITIES_META_KEY),
         )
-        try:
-            return await serve_one(server, dctx, method, params, connection=connection, lifespan_state=lifespan_state)
-        except (MCPError, ValidationError):
-            # DirectDispatcher's ladder maps these onward; this layer only owns the raise_exceptions
-            # decision for unmapped exceptions, which DirectDispatcher would otherwise leak via str(exc).
-            raise
-        except Exception:
-            if raise_exceptions:
-                raise
-            logger.exception("request handler raised")
-            raise MCPError(code=INTERNAL_ERROR, message="Internal server error") from None
+        return await serve_one(server, dctx, method, params, connection=connection, lifespan_state=lifespan_state)
 
     return handle

src/mcp/shared/direct_dispatcher.py

@@ -9,8 +9,10 @@
   (`ServerRunner`, `Context`, `Connection`) without wire-level moving parts
 * embed a server in-process when the JSON-RPC overhead is unnecessary
 
-Unlike `JSONRPCDispatcher`, exceptions raised in a handler propagate directly
-to the caller - there is no exception-to-`ErrorData` boundary here.
+Like `JSONRPCDispatcher`, this is an exception-to-error boundary: a handler
+exception surfaces to the caller as `MCPError`. The `raise_handler_exceptions`
+knob controls whether unmapped exceptions are sanitized (matching the wire
+path) or chained as ``__cause__`` for in-process debugging.
 """
 
 from __future__ import annotations
@@ -96,8 +98,9 @@ class DirectDispatcher:
     they are silently dropped.
     """
 
-    def __init__(self, transport_ctx: TransportContext):
+    def __init__(self, transport_ctx: TransportContext, *, raise_handler_exceptions: bool = True):
         self._transport_ctx = transport_ctx
+        self._raise_handler_exceptions = raise_handler_exceptions
         self._peer: DirectDispatcher | None = None
         self._on_request: OnRequest | None = None
         self._on_notify: OnNotify | None = None
@@ -235,7 +238,14 @@ async def _dispatch_request(
                     # tests see what runner-over-JSONRPC would.
                     raise MCPError(code=INVALID_PARAMS, message="Invalid request parameters", data="") from e
                 except Exception as e:
-                    raise MCPError(code=INTERNAL_ERROR, message=str(e)) from e
+                    # Single owner of the in-proc exception-to-error policy (mirrors
+                    # JSONRPCDispatcher / `_streamable_http_modern._to_jsonrpc_response`
+                    # for the wire paths). True chains the original for in-process
+                    # debugging; False sanitizes to match the wire path's leak guard.
+                    if self._raise_handler_exceptions:
+                        raise MCPError(code=INTERNAL_ERROR, message=str(e)) from e
+                    logger.exception("request handler raised")
+                    raise MCPError(code=INTERNAL_ERROR, message="Internal server error") from None
         except TimeoutError:
             raise MCPError(
                 code=REQUEST_TIMEOUT,
@@ -259,21 +269,27 @@ def create_direct_dispatcher_pair(
     *,
     can_send_request: bool = True,
     headers: Mapping[str, str] | None = None,
+    raise_handler_exceptions: bool = True,
 ) -> tuple[DirectDispatcher, DirectDispatcher]:
     """Create two `DirectDispatcher` instances wired to each other.
 
     Args:
         can_send_request: Sets `TransportContext.can_send_request` on both
             sides. Pass `False` to simulate a transport with no back-channel.
         headers: Sets `TransportContext.headers` on both sides.
+        raise_handler_exceptions: When `True` (the default - this is an
+            in-process debugging substrate), an unmapped handler exception
+            reaches the caller as `MCPError` with the original chained as
+            ``__cause__``. When `False` it is sanitized to an opaque
+            `INTERNAL_ERROR` so the in-process path matches the wire.
 
     Returns:
         A `(client, server)` pair. The wiring is symmetric, so the roles
         are conventional only.
     """
     ctx = TransportContext(kind=DIRECT_TRANSPORT_KIND, can_send_request=can_send_request, headers=headers)
-    client = DirectDispatcher(ctx)
-    server = DirectDispatcher(ctx)
+    client = DirectDispatcher(ctx, raise_handler_exceptions=raise_handler_exceptions)
+    server = DirectDispatcher(ctx, raise_handler_exceptions=raise_handler_exceptions)
     client.connect_to(server)
     server.connect_to(client)
     return client, server

tests/client/test_client.py

@@ -107,7 +107,7 @@ def greeting_prompt(name: str) -> str:
 
 async def test_client_is_initialized(app: MCPServer):
     """Test that the client is initialized after entering context."""
-    async with Client(app) as client:
+    async with Client(app, mode="legacy") as client:
         assert client.server_capabilities == snapshot(
             ServerCapabilities(
                 experimental={},
@@ -121,7 +121,7 @@ async def test_client_is_initialized(app: MCPServer):
 
 async def test_client_exposes_negotiated_protocol_version(app: MCPServer):
     """The negotiated protocol version is readable after initialization."""
-    async with Client(app) as client:
+    async with Client(app, mode="legacy") as client:
         assert client.protocol_version == LATEST_HANDSHAKE_VERSION
 
 
@@ -137,8 +137,8 @@ async def test_client_with_simple_server(simple_server: Server):
 
 
 async def test_client_send_ping(app: MCPServer):
-    async with Client(app) as client:
-        result = await client.send_ping()
+    async with Client(app, mode="legacy") as client:
+        result = await client.send_ping()  # pyright: ignore[reportDeprecated]
         assert result == snapshot(EmptyResult())
 
 
@@ -278,27 +278,28 @@ async def handle_progress(ctx: ServerRequestContext, params: types.ProgressNotif
 
     server = Server(name="test_server", on_progress=handle_progress)
 
-    async with Client(server) as client:
-        await client.send_progress_notification(progress_token="token123", progress=50.0)  # pyright: ignore[reportDeprecated]
-        await event.wait()
-        assert received_from_client == snapshot({"progress_token": "token123", "progress": 50.0})
+    with anyio.fail_after(5):
+        async with Client(server, mode="legacy") as client:
+            await client.send_progress_notification(progress_token="token123", progress=50.0)  # pyright: ignore[reportDeprecated]
+            await event.wait()
+            assert received_from_client == snapshot({"progress_token": "token123", "progress": 50.0})
 
 
 async def test_client_subscribe_resource(simple_server: Server):
-    async with Client(simple_server) as client:
+    async with Client(simple_server, mode="legacy") as client:
         result = await client.subscribe_resource("memory://test")
         assert result == snapshot(EmptyResult())
 
 
 async def test_client_unsubscribe_resource(simple_server: Server):
-    async with Client(simple_server) as client:
+    async with Client(simple_server, mode="legacy") as client:
         result = await client.unsubscribe_resource("memory://test")
         assert result == snapshot(EmptyResult())
 
 
 async def test_client_set_logging_level(simple_server: Server):
     """Test setting logging level."""
-    async with Client(simple_server) as client:
+    async with Client(simple_server, mode="legacy") as client:
         result = await client.set_logging_level("debug")  # pyright: ignore[reportDeprecated]
         assert result == snapshot(EmptyResult())
 
@@ -361,7 +362,7 @@ def test_client_with_url_initializes_streamable_http_transport():
 
 async def test_client_uses_transport_directly(app: MCPServer):
     transport = InMemoryTransport(app)
-    async with Client(transport) as client:
+    async with Client(transport, mode="legacy") as client:
         result = await client.call_tool("greet", {"name": "Transport"})
         assert result == snapshot(
             CallToolResult(

tests/client/test_list_methods_cursor.py

@@ -64,7 +64,7 @@ async def test_list_methods_params_parameter(
 
     See: https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/pagination#request-format
     """
-    async with Client(full_featured_server) as client:
+    async with Client(full_featured_server, mode="legacy") as client:
         spies = stream_spy()
 
         # Test without params (omitted)

tests/client/test_list_roots_callback.py

@@ -31,7 +31,7 @@ async def test_list_roots(context: Context, message: str):
         return True
 
     # Test with list_roots callback
-    async with Client(server, list_roots_callback=list_roots_callback) as client:
+    async with Client(server, list_roots_callback=list_roots_callback, mode="legacy") as client:
         # Make a request to trigger sampling callback
         result = await client.call_tool("test_list_roots", {"message": "test message"})
         assert result.is_error is False
@@ -41,7 +41,7 @@ async def test_list_roots(context: Context, message: str):
     # Without a list_roots callback the client responds with an MCPError, which the
     # tool body doesn't catch — the wrapper re-raises it as a top-level JSON-RPC
     # error rather than wrapping it as an isError result.
-    async with Client(server) as client:
+    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

tests/client/test_logging_callback.py

@@ -64,6 +64,7 @@ async def message_handler(
         server,
         logging_callback=logging_collector,
         message_handler=message_handler,
+        mode="legacy",
     ) as client:
         # First verify our test tool works
         result = await client.call_tool("test_tool", {})