@mcp-ts/sdk 1.3.7 → 1.3.10

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

@@ -1,641 +1,669 @@
-/**
- * useMcp React Hook
- * Manages MCP connections with SSE-based real-time updates
- * Based on Cloudflare's agents pattern
- */
-
-import { useEffect, useRef, useState, useCallback } from 'react';
-import { SSEClient, type SSEClientOptions } from '../core/sse-client';
-import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
-import type {
-  ToolInfo,
-  FinishAuthResult,
-  ListToolsRpcResult,
-  ListPromptsResult,
-  ListResourcesResult,
-  SessionInfo,
-} from '../../shared/types';
-
-export interface UseMcpOptions {
-  /**
-   * SSE endpoint URL
-   */
-  url: string;
-
-  /**
-   * User/Client identifier
-   */
-  identity: string;
-
-  /**
-   * Optional auth token
-   */
-  authToken?: string;
-
-  /**
-   * Auto-connect on mount
-   * @default true
-   */
-  autoConnect?: boolean;
-
-  /**
-   * Auto-initialize sessions on mount
-   * @default true
-   */
-  autoInitialize?: boolean;
-
-  /**
-   * Connection event callback
-   */
-  onConnectionEvent?: (event: McpConnectionEvent) => void;
-
-  /**
-   * Debug logging callback
-   */
-  onLog?: (level: string, message: string, metadata?: Record<string, unknown>) => void;
-  /**
-   * Optional callback to handle OAuth redirects (e.g. for popup flow)
-   * If provided, this will be called instead of window.location.href assignment
-   */
-  onRedirect?: (url: string) => void;
-
-  /**
-   * Request timeout in milliseconds
-   * @default 60000
-   */
-  requestTimeout?: number;
-
-  /**
-   * Enable client debug logs.
-   * @default false
-   */
-  debug?: boolean;
-
-}
-
-export interface McpConnection {
-  sessionId: string;
-  serverId: string;
-  serverName: string;
-  serverUrl?: string;
-  transport?: string;
-  state: McpConnectionState;
-  tools: ToolInfo[];
-  authUrl?: string;
-  error?: string;
-  createdAt?: Date;
-}
-
-export interface McpClient {
-  /**
-   * All connections
-   */
-  connections: McpConnection[];
-
-  /**
-   * SSE connection status
-   */
-  status: 'connecting' | 'connected' | 'disconnected' | 'error';
-
-  /**
-   * Whether initializing
-   */
-  isInitializing: boolean;
-
-  /**
-   * Connect to an MCP server
-   */
-  connect: (params: {
-    serverId: string;
-    serverName: string;
-    serverUrl: string;
-    callbackUrl: string;
-    transportType?: 'sse' | 'streamable_http';
-  }) => Promise<string>;
-
-  /**
-   * Disconnect from an MCP server
-   */
-  disconnect: (sessionId: string) => Promise<void>;
-
-  /**
-   * Get connection by session ID
-   */
-  getConnection: (sessionId: string) => McpConnection | undefined;
-
-  /**
-   * Get connection by server ID
-   */
-  getConnectionByServerId: (serverId: string) => McpConnection | undefined;
-
-  /**
-   * Check if server is connected
-   */
-  isServerConnected: (serverId: string) => boolean;
-
-  /**
-   * Get tools for a session
-   */
-  getTools: (sessionId: string) => ToolInfo[];
-
-  /**
-   * Refresh all connections
-   */
-  refresh: () => Promise<void>;
-
-  /**
-   * Manually connect SSE
-   */
-  connectSSE: () => void;
-
-  /**
-   * Manually disconnect SSE
-   */
-  disconnectSSE: () => void;
-
-  /**
-   * Complete OAuth authorization
-   */
-  finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
-
-  /**
-   * Explicitly resume OAuth flow for an existing session
-   */
-  resumeAuth: (sessionId: string) => Promise<void>;
-
-  /**
-   * Call a tool from a session
-   */
-  callTool: (
-    sessionId: string,
-    toolName: string,
-    toolArgs: Record<string, unknown>
-  ) => Promise<unknown>;
-
-  /**
-   * List available tools for a session
-   */
-  listTools: (sessionId: string) => Promise<ListToolsRpcResult>;
-
-  /**
-   * List available prompts for a session
-   */
-  listPrompts: (sessionId: string) => Promise<ListPromptsResult>;
-
-  /**
-   * Get a specific prompt with arguments
-   */
-  getPrompt: (sessionId: string, name: string, args?: Record<string, string>) => Promise<unknown>;
-
-  /**
-   * List available resources for a session
-   */
-  listResources: (sessionId: string) => Promise<ListResourcesResult>;
-
-  /**
-   * Read a specific resource
-   */
-  readResource: (sessionId: string, uri: string) => Promise<unknown>;
-
-  /**
-   * Access the underlying SSEClient instance (for advanced usage like AppHost)
-   */
-  sseClient: SSEClient | null;
-}
-
-/**
- * React hook for MCP connection management with SSE
- */
-export function useMcp(options: UseMcpOptions): McpClient {
-  const {
-    url,
-    identity,
-    authToken,
-    autoConnect = true,
-    autoInitialize = true,
-    onConnectionEvent,
-    onLog,
-    onRedirect,
-  } = options;
-
-  const clientRef = useRef<SSEClient | null>(null);
-  const isMountedRef = useRef(true);
-  const suppressAuthRedirectSessionsRef = useRef<Set<string>>(new Set());
-
-  const [connections, setConnections] = useState<McpConnection[]>([]);
-  const [status, setStatus] = useState<'connecting' | 'connected' | 'disconnected' | 'error'>(
-    'disconnected'
-  );
-  const [isInitializing, setIsInitializing] = useState(false);
-
-  /**
-   * Initialize SSE client
-   */
-  useEffect(() => {
-    isMountedRef.current = true;
-
-    const clientOptions: SSEClientOptions = {
-      url,
-      identity,
-      authToken,
-      onConnectionEvent: (event) => {
-        // Update local state based on event
-        updateConnectionsFromEvent(event);
-
-        // Call user callback
-        onConnectionEvent?.(event);
-      },
-      onObservabilityEvent: (event) => {
-        onLog?.(event.level || 'info', event.message || event.displayMessage || 'No message', event.metadata);
-      },
-      onStatusChange: (newStatus) => {
-        if (isMountedRef.current) {
-          setStatus(newStatus);
-        }
-      },
-      debug: options.debug,
-    };
-
-    const client = new SSEClient(clientOptions);
-    clientRef.current = client;
-
-    if (autoConnect) {
-      client.connect();
-
-      if (autoInitialize) {
-        loadSessions();
-      }
-    }
-
-    return () => {
-      isMountedRef.current = false;
-      client.disconnect();
-    };
-  }, [url, identity, authToken, autoConnect, autoInitialize]);
-
-  /**
-   * Update connections based on event
-   */
-  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';
-
-    setConnections((prev: McpConnection[]) => {
-      switch (event.type) {
-        case 'state_changed': {
-          const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
-          if (existing) {
-            // 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
-                : event.state;
-
-            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
-              } : c
-            );
-          } else {
-            // Fix: Don't add back disconnected sessions that were just removed
-            if (event.state === 'DISCONNECTED') {
-              return prev;
-            }
-
-            return [
-              ...prev,
-              {
-                sessionId: event.sessionId,
-                serverId: event.serverId,
-                serverName: event.serverName,
-                serverUrl: event.serverUrl,
-                state: event.state,
-                createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
-                tools: [],
-              },
-            ];
-          }
-        }
-
-        case 'tools_discovered': {
-          // Preload UI resources for instant loading when tools are discovered
-          if (clientRef.current && event.tools?.length) {
-            clientRef.current.preloadToolUiResources(event.sessionId, event.tools);
-          }
-
-          return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY' } : c
-          );
-        }
-
-        case 'auth_required': {
-          // Handle OAuth redirect
-          if (event.authUrl) {
-            onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: event.authUrl });
-
-            // Suppress redirects/popups for auto-restore on page load.
-            if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
-              if (onRedirect) {
-                onRedirect(event.authUrl);
-              } else if (typeof window !== 'undefined') {
-                window.location.href = event.authUrl;
-              }
-            }
-          }
-          return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: event.authUrl } : c
-          );
-        }
-
-        case 'error': {
-          return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, state: 'FAILED', error: event.error } : c
-          );
-        }
-
-        case 'disconnected': {
-          return prev.filter((c: McpConnection) => c.sessionId !== event.sessionId);
-        }
-
-        default:
-          return prev;
-      }
-    });
-  }, [onLog, onRedirect]);
-
-  /**
-   * Load sessions from server
-   */
-  const loadSessions = useCallback(async () => {
-    if (!clientRef.current) return;
-
-    try {
-      setIsInitializing(true);
-
-      const result = await clientRef.current.getSessions();
-      const sessions = result.sessions || [];
-
-      // Initialize connections
-      if (isMountedRef.current) {
-        setConnections(
-          sessions.map((s: SessionInfo) => ({
-            sessionId: s.sessionId,
-            serverId: s.serverId ?? 'unknown',
-            serverName: s.serverName ?? 'Unknown Server',
-            serverUrl: s.serverUrl,
-            transport: s.transport,
-            state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
-            createdAt: new Date(s.createdAt),
-            tools: [],
-          }))
-        );
-      }
-
-      // Validate each session in parallel
-      await Promise.all(
-        sessions.map(async (session: SessionInfo) => {
-          if (clientRef.current) {
-            try {
-              // Pending auth sessions should not auto-trigger popup/redirect on reload.
-              if (session.active === false) {
-                return;
-              }
-              suppressAuthRedirectSessionsRef.current.add(session.sessionId);
-              await clientRef.current.restoreSession(session.sessionId);
-            } catch (error) {
-              console.error(`[useMcp] Failed to validate session ${session.sessionId}:`, error);
-            } finally {
-              suppressAuthRedirectSessionsRef.current.delete(session.sessionId);
-            }
-          }
-        })
-      );
-    } catch (error) {
-      console.error('[useMcp] Failed to load sessions:', error);
-      onLog?.('error', 'Failed to load sessions', { error });
-    } finally {
-      if (isMountedRef.current) {
-        setIsInitializing(false);
-      }
-    }
-  }, [onLog]);
-
-  /**
-   * Connect to an MCP server
-   */
-  const connect = useCallback(
-    async (params: {
-      serverId: string;
-      serverName: string;
-      serverUrl: string;
-      callbackUrl: string;
-      transportType?: 'sse' | 'streamable_http';
-    }): Promise<string> => {
-      if (!clientRef.current) {
-        throw new Error('SSE client not initialized');
-      }
-
-      const result = await clientRef.current.connectToServer(params);
-      return result.sessionId;
-    },
-    []
-  );
-
-  /**
-   * Disconnect from an MCP server
-   */
-  const disconnect = useCallback(async (sessionId: string): Promise<void> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    await clientRef.current.disconnectFromServer(sessionId);
-
-    // Remove from local state
-    if (isMountedRef.current) {
-      setConnections((prev: McpConnection[]) => prev.filter((c: McpConnection) => c.sessionId !== sessionId));
-    }
-  }, []);
-
-  /**
-   * Refresh all connections
-   */
-  const refresh = useCallback(async () => {
-    await loadSessions();
-  }, [loadSessions]);
-
-  /**
-   * Manually connect SSE
-   */
-  const connectSSE = useCallback(() => {
-    clientRef.current?.connect();
-  }, []);
-
-  /**
-   * Manually disconnect SSE
-   */
-  const disconnectSSE = useCallback(() => {
-    clientRef.current?.disconnect();
-  }, []);
-
-  /**
-   * Complete OAuth authorization
-   */
-  const finishAuth = useCallback(async (sessionId: string, code: string): Promise<FinishAuthResult> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    return await clientRef.current.finishAuth(sessionId, code);
-  }, []);
-
-  /**
-   * Explicit user action to resume OAuth for an existing pending session.
-   */
-  const resumeAuth = useCallback(async (sessionId: string): Promise<void> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-    // Ensure this attempt is not suppressed as background restore.
-    suppressAuthRedirectSessionsRef.current.delete(sessionId);
-    await clientRef.current.restoreSession(sessionId);
-  }, []);
-
-  /**
-   * Call a tool
-   */
-  const callTool = useCallback(
-    async (
-      sessionId: string,
-      toolName: string,
-      toolArgs: Record<string, unknown>
-    ): Promise<unknown> => {
-      if (!clientRef.current) {
-        throw new Error('SSE client not initialized');
-      }
-
-      return await clientRef.current.callTool(sessionId, toolName, toolArgs);
-    },
-    []
-  );
-
-  /**
-   * List tools (refresh tool list)
-   */
-  const listTools = useCallback(async (sessionId: string): Promise<ListToolsRpcResult> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    return await clientRef.current.listTools(sessionId);
-  }, []);
-
-  /**
-   * List prompts
-   */
-  const listPrompts = useCallback(async (sessionId: string): Promise<ListPromptsResult> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    return await clientRef.current.listPrompts(sessionId);
-  }, []);
-
-  /**
-   * Get a specific prompt
-   */
-  const getPrompt = useCallback(
-    async (sessionId: string, name: string, args?: Record<string, string>): Promise<unknown> => {
-      if (!clientRef.current) {
-        throw new Error('SSE client not initialized');
-      }
-
-      return await clientRef.current.getPrompt(sessionId, name, args);
-    },
-    []
-  );
-
-  /**
-   * List resources
-   */
-  const listResources = useCallback(async (sessionId: string): Promise<ListResourcesResult> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    return await clientRef.current.listResources(sessionId);
-  }, []);
-
-  /**
-   * Read a specific resource
-   */
-  const readResource = useCallback(async (sessionId: string, uri: string): Promise<unknown> => {
-    if (!clientRef.current) {
-      throw new Error('SSE client not initialized');
-    }
-
-    return await clientRef.current.readResource(sessionId, uri);
-  }, []);
-
-  // Utility functions
-  const getConnection = useCallback(
-    (sessionId: string) => connections.find((c: McpConnection) => c.sessionId === sessionId),
-    [connections]
-  );
-
-  const getConnectionByServerId = useCallback(
-    (serverId: string) => connections.find((c: McpConnection) => c.serverId === serverId),
-    [connections]
-  );
-
-  const isServerConnected = useCallback(
-    (serverId: string) => {
-      const conn = getConnectionByServerId(serverId);
-      return conn ? conn.state === 'CONNECTED' || conn.state === 'DISCOVERING' || conn.state === 'READY' : false;
-    },
-    [getConnectionByServerId]
-  );
-
-  const getTools = useCallback(
-    (sessionId: string) => {
-      const conn = getConnection(sessionId);
-      return conn?.tools || [];
-    },
-    [getConnection]
-  );
-
-  return {
-    connections,
-    status,
-    isInitializing,
-    connect,
-    disconnect,
-    getConnection,
-    getConnectionByServerId,
-    isServerConnected,
-    getTools,
-    refresh,
-    connectSSE,
-    disconnectSSE,
-    finishAuth,
-    resumeAuth,
-    callTool,
-    listTools,
-    listPrompts,
-    getPrompt,
-    listResources,
-    readResource,
-    sseClient: clientRef.current,
-  };
-}
+/**
+ * useMcp React Hook
+ * Manages MCP connections with SSE-based real-time updates
+ * Based on Cloudflare's agents pattern
+ */
+
+import { useEffect, useRef, useState, useCallback, useMemo } from 'react';
+import { SSEClient, type SSEClientOptions } from '../core/sse-client';
+import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
+import type {
+  ToolInfo,
+  FinishAuthResult,
+  ListToolsRpcResult,
+  ListPromptsResult,
+  ListResourcesResult,
+  SessionInfo,
+} from '../../shared/types';
+
+export interface UseMcpOptions {
+  /**
+   * SSE endpoint URL
+   */
+  url: string;
+
+  /**
+   * User/Client identifier
+   */
+  identity: string;
+
+  /**
+   * Optional auth token
+   */
+  authToken?: string;
+
+  /**
+   * Auto-connect on mount
+   * @default true
+   */
+  autoConnect?: boolean;
+
+  /**
+   * Auto-initialize sessions on mount
+   * @default true
+   */
+  autoInitialize?: boolean;
+
+  /**
+   * Connection event callback
+   */
+  onConnectionEvent?: (event: McpConnectionEvent) => void;
+
+  /**
+   * Debug logging callback
+   */
+  onLog?: (level: string, message: string, metadata?: Record<string, unknown>) => void;
+  /**
+   * Optional callback to handle OAuth redirects (e.g. for popup flow)
+   * If provided, this will be called instead of window.location.href assignment
+   */
+  onRedirect?: (url: string) => void;
+
+  /**
+   * Request timeout in milliseconds
+   * @default 60000
+   */
+  requestTimeout?: number;
+
+  /**
+   * Enable client debug logs.
+   * @default false
+   */
+  debug?: boolean;
+
+}
+
+export interface McpConnection {
+  sessionId: string;
+  serverId: string;
+  serverName: string;
+  serverUrl?: string;
+  transport?: string;
+  state: McpConnectionState;
+  tools: ToolInfo[];
+  authUrl?: string;
+  error?: string;
+  createdAt?: Date;
+}
+
+export interface McpClient {
+  /**
+   * All connections
+   */
+  connections: McpConnection[];
+
+  /**
+   * SSE connection status
+   */
+  status: 'connecting' | 'connected' | 'disconnected' | 'error';
+
+  /**
+   * Whether initializing
+   */
+  isInitializing: boolean;
+
+  /**
+   * Connect to an MCP server
+   */
+  connect: (params: {
+    serverId: string;
+    serverName: string;
+    serverUrl: string;
+    callbackUrl: string;
+    transportType?: 'sse' | 'streamable_http';
+  }) => Promise<string>;
+
+  /**
+   * Disconnect from an MCP server
+   */
+  disconnect: (sessionId: string) => Promise<void>;
+
+  /**
+   * Get connection by session ID
+   */
+  getConnection: (sessionId: string) => McpConnection | undefined;
+
+  /**
+   * Get connection by server ID
+   */
+  getConnectionByServerId: (serverId: string) => McpConnection | undefined;
+
+  /**
+   * Check if server is connected
+   */
+  isServerConnected: (serverId: string) => boolean;
+
+  /**
+   * Get tools for a session
+   */
+  getTools: (sessionId: string) => ToolInfo[];
+
+  /**
+   * Refresh all connections
+   */
+  refresh: () => Promise<void>;
+
+  /**
+   * Manually connect SSE
+   */
+  connectSSE: () => void;
+
+  /**
+   * Manually disconnect SSE
+   */
+  disconnectSSE: () => void;
+
+  /**
+   * Complete OAuth authorization
+   */
+  finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
+
+  /**
+   * Explicitly resume OAuth flow for an existing session
+   */
+  resumeAuth: (sessionId: string) => Promise<void>;
+
+  /**
+   * Call a tool from a session
+   */
+  callTool: (
+    sessionId: string,
+    toolName: string,
+    toolArgs: Record<string, unknown>
+  ) => Promise<unknown>;
+
+  /**
+   * List available tools for a session
+   */
+  listTools: (sessionId: string) => Promise<ListToolsRpcResult>;
+
+  /**
+   * List available prompts for a session
+   */
+  listPrompts: (sessionId: string) => Promise<ListPromptsResult>;
+
+  /**
+   * Get a specific prompt with arguments
+   */
+  getPrompt: (sessionId: string, name: string, args?: Record<string, string>) => Promise<unknown>;
+
+  /**
+   * List available resources for a session
+   */
+  listResources: (sessionId: string) => Promise<ListResourcesResult>;
+
+  /**
+   * Read a specific resource
+   */
+  readResource: (sessionId: string, uri: string) => Promise<unknown>;
+
+  /**
+   * Access the underlying SSEClient instance (for advanced usage like AppHost)
+   */
+  sseClient: SSEClient | null;
+}
+
+/**
+ * React hook for MCP connection management with SSE
+ */
+export function useMcp(options: UseMcpOptions): McpClient {
+  const {
+    url,
+    identity,
+    authToken,
+    autoConnect = true,
+    autoInitialize = true,
+    onConnectionEvent,
+    onLog,
+    onRedirect,
+  } = options;
+
+  const clientRef = useRef<SSEClient | null>(null);
+  const isMountedRef = useRef(true);
+  const suppressAuthRedirectSessionsRef = useRef<Set<string>>(new Set());
+
+  const [connections, setConnections] = useState<McpConnection[]>([]);
+  const [status, setStatus] = useState<'connecting' | 'connected' | 'disconnected' | 'error'>(
+    'disconnected'
+  );
+  const [isInitializing, setIsInitializing] = useState(false);
+  /** Mirrored from `clientRef` so the public `McpClient` object can be memoized when the instance is ready. */
+  const [sseClient, setSseClient] = useState<SSEClient | null>(null);
+
+  /**
+   * Initialize SSE client
+   */
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    const clientOptions: SSEClientOptions = {
+      url,
+      identity,
+      authToken,
+      onConnectionEvent: (event) => {
+        // Update local state based on event
+        updateConnectionsFromEvent(event);
+
+        // Call user callback
+        onConnectionEvent?.(event);
+      },
+      onObservabilityEvent: (event) => {
+        onLog?.(event.level || 'info', event.message || event.displayMessage || 'No message', event.metadata);
+      },
+      onStatusChange: (newStatus) => {
+        if (isMountedRef.current) {
+          setStatus(newStatus);
+        }
+      },
+      debug: options.debug,
+    };
+
+    const client = new SSEClient(clientOptions);
+    clientRef.current = client;
+    setSseClient(client);
+
+    if (autoConnect) {
+      client.connect();
+
+      if (autoInitialize) {
+        loadSessions();
+      }
+    }
+
+    return () => {
+      isMountedRef.current = false;
+      client.disconnect();
+    };
+  }, [url, identity, authToken, autoConnect, autoInitialize]);
+
+  /**
+   * Update connections based on event
+   */
+  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';
+
+    setConnections((prev: McpConnection[]) => {
+      switch (event.type) {
+        case 'state_changed': {
+          const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
+          if (existing) {
+            // 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
+                : event.state;
+
+            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
+              } : c
+            );
+          } else {
+            // Fix: Don't add back disconnected sessions that were just removed
+            if (event.state === 'DISCONNECTED') {
+              return prev;
+            }
+
+            return [
+              ...prev,
+              {
+                sessionId: event.sessionId,
+                serverId: event.serverId,
+                serverName: event.serverName,
+                serverUrl: event.serverUrl,
+                state: event.state,
+                createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
+                tools: [],
+              },
+            ];
+          }
+        }
+
+        case 'tools_discovered': {
+          // Preload UI resources for instant loading when tools are discovered
+          if (clientRef.current && event.tools?.length) {
+            clientRef.current.preloadToolUiResources(event.sessionId, event.tools);
+          }
+
+          return prev.map((c: McpConnection) =>
+            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY' } : c
+          );
+        }
+
+        case 'auth_required': {
+          // Handle OAuth redirect
+          if (event.authUrl) {
+            onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: event.authUrl });
+
+            // Suppress redirects/popups for auto-restore on page load.
+            if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
+              if (onRedirect) {
+                onRedirect(event.authUrl);
+              } else if (typeof window !== 'undefined') {
+                window.location.href = event.authUrl;
+              }
+            }
+          }
+          return prev.map((c: McpConnection) =>
+            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: event.authUrl } : c
+          );
+        }
+
+        case 'error': {
+          return prev.map((c: McpConnection) =>
+            c.sessionId === event.sessionId ? { ...c, state: 'FAILED', error: event.error } : c
+          );
+        }
+
+        case 'disconnected': {
+          return prev.filter((c: McpConnection) => c.sessionId !== event.sessionId);
+        }
+
+        default:
+          return prev;
+      }
+    });
+  }, [onLog, onRedirect]);
+
+  /**
+   * Load sessions from server
+   */
+  const loadSessions = useCallback(async () => {
+    if (!clientRef.current) return;
+
+    try {
+      setIsInitializing(true);
+
+      const result = await clientRef.current.getSessions();
+      const sessions = result.sessions || [];
+
+      // Initialize connections
+      if (isMountedRef.current) {
+        setConnections(
+          sessions.map((s: SessionInfo) => ({
+            sessionId: s.sessionId,
+            serverId: s.serverId ?? 'unknown',
+            serverName: s.serverName ?? 'Unknown Server',
+            serverUrl: s.serverUrl,
+            transport: s.transport,
+            state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+            createdAt: new Date(s.createdAt),
+            tools: [],
+          }))
+        );
+      }
+
+      // Validate each session in parallel
+      await Promise.all(
+        sessions.map(async (session: SessionInfo) => {
+          if (clientRef.current) {
+            try {
+              // Pending auth sessions should not auto-trigger popup/redirect on reload.
+              if (session.active === false) {
+                return;
+              }
+              suppressAuthRedirectSessionsRef.current.add(session.sessionId);
+              await clientRef.current.restoreSession(session.sessionId);
+            } catch (error) {
+              console.error(`[useMcp] Failed to validate session ${session.sessionId}:`, error);
+            } finally {
+              suppressAuthRedirectSessionsRef.current.delete(session.sessionId);
+            }
+          }
+        })
+      );
+    } catch (error) {
+      console.error('[useMcp] Failed to load sessions:', error);
+      onLog?.('error', 'Failed to load sessions', { error });
+    } finally {
+      if (isMountedRef.current) {
+        setIsInitializing(false);
+      }
+    }
+  }, [onLog]);
+
+  /**
+   * Connect to an MCP server
+   */
+  const connect = useCallback(
+    async (params: {
+      serverId: string;
+      serverName: string;
+      serverUrl: string;
+      callbackUrl: string;
+      transportType?: 'sse' | 'streamable_http';
+    }): Promise<string> => {
+      if (!clientRef.current) {
+        throw new Error('SSE client not initialized');
+      }
+
+      const result = await clientRef.current.connectToServer(params);
+      return result.sessionId;
+    },
+    []
+  );
+
+  /**
+   * Disconnect from an MCP server
+   */
+  const disconnect = useCallback(async (sessionId: string): Promise<void> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    await clientRef.current.disconnectFromServer(sessionId);
+
+    // Remove from local state
+    if (isMountedRef.current) {
+      setConnections((prev: McpConnection[]) => prev.filter((c: McpConnection) => c.sessionId !== sessionId));
+    }
+  }, []);
+
+  /**
+   * Refresh all connections
+   */
+  const refresh = useCallback(async () => {
+    await loadSessions();
+  }, [loadSessions]);
+
+  /**
+   * Manually connect SSE
+   */
+  const connectSSE = useCallback(() => {
+    clientRef.current?.connect();
+  }, []);
+
+  /**
+   * Manually disconnect SSE
+   */
+  const disconnectSSE = useCallback(() => {
+    clientRef.current?.disconnect();
+  }, []);
+
+  /**
+   * Complete OAuth authorization
+   */
+  const finishAuth = useCallback(async (sessionId: string, code: string): Promise<FinishAuthResult> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    return await clientRef.current.finishAuth(sessionId, code);
+  }, []);
+
+  /**
+   * Explicit user action to resume OAuth for an existing pending session.
+   */
+  const resumeAuth = useCallback(async (sessionId: string): Promise<void> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+    // Ensure this attempt is not suppressed as background restore.
+    suppressAuthRedirectSessionsRef.current.delete(sessionId);
+    await clientRef.current.restoreSession(sessionId);
+  }, []);
+
+  /**
+   * Call a tool
+   */
+  const callTool = useCallback(
+    async (
+      sessionId: string,
+      toolName: string,
+      toolArgs: Record<string, unknown>
+    ): Promise<unknown> => {
+      if (!clientRef.current) {
+        throw new Error('SSE client not initialized');
+      }
+
+      return await clientRef.current.callTool(sessionId, toolName, toolArgs);
+    },
+    []
+  );
+
+  /**
+   * List tools (refresh tool list)
+   */
+  const listTools = useCallback(async (sessionId: string): Promise<ListToolsRpcResult> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    return await clientRef.current.listTools(sessionId);
+  }, []);
+
+  /**
+   * List prompts
+   */
+  const listPrompts = useCallback(async (sessionId: string): Promise<ListPromptsResult> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    return await clientRef.current.listPrompts(sessionId);
+  }, []);
+
+  /**
+   * Get a specific prompt
+   */
+  const getPrompt = useCallback(
+    async (sessionId: string, name: string, args?: Record<string, string>): Promise<unknown> => {
+      if (!clientRef.current) {
+        throw new Error('SSE client not initialized');
+      }
+
+      return await clientRef.current.getPrompt(sessionId, name, args);
+    },
+    []
+  );
+
+  /**
+   * List resources
+   */
+  const listResources = useCallback(async (sessionId: string): Promise<ListResourcesResult> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    return await clientRef.current.listResources(sessionId);
+  }, []);
+
+  /**
+   * Read a specific resource
+   */
+  const readResource = useCallback(async (sessionId: string, uri: string): Promise<unknown> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+
+    return await clientRef.current.readResource(sessionId, uri);
+  }, []);
+
+  // Utility functions
+  const getConnection = useCallback(
+    (sessionId: string) => connections.find((c: McpConnection) => c.sessionId === sessionId),
+    [connections]
+  );
+
+  const getConnectionByServerId = useCallback(
+    (serverId: string) => connections.find((c: McpConnection) => c.serverId === serverId),
+    [connections]
+  );
+
+  const isServerConnected = useCallback(
+    (serverId: string) => {
+      const conn = getConnectionByServerId(serverId);
+      return conn ? conn.state === 'CONNECTED' || conn.state === 'DISCOVERING' || conn.state === 'READY' : false;
+    },
+    [getConnectionByServerId]
+  );
+
+  const getTools = useCallback(
+    (sessionId: string) => {
+      const conn = getConnection(sessionId);
+      return conn?.tools || [];
+    },
+    [getConnection]
+  );
+
+  return useMemo(
+    () => ({
+      connections,
+      status,
+      isInitializing,
+      connect,
+      disconnect,
+      getConnection,
+      getConnectionByServerId,
+      isServerConnected,
+      getTools,
+      refresh,
+      connectSSE,
+      disconnectSSE,
+      finishAuth,
+      resumeAuth,
+      callTool,
+      listTools,
+      listPrompts,
+      getPrompt,
+      listResources,
+      readResource,
+      sseClient,
+    }),
+    [
+      connections,
+      status,
+      isInitializing,
+      connect,
+      disconnect,
+      getConnection,
+      getConnectionByServerId,
+      isServerConnected,
+      getTools,
+      refresh,
+      connectSSE,
+      disconnectSSE,
+      finishAuth,
+      resumeAuth,
+      callTool,
+      listTools,
+      listPrompts,
+      getPrompt,
+      listResources,
+      readResource,
+      sseClient,
+    ]
+  );
+}