serve_one returns dict; Client accessor and re-entry guard fixes

serve_one now returns the kernel's dict result and lets exceptions
propagate; the modern HTTP entry composes to_jsonrpc_response around it
directly, and modern_on_request no longer round-trips through
JSONRPCError on the in-process path. The dctx.request_id assert drops.

Client: the protocol_version/server_info/server_capabilities accessors
now raise the same RuntimeError as .session instead of bare assert.
__aenter__ publishes self._session only after the handshake succeeds, and
a separate _entered flag makes the one-shot re-entry guard explicit.
_drop_notify is renamed to say which direction it sinks. Adds a TODO at
mode='legacy' for the eventual default flip and a TODO above the
accessors for the connected-view shape.

migration.md: point at the era-neutral session/client accessors instead
of initialize_result, and stop listing client.instructions as
non-nullable.

The legacy-mode connect test now passes mode='legacy' explicitly so it
asserts what that mode does, not what the default is.

Author: maxisbey

docs/migration.md

@@ -161,7 +161,7 @@ Note: `sse_client` retains its `headers`, `timeout`, `sse_read_timeout`, and `au
 
 ### `StreamableHTTPTransport.protocol_version` attribute removed
 
-The transport no longer holds per-connection protocol state; era-dependent headers (e.g. `MCP-Protocol-Version`) are now supplied per-message by the session. If you were reading `transport.protocol_version` to learn the negotiated version, read it from `session.initialize_result.protocol_version` instead.
+The transport no longer holds per-connection protocol state; era-dependent headers (e.g. `MCP-Protocol-Version`) are now supplied per-message by the session. If you were reading `transport.protocol_version` to learn the negotiated version, read `session.protocol_version` (or `client.protocol_version` on the high-level `Client`) instead.
 
 ### `terminate_windows_process` removed
 
@@ -330,9 +330,9 @@ result = await session.list_resources(params=PaginatedRequestParams(cursor="next
 result = await session.list_tools(params=PaginatedRequestParams(cursor="next_page_token"))
 ```
 
-### `ClientSession.get_server_capabilities()` replaced by `initialize_result` property
+### `ClientSession.get_server_capabilities()` replaced by era-neutral accessors
 
-`ClientSession` now stores the full `InitializeResult` via an `initialize_result` property. This provides access to `server_info`, `capabilities`, `instructions`, and the negotiated `protocol_version` through a single property. The `get_server_capabilities()` method has been removed.
+`ClientSession` now exposes the negotiated server metadata as properties: `server_capabilities`, `server_info`, `instructions`, and `protocol_version`. These are populated by whichever connection step ran (`initialize()` for ≤2025-11-25 servers, `discover()` for 2026-07-28+). The `get_server_capabilities()` method has been removed.
 
 **Before (v1):**
 
@@ -344,15 +344,15 @@ capabilities = session.get_server_capabilities()
 **After (v2):**
 
 ```python
-result = session.initialize_result
-if result is not None:
-    capabilities = result.capabilities
-    server_info = result.server_info
-    instructions = result.instructions
-    version = result.protocol_version
+capabilities = session.server_capabilities
+server_info = session.server_info
+instructions = session.instructions
+version = session.protocol_version
 ```
 
-The high-level `Client.initialize_result` returns the same `InitializeResult` but is non-nullable — initialization is guaranteed inside the context manager, so no `None` check is needed. Like `session.initialize_result`, this replaces v1's `ClientSession.get_server_capabilities()`; use `client.initialize_result.capabilities` instead.
+The raw handshake result is also retained as `session.initialize_result` (legacy path) or `session.discover_result` (modern path) — exactly 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.
 
 ### `McpError` renamed to `MCPError`
 
@@ -770,9 +770,9 @@ async def my_tool(ctx: Context[MyLifespanState]) -> str: ...
 
 ### Version constants
 
