@mcp-ts/sdk 1.5.0 → 1.5.2

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

@@ -117,6 +117,17 @@ export interface McpClient {
      */
     disconnect: (sessionId: string) => Promise<void>;
 
+    /**
+     * Reconnect to an MCP server (disconnects existing session first)
+     */
+    reconnect: (params: {
+        serverId: string;
+        serverName: string;
+        serverUrl: string;
+        callbackUrl: string;
+        transportType?: 'sse' | 'streamable_http';
+    }) => Promise<string>;
+
     /**
      * Get connection by session ID
      */
@@ -240,16 +251,49 @@ export function useMcp(options: UseMcpOptions): McpClient {
             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);
                     // 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 =
-                        existing.state === 'READY' && isTransientReconnectState(event.state)
+                        existing.state === 'READY' && isTransientReconnectState(normalizedState)
                             ? existing.state
-                            : event.state;
+                            : normalizedState;
 
                     const index = connections.value.indexOf(existing);
                     connections.value[index] = {
@@ -268,7 +312,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         sessionId: event.sessionId,
                         serverId: event.serverId,
                         serverName: event.serverName,
-                        state: event.state,
+                        // 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),
                         createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                         tools: [],
                     }];
@@ -457,6 +503,36 @@ export function useMcp(options: UseMcpOptions): McpClient {
         return result.sessionId;
     };
 
+    /**
+     * Reconnect to an MCP server (tears down existing session, then connects fresh)
+     */
+    const reconnect = async (params: {
+        serverId: string;
+        serverName: string;
+        serverUrl: string;
+        callbackUrl: string;
+        transportType?: 'sse' | 'streamable_http';
+    }): Promise<string> => {
+        if (!clientRef.value) {
+            throw new Error('SSE client not initialized');
+        }
+
+        // Find and disconnect existing session for the same server
+        const existing = connections.value.find(
+            (c) => c.serverId === params.serverId || c.serverUrl === params.serverUrl
+        );
+        if (existing) {
+            await clientRef.value.disconnectFromServer(existing.sessionId);
+            if (isMountedRef.value) {
+                connections.value = connections.value.filter((c) => c.sessionId !== existing.sessionId);
+            }
+        }
+
+        // Connect fresh
+        const result = await clientRef.value.connectToServer(params);
+        return result.sessionId;
+    };
+
     /**
      * Disconnect from an MCP server
      */
@@ -607,6 +683,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
         status: status as unknown as { value: 'connecting' | 'connected' | 'disconnected' | 'error' },
         isInitializing: isInitializing as unknown as { value: boolean },
         connect,
+        reconnect,
         disconnect,
         getConnection,
         getConnectionByServerId,

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

@@ -363,9 +363,24 @@ export class SSEConnectionManager {
       return existing;
     }
 
+    const session = await storage.getSession(this.identity, sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
     const client = new MCPClient({
       identity: this.identity,
       sessionId,
+      // These fields are optional in MCPClient, but when rehydrating a known
+      // stored session on the server we pass them explicitly to preserve the
+      // original transport/connection metadata instead of relying on lazy
+      // reloading during initialize().
+      serverId: session.serverId,
+      serverName: session.serverName,
+      serverUrl: session.serverUrl,
+      callbackUrl: session.callbackUrl,
+      transportType: session.transportType,
+      headers: session.headers,
     });
 
     // Subscribe to events before connecting
@@ -437,6 +452,16 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original transport/connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        transportType: session.transportType,
+        headers: session.headers,
         ...clientMetadata,
       });
 
@@ -478,6 +503,20 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        // NOTE: transportType is intentionally omitted here.
+        // The session's stored transportType is a placeholder ('streamable_http')
+        // set before transport negotiation. Omitting it lets MCPClient auto-negotiate
+        // (try streamable_http → SSE fallback), which is critical for servers like
+        // Neon that only support SSE transport.
+        headers: session.headers,
       });
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));

package/src/server/mcp/oauth-client.ts

