diff --git a/docs/development/v4-notes/change-register.mdx b/docs/development/v4-notes/change-register.mdx
index 921ae29d1..3fe313f26 100644
--- a/docs/development/v4-notes/change-register.mdx
+++ b/docs/development/v4-notes/change-register.mdx
@@ -380,6 +380,19 @@ A tool can gather client input across rounds on a `2026-07-28` call by returning
*Verify:* `fastmcp_slim/fastmcp/server/context.py` (`input_responses`/`request_state` properties), `fastmcp_slim/fastmcp/server/low_level.py` (`RequestStateBoundary` install), `fastmcp_slim/fastmcp/server/server.py` (`request_state_security` param), `fastmcp_slim/fastmcp/server/mixins/mcp_operations.py` (`_on_call_tool` input-required passthrough + era gate), `fastmcp_slim/fastmcp/tools/base.py` (`InputRequiredToolResult`), `tests/server/test_mrtr_guards.py`.
+### Server protocol-version restriction — New (opt-in feature)
+
+A server can declare the set of MCP protocol versions it serves, so a client that shares none of them is refused at connection time instead of failing mid tool-call. The declaration is an allowlist expressed in the SDK's own units — `FastMCP(protocol_versions=MODERN_PROTOCOL_VERSIONS)`, `FastMCP(protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS)`, or exact strings like `["2026-07-28"]` — so authors pass the SDK's era tuples rather than FastMCP-invented alias vocabulary, and those tuples grow on their own when the SDK adds a revision to an era. An unrecognized version string is a `ValueError` at construction.
+
+Enforcement is **set membership, not a minimum**, matching the SDK's stated model that versions are an enumerated set rather than an ordered scalar (`mcp_types/version.py`). That is what makes handshake-only expressible: the modern era is numerically newer but *removed* the server-initiated back-channel (`ctx.elicit`/`ctx.sample`/`ctx.list_roots`), so a server built on the back-channel needs the handshake era specifically — a minimum-version model could not say that. Both connection paths are covered: the initialize handshake is refused before it commits, and modern connections are checked on the request itself, since a client pinned to a modern version never probes `server/discover`. Refusals use the spec-standard `-32022` unsupported-protocol-version error with the server's `supported` list, so a `mode="auto"` client refused at discovery by a handshake-only server reads the handshake versions out of the error and completes over `initialize` on its own.
+
+Membership is **era-aware**, because FastMCP can only *veto* a connection — never steer the version the peer settles on — and the two eras negotiate their version differently. A modern connection pins an exact version in every per-request envelope, so a modern-version declaration enforces exact membership. The handshake era is negotiated by the SDK's initialize handler (`ServerRunner._negotiate_initialize`), which honors the client's requested revision (or counters with the newest handshake revision) with no knowledge of the declaration; FastMCP cannot make it counter-offer a specific revision. So a handshake-version declaration enforces the handshake *era*, not an exact revision: a server that declares any handshake version accepts the handshake and runs at whatever revision the SDK negotiated, and only a server that declares no handshake version refuses it. Pinning a single handshake revision (`["2025-06-18"]`) narrows nothing — the earlier build refused an ordinary client that offered a different handshake revision than the pin, which broke normal handshake negotiation for any server pinned to an older handshake revision; enforcement now refuses the handshake only for a genuine cross-era mismatch (a modern-only server).
+
+The startup coherence check is now a **capability map** rather than ad-hoc cases: each entry names a capability, the protocol versions that carry it, and a detector. Present entries are multi-round-trip guard tools (modern versions, detected via `_contains_input_required` over tool return annotations) and the client back-channel (handshake versions, detected only from the configuration-level `sampling_handler` + `"fallback"` contradiction — the runtime calls have no static signal). A future capability, notably the 2026 tasks extension, is one entry rather than a new special case. Warnings only, never a hard error, and **silent unless a version set was declared** — a server with an ordinary guard tool and no declaration is fine, and warning there would train people to ignore warnings.
+
+The default is `None`: every protocol version the SDK supports is served. Flipping a server default would disconnect existing clients rather than degrade, so restriction stays strictly opt-in. No `settings.py` entry — this is per-server configuration, not global.
+
+*Verify:* `fastmcp_slim/fastmcp/server/protocol_versions.py` (validation, negotiation mirror, enforcement, capability map, coherence check), `fastmcp_slim/fastmcp/server/low_level.py` (handshake veto in the initialize path, per-request check in the root dispatch), `fastmcp_slim/fastmcp/server/mixins/lifespan.py` (startup coherence call), `tests/server/test_protocol_versions.py`.
### Proxy era mirroring — New (behavior)
A proxy is a server on its front and a client on its back, and the two eras have mutually exclusive interaction models on a single session: the handshake era pushes server-initiated requests (sampling/elicitation/roots) that the proxy forwards to its client, while the modern era forbids those and round-trips a guard tool's `InputRequiredResult` as a result instead. A proxy created from a non-Client target with no explicit `mode` now MIRRORS the front connection's negotiated era onto its backend session per request, so the whole chain speaks one era end-to-end — a modern client reaches a modern backend (guard round-trips work), a handshake client reaches a handshake backend (push-forwarding works), and the same proxy serves both without a backend session ever crossing eras. Because the default factory builds a fresh backend client per request and derives its `mode` from the front era at call time, only the metadata-only component caches are shared across eras. An explicit `create_proxy(target, mode=...)` still pins the backend era regardless of the front, overriding mirroring for a backend that only speaks one era; the resulting cross-era feature mismatches surface through the existing era gates. `ProxyInitializeMiddleware` no longer force-calls the handshake-only `client.initialize()` when the backend negotiated the modern era, so an explicit modern pin behind a handshake front no longer crashes on connect. The mirrored era carries through a multi-server `MCPConfig` target as well: that form mounts one proxy per configured server onto a composite router, and `TransportOptions.backend_mode` hands the era down to those mounted legs so every real backend negotiates it, not just the router in front of them. That router is also now sealed under a policy held on the transport rather than a fresh per-router ephemeral key, so a guard tool's `request_state` survives the router being rebuilt between rounds.
diff --git a/docs/development/v4-notes/protocol-2026.mdx b/docs/development/v4-notes/protocol-2026.mdx
index d6f0ce0c9..5cc2c3fd1 100644
--- a/docs/development/v4-notes/protocol-2026.mdx
+++ b/docs/development/v4-notes/protocol-2026.mdx
@@ -2,6 +2,8 @@
title: 2026-07-28 Protocol Support
---
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
FastMCP v4 serves the sessionless `2026-07-28` protocol era and the session-based handshake eras from a single server, with per-connection auto-detection. This page catalogs what FastMCP provides for the modern era — both the protocol machinery it inherits from the MCP Python SDK and the capabilities FastMCP implements itself on top of that layer. It is the reference for what a v4 deployment can actually do on the modern protocol today.
## Identity assertion (SEP-990): a complete server-side implementation
@@ -48,6 +50,152 @@ The complete picture of what a FastMCP v4 server and client provide on the `2026
| **Pagination** | Declarative `FastMCP(list_page_size=...)` paginates all list operations in the high-level server; the client auto-paginates with cycle detection. |
| **Telemetry** | OpenTelemetry spans on by default (no-op without an exporter), SDK-aligned attributes (`mcp.method.name`, `mcp.protocol.version`, `gen_ai.*`), plus auth and provider-delegation spans; `FASTMCP_ENABLE_TELEMETRY=false` disables cleanly. |
+## Restricting the protocol versions a server serves
+
+
+
+Most servers should skip this section. By default a FastMCP server serves every
+protocol version the SDK supports, and that is the right setting for almost
+everything — one server, every client, no configuration.
+
+Some servers cannot. A server can depend on a feature that exists on only one
+protocol era, and the two eras are not a ladder: the modern era added the
+multi-round-trip [guard pattern](/servers/elicitation#elicitation-on-the-modern-protocol)
+and *removed* the server-initiated back-channel (`ctx.elicit`, `ctx.sample`,
+`ctx.list_roots`) that the handshake eras provide. Neither era is a superset of
+the other, so a server can legitimately need either one.
+
+When a server's whole purpose depends on an era, a client that cannot speak it
+should be told at connect time. Today it finds out mid-call: a handshake-era
+client happily connects to a guard-tool server, lists its tools, calls one, and
+only then gets an era error — a failure surfacing far from its cause. Declaring
+the versions the server serves moves that failure to the connection.
+
+### Declaring versions
+
+Pass the protocol versions the server is willing to serve. The MCP SDK exposes
+each era as a tuple, and those tuples are the durable way to name an era — they
+grow on their own when the SDK adds a revision, so a server pinned to
+`MODERN_PROTOCOL_VERSIONS` keeps working across SDK upgrades:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import InputRequiredResult
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+
+mcp = FastMCP("guarded", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+
+@mcp.tool
+def confirm(action: str) -> str | InputRequiredResult:
+ ... # a guard tool: multi-round trips exist only on the modern era
+```
+
+A server built around the back-channel declares the other era:
+
+```python
+from fastmcp import Context, FastMCP
+from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS
+
+mcp = FastMCP("interviewer", protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS)
+
+
+@mcp.tool
+async def interview(ctx: Context) -> str:
+ answer = await ctx.elicit("What is your name?", response_type=str)
+ return f"Hello, {answer.data}"
+```
+
+You can also pin exact versions, which is what a server certified against a
+single modern revision wants:
+
+```python
+mcp = FastMCP("pinned", protocol_versions=["2026-07-28"])
+```
+
+Exact-revision pinning is enforceable for **modern** versions, which a client
+pins in every per-request envelope. It is not enforceable *within* the handshake
+era: the SDK negotiates the handshake revision and FastMCP can only veto a
+connection, not steer it, so pinning `["2025-06-18"]` still admits a client that
+negotiates `2025-11-25` — the pin asserts the handshake era, and the connection
+settles on whatever the SDK negotiated. See [Membership, not a
+minimum](#membership-not-a-minimum) below.
+
+Any string the SDK does not recognize raises `ValueError` at construction. A
+version the SDK could never negotiate is a bug in the server, not a runtime
+condition worth warning about.
+
+### Membership, not a minimum
+
+The declaration is a **set**, not a floor. Versions are an enumerated set rather
+than an ordered scale — the SDK says so directly, and future revision
+identifiers are not guaranteed to be date-shaped or sortable. This is what makes
+"handshake only" expressible at all: under a minimum-version model there is no
+way to say "the session era", because the modern era is numerically newer while
+lacking the features that era depends on.
+
+Membership is enforced **era-aware**, because FastMCP can only veto a connection
+— never steer the version the peer settles on — and the two eras negotiate
+differently. A modern version is pinned exactly in each per-request envelope, so
+a modern-version declaration enforces exact membership: a request at a modern
+version outside the set is refused. A handshake connection is negotiated by the
+SDK's initialize handler, which honors the client's requested revision (or
+counters with the newest handshake revision) with no knowledge of your
+declaration — FastMCP cannot make it counter-offer a specific revision. So a
+handshake-version declaration enforces the handshake *era*: a server that
+declares any handshake version accepts the handshake and runs at whatever
+revision the SDK negotiated, and only a server that declares no handshake version
+(a modern-only server) refuses it. What a handshake-version declaration
+enforces is therefore the era boundary, not a specific handshake revision.
+
+### What clients see
+
+A refused connection gets the spec-standard `-32022` unsupported-protocol-version
+error carrying the server's supported list, so a negotiating client treats it as
+guidance rather than a dead end:
+
+| Server declares | `mode="auto"` client | `mode="legacy"` client | Client pinned to `2026-07-28` |
+| --- | --- | --- | --- |
+| nothing (default) | modern | handshake | modern |
+| `MODERN_PROTOCOL_VERSIONS` | modern | refused | modern |
+| `HANDSHAKE_PROTOCOL_VERSIONS` | falls back to handshake | handshake | refused |
+
+An `auto` client refused at `server/discover` by a handshake-only server reads
+the handshake versions out of the error and completes the connection over
+`initialize` on its own — the restriction steers negotiation instead of breaking
+it. Only a client with no mutual version is refused outright, which is the point.
+
+Enforcement covers both connection paths FastMCP owns. The initialize handshake
+is refused before it commits. Modern connections are checked on the request
+itself, because a client pinned to a modern version never probes
+`server/discover` — refusing discovery alone would let it straight through.
+
+
+`fastmcp.Client` connects in-memory over the handshake by default, so testing a
+modern-only server in-process needs `Client(mcp, mode="auto")`. Over HTTP and
+stdio the default `auto` negotiation applies and no change is needed.
+
+
+### Startup coherence check
+
+FastMCP knows what is registered, so at startup it warns — never fails — when a
+declared version set cannot carry a capability the server actually uses. A
+handshake-only server registering a guard tool gets a warning naming the tool; a
+modern-only server configuring a `sampling_handler` with
+`sampling_handler_behavior="fallback"` gets one too, because the modern era has
+no back-channel for the fallback to reach.
+
+The check is **silent unless you declared something**. A server with ten
+ordinary tools and one guard tool is fine as-is: the guard tool raises a clear
+era error if an old client reaches for it, and warning about that at startup
+would only teach people to ignore warnings. The check fires when you asserted
+something and the registration contradicts the assertion.
+
+Detection is deliberately conservative. `ctx.elicit`, `ctx.sample`, and
+`ctx.list_roots` are runtime calls with no reliable static signal, so only
+configuration-level contradictions are caught — a missed case is a silent
+startup, never a false alarm.
+
## Still in the program
Elicitation on the modern protocol is now shipped in its **guard form** — a tool returns an `InputRequiredResult` and re-runs per round to gather user input via multi-round trips (see [Elicitation on the modern protocol](/servers/elicitation#elicitation-on-the-modern-protocol)). The declarative `Resolve(...)` layer over that primitive remains staged, tracked in the [Feature Program](/development/v4-notes/feature-program), along with the unified `subscriptions/listen` stream. The [Known Gaps](/development/v4-notes/known-gaps) page tracks the upstream dependencies that gate them.
diff --git a/fastmcp_slim/fastmcp/server/low_level.py b/fastmcp_slim/fastmcp/server/low_level.py
index 927ccf9de..17856e5c6 100644
--- a/fastmcp_slim/fastmcp/server/low_level.py
+++ b/fastmcp_slim/fastmcp/server/low_level.py
@@ -181,6 +181,7 @@ class FastMCPServerMiddleware:
self, ctx: ServerRequestContext, call_next: CallNext
) -> HandlerResult:
from fastmcp.server.dependencies import bind_request_context
+ from fastmcp.server.protocol_versions import protocol_version_error
fastmcp = self._ref()
with (
@@ -192,6 +193,18 @@ class FastMCPServerMiddleware:
return await call_next(ctx)
if ctx.method == "initialize" and ctx.request_id is not None:
return await self._run_initialize_mw(fastmcp, ctx, call_next)
+ # Refuse a request whose protocol version the server does not serve.
+ # The handshake is vetoed at `initialize` above; a modern connection
+ # has no handshake to veto (a client pinned to a modern version can
+ # skip `server/discover` entirely), so the request itself is the
+ # enforcement point. Routing the refusal through the outer pass lets
+ # `on_message`/`on_request` observe it like any other early failure.
+ if ctx.request_id is not None:
+ version_error = protocol_version_error(fastmcp, ctx.protocol_version)
+ if version_error is not None:
+ return await self._run_outer_mw(
+ fastmcp, ctx, call_next, _raise=version_error
+ )
if ctx.request_id is not None and ctx.method in _INTERIOR_METHODS:
return await self._dispatch_component(fastmcp, ctx, call_next)
return await self._run_outer_mw(fastmcp, ctx, call_next, _raise=None)
@@ -326,6 +339,9 @@ class FastMCPServerMiddleware:
) -> HandlerResult:
from fastmcp.server.context import Context
from fastmcp.server.middleware.middleware import MiddlewareContext
+ from fastmcp.server.protocol_versions import (
+ enforce_handshake_protocol_version,
+ )
# Reconstruct the InitializeRequest from the raw params so FastMCP
# middleware `on_initialize` hooks that inspect the message still work.
@@ -348,6 +364,12 @@ class FastMCPServerMiddleware:
async def call_original_handler(
_mw_ctx: MiddlewareContext,
) -> mcp_types.InitializeResult | None:
+ # Refuse the handshake before it commits when the negotiated version
+ # is not one the server serves. Raising MCPError here (before
+ # call_next) vetoes initialize on the framework-owned path, so the
+ # client sees a clear connect-time refusal instead of a runtime era
+ # error mid tool-call.
+ enforce_handshake_protocol_version(fastmcp, init_message)
# call_next(ctx) runs the rest of the SDK chain, which for
# initialize returns the serialized InitializeResult dict. FastMCP
# middleware `on_initialize` hooks expect a typed InitializeResult,
diff --git a/fastmcp_slim/fastmcp/server/mixins/lifespan.py b/fastmcp_slim/fastmcp/server/mixins/lifespan.py
index 77374d3f7..fbed10731 100644
--- a/fastmcp_slim/fastmcp/server/mixins/lifespan.py
+++ b/fastmcp_slim/fastmcp/server/mixins/lifespan.py
@@ -246,6 +246,15 @@ class LifespanMixin:
for provider in self.providers:
await stack.enter_async_context(provider.lifespan())
+ # Warn (never raise) when a declared `protocol_versions` set cannot
+ # carry a capability the server actually uses — e.g. modern-only
+ # guard tools under a handshake-only declaration. Silent when the
+ # server declared nothing. Runs once per fresh lifespan entry, after
+ # all providers are mounted so their components are visible.
+ from fastmcp.server.protocol_versions import check_protocol_coherence
+
+ await check_protocol_coherence(self)
+
self._started.set()
try:
yield
diff --git a/fastmcp_slim/fastmcp/server/protocol_versions.py b/fastmcp_slim/fastmcp/server/protocol_versions.py
new file mode 100644
index 000000000..f7399fb0c
--- /dev/null
+++ b/fastmcp_slim/fastmcp/server/protocol_versions.py
@@ -0,0 +1,373 @@
+"""Server protocol-version restriction: declaration, enforcement, and startup
+coherence checks.
+
+A FastMCP server may depend on features that exist on only one MCP protocol era.
+The modern (``2026-07-28``) era added the multi-round-trip "guard" pattern
+(SEP-2322) and *removed* the server-initiated back-channel (``ctx.elicit``,
+``ctx.sample``, ``ctx.list_roots``) that the handshake eras provide. Neither era
+is a superset of the other, so a server can legitimately require either one.
+
+Protocol versions are therefore modeled the way the SDK models them — as *an
+enumerated set, not an ordered scalar* (see ``mcp_types.version``). A server
+declares the set of protocol versions it is willing to serve, and enforcement is
+set membership:
+
+ from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+
+ FastMCP("guarded", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+The SDK's era tuples are the durable way to name an era: they grow on their own
+when the SDK adds a revision to an era, so a server pinned to
+``MODERN_PROTOCOL_VERSIONS`` keeps working across SDK upgrades without FastMCP
+inventing alias vocabulary of its own.
+
+Enforcement happens at both connection paths FastMCP owns:
+
+* the initialize handshake, refused before the handshake commits;
+* every modern per-request envelope, refused on the request itself. A client
+ pinned to a modern version never probes ``server/discover``, so refusing
+ discovery alone would not cover it — the request *is* the connection.
+
+Refusals use the spec-standard ``-32022`` unsupported-protocol-version error
+carrying the server's supported list, so a negotiating (``mode="auto"``) client
+reads it as guidance rather than as a dead end: refused at ``server/discover``
+by a handshake-only server, it sees handshake versions in ``supported`` and
+falls back to the initialize handshake on its own.
+
+FastMCP can only *veto* a connection, never steer the version the peer settles
+on, and the two eras negotiate their version differently — so enforcement is
+era-aware. A modern connection pins an exact version in every per-request
+envelope, so a modern-version declaration enforces exact membership. The
+handshake era is negotiated by the SDK's initialize handler
+(``ServerRunner._negotiate_initialize``), which honors the client's requested
+revision (or counters with the newest handshake revision) with no knowledge of
+this declaration; FastMCP cannot make it counter-offer a specific revision. A
+handshake-version declaration therefore enforces *era* membership, not an exact
+revision: a server that declares any handshake version serves the handshake era
+and accepts the handshake, running at whatever revision the SDK negotiates, and
+only a server that declares no handshake version refuses it. Pinning a single
+handshake revision (``["2025-06-18"]``) narrows nothing the SDK will honor — the
+connection still settles on whatever revision the client and SDK negotiate.
+
+Declaring nothing (the default) serves every era the SDK supports.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from mcp.shared.exceptions import MCPError
+from mcp_types import (
+ UNSUPPORTED_PROTOCOL_VERSION,
+ UnsupportedProtocolVersionErrorData,
+)
+from mcp_types.version import (
+ HANDSHAKE_PROTOCOL_VERSIONS,
+ KNOWN_PROTOCOL_VERSIONS,
+ LATEST_HANDSHAKE_VERSION,
+ MODERN_PROTOCOL_VERSIONS,
+)
+
+from fastmcp.tools.function_parsing import _contains_input_required
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+ import mcp_types
+
+ from fastmcp.server.server import FastMCP
+ from fastmcp.tools.base import Tool
+
+logger = get_logger(__name__)
+
+
+def validate_protocol_versions(
+ value: Iterable[str] | None,
+) -> tuple[str, ...] | None:
+ """Validate and normalize a declared set of protocol versions.
+
+ Returns ``None`` unchanged (no restriction), or the declared versions as a
+ deduplicated tuple in SDK order. Raises ``ValueError`` for an empty set (a
+ server that serves no protocol version can never be reached) or for any
+ string the SDK does not recognize — a version the SDK could never negotiate
+ is a programming error, not a runtime condition to warn about.
+ """
+ if value is None:
+ return None
+ declared = list(value)
+ unknown = [v for v in declared if v not in KNOWN_PROTOCOL_VERSIONS]
+ if unknown:
+ raise ValueError(
+ f"protocol_versions contains unknown MCP protocol version(s): "
+ f"{', '.join(repr(v) for v in unknown)}. "
+ f"Known versions: {', '.join(KNOWN_PROTOCOL_VERSIONS)}. "
+ f"Prefer the SDK's era tuples "
+ f"(mcp_types.version.MODERN_PROTOCOL_VERSIONS / "
+ f"HANDSHAKE_PROTOCOL_VERSIONS) over literal strings."
+ )
+ normalized = tuple(v for v in KNOWN_PROTOCOL_VERSIONS if v in declared)
+ if not normalized:
+ raise ValueError(
+ "protocol_versions must name at least one protocol version. "
+ "Pass None (the default) to serve every protocol version."
+ )
+ return normalized
+
+
+def describe_protocol_versions(versions: Sequence[str]) -> str:
+ """Human-readable description of a declared version set for error messages."""
+ if tuple(versions) == MODERN_PROTOCOL_VERSIONS:
+ return (
+ f"the modern protocol ({', '.join(versions)}), reached via server/discover"
+ )
+ if tuple(versions) == HANDSHAKE_PROTOCOL_VERSIONS:
+ return f"the handshake protocol ({', '.join(versions)}), reached via initialize"
+ return ", ".join(versions)
+
+
+def _remedy_for(versions: Sequence[str]) -> str:
+ """Actionable next step for a client that failed the version check."""
+ wants_modern = any(v in MODERN_PROTOCOL_VERSIONS for v in versions)
+ wants_handshake = any(v in HANDSHAKE_PROTOCOL_VERSIONS for v in versions)
+ if wants_modern and not wants_handshake:
+ return "Connect using the modern protocol (server/discover) instead."
+ if wants_handshake and not wants_modern:
+ return "Connect using the initialize handshake instead."
+ return "Use one of the protocol versions this server serves."
+
+
+def _serves_version(allowed: Sequence[str], version: str) -> bool:
+ """Whether a server declaring ``allowed`` serves a connection at ``version``.
+
+ Enforcement is era-aware because the two eras negotiate their version
+ differently and FastMCP can only *veto* a connection — never steer the
+ version the peer settles on:
+
+ * A modern version rides a per-request envelope that pins an exact version,
+ so membership is exact: the server serves it only when ``version`` is in
+ ``allowed``.
+ * A handshake version is negotiated by the SDK's initialize handler, which
+ honors the client's requested revision (or counters with the newest
+ handshake revision) with no knowledge of ``allowed``. FastMCP cannot make
+ the SDK counter-offer a specific revision, so a handshake-version pin
+ asserts *era* membership only: the server serves the handshake connection
+ when it declared any handshake version, whatever revision the SDK settled
+ on.
+ """
+ if version in HANDSHAKE_PROTOCOL_VERSIONS:
+ return not set(allowed).isdisjoint(HANDSHAKE_PROTOCOL_VERSIONS)
+ return version in allowed
+
+
+def protocol_version_error(fastmcp: FastMCP, version: str) -> MCPError | None:
+ """The refusal for ``version``, or ``None`` when the server serves it.
+
+ A server that declared nothing (the default) serves every version and never
+ refuses. Otherwise the decision is era-aware set membership (see
+ ``_serves_version``): a modern version must be an exact member, while a
+ handshake version is served whenever the declaration includes any handshake
+ version, because the SDK negotiates the handshake revision and FastMCP can
+ only veto — not steer — the version the connection settles on. A
+ handshake-only server still refuses modern connections just as a modern-only
+ server refuses handshake connections; only within-handshake revision pinning
+ is unenforceable.
+
+ The refusal is the spec-standard ``-32022`` unsupported-protocol-version
+ error carrying the server's supported list, which is what a negotiating
+ client already knows how to read: an ``auto`` client refused at
+ ``server/discover`` sees handshake versions in ``supported`` and falls back
+ to the initialize handshake instead of failing the connect.
+ """
+ allowed = fastmcp.protocol_versions
+ if allowed is None or _serves_version(allowed, version):
+ return None
+ return MCPError(
+ code=UNSUPPORTED_PROTOCOL_VERSION,
+ message=(
+ f"Server {fastmcp.name!r} serves {describe_protocol_versions(allowed)}; "
+ f"this connection uses MCP protocol version {version}. "
+ f"{_remedy_for(allowed)}"
+ ),
+ data=UnsupportedProtocolVersionErrorData(
+ supported=list(allowed), requested=version
+ ).model_dump(by_alias=True, mode="json"),
+ )
+
+
+def handshake_negotiated_version(requested: str | None) -> str:
+ """The version an initialize handshake would settle on for ``requested``.
+
+ Mirrors the SDK's ``ServerRunner._negotiate_initialize``: a client's
+ requested handshake revision is honored; anything else (an unknown string,
+ or a modern-era version the handshake cannot serve) counters with the newest
+ handshake revision. The connection operates at the returned version, so it is
+ the honest value to report as ``requested`` when a modern-only server refuses
+ the handshake — the enforcement decision itself is era-aware (see
+ ``_serves_version``) and does not turn on this exact revision.
+ """
+ if requested is not None and requested in HANDSHAKE_PROTOCOL_VERSIONS:
+ return requested
+ return LATEST_HANDSHAKE_VERSION
+
+
+def enforce_handshake_protocol_version(
+ fastmcp: FastMCP,
+ init_message: mcp_types.InitializeRequest | None,
+) -> None:
+ """Refuse an initialize handshake the server does not serve.
+
+ Called from the framework-owned initialize path before the handshake
+ commits, so the client sees a clear connect-time refusal naming what the
+ server serves instead of a confusing era error mid tool-call.
+
+ Enforcement is era-level (see ``_serves_version``): a server that declares
+ any handshake version serves the handshake era and accepts the handshake,
+ even when the client offers a different handshake revision than the one
+ pinned — the SDK negotiates the revision and FastMCP cannot steer it, only
+ veto. The refusal fires only for a genuine cross-era mismatch: a modern-only
+ server has no handshake version to share, so it refuses the handshake and
+ names the modern versions it does serve.
+ """
+ if fastmcp.protocol_versions is None or init_message is None:
+ return
+ requested = init_message.params.protocol_version
+ error = protocol_version_error(fastmcp, handshake_negotiated_version(requested))
+ if error is not None:
+ raise error
+
+
+# ---------------------------------------------------------------------------
+# Capability map
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProtocolCapability:
+ """A server-side capability that only some protocol versions can carry.
+
+ ``detect`` returns evidence (tool names, a configuration description) that
+ the server actually uses the capability, and is consulted only when the
+ declared version set cannot carry it — so detection never costs anything on
+ a server that declared nothing.
+ """
+
+ key: str
+ label: str
+ versions: tuple[str, ...]
+ remedy: str
+ detect: Callable[[FastMCP, Sequence[Tool]], list[str]]
+
+
+def tool_uses_multi_round_trip(tool: Tool) -> bool:
+ """True when a tool's return annotation makes it a modern-only guard tool.
+
+ A guard tool (SEP-2322) returns an ``InputRequiredResult`` to ask the client
+ for input across rounds; that pattern exists only on the modern era.
+ Detection reuses ``_contains_input_required`` over the tool's captured return
+ annotation, so every union/alias/``Annotated`` shape the parser recognizes is
+ covered. Only ``FunctionTool`` carries a return annotation; other tool kinds
+ return ``False`` (a conservative miss, not a false positive).
+ """
+ if not isinstance(tool, FunctionTool):
+ return False
+ return _contains_input_required(tool.return_type)
+
+
+def _detect_multi_round_trip(fastmcp: FastMCP, tools: Sequence[Tool]) -> list[str]:
+ return sorted(t.name for t in tools if tool_uses_multi_round_trip(t))
+
+
+def _detect_client_back_channel(fastmcp: FastMCP, tools: Sequence[Tool]) -> list[str]:
+ """Configuration-level evidence that the server wants the client back-channel.
+
+ ``ctx.elicit`` / ``ctx.sample`` / ``ctx.list_roots`` are *runtime* calls with
+ no reliable static signal, so only configuration contradictions are
+ detectable. A ``sampling_handler`` set to ``"fallback"`` says "prefer the
+ client's model, fall back to mine" — a preference that cannot be honored on a
+ protocol version without the back-channel.
+ """
+ if (
+ fastmcp.sampling_handler is not None
+ and fastmcp.sampling_handler_behavior == "fallback"
+ ):
+ return ["sampling_handler with behavior='fallback'"]
+ return []
+
+
+PROTOCOL_CAPABILITIES: tuple[ProtocolCapability, ...] = (
+ ProtocolCapability(
+ key="multi_round_trip",
+ label="multi-round-trip guard tools (they return InputRequiredResult)",
+ versions=MODERN_PROTOCOL_VERSIONS,
+ remedy=(
+ "Include the modern versions in protocol_versions "
+ "(mcp_types.version.MODERN_PROTOCOL_VERSIONS), or stop returning "
+ "InputRequiredResult from these tools."
+ ),
+ detect=_detect_multi_round_trip,
+ ),
+ ProtocolCapability(
+ key="client_back_channel",
+ label=(
+ "the server-initiated client back-channel "
+ "(ctx.elicit / ctx.sample / ctx.list_roots)"
+ ),
+ versions=HANDSHAKE_PROTOCOL_VERSIONS,
+ remedy=(
+ "Include the handshake versions in protocol_versions "
+ "(mcp_types.version.HANDSHAKE_PROTOCOL_VERSIONS), or use "
+ "sampling_handler_behavior='always' so the local handler is the "
+ "intended path."
+ ),
+ detect=_detect_client_back_channel,
+ ),
+ # Extension point: a capability that only some protocol versions can carry
+ # is one entry here, not a new special case in the check below. The 2026
+ # tasks extension is the next expected entry — when FastMCP implements it,
+ # add a ProtocolCapability naming the versions that carry it and a `detect`
+ # that reports the registered task-enabled components.
+)
+
+
+async def check_protocol_coherence(fastmcp: FastMCP) -> None:
+ """Warn at startup when a declared version set contradicts what is registered.
+
+ Warning-only by design, and **silent unless the server declared a version
+ set**. A server with an ordinary mix of tools is fine: a guard tool raises a
+ clear era error if an old client reaches for it, and warning about that at
+ startup would train people to ignore warnings. The check fires only when the
+ author asserted something and the registration contradicts the assertion.
+ """
+ allowed = fastmcp.protocol_versions
+ if allowed is None:
+ return
+
+ unmet = [c for c in PROTOCOL_CAPABILITIES if set(allowed).isdisjoint(c.versions)]
+ if not unmet:
+ return
+
+ # Inspect only this server's directly-registered tools. Aggregating mounted
+ # children would route through their middleware chains (a startup side
+ # effect); mounted or transformed components are a conservative miss, not a
+ # false positive. `LocalProvider.list_tools` is side-effect-free.
+ try:
+ tools: list[Tool] = list(await fastmcp._local_provider.list_tools())
+ except (LookupError, RuntimeError, ValueError) as exc:
+ logger.debug("Protocol coherence check could not list tools: %s", exc)
+ tools = []
+
+ for capability in unmet:
+ evidence = capability.detect(fastmcp, tools)
+ if not evidence:
+ continue
+ logger.warning(
+ "Server %r declares protocol_versions=%s, which cannot carry %s, "
+ "but the server uses it: %s. %s",
+ fastmcp.name,
+ list(allowed),
+ capability.label,
+ ", ".join(evidence),
+ capability.remedy,
+ )
diff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.py
index 88a7624d9..dc1fd3589 100644
--- a/fastmcp_slim/fastmcp/server/server.py
+++ b/fastmcp_slim/fastmcp/server/server.py
@@ -8,6 +8,7 @@ import secrets
from collections.abc import (
AsyncIterator,
Callable,
+ Iterable,
Sequence,
)
from contextlib import (
@@ -77,6 +78,7 @@ from fastmcp.server.middleware.middleware import (
mark_interior_dispatched,
)
from fastmcp.server.mixins import LifespanMixin, MCPOperationsMixin, TransportMixin
+from fastmcp.server.protocol_versions import validate_protocol_versions
from fastmcp.server.providers import LocalProvider, Provider
from fastmcp.server.providers.aggregate import AggregateProvider
from fastmcp.server.tasks.config import TaskConfig, TaskMeta
@@ -356,6 +358,7 @@ class FastMCP(
session_state_store: AsyncKeyValue | None = None,
sampling_handler: SamplingHandler | None = None,
sampling_handler_behavior: Literal["always", "fallback"] | None = None,
+ protocol_versions: Iterable[str] | None = None,
client_log_level: mcp_types.LoggingLevel | None = None,
experimental_capabilities: dict[str, dict[str, Any]] | None = None,
**kwargs: Any,
@@ -530,6 +533,16 @@ class FastMCP(
sampling_handler_behavior or "fallback"
)
+ # The set of MCP protocol versions this server is willing to serve.
+ # Enforced by set membership at both connection paths (the initialize
+ # handshake and the modern per-request envelope) and checked for
+ # coherence against registered features at startup. `None` (the default)
+ # declares no restriction: the server serves every protocol version the
+ # SDK supports, fully backward compatible.
+ self._protocol_versions: tuple[str, ...] | None = validate_protocol_versions(
+ protocol_versions
+ )
+
def __repr__(self) -> str:
return f"{type(self).__name__}({self.name!r})"
@@ -549,6 +562,15 @@ class FastMCP(
def version(self) -> str | None:
return self._mcp_server.version
+ @property
+ def protocol_versions(self) -> tuple[str, ...] | None:
+ """The MCP protocol versions this server serves, if restricted.
+
+ `None` (the default) means no restriction: every protocol version the
+ SDK supports is served. Otherwise the declared versions, in SDK order.
+ """
+ return self._protocol_versions
+
@property
def website_url(self) -> str | None:
return self._mcp_server.website_url
diff --git a/tests/server/test_protocol_versions.py b/tests/server/test_protocol_versions.py
new file mode 100644
index 000000000..6b54ab446
--- /dev/null
+++ b/tests/server/test_protocol_versions.py
@@ -0,0 +1,496 @@
+"""Server protocol-version restriction: declaration, enforcement, and startup
+coherence checks.
+
+A server declares the *set* of protocol versions it serves. Membership — not
+ordering — decides whether a connection is accepted, so a handshake-only server
+refuses modern connections just as a modern-only server refuses handshake
+connections. Enforcement is era-aware: FastMCP can only veto a connection, and
+the SDK negotiates the handshake revision with no knowledge of the declaration,
+so a handshake-version pin asserts the handshake *era*, not an exact revision. A
+startup check warns (never raises) when a declared set cannot carry a capability
+the server actually uses, and stays silent when nothing was declared.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import mcp_types
+import pytest
+from exceptiongroup import BaseExceptionGroup
+from mcp.client import Client as SDKClient
+from mcp.server import Server as LowLevelServer
+from mcp.shared.exceptions import MCPError
+from mcp_types.version import (
+ HANDSHAKE_PROTOCOL_VERSIONS,
+ MODERN_PROTOCOL_VERSIONS,
+)
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.server.protocol_versions import (
+ enforce_handshake_protocol_version,
+ handshake_negotiated_version,
+ tool_uses_multi_round_trip,
+ validate_protocol_versions,
+)
+from fastmcp.tools.base import Tool
+
+_COHERENCE_LOGGER = "fastmcp.server.protocol_versions"
+
+
+def _server(mcp: FastMCP) -> LowLevelServer:
+ """The lowlevel Server the SDK client connects to in-process."""
+ return mcp._mcp_server
+
+
+def _find_mcp_error(exc: BaseException) -> MCPError | None:
+ """Unwrap the MCPError a refused in-memory connection surfaces.
+
+ The legacy in-memory transport runs ``initialize`` inside a task group, so a
+ connect-time refusal propagates as an ``ExceptionGroup`` wrapping the
+ ``MCPError`` rather than the bare error.
+ """
+ if isinstance(exc, MCPError):
+ return exc
+ if isinstance(exc, BaseExceptionGroup):
+ for inner in exc.exceptions:
+ found = _find_mcp_error(inner)
+ if found is not None:
+ return found
+ if exc.__cause__ is not None:
+ return _find_mcp_error(exc.__cause__)
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Construction-time validation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+ "declared, expected",
+ [
+ (None, None),
+ (MODERN_PROTOCOL_VERSIONS, ("2026-07-28",)),
+ (HANDSHAKE_PROTOCOL_VERSIONS, HANDSHAKE_PROTOCOL_VERSIONS),
+ (["2026-07-28"], ("2026-07-28",)),
+ (["2025-06-18", "2026-07-28"], ("2025-06-18", "2026-07-28")),
+ # Normalized to SDK order, deduplicated.
+ (["2026-07-28", "2024-11-05", "2026-07-28"], ("2024-11-05", "2026-07-28")),
+ # Any iterable, not just a sequence.
+ ({"2025-11-25"}, ("2025-11-25",)),
+ ],
+)
+def test_valid_protocol_versions_normalized(declared, expected):
+ assert validate_protocol_versions(declared) == expected
+ assert FastMCP("s", protocol_versions=declared).protocol_versions == expected
+
+
+@pytest.mark.parametrize(
+ "declared",
+ [["9999-01-01"], ["modern"], ["2026"], [""], ["2026-07-28", "handshake"]],
+)
+def test_unknown_protocol_version_rejected(declared):
+ with pytest.raises(ValueError, match="unknown MCP protocol version"):
+ validate_protocol_versions(declared)
+ with pytest.raises(ValueError, match="unknown MCP protocol version"):
+ FastMCP("s", protocol_versions=declared)
+
+
+def test_empty_protocol_versions_rejected():
+ with pytest.raises(ValueError, match="at least one protocol version"):
+ validate_protocol_versions([])
+ with pytest.raises(ValueError, match="at least one protocol version"):
+ FastMCP("s", protocol_versions=[])
+
+
+def test_default_serves_every_version():
+ assert FastMCP("s").protocol_versions is None
+
+
+# ---------------------------------------------------------------------------
+# Handshake negotiation mirror
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+ "requested, expected",
+ [
+ ("2025-11-25", "2025-11-25"),
+ ("2025-06-18", "2025-06-18"),
+ ("2024-11-05", "2024-11-05"),
+ # A modern-era or unknown request counters with the newest handshake.
+ ("2026-07-28", "2025-11-25"),
+ ("garbage", "2025-11-25"),
+ (None, "2025-11-25"),
+ ],
+)
+def test_handshake_negotiated_version(requested, expected):
+ assert handshake_negotiated_version(requested) == expected
+
+
+# ---------------------------------------------------------------------------
+# Guard-tool detection
+# ---------------------------------------------------------------------------
+
+
+def test_guard_tool_detected():
+ def guard(x: int) -> str | mcp_types.InputRequiredResult:
+ return "ok"
+
+ assert tool_uses_multi_round_trip(Tool.from_function(guard)) is True
+
+
+def test_plain_tool_not_flagged():
+ def plain(x: int) -> int:
+ return x
+
+ assert tool_uses_multi_round_trip(Tool.from_function(plain)) is False
+
+
+# ---------------------------------------------------------------------------
+# Enforcement: modern-only server refuses handshake clients
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def modern_only_server() -> FastMCP:
+ mcp = FastMCP("modern-only", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ return mcp
+
+
+async def test_modern_only_refuses_handshake(modern_only_server):
+ with pytest.raises(BaseException) as excinfo:
+ async with SDKClient(_server(modern_only_server), mode="legacy") as client:
+ await client.list_tools()
+ err = _find_mcp_error(excinfo.value)
+ assert err is not None
+ assert err.code == mcp_types.UNSUPPORTED_PROTOCOL_VERSION
+ assert "2026-07-28" in err.message
+ assert "server/discover" in err.message
+
+
+@pytest.mark.parametrize("mode", ["auto", "2026-07-28"])
+async def test_modern_only_allows_modern(modern_only_server, mode):
+ async with SDKClient(_server(modern_only_server), mode=mode) as client:
+ result = await client.list_tools()
+ assert [t.name for t in result.tools] == ["add"]
+
+
+# ---------------------------------------------------------------------------
+# Enforcement: handshake-only server refuses modern clients
+#
+# This case is only expressible because the declaration is a set, not a bound:
+# under a minimum-version model there was no way to say "the session era".
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def handshake_only_server() -> FastMCP:
+ mcp = FastMCP("handshake-only", protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ return mcp
+
+
+async def test_handshake_only_allows_handshake(handshake_only_server):
+ async with SDKClient(_server(handshake_only_server), mode="legacy") as client:
+ assert client.protocol_version == "2025-11-25"
+ result = await client.list_tools()
+ assert [t.name for t in result.tools] == ["add"]
+
+
+async def test_handshake_only_refuses_pinned_modern_client(handshake_only_server):
+ """A client pinned to a modern version never probes discover, so the refusal
+ has to land on the request itself."""
+ with pytest.raises(BaseException) as excinfo:
+ async with SDKClient(
+ _server(handshake_only_server), mode="2026-07-28"
+ ) as client:
+ await client.list_tools()
+ err = _find_mcp_error(excinfo.value)
+ assert err is not None
+ assert err.code == mcp_types.UNSUPPORTED_PROTOCOL_VERSION
+ assert "initialize" in err.message
+
+
+# ---------------------------------------------------------------------------
+# Enforcement: pinned single version, and the unrestricted default
+# ---------------------------------------------------------------------------
+
+
+async def test_pinned_version_allows_exact_match():
+ mcp = FastMCP("pinned", protocol_versions=["2025-11-25"])
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ async with SDKClient(_server(mcp), mode="legacy") as client:
+ assert client.protocol_version == "2025-11-25"
+ result = await client.list_tools()
+ assert [t.name for t in result.tools] == ["add"]
+
+
+def _initialize_request(version: str) -> mcp_types.InitializeRequest:
+ return mcp_types.InitializeRequest.model_validate(
+ {
+ "method": "initialize",
+ "params": {
+ "protocolVersion": version,
+ "capabilities": {},
+ "clientInfo": {"name": "test", "version": "1"},
+ },
+ }
+ )
+
+
+@pytest.mark.parametrize("offered", ["2024-11-05", "2025-03-26", "2025-06-18"])
+def test_pinned_version_accepts_other_handshake_revision(offered):
+ """A handshake-version pin asserts the handshake *era*, not an exact revision.
+
+ FastMCP can only veto the handshake, and the SDK negotiates the revision with
+ no knowledge of the pin — so a server pinned to one handshake revision still
+ accepts a client offering another handshake revision. The connection just
+ settles on whatever the SDK negotiated, not on the pinned revision. (This
+ replaces a test that asserted the opposite, which encoded the pre-fix bug:
+ refusing an ordinary handshake client whenever it offered a handshake
+ revision other than the pinned one.)
+ """
+ mcp = FastMCP("pinned", protocol_versions=["2025-11-25"])
+
+ # No raise: the pinned revision and the offered revision are both handshake.
+ enforce_handshake_protocol_version(mcp, _initialize_request(offered))
+
+
+def test_pinned_version_accepts_matching_handshake():
+ mcp = FastMCP("pinned", protocol_versions=["2025-11-25"])
+ enforce_handshake_protocol_version(mcp, _initialize_request("2025-11-25"))
+
+
+@pytest.mark.parametrize("offered", ["2025-11-25", "2025-06-18", "garbage", None])
+def test_older_handshake_pin_accepts_any_handshake_offer_at_hook(offered):
+ """The review-comment bug, at the enforcement hook.
+
+ A server pinned to an older handshake revision must not refuse a client that
+ offers a newer (or unknown, which the SDK counters to the newest) handshake
+ revision. The SDK negotiates within the handshake era regardless of the pin,
+ and FastMCP cannot counter-offer the pinned revision — only veto — so the
+ honest behavior is to accept, since the server does serve the handshake era.
+ """
+ mcp = FastMCP("older-pin", protocol_versions=["2024-11-05"])
+
+ # No raise: the server serves the handshake era, so the handshake is served.
+ enforce_handshake_protocol_version(mcp, _initialize_request(offered or "garbage"))
+
+
+async def test_older_handshake_pin_accepts_normal_client_end_to_end():
+ """End-to-end review-comment regression: a server pinned to `2024-11-05`
+ accepts an ordinary legacy client that requests `2025-11-25`.
+
+ The pin declares the handshake era; the SDK negotiates the revision. The
+ connection settles on `2025-11-25` (what the SDK negotiated), not the pinned
+ `2024-11-05`, which is exactly why a handshake-revision pin is era-level: the
+ server cannot force the client down to the pinned revision.
+ """
+ mcp = FastMCP("older-pin", protocol_versions=["2024-11-05"])
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ async with SDKClient(_server(mcp), mode="legacy") as client:
+ assert client.protocol_version == "2025-11-25"
+ result = await client.list_tools()
+ assert [t.name for t in result.tools] == ["add"]
+
+
+def test_unrestricted_server_never_refuses_handshake():
+ mcp = FastMCP("open")
+ enforce_handshake_protocol_version(mcp, _initialize_request("2024-11-05"))
+
+
+async def test_fastmcp_client_default_reaches_handshake_only_server():
+ """`fastmcp.Client` defaults to the handshake in memory, which a
+ handshake-only server serves directly."""
+ mcp = FastMCP("handshake-only", protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ async with Client(mcp) as client:
+ assert [t.name for t in await client.list_tools()] == ["add"]
+
+
+async def test_fastmcp_client_needs_modern_mode_for_modern_only_server():
+ """The mirror case: a modern-only server refuses the default in-memory
+ handshake, and the refusal names the modern protocol."""
+ mcp = FastMCP("modern-only", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ with pytest.raises(MCPError, match="server/discover"):
+ async with Client(mcp) as client:
+ await client.list_tools()
+
+ async with Client(mcp, mode="auto") as client:
+ assert [t.name for t in await client.list_tools()] == ["add"]
+
+
+@pytest.mark.parametrize("mode", ["legacy", "auto", "2026-07-28"])
+async def test_default_allows_every_era(mode):
+ mcp = FastMCP("open")
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ async with SDKClient(_server(mcp), mode=mode) as client:
+ result = await client.list_tools()
+ assert [t.name for t in result.tools] == ["add"]
+
+
+# ---------------------------------------------------------------------------
+# Startup coherence check (warnings only, silent unless declared)
+# ---------------------------------------------------------------------------
+
+
+def _coherence_warnings(caplog) -> list[str]:
+ return [
+ r.getMessage()
+ for r in caplog.records
+ if r.name == _COHERENCE_LOGGER and r.levelno == logging.WARNING
+ ]
+
+
+async def _warnings_from_startup(mcp: FastMCP, caplog) -> list[str]:
+ with caplog.at_level(logging.WARNING, logger=_COHERENCE_LOGGER):
+ async with mcp._lifespan_manager():
+ pass
+ return _coherence_warnings(caplog)
+
+
+async def test_guard_tool_without_declaration_is_silent(caplog):
+ """Declaring nothing asserts nothing, so there is no contradiction to warn
+ about — the guard tool raises its own clear era error if reached."""
+ mcp = FastMCP("guardy")
+
+ @mcp.tool
+ def ask(x: int) -> str | mcp_types.InputRequiredResult:
+ return "ok"
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_guard_tool_under_handshake_only_warns(caplog):
+ mcp = FastMCP("guardy", protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def ask(x: int) -> str | mcp_types.InputRequiredResult:
+ return "ok"
+
+ warnings = await _warnings_from_startup(mcp, caplog)
+ assert any("ask" in w and "InputRequiredResult" in w for w in warnings)
+
+
+async def test_guard_tool_under_modern_declaration_silent(caplog):
+ mcp = FastMCP("guardy", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def ask(x: int) -> str | mcp_types.InputRequiredResult:
+ return "ok"
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_guard_tool_under_mixed_declaration_silent(caplog):
+ """A declaration that still includes a modern version can carry guard tools."""
+ mcp = FastMCP("guardy", protocol_versions=["2025-11-25", "2026-07-28"])
+
+ @mcp.tool
+ def ask(x: int) -> str | mcp_types.InputRequiredResult:
+ return "ok"
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def _sampling_handler(messages, params, context):
+ return "x"
+
+
+async def test_fallback_sampling_under_modern_declaration_warns(caplog):
+ mcp = FastMCP(
+ "samp",
+ protocol_versions=MODERN_PROTOCOL_VERSIONS,
+ sampling_handler=_sampling_handler,
+ sampling_handler_behavior="fallback",
+ )
+
+ warnings = await _warnings_from_startup(mcp, caplog)
+ assert any("back-channel" in w and "fallback" in w for w in warnings)
+
+
+async def test_fallback_sampling_without_declaration_is_silent(caplog):
+ mcp = FastMCP(
+ "samp",
+ sampling_handler=_sampling_handler,
+ sampling_handler_behavior="fallback",
+ )
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_always_sampling_under_modern_declaration_silent(caplog):
+ mcp = FastMCP(
+ "samp",
+ protocol_versions=MODERN_PROTOCOL_VERSIONS,
+ sampling_handler=_sampling_handler,
+ sampling_handler_behavior="always",
+ )
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_fallback_sampling_under_handshake_only_silent(caplog):
+ mcp = FastMCP(
+ "samp",
+ protocol_versions=HANDSHAKE_PROTOCOL_VERSIONS,
+ sampling_handler=_sampling_handler,
+ sampling_handler_behavior="fallback",
+ )
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_plain_server_is_coherent(caplog):
+ mcp = FastMCP("clean", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ def plain(a: int) -> int:
+ return a
+
+ assert await _warnings_from_startup(mcp, caplog) == []
+
+
+async def test_guard_tool_reaches_modern_client():
+ """A guard tool served under a modern declaration works end-to-end."""
+ mcp = FastMCP("guarded", protocol_versions=MODERN_PROTOCOL_VERSIONS)
+
+ @mcp.tool
+ async def confirm(ctx: Context) -> str | mcp_types.InputRequiredResult:
+ return "confirmed"
+
+ async with SDKClient(_server(mcp), mode="auto") as client:
+ result = await client.call_tool("confirm", {})
+ assert result.is_error is False