-`SUPPORTED_PROTOCOL_VERSIONS` is deprecated — it's now the union of `HANDSHAKE_PROTOCOL_VERSIONS` (initialize-handshake versions) and `MODERN_PROTOCOL_VERSIONS` (per-request-envelope versions). If you were using it to mean "versions the initialize handshake accepts", switch to `HANDSHAKE_PROTOCOL_VERSIONS`.
+`SUPPORTED_PROTOCOL_VERSIONS` is deprecated — it's now the union of `HANDSHAKE_PROTOCOL_VERSIONS` (initialize-handshake versions) and `MODERN_PROTOCOL_VERSIONS` (per-request-envelope versions). If you were using it to mean "versions the initialize handshake accepts", switch to `HANDSHAKE_PROTOCOL_VERSIONS`. Named scalars derived from these tuples are now exported alongside them — `LATEST_HANDSHAKE_VERSION`, `LATEST_MODERN_VERSION`, `OLDEST_SUPPORTED_VERSION` — so prefer those over indexing the tuples directly.
 
-`LATEST_PROTOCOL_VERSION` now reflects the newest protocol revision the SDK supports (`2026-07-28`). Code that used it to mean "the version `.initialize()` offers" should switch to `HANDSHAKE_PROTOCOL_VERSIONS[-1]`.
+`LATEST_PROTOCOL_VERSION` now reflects the newest protocol revision the SDK supports (`2026-07-28`). Code that used it to mean "the version `.initialize()` offers" should switch to `LATEST_HANDSHAKE_VERSION`.
 
 ### `ProgressContext` and `progress()` context manager removed
 

src/mcp/client/client.py

@@ -5,7 +5,7 @@
 from collections.abc import Mapping
 from contextlib import AsyncExitStack
 from dataclasses import KW_ONLY, dataclass, field
-from typing import Any, Literal
+from typing import Any, Literal, TypeVar
 
 import anyio
 from typing_extensions import deprecated
@@ -48,6 +48,20 @@
 initialize), or a modern protocol-version string (adopt directly). The ``str`` arm is for
 forward-compat; ``Client.__post_init__`` rejects anything outside that set at construction."""
 
+_T = TypeVar("_T")
+
+
+def _connected(value: _T | None) -> _T:
+    """Narrow a post-handshake session attribute from ``T | None`` to ``T``.
+
+    ``Client.__aenter__`` only assigns ``_session`` after the handshake succeeds, so inside
+    ``async with Client(...)`` these attributes are always populated; the ``.session`` gate
+    raises before this is reached otherwise. The guard exists for pyright, not runtime.
+    """
+    if value is None:  # pragma: no cover
+        raise RuntimeError("Client must be used within an async context manager")
+    return value
+
 
 def _synthesize_discover(protocol_version: str) -> types.DiscoverResult:
     return types.DiscoverResult(
@@ -60,11 +74,14 @@ def _synthesize_discover(protocol_version: str) -> types.DiscoverResult:
     )
 
 
-async def _drop_notify(_dctx: Any, _method: str, _params: Mapping[str, Any] | None) -> None:
-    """Server-side ``OnNotify`` for the modern in-process path: client→server notifications are dropped.
+async def _no_inbound_client_notifications(_dctx: Any, _method: str, _params: Mapping[str, Any] | None) -> None:
+    """Server-side inbound ``OnNotify`` for the modern in-process path — receives nothing.
 
-    The per-request driver (`serve_one`) has no notification dispatch table; progress and
-    cancellation travel via `CallOptions` on the `DirectDispatcher`, not as JSON-RPC notifies.
+    At 2026-07-28 the spec defines no client→server notifications: ``initialized`` and
+    ``roots/list_changed`` are removed, and cancellation is structural (anyio scope cancel
+    through the direct await, not a notify). Server→client notifications (progress, log
+    messages) flow the other way via the per-request ``DispatchContext`` into the client's
+    callbacks, and are not seen here.
     """
 
 
@@ -127,6 +144,8 @@ 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
+    # and the probe-timeout fallback is transport-aware (stdio→fallback / HTTP→reject).
     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
@@ -139,6 +158,7 @@ async def main():
     elicitation_callback: ElicitationFnT | None = None
     """Callback for handling elicitation requests."""
 
+    _entered: bool = field(init=False, default=False)
     _session: ClientSession | None = field(init=False, default=None)
     _exit_stack: AsyncExitStack | None = field(init=False, default=None)
     _transport: Transport | None = field(init=False, default=None)
@@ -175,7 +195,7 @@ async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
             tg = await exit_stack.enter_async_context(anyio.create_task_group())
             exit_stack.callback(server_disp.close)
             on_request = modern_on_request(self._inproc_server, lifespan_state, raise_exceptions=self.raise_exceptions)
