MCP OAuth callback uses random port, breaks in WSL2 environments
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
- Run Claude Code inside WSL2 on Windows 10
- Configure an HTTP MCP server requiring OAuth (e.g., Atlassian MCP)
- Trigger authentication via
/plugin→ Enter to auth - Browser opens on Windows, user authenticates successfully
- OAuth provider redirects to
http://localhost:<random-port>/callback?code=... - 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 settings —
claude 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
This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