chore: fast-follow nits — SEP-2243 Number() coercion, connect({prior}) docs, icons example (#2364)

Author: felixweinberger

docs/client.md

@@ -121,6 +121,26 @@ Once a modern era is negotiated, the client automatically attaches the per-reque
 already-constructed instance via {@linkcode @modelcontextprotocol/client!client/client.Client#setVersionNegotiation | client.setVersionNegotiation()}. See the [2026-07-28 support guide](./migration/support-2026-07-28.md#serving-the-2026-07-28-revision) for the full failure semantics,
 probe policy, and the `'auto'`-mode compatibility table.
 
+#### Skipping the probe: `connect({ prior })`
+
+A gateway, proxy, or worker fleet that already knows the server's `server/discover` advertisement can skip the probe entirely. Pass a previously-obtained {@linkcode @modelcontextprotocol/client!index.DiscoverResult | DiscoverResult} via
+{@linkcode @modelcontextprotocol/client!client/client.ConnectOptions | ConnectOptions.prior} and `connect()` adopts it directly with **zero round trips** — the 2026-07-28 protocol is stateless on HTTP, so once the advertisement is known there is nothing left to negotiate.
+
+```ts source="../examples/guides/clientGuide.examples.ts#Client_connect_prior"
+// Probe once (here via the 'auto'-mode connect), persist the result …
+const bootstrap = new Client({ name: 'gateway', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
+await bootstrap.connect(new StreamableHTTPClientTransport(url));
+const persisted = JSON.stringify(bootstrap.getDiscoverResult());
+
+// … then every worker connects with zero round trips.
+const worker = new Client({ name: 'worker', version: '1.0.0' });
+await worker.connect(new StreamableHTTPClientTransport(url), { prior: JSON.parse(persisted) });
+```
+
+{@linkcode @modelcontextprotocol/client!client/client.Client#getDiscoverResult | client.getDiscoverResult()} returns the value that the `'auto'`/pinned probe path, an explicit {@linkcode @modelcontextprotocol/client!client/client.Client#discover | client.discover()} call, or a
+prior `connect({ prior })` recorded; it round-trips through `JSON.stringify`/`JSON.parse`. `connect({ prior })` is **2026-07-28+ only** — it rejects with `SdkError(EraNegotiationFailed)` when the supplied result and the client share no modern revision. Only reuse a persisted
+`DiscoverResult` across clients that present the **same authorization context** as the one that obtained it. See the [`gateway/` example](../examples/gateway/README.md) for the full probe-once / connect-many pattern with a server-side proof.
+
 ### Disconnecting
 
 Call {@linkcode @modelcontextprotocol/client!client/client.Client#close | await client.close() } to disconnect. Pending requests are rejected with a {@linkcode @modelcontextprotocol/client!index.SdkErrorCode.ConnectionClosed | CONNECTION_CLOSED} error.

examples/guides/clientGuide.examples.ts

@@ -101,6 +101,20 @@ async function Client_versionNegotiation(transport: StreamableHTTPClientTranspor
     //#endregion Client_versionNegotiation
 }
 
+/** Example: zero-round-trip connect from a persisted DiscoverResult. */
+async function Client_connect_prior(url: URL) {
+    //#region Client_connect_prior
+    // Probe once (here via the 'auto'-mode connect), persist the result …
+    const bootstrap = new Client({ name: 'gateway', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
+    await bootstrap.connect(new StreamableHTTPClientTransport(url));
+    const persisted = JSON.stringify(bootstrap.getDiscoverResult());
+
+    // … then every worker connects with zero round trips.
+    const worker = new Client({ name: 'worker', version: '1.0.0' });
+    await worker.connect(new StreamableHTTPClientTransport(url), { prior: JSON.parse(persisted) });
+    //#endregion Client_connect_prior
+}
+
 // ---------------------------------------------------------------------------
 // Disconnecting
 // ---------------------------------------------------------------------------

examples/tools/client.ts

@@ -17,6 +17,7 @@ runClient('tools', async () => {
     const required = (calc.inputSchema as { required?: string[] }).required ?? [];
     check.ok(required.includes('op') && required.includes('a') && required.includes('b'));
     check.ok(calc.outputSchema, 'calc should publish an outputSchema');
+    check.equal(calc.icons?.[0]?.src, 'https://example.test/calc.svg', 'calc should advertise its icons over the wire');
 
     const result = await client.callTool({ name: 'calc', arguments: { op: 'add', a: 2, b: 3 } });
     check.equal((result.structuredContent as { result?: number } | undefined)?.result, 5);

examples/tools/server.ts

@@ -27,7 +27,10 @@ function buildServer(): McpServer {
                 b: z.number().describe('right operand')
             }),
             outputSchema: z.object({ op: z.string(), result: z.number() }),
-            annotations: { readOnlyHint: true, idempotentHint: true }
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            // Icons a client may render in its UI. `src` is required;
+            // `mimeType`, `sizes`, and `theme` are optional hints.
+            icons: [{ src: 'https://example.test/calc.svg', mimeType: 'image/svg+xml', sizes: ['any'] }]
         },
         async ({ op, a, b }) => {
             const result = op === 'add' ? a + b : op === 'sub' ? a - b : a * b;

packages/client/src/client/client.ts

@@ -2062,8 +2062,8 @@ export class Client extends Protocol<ClientContext> {
         } else if (evicted !== undefined) {
             for (const method of evicted) {
                 // `evict()` bumps the generation FIRST and unconditionally
-                // (the `_cacheListResult` race guard relies on the bump, not
-                // on the store's deletes completing), then drops only THIS
+                // (the `ClientResponseCache.write` race guard relies on the
+                // bump, not on the store's deletes completing), then drops only THIS
                 // server's two partition singletons — co-tenants on a shared
                 // store keep their entries. Store failures are reported via
                 // `onerror` inside `evict()` and the call resolves, so

packages/core/src/shared/mcpParamHeaders.ts

@@ -191,6 +191,10 @@ const BASE64_SENTINEL_SUFFIX = '?=';
 // RFC 4648 §4, padding required (the spec's encoding-examples table and the
 // conformance referee's invalid-padding cell both require canonical padding).
 const BASE64_CANONICAL = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+// Strict decimal — gates the numeric comparison in `validateMcpParamHeaders`
+// so `Number()` never sees the looser forms it would otherwise accept
+// (`'0x1a'`, `' 42 '`, `'1e3'`).
+const CANONICAL_DECIMAL = /^-?\d+(\.\d+)?$/;
 
 /**
  * Convert a primitive argument value to its string representation per the
@@ -369,17 +373,18 @@ export function validateMcpParamHeaders(
             );
         }
         // Integer/number-typed declarations compare numerically (the spec's
-        // SHOULD — `42.0` and `42` are equal), but only when both sides parse
-        // to finite numbers. A non-numeric primitive (e.g. `'abc'` where the
-        // schema declares `integer`) is a body-vs-schema fault that params
-        // validation owns; comparing `NaN === NaN` would wrongly report a
-        // header/body mismatch for an identical pair, so fall back to string
-        // comparison and let dispatch emit `-32602` instead.
-        const decodedNum = Number(decoded);
-        const bodyNum = Number(bodyString);
+        // SHOULD — `42.0` and `42` are equal). The strict-decimal gate is
+        // applied to the *header* side only (so `'0x1a'`, `' 42 '`, `'1e3'`
+        // etc. never coerce); the body side is gated on being an actual JS
+        // number — `String(0.0000001) === '1e-7'` would fail the regex even
+        // though the value is perfectly canonical. A non-numeric body
+        // primitive (e.g. `'abc'` where the schema declares `integer`) is a
+        // body-vs-schema fault that params validation owns; fall back to
+        // string comparison and let dispatch emit `-32602` instead so an
+        // identical non-numeric pair never reports a mismatch.
         const numericComparable =
-            (decl.type === 'integer' || decl.type === 'number') && Number.isFinite(decodedNum) && Number.isFinite(bodyNum);
-        const equal = numericComparable ? decodedNum === bodyNum : decoded === bodyString;
+            (decl.type === 'integer' || decl.type === 'number') && CANONICAL_DECIMAL.test(decoded) && typeof bodyRaw === 'number';
+        const equal = numericComparable ? Number(decoded) === bodyRaw : decoded === bodyString;
         if (!equal) {
             return paramHeaderMismatchRejection(
                 'param-header-mismatch',

packages/core/test/shared/mcpParamHeaders.test.ts

@@ -302,6 +302,30 @@ describe('validateMcpParamHeaders — server-behavior table', () => {
         expect(validateMcpParamHeaders(intDecl, { n: 42 }, new Headers({ [`${MCP_PARAM_HEADER_PREFIX}N`]: '42.0' }))).toBeUndefined();
     });
 
+    test('number-typed body values that String() in exponent form still compare numerically', () => {
+        const numDecl = [{ path: ['t'], headerName: 'T', type: 'number' }] as const;
+        // String(0.0000001) === '1e-7', which is not a canonical decimal — the
+        // body-side gate is `typeof bodyRaw === 'number'`, NOT the regex, so a
+        // numerically-equal canonical-decimal header is accepted.
+        expect(
+            validateMcpParamHeaders(numDecl, { t: 0.0000001 }, new Headers({ [`${MCP_PARAM_HEADER_PREFIX}T`]: '0.0000001' }))
+        ).toBeUndefined();
+        // And a numerically-different canonical decimal still rejects.
+        const r = validateMcpParamHeaders(numDecl, { t: 0.0000001 }, new Headers({ [`${MCP_PARAM_HEADER_PREFIX}T`]: '0.0000002' }));
+        expect(r).toMatchObject({ kind: 'reject', cell: 'param-header-mismatch' });
+    });
+
+    test('numeric comparison only engages for canonical decimals (no hex / exponent coercion)', () => {
+        const intDecl = [{ path: ['n'], headerName: 'N', type: 'integer' }] as const;
+        // Each of these would satisfy `Number(header) === 42` but is NOT the
+        // body's `'42'`; the strict-decimal gate keeps them on the
+        // string-comparison path so they reject as a mismatch.
+        for (const loose of ['0x2a', '4.2e1']) {
+            const r = validateMcpParamHeaders(intDecl, { n: 42 }, new Headers({ [`${MCP_PARAM_HEADER_PREFIX}N`]: loose }));
+            expect(r).toMatchObject({ kind: 'reject', cell: 'param-header-mismatch' });
+        }
+    });
+
     test('a non-numeric primitive in a number-declared param falls back to string comparison (no false NaN mismatch)', () => {
         const intDecl = [{ path: ['n'], headerName: 'N', type: 'integer' }] as const;
         // Identical header/body — must NOT report a header/body disagreement;