@mcp-ts/sdk 1.3.5 → 1.3.7

package/dist/index.mjs

@@ -126,8 +126,6 @@ var SOFTWARE_ID = "@mcp-ts";
 var SOFTWARE_VERSION = "1.3.4";
 var MCP_CLIENT_NAME = "mcp-ts-oauth-client";
 var MCP_CLIENT_VERSION = "2.0";
-
-// src/server/storage/redis-backend.ts
 var firstChar = customAlphabet(
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
   1
@@ -136,6 +134,18 @@ var rest = customAlphabet(
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
   11
 );
+function sanitizeServerLabel(name) {
+  let sanitized = name.replace(/[^a-zA-Z0-9-_]/g, "_").replace(/_{2,}/g, "_").toLowerCase();
+  if (!/^[a-zA-Z]/.test(sanitized)) {
+    sanitized = "s_" + sanitized;
+  }
+  return sanitized;
+}
+function generateSessionId() {
+  return firstChar() + rest();
+}
+
+// src/server/storage/redis-backend.ts
 var RedisStorageBackend = class {
   constructor(redis2) {
     this.redis = redis2;
@@ -144,6 +154,14 @@ var RedisStorageBackend = class {
     __publicField(this, "IDENTITY_KEY_PREFIX", "mcp:identity:");
     __publicField(this, "IDENTITY_KEY_SUFFIX", ":sessions");
   }
+  async init() {
+    try {
+      await this.redis.ping();
+      console.log("[mcp-ts][Storage] Redis: \u2713 Connected to server.");
+    } catch (error) {
+      throw new Error(`[RedisStorage] Failed to connect to Redis: ${error.message}`);
+    }
+  }
   /**
    * Generates Redis key for a specific session
    * @private
@@ -186,7 +204,7 @@ var RedisStorageBackend = class {
     return Array.from(keys);
   }
   generateSessionId() {
-    return firstChar() + rest();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     const { sessionId, identity } = session;
@@ -354,14 +372,8 @@ var RedisStorageBackend = class {
     }
   }
 };
-var firstChar2 = customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
-  1
-);
-var rest2 = customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-  11
-);
+
+// src/server/storage/memory-backend.ts
 var MemoryStorageBackend = class {
   constructor() {
     // Map<identity:sessionId, SessionData>
@@ -369,11 +381,14 @@ var MemoryStorageBackend = class {
     // Map<identity, Set<sessionId>>
     __publicField(this, "identitySessions", /* @__PURE__ */ new Map());
   }
+  async init() {
+    console.log("[mcp-ts][Storage] Memory: \u2713 internal memory store active.");
+  }
   getSessionKey(identity, sessionId) {
     return `${identity}:${sessionId}`;
   }
   generateSessionId() {
-    return firstChar2() + rest2();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     const { sessionId, identity } = session;
@@ -444,14 +459,6 @@ var MemoryStorageBackend = class {
   async disconnect() {
   }
 };
-var firstChar3 = customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
-  1
-);
-var rest3 = customAlphabet(
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-  11
-);
 var FileStorageBackend = class {
   /**
    * @param options.path Path to the JSON file storage (default: ./sessions.json)
@@ -488,6 +495,7 @@ var FileStorageBackend = class {
       }
     }
     this.initialized = true;
+    console.log(`[mcp-ts][Storage] File: \u2713 storage directory at ${path.dirname(this.filePath)} verified.`);
   }
   async ensureInitialized() {
     if (!this.initialized) await this.init();
@@ -501,7 +509,7 @@ var FileStorageBackend = class {
     return `${identity}:${sessionId}`;
   }
   generateSessionId() {
-    return firstChar3() + rest3();
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     await this.ensureInitialized();
@@ -592,6 +600,7 @@ var SqliteStorage = class {
                 CREATE INDEX IF NOT EXISTS idx_${this.table}_identity ON ${this.table}(identity);
             `);
       this.initialized = true;
+      console.log(`[mcp-ts][Storage] SQLite: \u2713 database at ${this.dbPath} verified.`);
     } catch (error) {
       if (error.code === "MODULE_NOT_FOUND" || error.message?.includes("better-sqlite3")) {
         throw new Error(
@@ -607,12 +616,7 @@ var SqliteStorage = class {
     }
   }
   generateSessionId() {
-    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-    let result = "";
-    for (let i = 0; i < 32; i++) {
-      result += chars.charAt(Math.floor(Math.random() * chars.length));
-    }
-    return result;
+    return generateSessionId();
   }
   async createSession(session, ttl) {
     this.ensureInitialized();
@@ -707,6 +711,157 @@ var SqliteStorage = class {
   }
 };
 
+// src/server/storage/supabase-backend.ts
+var SupabaseStorageBackend = class {
+  constructor(supabase) {
+    this.supabase = supabase;
+    __publicField(this, "DEFAULT_TTL", SESSION_TTL_SECONDS);
+  }
+  async init() {
+    const { error } = await this.supabase.from("mcp_sessions").select("session_id").limit(0);
+    if (error) {
+      if (error.code === "42P01") {
+        throw new Error(
+          '[SupabaseStorage] Table "mcp_sessions" not found in your database. Please run "npx mcp-ts supabase-init" in your project to set up the required table and RLS policies.'
+        );
+      }
+      throw new Error(`[SupabaseStorage] Initialization check failed: ${error.message}`);
+    }
+    console.log('[mcp-ts][Storage] Supabase: \u2713 "mcp_sessions" table verified.');
+  }
+  generateSessionId() {
+    return generateSessionId();
+  }
+  mapRowToSessionData(row) {
+    return {
+      sessionId: row.session_id,
+      serverId: row.server_id,
+      serverName: row.server_name,
+      serverUrl: row.server_url,
+      transportType: row.transport_type,
+      callbackUrl: row.callback_url,
+      createdAt: new Date(row.created_at).getTime(),
+      identity: row.identity,
+      headers: row.headers,
+      active: row.active,
+      clientInformation: row.client_information,
+      tokens: row.tokens,
+      codeVerifier: row.code_verifier,
+      clientId: row.client_id
+    };
+  }
+  async createSession(session, ttl) {
+    const { sessionId, identity } = session;
+    if (!sessionId || !identity) throw new Error("identity and sessionId required");
+    const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+    const expiresAt = new Date(Date.now() + effectiveTtl * 1e3).toISOString();
+    const { error } = await this.supabase.from("mcp_sessions").insert({
+      session_id: sessionId,
+      user_id: identity,
+      // Maps user_id to identity to support RLS using auth.uid()
+      server_id: session.serverId,
+      server_name: session.serverName,
+      server_url: session.serverUrl,
+      transport_type: session.transportType,
+      callback_url: session.callbackUrl,
+      created_at: new Date(session.createdAt || Date.now()).toISOString(),
+      identity,
+      headers: session.headers,
+      active: session.active ?? false,
+      client_information: session.clientInformation,
+      tokens: session.tokens,
+      code_verifier: session.codeVerifier,
+      client_id: session.clientId,
+      expires_at: expiresAt
+    });
+    if (error) {
+      if (error.code === "23505") {
+        throw new Error(`Session ${sessionId} already exists`);
+      }
+      throw new Error(`Failed to create session in Supabase: ${error.message}`);
+    }
+  }
+  async updateSession(identity, sessionId, data, ttl) {
+    const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+    const expiresAt = new Date(Date.now() + effectiveTtl * 1e3).toISOString();
+    const updateData = {
+      expires_at: expiresAt,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if ("serverId" in data) updateData.server_id = data.serverId;
+    if ("serverName" in data) updateData.server_name = data.serverName;
+    if ("serverUrl" in data) updateData.server_url = data.serverUrl;
+    if ("transportType" in data) updateData.transport_type = data.transportType;
+    if ("callbackUrl" in data) updateData.callback_url = data.callbackUrl;
+    if ("active" in data) updateData.active = data.active;
+    if ("headers" in data) updateData.headers = data.headers;
+    if ("clientInformation" in data) updateData.client_information = data.clientInformation;
+    if ("tokens" in data) updateData.tokens = data.tokens;
+    if ("codeVerifier" in data) updateData.code_verifier = data.codeVerifier;
+    if ("clientId" in data) updateData.client_id = data.clientId;
+    const { data: updatedRows, error } = await this.supabase.from("mcp_sessions").update(updateData).eq("identity", identity).eq("session_id", sessionId).select("id");
+    if (error) {
+      throw new Error(`Failed to update session: ${error.message}`);
+    }
+    if (!updatedRows || updatedRows.length === 0) {
+      throw new Error(`Session ${sessionId} not found for identity ${identity}`);
+    }
+  }
+  async getSession(identity, sessionId) {
+    const { data, error } = await this.supabase.from("mcp_sessions").select("*").eq("identity", identity).eq("session_id", sessionId).maybeSingle();
+    if (error) {
+      console.error("[SupabaseStorage] Failed to get session:", error);
+      return null;
+    }
+    if (!data) return null;
+    return this.mapRowToSessionData(data);
+  }
+  async getIdentitySessionsData(identity) {
+    const { data, error } = await this.supabase.from("mcp_sessions").select("*").eq("identity", identity);
+    if (error) {
+      console.error(`[SupabaseStorage] Failed to get session data for ${identity}:`, error);
+      return [];
+    }
+    return data.map((row) => this.mapRowToSessionData(row));
+  }
+  async removeSession(identity, sessionId) {
+    const { error } = await this.supabase.from("mcp_sessions").delete().eq("identity", identity).eq("session_id", sessionId);
+    if (error) {
+      console.error("[SupabaseStorage] Failed to remove session:", error);
+    }
+  }
+  async getIdentityMcpSessions(identity) {
+    const { data, error } = await this.supabase.from("mcp_sessions").select("session_id").eq("identity", identity);
+    if (error) {
+      console.error(`[SupabaseStorage] Failed to get sessions for ${identity}:`, error);
+      return [];
+    }
+    return data.map((row) => row.session_id);
+  }
+  async getAllSessionIds() {
+    const { data, error } = await this.supabase.from("mcp_sessions").select("session_id");
+    if (error) {
+      console.error("[SupabaseStorage] Failed to get all sessions:", error);
+      return [];
+    }
+    return data.map((row) => row.session_id);
+  }
+  async clearAll() {
+    const { error } = await this.supabase.from("mcp_sessions").delete().neq("session_id", "");
+    if (error) {
+      console.error("[SupabaseStorage] Failed to clear sessions:", error);
+    }
+  }
+  async cleanupExpiredSessions() {
+    const { error } = await this.supabase.from("mcp_sessions").delete().lt("expires_at", (/* @__PURE__ */ new Date()).toISOString());
+    if (error) {
+      console.error("[SupabaseStorage] Failed to cleanup expired sessions:", error);
+    }
+  }
+  async disconnect() {
+  }
+};
+
 // src/server/storage/index.ts
 var storageInstance = null;
 var storagePromise = null;
