feat (backend): Add support for MCP servers natively via CodeActAgent (All-Hands-AI#7637)

Co-authored-by: trungbach <[email protected]>
Co-authored-by: quangdz1704 <[email protected]>
Co-authored-by: Xingyao Wang <[email protected]>

Author: 4 people

openhands/agenthub/codeact_agent/codeact_agent.py

@@ -62,21 +62,21 @@ def __init__(
 
         Parameters:
         - llm (LLM): The llm to be used by this agent
+        - config (AgentConfig): The configuration for this agent
         """
         super().__init__(llm, config)
         self.pending_actions: deque[Action] = deque()
         self.reset()
 
-        # Retrieve the enabled tools
-        self.tools = codeact_function_calling.get_tools(
+        built_in_tools = codeact_function_calling.get_tools(
             codeact_enable_browsing=self.config.codeact_enable_browsing,
             codeact_enable_jupyter=self.config.codeact_enable_jupyter,
             codeact_enable_llm_editor=self.config.codeact_enable_llm_editor,
             llm=self.llm,
         )
-        logger.debug(
-            f"TOOLS loaded for CodeActAgent: {', '.join([tool.get('function').get('name') for tool in self.tools])}"
-        )
+
+        self.tools = built_in_tools
+
         self.prompt_manager = PromptManager(
             prompt_dir=os.path.join(os.path.dirname(__file__), 'prompts'),
         )
@@ -137,10 +137,23 @@ def step(self, state: State) -> Action:
             'messages': self.llm.format_messages_for_llm(messages),
         }
         params['tools'] = self.tools
+
+        if self.mcp_tools:
+            # Only add tools with unique names
+            existing_names = {tool['function']['name'] for tool in params['tools']}
+            unique_mcp_tools = [
+                tool
+                for tool in self.mcp_tools
+                if tool['function']['name'] not in existing_names
+            ]
+            params['tools'] += unique_mcp_tools
+
         # log to litellm proxy if possible
         params['extra_body'] = {'metadata': state.to_llm_metadata(agent_name=self.name)}
         response = self.llm.completion(**params)
+        logger.debug(f'Response from LLM: {response}')
         actions = codeact_function_calling.response_to_actions(response)
+        logger.debug(f'Actions after response_to_actions: {actions}')
         for action in actions:
             self.pending_actions.append(action)
         return self.pending_actions.popleft()

openhands/agenthub/codeact_agent/function_calling.py

@@ -24,6 +24,7 @@
     FunctionCallNotExistsError,
     FunctionCallValidationError,
 )
+from openhands.core.logger import openhands_logger as logger
 from openhands.events.action import (
     Action,
     AgentDelegateAction,
@@ -37,9 +38,11 @@
     IPythonRunCellAction,
     MessageAction,
 )
+from openhands.events.action.mcp import McpAction
 from openhands.events.event import FileEditSource, FileReadSource
 from openhands.events.tool import ToolCallMetadata
 from openhands.llm import LLM
+from openhands.mcp import MCPClientTool
 
 
 def combine_thought(action: Action, thought: str) -> Action:
@@ -70,6 +73,7 @@ def response_to_actions(response: ModelResponse) -> list[Action]:
         # Process each tool call to OpenHands action
         for i, tool_call in enumerate(assistant_msg.tool_calls):
             action: Action
+            logger.debug(f'Tool call in function_calling.py: {tool_call}')
             try:
                 arguments = json.loads(tool_call.function.arguments)
             except json.decoder.JSONDecodeError as e:
@@ -191,6 +195,15 @@ def response_to_actions(response: ModelResponse) -> list[Action]:
                         f'Missing required argument "url" in tool call {tool_call.function.name}'
                     )
                 action = BrowseURLAction(url=arguments['url'])
+
+            # ================================================
+            # McpAction (MCP)
+            # ================================================
+            elif tool_call.function.name.endswith(MCPClientTool.postfix()):
+                action = McpAction(
+                    name=tool_call.function.name.rstrip(MCPClientTool.postfix()),
+                    arguments=tool_call.function.arguments,
+                )
             else:
                 raise FunctionCallNotExistsError(
                     f'Tool {tool_call.function.name} is not registered. (arguments: {arguments}). Please check the tool name and retry with an existing tool.'

openhands/controller/agent.py

@@ -37,6 +37,7 @@ def __init__(
         self.config = config
         self._complete = False
         self.prompt_manager: 'PromptManager' | None = None
+        self.mcp_tools: list[dict] = []
 
     @property
     def complete(self) -> bool:
@@ -111,3 +112,11 @@ def list_agents(cls) -> list[str]:
         if not bool(cls._registry):
             raise AgentNotRegisteredError()
         return list(cls._registry.keys())
+
+    def set_mcp_tools(self, mcp_tools: list[dict]) -> None:
+        """Sets the list of MCP tools for the agent.
+
+        Args:
+        - mcp_tools (list[dict]): The list of MCP tools.
+        """
+        self.mcp_tools = mcp_tools

openhands/core/cli.py

@@ -39,6 +39,7 @@
     FileEditObservation,
 )
 from openhands.io import read_task
+from openhands.mcp import fetch_mcp_tools_from_config
 
 prompt_session = PromptSession()
 
@@ -195,7 +196,8 @@ async def main(loop: asyncio.AbstractEventLoop) -> None:
     display_message(f'Session ID: {sid}')
 
     agent = create_agent(config)
-
+    mcp_tools = await fetch_mcp_tools_from_config(config.mcp)
+    agent.set_mcp_tools(mcp_tools)
     runtime = create_runtime(
         config,
         sid=sid,

openhands/core/config/app_config.py

@@ -11,6 +11,7 @@
 )
 from openhands.core.config.extended_config import ExtendedConfig
 from openhands.core.config.llm_config import LLMConfig
+from openhands.core.config.mcp_config import MCPConfig
 from openhands.core.config.sandbox_config import SandboxConfig
 from openhands.core.config.security_config import SecurityConfig
 
@@ -47,6 +48,7 @@ class AppConfig(BaseModel):
         file_uploads_allowed_extensions: Allowed file extensions. `['.*']` allows all.
         cli_multiline_input: Whether to enable multiline input in CLI. When disabled,
             input is read line by line. When enabled, input continues until /exit command.
+        mcp: MCP configuration settings.
     """
 
     llms: dict[str, LLMConfig] = Field(default_factory=dict)
@@ -88,6 +90,7 @@ class AppConfig(BaseModel):
     max_concurrent_conversations: int = Field(
         default=3
     )  # Maximum number of concurrent agent loops allowed per user
+    mcp: MCPConfig = Field(default_factory=MCPConfig)
 
     defaults_dict: ClassVar[dict] = {}
 

openhands/core/config/mcp_config.py

@@ -0,0 +1,68 @@
+from typing import List
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field, ValidationError
+
+
+class MCPSSEConfig(BaseModel):
+    """Configuration for MCP SSE (Server-Sent Events) settings.
+
+    Attributes:
+        mcp_servers: List of MCP server URLs.
+    """
+
+    mcp_servers: List[str] = Field(default_factory=list)
+
+    model_config = {'extra': 'forbid'}
+
+    def validate_servers(self) -> None:
+        """Validate that server URLs are valid and unique."""
+        # Check for duplicate server URLs
+        if len(set(self.mcp_servers)) != len(self.mcp_servers):
+            raise ValueError('Duplicate MCP server URLs are not allowed')
+
+        # Validate URLs
+        for url in self.mcp_servers:
+            try:
+                result = urlparse(url)
+                if not all([result.scheme, result.netloc]):
+                    raise ValueError(f'Invalid URL format: {url}')
+            except Exception as e:
+                raise ValueError(f'Invalid URL {url}: {str(e)}')
+
+
+class MCPConfig(BaseModel):
+    """Configuration for MCP (Message Control Protocol) settings.
+
+    Attributes:
+        sse: SSE-specific configuration.
+    """
+
+    sse: MCPSSEConfig = Field(default_factory=MCPSSEConfig)
+
+    model_config = {'extra': 'forbid'}
+
+    @classmethod
+    def from_toml_section(cls, data: dict) -> dict[str, 'MCPConfig']:
+        """
+        Create a mapping of MCPConfig instances from a toml dictionary representing the [mcp] section.
+
+        The configuration is built from all keys in data.
+
+        Returns:
+            dict[str, MCPConfig]: A mapping where the key "mcp" corresponds to the [mcp] configuration
+        """
+        # Initialize the result mapping
+        mcp_mapping: dict[str, MCPConfig] = {}
+
+        try:
+            # Create SSE config if present
+            sse_config = MCPSSEConfig.model_validate(data)
+            sse_config.validate_servers()
+
+            # Create the main MCP config
+            mcp_mapping['mcp'] = cls(sse=sse_config)
+        except ValidationError as e:
+            raise ValueError(f'Invalid MCP configuration: {e}')
+
+        return mcp_mapping

openhands/core/config/utils.py

@@ -23,6 +23,7 @@
 )
 from openhands.core.config.extended_config import ExtendedConfig
 from openhands.core.config.llm_config import LLMConfig
+from openhands.core.config.mcp_config import MCPConfig
 from openhands.core.config.sandbox_config import SandboxConfig
 from openhands.core.config.security_config import SecurityConfig
 from openhands.storage import get_file_store
@@ -202,6 +203,21 @@ def load_from_toml(cfg: AppConfig, toml_file: str = 'config.toml') -> None:
             # Re-raise ValueError from SandboxConfig.from_toml_section
             raise ValueError('Error in [sandbox] section in config.toml')
 
+    # Process MCP sections if present
+    if 'mcp' in toml_config:
+        try:
+            mcp_mapping = MCPConfig.from_toml_section(toml_config['mcp'])
+            # We only use the base mcp config for now
+            if 'mcp' in mcp_mapping:
+                cfg.mcp = mcp_mapping['mcp']
+        except (TypeError, KeyError, ValidationError) as e:
+            logger.openhands_logger.warning(
+                f'Cannot parse MCP config from toml, values have not been applied.\nError: {e}'
+            )
+        except ValueError:
+            # Re-raise ValueError from MCPConfig.from_toml_section
+            raise ValueError('Error in MCP sections in config.toml')
+
     # Process condenser section if present
     if 'condenser' in toml_config:
         try:
@@ -259,6 +275,7 @@ def load_from_toml(cfg: AppConfig, toml_file: str = 'config.toml') -> None:
         'security',
         'sandbox',
         'condenser',
+        'mcp',
     }
     for key in toml_config:
         if key.lower() not in known_sections:

