Skip to content

feat: Support OOB redirect URI in OAuth /authorize for headless clients (#383)#385

Merged
stevenweaver merged 1 commit into
masterfrom
feature/mcp-oauth-oob-headless
May 22, 2026
Merged

feat: Support OOB redirect URI in OAuth /authorize for headless clients (#383)#385
stevenweaver merged 1 commit into
masterfrom
feature/mcp-oauth-oob-headless

Conversation

@stevenweaver
Copy link
Copy Markdown
Member

Summary

  • Adds support for the standard out-of-band redirect URI urn:ietf:wg:oauth:2.0:oob in the MCP server's /authorize endpoint
  • When OOB is requested, returns an HTML page rendering the auth code for the user to copy back into their MCP client, instead of 302-redirecting to a localhost callback
  • Existing http://localhost:<port>/callback flow is unchanged

Why

Per #383, the current OAuth flow fails on headless / remote-SSH boxes: the CLI binds its callback listener to localhost on the remote host, but the user's browser is on a different machine, so the redirect to http://localhost:<port>/callback lands on the wrong host and dies (Safari Can't Connect to the Server).

OOB unblocks any MCP client that supports the standard OOB redirect URI, and gives users a manual curl /register + open /authorize + curl /token path they can drive by hand from a headless box.

Caveat: Claude Code's CLI uses localhost-only callbacks, so it won't trigger the OOB path on its own. This PR provides the server-side capability; a separate docs change (different repo) will walk users through the manual flow.

Test plan

  • npm run test-mcp — all 53 existing MCP tests pass
  • End-to-end OOB round-trip verified locally: /register/authorize?redirect_uri=urn:ietf:wg:oauth:2.0:oob returns 200 + HTML with code → /token (with PKCE verifier) returns valid access_token
  • Standard localhost-callback flow still returns 302 with the original callback URL (no regression)
  • Reviewer: verify HTML escaping for the rendered code (the code is a UUID, but escapeHtml is applied defensively)

…ts (#383)

When redirect_uri=urn:ietf:wg:oauth:2.0:oob, /authorize renders an HTML
page showing the auth code instead of 302-redirecting to a localhost
callback. Unblocks remote/SSH boxes where the browser on the user's
local machine can't reach a localhost port bound on the remote host.

Existing localhost-callback flow is unchanged.
@stevenweaver stevenweaver merged commit ff1a8f0 into master May 22, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant