Skip to content

fix(agent-server): support public MCP OAuth callbacks - #6221

Merged
neubig merged 6 commits into
OpenHands:mainfrom
2Zest:codex/mcp-oauth-public-callback
Nov 15, 2026
Merged

neubig merged 6 commits into
OpenHands:mainfrom
2Zest:codex/mcp-oauth-public-callback

Conversation

@2Zest

@2Zest 2Zest commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

HUMAN:
我关注到托管环境中浏览器无法访问 Agent Server 的 localhost OAuth 回调,因此选择基于现有 OH_WEB_URL 提供公开回调地址,并用一次性 job 与 OAuth state 约束回调范围;我检查了路径前缀、错误分支和本地兼容性。


AGENT:

This PR was updated by an AI agent (OpenHands) on behalf of Graham Neubig.

Why

Install-time MCP OAuth (POST /api/mcp/oauth/start) registers http://localhost:<random port>/callback as the OAuth redirect URI. FastMCP opens that port on the agent-server host. The browser can only reach it when the browser and the agent-server share one machine and one network namespace. In the Agent Canvas Docker image, only port 8000 is published (OpenHands/OpenHands#15430). In a hosted Canvas, the browser is on another machine (OpenHands/OpenHands#18888). In both cases the provider sends the pop-up to the browser's own localhost, and the result is ERR_CONNECTION_REFUSED and "Sign-in was not completed".