@@ -725,53 +880,85 @@ async function createStorage() {
     try {
       const { getRedis: getRedis2 } = await Promise.resolve().then(() => (init_redis(), redis_exports));
       const redis2 = await getRedis2();
-      console.log("[Storage] Using Redis storage (Explicit)");
-      return new RedisStorageBackend(redis2);
+      console.log('[mcp-ts][Storage] Explicit selection: "redis"');
+      return await initializeStorage(new RedisStorageBackend(redis2));
     } catch (error) {
-      console.error("[Storage] Failed to initialize Redis:", error.message);
-      console.log("[Storage] Falling back to In-Memory storage");
-      return new MemoryStorageBackend();
+      console.error("[mcp-ts][Storage] Failed to initialize Redis:", error.message);
+      console.log("[mcp-ts][Storage] Falling back to In-Memory storage");
+      return await initializeStorage(new MemoryStorageBackend());
     }
   }
   if (type === "file") {
     const filePath = process.env.MCP_TS_STORAGE_FILE;
-    if (!filePath) {
-      console.warn('[Storage] MCP_TS_STORAGE_TYPE is "file" but MCP_TS_STORAGE_FILE is missing');
-    }
-    console.log(`[Storage] Using File storage (${filePath}) (Explicit)`);
+    console.log(`[mcp-ts][Storage] Explicit selection: "file" (${filePath || "default"})`);
     return await initializeStorage(new FileStorageBackend({ path: filePath }));
   }
   if (type === "sqlite") {
     const dbPath = process.env.MCP_TS_STORAGE_SQLITE_PATH;
-    console.log(`[Storage] Using SQLite storage (${dbPath || "default"}) (Explicit)`);
+    console.log(`[mcp-ts][Storage] Explicit selection: "sqlite" (${dbPath || "default"})`);
     return await initializeStorage(new SqliteStorage({ path: dbPath }));
   }
