fix(mcp): add consistent callback_port for OAuth MCP servers - #4843
Open
jpelletier1 wants to merge 1 commit into
Open
fix(mcp): add consistent callback_port for OAuth MCP servers#4843jpelletier1 wants to merge 1 commit into
jpelletier1 wants to merge 1 commit into
Conversation
OAuth providers like Atlassian Rovo and GitLab require pre-registered redirect URIs. Previously, FastMCP OAuth client used a random port on each authorization attempt, causing 'invalid callback URL' errors. This fix: - Adds callback_port field to MCPOAuthAuthentication (default: 8765) - Passes callback_port to OAuth constructor in utils.py - Adds test coverage for callback_port configuration Users can now: 1. Register OAuth apps with http://localhost:8765/callback 2. Configure custom ports via callback_port if needed 3. Set callback_port=null for random port (development only) Token expiry handling was already fixed in FastMCP 3.2.0. Fixes: OpenHands/OpenHands#17077 Co-authored-by: openhands <openhands@all-hands.dev>
Contributor
|
📁 PR Artifacts Notice This PR contains a |
Contributor
Python API breakage checks — ✅ PASSEDResult: ✅ PASSED |
Contributor
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
Contributor
Coverage Report •
|
|||||||||||||||||||||||||
Collaborator
|
👋 This PR needs a couple of things fixed before OpenHands can review it:
Push an update once this is addressed and this check re-runs automatically. This is an automated check - no AI was used to generate this comment. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
HUMAN:
AGENT:
Why
OAuth-based MCP server connections were failing to refresh expired tokens, specifically affecting OAuth providers like Atlassian Rovo and GitLab that require pre-registered redirect URIs. The root cause was that FastMCP's OAuth client was using a random port on each authorization attempt, causing "invalid callback URL" errors because the port didn't match the pre-registered redirect URI.
Summary
callback_portfield toMCPOAuthAuthenticationwith default value of 8765 to ensure consistent redirect URIs across sessions_oauth_auth_from_authentication_config()to passcallback_portto FastMCP's OAuth constructorREST API contract changes
Compared with base OpenAPI
bf8a121d8a3efor public/api/**paths.Issue Number
Fixes OpenHands/OpenHands#17077
How to Test
1. Run the test suite:
All 139 MCP-related tests pass successfully.
2. Test with a real OAuth MCP server:
Configure an OAuth MCP server in your settings:
{ "your-oauth-server": { "url": "https://your-provider.com/mcp", "auth": { "strategy": "oauth2", "authentication": { "type": "oauth", "client_id": "your-client-id", "client_secret": "your-client-secret", "scopes": ["read:data"], "callback_port": 8765 } } } }Register your OAuth application with redirect URI:
http://localhost:8765/callbackThe OAuth flow should now work consistently without "invalid callback URL" errors.
3. Verify backward compatibility:
callback_portwill use the default (8765)callback_port: nullstill allows random ports (for development)Video/Screenshots
Test output showing all 139 MCP tests passing:
Design Doc
See
.pr/oauth-mcp-fix-summary.mdfor comprehensive documentation including:Type
Notes
Configuration Changes:
callback_portinMCPOAuthAuthentication(defaults to 8765)http://localhost:8765/callback(or their custom port)Token Expiry Handling:
_initialize()method properly loads and restorestoken_expiry_timefrom storageFollow-ups:
🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)
• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server
Variants & Base Images
eclipse-temurin:17-jdknikolaik/python-nodejs:python3.13-nodejs22-slimnikolaik/python-nodejs:python3.13-nodejs22-slimgolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:e0b52e3-pythonRun
All tags pushed for this build
About Multi-Architecture Support
e0b52e3-python) is a multi-arch manifest supporting both amd64 and arm64e0b52e3-python-amd64) are also available if needed