[SEP-2575] client: connect() auto-probe activates _isStateless

connect() now probes server/discover via transport.sendAndReceive
before the legacy initialize handshake. On success the client enters
stateless mode (server identity/capabilities from DiscoverResult,
initialize skipped). On MethodNotFound / HTTP 4xx / parse failure it
falls through to the legacy initialize (extracted verbatim into
_initialize()).

_setupListChanged() routes options.listChanged to _listChangedLoop
(subscriptions/listen) when stateless, else to the existing
notification-handler path.

Existing tests that exercise pre-2026 connection-model behavior now
need LegacyTestClient (C14).

Author: felixweinberger

packages/client/src/client/client.ts

@@ -92,15 +92,24 @@ type ListChangedKinds = Record<
 
 /**
  * Returns true for `server/discover` failures that should fall through to the
- * legacy `initialize` handshake (server doesn't speak 2026-06).
+ * legacy `initialize` handshake (server doesn't speak 2026-06). Auth failures
+ * (401/403) are NOT fallbackable: a server that requires auth for `discover`
+ * will require it for `initialize` too, so falling back would only mask the
+ * real error and skip the transport's re-auth path.
  */
 function isFallbackable(e: unknown): boolean {
     if (e instanceof ProtocolError) {
         return e.code === ProtocolErrorCode.MethodNotFound;
     }
     if (e instanceof SdkError) {
         const status = (e.data as { status?: number } | undefined)?.status;
-        return e.code === SdkErrorCode.InvalidResult || (typeof status === 'number' && status >= 400 && status < 500);
+        // Any 4xx except 401/403 (auth) means the server doesn't speak 2026-06.
+        // 400 in particular is what a pre-2026 StreamableHTTP server returns for
+        // a non-initialize POST without an mcp-session-id.
+        return (
+            e.code === SdkErrorCode.InvalidResult ||
+            (typeof status === 'number' && status >= 400 && status < 500 && status !== 401 && status !== 403)
+        );
     }
     return false;
 }
@@ -475,33 +484,53 @@ export class Client extends Protocol<ClientContext> {
      * Probes `server/discover` via `transport.sendAndReceive`. On success,
      * marks this client stateless and populates server identity/capabilities
      * from the result. On {@linkcode isFallbackable} failure, leaves state
-     * untouched (the legacy `initialize` already populated it via `connect()`).
-     *
-     * Called from {@linkcode connect} (in C13).
+     * untouched so {@linkcode connect} falls through to the legacy
+     * `initialize` handshake.
      */
-    private async _negotiate(transport: Transport): Promise<void> {
+    private async _negotiate(transport: Transport, options?: RequestOptions): Promise<void> {
         const sar = transport.sendAndReceive?.bind(transport);
         const preferred = this._supportedProtocolVersions.find(v => isStatelessProtocolVersion(v));
         if (!sar || !preferred) return;
 
         transport.setProtocolVersion?.(preferred);
+        const signal =
+            options?.timeout === undefined
+                ? (options?.signal ?? AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MSEC))
+                : options?.signal
+                  ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeout)])
+                  : AbortSignal.timeout(options.timeout);
         try {
-            const raw = await this._collect(sar({ method: 'server/discover', params: { _meta: this._buildMeta(preferred) } }));
-            const dr = DiscoverResultSchema.parse(raw);
-            const negotiated = dr.supportedVersions.find(v => this._supportedProtocolVersions.includes(v));
-            if (negotiated && isStatelessProtocolVersion(negotiated)) {
-                this._serverCapabilities = dr.capabilities;
-                this._serverVersion = dr.serverInfo;
-                this._instructions = dr.instructions;
-                this._negotiatedProtocolVersion = negotiated;
-                this._isStateless = true;
-                transport.setProtocolVersion?.(negotiated);
-                return;
+            const raw = await this._collect(sar({ method: 'server/discover', params: { _meta: this._buildMeta(preferred) } }, { signal }), {
+                signal
+            });
+            const drParsed = DiscoverResultSchema.safeParse(raw);
+            if (drParsed.success) {
+                const dr = drParsed.data;
+                // The probe only counts as success when there is a mutual
+                // *stateless* version; otherwise fall through to legacy initialize.
+                const negotiated = dr.supportedVersions.find(
+                    v => isStatelessProtocolVersion(v) && this._supportedProtocolVersions.includes(v)
+                );
+                if (negotiated) {
+                    this._serverCapabilities = dr.capabilities;
+                    this._serverVersion = dr.serverInfo;
+                    this._instructions = dr.instructions;
+                    this._negotiatedProtocolVersion = negotiated;
+                    this._isStateless = true;
+                    transport.setProtocolVersion?.(negotiated);
+                    return;
+                }
             }
         } catch (error) {
-            if (!isFallbackable(error)) throw error;
+            if (!isFallbackable(error)) {
+                // Reset the version we set before re-throwing so the
+                // transport is not left advertising a stateless version.
+                transport.setProtocolVersion?.(this._negotiatedProtocolVersion ?? '');
+                throw error;
+            }
         }
-        // Reset header to whatever legacy initialize set.
+        // Fallback path: reset the version header so the subsequent legacy
+        // `_initialize()` (run by `connect()`) can set it.
         transport.setProtocolVersion?.(this._negotiatedProtocolVersion ?? '');
     }
 
