Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(frontend): read SDK 1.31.x flat mcp_config wire format (#15165)

Tim O'Farrell2dc45f5e0d19
diff --git a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
index eb835c7447..2d1050c573 100644
--- a/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
+++ b/frontend/__tests__/hooks/mutation/use-mcp-server-mutations.test.tsx
@@ -25,6 +25,11 @@ describe("MCP Server Mutation Hooks", () => {
);
};
+ // SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so the
+ // settings endpoint now returns a flat server map. ``parseMcpConfig`` still
+ // accepts the legacy wrapped shape, and ``toSdkMcpConfig`` now emits the
+ // flat shape. Tests below cover both directions.
+
describe("useAddMcpServer", () => {
it("fetches fresh settings at mutation time", async () => {
const getSettingsSpy = vi
@@ -32,9 +37,7 @@ describe("MCP Server Mutation Hooks", () => {
.mockResolvedValue({
agent_settings: {
mcp_config: {
- mcpServers: {
- existing: { url: "https://existing.com", transport: "sse" },
- },
+ existing: { url: "https://existing.com", transport: "sse" },
},
},
} as any);
@@ -59,12 +62,54 @@ describe("MCP Server Mutation Hooks", () => {
expect(getSettingsSpy).toHaveBeenCalledTimes(1);
expect(saveSettingsSpy).toHaveBeenCalledWith({
agent_settings_diff: {
+ mcp_config: expect.objectContaining({
+ existing: expect.objectContaining({ url: "https://existing.com" }),
+ }),
+ },
+ });
+ // Should not wrap in the legacy ``mcpServers`` envelope.
+ const savedConfig = (
+ saveSettingsSpy.mock.calls[0][0] as {
+ agent_settings_diff: { mcp_config: Record<string, unknown> };
+ }
+ ).agent_settings_diff.mcp_config;
+ expect(savedConfig).not.toHaveProperty("mcpServers");
+ });
+
+ it("also accepts the legacy wrapped shape on read", async () => {
+ // Backwards-compat: a server persisted before the SDK 1.31.x bump may
+ // still come back as ``{ mcpServers: {...} }`` if the value has not yet
+ // been rewritten by the backend. The frontend must still parse it.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+ agent_settings: {
mcp_config: {
- mcpServers: expect.objectContaining({
- existing: expect.objectContaining({ url: "https://existing.com" }),
- }),
+ mcpServers: {
+ existing: { url: "https://existing.com", transport: "sse" },
+ },
},
},
+ } as any);
+
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: createWrapper(),
+ });
+
+ result.current.mutate({ type: "sse", url: "https://new-server.com" });
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(saveSettingsSpy).toHaveBeenCalledWith({
+ agent_settings_diff: {
+ mcp_config: expect.objectContaining({
+ existing: expect.objectContaining({ url: "https://existing.com" }),
+ }),
+ },
});
});
@@ -93,11 +138,9 @@ describe("MCP Server Mutation Hooks", () => {
expect(saveSettingsSpy).toHaveBeenCalledWith({
agent_settings_diff: {
mcp_config: {
- mcpServers: {
- sse: {
- url: "https://first-server.com",
- transport: "sse",
- },
+ sse: {
+ url: "https://first-server.com",
+ transport: "sse",
},
},
},
@@ -128,11 +171,9 @@ describe("MCP Server Mutation Hooks", () => {
expect(saveSettingsSpy).toHaveBeenCalledWith({
agent_settings_diff: {
mcp_config: {
- mcpServers: {
- sse: {
- url: "https://server.com",
- transport: "sse",
- },
+ sse: {
+ url: "https://server.com",
+ transport: "sse",
},
},
},
@@ -145,11 +186,9 @@ describe("MCP Server Mutation Hooks", () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
agent_settings: {
mcp_config: {
- mcpServers: {
- server1: { url: "https://server1.com", transport: "sse" },
- server2: { url: "https://server2.com", transport: "sse" },
- server3: { url: "https://server3.com", transport: "sse" },
- },
+ server1: { url: "https://server1.com", transport: "sse" },
+ server2: { url: "https://server2.com", transport: "sse" },
+ server3: { url: "https://server3.com", transport: "sse" },
},
},
} as any);
@@ -171,11 +210,11 @@ describe("MCP Server Mutation Hooks", () => {
const savedPayload = saveSettingsSpy.mock.calls[0][0] as {
agent_settings_diff: {
- mcp_config: { mcpServers: Record<string, unknown> } | null;
+ mcp_config: Record<string, unknown> | null;
};
};
const savedConfig = savedPayload.agent_settings_diff.mcp_config;
- const serverNames = Object.keys(savedConfig?.mcpServers ?? {});
+ const serverNames = Object.keys(savedConfig ?? {});
expect(serverNames).toHaveLength(2);
});
@@ -209,9 +248,7 @@ describe("MCP Server Mutation Hooks", () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
agent_settings: {
mcp_config: {
- mcpServers: {
- myserver: { url: "https://old-url.com", transport: "sse" },
- },
+ myserver: { url: "https://old-url.com", transport: "sse" },
},
},
} as any);
@@ -239,13 +276,11 @@ describe("MCP Server Mutation Hooks", () => {
const savedPayload = saveSettingsSpy.mock.calls[0][0] as {
agent_settings_diff: {
- mcp_config: { mcpServers: Record<string, { url: string }> };
+ mcp_config: Record<string, { url: string }>;
};
};
const savedConfig = savedPayload.agent_settings_diff.mcp_config;
- const serverUrls = Object.values(savedConfig.mcpServers).map(
- (s) => s.url,
- );
+ const serverUrls = Object.values(savedConfig).map((s) => s.url);
expect(serverUrls).toContain("https://new-url.com");
});
});
diff --git a/frontend/__tests__/utils/mcp-config-format.test.ts b/frontend/__tests__/utils/mcp-config-format.test.ts
new file mode 100644
index 0000000000..60d73abd0c
--- /dev/null
+++ b/frontend/__tests__/utils/mcp-config-format.test.ts
@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vitest";
+import { parseMcpConfig, toSdkMcpConfig } from "#/utils/mcp-config";
+import { MCPConfig } from "#/types/settings";
+
+// SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so
+// ``GET /api/v1/settings`` now returns a flat server map directly. These tests
+// cover both the new wire format (flat) and the legacy wrapped shape, on both
+// the parse and serialize paths.
+
+describe("parseMcpConfig β€” SDK 1.31.x flat wire format", () => {
+ it("parses an shttp server from the flat shape", () => {
+ const input = {
+ shttp: { url: "https://mcp.deepwiki.com/mcp", timeout: 60 },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result).toEqual({
+ sse_servers: [],
+ stdio_servers: [],
+ shttp_servers: [
+ { name: "shttp", url: "https://mcp.deepwiki.com/mcp", timeout: 60 },
+ ],
+ });
+ });
+
+ it("parses mixed server types from the flat shape", () => {
+ const input = {
+ "sse-server": { url: "https://sse.example", transport: "sse" },
+ "http-server": { url: "https://http.example", transport: "http" },
+ "stdio-server": { command: "/usr/bin/cmd" },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers).toHaveLength(1);
+ expect(result.shttp_servers).toHaveLength(1);
+ expect(result.stdio_servers).toHaveLength(1);
+ });
+
+ it("treats mcpServers: null as the flat shape (empty server map)", () => {
+ // Defensive: a null ``mcpServers`` key on the new flat input shouldn't be
+ // confused with the legacy wrapper β€” it's just a stray key on the flat map.
+ const input = { mcpServers: null, real: { url: "https://x", transport: "sse" } };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.sse_servers).toHaveLength(1);
+ expect(result.sse_servers[0]).toMatchObject({ name: "real" });
+ });
+});
+
+describe("parseMcpConfig β€” legacy wrapped shape still works", () => {
+ it("parses an shttp server from the wrapped shape", () => {
+ const input = {
+ mcpServers: {
+ shttp: { url: "https://mcp.deepwiki.com/mcp", timeout: 60 },
+ },
+ };
+
+ const result = parseMcpConfig(input);
+
+ expect(result.shttp_servers).toHaveLength(1);
+ expect(result.shttp_servers[0]).toEqual({
+ name: "shttp",
+ url: "https://mcp.deepwiki.com/mcp",
+ timeout: 60,
+ });
+ });
+});
+
+describe("toSdkMcpConfig β€” emits flat server map", () => {
+ it("returns a flat server map without the mcpServers wrapper", () => {
+ const config: MCPConfig = {
+ sse_servers: [{ name: "my-custom-name", url: "https://example.com" }],
+ stdio_servers: [],
+ shttp_servers: [],
+ };
+
+ const result = toSdkMcpConfig(config);
+
+ expect(result).not.toHaveProperty("mcpServers");
+ expect(result).toEqual({
+ "my-custom-name": {
+ url: "https://example.com",
+ transport: "sse",
+ },
+ });
+ });
+
+ it("round-trips through parseMcpConfig unchanged", () => {
+ const config: MCPConfig = {
+ sse_servers: [{ name: "sse", url: "https://a.example" }],
+ stdio_servers: [{ name: "stdio", command: "/bin/x" }],
+ shttp_servers: [
+ { name: "shttp", url: "https://b.example", timeout: 90 },
+ ],
+ };
+
+ const serialized = toSdkMcpConfig(config);
+ const reparsed = parseMcpConfig(serialized);
+
+ expect(reparsed).toEqual(config);
+ });
+});
diff --git a/frontend/__tests__/utils/mcp-config.test.ts b/frontend/__tests__/utils/mcp-config.test.ts
index 73fdf51fdb..5e604c2029 100644
--- a/frontend/__tests__/utils/mcp-config.test.ts
+++ b/frontend/__tests__/utils/mcp-config.test.ts
@@ -174,11 +174,9 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
expect(result).toEqual({
- mcpServers: {
- "my-custom-name": {
- url: "https://example.com",
- transport: "sse",
- },
+ "my-custom-name": {
+ url: "https://example.com",
+ transport: "sse",
},
});
});
@@ -193,11 +191,9 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
expect(result).toEqual({
- mcpServers: {
- sse: {
- url: "https://example.com",
- transport: "sse",
- },
+ sse: {
+ url: "https://example.com",
+ transport: "sse",
},
});
});
@@ -215,12 +211,12 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
- expect(result?.mcpServers).toHaveProperty("sse");
- expect(result?.mcpServers).toHaveProperty("sse_1");
- expect(result?.mcpServers).toHaveProperty("sse_2");
- expect(result?.mcpServers["sse"].url).toBe("https://example1.com");
- expect(result?.mcpServers["sse_1"].url).toBe("https://example2.com");
- expect(result?.mcpServers["sse_2"].url).toBe("https://example3.com");
+ expect(result).toHaveProperty("sse");
+ expect(result).toHaveProperty("sse_1");
+ expect(result).toHaveProperty("sse_2");
+ expect(result?.["sse"].url).toBe("https://example1.com");
+ expect(result?.["sse_1"].url).toBe("https://example2.com");
+ expect(result?.["sse_2"].url).toBe("https://example3.com");
});
it("should serialize api_key as an Authorization bearer header", () => {
@@ -238,12 +234,12 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
- expect(result?.mcpServers["secure"]).toEqual({
+ expect(result?.["secure"]).toEqual({
url: "https://example.com",
transport: "sse",
headers: { Authorization: "Bearer my-secret" },
});
- expect(result?.mcpServers["shttp"]).toEqual({
+ expect(result?.["shttp"]).toEqual({
url: "https://shttp.example",
headers: { Authorization: "Bearer shttp-secret" },
});
@@ -280,12 +276,10 @@ describe("toSdkMcpConfig", () => {
const written = toSdkMcpConfig(parseMcpConfig(persisted));
expect(written).toEqual({
- mcpServers: {
- sse: {
- url: "https://example.com",
- transport: "sse",
- headers: { Authorization: "Bearer legacy-secret" },
- },
+ sse: {
+ url: "https://example.com",
+ transport: "sse",
+ headers: { Authorization: "Bearer legacy-secret" },
},
});
});
@@ -301,7 +295,7 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
- expect(result?.mcpServers["timeout"]).toEqual({
+ expect(result?.["timeout"]).toEqual({
url: "https://example.com",
timeout: 60,
});
@@ -323,7 +317,7 @@ describe("toSdkMcpConfig", () => {
const result = toSdkMcpConfig(config);
- expect(result?.mcpServers["my-stdio"]).toEqual({
+ expect(result?.["my-stdio"]).toEqual({
command: "/usr/bin/server",
args: ["--flag"],
env: { KEY: "value" },
@@ -352,9 +346,9 @@ describe("round-trip preservation", () => {
const parsed = parseMcpConfig(original);
const serialized = toSdkMcpConfig(parsed);
- expect(serialized?.mcpServers).toHaveProperty("custom-sse-name");
- expect(serialized?.mcpServers).toHaveProperty("custom-http-name");
- expect(serialized?.mcpServers).toHaveProperty("custom-stdio-name");
+ expect(serialized).toHaveProperty("custom-sse-name");
+ expect(serialized).toHaveProperty("custom-http-name");
+ expect(serialized).toHaveProperty("custom-stdio-name");
});
it("should not generate new names if original names are preserved", () => {
@@ -369,10 +363,10 @@ describe("round-trip preservation", () => {
const serialized = toSdkMcpConfig(parsed);
// Should use original names, not "sse" or "sse_1"
- expect(serialized?.mcpServers).toHaveProperty("server1");
- expect(serialized?.mcpServers).toHaveProperty("server2");
- expect(serialized?.mcpServers).not.toHaveProperty("sse");
- expect(serialized?.mcpServers).not.toHaveProperty("sse_1");
+ expect(serialized).toHaveProperty("server1");
+ expect(serialized).toHaveProperty("server2");
+ expect(serialized).not.toHaveProperty("sse");
+ expect(serialized).not.toHaveProperty("sse_1");
});
});
@@ -469,9 +463,9 @@ describe("edge cases", () => {
const parsed = parseMcpConfig(input);
const serialized = toSdkMcpConfig(parsed);
- expect(serialized?.mcpServers).toHaveProperty("server/with/slashes");
- expect(serialized?.mcpServers).toHaveProperty("server:with:colons");
- expect(serialized?.mcpServers).toHaveProperty("server with spaces");
+ expect(serialized).toHaveProperty("server/with/slashes");
+ expect(serialized).toHaveProperty("server:with:colons");
+ expect(serialized).toHaveProperty("server with spaces");
});
it("should handle cross-type name collisions", () => {
@@ -483,7 +477,7 @@ describe("edge cases", () => {
const result = toSdkMcpConfig(config);
- const names = Object.keys(result?.mcpServers || {});
+ const names = Object.keys(result || {});
expect(names).toContain("myserver");
expect(names).toContain("myserver_1");
expect(names).toHaveLength(2);
diff --git a/frontend/src/utils/mcp-config.ts b/frontend/src/utils/mcp-config.ts
index e50cbfc569..1d53afdd0e 100644
--- a/frontend/src/utils/mcp-config.ts
+++ b/frontend/src/utils/mcp-config.ts
@@ -13,7 +13,50 @@ const EMPTY_MCP_CONFIG: MCPConfig = {
};
type SdkMcpServerConfig = Record<string, SettingsValue>;
-type SdkMcpConfig = { mcpServers: Record<string, SdkMcpServerConfig> };
+
+/**
+ * Normalize the SDK wire payload to a flat server map.
+ *
+ * SDK 1.31.x dropped the ``mcpServers`` wrapper from ``model_dump``, so the
+ * ``GET /api/v1/settings`` response now returns a flat dict keyed by server
+ * name (e.g. ``{shttp: {...}}``) instead of ``{mcpServers: {shttp: {...}}}``.
+ * Older persisted settings, and clients that still send the wrapper, are
+ * accepted by the SDK's ``_normalize_mcp_config_field``, so we mirror its
+ * unwrap-or-pass-through logic here for both directions.
+ */
+function unwrapMcpServers(
+ value: Record<string, unknown>,
+): Record<string, unknown> {
+ if (
+ "mcpServers" in value &&
+ value.mcpServers &&
+ typeof value.mcpServers === "object"
+ ) {
+ return value.mcpServers as Record<string, unknown>;
+ }
+ return value;
+}
+
+/**
+ * Returns true if ``value`` already matches the frontend's parsed ``MCPConfig``
+ * shape (the grouped ``{ sse_servers, stdio_servers, shttp_servers }`` form
+ * used internally by the UI and as the placeholder on ``DEFAULT_AGENT_SETTINGS``).
+ *
+ * The check requires **exactly** the three grouping keys as arrays; a strict
+ * 3-key shape avoids misidentifying SDK-format payloads that happen to also
+ * carry an empty ``sse_servers``/``stdio_servers``/``shttp_servers`` array
+ * (e.g. a defensive frontend caller returning ``EMPTY_MCP_CONFIG`` alongside
+ * an SDK-format flat map).
+ */
+function isParsedMcpConfigShape(value: Record<string, unknown>): boolean {
+ const keys = Object.keys(value);
+ return (
+ keys.length === 3 &&
+ Array.isArray(value.sse_servers) &&
+ Array.isArray(value.stdio_servers) &&
+ Array.isArray(value.shttp_servers)
+ );
+}
function apiKeyFromAuthorizationHeader(value: unknown): string | undefined {
if (Array.isArray(value)) {
@@ -78,9 +121,13 @@ function getUniqueName(base: string, usedNames: Set<string>): string {
}
/**
- * Parse an SDK mcp_config value ({ mcpServers: { ... } }) and convert it
- * to the frontend MCPConfig format used by UI components.
- * Preserves server names for round-trip serialization.
+ * Parse an SDK mcp_config value and convert it to the frontend MCPConfig
+ * format used by UI components.
+ *
+ * Accepts both the SDK 1.31.x flat server map ({ shttp: {...} }) and the
+ * legacy wrapped shape ({ mcpServers: { shttp: {...} } }) so previously
+ * persisted settings keep loading. Preserves server names for round-trip
+ * serialization.
*/
export function parseMcpConfig(value: unknown): MCPConfig {
if (!value || typeof value !== "object") {
@@ -89,24 +136,34 @@ export function parseMcpConfig(value: unknown): MCPConfig {
const obj = value as Record<string, unknown>;
- if (
- !("mcpServers" in obj) ||
- !obj.mcpServers ||
- typeof obj.mcpServers !== "object"
- ) {
- return { ...EMPTY_MCP_CONFIG };
+ // Pass-through for the frontend's already-parsed grouped shape (used by
+ // ``DEFAULT_AGENT_SETTINGS`` and any internal caller that hands us an
+ // ``MCPConfig`` value). Detected by the three array-typed grouping keys.
+ if (isParsedMcpConfigShape(obj)) {
+ return {
+ sse_servers: obj.sse_servers as (string | MCPSSEServer)[],
+ stdio_servers: obj.stdio_servers as MCPStdioServer[],
+ shttp_servers: obj.shttp_servers as (string | MCPSHTTPServer)[],
+ };
}
+ const mcpServers = unwrapMcpServers(obj);
+
const sseServers: (string | MCPSSEServer)[] = [];
const stdioServers: MCPStdioServer[] = [];
const shttpServers: (string | MCPSHTTPServer)[] = [];
- const mcpServers = obj.mcpServers as Record<string, Record<string, unknown>>;
-
- for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
- // eslint-disable-next-line no-continue
- if (!serverConfig || typeof serverConfig !== "object") continue;
+ for (const [serverName, rawServerConfig] of Object.entries(mcpServers)) {
+ if (
+ !rawServerConfig ||
+ typeof rawServerConfig !== "object" ||
+ Array.isArray(rawServerConfig)
+ ) {
+ // eslint-disable-next-line no-continue
+ continue;
+ }
+ const serverConfig = rawServerConfig as Record<string, unknown>;
const url = serverConfig.url as string | undefined;
if (url) {
@@ -154,11 +211,18 @@ export function parseMcpConfig(value: unknown): MCPConfig {
}
/**
- * Convert the frontend MCPConfig format back to the SDK { mcpServers: { ... } }
- * shape expected by agent_settings.mcp_config on the backend.
+ * Convert the frontend MCPConfig format to the flat server map shape the
+ * SDK 1.31.x settings model emits via ``model_dump`` (``agent_settings.mcp_config``
+ * is now a ``dict[str, MCPServer]``, not a FastMCP ``MCPConfig``). The backend's
+ * ``_normalize_mcp_config_field`` still accepts the legacy ``{ mcpServers: ... }``
+ * wrapper for back-compat, so either shape round-trips; we emit the SDK-native
+ * shape to match the wire format the frontend receives.
+ *
* Uses preserved names when available, only generates names for new servers.
*/
-export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {
+export function toSdkMcpConfig(
+ config: MCPConfig,
+): Record<string, SdkMcpServerConfig> | null {
const mcpServers: Record<string, SdkMcpServerConfig> = {};
const usedNames = new Set<string>();
@@ -212,5 +276,5 @@ export function toSdkMcpConfig(config: MCPConfig): SdkMcpConfig | null {
mcpServers[name] = server;
}
- return Object.keys(mcpServers).length > 0 ? { mcpServers } : null;
+ return Object.keys(mcpServers).length > 0 ? mcpServers : null;
}