Fix OAuth MCP server timeouts with fastmcp 3.x compatibility

[jpshackelford]

Summary

This PR addresses issue #2184 where OAuth-based MCP servers (e.g., Notion) timeout after upgrading from v1.11 to v1.12. The root cause was that the fastmcp dependency was automatically upgraded to v3.x, and the hardcoded 30-second timeout was insufficient for OAuth servers that need browser-based authentication flows.

Alternative approach to PR #2185 - Instead of pinning fastmcp to v2.x, this PR updates the SDK to be compatible with fastmcp 3.x and adds configurable timeout support.

Changes

1. Upgrade fastmcp dependency (openhands-sdk/pyproject.toml)

   • Changed from >=2.11.3 to >=3.0.0

2. Add configurable mcp_timeout field (agent/base.py)

   • New mcp_timeout field on Agent class
   • Default increased from 30s to 60s (OAuth servers often need longer)
   • Properly documented with examples

3. Update create_mcp_tools() (mcp/utils.py)

   • Default timeout increased from 30s to 60s
   • Pass init_timeout to fastmcp Client constructor for better OAuth support
   • Updated docstring with parameter documentation

4. Use configurable timeout in Agent (agent/base.py)

   • Replaced hardcoded 30 with self.mcp_timeout in initialize()

5. Added tests

   • Tests for mcp_timeout field serialization/deserialization
   • Tests for custom timeout values being passed through
   • Tests for init_timeout being passed to MCPClient constructor

Migration

For users experiencing timeouts, you can now configure the timeout:

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

Or directly when calling create_mcp_tools:

from openhands.sdk.mcp import create_mcp_tools

client = create_mcp_tools(config, timeout=120.0)

Fixes #2184

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

@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:6ffa25c-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

• Each variant tag (e.g., 6ffa25c-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., 6ffa25c-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	40	6	85%	24–25, 28, 31, 92–93
TOTAL	19601	5334	72%