feat: add preventAutoAuth option to prevent automatic authentication popups

- Add preventAutoAuth option to UseMcpOptions to control automatic popup behavior
- Introduce pending_auth state for when auth is required but auto-popup is prevented
- Enhance authentication flow to check for existing tokens before triggering auth
- Add prepareAuthorizationUrl() helper method in BrowserOAuthClientProvider
- Update authenticate() method to handle pending_auth state transitions
- Improve chat UI components to handle new authentication states gracefully
- Add clear call-to-action UI with primary popup button and fallback new tab link
- Maintain backward compatibility - existing code continues to work unchanged

This prevents browser popup blockers from interfering with authentication flows
when users return to pages with MCP servers, providing better UX and control.

Author: geelen

examples/chat-ui/src/components/McpServerModal.tsx

@@ -23,6 +23,7 @@ function McpConnection({
     debug: true,
     autoRetry: false,
     popupFeatures: 'width=500,height=600,resizable=yes,scrollbars=yes',
+    preventAutoAuth: true, // Prevent automatic popups on page load
   })
 
   // Update parent component with connection data
@@ -197,6 +198,12 @@ const McpServerModal: React.FC<McpServerModalProps> = ({
             Discovering
           </span>
         )
+      case 'pending_auth':
+        return (
+          <span className={`${baseClasses} bg-orange-100 text-orange-800`}>
+            Authentication Required
+          </span>
+        )
       case 'authenticating':
         return (
           <span className={`${baseClasses} bg-purple-100 text-purple-800`}>
@@ -320,20 +327,32 @@ const McpServerModal: React.FC<McpServerModalProps> = ({
                           </div>
                         )}
 
-                        {authUrl && (
-                          <div className="p-3 bg-orange-50 border border-orange-200 rounded mb-3">
+                        {(state === 'pending_auth' || authUrl) && (
+                          <div className="p-3 bg-blue-50 border border-blue-200 rounded mb-3">
                             <p className="text-sm mb-2">
-                              Authentication required. Please click the link below:
+                              {state === 'pending_auth' 
+                                ? 'Authentication is required to connect to this server.'
+                                : 'Authentication popup was blocked. You can open the authentication page manually:'
+                              }
                             </p>
-                            <a
-                              href={authUrl}
-                              target="_blank"
-                              rel="noopener noreferrer"
-                              className="text-sm text-orange-700 hover:text-orange-800 underline"
-                              onClick={() => handleManualAuth(server.id)}
-                            >
-                              Authenticate in new window
-                            </a>
+                            <div className="space-y-2">
+                              <button
+                                className="w-full px-3 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded text-sm font-medium"
+                                onClick={() => handleManualAuth(server.id)}
+                              >
+                                Open Authentication Popup
+                              </button>
+                              {authUrl && (
+                                <a
+                                  href={authUrl}
+                                  target="_blank"
+                                  rel="noopener noreferrer"
+                                  className="block text-center text-sm text-blue-700 hover:text-blue-800 underline"
+                                >
+                                  Or open in new tab instead
+                                </a>
+                              )}
+                            </div>
                           </div>
                         )}
 

examples/chat-ui/src/components/McpServers.tsx

@@ -16,6 +16,7 @@ function McpConnection({
     debug: true,
     autoRetry: false,
     popupFeatures: 'width=500,height=600,resizable=yes,scrollbars=yes',
+    preventAutoAuth: true, // Prevent automatic popups on page load
   })
 
   // Update parent component with connection data
@@ -127,6 +128,12 @@ export function McpServers({
             Discovering
           </span>
         )
+      case 'pending_auth':
+        return (
+          <span className={`${baseClasses} bg-orange-100 text-orange-800`}>
+            Authentication Required
+          </span>
+        )
       case 'authenticating':
         return (
           <span className={`${baseClasses} bg-purple-100 text-purple-800`}>
@@ -241,21 +248,33 @@ export function McpServers({
           )}
         </div>
 
-        {/* Authentication Link if needed */}
-        {authUrl && (
-          <div className="p-3 bg-orange-50 border border-orange-200 rounded">
+        {/* Authentication Action for pending_auth or existing authUrl */}
+        {(state === 'pending_auth' || authUrl) && (
+          <div className="p-3 bg-blue-50 border border-blue-200 rounded">
             <p className="text-xs mb-2">
-              Authentication required. Please click the link below:
+              {state === 'pending_auth' 
+                ? 'Authentication is required to connect to this server.'
+                : 'Authentication popup was blocked. You can open the authentication page manually:'
+              }
             </p>
-            <a
-              href={authUrl}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-xs text-orange-700 hover:text-orange-800 underline"
-              onClick={handleManualAuth}
-            >
-              Authenticate in new window
-            </a>
+            <div className="space-y-2">
+              <button
+                className="w-full px-3 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded text-xs font-medium"
+                onClick={handleManualAuth}
+              >
+                Open Authentication Popup
+              </button>
+              {authUrl && (
+                <a
+                  href={authUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="block text-center text-xs text-blue-700 hover:text-blue-800 underline"
+                >
+                  Or open in new tab instead
+                </a>
+              )}
+            </div>
           </div>
         )}
 

src/auth/browser-provider.ts

@@ -115,11 +115,12 @@ export class BrowserOAuthClientProvider implements OAuthClientProvider {
   }
 
   /**
-   * Redirects the user agent to the authorization URL, storing necessary state.
-   * This now adheres to the SDK's void return type expectation for the interface.
+   * Generates and stores the authorization URL with state, without opening a popup.
+   * Used when preventAutoAuth is enabled to provide the URL for manual navigation.
    * @param authorizationUrl The fully constructed authorization URL from the SDK.
+   * @returns The full authorization URL with state parameter.
    */
-  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+  async prepareAuthorizationUrl(authorizationUrl: URL): Promise<string> {
     // Generate a unique state parameter for this authorization request
     const state = crypto.randomUUID()
     const stateKey = `${this.storageKeyPrefix}:state_${state}`
@@ -146,6 +147,18 @@ export class BrowserOAuthClientProvider implements OAuthClientProvider {
     // Persist the exact auth URL in case the popup fails and manual navigation is needed
     localStorage.setItem(this.getKey('last_auth_url'), authUrlString)
 
+    return authUrlString
+  }
+
+  /**
+   * Redirects the user agent to the authorization URL, storing necessary state.
+   * This now adheres to the SDK's void return type expectation for the interface.
+   * @param authorizationUrl The fully constructed authorization URL from the SDK.
+   */
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    // Prepare the authorization URL with state
+    const authUrlString = await this.prepareAuthorizationUrl(authorizationUrl)
+
     // Attempt to open the popup
     const popupFeatures = 'width=600,height=700,resizable=yes,scrollbars=yes,status=yes' // Make configurable if needed
     try {

src/react/types.ts

@@ -26,6 +26,8 @@ export type UseMcpOptions = {
   autoReconnect?: boolean | number
   /** Popup window features string (dimensions and behavior) for OAuth */
   popupFeatures?: string
+  /** Prevent automatic authentication popup on initial connection (default: false) */
+  preventAutoAuth?: boolean
 }
 
 export type UseMcpResult = {
@@ -34,13 +36,14 @@ export type UseMcpResult = {
   /**
    * The current state of the MCP connection:
    * - 'discovering': Checking server existence and capabilities (including auth requirements).
+   * - 'pending_auth': Authentication is required but auto-popup was prevented. User action needed.
    * - 'authenticating': Authentication is required and the process (e.g., popup) has been initiated.
    * - 'connecting': Establishing the SSE connection to the server.
    * - 'loading': Connected; loading resources like the tool list.
    * - 'ready': Connected and ready for tool calls.
    * - 'failed': Connection or authentication failed. Check the `error` property.
    */
-  state: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
+  state: 'discovering' | 'pending_auth' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
   /** If the state is 'failed', this provides the error message */
   error?: string
   /**

src/react/useMcp.ts

@@ -30,6 +30,7 @@ export function useMcp(options: UseMcpOptions): UseMcpResult {
     debug = false,
     autoRetry = false,
     autoReconnect = DEFAULT_RECONNECT_DELAY,
+    preventAutoAuth = false,
   } = options
 
   const [state, setState] = useState<UseMcpResult['state']>('discovering')
@@ -288,9 +289,22 @@ export function useMcp(options: UseMcpOptions): UseMcpResult {
 
         // Check for Auth error (Simplified - requires more thought for interaction with fallback)
         if (errorInstance instanceof UnauthorizedError || errorMessage.includes('Unauthorized') || errorMessage.includes('401')) {
-          addLog('info', 'Authentication required. Initiating SDK auth flow...')
+          addLog('info', 'Authentication required.')
+
+          // Check if we have existing tokens before triggering auth flow
+          assert(authProviderRef.current, 'Auth Provider not available for auth flow')
+          const existingTokens = await authProviderRef.current.tokens()
+
+          // If preventAutoAuth is enabled and no valid tokens exist, go to pending_auth state
+          if (preventAutoAuth && !existingTokens) {
+            addLog('info', 'Authentication required but auto-auth prevented. User action needed.')
+            setState('pending_auth')
+            // We'll set the auth URL when the user manually triggers auth
+            return 'auth_redirect' // Signal that we need user action
+          }
+
           // Ensure state is set only once if multiple attempts trigger auth
-          if (stateRef.current !== 'authenticating') {
+          if (stateRef.current !== 'authenticating' && stateRef.current !== 'pending_auth') {
             setState('authenticating')
             if (authTimeoutRef.current) clearTimeout(authTimeoutRef.current)
             authTimeoutRef.current = setTimeout(() => {
@@ -299,7 +313,6 @@ export function useMcp(options: UseMcpOptions): UseMcpResult {
           }
 
           try {
-            assert(authProviderRef.current, 'Auth Provider not available for auth flow')
             const authResult = await auth(authProviderRef.current, { serverUrl: url })
 
             if (!isMountedRef.current) return 'failed' // Unmounted during auth
@@ -478,13 +491,44 @@ export function useMcp(options: UseMcpOptions): UseMcpResult {
   }, [addLog, connect]) // Depends only on stable callbacks
 
   // authenticate is stable (depends on stable addLog, retry, connect)
-  const authenticate = useCallback(() => {
+  const authenticate = useCallback(async () => {
     addLog('info', 'Manual authentication requested...')
     const currentState = stateRef.current // Use ref
 
     if (currentState === 'failed') {
       addLog('info', 'Attempting to reconnect and authenticate via retry...')
       retry()
+    } else if (currentState === 'pending_auth') {
+      addLog('info', 'Proceeding with authentication from pending state...')
+      setState('authenticating')
+      if (authTimeoutRef.current) clearTimeout(authTimeoutRef.current)
+      authTimeoutRef.current = setTimeout(() => {
+        /* ... timeout logic ... */
+      }, AUTH_TIMEOUT)
+
+      try {
+        assert(authProviderRef.current, 'Auth Provider not available for manual auth')
+        const authResult = await auth(authProviderRef.current, { serverUrl: url })
+
+        if (!isMountedRef.current) return
+
+        if (authResult === 'AUTHORIZED') {
+          addLog('info', 'Manual authentication successful. Re-attempting connection...')
+          if (authTimeoutRef.current) clearTimeout(authTimeoutRef.current)
+          connectingRef.current = false
+          connect() // Restart full connection sequence
+        } else if (authResult === 'REDIRECT') {
+          addLog('info', 'Redirecting for manual authentication. Waiting for callback...')
+          // State is already authenticating, wait for callback
+        }
+      } catch (authError) {
+        if (!isMountedRef.current) return
+        if (authTimeoutRef.current) clearTimeout(authTimeoutRef.current)
+        failConnection(
+          `Manual authentication failed: ${authError instanceof Error ? authError.message : String(authError)}`,
+          authError instanceof Error ? authError : undefined,
+        )
+      }
     } else if (currentState === 'authenticating') {
       addLog('warn', 'Already attempting authentication. Check for blocked popups or wait for timeout.')
       const manualUrl = authProviderRef.current?.getLastAttemptedAuthUrl()
@@ -504,7 +548,7 @@ export function useMcp(options: UseMcpOptions): UseMcpResult {
       // assert(authProviderRef.current, "Auth Provider not available");
       // auth(authProviderRef.current, { serverUrl: url }).catch(failConnection);
     }
-  }, [addLog, retry, authUrl]) // Depends on stable callbacks and authUrl state
+  }, [addLog, retry, authUrl, url, failConnection, connect]) // Depends on stable callbacks and authUrl state
 
   // clearStorage is stable (depends on stable addLog, disconnect)
   const clearStorage = useCallback(() => {