feat(client): accept a known-legacy era verdict on ConnectOptions.prior

Hosts that already know a server's era from out-of-band metadata shouldn't
pay a server/discover probe round trip that fails against every legacy
server — and mode: 'legacy' pins the client to initialize forever. `prior`
now takes a discriminated PriorDiscovery verdict alongside the bare
DiscoverResult: the modern arm wraps a DiscoverResult (zero round trips, as
before), the legacy arm skips the probe and runs the plain legacy initialize
handshake. Freshness is the supplying host's responsibility — a stale legacy
verdict succeeds silently against an upgraded server, so hosts must date
cached legacy verdicts in their own storage and stop supplying them past
their policy horizon; with no prior, the configured versionNegotiation mode
decides (an 'auto' client re-probes). Persisted-blob plumbing fails typed:
null priors are treated as absent, and corrupt or unrecognized shapes —
including a bare result whose supportedVersions is not an array — reject
with SdkError(EraNegotiationFailed) before anything reaches the wire.

Author: felixweinberger

.changeset/prior-legacy-verdict.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+`ConnectOptions.prior` now accepts a cached era verdict (new exported type `PriorDiscovery`), not only a positive `DiscoverResult`. Hosts that already know a server's era from out-of-band metadata can pass `{ kind: 'legacy' }` to skip the `server/discover` probe and run the plain `initialize` handshake directly — without pinning the client to `mode: 'legacy'`: stop supplying the verdict and `connect()` falls back to the configured `versionNegotiation` mode (under `'auto'`, it re-probes and rediscovers an upgraded server). Freshness is the supplying host's responsibility — a stale legacy verdict succeeds silently against an upgraded server, so hosts must date cached legacy verdicts in their own storage and stop supplying them past their policy horizon. The positive verdict has a symmetric wrapped form, `{ kind: 'modern', discover }`; the bare `DiscoverResult` form stays accepted. Persisted-blob plumbing is hardened: `prior: null` is treated as absent, and an unrecognized shape rejects with a typed `SdkError(EraNegotiationFailed)` instead of a `TypeError`. Previously, a host fronting a known-legacy server had no way to avoid a probe round trip that fails against every legacy server — `connect({ prior })` threw `EraNegotiationFailed` on anything without a modern overlap.

docs/advanced/gateway.md

