Gate resolver egress on the request channel's sendability

The legacy capability gate keyed on whether the handshake's declaration
was visible, which let a session initialized with a bare
notifications/initialized (no declared capabilities, live back-channel)
receive ungated requests. Gate on the request-scoped channel's
can_send_request instead, the channel these sends actually ride, so any
sendable session is checked and a channel-less one keeps failing with
its no-back-channel error. Adds ServerSession.can_send_request and a
bare-initialized regression test, and corrects docs wording: tool_choice
counts toward sampling.tools, the sampling.tools declaration needs the
explicit client field, and the v1 claims are scoped to what v1 checked.

Author: maxisbey

docs/handlers/dependencies.md

@@ -142,7 +142,7 @@ Elicitation is one of the three questions a resolver can ask, and the multi-roun
 --8<-- "docs_src/dependencies/tutorial004.py"
 ```
 
-* The framework routes these exactly like `Elicit`: inside the multi-round-trip `tools/call` on **2026-07-28**, over the standalone server->client request on **2025-11-25**. On either transport it refuses with a `-32021` protocol error when the client never declared the matching capability (`sampling`, `roots`, `elicitation`; `sampling.tools` when the request carries tools).
+* The framework routes these exactly like `Elicit`: inside the multi-round-trip `tools/call` on **2026-07-28**, over the standalone server->client request on **2025-11-25**. An undeclared capability refuses the call with a `-32021` protocol error (`sampling`, `roots`, form `elicitation`; `sampling.tools` when the request carries `tools` or `tool_choice`).
 * Everything the info box above says about questions applies unchanged: a `Sample` request is matched to its recorded result by its exact rendering, so build it deterministically from the tool's arguments and earlier answers; the client then pays for the LLM call once per tool call, not once per round. The recorded result rides `request_state` for the rest of the call, so a very large completion makes every remaining round-trip heavier.
 * The standalone sampling and roots *features* are deprecated at 2026-07-28 (SEP-2577). New servers that need the client's model ask through this carrier; servers that don't should integrate with an LLM provider directly. `include_context` values other than `"none"` are themselves deprecated; avoid them.
 

docs/handlers/sampling-and-roots.md

@@ -16,7 +16,7 @@ A resolver returns `Sample(...)` and the tool receives the completion, through t
 ```
 
 * `Sample(messages, max_tokens=...)` mirrors the `sampling/createMessage` parameters. The injected value is the client's `CreateMessageResult`; pass `tools=[...]` and it becomes a `CreateMessageResultWithTools` instead.
-* The client must have declared the `sampling` capability (`sampling.tools` if you pass tools). If it didn't, the call fails with a `-32021` protocol error before anything is sent.
+* The client must have declared the `sampling` capability (`sampling.tools` if you pass `tools` or `tool_choice`). If it didn't, the call fails with a `-32021` protocol error instead of sending a request the client cannot handle. A pre-2026 session with no back-channel fails with its usual no-back-channel error, since there is nothing to send on.
 * At `2026-07-28` the request is delivered inside the multi-round-trip flow (**[Multi-round-trip requests](multi-round-trip.md)**); on `2025-11-25` it is a standalone request to the client. The code is the same either way, but mind the multi-round-trip rule: the request must render identically across retry rounds, so build it only from the tool's arguments and other stable data.
 * Leave `include_context` alone: values other than `"none"` are themselves deprecated (SEP-2596) and need a capability almost no client declares.
 
@@ -29,7 +29,7 @@ Roots are the folders the client says the server may operate on. They are inform
 ```
 
 * The injected `ListRootsResult` carries a list of `Root`s: a `file://` URI and an optional display name.
-* The gate is the same as for sampling: without a declared `roots` capability the call fails with `-32021` before a request is sent.
+* The gate is the same as for sampling: without a declared `roots` capability the call fails with `-32021` instead of sending the request.
 
 On the other side of the wire, the client answers both requests with the callbacks it already has: `sampling_callback` and `list_roots_callback`, covered in **[Client callbacks](../client/callbacks.md)**.
 
@@ -40,7 +40,7 @@ On the other side of the wire, the client answers both requests with the callbac
 ## Recap
 
 * Return `Sample(...)` or `ListRoots()` from a resolver; the tool receives the `CreateMessageResult` or `ListRootsResult` like any other dependency.
