feat(oauth): non-blocking auth flow for AI agents

[philschmid]

Summary

Continuation of #22 with improvements based on review feedback.

Key change from PR #22: CLI now NEVER opens browser - always returns auth URL for AI agents.

What's Different from #22

Feature	PR #22	This PR
Browser behavior	Opens browser for single server	Never opens browser
allowInteractiveAuth	Configurable option	Removed entirely
Port selection	Fixed ports with fallback	Random port by default
Error handling	Interactive OAuth flow	Always returns auth URL

Changes

• Removed allowInteractiveAuth entirely - CLI is designed for AI agents
• redirectToAuthorization() captures auth URL - never opens browser
• AuthRequiredError includes authorization URL for immediate action
• Callback server runs in background (5 min timeout) - CLI returns immediately
• Random port by default - avoids conflicts with multiple OAuth servers
• Comprehensive OAuth configuration docs - options table, three example scenarios

Previous OAuth commits in this branch (from #22)

• feat: add OAuth support for HTTP MCP servers
• fix: OAuth race condition and concurrent auth handling
• feat: add OAuth callback port fallback and pretty HTML pages
• fix: detect and invalidate stale OAuth client registrations
• refactor: split oauth.ts into logical modules

Testing

All 232 tests pass, lint clean.

---

cc @attehuhtakangas - would appreciate if you could test this version! The main difference is that it never tries to open a browser, which is better suited for AI agent usage.

[attehuhtakangas]

@philschmid it doesn't work, the callback server is stopped before it starts to listen. Example output:

mcp-cli -c /Users/atte/.config/mcp/mcp_servers.json datadog
Error [SERVER_CONNECTION_FAILED]: Failed to connect to server "datadog"
  Details: [AUTH REQUIRED] datadog
  Authenticate at: https://mcp.datadoghq.com/api/unstable/mcp-server/authorize?response_type=code&client_id=mcp_1234567&code_challenge=[OMITTED]&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A54723%2Fcallback&resource=https%3A%2F%2Fmcp.datadoghq.com%2F
  Callback server running in background (5 min timeout).
  After authenticating, confirm "done" and retry this command.
  Suggestion: Connection timed out. Check network connectivity and server availability

Since this is in your PR and branch now, here's my Claude's plan to fix it in case it's helpful:

Claude's plan

Fix: OAuth callback server dies immediately on process exit                         
                                                  
 Context                                  
                                     
 When running mcp-cli datadog, the CLI detects OAuth is required, starts a callback server, prints the auth URL, then immediately calls process.exit() — killing the callback server before it can receive
 the OAuth redirect. The auth URL points to a dead callback server.

 The root cause is in info.ts (and call.ts): they catch AuthRequiredError as a generic error, wrap it in serverConnectionError(), and call process.exit(). The callback server lives in the same process and
  dies with it.

 A secondary issue: AuthRequiredError's message contains "5 min timeout", which triggers the misleading "Connection timed out" suggestion in serverConnectionError().

 Fix

 Instead of throwing AuthRequiredError and exiting, make connectToServer() wait for the OAuth callback when a waitForAuth option is set. The info and call commands pass this option; list keeps the current
  non-blocking behavior.

 The MCP SDK provides transport.finishAuth(code) exactly for this: it exchanges the authorization code for tokens and saves them.

 1. src/client.ts — Add waitForAuth option and blocking auth flow

 - Change ConnectOptions from Record<string, never> to { waitForAuth?: boolean }
 - In the catch block inside connectToServer() where isOAuthNeeded() is true:
   - If options.waitForAuth is true:
       i. Print auth URL + "Waiting for authentication..." to stderr
     ii. Call authProvider.waitForCallback() to block until code arrives
     iii. Call transport.finishAuth(code) to exchange code for tokens
     iv. Create fresh Client + createHttpTransport() and connect (tokens now on disk)
     v. Return the new connected client
   - If waitForAuth is false/undefined: throw AuthRequiredError (current behavior for list)

 2. src/commands/info.ts — Handle auth and pass waitForAuth: true

 - Import AuthRequiredError
 - Pass { waitForAuth: true } to getConnection()
 - In the catch block, detect AuthRequiredError separately and show auth-specific error (not the misleading "Connection timed out" suggestion)

 3. src/commands/call.ts — Pass waitForAuth: true

 - Import AuthRequiredError
 - Pass { waitForAuth: true } to getConnection()
 - Handle AuthRequiredError with auth-specific error messaging

 4. src/errors.ts — Better suggestion for auth-related errors

 - In serverConnectionError(), check for "AUTH REQUIRED" or "OAuth callback" before the generic "timeout" check, so auth errors get an appropriate suggestion instead of "Connection timed out"

 Files to modify

 - src/client.ts — Core fix: blocking auth flow in connectToServer()
 - src/commands/info.ts — Pass waitForAuth: true, handle AuthRequiredError
 - src/commands/call.ts — Pass waitForAuth: true, handle AuthRequiredError
 - src/errors.ts — Fix misleading timeout suggestion for auth errors

Details