Add an opt-in strict_capabilities flag to Client and ClientSession

Client(..., strict_capabilities=True) rejects, before any request reaches
the transport, a call to a method whose required server capability the
connected server did not advertise -- for example list_resources() against
a server that only advertised tools, or subscribe_resource() when the
server's resources capability does not set subscribe. The rejection is an
MCPError with code -32601 (METHOD_NOT_FOUND) and data set to the method,
the same shape a compliant server returns for an unadvertised capability,
so opting in changes where the rejection happens, not what callers catch.

The default is False and unchanged: every request is sent and the server's
answer is surfaced. This mirrors the TypeScript SDK's
enforceStrictCapabilities option (also default-off). The same keyword-only
parameter exists on ClientSession for low-level users; Client forwards it.

The method-to-capability table lives in
mcp_types.methods.SERVER_CAPABILITY_REQUIREMENTS next to the other
per-method maps, with missing_server_capability() as its only evaluator,
so the check in ClientSession.send_request is a single data-driven gate
rather than a per-method condition, and the relationship is the same at
every protocol version. Because the gate reads server_capabilities, a bare
version pin (mode="2026-07-28" with no prior_discover=) would reject every
gated method; that combination is refused at Client construction with a
ValueError that names the fix.

The interaction-requirements entry for the lifecycle capability rule is no
longer marked untested: the new tests pin both the opt-in pre-wire
rejection and the default send-and-surface behaviour.

Author: maxisbey

docs/client/index.md

@@ -31,7 +31,7 @@ Everything else on this page is identical across all three. Headers, subprocesse
 Four read-only properties, populated the moment you enter the block:
 
 * `client.server_info`: the server's identity. `server_info.name` here is `"Bookshop"`, `server_info.version` is whatever the server reports.
-* `client.server_capabilities`: what the server can do (`tools`, `resources`, `prompts`, `completions`, ...). A capability the server doesn't have is `None`.
+* `client.server_capabilities`: what the server can do (`tools`, `resources`, `prompts`, `completions`, ...). A capability the server doesn't have is `None`. Pass `Client(..., strict_capabilities=True)` and the client uses this to refuse, client-side, a call whose capability the server didn't advertise: it raises `MCPError` with code `-32601` without sending anything. By default the request is sent and the server's answer comes back.
 * `client.protocol_version`: the protocol version the two sides agreed on. Here it is `"2026-07-28"`.
 * `client.instructions`: the server's `instructions=` string, or `None` if it didn't set one.
 
@@ -145,7 +145,7 @@ The resource verbs come in pairs: two ways to list, one way to read.
 
 `read_resource` returns `contents`, a list of `TextResourceContents` or `BlobResourceContents`. Same idea as tool content: narrow with `isinstance`, then read `.text` (or `.blob`).
 
-A client can also **subscribe** to a resource and be told when it changes: `subscribe_resource(uri)` and `unsubscribe_resource(uri)`, same shape as everything else here. `MCPServer` doesn't implement that half. It says so up front (`server_capabilities.resources.subscribe` is `False`) and answers the request with an `MCPError`: `-32601`, *Method not found*. A server that does support subscriptions is built on the low-level `Server` (**The low-level Server**).
+A client can also **subscribe** to a resource and be told when it changes: `subscribe_resource(uri)` and `unsubscribe_resource(uri)`, same shape as everything else here. `MCPServer` doesn't implement that half. It says so up front (`server_capabilities.resources.subscribe` is `False`) and answers the request with an `MCPError`: `-32601`, *Method not found*. With `strict_capabilities=True` you get the same `-32601` without the round trip: the client sees `server_capabilities.resources.subscribe` is falsy and never sends the request. A server that does support subscriptions is built on the low-level `Server` (**The low-level Server**).
 
 ## Prompts
 

docs/migration.md

@@ -439,6 +439,26 @@ 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.
 
+### `Client` gains an opt-in `strict_capabilities` flag
+
+`Client(..., strict_capabilities=True)` makes the client reject, before any request reaches
+the transport, a call to a method whose required server capability the connected server did
+not advertise -- for example `list_resources()` against a server that only advertised
+`tools`, or `subscribe_resource()` against a server whose `resources` capability does not set
+`subscribe`. The rejection is an `MCPError` with code `-32601` (`METHOD_NOT_FOUND`), the same
+code a compliant server returns for an unadvertised capability, so existing error handling is
+unaffected.
+
+The default is `False` and is unchanged from v1: every request is sent and the server's
+answer is surfaced. This mirrors the TypeScript SDK's `enforceStrictCapabilities` option, and
+the same keyword-only parameter exists directly on `ClientSession(..., strict_capabilities=)`
+for low-level users -- `Client` just forwards it. The check reads
+`client.server_capabilities`, so a bare version pin (`mode="2026-07-28"` with no
+`prior_discover=`) -- where the client never asks the server what it supports and so every
+capability-gated method would be rejected -- is refused at construction with a `ValueError`
+that names the fix: supply `prior_discover=` or use `mode="auto"`. Which method needs which
+capability is exported as `mcp_types.methods.SERVER_CAPABILITY_REQUIREMENTS`.
+
 ### 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.

