Merge pull request #4572 from PrefectHQ/feature/client-auto-default

Negotiate the best mutual protocol era by default

Author: jlowin

docs/clients/auth/bearer.mdx

@@ -37,7 +37,7 @@ async with Client(
     "https://your-server.fastmcp.app/mcp", 
     auth="<your-token>",
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:
@@ -52,7 +52,7 @@ transport = StreamableHttpTransport(
 )
 
 async with Client(transport) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 ## `BearerAuth` Helper
@@ -67,7 +67,7 @@ async with Client(
     "https://your-server.fastmcp.app/mcp", 
     auth=BearerAuth(token="<your-token>"),
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 ## Custom Headers
@@ -84,5 +84,5 @@ async with Client(
         headers={"X-API-Key": "<your-token>"},
     ),
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```

docs/clients/auth/cimd.mdx

@@ -32,7 +32,7 @@ async with Client(
         client_metadata_url="https://myapp.example.com/oauth/client.json",
     ),
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 When the server supports CIMD, the client uses your metadata URL as its `client_id` instead of performing Dynamic Client Registration. The server fetches your document, validates it, and proceeds with the standard OAuth authorization flow.

docs/clients/auth/oauth.mdx

@@ -29,7 +29,7 @@ from fastmcp import Client
 
 # Uses default OAuth settings
 async with Client("https://your-server.fastmcp.app/mcp", auth="oauth") as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 
@@ -44,7 +44,7 @@ from fastmcp.client.auth import OAuth
 oauth = OAuth(scopes=["user"])
 
 async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 <Note>
@@ -125,7 +125,7 @@ encrypted_storage = FernetEncryptionWrapper(
 oauth = OAuth(token_storage=encrypted_storage)
 
 async with Client("https://your-server.fastmcp.app/mcp", auth=oauth) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 You can use any `AsyncKeyValue`-compatible backend from the [key-value library](https://github.com/strawgate/py-key-value) including Redis, DynamoDB, and more. Wrap your storage in `FernetEncryptionWrapper` for encryption.
@@ -150,7 +150,7 @@ async with Client(
         client_metadata_url="https://myapp.example.com/oauth/client.json",
     ),
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 See the [CIMD Authentication](/clients/auth/cimd) page for complete documentation on creating, hosting, and validating CIMD documents.
@@ -172,7 +172,7 @@ async with Client(
         client_secret="my-client-secret",
     ),
 ) as client:
-    await client.ping()
+    await client.list_tools()
 ```
 
 Public clients that rely on PKCE for security can omit `client_secret`:

docs/clients/client.mdx

@@ -37,9 +37,6 @@ client = Client("my_mcp_server.py")
 
 async def main():
     async with client:
-        # Basic server interaction
-        await client.ping()
-
         # List available operations
         tools = await client.list_tools()
         resources = await client.list_resources()
@@ -171,21 +168,31 @@ async with client:
 
 MCP has two protocol eras: the original *legacy* era, which begins every connection with an `initialize` handshake, and the *modern* era (protocol version `2026-07-28` and later), which a client discovers by probing the server's `server/discover` endpoint. The `mode` parameter controls which era the client negotiates when it connects.
 
-By default, `mode="legacy"`. This runs the initialize handshake and behaves identically to earlier FastMCP versions, so existing code connecting to any server keeps working unchanged.
+By default, `mode="auto"`. The client probes `server/discover` and adopts the modern protocol when the server responds; for any server that is not positive evidence of modern support, it falls back to the legacy handshake. This makes the default safe against a mixed fleet of legacy and modern servers.
 
 ```python
 from fastmcp import Client
 
-# Legacy handshake (the default)
-client = Client("https://example.com/mcp", mode="legacy")
+# Negotiate the newest era the server supports (the default)
+client = Client("https://example.com/mcp", mode="auto")
 ```
 
-Set `mode="auto"` to negotiate the newest era the server supports. The client probes `server/discover` and adopts the modern protocol when the server responds; for any server that is not positive evidence of modern support, it falls back to the legacy handshake. This makes `"auto"` safe to use against a mixed fleet of legacy and modern servers.
+Set `mode="legacy"` to force the initialize handshake. This behaves identically to earlier FastMCP versions and is the opt-out if a server misbehaves under discovery or you need the legacy `initialize` result object.
 
 ```python
-client = Client("https://example.com/mcp", mode="auto")
+client = Client("https://example.com/mcp", mode="legacy")
 ```
 
+Legacy mode is also what you need for the capabilities that depend on a live session between client and server. The handshake opens a persistent back-channel the server can push requests down, and the modern era removed it. Pin `mode="legacy"` when your code relies on any of these:
+
+- **[Sampling](/clients/sampling)** — server-initiated LLM completion requests
+- **[Roots](/clients/roots)** — server-initiated requests for the client's roots
+- **[Elicitation](/clients/elicitation)** — server-initiated requests for user input, which modern connections replace with [input-required rounds](/clients/elicitation#input-required-rounds)
+- **[Background tasks](/clients/tasks)** — submitting an operation with `task=True`
+- `client.ping()` and `transport.get_session_id()`
+
+A FastMCP server serves both eras, so a default client negotiates the modern one and these raise an era-specific error. Pinning the handshake restores them.
+
 You can also pin a specific modern protocol version to adopt it directly, without a discovery probe:
 
 ```python
@@ -201,7 +208,9 @@ async with Client("https://example.com/mcp", mode="auto") as client:
 ```
 
 <Note>
-`mode="auto"` is not the default yet — the conservative `"legacy"` remains the default to preserve byte-identical behavior against pre-2026 servers. Whether `"auto"` becomes the default is a future release decision.
+`mode="auto"` is the default as of FastMCP 4.0. Earlier versions defaulted to `"legacy"`. If a server behaves unexpectedly under discovery, or you depend on the legacy `initialize` result, pin the old behavior with `Client(..., mode="legacy")`.
+
+The SSE transport is legacy-only — it cannot carry the sessionless modern era — so a client connecting over SSE always negotiates the legacy handshake, even under `mode="auto"`. A multi-server config (`MCPConfigTransport` with more than one server) is likewise legacy-only, because it mounts each backend behind a legacy-era proxy; a single-server config mirrors its one backend transport's era.
 </Note>
 
 ## Response caching
@@ -260,6 +269,31 @@ client = Client("https://example.com/mcp", mode="auto", cache=config)
 
 The adapter serializes each result through a type-tagged envelope validated against an allowlist of cacheable result models, so a value naming an unknown type is treated as a cache miss rather than deserialized blindly. Each store instance owns its own collection namespace; `clear()` affects only that namespace, never another tenant's entries.
 
+## Client extensions
+
+<VersionBadge version="4.0.0" />
+
+Client extensions (SEP-2133) are the advanced mechanism a client uses to opt into vendor capabilities that live outside the core protocol. An extension is a `ClientExtension` instance that bundles three things: a capability *advertisement* the server can read, one or more *result claims* that let the client parse extra `tools/call` result shapes, and *notification bindings* that observe server notifications the core protocol doesn't define. Pass a sequence of them to `extensions=`.
+
+```python
+from fastmcp import Client
+from myproject.extensions import AppsExtension
+
+client = Client("https://example.com/mcp", extensions=[AppsExtension()])
+```
+
+Each extension's contributions are threaded into the underlying session. Notification bindings compose with FastMCP's own internal task-status binding rather than replacing it, so an extension that observes a custom notification and FastMCP's task tracking both work on the same connection. When a tool returns a shape an extension claims, `client.call_tool()` resolves it transparently through the owning claim's resolver and hands you back an ordinary result. Result claims and their advertisements are honored only on modern-era connections, so they are inert on a legacy handshake.
+
+For the rare case where you need to register additional result claims against an extension that is already advertised, pass them through `result_claims=`, keyed by the extension's identifier. Prefer declaring claims on the extension itself; this parameter merges extra claims with an extension's own.
+
+```python
+client = Client(
+    "https://example.com/mcp",
+    extensions=[AppsExtension()],
+    result_claims={"example.com/apps": [extra_claim]},
+)
+```
+
 ## Operations
 
 FastMCP clients interact with three types of server components.
@@ -301,6 +335,8 @@ See [Prompts](/clients/prompts) for detailed documentation including argument se
 
 The client supports callback handlers for advanced server interactions. These let you respond to server-initiated requests and receive notifications.
 
+Sampling, elicitation, and roots are all server-initiated, so they belong to the handshake era described under [protocol negotiation](#protocol-negotiation). A default client negotiates the newest era both peers share, where the server has no back-channel to push those requests down, so an example that exercises them pins `mode="legacy"`. Logging and progress arrive as notifications on the response stream and work in either era.
+
 ```python
 from fastmcp import Client
 from fastmcp.client.logging import LogMessage
@@ -317,6 +353,7 @@ async def sampling_handler(messages, params, context):
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     log_handler=log_handler,
     progress_handler=progress_handler,
     sampling_handler=sampling_handler,

docs/clients/elicitation.mdx

@@ -13,6 +13,12 @@ Use this when you need to respond to server requests for user input during tool
 
 Elicitation allows MCP servers to request structured input from users during operations. Instead of requiring all inputs upfront, servers can interactively ask for missing parameters, request clarification, or gather additional context.
 
+Two routes reach that outcome, and the protocol version the client negotiates decides which one applies. On older versions the server pushes an elicitation request down to the client, over the connection the `initialize` handshake opens; that is the flow the next few sections describe. On `2026-07-28` and later the server instead returns a description of what it needs, and the client answers with a fresh call — see [input-required rounds](#input-required-rounds). You write the same `elicitation_handler` either way — FastMCP routes it to whichever mechanism the connection supports.
+
+<Note>
+**This page shows the older protocol's elicitation flow.** On protocol version `2026-07-28` the server instead returns a description of what it needs and the client answers with a new call — see [input-required rounds](#input-required-rounds). The same `elicitation_handler` serves both. Clients default to `mode="auto"`, so the examples below pass `mode="legacy"` to exercise the server-initiated flow. See [protocol negotiation](/clients/client#protocol-negotiation).
+</Note>
+
 ## Handler Template
 
 ```python
@@ -54,6 +60,7 @@ async def elicitation_handler(
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     elicitation_handler=elicitation_handler,
 )
 ```
@@ -138,6 +145,7 @@ async def elicitation_handler(message, response_type, params, context):
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     elicitation_handler=elicitation_handler
 )
 ```
@@ -146,7 +154,7 @@ client = Client(
 
 <VersionBadge version="4.0.0" />
 
-On modern-era connections (protocol version `2026-07-28` and later), a server can ask for input before it returns a final result. Nothing is held open: the tool *returns* a description of what it needs, which completes that round as an ordinary response, and the client answers by issuing a **new** `call_tool`, `get_prompt`, or `read_resource` request carrying the answer. `fastmcp.Client` drives that loop for you — it fulfils each round's requests using the callbacks you already configured (your `elicitation_handler`, `sampling_handler`, and roots) and repeats until the call reaches a terminal result. No extra wiring is needed beyond the handlers described above.
+On protocol version `2026-07-28` and later, a server can ask for input before it returns a final result. Nothing is held open: the tool *returns* a description of what it needs, which completes that round as an ordinary response, and the client answers by issuing a **new** `call_tool`, `get_prompt`, or `read_resource` request carrying the answer. `fastmcp.Client` drives that loop for you — it fulfils each round's requests using the callbacks you already configured (your `elicitation_handler`, `sampling_handler`, and roots) and repeats until the call reaches a terminal result. No extra wiring is needed beyond the handlers described above.
 
 The `input_required_max_rounds` parameter caps how many rounds the client will answer before giving up, guarding against a server that never terminates. It defaults to `10`.
 

docs/clients/roots.mdx

@@ -13,6 +13,10 @@ Use this when you need to tell servers what local resources the client has acces
 
 Roots inform servers about resources the client can provide. Servers can use this information to adjust behavior or provide more relevant responses.
 
+<Note>
+**Roots require the older MCP protocol.** A server reads roots by sending a request down to the client, and protocol version `2026-07-28` removed the server's ability to do that. Clients default to `mode="auto"`, which negotiates the newest version both sides support, so the examples below pass `mode="legacy"`. See [protocol negotiation](/clients/client#protocol-negotiation).
+</Note>
+
 ## Static Roots
 
 Provide a list of roots when creating the client:
@@ -22,6 +26,7 @@ from fastmcp import Client
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     roots=["/path/to/root1", "/path/to/root2"]
 )
 ```
@@ -40,6 +45,7 @@ async def roots_callback(context: RequestContext) -> list[str]:
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     roots=roots_callback
 )
 ```

docs/clients/sampling.mdx

@@ -13,6 +13,10 @@ Use this when you need to respond to server requests for LLM completions.
 
 MCP servers can request LLM completions from clients during tool execution. This enables servers to delegate AI reasoning to the client, which controls which LLM is used and how requests are made.
 
+<Note>
+**Sampling requires the older MCP protocol.** A server requests sampling by sending a request down to the client, and protocol version `2026-07-28` removed the server's ability to do that. Clients default to `mode="auto"`, which negotiates the newest version both sides support, so every example on this page passes `mode="legacy"`. See [protocol negotiation](/clients/client#protocol-negotiation).
+</Note>
+
 ## Handler Template
 
 ```python
@@ -49,6 +53,7 @@ async def sampling_handler(
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=sampling_handler,
 )
 ```
@@ -109,6 +114,7 @@ from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=OpenAISamplingHandler(default_model="gpt-4o"),
 )
 ```
@@ -120,6 +126,7 @@ from openai import AsyncOpenAI
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=OpenAISamplingHandler(
         default_model="llama-3.1-70b",
         client=AsyncOpenAI(base_url="http://localhost:8000/v1"),
@@ -141,6 +148,7 @@ from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=AnthropicSamplingHandler(default_model="claude-sonnet-4-5"),
 )
 ```
@@ -159,6 +167,7 @@ from fastmcp.client.sampling.handlers.google_genai import GoogleGenaiSamplingHan
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=GoogleGenaiSamplingHandler(default_model="gemini-2.0-flash"),
 )
 ```
@@ -176,6 +185,7 @@ from fastmcp.types import SamplingCapability
 
 client = Client(
     "my_mcp_server.py",
+    mode="legacy",
     sampling_handler=basic_handler,
     sampling_capabilities=SamplingCapability(),  # No tool support
 )

docs/clients/tasks.mdx

@@ -14,14 +14,18 @@ Use this when you need to run long operations asynchronously while doing other w
 
 The MCP task protocol lets you request operations to run in the background. The call returns a Task object immediately, letting you track progress, cancel operations, or await results.
 
+<Note>
+**Background tasks require the older MCP protocol.** FastMCP submits a task over the session that the `initialize` handshake opens, and protocol version `2026-07-28` has no equivalent. Clients default to `mode="auto"`, which negotiates the newest version both sides support, so the examples on this page pass `mode="legacy"`. See [protocol negotiation](/clients/client#protocol-negotiation).
+</Note>
+
 ## Requesting Background Execution
 
 Pass `task=True` to run an operation as a background task:
 
 ```python
 from fastmcp import Client
 
-async with Client(server) as client:
+async with Client(server, mode="legacy") as client:
     # Start a background task
     task = await client.call_tool("slow_computation", {"duration": 10}, task=True)
 
@@ -154,7 +158,7 @@ import asyncio
 from fastmcp import Client
 
 async def main():
-    async with Client(server) as client:
+    async with Client(server, mode="legacy") as client:
         # Start background task
         task = await client.call_tool(
             "slow_computation",

docs/clients/transports.mdx

@@ -86,7 +86,7 @@ client = Client(transport)
 
 async def efficient_multiple_operations():
     async with client:
-        await client.ping()
+        await client.list_tools()
 
     async with client:  # Reuses the same subprocess
         await client.call_tool("process_data", {"file": "data.csv"})