Skip to content

πŸ™Œ OpenHands: AI-Driven Development

(refactor): Update MCP Client to use FastMCP (#8931)

Rohit Malhotra4df3ee9d2ee1
diff --git a/openhands/mcp/client.py b/openhands/mcp/client.py
index 14957716ca..2a8ff20095 100644
--- a/openhands/mcp/client.py
+++ b/openhands/mcp/client.py
@@ -1,13 +1,12 @@
-import asyncio
-import datetime
-from contextlib import AsyncExitStack
from typing import Optional
-from mcp import ClientSession
-from mcp.client.sse import sse_client
-from mcp.client.streamable_http import streamablehttp_client
+from fastmcp import Client
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from mcp import McpError
+from mcp.types import CallToolResult
from pydantic import BaseModel, Field
+from openhands.core.config.mcp_config import MCPSHTTPServerConfig, MCPSSEServerConfig
from openhands.core.logger import openhands_logger as logger
from openhands.mcp.tool import MCPClientTool
@@ -17,8 +16,7 @@ class MCPClient(BaseModel):
A collection of tools that connects to an MCP server and manages available tools through the Model Context Protocol.
"""
- session: Optional[ClientSession] = None
- exit_stack: AsyncExitStack = AsyncExitStack()
+ client: Optional[Client] = None
description: str = 'MCP client tools for server interaction'
tools: list[MCPClientTool] = Field(default_factory=list)
tool_map: dict[str, MCPClientTool] = Field(default_factory=dict)
@@ -26,189 +24,87 @@ class MCPClient(BaseModel):
class Config:
arbitrary_types_allowed = True
- async def connect_sse(
- self,
- server_url: str,
- api_key: str | None = None,
- conversation_id: str | None = None,
- timeout: float = 30.0,
- ) -> None:
- """Connect to an MCP server using SSE transport.
-
- Args:
- server_url: The URL of the SSE server to connect to.
- timeout: Connection timeout in seconds. Default is 30 seconds.
- """
- if not server_url:
- raise ValueError('Server URL is required.')
- if self.session:
- await self.disconnect()
-
- try:
- # Use asyncio.wait_for to enforce the timeout
- async def connect_with_timeout():
- headers = (
- {
- 'Authorization': f'Bearer {api_key}',
- 's': api_key, # We need this for action execution server's MCP Router
- 'X-Session-API-Key': api_key, # We need this for Remote Runtime
- }
- if api_key
- else {}
- )
-
- if conversation_id:
- headers['X-OpenHands-Conversation-ID'] = conversation_id
-
- # Convert float timeout to datetime.timedelta for consistency
- timeout_delta = datetime.timedelta(seconds=timeout)
-
- streams_context = sse_client(
- url=server_url,
- headers=headers if headers else None,
- timeout=timeout,
- )
- streams = await self.exit_stack.enter_async_context(streams_context)
- # For SSE client, we only get read_stream and write_stream (2 values)
- read_stream, write_stream = streams
- self.session = await self.exit_stack.enter_async_context(
- ClientSession(
- read_stream, write_stream, read_timeout_seconds=timeout_delta
- )
- )
- await self._initialize_and_list_tools()
-
- # Apply timeout to the entire connection process
- await asyncio.wait_for(connect_with_timeout(), timeout=timeout)
- except asyncio.TimeoutError:
- logger.error(
- f'Connection to {server_url} timed out after {timeout} seconds'
- )
- await self.disconnect() # Clean up resources
- raise # Re-raise the TimeoutError
- except Exception as e:
- logger.error(f'Error connecting to {server_url}: {str(e)}')
- await self.disconnect() # Clean up resources
- raise
-
async def _initialize_and_list_tools(self) -> None:
"""Initialize session and populate tool map."""
- if not self.session:
+ if not self.client:
raise RuntimeError('Session not initialized.')
- await self.session.initialize()
- response = await self.session.list_tools()
+ async with self.client:
+ tools = await self.client.list_tools()
# Clear existing tools
self.tools = []
# Create proper tool objects for each server tool
- for tool in response.tools:
+ for tool in tools:
server_tool = MCPClientTool(
name=tool.name,
description=tool.description,
inputSchema=tool.inputSchema,
- session=self.session,
+ session=self.client,
)
self.tool_map[tool.name] = server_tool
self.tools.append(server_tool)
- logger.info(
- f'Connected to server with tools: {[tool.name for tool in response.tools]}'
- )
+ logger.info(f'Connected to server with tools: {[tool.name for tool in tools]}')
- async def call_tool(self, tool_name: str, args: dict):
- """Call a tool on the MCP server."""
- if tool_name not in self.tool_map:
- raise ValueError(f'Tool {tool_name} not found.')
- # The MCPClientTool is primarily for metadata; use the session to call the actual tool.
- if not self.session:
- raise RuntimeError('Client session is not available.')
- return await self.session.call_tool(name=tool_name, arguments=args)
-
- async def connect_shttp(
+ async def connect_http(
self,
- server_url: str,
- api_key: str | None = None,
+ server: MCPSSEServerConfig | MCPSHTTPServerConfig,
conversation_id: str | None = None,
timeout: float = 30.0,
- ) -> None:
- """Connect to an MCP server using StreamableHTTP transport.
-
- Args:
- server_url: The URL of the StreamableHTTP server to connect to.
- api_key: Optional API key for authentication.
- conversation_id: Optional conversation ID for session tracking.
- timeout: Connection timeout in seconds. Default is 30 seconds.
- """
+ ):
+ """Connect to MCP server using SHTTP or SSE transport"""
+ server_url = server.url
+ api_key = server.api_key
+
if not server_url:
raise ValueError('Server URL is required.')
- if self.session:
- await self.disconnect()
try:
- # Use asyncio.wait_for to enforce the timeout
- async def connect_with_timeout():
- headers = (
- {
- 'Authorization': f'Bearer {api_key}',
- 's': api_key, # We need this for action execution server's MCP Router
- 'X-Session-API-Key': api_key, # We need this for Remote Runtime
- }
- if api_key
- else {}
- )
-
- if conversation_id:
- headers['X-OpenHands-Conversation-ID'] = conversation_id
+ headers = (
+ {
+ 'Authorization': f'Bearer {api_key}',
+ 's': api_key, # We need this for action execution server's MCP Router
+ 'X-Session-API-Key': api_key, # We need this for Remote Runtime
+ }
+ if api_key
+ else {}
+ )
- # Convert float timeout to datetime.timedelta
- timeout_delta = datetime.timedelta(seconds=timeout)
- sse_read_timeout_delta = datetime.timedelta(
- seconds=timeout * 10
- ) # 10x longer for read timeout
+ if conversation_id:
+ headers['X-OpenHands-Conversation-ID'] = conversation_id
- streams_context = streamablehttp_client(
+ # Instantiate custom transports due to custom headers
+ if isinstance(server, MCPSHTTPServerConfig):
+ transport = StreamableHttpTransport(
url=server_url,
headers=headers if headers else None,
- timeout=timeout_delta,
- sse_read_timeout=sse_read_timeout_delta,
)
- streams = await self.exit_stack.enter_async_context(streams_context)
- # For StreamableHTTP client, we get read_stream, write_stream, and get_session_id (3 values)
- read_stream, write_stream, _ = streams
- self.session = await self.exit_stack.enter_async_context(
- ClientSession(
- read_stream, write_stream, read_timeout_seconds=timeout_delta
- )
+ else:
+ transport = SSETransport(
+ url=server_url,
+ headers=headers if headers else None,
)
- await self._initialize_and_list_tools()
- # Apply timeout to the entire connection process
- await asyncio.wait_for(connect_with_timeout(), timeout=timeout)
- except asyncio.TimeoutError:
- logger.error(
- f'Connection to {server_url} timed out after {timeout} seconds'
- )
- await self.disconnect() # Clean up resources
- raise # Re-raise the TimeoutError
+ self.client = Client(transport, timeout=timeout)
+
+ await self._initialize_and_list_tools()
+ except McpError as e:
+ logger.error(f'McpError connecting to {server_url}: {e}')
+ raise # Re-raise the error
+
except Exception as e:
- logger.error(f'Error connecting to {server_url}: {str(e)}')
- await self.disconnect() # Clean up resources
+ logger.error(f'Error connecting to {server_url}: {e}')
raise
- async def disconnect(self) -> None:
- """Disconnect from the MCP server and clean up resources."""
- if self.session:
- try:
- # Close the session first
- if hasattr(self.session, 'close'):
- await self.session.close()
- # Then close the exit stack
- await self.exit_stack.aclose()
- except Exception as e:
- logger.error(f'Error during disconnect: {str(e)}')
- finally:
- self.session = None
- self.tools = []
- logger.info('Disconnected from MCP server')
+ async def call_tool(self, tool_name: str, args: dict) -> CallToolResult:
+ """Call a tool on the MCP server."""
+ if tool_name not in self.tool_map:
+ raise ValueError(f'Tool {tool_name} not found.')
+ # The MCPClientTool is primarily for metadata; use the session to call the actual tool.
+ if not self.client:
+ raise RuntimeError('Client session is not available.')
+
+ async with self.client:
+ return await self.client.call_tool_mcp(name=tool_name, arguments=args)
diff --git a/openhands/mcp/utils.py b/openhands/mcp/utils.py
index 122fee46e4..c4a87f20a2 100644
--- a/openhands/mcp/utils.py
+++ b/openhands/mcp/utils.py
@@ -72,38 +72,22 @@ async def create_mcp_clients(
mcp_clients = []
for server in servers:
- is_sse = isinstance(server, MCPSSEServerConfig)
- connection_type = 'SSE' if is_sse else 'SHTTP'
+ is_shttp = isinstance(server, MCPSHTTPServerConfig)
+ connection_type = 'SHTTP' if is_shttp else 'SSE'
logger.info(
f'Initializing MCP agent for {server} with {connection_type} connection...'
)
client = MCPClient()
try:
- if is_sse:
- await client.connect_sse(
- server.url,
- api_key=server.api_key,
- conversation_id=conversation_id,
- )
- else:
- await client.connect_shttp(
- server.url,
- api_key=server.api_key,
- conversation_id=conversation_id,
- )
+ await client.connect_http(server, conversation_id=conversation_id)
# Only add the client to the list after a successful connection
mcp_clients.append(client)
except Exception as e:
logger.error(f'Failed to connect to {server}: {str(e)}', exc_info=True)
- try:
- await client.disconnect()
- except Exception as disconnect_error:
- logger.error(
- f'Error during disconnect after failed connection: {str(disconnect_error)}'
- )
+
return mcp_clients
@@ -143,13 +127,6 @@ async def fetch_mcp_tools_from_config(
# Convert tools to the format expected by the agent
mcp_tools = convert_mcp_clients_to_tools(mcp_clients)
- # Always disconnect clients to clean up resources
- for mcp_client in mcp_clients:
- try:
- await mcp_client.disconnect()
- except Exception as disconnect_error:
- logger.error(f'Error disconnecting MCP client: {str(disconnect_error)}')
-
except Exception as e:
logger.error(f'Error fetching MCP tools: {str(e)}')
return []
diff --git a/openhands/runtime/impl/action_execution/action_execution_client.py b/openhands/runtime/impl/action_execution/action_execution_client.py
index 48d29bde99..ef72fcdab7 100644
--- a/openhands/runtime/impl/action_execution/action_execution_client.py
+++ b/openhands/runtime/impl/action_execution/action_execution_client.py
@@ -471,11 +471,6 @@ class ActionExecutionClient(Runtime):
# Call the tool and return the result
# No need for try/finally since disconnect() is now just resetting state
result = await call_tool_mcp_handler(mcp_clients, action)
-
- # Reset client state (no active connections to worry about)
- for client in mcp_clients:
- await client.disconnect()
-
return result
def close(self) -> None:
diff --git a/tests/unit/test_mcp_client_timeout.py b/tests/unit/test_mcp_client_timeout.py
index 602a217d26..d731e1059b 100644
--- a/tests/unit/test_mcp_client_timeout.py
+++ b/tests/unit/test_mcp_client_timeout.py
@@ -1,49 +1,30 @@
-import asyncio
-from contextlib import asynccontextmanager
-from unittest import mock
-
import pytest
+from httpx import ConnectError
+from mcp import McpError
+from openhands.core.config.mcp_config import MCPSSEServerConfig
from openhands.mcp.client import MCPClient
@pytest.mark.asyncio
async def test_connect_sse_timeout():
- """Test that connect_sse properly times out when server_url is invalid."""
+ """Test that connect_http properly times out"""
client = MCPClient()
- # Create a mock async context manager that simulates a timeout
- @asynccontextmanager
- async def mock_slow_context(*args, **kwargs):
- # This will hang for longer than our timeout
- await asyncio.sleep(10.0)
- yield (mock.AsyncMock(), mock.AsyncMock())
+ server = MCPSSEServerConfig(url='http://server1:8080')
- # Patch the sse_client function to return our slow context manager
- with mock.patch(
- 'openhands.mcp.client.sse_client', return_value=mock_slow_context()
- ):
- # Test with a very short timeout
- with pytest.raises(asyncio.TimeoutError):
- await client.connect_sse('http://example.com', timeout=0.1)
+ # Test with a very short timeout
+ with pytest.raises(McpError, match='Timed out'):
+ await client.connect_http(server, timeout=0.001)
@pytest.mark.asyncio
-async def test_connect_streamable_http_timeout():
- """Test that connect_streamable_http properly times out when server_url is invalid."""
+async def test_connect_sse_invalid_url():
+ """Test that connect_http hits error when server_url is invalid."""
client = MCPClient()
- # Create a mock async context manager that simulates a timeout
- @asynccontextmanager
- async def mock_slow_context(*args, **kwargs):
- # This will hang for longer than our timeout
- await asyncio.sleep(10.0)
- yield (mock.AsyncMock(), mock.AsyncMock(), mock.AsyncMock())
-
- # Patch the streamablehttp_client function to return our slow context manager
- with mock.patch(
- 'openhands.mcp.client.streamablehttp_client', return_value=mock_slow_context()
- ):
- # Test with a very short timeout
- with pytest.raises(asyncio.TimeoutError):
- await client.connect_shttp('http://example.com', timeout=0.1)
+ server = MCPSSEServerConfig(url='http://server1:8080')
+
+ # Test with larger timeout
+ with pytest.raises(ConnectError):
+ await client.connect_http(server, timeout=1)
diff --git a/tests/unit/test_mcp_create_clients_timeout.py b/tests/unit/test_mcp_create_clients_timeout.py
index 53454c2b5f..f25dfc9fa5 100644
--- a/tests/unit/test_mcp_create_clients_timeout.py
+++ b/tests/unit/test_mcp_create_clients_timeout.py
@@ -2,6 +2,7 @@ import asyncio
import pytest
+from openhands.core.config.mcp_config import MCPSSEServerConfig
from openhands.mcp.client import MCPClient
from openhands.mcp.utils import create_mcp_clients
@@ -10,22 +11,24 @@ from openhands.mcp.utils import create_mcp_clients
async def test_create_mcp_clients_timeout_with_invalid_url():
"""Test that create_mcp_clients properly times out when given an invalid URL."""
# Use a non-existent domain that should cause a connection timeout
- invalid_url = 'http://non-existent-domain-that-will-timeout.invalid'
+ server = MCPSSEServerConfig(
+ url='http://non-existent-domain-that-will-timeout.invalid'
+ )
- # Temporarily modify the default timeout for the MCPClient.connect_sse method
- original_connect_sse = MCPClient.connect_sse
+ # Temporarily modify the default timeout for the MCPClient.connect_http method
+ original_connect_connect_http = MCPClient.connect_http
# Create a wrapper that calls the original method but with a shorter timeout
- async def connect_sse_with_short_timeout(self, server_url, timeout=30.0):
- return await original_connect_sse(self, server_url, timeout=0.5)
+ async def connect_http_with_short_timeout(self, server_url, timeout=30.0):
+ return await original_connect_connect_http(self, server_url, timeout=0.5)
try:
# Replace the method with our wrapper
- MCPClient.connect_sse = connect_sse_with_short_timeout
+ MCPClient.connect_http = connect_http_with_short_timeout
# Call create_mcp_clients with the invalid URL
start_time = asyncio.get_event_loop().time()
- clients = await create_mcp_clients([invalid_url], [])
+ clients = await create_mcp_clients([server], [])
end_time = asyncio.get_event_loop().time()
# Verify that no clients were successfully connected
@@ -38,7 +41,7 @@ async def test_create_mcp_clients_timeout_with_invalid_url():
)
finally:
# Restore the original method
- MCPClient.connect_sse = original_connect_sse
+ MCPClient.connect_http = original_connect_connect_http
@pytest.mark.asyncio
@@ -48,16 +51,16 @@ async def test_create_mcp_clients_with_unreachable_host():
# This IP is in the TEST-NET-1 range (192.0.2.0/24) reserved for documentation and examples
unreachable_url = 'http://192.0.2.1:8080'
- # Temporarily modify the default timeout for the MCPClient.connect_sse method
- original_connect_sse = MCPClient.connect_sse
+ # Temporarily modify the default timeout for the MCPClient.connect_http method
+ original_connect_http = MCPClient.connect_http
# Create a wrapper that calls the original method but with a shorter timeout
- async def connect_sse_with_short_timeout(self, server_url, timeout=30.0):
- return await original_connect_sse(self, server_url, timeout=1.0)
+ async def connect_http_with_short_timeout(self, server_url, timeout=30.0):
+ return await original_connect_http(self, server_url, timeout=1.0)
try:
# Replace the method with our wrapper
- MCPClient.connect_sse = connect_sse_with_short_timeout
+ MCPClient.connect_http = connect_http_with_short_timeout
# Call create_mcp_clients with the unreachable URL
start_time = asyncio.get_event_loop().time()
@@ -73,4 +76,4 @@ async def test_create_mcp_clients_with_unreachable_host():
)
finally:
# Restore the original method
- MCPClient.connect_sse = original_connect_sse
+ MCPClient.connect_http = original_connect_http
diff --git a/tests/unit/test_mcp_timeout.py b/tests/unit/test_mcp_timeout.py
index 898820276f..91cf45a0a0 100644
--- a/tests/unit/test_mcp_timeout.py
+++ b/tests/unit/test_mcp_timeout.py
@@ -13,12 +13,12 @@ async def test_sse_connection_timeout():
# Create a mock MCPClient
mock_client = mock.MagicMock(spec=MCPClient)
- # Configure the mock to raise a TimeoutError when connect_sse is called
- async def mock_connect_sse(*args, **kwargs):
+ # Configure the mock to raise a TimeoutError when connect_http is called
+ async def mock_connect_http(*args, **kwargs):
await asyncio.sleep(0.1) # Simulate some delay
raise asyncio.TimeoutError('Connection timed out')
- mock_client.connect_sse.side_effect = mock_connect_sse
+ mock_client.connect_http.side_effect = mock_connect_http
mock_client.disconnect = mock.AsyncMock()
# Mock the MCPClient constructor to return our mock
@@ -35,11 +35,8 @@ async def test_sse_connection_timeout():
# Verify that no clients were successfully connected
assert len(clients) == 0
- # Verify that connect_sse was called for each server
- assert mock_client.connect_sse.call_count == 2
-
- # Verify that disconnect was called for each failed connection
- assert mock_client.disconnect.call_count == 2
+ # Verify that connect_http was called for each server
+ assert mock_client.connect_http.call_count == 2
@pytest.mark.asyncio
diff --git a/tests/unit/test_mcp_utils.py b/tests/unit/test_mcp_utils.py
index 91e479a447..240bfb27f5 100644
--- a/tests/unit/test_mcp_utils.py
+++ b/tests/unit/test_mcp_utils.py
@@ -24,7 +24,7 @@ async def test_create_mcp_clients_success(mock_mcp_client):
# Setup mock
mock_client_instance = AsyncMock()
mock_mcp_client.return_value = mock_client_instance
- mock_client_instance.connect_sse = AsyncMock()
+ mock_client_instance.connect_http = AsyncMock()
# Test with two servers
server_configs = [
@@ -38,12 +38,12 @@ async def test_create_mcp_clients_success(mock_mcp_client):
assert len(clients) == 2
assert mock_mcp_client.call_count == 2
- # Check that connect_sse was called with correct parameters
- mock_client_instance.connect_sse.assert_any_call(
- 'http://server1:8080', api_key=None, conversation_id=None
+ # Check that connect_http was called with correct parameters
+ mock_client_instance.connect_http.assert_any_call(
+ server_configs[0], conversation_id=None
)
- mock_client_instance.connect_sse.assert_any_call(
- 'http://server2:8080', api_key='test-key', conversation_id=None
+ mock_client_instance.connect_http.assert_any_call(
+ server_configs[1], conversation_id=None
)
@@ -56,11 +56,10 @@ async def test_create_mcp_clients_connection_failure(mock_mcp_client):
mock_mcp_client.return_value = mock_client_instance
# First connection succeeds, second fails
- mock_client_instance.connect_sse.side_effect = [
+ mock_client_instance.connect_http.side_effect = [
None, # Success
Exception('Connection failed'), # Failure
]
- mock_client_instance.disconnect = AsyncMock()
server_configs = [
MCPSSEServerConfig(url='http://server1:8080'),
@@ -71,7 +70,6 @@ async def test_create_mcp_clients_connection_failure(mock_mcp_client):
# Verify only one client was successfully created
assert len(clients) == 1
- assert mock_client_instance.disconnect.call_count == 1
def test_convert_mcp_clients_to_tools_empty():