-            await tg.start(server_disp.run, on_request, _drop_notify)
+            await tg.start(server_disp.run, on_request, _no_inbound_client_notifications)
             dispatcher = client_disp
             read_stream = write_stream = None
         else:
@@ -201,27 +221,31 @@ async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
 
     async def __aenter__(self) -> Client:
         """Enter the async context manager."""
-        if self._session is not None:
+        if self._entered:
             raise RuntimeError("Client is already entered; cannot reenter")
+        self._entered = True
 
         async with AsyncExitStack() as exit_stack:
             session = await self._build_session(exit_stack)
-            self._session = await exit_stack.enter_async_context(session)
+            session = await exit_stack.enter_async_context(session)
 
             if self.mode == "legacy":
-                await self._session.initialize()
+                await session.initialize()
             elif self.mode == "auto":
                 try:
-                    await self._session.discover()
+                    await session.discover()
                 except MCPError as e:
                     if e.code in (METHOD_NOT_FOUND, REQUEST_TIMEOUT):
-                        await self._session.initialize()
+                        await session.initialize()
                     else:
                         raise
             else:
-                self._session.adopt(self.prior_discover or _synthesize_discover(self.mode))
+                session.adopt(self.prior_discover or _synthesize_discover(self.mode))
 
-            # Transfer ownership to self for __aexit__ to handle
+            # Only publish the session after the handshake succeeds, so `_session is not None`
+            # implies the protocol_version/server_info/server_capabilities are populated. If the
+            # handshake raised above, the local exit_stack unwinds the transport for us.
+            self._session = session
             self._exit_stack = exit_stack.pop_all()
             return self
 
@@ -244,26 +268,24 @@ def session(self) -> ClientSession:
             raise RuntimeError("Client must be used within an async context manager")
         return self._session
 
+    # TODO(maxisbey): the by-construction shape is for __aenter__ to return a connected-view
+    # type whose protocol_version/server_info/server_capabilities are non-Optional fields,
+    # eliminating these guards (and the one in .session). Same family as resolving the
+    # transport/connector at __post_init__ so the Optional internal fields disappear.
     @property
     def protocol_version(self) -> str:
         """Negotiated protocol version (set by initialize/discover/adopt during ``__aenter__``)."""
-        version = self.session.protocol_version
-        assert version is not None
-        return version
+        return _connected(self.session.protocol_version)
 
     @property
     def server_info(self) -> Implementation:
         """Server name/version (set by initialize/discover/adopt during ``__aenter__``)."""
-        info = self.session.server_info
-        assert info is not None
-        return info
+        return _connected(self.session.server_info)
 
     @property
     def server_capabilities(self) -> ServerCapabilities:
         """Server capabilities (set by initialize/discover/adopt during ``__aenter__``)."""
-        caps = self.session.server_capabilities
-        assert caps is not None
-        return caps
+        return _connected(self.session.server_capabilities)
 
     @property
     def instructions(self) -> str | None:

src/mcp/server/_streamable_http_modern.py

@@ -25,7 +25,7 @@
 from starlette.types import Receive, Scope, Send
 
 from mcp.server.connection import Connection
-from mcp.server.runner import serve_one
+from mcp.server.runner import serve_one, to_jsonrpc_response
 from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
 from mcp.shared.dispatcher import CallOptions
 from mcp.shared.exceptions import NoBackChannelError
@@ -193,5 +193,7 @@ async def handle_modern_request(
         request_id=req.id,
         message_metadata=ServerMessageMetadata(request_context=request),
     )
-    msg = await serve_one(app, dctx, req.method, req.params, connection=connection, lifespan_state=lifespan_state)
+    msg = await to_jsonrpc_response(
+        req.id, serve_one(app, dctx, req.method, req.params, connection=connection, lifespan_state=lifespan_state)
+    )
     await _write(msg, scope, receive, send)

src/mcp/server/runner.py

@@ -36,7 +36,7 @@
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher, handler_exception_to_error_data
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
+from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
 from mcp.types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
