MCP servers configured in user settings do not work in automation-triggered conversations

[jpshackelford]

Problem

MCP servers configured in the user's OpenHands SaaS workspace settings work correctly in regular SaaS conversations but do not work in automation-triggered conversations.

Observed Behavior

• Regular conversations: MCP tools are available and functional
• Automation conversations: The automation script calls workspace.get_mcp_config() but returns empty/no servers, so MCP tools are not available

Expected Behavior

Automation-triggered conversations should have access to the same MCP servers configured in the user's workspace settings.

Reproduction

1. Configure an MCP server in OpenHands SaaS workspace settings
2. Verify it works in a regular conversation
3. Create an automation that attempts to use MCP tools
4. Observe that MCP tools are not available in the automation

Environment

• Automation service uses sdk_main.py template which calls workspace.get_mcp_config()
• The SDK method fetches from /api/v1/users/me endpoint

[linear]

APP-1529

[jpshackelford]

Root Cause Analysis

How automations get MCP config

1. The automation service generates a sdk_main.py script that runs inside the sandbox
2. This script calls workspace.get_mcp_config() to fetch the user's MCP configuration (sdk_main.py:168)
3. The SDK method calls GET /api/v1/users/me and reads the mcp_config field from the response
4. The SDK then tries to transform this data into the format the Agent expects

The problem: get_mcp_config() expects a format the API never returned

The API returns mcp_config in the standard fastmcp.MCPConfig format:

{
  "mcpServers": {
    "server-name": {
      "url": "https://...",
      "headers": {"Authorization": "Bearer xxx"},
      "transport": "streamable-http"
    }
  }
}

But the SDK's get_mcp_config() (workspace.py:725-769) was written expecting a different format with separate arrays (sse_servers, shttp_servers, stdio_servers), which it then transforms back into mcpServers. Since the API already returns mcpServers, the transformation finds nothing and returns empty.

The API is returning the correct format. The bug is in get_mcp_config() which should recognize and pass through the mcpServers format directly.

Why regular conversations work differently

Regular SaaS conversations don't use workspace.get_mcp_config(). Instead, live_status_app_conversation_service.py accesses user.agent_settings.mcp_config directly and passes it to the Agent (line 1076-1077).

Additional issue

The SDK also doesn't pass expose_secrets=true when calling the API, so credentials would be masked even if the format was handled correctly. Compare with get_llm() which does pass this parameter.

---

Proposed Fix

Fix in SDK (openhands-workspace/openhands/workspace/cloud/workspace.py)

• Add expose_secrets=true parameter to the API call
• Check if response already has mcpServers key and return as-is
• Keep legacy sse_servers/shttp_servers transformation as fallback for backward compat (if there are any callers using that format)

---

Question

Is there any use case where the API would return the sse_servers/shttp_servers format, or was get_mcp_config() simply implemented with incorrect assumptions? If the latter, should we remove the legacy transformation entirely or keep it as defensive code?

---

This comment was generated by an AI agent (OpenHands) on behalf of the user.

[jpshackelford]

Regression Timeline

This is confirmed as a regression. Here's the sequence of events:

Timeline

Date	Commit	Change
Mar 27	b2e583ba (SDK)	get_mcp_config() added to OpenHandsCloudWorkspace, expecting the legacy format with sse_servers, shttp_servers, stdio_servers arrays
Apr 15	b4da0e1c6 (OpenHands)	BREAKING: Settings refactored — mcp_config type changed from openhands.core.config.mcp_config.MCPConfig to fastmcp.MCPConfig (which uses mcpServers dict format)
Apr 16	f1ff98b2f (OpenHands)	SDK compat fields added to inject mcp_config into API response — but the format was already changed

What Changed

Before Apr 15 (worked):

# openhands/core/config/mcp_config.py (legacy)
class MCPConfig:
    sse_servers: list[MCPSSEServerConfig]    # [{url, api_key}, ...]
    shttp_servers: list[MCPSHTTPServerConfig] # [{url, api_key, timeout}, ...]
    stdio_servers: list[MCPStdioServerConfig] # [{name, command, args, env}, ...]

