automatic skipLocalStorage for server and client if database

Author: jeremybosma

index.ts

@@ -45,9 +45,9 @@ import { notionIntegration } from './src/integrations/notion.js';
  * Default configuration:
  * - Calls API routes at: {window.location.origin}/api/integrate/mcp
  * - OAuth routes at: {window.location.origin}/api/integrate/oauth/*
- * - Saves tokens to localStorage (tokens persist across page reloads)
+ * - Automatically detects if server uses database storage and skips localStorage accordingly
  * 
- * For custom configuration (different apiBaseUrl, apiRouteBase, localStorage, etc.),
+ * For custom configuration (different apiBaseUrl, apiRouteBase, etc.),
  * use `createMCPClient()` instead.
  * 
  * @example
@@ -68,7 +68,6 @@ import { notionIntegration } from './src/integrations/notion.js';
  * 
  * const customClient = createMCPClient({
  *   integrations: [githubIntegration()],
- *   skipLocalStorage: true, // Disable localStorage and use server-side callbacks
  * });
  * ```
  */
@@ -78,8 +77,5 @@ export const client = createMCPClient({
     gmailIntegration(),
     notionIntegration(),
   ],
-  // Default client uses localStorage to persist tokens across page reloads
-  // If you need server-side token management, set skipLocalStorage: true and configure callbacks
-  skipLocalStorage: false,
 });
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "integrate-sdk",
-  "version": "0.8.23",
+  "version": "0.8.24",
   "description": "Type-safe 3rd party integration SDK for the Integrate MCP server",
   "type": "module",
   "main": "./dist/index.js",

src/adapters/base-handler.ts

@@ -231,6 +231,14 @@ export class OAuthHandler {
     return headers;
   }
 
+  /**
+   * Check if database callbacks are configured
+   * Used to determine if we should set X-Integrate-Use-Database header
+   */
+  hasDatabaseCallbacks(): boolean {
+    return !!this.config.setProviderToken;
+  }
+
   /**
    * Handle authorization URL request
    * Gets authorization URL from MCP server with full OAuth credentials

src/adapters/nextjs.ts

@@ -115,6 +115,11 @@ export function createNextOAuthHandler(config: OAuthHandlerConfig) {
           response.headers.set('Set-Cookie', result.setCookie);
         }
 
+        // Add X-Integrate-Use-Database header if database callbacks are configured
+        if (handler.hasDatabaseCallbacks()) {
+          response.headers.set('X-Integrate-Use-Database', 'true');
+        }
+        
         return response;
       } catch (error: any) {
         console.error('[OAuth Authorize] Error:', error);
@@ -180,6 +185,11 @@ export function createNextOAuthHandler(config: OAuthHandlerConfig) {
           response.headers.set('Set-Cookie', result.clearCookie);
         }
 
+        // Add X-Integrate-Use-Database header if database callbacks are configured
+        if (handler.hasDatabaseCallbacks()) {
+          response.headers.set('X-Integrate-Use-Database', 'true');
+        }
+        
         return response;
       } catch (error: any) {
         console.error('[OAuth Callback] Error:', error);
@@ -248,7 +258,14 @@ export function createNextOAuthHandler(config: OAuthHandlerConfig) {
 
         const accessToken = authHeader.substring(7); // Remove 'Bearer ' prefix
         const result = await handler.handleStatus(provider, accessToken);
-        return Response.json(result);
+        const response = Response.json(result);
+        
+        // Add X-Integrate-Use-Database header if database callbacks are configured
+        if (handler.hasDatabaseCallbacks()) {
+          response.headers.set('X-Integrate-Use-Database', 'true');
+        }
+        
+        return response;
       } catch (error: any) {
         console.error('[OAuth Status] Error:', error);
         return Response.json(
@@ -322,7 +339,14 @@ export function createNextOAuthHandler(config: OAuthHandlerConfig) {
 
         // Pass the request object for context extraction
         const result = await handler.handleDisconnect({ provider }, accessToken, req);
-        return Response.json(result);
+        const response = Response.json(result);
+        
+        // Add X-Integrate-Use-Database header if database callbacks are configured
+        if (handler.hasDatabaseCallbacks()) {
+          response.headers.set('X-Integrate-Use-Database', 'true');
+        }
+        
+        return response;
       } catch (error: any) {
         console.error('[OAuth Disconnect] Error:', error);
         return Response.json(

src/client.ts

@@ -160,6 +160,7 @@ export class MCPClientBase<TIntegrations extends readonly MCPIntegration[] = rea
   private eventEmitter: SimpleEventEmitter = new SimpleEventEmitter();
   private apiRouteBase: string;
   private apiBaseUrl?: string;
+  private databaseDetected: boolean = false;
 
   /**
    * Promise that resolves when OAuth callback processing is complete
@@ -222,7 +223,6 @@ export class MCPClientBase<TIntegrations extends readonly MCPIntegration[] = rea
         getProviderToken: (config as any).getProviderToken,
         setProviderToken: (config as any).setProviderToken,
         removeProviderToken: (config as any).removeProviderToken,
-        skipLocalStorage: config.skipLocalStorage,
       }
     );
 
@@ -620,6 +620,12 @@ export class MCPClientBase<TIntegrations extends readonly MCPIntegration[] = rea
       }),
     });
 
+    // Check for X-Integrate-Use-Database header to auto-detect database usage
+    if (!this.databaseDetected && response.headers.get('X-Integrate-Use-Database') === 'true') {
+      this.oauthManager.setSkipLocalStorage(true);
+      this.databaseDetected = true;
+    }
+
     if (!response.ok) {
       // Try to parse error response
       let errorMessage = `Request failed: ${response.statusText}`;

src/config/types.ts

@@ -449,26 +449,6 @@ export interface MCPClientConfig<TIntegrations extends readonly MCPIntegration[]
    */
   autoHandleOAuthCallback?: boolean;
 
