Regression: OAuth MCP servers (e.g., Notion) timeout after upgrading to v1.12

[jpshackelford]

Description

Users of OpenHands CLI are experiencing timeout errors when connecting to OAuth-based MCP servers (such as Notion) after upgrading from v1.11 to v1.12.

Reproduction Steps

1. Configure Notion MCP in ~/.openhands/mcp.json:

   {
     "Notion": {
       "url": "https://mcp.notion.com/mcp",
       "auth": "oauth",
       "enabled": true
     }
   }

2. Upgrade OpenHands CLI to v1.12 (uv tool install openhands@latest)
3. Start a conversation with openhands
4. Observe MCPTimeoutError after 30 seconds

Expected Behavior

Notion MCP connects successfully (as it did in v1.11).

Actual Behavior

MCPTimeoutError: MCP tool listing timed out after 30 seconds.
MCP servers configured: Notion, fetch, playwright

Possible solutions:
  1. Increase the timeout value (default is 30 seconds)
  2. Check if the MCP server is running and responding
  3. Verify network connectivity to the MCP server

Root Cause

The fastmcp dependency in openhands-sdk/pyproject.toml is specified as >=2.11.3 with no upper bound. When users upgraded to v1.12, fastmcp was automatically upgraded from v2.14.5 to v3.0.2.

FastMCP 3.0 introduced breaking changes that affect:

• Transport handling for remote MCP servers
• OAuth authentication flows
• Connection timeout behavior

Additionally, the 30-second timeout is hardcoded and cannot be configured by users, despite the error message suggesting they increase it.

Version Information

• Working version: v1.11 (fastmcp 2.x)
• Broken version: v1.12 (fastmcp 3.x)

Workaround

Users can disable the problematic MCP server:

openhands mcp disable Notion

Suggested Fix

1. Pin or properly constrain the fastmcp dependency version
2. Update SDK code to be compatible with fastmcp 3.x
3. Make the MCP connection timeout configurable
4. Improve transport auto-detection for remote OAuth servers

[jpshackelford]

@jpelletier1 @jamiechicago312 FYI. I will be opening a PR for this....

[enyst]

Is this related to eager initialization?

• Feature Request: Lazy MCP Server Connection via Adapter Tool #1418

[jpshackelford]

@OpenHands #2185 takes the approach of rolling back the fastmcp version. Open a new PR that keeps the version (or updates it further) and addresses the issue reported here by adding configurable timeouts and other needed fixes.

[openhands-ai]

I'm on it! jpshackelford can track my progress at all-hands.dev

[openhands-ai]

Final Summary

I have successfully completed the task to fix issue #2184 (OAuth MCP server timeouts) by creating PR #2189: #2189

Checklist - Request Fulfillment

✅ Kept/updated fastmcp version - Changed from >=2.11.3 to >=3.0.0 (as requested, instead of rolling back like PR #2185)

✅ Added configurable timeouts - New mcp_timeout field on Agent class with 60s default

✅ Fixed hardcoded timeout - Replaced hardcoded 30 in Agent.initialize() with self.mcp_timeout

✅ Passed timeout to fastmcp Client - Added init_timeout parameter to MCPClient constructor for OAuth support

✅ Added tests - Tests for mcp_timeout serialization/deserialization and init_timeout passing

✅ All 2398 SDK tests pass with fastmcp 3.x

✅ Branch pushed - openhands/fix-mcp-timeout-fastmcp3

✅ PR created - #2189 with proper description referencing "Fixes #2184"

Files Changed (6 total)

• openhands-sdk/pyproject.toml - fastmcp version update
• openhands-sdk/openhands/sdk/agent/base.py - Added mcp_timeout field
• openhands-sdk/openhands/sdk/mcp/utils.py - Updated create_mcp_tools() with init_timeout
• tests/sdk/agent/test_agent_serialization.py - 4 new tests
• tests/sdk/mcp/test_create_mcp_tool.py - 2 new tests
• uv.lock - Updated lockfile

The changes are concise and focused only on addressing the timeout issue with fastmcp 3.x compatibility. No extraneous changes were made.

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?