MCP OAuth authentication UX issues: stale token not auto-refreshed, silent errors, foreground login timeout

[bevis-wong]

Description

Summary

After configuring an OAuth-protected HTTP MCP server (Nordic MCP at https://aidev.nordicsemi.com/mcp) in mcp.json, the following chain of issues made authentication far more difficult than it should be.

Steps to reproduce

1. Added nordic-mcp to mcp.json (HTTP type, no explicit auth fields)
2. Restarted CodeWhale — list_mcp_resources returned empty []
3. tool_search for nordic returned zero deferred tools
4. Had to manually grep ~/.codewhale/logs/ to discover: 401 Unauthorized, bearer token expired
5. codewhale mcp list showed auth=not-logged-in
6. codewhale mcp connect nordic-mcp failed with 401 and exited — no hint to use login
7. Foreground codewhale mcp login nordic-mcp generated the authorization URL but was killed by exec_shell's 30-second timeout while waiting for the browser callback
8. Finally ran mcp login in background mode; user completed OAuth in the browser; credentials were stored successfully

Root issues

#	Issue	Detail
1	Stale token not auto-refreshed	CodeWhale caches an expired bearer token, gets 401, and silently fails instead of clearing it and re-initiating OAuth
2	Auth errors silently swallowed	list_mcp_resources returns an empty array with no indication that authentication is required; user must dig through logs
3	mcp connect doesn't trigger OAuth	mcp connect receives 401 and exits immediately without suggesting mcp login
4	mcp login times out in foreground	OAuth requires manual browser interaction, so foreground execution is guaranteed to hit the timeout; no progress indicator or background-mode guidance
5	mcp list shows auth=not-logged-in but doesn't auto-recover	The client is aware of the unauthenticated state but takes no action

Expected behavior

• On receiving 401, automatically clear the stale token and (in TUI) prompt the user to complete OAuth login
• list_mcp_resources / list_mcp_resource_templates should return a human-readable error (e.g., {"error": "authentication_required", "server": "nordic-mcp"}) instead of an empty array when authentication fails
• mcp connect should print a helpful message on 401: "This server requires OAuth authentication. Run codewhale mcp login <name>"
• mcp login should print a clear status line after starting the local callback server ("Waiting for browser authorization…") and warn on prolonged inactivity rather than crashing

[github-actions]

Thanks @bevis-wong for the report.

This issue is staying open for maintainer triage. CodeWhale gets better because people bring us real edge cases from real machines, providers, regions, and workflows.

If you can add a reproduction, logs, version output, screenshots, or the provider/model involved, that makes it much easier for us to verify and harvest the fix. Maintainers may comment /lgtmi to mark recurring issue reporters as approved so this intake note is skipped next time.

[Hmbown]

v0.8.66 implementation prompt

This is now release-scoped for v0.8.66. Treat it as an MCP OAuth/authentication UX fix, not a broad MCP rewrite.

Desired behavior

When a URL-based MCP server requires OAuth and the stored token is missing, stale, or rejected:

• the user should see an actionable auth-required error instead of an empty resource/tool list
• codewhale mcp connect <name> should explain the likely OAuth requirement and suggest codewhale mcp login <name>
• codewhale mcp login <name> should print clear status after opening the browser/callback listener, so users know it is waiting for browser authorization
• stale stored OAuth credentials should be cleared or marked unusable after a 401/Unauthorized response so the next status/list/connect flow points toward login instead of silently retrying the same dead token
• foreground login should not look like a generic shell/tool timeout problem; docs and command output should steer users toward running it directly in a terminal or through the background shell path when invoked by an agent

Code anchors

Start here:

• crates/tui/src/mcp/oauth.rs
  • token load/save/delete: load_oauth_tokens, save_oauth_tokens, delete_oauth_tokens
  • token refresh/install path: McpOAuthRuntime::with_auth, get_token, refresh handling
  • login flow: perform_oauth_login_for_server, perform_oauth_login, callback wait around the OAuth callback timeout
  • auth status: auth_status_for_server
• crates/tui/src/mcp.rs
  • URL/Streamable HTTP server startup and discovery, where 401s currently become startup/resource discovery failure noise
• crates/tui/src/main.rs
  • mcp list, mcp connect, mcp login, mcp logout command handling and printed guidance
• crates/tui/src/tui/ui.rs
  • in-TUI /mcp login event handling and status messages
• docs/MCP.md
  • OAuth setup and login docs

Suggested patch shape

1. Add a small helper that classifies MCP auth failures from errors/status text, at minimum matching HTTP 401/Unauthorized from connect/discovery/token refresh.
2. When startup/discovery fails due to an auth failure on a URL-based MCP server with OAuth support, surface a structured/human-readable error in the MCP tool/resource listing path. Do not silently collapse to [] with no hint.
3. In mcp connect, if the failure is auth-shaped and oauth_login_support(server) returns Some, print:
   MCP server '<name>' requires OAuth authentication. Run codewhale mcp login <name>.
4. In mcp login, after the authorization URL/callback server is ready, print a status line such as:
   Waiting for browser authorization for MCP server '<name>'...
   Keep the URL output. If the wait times out, mention retrying directly from a terminal or via a background shell/task flow.
5. If a stored token causes a 401 during refresh/use, delete it or mark it invalid with a warning so mcp list reports auth=not-logged-in and the next action is obvious.
6. Add focused tests with a fake HTTP MCP/OAuth server or mocked error path. Minimum coverage:
   • stale token / 401 yields login guidance
   • mcp connect auth failure prints login guidance
   • login wait status text is emitted
   • resource/tool listing failure does not disappear as an unexplained empty list

Non-goals for v0.8.66

• Do not design a new MCP auth config format.
• Do not add a global “auto-login” flow that unexpectedly opens browsers from model tool calls.
• Do not weaken shell safety to make multiline OAuth helper scripts work; that is tracked separately in v0.8.66: clarify exec_shell multiline safety block and heredoc workflow #3827.

Validation

Run focused MCP tests first, then the relevant TUI binary filter. Suggested starting points:

cargo test -p codewhale-tui --bin codewhale-tui --locked mcp
cargo test -p codewhale-tui --bin codewhale-tui --locked oauth

If the patch touches config parsing, add cargo test -p codewhale-config --locked.