refactor(MCP): Replace `MCPRouter` with FastMCP Proxy #8877

xingyaoww · 2025-06-03T15:39:38Z

This change is worth documenting at https://docs.all-hands.dev/
Include this change in the Release Notes. If checked, you must provide an end-user friendly description for your change below

End-user friendly description of the problem this fixes or functionality this introduces.

Summarize what the PR does, explaining any non-trivial design decisions.

Replace MCPRouter with FastMCP Proxy for better reliability and support for streamable HTTP requests from latest MCP protocol (#8864)

This PR refactors the MCP Proxy implementation in the action execution server to use a dedicated MCPProxyManager class. The implementation simplifies the code by:

Extracting MCP Proxy logic to a separate module (openhands/runtime/mcp/proxy/)
Maintaining configuration in-memory instead of using file-based approach (removing MCP_CONFIG_PATH)
Improving error handling and logging
Providing a cleaner API for mounting and updating MCP tools

Link of any specific issues this addresses:

To run this PR locally, use the following command:

docker run -it --rm   -p 3000:3000   -v /var/run/docker.sock:/var/run/docker.sock   --add-host host.docker.internal:host-gateway   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:d2943d3-nikolaik   --name openhands-app-d2943d3   docker.all-hands.dev/all-hands-ai/openhands:d2943d3

iSevenDays · 2025-06-03T15:45:57Z

+1 I hope this PR can be merged quickly, as I'm having issues related to MCP reliability

…-mcprouter-to-fastmcp

- Created new MCPProxyManager class to encapsulate proxy functionality - Removed file-based configuration in favor of in-memory configuration - Updated action_execution_server.py to use the new MCPProxyManager - Added comprehensive documentation for the new module - Improved error handling and logging

xingyaoww · 2025-06-06T21:34:16Z

@OpenHands I got the following error when launching the test

2025-06-06 17:33:36 21:33:36 - openhands:DEBUG: action_execution_server.py:377 - Bash init commands completed
2025-06-06 17:33:36 21:33:36 - openhands:DEBUG: action_execution_server.py:304 - Runtime client initialized.
2025-06-06 17:33:36 21:33:36 - openhands:INFO: action_execution_server.py:666 - ActionExecutor initialized.
2025-06-06 17:33:36 21:33:36 - openhands:INFO: action_execution_server.py:676 - Initializing MCP Proxy Manager...
2025-06-06 17:33:36 21:33:36 - openhands.runtime.mcp.proxy.manager:INFO: manager.py:60 - Initializing FastMCP Proxy 'OpenHandsActionExecutionProxy'...
2025-06-06 17:33:36 ERROR: Traceback (most recent call last):
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/starlette/routing.py", line 692, in lifespan
2025-06-06 17:33:36 async with self.lifespan_context(app) as maybe_state:
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/micromamba/envs/openhands/lib/python3.12/contextlib.py", line 210, in aenter
2025-06-06 17:33:36 return await anext(self.gen)
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/code/openhands/runtime/action_execution_server.py", line 686, in lifespan
2025-06-06 17:33:36 mcp_proxy_manager.initialize()
2025-06-06 17:33:36 File "/openhands/code/openhands/runtime/mcp/proxy/manager.py", line 63, in initialize
2025-06-06 17:33:36 self.proxy = FastMCP.as_proxy(
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/fastmcp/server/server.py", line 1309, in as_proxy
2025-06-06 17:33:36 client = Client(backend)
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/fastmcp/client/client.py", line 150, in init
2025-06-06 17:33:36 self.transport = cast(ClientTransportT, infer_transport(transport))
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/fastmcp/client/transports.py", line 883, in infer_transport
2025-06-06 17:33:36 inferred_transport = MCPConfigTransport(config=transport)
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/fastmcp/client/transports.py", line 732, in init
2025-06-06 17:33:36 config = MCPConfig.from_dict(config)
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/fastmcp/utilities/mcp_config.py", line 77, in from_dict
2025-06-06 17:33:36 return cls(mcpServers=config.get("mcpServers", config))
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 File "/openhands/poetry/openhands-ai-5O4_aCHf-py3.12/lib/python3.12/site-packages/pydantic/main.py", line 253, in init
2025-06-06 17:33:36 validated_self = self.pydantic_validator.validate_python(data, self_instance=self)
2025-06-06 17:33:36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-06-06 17:33:36 pydantic_core._pydantic_core.ValidationError: 2 validation errors for MCPConfig
2025-06-06 17:33:36 mcpServers.default.StdioMCPServer.command
2025-06-06 17:33:36 Field required [type=missing, input_value={}, input_type=dict]
2025-06-06 17:33:36 For further information visit https://errors.pydantic.dev/2.11/v/missing
2025-06-06 17:33:36 mcpServers.default.RemoteMCPServer.url
2025-06-06 17:33:36 Field required [type=missing, input_value={}, input_type=dict]
2025-06-06 17:33:36 For further information visit https://errors.pydantic.dev/2.11/v/missing
2025-06-06 17:33:36
2025-06-06 17:33:36 ERROR: Application startup failed. Exiting.
2025-06-06 17:33:36 21:33:36 - openhands:DEBUG: browser_env.py:126 - SHUTDOWN recv, shutting down browser env...

openhands-ai · 2025-06-06T21:34:26Z

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

openhands-ai · 2025-06-06T21:37:13Z

I fixed the error you encountered when launching the test by addressing a configuration issue in the FastMCP integration.

The error was occurring because the MCPProxyManager class was initializing with an empty configuration dictionary that didn't meet FastMCP's requirements. The validation errors showed that either a StdioMCPServer with a 'command' field or a RemoteMCPServer with a 'url' field was required.

I modified the MCPProxyManager class to initialize with a valid StdioMCPServer configuration that includes:

A 'command' field set to 'python'
'args' field set to ['-m', 'mcp.server']
'env' field as an empty dictionary
'transport' field set to 'stdio'

This change provides the required configuration structure that FastMCP expects, which should resolve the validation errors you were seeing.

I've committed this fix and pushed it to the 'refactor-mcprouter-to-fastmcp' branch, so the PR #8877 has been updated with this change.

malhotra5

LGTM!

We should also remove mcpm and mcp from poetry

FastMCP will handle the mcp dependency from now on, which should prevent dependabot conflicts

openhands/runtime/mcp/proxy/manager.py

openhands-ai · 2025-06-08T21:45:52Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- Run Python Unit Tests

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #8877

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

Refactor MCPRouter to use FastMCP Proxy

137eec4

mamoodi assigned xingyaoww Jun 3, 2025

xingyaoww and others added 4 commits June 3, 2025 14:16

Merge commit 'a348840534dc10f20e57e80b6a80a08ac7a030f0' into refactor…

9f8bcf8

…-mcprouter-to-fastmcp

Fix test_default_activated_tools to match new MCP config structure

20b1f37

Merge branch 'main' into refactor-mcprouter-to-fastmcp

4c2c1bd

malhotra5 mentioned this pull request Jun 5, 2025

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

Merged

2 tasks

xingyaoww added 2 commits June 5, 2025 16:22

Merge branch 'main' into refactor-mcprouter-to-fastmcp

a2b5ab7

Merge branch 'main' into refactor-mcprouter-to-fastmcp

504a8c8

Fix FastMCP configuration in MCPProxyManager

51245fa

xingyaoww added 10 commits June 7, 2025 14:03

at least fixing the init issue

1ca9479

fix last bit of issue for mcp mounting

ac53e90

fix test prefix since fastmcp proxy adds prefix

4b4d3c2

fix wrong name

cad402a

fix another test

92ef1a1

Merge branch 'main' into refactor-mcprouter-to-fastmcp

a34b990

fix test

1ec4bef

fix test

7d02a86

tweak test again

a625bbc

hopefully this fixes everything

0977e72

xingyaoww marked this pull request as ready for review June 8, 2025 14:58

xingyaoww requested a review from malhotra5 June 8, 2025 18:32

malhotra5 approved these changes Jun 8, 2025

View reviewed changes

malhotra5 reviewed Jun 8, 2025

View reviewed changes

openhands/runtime/mcp/proxy/manager.py Show resolved Hide resolved

xingyaoww added 2 commits June 8, 2025 17:22

remove mcpm from dependency

2f3d471

update dependabot

8fc5307

xingyaoww enabled auto-merge (squash) June 8, 2025 21:23

Merge branch 'main' into refactor-mcprouter-to-fastmcp

d2943d3

xingyaoww merged commit d6d5499 into main Jun 8, 2025
18 checks passed

xingyaoww deleted the refactor-mcprouter-to-fastmcp branch June 8, 2025 22:03

luk2038649 mentioned this pull request Jun 9, 2025

chore(kubernetes): rm chart ziffmedia/OpenHands#1

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(MCP): Replace `MCPRouter` with FastMCP Proxy #8877

refactor(MCP): Replace `MCPRouter` with FastMCP Proxy #8877

Uh oh!

xingyaoww commented Jun 3, 2025 •

edited by github-actions bot

Loading

Uh oh!

iSevenDays commented Jun 3, 2025

Uh oh!

xingyaoww commented Jun 6, 2025

Uh oh!

openhands-ai bot commented Jun 6, 2025

Uh oh!

openhands-ai bot commented Jun 6, 2025

Uh oh!

malhotra5 left a comment

Uh oh!

Uh oh!

openhands-ai bot commented Jun 8, 2025

Uh oh!

Uh oh!

Uh oh!

refactor(MCP): Replace MCPRouter with FastMCP Proxy #8877

refactor(MCP): Replace MCPRouter with FastMCP Proxy #8877

Uh oh!

Conversation

xingyaoww commented Jun 3, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iSevenDays commented Jun 3, 2025

Uh oh!

xingyaoww commented Jun 6, 2025

Uh oh!

openhands-ai bot commented Jun 6, 2025

Uh oh!

openhands-ai bot commented Jun 6, 2025

Uh oh!

malhotra5 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

openhands-ai bot commented Jun 8, 2025

Uh oh!

Uh oh!

Uh oh!

refactor(MCP): Replace `MCPRouter` with FastMCP Proxy #8877

refactor(MCP): Replace `MCPRouter` with FastMCP Proxy #8877

xingyaoww commented Jun 3, 2025 •

edited by github-actions bot

Loading