Summary

  • New unauthenticated route GET /api/mcp/oauth/redirect, not included in the OpenAPI schema.
    • It finds the probe job that is waiting for a redirect by its OAuth state (constant-time compare) and hands code/state to the FastMCP flow.
    • Unknown state, a job that is not waiting yet, an expired job, and a replay each get a defined 4xx error. These requests complete no job.
    • A provider error fails the probe with the provider's description.
  • Redirect URI selection:
    • When web_url / OH_WEB_URL is set, the redirect URI is {web_url}/api/mcp/oauth/redirect. The path prefix is kept.
    • Otherwise, for dynamically registered clients, it is the new optional callback_base_url in the start request: {callback_base_url}/api/mcp/oauth/redirect. Agent Canvas sends its backend origin (fix(mcp): send the browser's backend URL as the MCP OAuth callback base OpenHands#19744).
    • Pre-registered clients keep the loopback redirect unless web_url is set, because their redirect URIs are fixed at the provider.
    • A stored DCR client that was registered for another redirect URI is registered again.
  • When neither value is set, the behavior is unchanged. The flow uses the loopback callback server and the existing POST /api/mcp/oauth/callback/{job_id} relay.
  • The web_url field description now documents its OAuth role.

Issue Number

Fixes #6828

This PR is the agent-server part of OpenHands/OpenHands#18888 and OpenHands/OpenHands#15430. The Canvas part is OpenHands/OpenHands#19744.

How to Test

Automated tests (tests/agent_server/test_mcp_oauth_redirect.py, 17 tests) run a real FastMCP OAuth-protected server in-process. They cover these cases:

  • the redirect to callback_base_url completes the probe;
  • web_url with a path prefix takes precedence;
  • the loopback default is unchanged without either value;
  • a stale DCR client is registered again;
  • unknown state, a job that is not waiting yet, an expired job, a provider error, and a replay;
  • the route does not need a session key;
  • pre-registered clients follow only web_url;
  • callback_base_url validation.
uv run pytest tests/agent_server/test_mcp_oauth_redirect.py tests/agent_server/test_mcp_router.py tests/agent_server/test_config.py tests/agent_server/test_openapi_contract.py tests/agent_server/test_init_router.py
uv run pre-commit run --files <changed files>   # ruff, pycodestyle, pyright: pass

End-to-end, I used a real Agent Canvas and a real browser:

  • Canvas: the ghcr.io/openhands/agent-canvas:main image (rev 86430845). A wrapper replaced the bundled agent-server binary and ran the agent-server from an SDK checkout. Before = main at 173add70; after = this branch.
  • MCP server: a local mock OAuth-protected MCP server that uses DCR and PKCE. Its consent page shows the redirect URI.
  • Steps: Playwright drove Customize → MCP → Add custom server (SHTTP + OAuth), then Test connection, then Authorize in the pop-up.

Video/Screenshots

Before (main), Docker at http://localhost:8000: the redirect goes to http://localhost:36217/callback and fails with ERR_CONNECTION_REFUSED.

before docker

After (this PR + Canvas #19744), Docker at http://localhost:8000: the redirect goes to http://localhost:8000/api/mcp/oauth/redirect, and Canvas shows "Connected — 2 tool(s) available".

after docker

Before (main), behind an HTTPS reverse proxy (https://canvas.example.test:8443)

before proxy

After (this PR + Canvas #19744), behind the same proxy, with no configuration

after proxy

After (this PR only), with the unchanged Canvas main frontend and OH_WEB_URL=https://canvas.example.test:8443: this shows the server-only path from the #18888 acceptance criteria.

after web_url

Design Doc

https://htmlpreview.github.io/?https://github.com/2Zest/software-agent-sdk/blob/27ed99cab36a3cadbb6c1324acdb74a153b628c9/.pr/design.html

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

  • The #18888 acceptance criteria say that behavior is unchanged when no external URL is configured. That stays true for every client that does not send callback_base_url. Agent Canvas sends it so that the Docker image (#15430) works without extra configuration. Only dynamically registered clients use it, because the redirect URIs of a pre-registered client are fixed at the provider.
  • The redirect route has no session-key check because the provider redirects the user's browser to it. Access is limited to the unguessable OAuth state of a job that is waiting for its redirect. Each job accepts one redirect.
  • @openhands/typescript-client will get callback_base_url in the next generated client release.

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

📁 PR Artifacts Notice

This PR adds or changes temporary PR-specific documents under .pr/. They stay available on this branch for review; after merge, the next release PR removes .pr/ from main.

Replace the per-job public callback with a fixed /api/mcp/oauth/redirect
route that finds the waiting probe by its OAuth state. The redirect base is
web_url (OH_WEB_URL) or, for dynamically registered clients, the
callback_base_url the browser sends; pre-registered clients keep the
loopback callback unless web_url is set. Stale DCR clients registered for
another redirect URI are registered again.

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>

@all-hands-bot all-hands-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This review was posted by an AI agent (OpenHands).

Scope: agent-server changes belong here and the Canvas/frontend half is correctly split into OpenHands/OpenHands#19744. The unauthenticated GET /api/mcp/oauth/redirect route is justified by OAuth redirect-endpoint semantics (the provider sends the user's browser there, so a session key would break the flow); access is bounded by a per-flow unguessable state, one-shot accept_redirect, readiness gating on the job, and a 15-minute TTL sweep, matching what the PR describes. Verified positives: the loopback default and POST /api/mcp/oauth/callback/{job_id} relay are preserved when no external URL is configured; web_url correctly wins over callback_base_url with path-prefix handling; the redirect page escapes the provider-provided error_description via html.escape (no XSS); callback_base_url is only honored for authenticated start requests and for DCR clients, and PKCE keeps a redirected code unusable to the caller; a stale DCR client registered for another redirect URI is re-registered. The new tests exercise a real FastMCP OAuth-protected server, and the PR ships live before/after Canvas evidence. All head checks except Validate PR description pass on 27ed99ca; the failing check is the repo's readiness gate (ready-for-dev on newly linked issue #6828), owned by the deterministic automation and maintainers, not a code defect.

One material finding: when the provider denies authorization (or otherwise returns an error), the probe job never resolves. The route records the error and returns a 400 page, the overridden callback_handler then raises RuntimeError("OAuth authorization failed: ..."), fastmcp's Client._connect re-wraps it as RuntimeError("Client failed to connect: ...") (verified against fastmcp 3.2.0: _connection_failure does not pass RuntimeError through), and _probe_mcp_server catches only MCPTimeoutError/MCPError, so the exception escapes _run_oauth_probe_job (which has no guard) and job.set_result never runs. GET /api/mcp/oauth/status/{job_id} then reports authorizing until the 15-minute TTL sweep makes it 404. On main this path does not exist: the loopback callback_handler raises the typed callback error that surfaces as a failure the status route can report. The new test covers only the route's 400 page, not the probe outcome, so the PR's claim "a provider error fails the probe with the provider's description" is not delivered end to end. Suggested fix: guard _run_oauth_probe_job (catch Exception and set an MCPTestFailure), or raise/convert to MCPError in callback_handler so the existing catch path reports the denial.


The two inline locations GitHub could not resolve are restated here so the findings remain attached to this review:

Finding 1 — openhands-agent-server/openhands/agent_server/mcp_router.py, line 644 (raise RuntimeError(f"OAuth authorization failed: {error}")):
This RuntimeError is not catchable by _probe_mcp_server (which handles only MCPTimeoutError and MCPError; fastmcp's Client._connect re-wraps it via _connection_failure as another RuntimeError), so on the provider-denial path the exception escapes _run_oauth_probe_job, job.set_result never runs, and the status route reports authorizing until the TTL sweep 404s the job. Raising an MCPError (or guarding the probe thread) would let the denial surface as a normal probe failure.

Finding 2 — openhands-agent-server/openhands/agent_server/mcp_router.py, line 1114 (result = _probe_mcp_server(...) in _run_oauth_probe_job):
_run_oauth_probe_job calls _probe_mcp_server(...) with no exception guard; any non-MCPError/MCPTimeoutError exception (including the RuntimeError raised by the new callback_handler branch when the provider reports an error) kills this thread before job.set_result(...), leaving the job stuck in authorizing with no way for the UI to see the outcome. Wrapping the call in try/except Exception that sets an MCPTestFailure would close this gap for the new redirect flow and any future failure mode.

(Note for reproducers: 3 tests in test_mcp_oauth_redirect.py that bind a real local FastMCP server time out in this sandboxed workspace because localhost HTTP requests take multiple seconds here; the same tests pass in the PR's agent-server-tests CI run on this head.)

🔄 CHANGES REQUESTED

Co-authored-by: openhands <openhands@all-hands.dev>
Keep the installed client available for refresh. Reuse FastMCP stale-client retry only when a new authorization flow needs another redirect URI.

Co-authored-by: openhands <openhands@all-hands.dev>
@neubig

neubig commented Nov 15, 2026

Copy link
Copy Markdown
Member

Follow-up regression test and fix are available in 2Zest#1. Test-only commit ff76595b7 reproduces unnecessary reauthorization after a callback URL change; fix 039452194 preserves client identity through refresh and defers stale-registration retry until fresh authorization. All 18 redirect tests pass locally, including the existing stale-registration case.

I also rechecked the earlier denial-error finding: MCPClient.connect() converts RuntimeError into MCPError, and _probe_mcp_server() handles MCPError plus a final except Exception; the claimed forever-authorizing failure does not follow from current code. The refresh regression above is independently reproduced instead.

This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig.

@neubig

neubig commented Nov 15, 2026

Copy link
Copy Markdown
Member

Integrated follow-up PR 2Zest#1 by fast-forwarding this PR branch to 039452194ee98662d7769b5aa452c67efd6ae54e; both the failing-test commit and separate fix commit are retained. This updates the existing SDK PR only, not main. The issue-readiness validation now passes. Full current-head workflows required fork-run approval; those runs have been approved to execute.

This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig.

@neubig neubig left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Taste: acceptable. Reviewed original public-callback change plus the separately committed refresh regression/fix at 039452194ee98662d7769b5aa452c67efd6ae54e.

The real OAuth regression fails on test-only commit ff76595b7 and passes after the fix. All 18 redirect tests pass locally; an independent agent independently ran those 18 tests and found no material defect in the follow-up. All 17 OAuth-store tests also pass. The stale-redirect check now runs only when fresh authorization is required, preserving the original client identity for refresh and reusing FastMCP’s bounded retry for re-registration. Original Docker/proxy before-and-after evidence remains relevant; full current-head CI is running.

Correction to the earlier review: provider-denial RuntimeError is converted by MCPClient.connect and/or handled by the existing catch-all in _probe_mcp_server, so the previously alleged forever-authorizing path is not a valid finding.

[RISK ASSESSMENT] HIGH: OAuth/authentication boundary. Do not auto-merge; human OAuth-maintainer judgment remains appropriate. Code review approved; final merge is contingent on current-head CI and release/pin coordination with Canvas #19744. Key insight: redirect compatibility constrains authorization, not refresh.

This review was created by an AI agent (OpenHands) on behalf of Graham Neubig.

@neubig

neubig commented Nov 15, 2026

Copy link
Copy Markdown
Member

Final verification: all current-head checks on 039452194ee98662d7769b5aa452c67efd6ae54e are green (expected conditional skips only), including agent-server tests, cross tests, TypeScript integration, pre-commit, API compatibility, and Linux/macOS/Windows binary builds/tests. Canvas #19744 is also CI-green at 760f24ef38ca. The SDK APPROVE review is attached to this exact fixed head. No upstream PR has been merged into main; release/pin coordination and maintainer merge judgment remain.

This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig.

@neubig

neubig commented Nov 15, 2026

Copy link
Copy Markdown
Member

Final re-review at 039452194ee98662d7769b5aa452c67efd6ae54e: no material issue found. Re-read callback auth routing, state/readiness/one-shot handling, URL precedence, static-client behavior, and refresh/re-registration lifecycle. Reran all 18 redirect tests successfully. Additionally exercised real OAuth flows for (1) expired access token + rejected refresh + changed callback, which re-registers and completes authorization, and (2) provider denial, which reaches failed job status with its description. All 32 current-head checks pass (5 conditional skips). Merging on Graham’s explicit instruction after this final check.

[RISK ASSESSMENT] Authentication-sensitive; reviewed state/PKCE boundaries and real failure/recovery behavior. No remaining material finding.

This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig.

@neubig
neubig merged commit 2284096 into OpenHands:main Nov 15, 2026
37 checks passed
@enyst enyst mentioned this pull request Nov 15, 2026
1 of 5 tasks
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.

[Bug]: Install-time MCP OAuth redirect URI is unreachable when the browser is not on the agent-server host

4 participants