refactor(sdk): replace AgentBase.mcp_config dict with MCPConfig | None

Replace the untyped dict[str, Any] field with the typed MCPConfig
Pydantic model from fastmcp, aligning AgentBase with AgentSettings
which already uses MCPConfig | None.

Changes:
- AgentBase.mcp_config: dict[str, Any] -> MCPConfig | None (default None)
- Add field_validator (mode='before') to coerce dicts to MCPConfig for
  backward compatibility and normalize empty values to None
- Update field_serializer to dump MCPConfig to dict before sanitizing
- Update local_conversation.py and plugin/loader.py to bridge between
  dict (for plugin merge operations) and MCPConfig
- Update settings/model.py to pass MCPConfig directly (no more
  .model_dump())
- Update all test files for MCPConfig type

The field_validator ensures backward compatibility: callers passing
plain dicts still work. Sanitization still prevents secret leakage
through all serialization paths.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

openhands-sdk/openhands/sdk/agent/base.py

@@ -8,12 +8,14 @@
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any
 
+from fastmcp.mcp_config import MCPConfig
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
     PrivateAttr,
     field_serializer,
+    field_validator,
     model_validator,
 )
 
@@ -82,9 +84,9 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             },
         ],
     )
-    mcp_config: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Optional MCP configuration dictionary to create MCP tools.",
+    mcp_config: MCPConfig | None = Field(
+        default=None,
+        description="Optional MCP configuration to create MCP tools.",
         examples=[
             {"mcpServers": {"fetch": {"command": "uvx", "args": ["mcp-server-fetch"]}}}
         ],
@@ -230,9 +232,24 @@ def _validate_system_prompt_fields(cls, data: Any) -> Any:
         ),
     )
 
+    @field_validator("mcp_config", mode="before")
+    @classmethod
+    def _normalize_mcp_config(cls, v: Any) -> Any:
+        """Coerce dicts to MCPConfig and normalise empty values to None."""
+        if v is None or v == {}:
+            return None
+        if isinstance(v, dict):
+            return MCPConfig.model_validate(v)
+        if isinstance(v, MCPConfig) and not v.mcpServers:
+            return None
+        return v
+
     @field_serializer("mcp_config")
     @classmethod
-    def _sanitize_mcp_config(cls, v: dict[str, Any]) -> dict[str, Any]:
+    def _sanitize_mcp_config(
+        cls,
+        v: MCPConfig | None,
+    ) -> dict[str, Any]:
         """Sanitize MCP config during serialization to prevent secret leakage.
 
         MCP config may contain secrets in server headers (e.g. Authorization
@@ -243,7 +260,10 @@ def _sanitize_mcp_config(cls, v: dict[str, Any]) -> dict[str, Any]:
         The runtime agent always provides a fresh mcp_config on resume, so
         redacting here does not break conversation restore.
         """
-        return sanitize_config(v) if v else v
+        if v is None:
+            return {}
+        raw = v.model_dump(exclude_none=True, exclude_defaults=True)
+        return sanitize_config(raw) if raw else raw
 
     # Runtime materialized tools; private and non-serializable
     _tools: dict[str, ToolDefinition] = PrivateAttr(default_factory=dict)
@@ -363,7 +383,7 @@ def _initialize(self, state: ConversationState):
                 futures.append(future)
 
             # Submit MCP tools creation if configured
-            if self.mcp_config:
+            if self.mcp_config and self.mcp_config.mcpServers:
                 future = executor.submit(create_mcp_tools, self.mcp_config, 30)
                 futures.append(future)
 

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -335,7 +335,13 @@ def _ensure_plugins_loaded(self) -> None:
 
             # Start with agent's existing context and MCP config
             merged_context = self.agent.agent_context
-            merged_mcp = dict(self.agent.mcp_config) if self.agent.mcp_config else {}
+            merged_mcp = (
+                self.agent.mcp_config.model_dump(
+                    exclude_none=True, exclude_defaults=True
+                )
+                if self.agent.mcp_config
+                else {}
+            )
 
             for spec in self._plugin_specs:
                 # Fetch plugin and get resolved commit SHA
@@ -368,11 +374,17 @@ def _ensure_plugins_loaded(self) -> None:
                 if plugin.agents:
                     all_plugin_agents.extend(plugin.agents)
 
-            # Update agent with merged content
+            # Update agent with merged content; coerce merged dict to
+            # MCPConfig so the typed field is satisfied (model_copy
+            # bypasses validators).
+            from fastmcp.mcp_config import MCPConfig
+
             self.agent = self.agent.model_copy(
                 update={
                     "agent_context": merged_context,
-                    "mcp_config": merged_mcp,
+                    "mcp_config": (
+                        MCPConfig.model_validate(merged_mcp) if merged_mcp else None
+                    ),
                 }
             )
 

