Repository navigation
fix(agent-server): support public MCP OAuth callbacks - #6221
Conversation
|
📁 PR Artifacts Notice This PR adds or changes temporary PR-specific documents under |
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
left a comment
There was a problem hiding this comment.
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>
|
Follow-up regression test and fix are available in 2Zest#1. Test-only commit I also rechecked the earlier denial-error finding: This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig. |
|
Integrated follow-up PR 2Zest#1 by fast-forwarding this PR branch to This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig. |
neubig
left a comment
There was a problem hiding this comment.
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.
|
Final verification: all current-head checks on This comment was created by an AI agent (OpenHands) on behalf of Graham Neubig. |
|
Final re-review at [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. |
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) registershttp://localhost:<random port>/callbackas 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 ownlocalhost, and the result isERR_CONNECTION_REFUSEDand "Sign-in was not completed".Summary
GET /api/mcp/oauth/redirect, not included in the OpenAPI schema.state(constant-time compare) and handscode/stateto the FastMCP flow.errorfails the probe with the provider's description.web_url/OH_WEB_URLis set, the redirect URI is{web_url}/api/mcp/oauth/redirect. The path prefix is kept.callback_base_urlin 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).web_urlis set, because their redirect URIs are fixed at the provider.POST /api/mcp/oauth/callback/{job_id}relay.web_urlfield 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:callback_base_urlcompletes the probe;web_urlwith a path prefix takes precedence;web_url;callback_base_urlvalidation.End-to-end, I used a real Agent Canvas and a real browser:
ghcr.io/openhands/agent-canvas:mainimage (rev86430845). A wrapper replaced the bundled agent-server binary and ran the agent-server from an SDK checkout. Before =mainat173add70; after = this branch.Video/Screenshots
Before (main), Docker at
http://localhost:8000: the redirect goes tohttp://localhost:36217/callbackand fails withERR_CONNECTION_REFUSED.After (this PR + Canvas #19744), Docker at
http://localhost:8000: the redirect goes tohttp://localhost:8000/api/mcp/oauth/redirect, and Canvas shows "Connected — 2 tool(s) available".Before (main), behind an HTTPS reverse proxy (
https://canvas.example.test:8443)After (this PR + Canvas #19744), behind the same proxy, with no configuration
After (this PR only), with the unchanged Canvas
mainfrontend andOH_WEB_URL=https://canvas.example.test:8443: this shows the server-only path from the #18888 acceptance criteria.Design Doc
https://htmlpreview.github.io/?https://github.com/2Zest/software-agent-sdk/blob/27ed99cab36a3cadbb6c1324acdb74a153b628c9/.pr/design.html
Type
Notes
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.stateof a job that is waiting for its redirect. Each job accepts one redirect.@openhands/typescript-clientwill getcallback_base_urlin the next generated client release.