feat(auth-timeout): make callback timeout configurable

Author: peterkarman1

README.md

@@ -153,6 +153,17 @@ You can specify multiple `--ignore-tool` flags to ignore different patterns. Exa
 - `*account` - ignores all tools ending with "account" (e.g., `getAccount`, `updateAccount`)
 - `exactTool` - ignores only the tool named exactly "exactTool"
 
+* To change the timeout for the OAuth callback (by default `30` seconds), add the `--auth-timeout` flag with a value in seconds. This is useful if the authentication process on the server side takes a long time.
+
+```json
+      "args": [
+        "mcp-remote",
+        "https://remote.mcp.server/sse",
+        "--auth-timeout",
+        "60"
+      ]
+```
+
 ### Transport Strategies
 
 MCP Remote supports different transport strategies when connecting to an MCP server. This allows you to control whether it uses Server-Sent Events (SSE) or HTTP transport, and in what order it tries them.

src/client.ts

@@ -36,6 +36,7 @@ async function runClient(
   host: string,
   staticOAuthClientMetadata: StaticOAuthClientMetadata,
   staticOAuthClientInfo: StaticOAuthClientInformationFull,
+  authTimeoutMs: number,
 ) {
   // Set up event emitter for auth flow
   const events = new EventEmitter()
@@ -44,7 +45,7 @@ async function runClient(
   const serverUrlHash = getServerUrlHash(serverUrl)
 
   // Create a lazy auth coordinator
-  const authCoordinator = createLazyAuthCoordinator(serverUrlHash, callbackPort, events)
+  const authCoordinator = createLazyAuthCoordinator(serverUrlHash, callbackPort, events, authTimeoutMs)
 
   // Create the OAuth client provider
   const authProvider = new NodeOAuthClientProvider({
@@ -159,8 +160,8 @@ async function runClient(
 
 // Parse command-line arguments and run the client
 parseCommandLineArgs(process.argv.slice(2), 'Usage: npx tsx client.ts <https://server-url> [callback-port] [--debug]')
-  .then(({ serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo }) => {
-    return runClient(serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo)
+  .then(({ serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo, authTimeoutMs }) => {
+    return runClient(serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo, authTimeoutMs)
   })
   .catch((error) => {
     console.error('Fatal error:', error)

src/lib/coordination.ts

@@ -129,7 +129,12 @@ export async function waitForAuthentication(port: number): Promise<boolean> {
  * @param events The event emitter to use for signaling
  * @returns An AuthCoordinator object with an initializeAuth method
  */
-export function createLazyAuthCoordinator(serverUrlHash: string, callbackPort: number, events: EventEmitter): AuthCoordinator {
+export function createLazyAuthCoordinator(
+  serverUrlHash: string,
+  callbackPort: number,
+  events: EventEmitter,
+  authTimeoutMs: number,
+): AuthCoordinator {
   let authState: { server: Server; waitForAuthCode: () => Promise<string>; skipBrowserAuth: boolean } | null = null
 
   return {
@@ -144,7 +149,7 @@ export function createLazyAuthCoordinator(serverUrlHash: string, callbackPort: n
       if (DEBUG) debugLog('Initializing auth coordination on-demand', { serverUrlHash, callbackPort })
 
       // Initialize auth using the existing coordinateAuth logic
-      authState = await coordinateAuth(serverUrlHash, callbackPort, events)
+      authState = await coordinateAuth(serverUrlHash, callbackPort, events, authTimeoutMs)
       if (DEBUG) debugLog('Auth coordination completed', { skipBrowserAuth: authState.skipBrowserAuth })
       return authState
     },
@@ -162,6 +167,7 @@ export async function coordinateAuth(
   serverUrlHash: string,
   callbackPort: number,
   events: EventEmitter,
+  authTimeoutMs: number,
 ): Promise<{ server: Server; waitForAuthCode: () => Promise<string>; skipBrowserAuth: boolean }> {
   if (DEBUG) debugLog('Coordinating authentication', { serverUrlHash, callbackPort })
 
@@ -228,6 +234,7 @@ export async function coordinateAuth(
     port: callbackPort,
     path: '/oauth/callback',
     events,
+    authTimeoutMs,
   })
 
   // Get the actual port the server is running on

src/lib/types.ts

@@ -43,6 +43,8 @@ export interface OAuthCallbackServerOptions {
   path: string
   /** Event emitter to signal when auth code is received */
   events: EventEmitter
+  /** Timeout in milliseconds for the auth callback server's long poll */
+  authTimeoutMs?: number
 }
 
 // optional tatic OAuth client information

src/lib/utils.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi } from 'vitest'
 import { parseCommandLineArgs, shouldIncludeTool, mcpProxy } from './utils'
 import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { parseCommandLineArgs, setupOAuthCallbackServerWithLongPoll } from './utils'
+import { EventEmitter } from 'events'
+import express from 'express'
 
 // All sanitizeUrl tests have been moved to the strict-url-sanitise package
 
@@ -773,3 +777,150 @@ describe('Feature: MCP Proxy', () => {
     )
   })
 })
+
+describe('parseCommandLineArgs', () => {
+  const mockUsage = 'Usage: test <url>'
+  const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => {
+    throw new Error('process.exit called')
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    mockExit.mockReset()
+  })
+
+  describe('--auth-timeout parsing', () => {
+    it('should use default timeout of 30000ms when no --auth-timeout flag is provided', async () => {
+      const args = ['https://example.com']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(30000)
+    })
+
+    it('should parse valid timeout in seconds and convert to milliseconds', async () => {
+      const args = ['https://example.com', '--auth-timeout', '60']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(60000)
+    })
+
+    it('should parse another valid timeout value', async () => {
+      const args = ['https://example.com', '--auth-timeout', '120']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(120000)
+    })
+
+    it('should use default timeout when invalid timeout value is provided', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const args = ['https://example.com', '--auth-timeout', 'invalid']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(30000)
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: Ignoring invalid auth timeout value: invalid. Must be a positive number.')
+      )
+
+      consoleSpy.mockRestore()
+    })
+
+    it('should use default timeout when negative timeout value is provided', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const args = ['https://example.com', '--auth-timeout', '-30']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(30000)
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: Ignoring invalid auth timeout value: -30. Must be a positive number.')
+      )
+
+      consoleSpy.mockRestore()
+    })
+
+    it('should use default timeout when zero timeout value is provided', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const args = ['https://example.com', '--auth-timeout', '0']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(30000)
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: Ignoring invalid auth timeout value: 0. Must be a positive number.')
+      )
+
+      consoleSpy.mockRestore()
+    })
+
+    it('should use default timeout when --auth-timeout flag has no value', async () => {
+      const args = ['https://example.com', '--auth-timeout']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(30000)
+    })
+
+    it('should log when using custom timeout', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const args = ['https://example.com', '--auth-timeout', '45']
+      const result = await parseCommandLineArgs(args, mockUsage)
+
+      expect(result.authTimeoutMs).toBe(45000)
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Using auth callback timeout: 45 seconds')
+      )
+
+      consoleSpy.mockRestore()
+    })
+  })
+})
+
+describe('setupOAuthCallbackServerWithLongPoll', () => {
+  let server: any
+  let events: EventEmitter
+
+  beforeEach(() => {
+    events = new EventEmitter()
+  })
+
+  afterEach(() => {
+    if (server) {
+      server.close()
+      server = null
+    }
+  })
+
+  it('should use custom timeout when authTimeoutMs is provided', async () => {
+    const customTimeout = 5000
+    const result = setupOAuthCallbackServerWithLongPoll({
+      port: 0, // Use any available port
+      path: '/oauth/callback',
+      events,
+      authTimeoutMs: customTimeout
+    })
+
+    server = result.server
+
+    // Test that the server was created
+    expect(server).toBeDefined()
+    expect(typeof result.waitForAuthCode).toBe('function')
+  })
+
+  it('should use default timeout when authTimeoutMs is not provided', async () => {
+    const result = setupOAuthCallbackServerWithLongPoll({
+      port: 0, // Use any available port
+      path: '/oauth/callback',
+      events
+    })
+
+    server = result.server
+
+    // Test that the server was created with defaults
+    expect(server).toBeDefined()
+    expect(typeof result.waitForAuthCode).toBe('function')
+  })
+})