@@ -500,16 +500,10 @@ export class MCPClient {
       this.emitStateChange('CONNECTED');
       this.emitProgress('Connected successfully');
 
-      // Promote short-lived OAuth-pending session TTL to long-lived active TTL once.
-      // Also persist when transport negotiation changed the effective transport.
-      const existingSession = await storage.getSession(this.identity, this.sessionId);
-      const needsTransportUpdate = !existingSession || existingSession.transportType !== this.transportType;
-      const needsTtlPromotion = !existingSession || existingSession.active !== true;
-
-      if (needsTransportUpdate || needsTtlPromotion) {
-        console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
-        await this.saveSession(SESSION_TTL_SECONDS, true);
-      }
+      // Refresh session metadata on every successful connect so active sessions
+      // record ongoing usage and don't look dormant to storage cleanup jobs.
+      console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
+      await this.saveSession(SESSION_TTL_SECONDS, true);
     } catch (error) {
       /** Handle Authentication Errors */
       if (
@@ -537,11 +531,17 @@ export class MCPClient {
               : `OAuth authorization URL not available: ${detail}`;
           this.emitError(message, 'auth');
           this.emitStateChange('FAILED');
+          
+          // Proactive Cleanup: This session has reached a terminal failure state. 
+          // We remove it now to ensure the database remains lean, bypassing the 
+          // automated lifecycle sweep.
           try {
             await storage.removeSession(this.identity, this.sessionId);
           } catch {
-            // best-effort cleanup
+            // Non-blocking: Proactive cleanup failures are suppressed to prioritize 
+            // the original error context.
           }
+          
           throw new Error(message);
         }
 
@@ -571,6 +571,19 @@ export class MCPClient {
       const errorMessage = error instanceof Error ? error.message : 'Connection failed';
       this.emitError(errorMessage, 'connection');
       this.emitStateChange('FAILED');
+
+      // Terminal Handshake Failure: only purge transient sessions. Active
+      // sessions may still hold valid credentials for a later reconnect.
+      try {
+        const existingSession = await storage.getSession(this.identity, this.sessionId);
+        if (!existingSession || existingSession.active !== true) {
+          await storage.removeSession(this.identity, this.sessionId);
+        }
+      } catch {
+        // Non-blocking: Cleanup is performed on a best-effort basis and should
+        // not interfere with the primary error propagation.
+      }
+
       throw error;
     }
   }
@@ -606,6 +619,7 @@ export class MCPClient {
 
     let lastError: unknown;
     let tokensExchanged = false;
+    let authenticatedStateEmitted = false;
 
     for (const currentType of transportsToTry) {
       const isLastAttempt = currentType === transportsToTry[transportsToTry.length - 1];
@@ -623,10 +637,11 @@ export class MCPClient {
           this.emitProgress(`Tokens already exchanged, skipping auth step for ${currentType}...`);
         }
 
-        /** Success! Update transport type */
-        this.transportType = currentType;
+        if (!authenticatedStateEmitted) {
+          this.emitStateChange('AUTHENTICATED');
+          authenticatedStateEmitted = true;
+        }
 
-        this.emitStateChange('AUTHENTICATED');
         this.emitProgress('Creating authenticated client...');
 
         this.client = new Client(
@@ -650,6 +665,9 @@ export class MCPClient {
         /** We explicitly try to connect with the transport we just auth'd with first */
         await this.client.connect(this.transport);
 
+        /** Connection succeeded — lock in the transport type */
+        this.transportType = currentType;
+
         this.emitStateChange('CONNECTED');
         // Update session with 12hr TTL after successful OAuth
         console.log(`[MCPClient] Updating session ${this.sessionId} to 12hr TTL (OAuth complete)`);

package/src/shared/meta-tools.ts

@@ -33,16 +33,18 @@ export function createSearchToolDefinition(): Tool {
   return {
     name: 'mcp_search_tool_bm25',
     description:
-      'Search the catalog of available tools using BM25 natural language ranking. ' +
-      'Returns tool names, descriptions, and server info. ' +
-      'Use this FIRST to find relevant tools before calling them. ' +
-      'Example queries: "database query", "send email", "github pull request".',
+      'Search the catalog of available tools. Returns tool names, descriptions, and server info. ' +
+      'Use this FIRST to find relevant tools before calling them.\n\n' +
+      'Query forms:\n' +
+      '- "select:Read,Edit,Grep" — fetch these exact tools by name\n' +
+      '- "notebook jupyter" — keyword search, up to limit best matches\n' +
+      '- "+slack send" — require "slack" in the name, rank by remaining terms',
     inputSchema: {
       type: 'object' as const,
       properties: {
         query: {
           type: 'string',
-          description: 'Natural language description of the capability you need.',
+          description: 'Query to find tools. Use "select:<tool_name>" for direct selection, or keywords to search. Prefix keywords with + to require them.',
         },
         limit: {
           type: 'number',
@@ -105,10 +107,10 @@ export function createGetSchemaToolDefinition(): Tool {
           type: 'string',
           description: 'The exact tool name returned by mcp_search_tool_bm25.',
         },
-        serverName: {
+        serverId: {
           type: 'string',
           description:
-            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+            'Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
         },
       },
       required: ['toolName'],
@@ -141,10 +143,10 @@ export function createExecuteToolDefinition(): Tool {
           type: 'string',
           description: 'The exact tool name from mcp_search_tool_bm25 results.',
         },
-        serverName: {
+        serverId: {
           type: 'string',
           description:
-            'Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
+            'Optional: The server ID provided in mcp_search_tool_bm25. Required if multiple tools have the same name.',
         },
         args: {
           type: 'object',
@@ -206,6 +208,53 @@ export async function executeMetaTool(
       const query = String(args.query ?? '');
       const limit = Math.min(Number(args.limit) || 5, 20);
 
+      // Fast path: Check for select: prefix
+      const selectMatch = query.match(/^select:(.+)$/i);
+      if (selectMatch) {
+        const requested = selectMatch[1]!
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean);
+
+        const found: any[] = [];
+        const errors: string[] = [];
+        
+        for (const requestedToolName of requested) {
+          const { tool, error } = resolveToolSchema(requestedToolName);
+          if (error) {
+            const errorMsg = error.content[0]?.type === 'text' ? error.content[0].text : 'Unknown error';
+            errors.push(`- **${requestedToolName}**: ${errorMsg}`);
+          } else if (tool) {
+            found.push(tool);
+          } else {
+            errors.push(`- **${requestedToolName}**: Tool not found. Try searching with mcp_search_tool_bm25.`);
+          }
+        }
+
+        const lines: string[] = [];
+
+        if (found.length > 0) {
+          lines.push(...found.map((t, i) =>
+            `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n   ${t.description}`
+          ));
+        }
+        
+        if (errors.length > 0) {
+          if (lines.length > 0) lines.push(""); // Add empty line spacing
+          lines.push("Errors resolving some tools:");
+          lines.push(...errors);
+        }
+
+        const text = lines.length > 0 
+          ? lines.join('\n') 
+          : `No tools found matching select query: ${requested.join(', ')}`;
+
+        return {
+          content: [{ type: 'text', text }],
+          isError: found.length === 0,
+        };
+      }
+
       const results = await router.searchTools(query, limit);
 
       const text = results.length === 0
@@ -213,7 +262,7 @@ export async function executeMetaTool(
         : results
             .map(
               (t, i) =>
-                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n` +
                 `   ${t.description}\n` +
                 `   Estimated tokens: ${t.estimatedTokens}`
             )
@@ -236,7 +285,7 @@ export async function executeMetaTool(
         : results
             .map(
               (t, i) =>
-                `${i + 1}. **${t.name}** (server: ${t.serverName})\n` +
+                `${i + 1}. **${t.name}** (server: ${t.serverName}, serverId: ${t.serverId})\n` +
                 `   ${t.description}\n` +
                 `   Estimated tokens: ${t.estimatedTokens}`
             )
@@ -250,7 +299,7 @@ export async function executeMetaTool(
 
     case 'mcp_get_tool_schema': {
       const name = String(args.toolName ?? '');
-      const namespace = String(args.serverName ?? '') || undefined;
+      const namespace = String(args.serverId ?? '') || undefined;
       const { tool, error } = resolveToolSchema(name, namespace);
 
       if (error) {
@@ -283,7 +332,7 @@ export async function executeMetaTool(
 
     case 'mcp_execute_tool': {
       const targetToolName = String(args.toolName ?? '');
-      const namespace = String(args.serverName ?? '') || undefined;
+      const namespace = String(args.serverId ?? '') || undefined;
       const toolArgs = (args.args as Record<string, unknown>) ?? {};
 
       if (!targetToolName) {

package/src/shared/tool-index.ts

@@ -24,6 +24,8 @@ export interface ToolSummary {
   description: string;
   /** Server that owns this tool */
   serverName: string;
+  /** Unique ID of the server */
+  serverId: string;
   /** Session the tool belongs to */
   sessionId: string;
   /** Estimated token cost of the full inputSchema */
@@ -33,6 +35,7 @@ export interface ToolSummary {
 /** A tool with routing metadata attached during indexing. */
 export interface IndexedTool extends Tool {
   sessionId: string;
+  serverId: string;
   serverName: string;
 }
 
@@ -177,6 +180,7 @@ export class ToolIndex {
         name: tool.name,
         description: tool.description ?? '',
         serverName: tool.serverName,
+        serverId: tool.serverId,
         sessionId: tool.sessionId,
         estimatedTokens,
       });
@@ -258,8 +262,55 @@ export class ToolIndex {
   async search(query: string, topK = 5): Promise<ToolSummary[]> {
     if (this.tools.size === 0) return [];
 
-    const queryLower = query.toLowerCase();
-    const queryTokens = this.tokenize(queryLower);
+    const queryLower = query.toLowerCase().trim();
+
+    // Fast path: Exact tool name match (supports duplicate names across servers)
+    const exactMatches = [...this.toolSummaries.values()].filter(
+      (summary) => summary.name.toLowerCase() === queryLower
+    );
+    if (exactMatches.length > 0) {
+      return exactMatches.slice(0, topK);
+    }
+
+    // Fast path: MCP prefix match (e.g. "mcp__github")
+    if (queryLower.startsWith('mcp__') && queryLower.length > 5) {
+      const prefixMatches = [...this.toolSummaries.values()]
+        .filter((t) => t.name.toLowerCase().startsWith(queryLower))
+        .slice(0, topK);
+      if (prefixMatches.length > 0) return prefixMatches;
+    }
+
+    const queryTermsRaw = queryLower.split(/\s+/).filter((t) => t.length > 0);
+    const requiredTerms: string[] = [];
+    const optionalTerms: string[] = [];
+
+    for (const term of queryTermsRaw) {
+      if (term.startsWith('+') && term.length > 1) {
+        requiredTerms.push(term.slice(1));
+      } else {
+        optionalTerms.push(term);
+      }
+    }
+
+    const allScoringTerms =
+      requiredTerms.length > 0 ? [...requiredTerms, ...optionalTerms] : queryTermsRaw;
+    const normalizedQueryText = allScoringTerms.join(' ').trim();
+    const queryTokens = this.tokenize(allScoringTerms.join(' '));
+
+    // Pre-filter: only keep documents that contain ALL required terms
+    const candidateKeys = new Set<string>();
+    for (const docKey of this.toolSummaries.keys()) {
+      if (requiredTerms.length > 0) {
+        const text = this.searchTexts.get(docKey) || '';
+        const summary = this.toolSummaries.get(docKey)!;
+        const nameLower = summary.name.toLowerCase();
+        const matchesAll = requiredTerms.every(
+          (term) => text.includes(term) || nameLower.includes(term)
+        );
+        if (!matchesAll) continue;
+      }
+      candidateKeys.add(docKey);
+    }
 
     // 1. Keyword scores (BM25)
     const keywordScores = new Map<string, number>();
@@ -267,7 +318,12 @@ export class ToolIndex {
     const k1 = 1.2;
     const b = 0.75;
 
-    for (const [docKey, docTf] of this.tfVectors) {
+    for (const docKey of candidateKeys) {
+      const docTf = this.tfVectors.get(docKey);
+      if (!docTf) continue;
+      
+      const summary = this.toolSummaries.get(docKey)!;
+
       let score = 0;
       const docLen = this.docLengths.get(docKey) ?? 0;
 
@@ -276,16 +332,30 @@ export class ToolIndex {
         if (tfVal === 0) continue;
 
         const idf = this.idf.get(tok) ?? 0;
-
         // BM25 formula:
         // score = idf * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLen / avgDocLength)))
         const numerator = tfVal * (k1 + 1);
         const denominator = tfVal + k1 * (1 - b + b * (docLen / this.avgDocLength));
-        
+
         score += idf * (numerator / denominator);
       }
 
-      keywordScores.set(docKey, score);
+      // Name heuristics: give massive boosts for exact server/tool name matches
+      const serverLower = (summary.serverName || summary.serverId || '').toLowerCase();
+      const toolLower = summary.name.toLowerCase();
+
+      for (const term of allScoringTerms) {
+        if (serverLower.includes(term)) {
+          score += 10;
+        }
+        if (toolLower.includes(term)) {
+          score += 5;
+        }
+      }
+
+      if (score > 0) {
+        keywordScores.set(docKey, score);
+      }
     }
 
     // 2. Embedding scores (optional)
@@ -293,11 +363,14 @@ export class ToolIndex {
 
     if (this.options.embedFn && this.embeddings.size > 0) {
       try {
-        const [queryEmbedding] = await this.options.embedFn([queryLower]);
+        const [queryEmbedding] = await this.options.embedFn([normalizedQueryText]);
         if (queryEmbedding) {
           embeddingScores = new Map();
-          for (const [docKey, vec] of this.embeddings) {
-            embeddingScores.set(docKey, this.cosineSimilarity(queryEmbedding, vec));
+          for (const docKey of candidateKeys) {
+            const vec = this.embeddings.get(docKey);
+            if (vec) {
+              embeddingScores.set(docKey, this.cosineSimilarity(queryEmbedding, vec));
+            }
           }
         }
       } catch {
@@ -309,7 +382,7 @@ export class ToolIndex {
     const kw = this.options.keywordWeight;
     const finalScores: Array<{ docKey: string; score: number }> = [];
 
-    for (const docKey of this.toolSummaries.keys()) {
+    for (const docKey of candidateKeys) {
       const kwScore = keywordScores.get(docKey) ?? 0;
       const embScore = embeddingScores?.get(docKey) ?? 0;
 
@@ -389,7 +462,7 @@ export class ToolIndex {
     const list = this.tools.get(name) ?? [];
     if (!namespace) return list;
 
-    return list.filter((t) => t.sessionId === namespace || t.serverName === namespace);
+    return list.filter((t) => t.sessionId === namespace || t.serverId === namespace);
   }
 
   /** All indexed tool names. */
@@ -463,7 +536,7 @@ export class ToolIndex {
   }
 
   private getDocumentKey(tool: IndexedTool): string {
-    return `${tool.sessionId}::${tool.serverName}::${tool.name}`;
+    return `${tool.sessionId}::${tool.serverId}::${tool.name}`;
   }
 
   /** Simple whitespace + camelCase + snake_case tokenizer. */

package/src/shared/tool-router.ts

@@ -219,10 +219,10 @@ export class ToolRouter {
     if (matches.length === 0) return undefined;
 
     if (matches.length > 1) {
-      const servers = matches.map((m) => m.serverName).join(', ');
+      const servers = matches.map((m) => m.serverId).join(', ');
       throw new Error(
         `Tool "${toolName}" is provided by multiple servers: [${servers}]. ` +
-          `Please specify the desired "serverName" as a namespace.`
+          `Please specify the desired "serverId" as a namespace.`
       );
     }
 
@@ -372,6 +372,7 @@ export class ToolRouter {
         for (const tool of tools) {
           result.push({
             ...tool,
+            serverId,
             serverName: serverName,
             sessionId,
           });
@@ -409,20 +410,20 @@ export class ToolRouter {
         });
       }
     } else {
-      // Auto-group by server name
+      // Auto-group by server ID
       const serverTools = new Map<string, string[]>();
       for (const tool of this.allTools) {
-        const group = tool.serverName;
+        const group = tool.serverId;
         if (!serverTools.has(group)) {
           serverTools.set(group, []);
         }
         serverTools.get(group)!.push(tool.name);
       }
 
-      for (const [serverName, tools] of serverTools) {
-        this.groupsMap.set(serverName, {
+      for (const [serverId, tools] of serverTools) {
+        this.groupsMap.set(serverId, {
           tools,
-          active: this.activeGroups.size === 0 || this.activeGroups.has(serverName),
+          active: this.activeGroups.size === 0 || this.activeGroups.has(serverId),
         });
       }
     }

package/supabase/migrations/20260421010000_add_session_cleanup_cron.sql

@@ -0,0 +1,32 @@
+-- Enable the pg_cron extension (available on all Supabase plans).
+-- This is idempotent and safe to run multiple times.
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Stage 1: Short-term Transient Purge (every 5 minutes)
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Targets sessions that are NOT active (failed connections, abandoned OAuth
+-- flows, mid-flow errors) whose TTL has expired. Active sessions are explicitly
+-- excluded from this sweep to preserve automation credentials.
+--
+-- The idx_mcp_sessions_expires_at index ensures this is a fast indexed scan.
+SELECT cron.schedule(
+    'cleanup-transient-sessions',
+    '*/5 * * * *',
+    $$DELETE FROM public.mcp_sessions WHERE expires_at < now() AND active IS NOT TRUE;$$
+);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Stage 2: Long-term Dormancy Eviction (daily at midnight UTC)
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Safety net for sessions that were successfully established (active = true)
+-- but have been completely untouched for 30+ days. This prevents "active"
+-- records from persisting indefinitely if they are genuinely abandoned.
+SELECT cron.schedule(
+    'cleanup-dormant-sessions',
+    '0 0 * * *',
+    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+);
+
+-- Add a comment on the extension for visibility in Supabase Dashboard
+COMMENT ON EXTENSION pg_cron IS 'Automated Session Lifecycle Management.';