After Apr 15 (broken):

# fastmcp.mcp_config.MCPConfig (new)
class MCPConfig:
    mcpServers: dict[str, RemoteMCPServer | StdioMCPServer]
    # {"server-name": {url, transport, headers, ...}, ...}

Why Tests Didn't Catch It

The SDK tests mock the API response using the legacy format that existed when get_mcp_config() was written. When the API format changed 19 days later, no integration test caught the mismatch.

Recommended Fix

In SDK's workspace.py, add passthrough for the new format before the legacy transformation:

mcp_config_data = data.get("mcp_config")
if not mcp_config_data:
    return {}

# NEW: Passthrough if API returns mcpServers format directly
if "mcpServers" in mcp_config_data:
    return mcp_config_data

# LEGACY: Transform sse_servers/shttp_servers/stdio_servers
# ... existing code ...

Also add ?expose_secrets=true to the API URL (currently missing).

---

This comment was generated by an AI agent (OpenHands) on behalf of the user.

[jpshackelford]

Rationale Behind the Breaking Change

The change was intentional as part of a larger initiative to unify settings between the SDK and OpenHands GUI/CLI. Here's the context:

The Initiative: Programmatic Settings Schema (Issue #2228)

The goal was to eliminate manual duplication of settings across SDK, CLI, and GUI:

"Currently, when new settings are added to the SDK, they need to be manually added to the settings menus in the CLI and GUI. This results in a long time lag from when settings are implemented in the SDK to when they become available to users."

The Implementation Chain

PR	Date	Purpose
SDK #2361	Mar 30	Centralize settings schema in SDK using fastmcp.MCPConfig
SDK #2789	Apr 13	Split agent/conversation settings schemas
OpenHands #13306 (private)	Apr 15	Adopt SDK's AgentSettings (with fastmcp.MCPConfig) in OpenHands backend

Why fastmcp.MCPConfig Replaced Legacy MCPConfig

From SDK #2361:

"AgentSettings.mcp_config now uses FastMCP's typed MCPConfig at runtime. When serializing settings back to plain data, keep the output compact with exclude_none=True, exclude_defaults=True so callers still see the familiar .mcp.json-style dict shape."

The SDK standardized on fastmcp.MCPConfig (mcpServers dict format) as the canonical MCP configuration format - it's what the MCP ecosystem uses (Claude Desktop config, etc.).

Why Reverting Would Be Problematic

1. The new format is the standard - fastmcp.MCPConfig with mcpServers is the canonical MCP format
2. Frontend already uses it - The GUI settings editor expects this format
3. SDK standardized on it - All new SDK features use fastmcp.MCPConfig
4. It was a deliberate architectural choice to reduce format fragmentation

The Correct Fix

The SDK's get_mcp_config() should be updated to:

1. Recognize and passthrough the new mcpServers format (which is what the SDK itself now uses internally)
2. Keep the legacy transformation as a fallback
3. Add expose_secrets=true to the API call

This aligns get_mcp_config() with the SDK's own internal use of fastmcp.MCPConfig.

---

This comment was generated by an AI agent (OpenHands) on behalf of the user.

[jpshackelford]

Why It Works in SaaS but Not Automations

Regular SaaS conversations access the MCP config directly from the user object in the backend:

# live_status_app_conversation_service.py
user.agent_settings.mcp_config  # Direct object access

No API call, no format transformation—just passes the fastmcp.MCPConfig object straight to the Agent.

Automation-triggered conversations run in an isolated sandbox and must fetch config via API:

# sdk_main.py → workspace.get_mcp_config()
GET /api/v1/users/me  # Fetches config over HTTP

This SDK method was written expecting the legacy format (sse_servers/shttp_servers arrays), but the API was later updated to return the new mcpServers dict format. The mismatch causes an empty config to be returned.

---

This comment was generated by an AI agent (OpenHands) on behalf of @jpshackelford.