src/lib/utils.ts

@@ -475,7 +475,7 @@ export function setupOAuthCallbackServerWithLongPoll(options: OAuthCallbackServe
     const longPollTimeout = setTimeout(() => {
       log('Long poll timeout reached, responding with 202')
       res.status(202).send('Authentication in progress')
-    }, 30000)
+    }, options.authTimeoutMs || 30000)
 
     // If auth completes while we're waiting, send the response immediately
     authCompletedPromise
@@ -716,6 +716,19 @@ export async function parseCommandLineArgs(args: string[], usage: string) {
     j++
   }
 
+  // Parse auth timeout
+  let authTimeoutMs = 30000 // Default 30 seconds
+  const authTimeoutIndex = args.indexOf('--auth-timeout')
+  if (authTimeoutIndex !== -1 && authTimeoutIndex < args.length - 1) {
+    const timeoutSeconds = parseInt(args[authTimeoutIndex + 1], 10)
+    if (!isNaN(timeoutSeconds) && timeoutSeconds > 0) {
+      authTimeoutMs = timeoutSeconds * 1000
+      log(`Using auth callback timeout: ${timeoutSeconds} seconds`)
+    } else {
+      log(`Warning: Ignoring invalid auth timeout value: ${args[authTimeoutIndex + 1]}. Must be a positive number.`)
+    }
+  }
+
   if (!serverUrl) {
     log(usage)
     process.exit(1)
@@ -791,6 +804,7 @@ export async function parseCommandLineArgs(args: string[], usage: string) {
     staticOAuthClientInfo,
     authorizeResource,
     ignoredTools,
+    authTimeoutMs,
   }
 }
 

src/proxy.ts

@@ -37,6 +37,7 @@ async function runProxy(
   staticOAuthClientInfo: StaticOAuthClientInformationFull,
   authorizeResource: string,
   ignoredTools: string[],
+  authTimeoutMs: number,
 ) {
   // Set up event emitter for auth flow
   const events = new EventEmitter()
@@ -45,7 +46,7 @@ async function runProxy(
   const serverUrlHash = getServerUrlHash(serverUrl)
 
   // Create a lazy auth coordinator
-  const authCoordinator = createLazyAuthCoordinator(serverUrlHash, callbackPort, events)
+  const authCoordinator = createLazyAuthCoordinator(serverUrlHash, callbackPort, events, authTimeoutMs)
 
   // Create the OAuth client provider
   const authProvider = new NodeOAuthClientProvider({
@@ -158,6 +159,7 @@ parseCommandLineArgs(process.argv.slice(2), 'Usage: npx tsx proxy.ts <https://se
       staticOAuthClientInfo,
       authorizeResource,
       ignoredTools,
+      authTimeoutMs,
     }) => {
       return runProxy(
         serverUrl,
@@ -169,6 +171,7 @@ parseCommandLineArgs(process.argv.slice(2), 'Usage: npx tsx proxy.ts <https://se
         staticOAuthClientInfo,
         authorizeResource,
         ignoredTools,
+        authTimeoutMs,
       )
     },
   )