[FEATURE] configurable MCP OAuth callback URL/host for remote & headless setups

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When authenticating a remote MCP server via /mcp, Claude Code's OAuth loopback redirect URI is hardcoded to http://localhost:PORT/callback. --callback-port / oauth.callbackPort let you fix the port, but the host is always localhost.

This breaks headless / remote setups where Claude Code runs on a server (no local browser), and the OAuth provider must redirect back to a reachable hostname (e.g. an internal admin host, a Devbox ingress URL, or a tunnel endpoint) rather than the agent box's localhost. The provider's registered redirect URI can't be localhost:PORT because the browser completing the flow is on a different machine.

Proposed Solution

Add an opt-in setting to override the OAuth redirect URI, mirroring what OpenAI Codex CLI already ships:

• mcp_oauth_callback_port — fixed callback listener port (Codex)
• mcp_oauth_callback_url — full custom redirect URI used as OAuth redirect_uri; localhost URLs bind the local interface, non-local URLs bind 0.0.0.0 so the callback can reach the host (Codex)

Refs:

• Codex config reference: https://developers.openai.com/codex/config-reference
• Codex MCP docs: https://developers.openai.com/codex/mcp

A Claude Code equivalent (e.g. a per-server oauth.callbackUrl in .mcp.json, or env var) would unblock remote/headless MCP auth.

Alternative Solutions

SSH local-forward the loopback port back to the machine with the browser (ssh -L PORT:localhost:PORT ...) and register http://localhost:PORT/callback. Works, but awkward for automated/headless deployments.

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

Claude Code on a shared headless server, developer on a laptop.

• Claude Code runs on somehost.internal.companyname.com (no GUI, no browser on the box).
• The developer works from a laptop over SSH.
• An internal MCP server (claude_design) requires OAuth login.

Today this breaks:

1. /mcp starts the OAuth flow and spins up a loopback listener on localhost:PORT on the server.
2. The provider redirects the browser to http://localhost:PORT/callback.
3. But the browser is on the laptop. The laptop's localhost is not the server's localhost, so the callback reaches nothing and auth hangs/fails.

With this feature (callbackUrl = https://somehost.internal.companyname.com:3118/callback):

1. The server binds the listener on 0.0.0.0:3118, reachable by hostname.
2. That URL is registered as the redirect URI in the provider's OAuth app.
3. The laptop browser completes login, redirects, reaches the server, and the token lands.

Other setups with the same shape:

• Cloud devbox / Codespaces — the agent runs in a container; the OAuth callback must go through the ingress URL (https://somehost.internal.companyname.com/callback), not container localhost.
• CI / automated MCP auth — headless runner with no interactive localhost browser.
• Team jump host — many developers SSH into one Claude Code host; loopback is ambiguous, a named host is clean.

The common thread: the machine running Claude Code is not the machine with the browser. Loopback assumes they are the same; this feature removes that assumption.

Additional content: Security considerations

Binding to 0.0.0.0 and delivering tokens to a non-loopback host widens the attack surface vs. the RFC 8252 loopback default. Suggest three options:

1. keep loopback the default
2. when the configured hostname's network (RFC 1918 private address space, e.g.: 10.0.0.0/8) lives on a different network interface than the default gateway, use that instead of 0.0.0.0
3. make the override explicit and opt-in, and document the tradeoff.