@mcp-ts/sdk 2.4.0 → 2.4.1

package/migrations/v2.3.4/neon/20260513010000_install_mcp_sessions.sql

@@ -0,0 +1,69 @@
+-- Create the mcp_sessions table for Neon Postgres.
+-- Run this with an owner/admin role, then grant app access with the least-privilege SQL below.
+
+CREATE TABLE IF NOT EXISTS public.mcp_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL UNIQUE,
+    user_id TEXT NOT NULL,
+    server_id TEXT,
+    server_name TEXT,
+    server_url TEXT NOT NULL,
+    transport_type TEXT NOT NULL,
+    callback_url TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at TIMESTAMPTZ NOT NULL,
+    active BOOLEAN DEFAULT false,
+    headers JSONB,
+    client_information JSONB,
+    tokens JSONB,
+    code_verifier TEXT,
+    client_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+
+CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_mcp_sessions_updated_at ON public.mcp_sessions;
+
+CREATE TRIGGER trg_mcp_sessions_updated_at
+BEFORE UPDATE ON public.mcp_sessions
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
+-- Optional production configuration:
+-- Create a dedicated app role and use its credentials in NEON_DATABASE_URL.
+-- Replace neondb and the password before running.
+--
+-- CREATE ROLE mcp_service_role LOGIN PASSWORD 'replace-with-a-strong-password';
+-- GRANT CONNECT ON DATABASE neondb TO mcp_service_role;
+-- GRANT USAGE ON SCHEMA public TO mcp_service_role;
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_sessions TO mcp_service_role;
+-- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
+
+-- Optional RLS configuration:
+-- Uncomment and run this block after creating mcp_service_role if you want
+-- to enforce access through Row Level Security for the dedicated app role.
+--
+-- REVOKE ALL ON public.mcp_sessions FROM PUBLIC;
+-- REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM PUBLIC;
+--
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_sessions TO mcp_service_role;
+-- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
+--
+-- ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+--
+-- CREATE POLICY mcp_service_role_full_access
+-- ON public.mcp_sessions
+-- FOR ALL
+-- TO mcp_service_role
+-- USING (true)
+-- WITH CHECK (true);

package/migrations/v2.3.4/neon/20260513020000_add_session_cleanup_cron.sql

@@ -0,0 +1,35 @@
+-- Optional Neon pg_cron cleanup jobs.
+--
+-- Neon pg_cron requires endpoint-level setup before this migration can run:
+-- configure cron.database_name for your compute endpoint, restart the compute,
+-- then install/schedule jobs from the target database.
+--
+-- If pg_cron is not enabled for your Neon project, skip this migration and run
+-- storage.cleanupExpiredSessions() from your application scheduler instead.
+
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+
+-- Keep reruns idempotent without NOTICE noise.
+SELECT cron.unschedule(jobname)
+FROM cron.job
+WHERE jobname IN (
+  'mcp-cleanup-transient-sessions',
+  'mcp-cleanup-dormant-sessions'
+);
+
+-- Stage 1: Short-term Transient Purge (every 5 minutes)
+-- Removes failed connections, abandoned OAuth flows, and other inactive
+-- sessions whose TTL has expired.
+SELECT cron.schedule(
+    'mcp-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)
+-- Removes active sessions that have not been touched for 30+ days.
+SELECT cron.schedule(
+    'mcp-cleanup-dormant-sessions',
+    '0 0 * * *',
+    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+);

package/migrations/v2.3.4/supabase/20260330195700_install_mcp_sessions.sql

@@ -0,0 +1,82 @@
+-- Create the mcp_sessions table
+CREATE TABLE IF NOT EXISTS public.mcp_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL UNIQUE,
+    user_id TEXT NOT NULL, -- Will store the application user's ID
+    server_id TEXT,
+    server_name TEXT,
+    server_url TEXT NOT NULL,
+    transport_type TEXT NOT NULL,
+    callback_url TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at TIMESTAMPTZ NOT NULL,
+    active BOOLEAN DEFAULT false,
+    headers JSONB,
+    client_information JSONB,
+    tokens JSONB,
+    code_verifier TEXT,
+    client_id TEXT
+);
+
+-- Add an index on user_id for faster lookups
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
+-- Add an index on expires_at to speed up the cleanup job
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+
+-- Trigger to automatically update the 'updated_at' column
+CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_mcp_sessions_updated_at ON public.mcp_sessions;
+CREATE TRIGGER trg_mcp_sessions_updated_at
+BEFORE UPDATE ON public.mcp_sessions
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
+-- Enable Row Level Security (RLS)
+ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+
+-- Policy 1: Users can read their own sessions
+CREATE POLICY "Users can view their own sessions"
+ON public.mcp_sessions
+FOR SELECT
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);
+
+-- Policy 2: Users can insert their own sessions
+CREATE POLICY "Users can insert their own sessions"
+ON public.mcp_sessions
+FOR INSERT
+TO authenticated
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
+-- Policy 3: Users can update their own sessions
+CREATE POLICY "Users can update their own sessions"
+ON public.mcp_sessions
+FOR UPDATE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+)
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
+-- Policy 4: Users can delete their own sessions
+CREATE POLICY "Users can delete their own sessions"
+ON public.mcp_sessions
+FOR DELETE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);