openhands-sdk/openhands/sdk/plugin/loader.py

@@ -66,9 +66,14 @@ def load_plugins(
     if not plugin_specs:
         return agent, None
 
-    # Start with agent's existing context and MCP config
+    # Start with agent's existing context and MCP config (as dict for
+    # plugin merge operations, then coerced back to MCPConfig).
     merged_context: AgentContext | None = agent.agent_context
-    merged_mcp: dict[str, Any] = dict(agent.mcp_config) if agent.mcp_config else {}
+    merged_mcp: dict[str, Any] = (
+        agent.mcp_config.model_dump(exclude_none=True, exclude_defaults=True)
+        if agent.mcp_config
+        else {}
+    )
     all_hooks: list[HookConfig] = []
 
     for spec in plugin_specs:
@@ -100,11 +105,16 @@ def load_plugins(
     # Combine all hook configs (concatenation semantics)
     combined_hooks = HookConfig.merge(all_hooks)
 
+    # Coerce merged dict back to MCPConfig (model_copy bypasses validators).
+    from fastmcp.mcp_config import MCPConfig
+
     # Create updated agent with merged content
     updated_agent = agent.model_copy(
         update={
             "agent_context": merged_context,
-            "mcp_config": merged_mcp,
+            "mcp_config": (
+                MCPConfig.model_validate(merged_mcp) if merged_mcp else None
+            ),
         }
     )
 

openhands-sdk/openhands/sdk/settings/model.py

@@ -552,7 +552,7 @@ def create_agent(self) -> Agent:
         return Agent(
             llm=self.llm,
             tools=self.tools,
-            mcp_config=self._serialize_mcp_config(self.mcp_config),
+            mcp_config=self.mcp_config,
             agent_context=self.agent_context,
             condenser=self.build_condenser(self.llm),
             critic=self.build_critic(),

tests/sdk/agent/test_agent_serialization.py

@@ -1,11 +1,11 @@
 """Test agent JSON serialization with DiscriminatedUnionMixin."""
 
 import json
-from typing import cast
 from unittest.mock import Mock
 
 import mcp.types
 import pytest
+from fastmcp.mcp_config import MCPConfig
 from pydantic import BaseModel
 
 from openhands.sdk.agent import Agent
@@ -62,16 +62,20 @@ def test_mcp_tool_serialization():
 def test_agent_serialization_should_include_mcp_tool() -> None:
     # Create a simple LLM instance and agent with empty tools
     llm = LLM(model="test-model", usage_id="test-llm")
-    mcp_config = {
+    mcp_config_dict = {
         "mcpServers": {
             "dummy": {"command": "echo", "args": ["dummy-mcp"]},
         }
     }
-    agent = Agent(llm=llm, tools=[], mcp_config=cast(dict[str, object], mcp_config))
+    agent = Agent(
+        llm=llm,
+        tools=[],
+        mcp_config=MCPConfig.model_validate(mcp_config_dict),
+    )
 
     # Serialize to JSON (excluding non-serializable fields)
     agent_dump = agent.model_dump()
-    assert agent_dump.get("mcp_config") == mcp_config
+    assert agent_dump.get("mcp_config") == mcp_config_dict
     agent_json = agent.model_dump_json()
 
     # Deserialize from JSON using the base class

tests/sdk/agent/test_mcp_config_sanitization.py

@@ -11,6 +11,7 @@
 import uuid
 from pathlib import Path
 
+from fastmcp.mcp_config import MCPConfig, RemoteMCPServer
 from pydantic import SecretStr
 
 from openhands.sdk import Agent
@@ -22,10 +23,43 @@
 from openhands.sdk.workspace import LocalWorkspace
 
 
-def _make_agent(**kwargs) -> Agent:
+def _make_agent(
+    mcp_config: dict | MCPConfig | None = None,
+) -> Agent:
     """Helper to create an Agent with default LLM."""
     llm = LLM(model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm")
-    return Agent(llm=llm, tools=[], **kwargs)
+    cfg: MCPConfig | None = None
+    if isinstance(mcp_config, dict):
+        cfg = MCPConfig.model_validate(mcp_config) if mcp_config else None
+    else:
+        cfg = mcp_config
+    return Agent(llm=llm, tools=[], mcp_config=cfg)
+
+
+# -- Tests for MCPConfig type coercion --
+
+
+def test_mcp_config_dict_coerced_to_mcpconfig():
+    """Passing a raw dict is coerced to MCPConfig via the field validator."""
+    agent = _make_agent(
+        mcp_config={
+            "mcpServers": {"fetch": {"command": "uvx", "args": ["mcp-server-fetch"]}}
+        }
+    )
+    assert isinstance(agent.mcp_config, MCPConfig)
+    assert "fetch" in agent.mcp_config.mcpServers
+
+
+def test_mcp_config_none_stays_none():
+    """None mcp_config remains None."""
+    agent = _make_agent(mcp_config=None)
+    assert agent.mcp_config is None
+
+
+def test_mcp_config_empty_dict_normalised_to_none():
+    """Empty dict is normalised to None."""
+    agent = _make_agent(mcp_config={})
+    assert agent.mcp_config is None
 
 
 # -- Tests for model_dump / model_dump_json redaction --
@@ -97,8 +131,8 @@ def test_mcp_config_api_key_field_redacted_on_dump():
     )
 
 
-def test_mcp_config_empty_dict_preserved():
-    """Empty mcp_config is preserved as-is (no crash)."""
+def test_mcp_config_empty_serialises_to_empty_dict():
+    """None mcp_config serialises as empty dict for backward compat."""
     agent = _make_agent(mcp_config={})
     dumped = agent.model_dump(mode="json")
     assert dumped["mcp_config"] == {}
@@ -164,15 +198,10 @@ def test_mcp_config_roundtrip_preserves_structure():
     json_str = agent.model_dump_json()
     restored = AgentBase.model_validate_json(json_str)
 
-    # Structure preserved, secrets redacted
-    assert "shttp_server" in restored.mcp_config["mcpServers"]
-    assert "stdio_server" in restored.mcp_config["mcpServers"]
-    shttp = restored.mcp_config["mcpServers"]["shttp_server"]
-    assert shttp["url"] == "https://example.com/mcp"
-    assert shttp["headers"]["Authorization"] == "<redacted>"
-    stdio = restored.mcp_config["mcpServers"]["stdio_server"]
-    assert stdio["command"] == "npx"
-    assert stdio["env"]["API_TOKEN"] == "<redacted>"
+    # Structure preserved, secrets redacted; restored as MCPConfig
+    assert isinstance(restored.mcp_config, MCPConfig)
+    assert "shttp_server" in restored.mcp_config.mcpServers
+    assert "stdio_server" in restored.mcp_config.mcpServers
 
 
 # -- Tests for ConversationStateUpdateEvent pathway --
@@ -282,28 +311,30 @@ def test_persisted_base_state_has_redacted_mcp_config():
 
 
 def test_mcp_config_runtime_value_unaffected():
-    """The in-memory mcp_config dict is NOT modified by serialization.
+    """The in-memory MCPConfig is NOT modified by serialization.
 
     field_serializer only affects the output of model_dump/model_dump_json,
     not the actual field value on the instance.
     """
-    secret_config = {
-        "mcpServers": {
-            "slack": {
-                "headers": {"Authorization": "Bearer real-token"},
+    agent = _make_agent(
+        mcp_config={
+            "mcpServers": {
+                "slack": {
+                    "url": "https://mcp.example.com",
+                    "headers": {"Authorization": "Bearer real-token"},
+                }
             }
         }
-    }
-    agent = _make_agent(mcp_config=secret_config)
+    )
 
     # Serialize (triggers field_serializer)
     _ = agent.model_dump(mode="json")
 
-    # In-memory value is untouched (frozen model, so original dict is intact)
-    assert (
-        agent.mcp_config["mcpServers"]["slack"]["headers"]["Authorization"]
-        == "Bearer real-token"
-    )
+    # In-memory MCPConfig is untouched
+    assert isinstance(agent.mcp_config, MCPConfig)
+    slack = agent.mcp_config.mcpServers["slack"]
+    assert isinstance(slack, RemoteMCPServer)
+    assert slack.headers["Authorization"] == "Bearer real-token"
 
 
 def test_multiple_servers_all_sanitized():

tests/sdk/conversation/test_local_conversation_plugins.py

@@ -256,23 +256,21 @@ def mock_create_mcp_tools(config, timeout):
         )
 
         # Before loading plugins, no MCP config should exist
-        assert (
-            conversation.agent.mcp_config is None or conversation.agent.mcp_config == {}
-        )
+        assert conversation.agent.mcp_config is None
 
         # Trigger plugin loading and agent initialization
         conversation._ensure_agent_ready()
 
         # After loading, MCP config should be merged
         assert conversation.agent.mcp_config is not None
-        assert "mcpServers" in conversation.agent.mcp_config
-        assert "test-server" in conversation.agent.mcp_config["mcpServers"]
+        assert "test-server" in conversation.agent.mcp_config.mcpServers
 
         # The agent should have been initialized with the complete MCP config
         # This verifies that create_mcp_tools was called with the plugin's MCP config
         assert len(mcp_tools_created) > 0
-        assert "mcpServers" in mcp_tools_created[-1]
-        assert "test-server" in mcp_tools_created[-1]["mcpServers"]
+        last_config = mcp_tools_created[-1]
+        assert hasattr(last_config, "mcpServers")
+        assert "test-server" in last_config.mcpServers
 
         conversation.close()