src/mcp-types/mcp_types/methods.py

@@ -6,7 +6,10 @@
 Surface maps key `(method, version)` to per-version wire types (key absence is
 the version gate; shape validation is per schema era, i.e. 2025-11-25 for every
 pre-2026 version and 2026-07-28 for 2026). Monolith maps key `method` to the
-version-free `mcp_types` models user code receives."""
+version-free `mcp_types` models user code receives.
+`SERVER_CAPABILITY_REQUIREMENTS` keys `method` to the `ServerCapabilities`
+attribute path it requires (version-invariant); `missing_server_capability`
+evaluates it."""
 
 from __future__ import annotations
 
@@ -29,11 +32,13 @@
     "MONOLITH_NOTIFICATIONS",
     "MONOLITH_REQUESTS",
     "MONOLITH_RESULTS",
+    "SERVER_CAPABILITY_REQUIREMENTS",
     "SERVER_NOTIFICATIONS",
     "SERVER_REQUESTS",
     "SERVER_RESULTS",
     "SPEC_CLIENT_METHODS",
     "SPEC_CLIENT_NOTIFICATION_METHODS",
+    "missing_server_capability",
     "parse_client_notification",
     "parse_client_request",
     "parse_client_result",
@@ -404,6 +409,55 @@
 """Monolith result model (or two-arm union) per request method."""
 
 
+# --- Server capability requirements ---
+
+SERVER_CAPABILITY_REQUIREMENTS: Final[Mapping[str, tuple[str, ...]]] = MappingProxyType(
+    {
+        "completion/complete": ("completions",),
+        "logging/setLevel": ("logging",),
+        "prompts/get": ("prompts",),
+        "prompts/list": ("prompts",),
+        "resources/list": ("resources",),
+        "resources/read": ("resources",),
+        "resources/subscribe": ("resources", "subscribe"),
+        "resources/templates/list": ("resources",),
+        "resources/unsubscribe": ("resources",),
+        "tools/call": ("tools",),
+        "tools/list": ("tools",),
+    }
+)
+"""The server capability each client request method requires, as an attribute path into
+`ServerCapabilities`. Methods with no entry (`ping`, `initialize`, `server/discover`,
+`subscriptions/listen`) require no server capability. `subscriptions/listen` stays ungated on
+purpose: at 2026-07-28 the `resources.subscribe` capability licenses that request's
+`resourceSubscriptions` FIELD, a params-level fact a method-keyed table cannot express, and
+no spec MUST ties the method itself to a capability -- gating it here would wrongly reject a
+listen that asks only for `toolsListChanged`. The relationship is the same at every protocol
+version, so the map is keyed by method alone."""
+
+
+def missing_server_capability(method: str, capabilities: types.ServerCapabilities | None) -> str | None:
+    """The server capability `method` requires but `capabilities` does not advertise.
+
+    Returns the dotted name of the first unadvertised step on the required capability path --
+    `resources` when no resources capability is advertised at all, `resources.subscribe` when
+    `resources` is advertised but `subscribe` is not -- or None when `method` requires no
+    server capability or the required one is advertised. Naming the first missing step rather
+    than the whole path matches the TypeScript SDK's assertCapabilityForMethod and is the
+    actionable thing to tell the caller. `capabilities=None` (nothing negotiated yet)
+    advertises nothing.
+    """
+    path = SERVER_CAPABILITY_REQUIREMENTS.get(method)
+    if path is None:
+        return None
+    node: Any = capabilities
+    for index, attr in enumerate(path):
+        node = node and getattr(node, attr)
+        if not node:
+            return ".".join(path[: index + 1])
+    return None
+
+
 # --- Parse functions ---
 
 # Envelope stubs merged into bodies for surface validation (surface classes are full frames).

src/mcp/client/client.py

@@ -196,6 +196,17 @@ async def main():
     """A previously-obtained DiscoverResult to install via .adopt() when mode is a version pin.
     Ignored when mode='legacy'."""
 
+    strict_capabilities: bool = False
+    """Reject calls to methods whose required server capability the server did not advertise.
+
+    Opt-in (default False: every request is sent and the server's answer is surfaced, matching
+    the pre-2026 client). When True, such a call raises `MCPError` with code `METHOD_NOT_FOUND`
+    before any request reaches the transport -- the same code a compliant server returns for an
+    unadvertised capability. The check reads `server_capabilities`, so a bare version pin
+    (`mode='2026-07-28'` with no `prior_discover=`) -- which never asks the server what it
+    supports -- is rejected at construction with a `ValueError`; supply `prior_discover=` or
+    use `mode='auto'`. Mirrors the TypeScript SDK's `enforceStrictCapabilities` option."""
+
     elicitation_callback: ElicitationFnT | None = None
     """Callback for handling elicitation requests."""
 