package/migrations/v2.3.4/supabase/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.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "publishConfig": {
     "access": "public"
   },

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

@@ -356,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)
@@ -606,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

@@ -100,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
@@ -107,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
@@ -197,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.
      *
@@ -213,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 = [];
     }
 }

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

@@ -242,7 +242,7 @@ export class MCPClient {
        * Observation: SDK 1.24.0+ connections may hang indefinitely in some environments.
        * This wrapper enforces a timeout and properly uses AbortController to unblock the request.
        */
-      fetch: (url: RequestInfo | URL, init?: RequestInit) => {
+      fetch: async (url: RequestInfo | URL, init?: RequestInit) => {
         const timeout = 30000;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), timeout);
@@ -251,7 +251,20 @@ export class MCPClient {
           (AbortSignal.any ? AbortSignal.any([init.signal, controller.signal]) : controller.signal) :
           controller.signal;
 
-        return fetch(url, { ...init, signal }).finally(() => clearTimeout(timeoutId));
+        try {
+          const response = await fetch(url, { ...init, signal });
+          
+          const hasSessionHeader = init?.headers && new Headers(init.headers as HeadersInit).has('mcp-session-id');
+
+          if (response.status === 404 && hasSessionHeader) {
+            this.client = null;
+            throw new Error("MCP_SESSION_EXPIRED: Downstream session was not found on the server.");
+          }
+
+          return response;
+        } finally {
+          clearTimeout(timeoutId);
+        }
       }
     };
 
@@ -497,6 +510,27 @@ export class MCPClient {
    * @throws {Error} When connection fails for other reasons
    */
   async connect(): Promise<void> {
+    // Re-entry guard: if a previous SDK Client is still attached to a transport
+    // (e.g. a stale session from a prior connect() call on the same MCPClient
+    // instance), close and detach it before proceeding. The MCP SDK client will
+    // throw if asked to connect while a transport is already attached, and the
+    // stale transport would send an expired mcp-session-id to the remote server
+    // causing "Session not found. Reconnect without session header." errors.
+    //
+    // We also null out this.client so that initialize() creates a fresh Client
+    // instance with a clean transport slot, rather than reusing the old one.
+    // The oauthProvider is intentionally preserved — OAuth tokens remain valid
+    // across reconnects; only the transport session needs to be renegotiated.
+    if (this.client?.transport) {
+      this.transport = null;
+      try {
+        await this.client.close();
+      } catch {
+        // Closing a transport that may have already failed is best-effort.
+      }
+      this.client = null;
+    }
+
     await this.initialize();
 
     if (!this.client || !this.oauthProvider) {
@@ -997,7 +1031,7 @@ export class MCPClient {
     }
 
     await sessions.delete(this.userId, this.sessionId);
-    this.disconnect();
+    await this.disconnect();
   }
 
   /**
@@ -1009,10 +1043,29 @@ export class MCPClient {
   }
 
   /**
-   * Disconnects from the MCP server and cleans up resources
-   * Does not remove session from Redis - use clearSession() for that
+   * Disconnects from the MCP server and cleans up resources.
+   * Does not remove session from Redis — use clearSession() for that.
+   *
+   * For Streamable HTTP sessions, sends an HTTP DELETE to the MCP endpoint
+   * before closing, as recommended by the MCP Streamable HTTP spec
+   * (section "Session Management", rule 5). This is best-effort — errors
+   * (e.g. server already restarted, 404/405 responses) are silently ignored.
    */
-  disconnect(reason?: string): void {
+  async disconnect(): Promise<void> {
+    // Per the MCP Streamable HTTP spec (2025-11-25), clients SHOULD send an
+    // HTTP DELETE with the mcp-session-id header when they no longer need a
+    // session. The server MAY respond with 405 if it doesn't support explicit
+    // termination — terminateSession() handles that gracefully.
+    // SSEClientTransport has no session concept, so we guard with instanceof.
+    if (this.transport instanceof StreamableHTTPClientTransport) {
+      try {
+        await this.transport.terminateSession();
+      } catch {
+        // Best-effort: server may be unreachable or may have already expired
+        // the session. Either way, we proceed with local cleanup.
+      }
+    }
+
     if (this.client) {
       this.client.close();
     }
@@ -1026,7 +1079,6 @@ export class MCPClient {
         type: 'disconnected',
         sessionId: this.sessionId,
         serverId: this.serverId,
-        reason,
         timestamp: Date.now(),
       });
 
@@ -1036,9 +1088,7 @@ export class MCPClient {
         message: `Disconnected from ${this.serverId}`,
         sessionId: this.sessionId,
         serverId: this.serverId,
-        payload: {
-          reason: reason || 'unknown',
-        },
+        payload: {},
         timestamp: Date.now(),
         id: nanoid(),
       });

package/src/shared/events.ts

@@ -121,7 +121,6 @@ export type McpConnectionEvent =
     type: 'disconnected';
     sessionId: string;
     serverId: string;
-    reason?: string;
     timestamp: number;
   }
   | {