-* The client must declare the matching capability, or the call fails with `-32021` before a request is sent.
+* The client must declare the matching capability, or the call fails with `-32021` instead of a request being sent.
 * Both features are deprecated at `2026-07-28`: fully functional for now, wrong for new designs. Prefer provider APIs over sampling and explicit parameters over roots.
 
 Reporting how far along a slow tool is: **[Progress](progress.md)**.

docs/migration.md

@@ -42,18 +42,21 @@ dependencies elicit via `Resolve(...)`: the resolver owns that tool's
 
 ### Resolver-routed requests require the client capability on every protocol version
 
-A v1 server could call `ctx.elicit()`, `create_message()`, or `list_roots()`
-against any client; nothing checked what the client had declared. In v2 the
-`Resolve(...)` markers (`Elicit`, `Sample`, `ListRoots`) enforce the spec's
-egress rule on both transports: if the client never declared the matching
-capability (`elicitation`, `sampling`, or `roots`, plus `sampling.tools` when
-the request carries tools), the call fails with a `-32021`
+A v1 server could send elicitation, sampling, and roots requests to clients
+that never declared the matching capability; only tools-bearing sampling was
+checked. In v2 the `Resolve(...)` markers (`Elicit`, `Sample`, `ListRoots`)
+enforce the spec's egress rule: an undeclared capability (form `elicitation`,
+`sampling`, or `roots`, plus `sampling.tools` when the request carries `tools`
+or `tool_choice`) fails the call with a `-32021`
 `MISSING_REQUIRED_CLIENT_CAPABILITY` JSON-RPC error instead of sending a
-request the client cannot handle. This applies on 2025-11-25 sessions too, so a
-client that answered elicitations without declaring the capability now sees the
-error: declare the capability (the SDK client does this automatically when the
-matching callback is set) or drop the asking dependency. Direct `ctx.elicit()`
-and `ctx.session.*` calls outside resolvers are not gated.
+request the client cannot handle. This applies on 2025-11-25 sessions with a
+live back-channel too; a session with no back-channel keeps failing with its
+no-back-channel error. To migrate, declare the capability: the SDK client
+declares `elicitation`, `sampling`, and `roots` when the matching callback is
+set, and `sampling.tools` needs an explicit
+`Client(sampling_capabilities=SamplingCapability(tools=...))`. Direct
+`ctx.elicit()` and `ctx.session.*` calls outside resolvers keep their previous
+behavior, including the pre-existing tools check on `create_message`.
 
 ### `MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error
 

src/mcp/server/mcpserver/resolve.py

@@ -122,7 +122,7 @@ class Sample:
     """A resolver's request to sample the client's LLM via `sampling/createMessage`.
 
     The framework injects a `CreateMessageResult` (`CreateMessageResultWithTools` when `tools` are
-    given); requires the `sampling` capability (`sampling.tools` when tools are given). On
+    given); requires the `sampling` capability (`sampling.tools` when `tools` or `tool_choice` are given). On
     >= 2026-07-28 the request must render identically across retry rounds, and the sampled result
     rides `request_state` on every later round. `include_context` other than "none" is deprecated in the draft spec.
     """
