fix: MCP OAuth timeout regression - pin fastmcp <3 and add configurable timeout

[jpshackelford]

Summary

Fixes #2184 - OAuth MCP servers (e.g., Notion) timing out after upgrading from v1.11 to v1.12.

Root Cause

The fastmcp dependency was 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, which has breaking changes affecting OAuth MCP server connections.

Changes

1. Pin fastmcp dependency (pyproject.toml)

# Before
"fastmcp>=2.11.3",
# After
"fastmcp>=2.11.3,<3",

2. Add configurable MCP timeout (agent/base.py)

• New mcp_timeout field on Agent class
• Default increased from 30s to 60s (OAuth servers often need longer)
• Effective timeout is the maximum of agent's mcp_timeout and any per-server timeouts in mcp_config

3. Respect per-server timeout configuration (mcp/utils.py)

• Added _get_effective_timeout() to compute timeout from config
• Updated error message with actionable configuration hints

4. Added tests

• Test per-server timeout takes effect when higher than default
• Test default timeout used when no server timeout specified
• Test default timeout used when server timeout is lower (safety floor)

Testing

# Run the new tests
pytest tests/sdk/mcp/test_create_mcp_tool.py -k "timeout" -v

Migration

For users experiencing timeouts, either:

1. Disable the problematic server (workaround):

   openhands mcp disable Notion

2. Set a higher timeout in your agent config:

   agent = Agent(
       mcp_timeout=120.0,  # 2 minutes
       mcp_config={...}
   )

3. Set per-server timeout in mcp_config:

   {
     "mcpServers": {
       "Notion": {
         "url": "https://mcp.notion.com/mcp",
         "auth": "oauth",
         "timeout": 120
       }
     }
   }

@jpshackelford can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:04222e5-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-04222e5-python \
  ghcr.io/openhands/agent-server:04222e5-python

All tags pushed for this build

ghcr.io/openhands/agent-server:04222e5-golang-amd64
ghcr.io/openhands/agent-server:04222e5-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:04222e5-golang-arm64
ghcr.io/openhands/agent-server:04222e5-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:04222e5-java-amd64
ghcr.io/openhands/agent-server:04222e5-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:04222e5-java-arm64
ghcr.io/openhands/agent-server:04222e5-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:04222e5-python-amd64
ghcr.io/openhands/agent-server:04222e5-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:04222e5-python-arm64
ghcr.io/openhands/agent-server:04222e5-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:04222e5-golang
ghcr.io/openhands/agent-server:04222e5-java
ghcr.io/openhands/agent-server:04222e5-python

About Multi-Architecture Support

• Each variant tag (e.g., 04222e5-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 04222e5-python-amd64) are also available if needed

[github-actions]

API breakage checks (Griffe)

Result: Passed

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/agent
base.py	192	19	90%	209, 298, 302–306, 356–358, 368, 378, 386–387, 497, 534–535, 545–546
openhands-sdk/openhands/sdk/mcp
utils.py	50	6	88%	24–25, 28, 31, 109–110
TOTAL	18690	5632	69%

[jpshackelford]

@OpenHands Are you trying to both revert a fastmcp version and make the code work with that version more effectively at the same time? I think our intent was to correct issues that resulted from the fastmcp upgrade. Please see the linked issue and think carefully about the correct path forward.

[openhands-ai]

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

[openhands-ai]

Summary

Based on @jpshackelford's feedback, I simplified PR #2185 to focus on the core fix for the regression.

What was done:

1. Removed timeout configuration changes - Reverted all additions:

   • Removed mcp_timeout field from AgentBase class
   • Removed _get_effective_timeout() function from mcp/utils.py
   • Removed the 3 new timeout-related tests
   • Restored original error message format

2. Kept only the essential fix - The PR now contains a single-line change:

   -    "fastmcp>=2.11.3",
   +    "fastmcp>=2.11.3,<3",

Why:

The original PR was conflating two separate concerns:

• The fix: Pin fastmcp to v2.x to prevent the v3.0 breaking changes
• An enhancement: Add configurable MCP timeout

Since pinning fastmcp to <3 should restore the working behavior users had in v1.11, the timeout configuration is a separate improvement that can be addressed in a follow-up PR if needed.

Changes pushed:

The simplified fix has already been pushed to fix/mcp-oauth-timeout-regression. The PR diff now shows only the pyproject.toml dependency pin change.