MCP OAuth callback uses random port, breaks in WSL2 environments

Resolved 💬 6 comments Opened Mar 18, 2026 by hungvminh Closed May 6, 2026

Problem

MCP servers requiring OAuth (Atlassian, Figma, custom HTTP MCP servers) fail to authenticate when Claude Code runs inside WSL2 on Windows 10/11.

The OAuth callback server binds to localhost:<random-port>, but the Windows browser cannot reach WSL2's localhost due to broken/absent automatic localhost relay in many corporate environments. The random ephemeral port makes it impossible to set up a persistent netsh portproxy forwarding rule.

Steps to reproduce

  1. Run Claude Code inside WSL2 on Windows 10
  2. Configure an HTTP MCP server requiring OAuth (e.g., Atlassian MCP)
  3. Trigger authentication via /plugin → Enter to auth
  4. Browser opens on Windows, user authenticates successfully
  5. OAuth provider redirects to http://localhost:<random-port>/callback?code=...
  6. Browser shows ERR_CONNECTION_REFUSED — callback never reaches Claude Code

Expected behavior

OAuth callback should complete successfully in WSL2 environments.

Suggested fix

Use a fixed or configurable OAuth callback port instead of a random ephemeral port.

For comparison, OpenCode uses a fixed OAUTH_CALLBACK_PORT = 19876, which allows a one-time netsh portproxy rule to permanently solve the WSL2 forwarding problem.

Possible implementations:

  • Fixed port (e.g., 19876 or similar) — simplest, matches OpenCode's approach
  • Configurable via env var (e.g., CLAUDE_OAUTH_PORT=19876) — most flexible
  • Configurable via settingsclaude config set oauthCallbackPort 19876

Additionally, using 127.0.0.1 instead of localhost in the redirect_uri would avoid IPv6 resolution issues on Windows (where localhost may resolve to ::1 before 127.0.0.1).

Environment

  • Claude Code: 2.1.76
  • OS: WSL2 (Ubuntu) on Windows 10 Build 19045
  • WSL version: 2.6.3.0

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