-  /**
-   * Skip saving OAuth tokens to localStorage
-   * Set to true when using server-side database storage for tokens
-   * 
-   * When true, tokens will not be saved to browser localStorage.
-   * This is useful when your server handles all token storage via database callbacks.
-   * 
-   * @default false (tokens are saved to localStorage)
-   * 
-   * @example
-   * ```typescript
-   * // Browser client when server uses database storage
-   * const client = createMCPClient({
-   *   integrations: [githubIntegration({ ... })],
-   *   skipLocalStorage: true // Don't save tokens in browser
-   * });
-   * ```
-   */
-  skipLocalStorage?: boolean;
-
   /**
    * Configure behavior when OAuth callback processing fails
    * 

src/oauth/manager.ts

@@ -40,7 +40,6 @@ export class OAuthManager {
       getProviderToken?: (provider: string, context?: MCPContext) => Promise<ProviderTokenData | undefined> | ProviderTokenData | undefined;
       setProviderToken?: (provider: string, tokenData: ProviderTokenData | null, context?: MCPContext) => Promise<void> | void;
       removeProviderToken?: (provider: string, context?: MCPContext) => Promise<void> | void;
-      skipLocalStorage?: boolean;
     }
   ) {
     this.oauthApiBase = oauthApiBase;
@@ -55,12 +54,10 @@ export class OAuthManager {
     this.setTokenCallback = tokenCallbacks?.setProviderToken;
     this.removeTokenCallback = tokenCallbacks?.removeProviderToken;
 
-    // Determine skipLocalStorage setting:
-    // 1. If explicitly set, use that value
-    // 2. If getTokenCallback is provided (indicating server-side database storage), auto-set to true
-    // 3. Otherwise, default to false (use localStorage when callbacks are not configured)
-    // This ensures localStorage is only used when callbacks are NOT configured AND skipLocalStorage is false
-    this.skipLocalStorage = tokenCallbacks?.skipLocalStorage ?? !!tokenCallbacks?.getProviderToken;
+    // Auto-detect skipLocalStorage from callbacks:
+    // If getTokenCallback or setTokenCallback is provided (indicating server-side database storage), auto-set to true
+    // Otherwise, default to false (use localStorage when callbacks are not configured)
+    this.skipLocalStorage = !!(tokenCallbacks?.getProviderToken || tokenCallbacks?.setProviderToken);
 
     // Clean up any expired pending auth entries from localStorage
     this.cleanupExpiredPendingAuths();
@@ -843,6 +840,11 @@ export class OAuthManager {
       }),
     });
 
+    // Check for X-Integrate-Use-Database header to auto-detect database usage
+    if (response.headers.get('X-Integrate-Use-Database') === 'true') {
+      this.skipLocalStorage = true;
+    }
+
     if (!response.ok) {
       const error = await response.text();
       throw new Error(`Failed to get authorization URL: ${error}`);
@@ -899,6 +901,11 @@ export class OAuthManager {
       }),
     });
 
+    // Check for X-Integrate-Use-Database header to auto-detect database usage
+    if (response.headers.get('X-Integrate-Use-Database') === 'true') {
+      this.skipLocalStorage = true;
+    }
+
     if (!response.ok) {
       const error = await response.text();
       throw new Error(`Failed to exchange code for token: ${error}`);
@@ -908,6 +915,14 @@ export class OAuthManager {
     return data;
   }
 
+  /**
+   * Update skipLocalStorage setting at runtime
+   * Called automatically when server indicates database usage via response header
+   */
+  setSkipLocalStorage(value: boolean): void {
+    this.skipLocalStorage = value;
+  }
+
   /**
    * Close any open OAuth windows
    */

