@mcp-ts/sdk 2.3.4 → 2.4.1

package/src/client/react/oauth-popup.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { parseOAuthState } from '../../shared/utils.js';
 
 export interface OAuthPopupConnectionLike {
   sessionId: string;
@@ -11,7 +12,7 @@ export interface OAuthPopupConnectionLike {
  *
  * These utilities sit on top of the core MCP auth primitives:
  * - `useMcp({ onRedirect })` to decide how auth navigation happens
- * - `finishAuth(sessionId, code)` to complete code exchange
+ * - `finishAuth(state, code)` to complete code exchange
  *
  * Consumers are free to:
  * - use these helpers as-is for a turnkey popup flow
@@ -60,6 +61,7 @@ function postPopupResult(
   popupWindow: WindowProxy | null,
   result: {
     sessionId?: string;
+    state?: string;
     success: boolean;
     error?: string;
   }
@@ -150,9 +152,9 @@ export function createOAuthPopupRedirectHandler(
  */
 export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
   connections: TConnection[],
-  finishAuth: (sessionId: string, code: string) => Promise<unknown>
+  finishAuth: (state: string, code: string) => Promise<unknown>
 ): void {
-  const pendingPopupsRef = useRef<Map<string, WindowProxy>>(new Map());
+  const pendingPopupsRef = useRef<Map<string, { popupWindow: WindowProxy | null; state: string }>>(new Map());
   const processingCodesRef = useRef<Set<string>>(new Set());
 
   useEffect(() => {
@@ -169,10 +171,16 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
       const popupWindow = event.source && 'postMessage' in event.source
         ? event.source as WindowProxy
         : null;
-      const targetSessionId = typeof event.data.sessionId === 'string' ? event.data.sessionId : '';
+      const rawState =
+        typeof event.data.state === 'string'
+          ? event.data.state
+          : typeof event.data.sessionId === 'string'
+            ? event.data.sessionId
+            : '';
+      const targetSessionId = rawState ? parseOAuthState(rawState)?.sessionId || rawState : '';
 
       if (popupWindow && targetSessionId) {
-        pendingPopupsRef.current.set(targetSessionId, popupWindow);
+        pendingPopupsRef.current.set(targetSessionId, { popupWindow, state: rawState });
       }
 
       if (!targetSessionId) {
@@ -190,6 +198,7 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
         if (popupWindow) {
           postPopupResult(popupWindow, {
             sessionId: targetSessionId,
+            state: rawState,
             success: false,
             error: 'OAuth session not found in the current client state',
           });
@@ -204,13 +213,14 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
       processingCodesRef.current.add(codeKey);
 
       try {
-        await finishAuth(targetSession.sessionId, code);
+        await finishAuth(rawState, code);
       } catch (error) {
         processingCodesRef.current.delete(codeKey);
         pendingPopupsRef.current.delete(targetSession.sessionId);
         if (popupWindow) {
           postPopupResult(popupWindow, {
-            sessionId: targetSession.sessionId,
+            sessionId: rawState,
+            state: rawState,
             success: false,
             error: error instanceof Error ? error.message : 'Failed to finish auth',
           });
@@ -237,11 +247,14 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
 
   useEffect(() => {
     for (const connection of connections) {
-      const popupWindow = pendingPopupsRef.current.get(connection.sessionId) || null;
+      const pendingPopup = pendingPopupsRef.current.get(connection.sessionId);
+      const popupWindow = pendingPopup?.popupWindow || null;
+      const resultState = pendingPopup?.state || connection.sessionId;
 
       if (connection.state === 'AUTHENTICATED' || connection.state === 'READY' || connection.state === 'CONNECTED') {
         postPopupResult(popupWindow, {
-          sessionId: connection.sessionId,
+          sessionId: resultState,
+          state: resultState,
           success: true,
         });
         for (const codeKey of processingCodesRef.current) {
@@ -255,7 +268,8 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
 
       if (connection.state === 'FAILED') {
         postPopupResult(popupWindow, {
-          sessionId: connection.sessionId,
+          sessionId: resultState,
+          state: resultState,
           success: false,
           error: connection.error || 'Failed to complete authorization',
         });
@@ -277,7 +291,7 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
  * opener window, waits for success/failure, and closes the popup on success.
  *
  * It is intentionally optional: apps can replace it with their own callback
- * page UI or skip popup auth entirely and call `finishAuth(sessionId, code)`
+ * page UI or skip popup auth entirely and call `finishAuth(state, code)`
  * from any callback route they control.
  */
 export function McpOAuthCallbackContent({
@@ -328,7 +342,14 @@ export function McpOAuthCallbackContent({
         return;
       }
 
-      if (event.data.sessionId !== sessionId) {
+      const resultState =
+        typeof event.data.state === 'string'
+          ? event.data.state
+          : typeof event.data.sessionId === 'string'
+            ? event.data.sessionId
+            : '';
+
+      if (resultState !== sessionId) {
         return;
       }
 
@@ -352,7 +373,7 @@ export function McpOAuthCallbackContent({
     window.addEventListener('message', handleResult);
     channel?.addEventListener('message', handleResult);
 
-    const payload = { type: AUTH_CODE_MESSAGE, code, sessionId };
+    const payload = { type: AUTH_CODE_MESSAGE, code, state: sessionId, sessionId };
 
     if (window.opener) {
       try {

package/src/client/react/use-mcp.ts

@@ -6,6 +6,11 @@
 
 import { useEffect, useRef, useState, useCallback, useMemo } from 'react';
 import { SSEClient, type SSEClientOptions } from '../core/sse-client';
+import {
+  getInitialConnectionState,
+  getVisibleConnectionState,
+  isTransientReconnectState,
+} from '../utils/session-state';
 import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
 import type {
   ToolInfo,
@@ -84,6 +89,7 @@ export interface McpConnection {
   authUrl?: string;
   error?: string;
   createdAt?: Date;
+  updatedAt?: Date;
 }
 
 export interface McpClient {
@@ -167,7 +173,7 @@ export interface McpClient {
   /**
    * Complete OAuth authorization
    */
-  finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
+  finishAuth: (state: string, code: string) => Promise<FinishAuthResult>;
 
   /**
    * Explicitly resume OAuth flow for an existing session
@@ -293,42 +299,6 @@ export function useMcp(options: UseMcpOptions): McpClient {
   const updateConnectionsFromEvent = useCallback((event: McpConnectionEvent) => {
     if (!isMountedRef.current) return;
 
-    const isTransientReconnectState = (state: McpConnectionState): boolean =>
-      state === 'INITIALIZING' ||
-      state === 'VALIDATING' ||
-      state === 'RECONNECTING' ||
-      state === 'CONNECTING' ||
-      state === 'CONNECTED' ||
-      state === 'DISCOVERING';
-
-    const getVisibleState = (
-      incomingState: McpConnectionState,
-      existingState?: McpConnectionState,
-      previousState?: McpConnectionState
-    ): McpConnectionState => {
-      // `INITIALIZING` has two meanings in practice:
-      // 1. genuine cold start / reconnect work
-      // 2. an internal setup step that happens mid-OAuth completion
-      //
-      // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
-      // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
-      // We keep the raw event stream intact for observability, but collapse the
-      // visible state back into the current auth phase in the UI.
-      if (
-        incomingState === 'INITIALIZING' &&
-        (existingState === 'AUTHENTICATING' ||
-          existingState === 'AUTHENTICATED' ||
-          previousState === 'AUTHENTICATING' ||
-          previousState === 'AUTHENTICATED')
-      ) {
-        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
-          ? 'AUTHENTICATED'
-          : 'AUTHENTICATING';
-      }
-
-      return incomingState;
-    };
-
     setConnections((prev: McpConnection[]) => {
       switch (event.type) {
         case 'state_changed': {
@@ -336,7 +306,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           if (existing) {
             // Normalize the incoming backend state into the smoother user-facing
             // state we want to render for this existing connection.
-            const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
+            const normalizedState = getVisibleConnectionState(event.state, existing.state, event.previousState);
             // In stateless per-request transport, tool calls can emit transient reconnect states.
             // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
             const nextState =
@@ -344,12 +314,14 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 ? existing.state
                 : normalizedState;
 
+            const updatedAt = new Date();
             return prev.map((c: McpConnection) =>
               c.sessionId === event.sessionId ? {
                 ...c,
                 state: nextState,
                 // update createdAt if present in event, otherwise keep existing
-                createdAt: event.createdAt ? new Date(event.createdAt) : c.createdAt
+                createdAt: event.createdAt ? new Date(event.createdAt) : c.createdAt,
+                updatedAt,
               } : c
             );
           } else {
@@ -367,8 +339,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 serverUrl: event.serverUrl,
                 // New connections do not have prior local state, so we normalize
                 // only against the server-reported previous state.
-                state: getVisibleState(event.state, undefined, event.previousState),
+                state: getVisibleConnectionState(event.state, undefined, event.previousState),
                 createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
+                updatedAt: new Date(),
                 tools: [],
               },
             ];
@@ -382,7 +355,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           }
 
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY' } : c
+            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY', updatedAt: new Date() } : c
           );
         }
 
@@ -453,8 +426,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
             serverName: s.serverName ?? 'Unknown Server',
             serverUrl: s.serverUrl,
             transport: s.transport,
-            state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+            state: getInitialConnectionState(s.status),
             createdAt: new Date(s.createdAt),
+            updatedAt: new Date(s.updatedAt ?? s.createdAt),
             tools: [],
           }))
         );
@@ -466,7 +440,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           if (clientRef.current) {
             try {
               // Pending auth sessions should not auto-trigger popup/redirect on reload.
-              if (session.active === false) {
+              if (session.status !== 'active') {
                 return;
               }
               suppressAuthRedirectSessionsRef.current.add(session.sessionId);
@@ -585,12 +559,12 @@ export function useMcp(options: UseMcpOptions): McpClient {
   /**
    * Complete OAuth authorization
    */
-  const finishAuth = useCallback(async (sessionId: string, code: string): Promise<FinishAuthResult> => {
+  const finishAuth = useCallback(async (state: string, code: string): Promise<FinishAuthResult> => {
     if (!clientRef.current) {
       throw new Error('SSE client not initialized');
     }
 
-    return await clientRef.current.finishAuth(sessionId, code);
+    return await clientRef.current.finishAuth(state, code);
   }, []);
 
   /**

package/src/client/utils/session-state.ts

@@ -0,0 +1,43 @@
+import type { McpConnectionState } from '../../shared/events';
+import type { SessionInfo } from '../../shared/types';
+
+export function getInitialConnectionState(status: SessionInfo['status']): McpConnectionState {
+    return status === 'active' ? 'VALIDATING' : 'AUTHENTICATING';
+}
+
+export function isTransientReconnectState(state: McpConnectionState): boolean {
+    return state === 'INITIALIZING' ||
+        state === 'VALIDATING' ||
+        state === 'RECONNECTING' ||
+        state === 'CONNECTING' ||
+        state === 'CONNECTED' ||
+        state === 'DISCOVERING';
+}
+
+export function getVisibleConnectionState(
+    incomingState: McpConnectionState,
+    existingState?: McpConnectionState,
+    previousState?: McpConnectionState
+): McpConnectionState {
+    // `INITIALIZING` has two meanings in practice:
+    // 1. genuine cold start / reconnect work
+    // 2. an internal setup step that happens mid-OAuth completion
+    //
+    // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+    // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+    if (
+        incomingState === 'INITIALIZING' &&
+        (
+            existingState === 'AUTHENTICATING' ||
+            existingState === 'AUTHENTICATED' ||
+            previousState === 'AUTHENTICATING' ||
+            previousState === 'AUTHENTICATED'
+        )
+    ) {
+        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+            ? 'AUTHENTICATED'
+            : 'AUTHENTICATING';
+    }
+
+    return incomingState;
+}

package/src/client/vue/use-mcp.ts

@@ -6,6 +6,11 @@
 
 import { ref, onMounted, onUnmounted, watch, computed, shallowRef } from 'vue';
 import { SSEClient, type SSEClientOptions } from '../core/sse-client';
+import {
+    getInitialConnectionState,
+    getVisibleConnectionState,
+    isTransientReconnectState,
+} from '../utils/session-state';
 import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
 import type {
     ToolInfo,
@@ -83,6 +88,7 @@ export interface McpConnection {
     authUrl?: string;
     error?: string;
     createdAt?: Date;
+    updatedAt?: Date;
 }
 
 export interface McpClient {
@@ -166,7 +172,7 @@ export interface McpClient {
     /**
      * Complete OAuth authorization
      */
-    finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
+    finishAuth: (state: string, code: string) => Promise<FinishAuthResult>;
 
     /**
      * Explicitly resume OAuth flow for an existing session
@@ -243,51 +249,13 @@ export function useMcp(options: UseMcpOptions): McpClient {
     const updateConnectionsFromEvent = (event: McpConnectionEvent) => {
         if (!isMountedRef.value) return;
 
-        const isTransientReconnectState = (state: McpConnectionState): boolean =>
-            state === 'INITIALIZING' ||
-            state === 'VALIDATING' ||
-            state === 'RECONNECTING' ||
-            state === 'CONNECTING' ||
-            state === 'CONNECTED' ||
-            state === 'DISCOVERING';
-
-        const getVisibleState = (
-            incomingState: McpConnectionState,
-            existingState?: McpConnectionState,
-            previousState?: McpConnectionState
-        ): McpConnectionState => {
-            // `INITIALIZING` has two meanings in practice:
-            // 1. genuine cold start / reconnect work
-            // 2. an internal setup step that happens mid-OAuth completion
-            //
-            // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
-            // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
-            // We keep the raw event stream intact for observability, but collapse the
-            // visible state back into the current auth phase in the UI.
-            if (
-                incomingState === 'INITIALIZING' &&
-                (
-                    existingState === 'AUTHENTICATING' ||
-                    existingState === 'AUTHENTICATED' ||
-                    previousState === 'AUTHENTICATING' ||
-                    previousState === 'AUTHENTICATED'
-                )
-            ) {
-                return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
-                    ? 'AUTHENTICATED'
-                    : 'AUTHENTICATING';
-            }
-
-            return incomingState;
-        };
-
         switch (event.type) {
             case 'state_changed': {
                 const existing = connections.value.find((c) => c.sessionId === event.sessionId);
                 if (existing) {
                     // Normalize the incoming backend state into the smoother user-facing
                     // state we want to render for this existing connection.
-                    const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
+                    const normalizedState = getVisibleConnectionState(event.state, existing.state, event.previousState);
                     // In stateless per-request transport, tool calls can emit transient reconnect states.
                     // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
                     const nextState =
@@ -300,7 +268,8 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         ...existing,
                         state: nextState,
                         // update createdAt if present in event, otherwise keep existing
-                        createdAt: event.createdAt ? new Date(event.createdAt) : existing.createdAt
+                        createdAt: event.createdAt ? new Date(event.createdAt) : existing.createdAt,
+                        updatedAt: new Date(),
                     };
                 } else {
                     // Fix: Don't add back disconnected sessions that were just removed
@@ -314,8 +283,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         serverName: event.serverName,
                         // New connections do not have prior local state, so we normalize
                         // only against the server-reported previous state.
-                        state: getVisibleState(event.state, undefined, event.previousState),
+                        state: getVisibleConnectionState(event.state, undefined, event.previousState),
                         createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
+                        updatedAt: new Date(),
                         tools: [],
                     }];
                 }
@@ -325,7 +295,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
             case 'tools_discovered': {
                 const index = connections.value.findIndex((c) => c.sessionId === event.sessionId);
                 if (index !== -1) {
-                    connections.value[index] = { ...connections.value[index], tools: event.tools, state: 'READY' };
+                    connections.value[index] = { ...connections.value[index], tools: event.tools, state: 'READY', updatedAt: new Date() };
                 }
                 break;
             }
@@ -397,8 +367,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                     serverName: s.serverName ?? 'Unknown Server',
                     serverUrl: s.serverUrl,
                     transport: s.transport,
-                    state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+                    state: getInitialConnectionState(s.status),
                     createdAt: new Date(s.createdAt),
+                    updatedAt: new Date(s.updatedAt ?? s.createdAt),
                     tools: [],
                 }));
             }
@@ -409,7 +380,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
                     if (clientRef.value) {
                         try {
                             // Pending auth sessions should not auto-trigger popup/redirect on reload.
-                            if (session.active === false) {
+                            if (session.status !== 'active') {
                                 return;
                             }
                             suppressAuthRedirectSessions.value.add(session.sessionId);
@@ -573,12 +544,12 @@ export function useMcp(options: UseMcpOptions): McpClient {
     /**
      * Complete OAuth authorization
      */
-    const finishAuth = async (sessionId: string, code: string): Promise<FinishAuthResult> => {
+    const finishAuth = async (state: string, code: string): Promise<FinishAuthResult> => {
         if (!clientRef.value) {
             throw new Error('SSE client not initialized');
         }
 
-        return await clientRef.value.finishAuth(sessionId, code);
+        return await clientRef.value.finishAuth(state, code);
     };
 
     /**

package/src/server/handlers/sse-handler.ts

@@ -36,6 +36,7 @@ import type {
 import { RpcErrorCodes } from '../../shared/errors.js';
 import { UnauthorizedError } from '../../shared/errors.js';
 import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
+import { parseOAuthState } from '../../shared/utils.js';
 import { MCPClient } from '../mcp/oauth-client.js';
 import { sessions } from '../storage/index.js';
 
@@ -238,7 +239,8 @@ export class SSEConnectionManager {
         serverUrl: s.serverUrl,
         transport: s.transportType,
         createdAt: s.createdAt,
-        active: s.active !== false,
+        updatedAt: s.updatedAt ?? s.createdAt,
+        status: s.status ?? 'pending',
       })),
     };
   }
@@ -265,7 +267,7 @@ export class SSEConnectionManager {
     if (duplicate) {
       // If the existing session is still pending OAuth, treat connect as "resume auth"
       // instead of failing with duplicate connection error.
-      if (duplicate.active === false) {
+      if (duplicate.status === 'pending') {
         await this.getSession({ sessionId: duplicate.sessionId });
         return {
           sessionId: duplicate.sessionId,
@@ -354,8 +356,8 @@ export class SSEConnectionManager {
     const client = this.clients.get(sessionId);
 
     if (client) {
+      // clearSession() handles DELETE + local cleanup internally.
       await client.clearSession();
-      client.disconnect();
       this.clients.delete(sessionId);
     } else {
       // Handle orphaned sessions (e.g., OAuth flow failed before client was stored)
@@ -504,7 +506,10 @@ export class SSEConnectionManager {
    * Complete OAuth authorization flow
    */
   private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
-    const { sessionId, code } = params;
+    const { code } = params;
+    const oauthState = params.state;
+    const parsedState = parseOAuthState(oauthState);
+    const sessionId = parsedState?.sessionId || oauthState;
 
     const session = await sessions.get(this.userId, sessionId);
     if (!session) {
@@ -533,7 +538,7 @@ export class SSEConnectionManager {
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));
 
-      await client.finishAuth(code);
+      await client.finishAuth(code, oauthState);
       this.clients.set(sessionId, client);
 
       const tools = await client.listTools();
@@ -601,16 +606,18 @@ export class SSEConnectionManager {
   /**
    * Cleanup and close all connections
    */
-  dispose(): void {
+  async dispose(): Promise<void> {
     this.isActive = false;
 
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
     }
 
-    for (const client of this.clients.values()) {
-      client.disconnect();
-    }
+    // Send HTTP DELETE to each Streamable HTTP server before closing, per spec.
+    // Run in parallel so shutdown is not serialised across many sessions.
+    await Promise.all(
+      Array.from(this.clients.values()).map((client) => client.disconnect())
+    );
 
     this.clients.clear();
   }

package/src/server/mcp/multi-session-client.ts

@@ -66,12 +66,8 @@ export class MultiSessionClient {
      *
      * A session is considered connectable when:
      * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
-     * - Its `active` flag is not explicitly `false` — sessions with `active: false` are
-     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     * - Its status is `active`. Pending sessions are skipped here
      *   and let the OAuth flow complete separately before we try to reconnect them.
-     *
-     * Note: Sessions where `active` is `undefined` (legacy records) are included
-     * for backwards compatibility.
      */
     private async getActiveSessions(): Promise<Session[]> {
         const sessionList = await sessions.list(this.userId);
@@ -79,7 +75,7 @@ export class MultiSessionClient {
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
-            s.active !== false  // exclude OAuth-pending / failed sessions
+            s.status === 'active'
         );
         return valid;
     }
@@ -104,6 +100,9 @@ export class MultiSessionClient {
      * Connects a single session, with built-in deduplication to prevent race conditions.
      *
      * - If a client for this session already exists and is connected, returns immediately.
+     * - If the existing client entry is no longer connected (e.g. it was explicitly
+     *   disconnected), it is evicted so that `establishConnectionWithRetries` creates a
+     *   fresh transport — preventing "Client already connected" errors from the SDK.
      * - If a connection attempt for this session is already in-flight (e.g. from a
      *   concurrent call), it joins the existing promise instead of starting a new one.
      *   This is the key concurrency lock — the `connectionPromises` map acts as a
@@ -111,9 +110,19 @@ export class MultiSessionClient {
      * - On completion (success or failure), the promise is cleaned up from the map.
      */
     private async connectSession(session: Session): Promise<void> {
-        const existingClient = this.clients.find(c => c.getSessionId() === session.sessionId);
-        if (existingClient?.isConnected()) {
-            return;
+        const existing = this.clients.find(c => c.getSessionId() === session.sessionId);
+
+        if (existing) {
+            if (existing.isConnected()) {
+                // Genuinely connected — nothing to do.
+                return;
+            }
+
+            // Client entry exists but is no longer connected (explicit disconnect or
+            // a prior failed reconnect attempt). Remove it so the fresh connect below
+            // starts with a clean slate and the underlying SDK Client doesn't complain
+            // about an already-attached transport.
+            this.clients = this.clients.filter(c => c !== existing);
         }
 
         // Avoid concurrent connection attempts for the same session
@@ -201,9 +210,33 @@ export class MultiSessionClient {
      */
     async connect(): Promise<void> {
         const sessions = await this.getActiveSessions();
+        const activeSessionIds = new Set(sessions.map(s => s.sessionId));
+
+        // Prune stale clients whose sessions no longer exist in storage.
+        // Otherwise a lingering MCPClient with a still-alive SDK Client
+        // transport triggers OAuth refreshes on listTools(), and the
+        // StorageOAuthClientProvider.state() -> patchCredentials() call
+        // fails with a FK violation because the session was deleted.
+        this.clients = this.clients.filter(c => activeSessionIds.has(c.getSessionId()));
+
         await this.connectInBatches(sessions);
     }
 
+    /**
+     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
+     *
+     * Call this when downstream MCP servers have expired their transport sessions
+     * (e.g. after a remote server restart) and subsequent tool calls return
+     * "Session not found. Reconnect without session header." errors.
+     *
+     * OAuth tokens are preserved in the storage backend — no re-authentication
+     * is required. Only the in-memory transport sessions are cleared.
+     */
+    async reconnect(): Promise<void> {
+        await this.disconnect();
+        await this.connect();
+    }
+
     /**
      * Returns all currently connected `MCPClient` instances.
      *
@@ -217,11 +250,15 @@ export class MultiSessionClient {
     /**
      * Gracefully disconnects all active MCP clients and clears the internal client list.
      *
+     * For Streamable HTTP sessions, each client sends an HTTP DELETE to its MCP
+     * endpoint per the spec before closing locally. All disconnects run in
+     * parallel so shutdown is not serialised across many sessions.
+     *
      * Call this during server shutdown or when a user logs out to free up
      * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
-    disconnect(): void {
-        this.clients.forEach((client) => client.disconnect());
+    async disconnect(): Promise<void> {
+        await Promise.all(this.clients.map((client) => client.disconnect()));
         this.clients = [];
     }
 }