@@ -26,7 +26,7 @@ await worker.connect(new StreamableHTTPClientTransport(url), { prior: JSON.parse
 
 `worker` is connected: `callTool` works immediately, and the server has not heard from it yet.
 
-`connect({ prior })` is 2026-07-28+ only — see [Protocol versions](../protocol-versions.md).
+Adopting a `DiscoverResult` is 2026-07-28+ only — see [Protocol versions](../protocol-versions.md). For a server known to be legacy, `prior` also takes a negative verdict — see [Skip the probe for a known-legacy server](#skip-the-probe-for-a-known-legacy-server).
 
 ## Probe once at bootstrap
 
@@ -150,6 +150,93 @@ re-probed: 2026-07-28
 
 Replace the persisted blob with the fresh `getDiscoverResult()` and the rest of the fleet recovers on its next read.
 
+## Skip the probe for a known-legacy server
+
+When out-of-band metadata already says the server is pre-2026 — a registry entry, an earlier connection's outcome — an `'auto'`-mode probe is a round trip that fails on every single connect. Supply the negative verdict instead: `prior` also takes a `PriorDiscovery`, and its `{ kind: 'legacy' }` arm skips the probe and goes straight to the `initialize` handshake.
+
+```ts source="../../examples/guides/advanced/gateway.examples.ts#prior_legacy"
+const pinnedLegacy = new Client({ name: 'worker-e', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
+await pinnedLegacy.connect(new StreamableHTTPClientTransport(url), {
+    prior: { kind: 'legacy' }
+});
+console.log(pinnedLegacy.getProtocolEra());
+```
+
+```
+legacy
+```
+
+Freshness is your responsibility: the SDK adopts whatever verdict you hand it. A stale modern verdict fails loudly at the first request, but a stale legacy verdict succeeds silently forever — an upgraded server still answers `initialize`, so nothing ever corrects it. Date cached legacy verdicts in your own storage and stop supplying them past your policy horizon; with no `prior`, the configured mode decides again (under `mode: 'auto'` the connect re-probes, so the upgrade is discovered).
+
+The positive verdict has a wrapped form too: `{ kind: 'modern', discover }` adopts `discover` exactly like the bare `DiscoverResult`.
+
+## Caching discovery verdicts
+
+The pieces above compose into the full host-side loop: probe once, cache the verdict under your own timestamp, and gate every later connect on a freshness check you control.
+
+The first connect under `mode: 'auto'` pays one probe. Afterwards the outcome is readable on the client: `getDiscoverResult()` returns the `DiscoverResult` on a modern server, and on a connected client its absence means the era is legacy. Store that verdict together with when you stored it — the `Map` below keeps `storedAt` explicitly; in a real deployment the store does the dating for you (a Redis key TTL, where an expired read simply comes back empty, or a database row's `created_at` column).
+
+Before each connect, supply the cached verdict only while your own policy says it is fresh — a fixed horizon here, any predicate in practice. Supplying `undefined` under `mode: 'auto'` *is* the re-probe, and the fresh outcome re-populates the cache. The timestamp matters most for the legacy branch: a stale legacy verdict succeeds silently forever (an upgraded server still answers `initialize`), so only the timestamp ever retires it; a stale modern verdict fails loudly at the first request.
+
+```ts source="../../examples/guides/advanced/gateway.examples.ts#prior_cache"
+import type { PriorDiscovery } from '@modelcontextprotocol/client';
+
+// Host-side verdict cache. A real deployment keeps this in Redis (a key TTL
+// does the dating: an expired read is no prior) or a database row with a
+// created_at column; the Map stores the timestamp explicitly.
+const verdicts = new Map<string, { verdict: PriorDiscovery; storedAt: number }>();
+const HORIZON_MS = 24 * 60 * 60 * 1000; // fixed-horizon freshness policy
+const fresh = (entry: { storedAt: number }): boolean => Date.now() - entry.storedAt < HORIZON_MS;
+
+// Count server/discover probes at the fetch layer (the wire trace).
+let probes = 0;
+const tracingFetch: typeof fetch = async (input, init) => {
+    if (typeof init?.body === 'string' && init.body.includes('"server/discover"')) probes++;
+    return fetch(input, init);
+};
+
+async function connectCached(key: string): Promise<Client> {
+    const entry = verdicts.get(key);
+    // An entry past the horizon is not supplied — under mode: 'auto' that IS
+    // the re-probe, and the fresh outcome below re-populates the cache.
+    const prior = entry && fresh(entry) ? entry.verdict : undefined;
+
+    const client = new Client({ name: 'cached-worker', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
+    await client.connect(new StreamableHTTPClientTransport(url, { fetch: tracingFetch }), { prior });
+
+    if (prior === undefined) {
+        // Fresh outcome: getDiscoverResult() is the DiscoverResult on a modern
+        // server; its absence on a connected client means the era is legacy.
+        const discover = client.getDiscoverResult();
+        // Date the entry with the host's own clock — only this timestamp ever
+        // retires a legacy verdict (a stale one succeeds silently forever).
+        verdicts.set(key, {
+            verdict: discover ? { kind: 'modern', discover } : { kind: 'legacy' },
+            storedAt: Date.now()
+        });
+    }
+    return client;
+}
+
+const first = await connectCached('gateway-target'); // no entry: probes
+console.log('probes after first connect:', probes);
+
+const second = await connectCached('gateway-target'); // fresh entry: verdict supplied, no probe
+console.log('probes after second connect:', probes);
+
+verdicts.get('gateway-target')!.storedAt -= HORIZON_MS + 1; // the horizon passes
+const third = await connectCached('gateway-target'); // stale: dropped, re-probed, re-cached
+console.log('probes after the horizon passes:', probes);
+```
+
+```
+probes after first connect: 1
+probes after second connect: 1
+probes after the horizon passes: 2
+```
+
+The wire trace shows the shape of the loop: one probe to fill the cache, none while the verdict is fresh, one more when the horizon forces rediscovery.
+
 ## Recap
 
 - `connect(transport, { prior })` adopts a persisted `DiscoverResult` with zero round trips.
@@ -158,3 +245,4 @@ Replace the persisted blob with the fresh `getDiscoverResult()` and the rest of
 - Reuse a `DiscoverResult` only across clients that present the same authorization context.
 - Prior-connected clients are request-only; call `listen()` on the one that needs notifications.
 - An incompatible `prior` rejects with `SdkError(EraNegotiationFailed)`; fall back to a fresh probe and re-persist.
+- A known-legacy server takes `prior: { kind: 'legacy' }` — no probe, straight to `initialize`. Stale legacy verdicts fail silently (an upgraded server still answers `initialize`), so date them in your own storage and stop supplying them past your policy horizon.

docs/clients/caching.md

@@ -94,6 +94,10 @@ Fresh or not, the cache also evicts itself when the server signals a change: a `
 Cache hints are a 2026-07-28 surface — see [Protocol versions](../protocol-versions.md). Against a 2025-era server, `defaultCacheTtlMs` is the only lever.
 :::
 
+## Two caches, two owners
+
+The response cache on this page is the only cache the SDK manages: the server declares each entry's lifetime (`ttlMs`) and the SDK enforces it. A host that also caches **discovery verdicts** — the connect-time era outcome supplied as `ConnectOptions.prior` — owns that policy itself: the SDK never expires a supplied verdict. See [Protocol versions](../protocol-versions.md#skip-the-probe-with-a-cached-verdict) for the verdict shapes and [Caching discovery verdicts](../advanced/gateway.md#caching-discovery-verdicts) for the full host-side loop.
+
 ## Recap
 
 - Caching is one feature with two halves: the server attaches `ttlMs` / `cacheScope`, the client honours them — by default neither half does anything alone.

docs/clients/connect.md

@@ -85,6 +85,19 @@ Call list-trips before book-trip. Dates are ISO 8601.
 
 The capability object gates every verb on [the next page](./calling.md): only ask for what the server advertised. `getInstructions()` is the server's usage guide for the model — put it in the system prompt.
 
+A fourth accessor, `getDiscoverResult()`, tells the eras apart at connect time. Present, it is the modern-era `DiscoverResult` — persistable with `JSON.stringify` and usable on a later connect as `ConnectOptions.prior` to skip the probe. Absent on a connected client, the era is legacy. This page's client used the default legacy handshake:
+
+```ts source="../../examples/guides/clients/connect.examples.ts#connect_discoverResult"
+// The default mode ran the legacy initialize handshake — no DiscoverResult.
+console.log(client.getDiscoverResult());
+```
+
+```
+undefined
+```
+
+Under `versionNegotiation: { mode: 'auto' }` against a 2026-era server it returns the advertisement — see [Protocol versions](../protocol-versions.md#skip-the-probe-with-a-cached-verdict) for the cached-verdict shapes and [Caching discovery verdicts](../advanced/gateway.md#caching-discovery-verdicts) for the full host-side loop.
+
 ## Disconnect cleanly
 
 Over Streamable HTTP, terminate the server-side session, then close the client.
@@ -101,6 +114,6 @@ await client.close();
 - `new Client({ name, version })`, a transport, and `connect()` are the whole setup; `connect()` runs the `initialize` handshake.
 - `StreamableHTTPClientTransport` connects to remote servers; `StdioClientTransport`, from `@modelcontextprotocol/client/stdio`, spawns local ones; `SSEClientTransport` is the fallback for SSE-only servers.
 - `InMemoryTransport.createLinkedPair()` links a client and a server in one process.
-- After `connect()`, `getServerVersion()`, `getServerCapabilities()`, and `getInstructions()` return what the server declared.
+- After `connect()`, `getServerVersion()`, `getServerCapabilities()`, and `getInstructions()` return what the server declared; `getDiscoverResult()` tells the eras apart (present = modern, absent = legacy).
 - `close()` tears down the transport and rejects in-flight requests.
 - Protocol-revision differences live on the protocol versions page, not here.

docs/migration/support-2026-07-28.md

@@ -109,7 +109,12 @@ The probe request itself already carries the per-request `_meta` envelope
 the envelope to every outgoing request and notification. Tooling that classifies
 traffic must not treat "saw an envelope" as "modern era negotiated": the legacy-fallback
 path also begins with one enveloped probe. A gateway/worker fleet can skip the
-probe entirely with `client.connect(transport, { prior: persistedDiscoverResult })`.
+probe entirely with `client.connect(transport, { prior: persistedDiscoverResult })` —
+or, for a server known out-of-band to be legacy, with
+`{ prior: { kind: 'legacy' } }`, which goes straight to `initialize`. Freshness
+of a cached legacy verdict is the host's responsibility (a stale one succeeds
+silently against an upgraded server); stop supplying it and the configured
+mode decides again (an `'auto'` client re-probes).
 
 ### Server over HTTP: `createMcpHandler`
 

docs/migration/upgrade-to-v2.md

@@ -1758,8 +1758,14 @@ from a subpath means the corresponding peer dep must be in your `package.json`.
 ### `Client.connect(transport, { prior })` — zero-round-trip connect
 
 Probe once, persist `client.getDiscoverResult()` (`JSON.stringify`), and feed it to
-every worker as `client.connect(transport, { prior })` — 2026-07-28+ only. New exported
-type `ConnectOptions` (extends `RequestOptions` with `prior?: DiscoverResult`).
+every worker as `client.connect(transport, { prior })`. New exported types
+`ConnectOptions` (extends `RequestOptions` with `prior?: DiscoverResult | PriorDiscovery`)
+and `PriorDiscovery` — a cached era verdict: the modern arm wraps a `DiscoverResult`
+(zero round trips), the legacy arm (`{ kind: 'legacy' }`) skips the probe and runs the
+plain `initialize` handshake for servers known to be pre-2026. Freshness is the
+supplying host's responsibility — date cached legacy verdicts in your own storage and
+stop supplying them past your policy horizon (a stale one succeeds silently against an
+upgraded server).
 
 ### Serving the 2026-07-28 revision
 

docs/protocol-versions.md

@@ -74,6 +74,12 @@ The rejection is a typed, local `SdkError` — nothing reaches the server beyond
 ERA_NEGOTIATION_FAILED: Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode)
 ```
 
+## Skip the probe with a cached verdict
+
+`mode: 'auto'` pays the probe on every fresh connect. A host that already knows the server's era — from a registry entry, or an earlier connection's outcome — skips it by supplying `ConnectOptions.prior`: a bare `DiscoverResult` (or `{ kind: 'modern', discover }`) is adopted with zero round trips, and `{ kind: 'legacy' }` goes straight to the `initialize` handshake. Both wrapped forms are the exported `PriorDiscovery` type.
+
+Freshness is the host's job, not the SDK's: a stale modern verdict fails loudly at the first request, but a stale legacy verdict succeeds silently against an upgraded server — so date cached legacy verdicts in your own storage and stop supplying them past your policy horizon. [Caching discovery verdicts](./advanced/gateway.md#caching-discovery-verdicts) shows the full loop, including the re-probe that re-populates the cache.
+
 ## Understand the probe
 
 `probe` bounds the `server/discover` round trip that `'auto'` and a pin run before anything else.

examples/gateway/README.md

@@ -47,4 +47,4 @@ The server exposes a `request_count` tool returning how many MCP requests reache
 Only reuse a persisted `DiscoverResult` across workers that present the **same authorization context** as the bootstrap client (key the blob on a credential hash). Adopting a wider `prior` does not grant access — the server authorizes every request — but it can mislead
 client-side capability gating.
 
-`connect({ prior })` is **modern-only**: no mutual 2026-07-28+ revision → `SdkError(EraNegotiationFailed)`. Use `versionNegotiation: { mode: 'auto' }` for legacy-era fallback.
+Adopting a `DiscoverResult` via `connect({ prior })` is **modern-only**: no mutual 2026-07-28+ revision → `SdkError(EraNegotiationFailed)`. For a server known to be legacy, pass the negative verdict instead — `prior: { kind: 'legacy' }` skips the probe and goes straight to `initialize`. Freshness is the host's responsibility: date cached legacy verdicts in your own storage and stop supplying them past your policy horizon (a stale one succeeds silently against an upgraded server; with no `prior`, a `mode: 'auto'` client re-probes).