src/server.ts

@@ -397,10 +397,20 @@ export function createMCPServer<TIntegrations extends readonly MCPIntegration[]>
           providers,
           serverUrl: config.serverUrl,
           apiKey: config.apiKey, // API key is included here and sent to MCP server
+          setProviderToken: config.setProviderToken,
+          removeProviderToken: config.removeProviderToken,
+          getSessionContext: config.getSessionContext,
         });
 
         const result = await oauthHandler.handleToolCall(body, authHeader);
-        return Response.json(result);
+        const response = Response.json(result);
+        
+        // Add X-Integrate-Use-Database header if database callbacks are configured
+        if (oauthHandler.hasDatabaseCallbacks()) {
+          response.headers.set('X-Integrate-Use-Database', 'true');
+        }
+        
+        return response;
       } catch (error: any) {
         console.error('[MCP Tool Call] Error:', error);
         return Response.json(

tests/client/api-routing.test.ts

@@ -465,5 +465,93 @@ describe("MCP Client - API Routing", () => {
 
     expect(apiHandlerCalled).toBe(true);
   });
+
+  it("should detect X-Integrate-Use-Database header and update skipLocalStorage", async () => {
+    const mockLocalStorage = new Map<string, string>();
+    
+    // Mock localStorage
+    global.localStorage = {
+      getItem: (key: string) => mockLocalStorage.get(key) || null,
+      setItem: (key: string, value: string) => mockLocalStorage.set(key, value),
+      removeItem: (key: string) => mockLocalStorage.delete(key),
+      clear: () => mockLocalStorage.clear(),
+      length: 0,
+      key: () => null,
+    } as any;
+
+    let headerDetected = false;
+
+    global.fetch = mock(async (url: string, options?: any) => {
+      if (url.includes("/api/integrate/mcp")) {
+        // Return response with X-Integrate-Use-Database header
+        const headers = new Headers();
+        headers.set('X-Integrate-Use-Database', 'true');
+        
+        return {
+          ok: true,
+          headers,
+          json: async () => ({
+            content: [{ type: "text", text: "result" }],
+          }),
+        } as Response;
+      } else if (url.includes("mcp.integrate.dev")) {
+        // Mock initialization calls
+        return {
+          ok: true,
+          headers: new Headers(),
+          json: async () => ({
+            jsonrpc: "2.0",
+            id: 1,
+            result: { tools: [] },
+          }),
+        } as Response;
+      }
+      return { ok: false, headers: new Headers() } as Response;
+    }) as any;
+
+    const mockOAuthManager = {
+      getProviderToken: mock(() => null),
+      loadAllProviderTokens: mock(() => { }),
+      getAllProviderTokens: mock(() => new Map()),
+      setProviderToken: mock(() => { }),
+      clearAllProviderTokens: mock(() => { }),
+      clearAllPendingAuths: mock(() => { }),
+      checkAuthStatus: mock(() => Promise.resolve({ authorized: false })),
+      initiateFlow: mock(() => Promise.resolve()),
+      handleCallback: mock(() => Promise.resolve({ provider: "github", accessToken: "token", expiresAt: Date.now() })),
+      disconnectProvider: mock(() => Promise.resolve()),
+      setSkipLocalStorage: mock((value: boolean) => {
+        headerDetected = value;
+      }),
+    };
+
+    const integration = createSimpleIntegration({
+      id: "test",
+      tools: ["test_tool"],
+    });
+
+    const client = new MCPClientBase({
+      integrations: [integration],
+      apiRouteBase: "/api/integrate",
+      connectionMode: "manual",
+    });
+
+    (client as any).oauthManager = mockOAuthManager;
+    (client as any).initialized = true;
+    (client as any).transport.connected = true;
+    (client as any).availableTools.set("test_tool", {
+      name: "test_tool",
+      description: "Test tool",
+      inputSchema: { type: "object" },
+    });
+    (client as any).enabledToolNames.add("test_tool");
+
+    // Make a tool call - should detect header
+    await (client as any).callServerTool("test_tool", {});
+
+    // Verify header was detected and skipLocalStorage was set
+    expect(mockOAuthManager.setSkipLocalStorage).toHaveBeenCalledWith(true);
+    expect(headerDetected).toBe(true);
+  });
 });