+  if (type === "supabase") {
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY;
+    if (!url || !key) {
+      console.warn('[mcp-ts][Storage] Explicit selection "supabase" requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.');
+    } else {
+      if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+        console.warn('[mcp-ts][Storage] \u26A0\uFE0F  Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+      }
+      try {
+        const { createClient } = await import('@supabase/supabase-js');
+        const client = createClient(url, key);
+        console.log('[mcp-ts][Storage] Explicit selection: "supabase"');
+        return await initializeStorage(new SupabaseStorageBackend(client));
+      } catch (error) {
+        console.error("[mcp-ts][Storage] Failed to initialize Supabase:", error.message);
+        console.log("[mcp-ts][Storage] Falling back to In-Memory storage");
+        return await initializeStorage(new MemoryStorageBackend());
+      }
+    }
+  }
   if (type === "memory") {
-    console.log("[Storage] Using In-Memory storage (Explicit)");
-    return new MemoryStorageBackend();
+    console.log('[mcp-ts][Storage] Explicit selection: "memory"');
+    return await initializeStorage(new MemoryStorageBackend());
   }
   if (process.env.REDIS_URL) {
     try {
       const { getRedis: getRedis2 } = await Promise.resolve().then(() => (init_redis(), redis_exports));
       const redis2 = await getRedis2();
-      console.log("[Storage] Auto-detected REDIS_URL. Using Redis storage.");
-      return new RedisStorageBackend(redis2);
+      console.log('[mcp-ts][Storage] Auto-detection: "redis" (via REDIS_URL)');
+      return await initializeStorage(new RedisStorageBackend(redis2));
     } catch (error) {
-      console.error("[Storage] Redis auto-detection failed:", error.message);
-      console.log("[Storage] Falling back to In-Memory storage");
-      return new MemoryStorageBackend();
+      console.error("[mcp-ts][Storage] Redis auto-detection failed:", error.message);
+      console.log("[mcp-ts][Storage] Falling back to next available backend");
     }
   }
   if (process.env.MCP_TS_STORAGE_FILE) {
-    console.log(`[Storage] Auto-detected MCP_TS_STORAGE_FILE. Using File storage (${process.env.MCP_TS_STORAGE_FILE}).`);
+    console.log(`[mcp-ts][Storage] Auto-detection: "file" (${process.env.MCP_TS_STORAGE_FILE})`);
     return await initializeStorage(new FileStorageBackend({ path: process.env.MCP_TS_STORAGE_FILE }));
   }
   if (process.env.MCP_TS_STORAGE_SQLITE_PATH) {
-    console.log(`[Storage] Auto-detected MCP_TS_STORAGE_SQLITE_PATH. Using SQLite storage (${process.env.MCP_TS_STORAGE_SQLITE_PATH}).`);
+    console.log(`[mcp-ts][Storage] Auto-detection: "sqlite" (${process.env.MCP_TS_STORAGE_SQLITE_PATH})`);
     return await initializeStorage(new SqliteStorage({ path: process.env.MCP_TS_STORAGE_SQLITE_PATH }));
   }
-  console.log("[Storage] No storage configured. Using In-Memory storage (Default).");
-  return new MemoryStorageBackend();
+  if (process.env.SUPABASE_URL && (process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY)) {
+    try {
+      const { createClient } = await import('@supabase/supabase-js');
+      const url = process.env.SUPABASE_URL;
+      const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY;
+      if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+        console.warn('[mcp-ts][Storage] \u26A0\uFE0F Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+      }
+      const client = createClient(url, key);
+      console.log('[mcp-ts][Storage] Auto-detection: "supabase" (via SUPABASE_URL)');
+      return await initializeStorage(new SupabaseStorageBackend(client));
+    } catch (error) {
+      console.error("[mcp-ts][Storage] Supabase auto-detection failed:", error.message);
+    }
+  }
+  console.log('[mcp-ts][Storage] Defaulting to: "memory"');
+  return await initializeStorage(new MemoryStorageBackend());
 }
 async function getStorage() {
   if (storageInstance) {
@@ -981,15 +1168,6 @@ var StorageOAuthClientProvider = class {
   }
 };
 
-// src/shared/utils.ts
-function sanitizeServerLabel(name) {
-  let sanitized = name.replace(/[^a-zA-Z0-9-_]/g, "_").replace(/_{2,}/g, "_").toLowerCase();
-  if (!/^[a-zA-Z]/.test(sanitized)) {
-    sanitized = "s_" + sanitized;
-  }
-  return sanitized;
-}
-
 // src/shared/events.ts
 var Emitter = class {
   constructor() {
@@ -2020,47 +2198,132 @@ var MCPClient = class _MCPClient {
 };
 
 // src/server/mcp/multi-session-client.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_RETRY_DELAY_MS = 1e3;
+var CONNECTION_BATCH_SIZE = 5;
 var MultiSessionClient = class {
+  /**
+   * Creates a new MultiSessionClient for the given user identity.
+   *
+   * @param identity - A unique string identifying the user (e.g. user ID or email).
+   * @param options  - Optional tuning for connection timeout, retry count, and retry delay.
+   *                   Falls back to sensible defaults if not provided.
+   */
   constructor(identity, options = {}) {
     __publicField(this, "clients", []);
     __publicField(this, "identity");
     __publicField(this, "options");
+    __publicField(this, "connectionPromises", /* @__PURE__ */ new Map());
     this.identity = identity;
     this.options = {
-      timeout: 15e3,
-      maxRetries: 2,
-      retryDelay: 1e3,
+      timeout: DEFAULT_TIMEOUT_MS,
+      maxRetries: DEFAULT_MAX_RETRIES,
+      retryDelay: DEFAULT_RETRY_DELAY_MS,
       ...options
     };
   }
+  /**
+   * Fetches all sessions for this identity from storage and returns only the
+   * ones that are ready to connect.
+   *
+   * 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
+   *   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.
+   */
   async getActiveSessions() {
     const sessions = await storage.getIdentitySessionsData(this.identity);
-    console.log(
-      `[MultiSessionClient] All sessions for ${this.identity}:`,
-      sessions.map((s) => ({ sessionId: s.sessionId, serverId: s.serverId }))
+    const valid = sessions.filter(
+      (s) => s.serverId && s.serverUrl && s.callbackUrl && s.active !== false
+      // exclude OAuth-pending / failed sessions
     );
-    const valid = sessions.filter((s) => s.serverId && s.serverUrl && s.callbackUrl);
-    console.log(`[MultiSessionClient] Filtered valid sessions:`, valid.length);
     return valid;
   }
+  /**
+   * Connects to a list of sessions in controlled batches of `CONNECTION_BATCH_SIZE`.
+   *
+   * Batching prevents overwhelming the event loop or external servers when a user
+   * has many active MCP sessions (e.g. 20+ servers). Within each batch, sessions
+   * are connected concurrently using `Promise.all` for speed.
+   */
   async connectInBatches(sessions) {
-    const BATCH_SIZE = 5;
-    for (let i = 0; i < sessions.length; i += BATCH_SIZE) {
-      const batch = sessions.slice(i, i + BATCH_SIZE);
+    for (let i = 0; i < sessions.length; i += CONNECTION_BATCH_SIZE) {
+      const batch = sessions.slice(i, i + CONNECTION_BATCH_SIZE);
       await Promise.all(batch.map((session) => this.connectSession(session)));
     }
   }
+  /**
+   * 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 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
+   *   per-session mutex so we never spin up two physical connections for the same session.
+   * - On completion (success or failure), the promise is cleaned up from the map.
+   */
   async connectSession(session) {
     const existingClient = this.clients.find((c) => c.getSessionId() === session.sessionId);
     if (existingClient?.isConnected()) {
       return;
     }
-    const maxRetries = this.options.maxRetries ?? 2;
-    const retryDelay = this.options.retryDelay ?? 1e3;
+    if (this.connectionPromises.has(session.sessionId)) {
+      return this.connectionPromises.get(session.sessionId);
+    }
+    const connectPromise = this.establishConnectionWithRetries(session);
+    this.connectionPromises.set(session.sessionId, connectPromise);
+    try {
+      await connectPromise;
+    } finally {
+      this.connectionPromises.delete(session.sessionId);
+    }
+  }
+  /**
+   * The core connection loop for a single session.
+   *
+   * Attempts to establish a physical MCP connection, retrying up to `maxRetries` times
+   * if the connection fails. Each attempt:
+   * 1. Creates a fresh `MCPClient` instance from the session data.
+   * 2. Races the connect call against a timeout promise — if the server doesn't respond
+   *    within `timeoutMs`, the attempt is aborted and counted as a failure.
+   * 3. On success, replaces any stale client entry for this session in the `clients` array.
+   * 4. On failure, waits `retryDelay` ms before the next attempt.
+   *
+   * If all attempts are exhausted, logs an error and returns silently (does not throw),
+   * so a single bad server doesn't block the rest of the batch from connecting.
+   */
+  async establishConnectionWithRetries(session) {
+    const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        const client = await this.createAndConnectClient(session);
+        const client = new MCPClient({
+          identity: this.identity,
+          sessionId: session.sessionId,
+          serverId: session.serverId,
+          serverUrl: session.serverUrl,
+          callbackUrl: session.callbackUrl,
+          serverName: session.serverName,
+          transportType: session.transportType,
+          headers: session.headers
+        });
+        const timeoutMs = this.options.timeout ?? DEFAULT_TIMEOUT_MS;
+        let timeoutTimer;
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutTimer = setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        try {
+          await Promise.race([client.connect(), timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutTimer);
+        }
+        this.clients = this.clients.filter((c) => c.getSessionId() !== session.sessionId);
         this.clients.push(client);
         return;
       } catch (error) {
@@ -2072,36 +2335,32 @@ var MultiSessionClient = class {
     }
     console.error(`[MultiSessionClient] Failed to connect to session ${session.sessionId} after ${maxRetries + 1} attempts:`, lastError);
   }
-  async createAndConnectClient(session) {
-    const client = new MCPClient({
-      identity: this.identity,
-      sessionId: session.sessionId,
-      serverId: session.serverId,
-      serverUrl: session.serverUrl,
-      callbackUrl: session.callbackUrl,
-      serverName: session.serverName,
-      transportType: session.transportType,
-      headers: session.headers
-    });
-    const timeoutMs = this.options.timeout ?? 15e3;
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
-    });
-    await Promise.race([client.connect(), timeoutPromise]);
-    return client;
-  }
+  /**
+   * The main entry point. Fetches all active sessions for this identity from
+   * storage and establishes connections to all of them in batches.
+   *
+   * Call this once after creating the client. On traditional servers, you can
+   * cache the `MultiSessionClient` instance after calling `connect()` to avoid
+   * re-fetching and re-connecting on every request.
+   */
   async connect() {
     const sessions = await this.getActiveSessions();
     await this.connectInBatches(sessions);
   }
   /**
-   * Returns the array of currently connected clients.
+   * Returns all currently connected `MCPClient` instances.
+   *
+   * Use this to enumerate available tools across all connected servers,
+   * or to route a tool call to the right client by `serverId`.
    */
   getClients() {
     return this.clients;
   }
   /**
-   * Disconnects all clients.
+   * Gracefully disconnects all active MCP clients and clears the internal client list.
+   *
+   * Call this during server shutdown or when a user logs out to free up
+   * underlying transport resources (SSE streams, HTTP connections, etc.).
    */
   disconnect() {
     this.clients.forEach((client) => client.disconnect());