openhands/core/main.py

@@ -30,6 +30,7 @@
 from openhands.events.event import Event
 from openhands.events.observation import AgentStateChangedObservation
 from openhands.io import read_input, read_task
+from openhands.mcp import fetch_mcp_tools_from_config
 from openhands.memory.memory import Memory
 from openhands.runtime.base import Runtime
 from openhands.utils.async_utils import call_async_from_sync
@@ -95,6 +96,8 @@ async def run_controller(
 
     if agent is None:
         agent = create_agent(config)
+        mcp_tools = await fetch_mcp_tools_from_config(config.mcp)
+        agent.set_mcp_tools(mcp_tools)
 
     # when the runtime is created, it will be connected and clone the selected repository
     repo_directory = None

openhands/core/schema/action.py

@@ -38,6 +38,10 @@ class ActionType(str, Enum):
     """Interact with the browser instance.
     """
 
+    MCP = 'call_tool_mcp'
+    """Interact with the MCP server.
+    """
+
     DELEGATE = 'delegate'
     """Delegates a task to another agent.
     """

openhands/core/schema/observation.py

@@ -49,3 +49,6 @@ class ObservationType(str, Enum):
 
     RECALL = 'recall'
     """Result of a recall operation. This can be the workspace context, a microagent, or other types of information."""
+
+    MCP = 'mcp'
+    """Result of a MCP Server operation"""