@@ -215,6 +226,13 @@ def __post_init__(self) -> None:
                 f"mode must be 'legacy', 'auto', or one of {list(MODERN_PROTOCOL_VERSIONS)}; got {self.mode!r}{hint}"
             )
 
+        if self.strict_capabilities and self.mode in MODERN_PROTOCOL_VERSIONS and self.prior_discover is None:
+            raise ValueError(
+                "strict_capabilities=True with a version pin needs prior_discover=: a bare pin "
+                "never asks the server what it supports, so every capability-gated method would "
+                "be rejected. Supply prior_discover= or use mode='auto'."
+            )
+
         srv = self.server
         if isinstance(srv, MCPServer):
             srv = srv._lowlevel_server  # pyright: ignore[reportPrivateUsage]
@@ -237,6 +255,7 @@ async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
             message_handler=self.message_handler,
             client_info=self.client_info,
             elicitation_callback=self.elicitation_callback,
+            strict_capabilities=self.strict_capabilities,
         )
 
     async def __aenter__(self) -> Client:

src/mcp/client/session.py

@@ -213,6 +213,7 @@ def __init__(
         client_info: types.Implementation | None = None,
         *,
         sampling_capabilities: types.SamplingCapability | None = None,
+        strict_capabilities: bool = False,
         dispatcher: Dispatcher[Any] | None = None,
     ) -> None:
         self._session_read_timeout_seconds = read_timeout_seconds
@@ -223,6 +224,7 @@ def __init__(
         self._list_roots_callback = list_roots_callback or _default_list_roots_callback
         self._logging_callback = logging_callback or _default_logging_callback
         self._message_handler = message_handler or _default_message_handler
+        self._strict_capabilities = strict_capabilities
         self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
         self._x_mcp_header_maps: dict[str, dict[tuple[str, ...], str]] = {}
         self._initialize_result: types.InitializeResult | None = None
@@ -296,11 +298,22 @@ async def send_request(
             metadata: Streamable HTTP resumption hints.
 
         Raises:
-            MCPError: Error response, read timeout, or connection closed.
+            MCPError: Error response, read timeout, or connection closed. Also raised
+                before any send when `strict_capabilities` is set and the server did not
+                advertise the capability `request.method` requires (code
+                `METHOD_NOT_FOUND`).
             RuntimeError: Called before entering the context manager.
         """
         data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
         method: str = data["method"]
+        if self._strict_capabilities and (
+            missing := _methods.missing_server_capability(method, self.server_capabilities)
+        ):
+            raise MCPError(
+                code=METHOD_NOT_FOUND,
+                message=f"Server does not advertise the {missing} capability (required for {method})",
+                data=method,
+            )
         opts: CallOptions = {}
         self._stamp(data, opts)
         timeout = (

tests/client/test_client.py

@@ -513,3 +513,11 @@ def test_client_rejects_handshake_era_mode_at_construction() -> None:
         Client(server, mode="2025-06-18")
     with pytest.raises(ValueError, match=r"mode must be 'legacy', 'auto', or one of"):
         Client(server, mode="not-a-version")
+
+
+def test_client_rejects_strict_capabilities_on_a_bare_version_pin_at_construction() -> None:
+    """`strict_capabilities=True` with a version pin and no `prior_discover=` is rejected by
+    `__post_init__`: a bare pin never asks the server what it supports, so every
+    capability-gated method would be rejected before doing anything useful."""
+    with pytest.raises(ValueError, match=r"prior_discover= or use mode='auto'"):
+        Client(MCPServer("test"), mode="2026-07-28", strict_capabilities=True)

tests/interaction/_requirements.py

@@ -202,14 +202,15 @@ def __post_init__(self) -> None:
         ),
         divergence=Divergence(
             note=(
-                "The client sends any request regardless of the server's advertised capabilities and "
-                "surfaces whatever the server answers; the spec's MUST is not enforced."
+                "Not the default: by default the client sends any request regardless of the "
+                "server's advertised capabilities and surfaces whatever the server answers. The "
+                "client-side pre-check is opt-in via Client(strict_capabilities=True), which "
+                "rejects with METHOD_NOT_FOUND before any wire traffic -- the same shape as the "
+                "TypeScript SDK's enforceStrictCapabilities (also default-off). The 2026-07-28 "
+                "revision removes the lifecycle page that carries this MUST; there the server's "
+                "-32601 is the authoritative signal and the SDK's server already returns it."
             ),
         ),
-        deferred=(
-            "Not implemented in the SDK: the client sends any request regardless of the server's "
-            "advertised capabilities and surfaces whatever the server answers."
-        ),
     ),
     "lifecycle:initialize:basic": Requirement(
         source=f"{SPEC_BASE_URL}/basic/lifecycle#initialization",