@@ -449,10 +449,9 @@ def __init__(
         self.asked = decoded.asked
         # In-call dedup keyed by resolver identity (distinguishes two instances of
         # the same bound method); `persist` holds the wire-shaped record of each
-        # elicited outcome, keyed by its wire key - exactly what the next round's
-        # `request_state` carries. Entries are the client's own (validated) wire
-        # data, never re-derived from a model, so encode-restore is the identity.
-        # Pure resolvers are cheap to re-run each round and are not persisted.
+        # asked outcome, keyed by its wire key - exactly what the next round's `request_state`
+        # carries: the client's own validated content (elicitation) or the validated result's
+        # dump (sample/roots). Pure resolvers are cheap to re-run each round and are not persisted.
         self.cache: dict[Hashable, ElicitationResult[Any]] = {}
         self.persist: dict[str, _StateEntry] = {}
         self.pending: InputRequests = {}
@@ -570,9 +569,9 @@ async def _resolve(fn: Callable[..., Any], res: _Resolution) -> ElicitationResul
 async def _fulfil(marker: _Marker, key: str, res: _Resolution) -> ElicitationResult[Any]:
     """Turn a resolver's request marker into an outcome via the negotiated transport."""
     if not res.input_required:
-        # Gate only when the handshake's declaration is visible: a session with no
-        # client info (e.g. stateless HTTP) has no back-channel, and the send path reports that.
-        if res.context.client_capabilities is not None:
+        # Gate wherever the request could actually be sent; otherwise the send path
+        # itself reports the failure.
+        if res.context.session.can_send_request:
             _require_capability(res.context, marker, key)
         if isinstance(marker, Elicit):
             return await res.context.elicit(marker.message, marker.schema)
@@ -770,9 +769,7 @@ def _decode_state(request_state: str | None) -> _State:
 def _encode_state(outcomes: Mapping[str, _StateEntry], asked: Mapping[str, str]) -> str:
     """Encode recorded outcomes and asked-question digests for the next round.
 
-    Outcome entries already hold the client's wire-shaped data exactly as it was
-    sent (and validated), so encoding is pure wrapping: encode-restore is the
-    identity.
+    Outcome entries are already wire-shaped, so encoding is pure wrapping.
     """
     state = _State(v=_STATE_VERSION, outcomes=dict(outcomes), asked=dict(asked))
     return compact_json(state.model_dump(mode="json"))
@@ -796,9 +793,9 @@ def _outcome_from_state(entry: _StateEntry, marker: _Marker) -> ElicitationResul
 def _restore_outcome(res: _Resolution, key: str, marker: _Marker, q: str) -> ElicitationResult[Any] | None:
     """Restore `key`'s recorded outcome from a prior round, or `None` when absent.
 
-    An entry pinned to a question digest other than `q`, or whose accepted
-    data fails validation against the live `schema`, is dropped as if no
-    progress was recorded, so the question is asked again.
+    An entry pinned to a question digest other than `q`, or that fails
+    validation against the live marker, is dropped as if no progress was
+    recorded, so the question is asked again.
 
     Carries the original decoded entry forward unchanged in `res.persist`: if a
     later resolver is still pending, the next round's `request_state` is built from

src/mcp/server/session.py

@@ -45,6 +45,11 @@ def client_params(self) -> types.InitializeRequestParams | None:
         """The client's `initialize` request params; `None` when no client info was supplied."""
         return self._connection.client_params
 
+    @property
+    def can_send_request(self) -> bool:
+        """Whether this request's channel can currently deliver a server-initiated request."""
+        return self._request_outbound.can_send_request
+
     @property
     def protocol_version(self) -> str:
         """The protocol version this connection speaks.

tests/server/mcpserver/test_resolve.py

@@ -20,6 +20,9 @@
     ElicitResult,
     InputRequiredResult,
     InputResponses,
+    JSONRPCError,
+    JSONRPCNotification,
+    JSONRPCRequest,
     ListRootsResult,
     Root,
     SamplingCapability,
@@ -36,6 +39,7 @@
 
 from mcp import Client, InputRequiredRoundsExceededError
 from mcp.client import ClientRequestContext
+from mcp.client._memory import InMemoryTransport
 from mcp.server.context import ServerRequestContext
 from mcp.server.mcpserver import (
     AcceptedElicitation,
@@ -69,6 +73,7 @@
 )
 from mcp.server.mcpserver.tools.base import Tool
 from mcp.shared.exceptions import MCPError
+from mcp.shared.message import SessionMessage
 
 
 def _question_digest(elicit: Elicit[Any]) -> str:
@@ -2723,3 +2728,29 @@ def test_decline_entry_for_a_sample_marker_is_invalid():
     # Decline outcomes exist only for elicitations; for a Sample the entry's None data fails validation.
     with pytest.raises(ValidationError):
         _outcome_from_state(_StateEntry(action="decline"), _sample_capital(cast(Context, None)))
+
+
+@pytest.mark.anyio
+async def test_bare_initialized_session_is_still_gated():
+    # notifications/initialized alone commits the handshake: a live back-channel, no declared capabilities.
+    mcp = MCPServer(name="BareInit", request_state_security=RequestStateSecurity.ephemeral())
+
+    async def ask(ctx: Context) -> Elicit[Login]:
+        return Elicit("user?", Login)
+
+    @mcp.tool()
+    async def tool(login: Annotated[Login, Resolve(ask)]) -> str:
+        return login.username  # pragma: no cover
+
+    async with InMemoryTransport(mcp) as (read, write):
+        await write.send(SessionMessage(JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized")))
+        await write.send(
+            SessionMessage(
+                JSONRPCRequest(jsonrpc="2.0", id=1, method="tools/call", params={"name": "tool", "arguments": {}})
+            )
+        )
+        with anyio.fail_after(5):
+            message = await read.receive()
+    assert isinstance(message, SessionMessage)
+    assert isinstance(message.message, JSONRPCError)
+    assert message.message.error.code == MISSING_REQUIRED_CLIENT_CAPABILITY