@@ -187,13 +187,12 @@ async def to_jsonrpc_response(
 ) -> JSONRPCResponse | JSONRPCError:
     """Await ``coro`` and wrap its outcome as the JSON-RPC reply for ``request_id``.
 
-    The exception-to-wire boundary for the request-per-call drivers
-    (`serve_one`, the modern HTTP entry). `MCPError` and `ValidationError`
+    The exception-to-wire boundary for the modern HTTP entry, which composes
+    this around `serve_one` directly. `MCPError` and `ValidationError`
     map via the shared `handler_exception_to_error_data` ladder; any other
     exception is logged and surfaced as `INTERNAL_ERROR` so handler internals
     never reach the wire. Set ``raise_unhandled`` to let unmapped exceptions
-    propagate instead of being sanitized — used by the in-process test path so
-    handler tracebacks reach the caller.
+    propagate instead of being sanitized.
     """
     try:
         result = await coro
@@ -422,7 +421,7 @@ def _negotiate_initialize(params: Mapping[str, Any] | None) -> tuple[InitializeR
         """Validate `initialize` params and pick the protocol version."""
         init = InitializeRequestParams.model_validate(params or {}, by_name=False)
         requested = init.protocol_version
-        negotiated = requested if requested in HANDSHAKE_PROTOCOL_VERSIONS else HANDSHAKE_PROTOCOL_VERSIONS[-1]
+        negotiated = requested if requested in HANDSHAKE_PROTOCOL_VERSIONS else LATEST_HANDSHAKE_VERSION
         return init, negotiated
 
     def _handle_initialize(self, params: Mapping[str, Any] | None) -> InitializeResult:
@@ -508,25 +507,21 @@ async def serve_one(
     *,
     connection: Connection,
     lifespan_state: LifespanT,
-    raise_exceptions: bool = False,
-) -> JSONRPCResponse | JSONRPCError:
-    """Handle a single request ``(method, params)`` and return its JSON-RPC reply.
+) -> dict[str, Any]:
+    """Handle a single request ``(method, params)`` and return its result dict.
 
     The single-exchange driver: builds the kernel, runs `on_request` once under
-    `dctx`, maps the outcome to a `JSONRPCResponse` / `JSONRPCError` via
-    `to_jsonrpc_response`, and tears down `connection.exit_stack` (shielded) on
-    the way out. The entry constructs the (born-ready) `Connection` and the
-    `dctx`; this only consumes them. ``raise_exceptions`` lets unmapped handler
-    exceptions propagate instead of being sanitized to `INTERNAL_ERROR`.
+    `dctx`, and tears down `connection.exit_stack` (shielded) on the way out.
+    The entry constructs the (born-ready) `Connection` and the `dctx`; this
+    only consumes them.
+
+    Raises whatever the handler chain raises (`MCPError` / `ValidationError` /
+    unmapped); callers own the exception-to-wire mapping. The HTTP entry
+    composes this with `to_jsonrpc_response`.
     """
     runner = ServerRunner(server, connection, lifespan_state)
     try:
-        # Single-exchange driver only handles requests; both entries populate `request_id`.
-        # TODO(L54): drop once `DispatchContext` is split so `OnRequest` carries a non-Optional id.
-        assert dctx.request_id is not None
-        return await to_jsonrpc_response(
-            dctx.request_id, runner.on_request(dctx, method, params), raise_unhandled=raise_exceptions
-        )
+        return await runner.on_request(dctx, method, params)
     finally:
         await aclose_shielded(connection)
 
@@ -540,29 +535,30 @@ def modern_on_request(
     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.
+    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.
     """
 
     async def handle(
         dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
     ) -> dict[str, Any]:
         meta = (params or {}).get("_meta", {})
         connection = Connection.from_envelope(
-            meta.get(PROTOCOL_VERSION_META_KEY, MODERN_PROTOCOL_VERSIONS[-1]),
+            meta.get(PROTOCOL_VERSION_META_KEY, LATEST_MODERN_VERSION),
             meta.get(CLIENT_INFO_META_KEY),
             meta.get(CLIENT_CAPABILITIES_META_KEY),
         )
-        msg = await serve_one(
-            server,
-            dctx,
-            method,
-            params,
-            connection=connection,
-            lifespan_state=lifespan_state,
-            raise_exceptions=raise_exceptions,
-        )
-        if isinstance(msg, JSONRPCError):
-            raise MCPError(code=msg.error.code, message=msg.error.message, data=msg.error.data)
-        return msg.result
+        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 handle