Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(app_server): pass flat mcp_config shape to SDK Agent (#15159)

Tim O'Farrelld009e69bffb1
diff --git a/openhands/app_server/app_conversation/live_status_app_conversation_service.py b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
index 966e284070..77d09c7e37 100644
--- a/openhands/app_server/app_conversation/live_status_app_conversation_service.py
+++ b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
@@ -127,6 +127,7 @@ from openhands.sdk import Agent, AgentContext, LocalWorkspace
from openhands.sdk.hooks import HookConfig
from openhands.sdk.llm import LLM
from openhands.sdk.llm.llm_profile_store import PROFILE_NAME_REGEX
+from openhands.sdk.mcp.config import MCPServer
from openhands.sdk.plugin import PluginSource
from openhands.sdk.secret import LookupSecret, StaticSecret
from openhands.sdk.settings import ACPAgentSettings
@@ -1259,7 +1260,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
)
async def _add_system_mcp_servers(
- self, mcp_servers: dict[str, Any], conversation_id: UUID
+ self, mcp_servers: dict[str, MCPServer], conversation_id: UUID
) -> None:
"""Add system-generated MCP servers (default OpenHands server).
@@ -1274,20 +1275,22 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
if not self.web_url:
return
- # Add default OpenHands MCP server (includes Tavily proxy if configured)
- mcp_url = f'{self.web_url}/mcp/mcp'
- mcp_servers['default'] = {
- 'url': mcp_url,
- 'headers': {'X-OpenHands-ServerConversation-ID': str(conversation_id)},
- }
+ headers = {'X-OpenHands-ServerConversation-ID': SecretStr(str(conversation_id))}
# Add API key if available
mcp_api_key = await self.user_context.get_mcp_api_key()
if mcp_api_key:
- mcp_servers['default']['headers']['X-Session-API-Key'] = mcp_api_key
+ headers['X-Session-API-Key'] = SecretStr(mcp_api_key)
+
+ # Add default OpenHands MCP server (includes Tavily proxy if configured)
+ mcp_url = f'{self.web_url}/mcp/mcp'
+ mcp_servers['default'] = MCPServer(
+ url=mcp_url,
+ headers=headers,
+ )
def _merge_custom_mcp_config(
- self, mcp_servers: dict[str, Any], user: UserInfo
+ self, mcp_servers: dict[str, MCPServer], user: UserInfo
) -> None:
"""Merge custom MCP configuration from user settings.
@@ -1298,24 +1301,16 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
if isinstance(user.agent_settings, ACPAgentSettings):
return
- sdk_mcp = user.agent_settings.mcp_config
- if not sdk_mcp:
+ user_mcp = user.agent_settings.mcp_config
+ if not user_mcp:
return
try:
- count = len(sdk_mcp)
+ count = len(user_mcp)
_logger.info(
f'Loading custom MCP config from user settings: {count} servers'
)
-
- for name, server in sdk_mcp.items():
- mcp_servers[name] = server.model_dump(
- exclude_none=True, context={'expose_secrets': 'plaintext'}
- )
-
- _logger.info(
- f'Successfully merged custom MCP config: added {count} servers'
- )
+ mcp_servers.update(user_mcp)
except Exception as e:
_logger.error(
@@ -1329,7 +1324,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
async def _configure_llm_and_mcp(
self, user: UserInfo, llm_model: str | None, conversation_id: UUID
- ) -> tuple[LLM, dict]:
+ ) -> tuple[LLM, dict[str, MCPServer]]:
"""Configure LLM and MCP (Model Context Protocol) settings.
Args:
@@ -1338,12 +1333,13 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
conversation_id: Conversation ID forwarded to the OpenHands MCP server
Returns:
- Tuple of (configured LLM instance, MCP config dictionary)
+ Tuple of (configured LLM instance, MCP config dict in the flat
+ ``{server_name: server_dict}`` shape the SDK 1.31.x
+ ``Agent.mcp_config`` field expects)
"""
# Configure LLM
llm = self._configure_llm(user, llm_model)
- # Configure MCP - SDK expects format: {'mcpServers': {'server_name': {...}}}
mcp_servers: dict[str, Any] = {}
# Add system-generated servers (default MCP server with Tavily proxy)
@@ -1352,17 +1348,12 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
# Merge custom servers from user settings
self._merge_custom_mcp_config(mcp_servers, user)
- # Wrap in the mcpServers structure required by the SDK
- mcp_config = {'mcpServers': mcp_servers} if mcp_servers else {}
- _logger.info(f'Final MCP configuration: {sanitize_config(mcp_config)}')
-
- return llm, mcp_config
+ return llm, mcp_servers
@staticmethod
def _apply_server_agent_overrides(
agent: Agent,
agent_type: AgentType,
- mcp_config: dict,
conversation_id: UUID,
user_id: str | None,
) -> Agent:
@@ -1770,7 +1761,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
)
agent = self._apply_server_agent_overrides(
- agent, agent_type, mcp_config, conversation_id, user.id
+ agent, agent_type, conversation_id, user.id
)
# --- hooks (require remote workspace; must precede request build) -----
diff --git a/tests/unit/app_server/test_live_status_app_conversation_service.py b/tests/unit/app_server/test_live_status_app_conversation_service.py
index 0d6922485b..b4390700d7 100644
--- a/tests/unit/app_server/test_live_status_app_conversation_service.py
+++ b/tests/unit/app_server/test_live_status_app_conversation_service.py
@@ -655,17 +655,14 @@ class TestLiveStatusAppConversationService:
assert llm.api_key.get_secret_value() == self.mock_user.llm_api_key
assert llm.usage_id == 'agent'
- assert 'mcpServers' in mcp_config
- assert 'default' in mcp_config['mcpServers']
- assert (
- mcp_config['mcpServers']['default']['url']
- == 'https://test.example.com/mcp/mcp'
- )
- assert mcp_config['mcpServers']['default']['headers'][
+ assert 'default' in mcp_config
+ default_server = mcp_config['default']
+ assert default_server.url == 'https://test.example.com/mcp/mcp'
+ assert default_server.headers[
'X-OpenHands-ServerConversation-ID'
- ] == str(self.conversation_id)
+ ].get_secret_value() == str(self.conversation_id)
assert (
- mcp_config['mcpServers']['default']['headers']['X-Session-API-Key']
+ default_server.headers['X-Session-API-Key'].get_secret_value()
== 'mcp_api_key'
)
@@ -835,12 +832,13 @@ class TestLiveStatusAppConversationService:
# Assert
assert llm.model == self.mock_user.llm_model
- assert 'mcpServers' in mcp_config
- assert 'default' in mcp_config['mcpServers']
+ assert 'default' in mcp_config
- headers = mcp_config['mcpServers']['default']['headers']
- assert headers['X-OpenHands-ServerConversation-ID'] == str(self.conversation_id)
- assert 'X-Session-API-Key' not in headers
+ default_headers = mcp_config['default'].headers
+ assert default_headers[
+ 'X-OpenHands-ServerConversation-ID'
+ ].get_secret_value() == str(self.conversation_id)
+ assert 'X-Session-API-Key' not in default_headers
@pytest.mark.asyncio
async def test_configure_llm_and_mcp_without_web_url(self):
@@ -1003,7 +1001,7 @@ class TestLiveStatusAppConversationService:
agent = Agent(llm=llm, tools=[], condenser=condenser)
updated = self.service._apply_server_agent_overrides(
- agent, AgentType.DEFAULT, {}, uuid4(), 'user-1'
+ agent, AgentType.DEFAULT, uuid4(), 'user-1'
)
assert updated.llm.usage_id == 'agent'
@@ -1018,7 +1016,7 @@ class TestLiveStatusAppConversationService:
agent = Agent(llm=llm, tools=[], condenser=condenser)
updated = self.service._apply_server_agent_overrides(
- agent, AgentType.DEFAULT, {}, uuid4(), 'user-1'
+ agent, AgentType.DEFAULT, uuid4(), 'user-1'
)
# Non-openhands model: main LLM unchanged, but condenser still gets usage_id
@@ -2264,9 +2262,7 @@ class TestLiveStatusAppConversationService:
)
assert isinstance(llm, LLM)
- assert 'mcpServers' in mcp_config
-
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'default' in mcp_servers
assert 'linear' in mcp_servers
assert 'notion' in mcp_servers
@@ -2293,7 +2289,7 @@ class TestLiveStatusAppConversationService:
)
assert isinstance(llm, LLM)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'custom-http' in mcp_servers
@pytest.mark.asyncio
@@ -2317,13 +2313,15 @@ class TestLiveStatusAppConversationService:
)
assert isinstance(llm, LLM)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'my-custom-server' in mcp_servers
server_config = mcp_servers['my-custom-server']
- assert server_config['command'] == 'npx'
- assert server_config['args'] == ['-y', 'my-package']
- assert server_config['env'] == {'API_KEY': 'secret'}
+ assert server_config.command == 'npx'
+ assert server_config.args == ['-y', 'my-package']
+ assert {
+ k: v.get_secret_value() for k, v in (server_config.env or {}).items()
+ } == {'API_KEY': 'secret'}
@pytest.mark.asyncio
async def test_configure_llm_and_mcp_merges_system_and_custom_servers(self):
@@ -2348,7 +2346,7 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
# System provides default MCP server (Tavily is proxied through it if configured)
assert 'default' in mcp_servers
@@ -2379,12 +2377,19 @@ class TestLiveStatusAppConversationService:
# Assert - should still return valid config with system servers only
assert isinstance(llm, LLM)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'default' in mcp_servers
@pytest.mark.asyncio
- async def test_configure_llm_and_mcp_sdk_format_with_mcpservers_wrapper(self):
- """Test _configure_llm_and_mcp returns SDK-required format with mcpServers key."""
+ async def test_configure_llm_and_mcp_returns_flat_server_map(self):
+ """Test _configure_llm_and_mcp returns the SDK 1.31.x flat server map.
+
+ ``Agent.mcp_config`` is a ``dict[str, MCPServer]`` β€” no ``mcpServers``
+ wrapper β€” so ``_configure_llm_and_mcp`` must hand back the flat
+ ``{server_name: MCPServer}`` shape directly.
+ """
+ from openhands.sdk.mcp.config import MCPServer
+
# Arrange
self.mock_user_context.get_mcp_api_key.return_value = 'mcp_key'
@@ -2393,14 +2398,15 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- # Assert - SDK expects {'mcpServers': {...}} format
- assert 'mcpServers' in mcp_config
- assert isinstance(mcp_config['mcpServers'], dict)
+ # Assert - SDK 1.31.x ``Agent.mcp_config`` expects the flat shape.
+ assert 'mcpServers' not in mcp_config
+ assert isinstance(mcp_config, dict)
- # Verify structure matches SDK expectations
- for server_name, server_config in mcp_config['mcpServers'].items():
+ # Verify each entry is a string server name mapped to an MCPServer
+ # instance so the SDK ``Agent`` constructor can validate it directly.
+ for server_name, server_config in mcp_config.items():
assert isinstance(server_name, str)
- assert isinstance(server_config, dict)
+ assert isinstance(server_config, MCPServer)
@pytest.mark.asyncio
async def test_configure_llm_and_mcp_empty_custom_config(self):
@@ -2414,7 +2420,7 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'default' in mcp_servers
assert len(mcp_servers) == 1
@@ -2434,7 +2440,7 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'public' in mcp_servers
@pytest.mark.asyncio
@@ -2455,7 +2461,7 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'http-server' in mcp_servers
@pytest.mark.asyncio
@@ -2474,11 +2480,11 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'simple-server' in mcp_servers
server_config = mcp_servers['simple-server']
- assert server_config['command'] == 'node'
- assert server_config['args'] == ['app.js']
+ assert server_config.command == 'node'
+ assert server_config.args == ['app.js']
@pytest.mark.asyncio
async def test_configure_llm_and_mcp_multiple_servers_same_type(self):
@@ -2504,7 +2510,7 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'server1' in mcp_servers
assert 'server2' in mcp_servers
@@ -2544,15 +2550,17 @@ class TestLiveStatusAppConversationService:
self.mock_user, None, self.conversation_id
)
- mcp_servers = mcp_config['mcpServers']
+ mcp_servers = mcp_config
assert 'sse-server' in mcp_servers
assert 'http-server' in mcp_servers
assert 'stdio-server' in mcp_servers
stdio_server = mcp_servers['stdio-server']
- assert stdio_server['command'] == 'npx'
- assert stdio_server['env'] == {'TOKEN': 'value'}
+ assert stdio_server.command == 'npx'
+ assert {
+ k: v.get_secret_value() for k, v in (stdio_server.env or {}).items()
+ } == {'TOKEN': 'value'}
# ------------------------------------------------------------------ #
# Regression tests: workspace.working_dir == project_dir #