@@ -609,10 +638,11 @@ export class Client extends Protocol<ClientContext> {
     // ═══════════════════════════════════════════════════════════════════════
     // session-dependent (existing — bodies unchanged unless noted dual-mode above)
     //
-    // `connect()` performs the legacy `initialize` handshake. The 2026-06
-    // discover auto-probe is wired in C13. `ping`, `subscribeResource`,
-    // `unsubscribeResource`, and `_setupListChangedHandler*` use the
-    // persistent connection; `_listChangedLoop` (above) is the 2026 path.
+    // `_initialize()` (extracted verbatim from the previous inline `connect()`
+    // body) performs the legacy `initialize` handshake. `ping`,
+    // `subscribeResource`, `unsubscribeResource`, and
+    // `_setupListChangedHandler*` use the persistent connection;
+    // `_listChangedLoop` (above) is the 2026 path.
     // ═══════════════════════════════════════════════════════════════════════
 
     /**
@@ -787,46 +817,13 @@ export class Client extends Protocol<ClientContext> {
             return;
         }
         try {
-            const result = await this._requestWithSchema(
-                {
-                    method: 'initialize',
-                    params: {
-                        protocolVersion: this._supportedProtocolVersions[0] ?? LATEST_PROTOCOL_VERSION,
-                        capabilities: this._capabilities,
-                        clientInfo: this._clientInfo
-                    }
-                },
-                InitializeResultSchema,
-                options
-            );
-
-            if (result === undefined) {
-                throw new Error(`Server sent invalid initialize result: ${result}`);
-            }
-
-            if (!this._supportedProtocolVersions.includes(result.protocolVersion)) {
-                throw new Error(`Server's protocol version is not supported: ${result.protocolVersion}`);
-            }
-
-            this._serverCapabilities = result.capabilities;
-            this._serverVersion = result.serverInfo;
-            this._negotiatedProtocolVersion = result.protocolVersion;
-            // HTTP transports must set the protocol version in each header after initialization.
-            if (transport.setProtocolVersion) {
-                transport.setProtocolVersion(result.protocolVersion);
-            }
-
-            this._instructions = result.instructions;
-
-            await this.notification({
-                method: 'notifications/initialized'
-            });
-
-            // Set up list changed handlers now that we know server capabilities
-            if (this._pendingListChangedConfig) {
-                this._setupListChangedHandlers(this._pendingListChangedConfig);
-                this._pendingListChangedConfig = undefined;
+            // Probe `server/discover` (SEP-2575). If it succeeds, this client is
+            // stateless and the legacy `initialize` is skipped.
+            await this._negotiate(transport, options);
+            if (!this._isStateless) {
+                await this._initialize(transport, options);
             }
+            this._setupListChanged();
         } catch (error) {
             // Disconnect if initialization fails.
             void this.close();

packages/client/src/client/streamableHttp.ts

@@ -195,32 +195,66 @@ export class StreamableHTTPClientTransport implements Transport {
      * `subscriptions/listen` the indefinite stream). Backed directly by
      * `fetch`; does not go through `Protocol.request()`/`_responseHandlers`.
      *
-     * Used by `Client` for 2026-06 stateless calls. Auth handling matches
-     * {@linkcode send} (token attached via `_commonHeaders`); 401/403 retry
-     * is left to the caller (`Client` falls back to legacy `request()` on
-     * auth failure).
+     * Used by `Client` for 2026-06 stateless calls. Auth handling mirrors
+     * {@linkcode send}: token attached via `_commonHeaders`, one 401 retry via
+     * `authProvider.onUnauthorized`, and one 403 `insufficient_scope` upscoping
+     * retry for OAuth providers. The ladder is duplicated here (not shared with
+     * `send()`) so `send()` stays byte-identical to the pre-2026 code path.
      */
     async *sendAndReceive(
         request: Omit<JSONRPCRequest, 'jsonrpc' | 'id'>,
         opts?: { signal?: AbortSignal }
     ): AsyncGenerator<JSONRPCMessage, void, void> {
-        const headers = await this._commonHeaders();
-        headers.set('content-type', 'application/json');
-        headers.set('accept', 'application/json, text/event-stream');
         const body = JSON.stringify({ jsonrpc: '2.0', id: 0, ...request });
         const signal =
             opts?.signal && this._abortController
                 ? AbortSignal.any([opts.signal, this._abortController.signal])
                 : (opts?.signal ?? this._abortController?.signal);
-        const response = await (this._fetch ?? fetch)(this._url, {
-            ...this._requestInit,
-            method: 'POST',
-            headers,
-            body,
-            signal
-        });
+        const post = async (): Promise<Response> => {
+            const headers = await this._commonHeaders();
+            headers.set('content-type', 'application/json');
+            headers.set('accept', 'application/json, text/event-stream');
+            return (this._fetch ?? fetch)(this._url, { ...this._requestInit, method: 'POST', headers, body, signal });
+        };
+        let response = await post();
+        if (response.status === 401 && this._authProvider) {
+            if (response.headers.has('www-authenticate')) {
+                const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
+                this._resourceMetadataUrl = resourceMetadataUrl;
+                this._scope = scope;
+            }
+            if (this._authProvider.onUnauthorized) {
+                await this._authProvider.onUnauthorized({ response, serverUrl: this._url, fetchFn: this._fetchWithInit });
+                await response.text?.().catch(() => {});
+                response = await post();
+            }
+        }
+        if (response.status === 403 && this._oauthProvider) {
+            const { resourceMetadataUrl, scope, error } = extractWWWAuthenticateParams(response);
+            if (error === 'insufficient_scope') {
+                const wwwAuthHeader = response.headers.get('WWW-Authenticate');
+                if (this._lastUpscopingHeader !== wwwAuthHeader) {
+                    if (scope) this._scope = scope;
+                    if (resourceMetadataUrl) this._resourceMetadataUrl = resourceMetadataUrl;
+                    this._lastUpscopingHeader = wwwAuthHeader ?? undefined;
+                    const result = await auth(this._oauthProvider, {
+                        serverUrl: this._url,
+                        resourceMetadataUrl: this._resourceMetadataUrl,
+                        scope: this._scope,
+                        fetchFn: this._fetchWithInit
+                    });
+                    if (result === 'AUTHORIZED') {
+                        await response.text?.().catch(() => {});
+                        response = await post();
+                    }
+                }
+            }
+        }
         if (!response.ok) {
             const text = await response.text().catch(() => '');
+            if (response.status === 401) {
+                throw new SdkError(SdkErrorCode.ClientHttpAuthentication, text || 'Unauthorized', { status: 401 });
+            }
             throw new SdkError(SdkErrorCode.SendFailed, `HTTP ${response.status}: ${text || response.statusText}`, {
                 status: response.status
             });

packages/client/test/client/clientSend.test.ts

@@ -172,3 +172,86 @@ describe('Client.subscribe', () => {
         expect(seen).toEqual(['notifications/subscriptions/acknowledged', 'notifications/tools/list_changed']);
     });
 });
+
+describe('Client.connect auto-probe (SEP-2575)', () => {
+    function discoverable(handler: (req: JSONRPCRequest) => AsyncIterable<JSONRPCMessage>): Transport {
+        const t = mockTransport(handler);
+        // Route legacy `initialize` (sent via Protocol.request → transport.send)
+        // back through onmessage so the fallback path can complete in-process.
+        t.send = async m => {
+            if ('method' in m && m.method === 'initialize') {
+                queueMicrotask(() =>
+                    t.onmessage?.({
+                        jsonrpc: JSONRPC_VERSION,
+                        id: (m as JSONRPCRequest).id,
+                        result: { protocolVersion: '2025-11-25', capabilities: {}, serverInfo: { name: 's', version: '1' } }
+                    })
+                );
+            } else if ('method' in m && m.method === 'notifications/initialized') {
+                // ignore
+            }
+        };
+        return t;
+    }
+
+    it('discover success → stateless mode, skips initialize', async () => {
+        const seen: string[] = [];
+        const t = discoverable(req => {
+            seen.push(req.method);
+            return once({
+                jsonrpc: JSONRPC_VERSION,
+                id: req.id,
+                result: {
+                    supportedVersions: [DRAFT_PROTOCOL_VERSION],
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 's', version: '2' }
+                }
+            });
+        });
+        const c = new Client({ name: 'c', version: '1' });
+        await c.connect(t);
+        expect(seen).toEqual(['server/discover']);
+        expect((c as unknown as { _isStateless: boolean })._isStateless).toBe(true);
+        expect(c.getServerCapabilities()).toEqual({ tools: {} });
+        expect(c.getServerVersion()).toEqual({ name: 's', version: '2' });
+    });
+
+    it('discover MethodNotFound → falls back to legacy initialize', async () => {
+        const seen: string[] = [];
+        const t = discoverable(req => {
+            seen.push(req.method);
+            return once({ jsonrpc: JSONRPC_VERSION, id: req.id, error: { code: -32_601, message: 'unknown method' } });
+        });
+        const c = new Client({ name: 'c', version: '1' });
+        await c.connect(t);
+        expect(seen).toEqual(['server/discover']);
+        expect((c as unknown as { _isStateless: boolean })._isStateless).toBe(false);
+        expect(c.getServerVersion()).toEqual({ name: 's', version: '1' });
+    });
+
+    it('no sendAndReceive → goes straight to legacy initialize', async () => {
+        const t: Transport = {
+            start: async () => {},
+            close: async () => {},
+            send: async m => {
+                if ('method' in m && m.method === 'initialize') {
+                    queueMicrotask(() =>
+                        t.onmessage?.({
+                            jsonrpc: JSONRPC_VERSION,
+                            id: (m as JSONRPCRequest).id,
+                            result: {
+                                protocolVersion: '2025-11-25',
+                                capabilities: {},
+                                serverInfo: { name: 's', version: '1' }
+                            }
+                        })
+                    );
+                }
+            }
+        };
+        const c = new Client({ name: 'c', version: '1' });
+        await c.connect(t);
+        expect((c as unknown as { _isStateless: boolean })._isStateless).toBe(false);
+        expect(c.getServerVersion()?.name).toBe('s');
+    });
+});