Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: migrate Linear integration to streamable HTTP /mcp endpoint (#1132)

Hiep Le614477e5c959
diff --git a/__tests__/components/features/mcp-page/install-server-modal.test.tsx b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
index 21f7730f47..8473b4429e 100644
--- a/__tests__/components/features/mcp-page/install-server-modal.test.tsx
+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
@@ -11,6 +11,7 @@ import {
INTEGRATION_CATALOG as MCP_MARKETPLACE,
type IntegrationCatalogEntry as MarketplaceEntry,
} from "@openhands/extensions/integrations";
+import { getMcpMarketplaceCatalog } from "#/utils/mcp-marketplace-utils";
function renderWith(ui: React.ReactNode) {
return render(ui, {
@@ -207,6 +208,53 @@ describe("InstallServerModal", () => {
await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
});
+ it("installs Linear over streamable HTTP with the api key as a bearer credential", async () => {
+ // Arrange: the marketplace serves the patched Linear entry (shttp
+ // /mcp endpoint, bearer auth) β€” the UI must never touch the removed
+ // /sse transport.
+ const linear = getMcpMarketplaceCatalog(MCP_MARKETPLACE).find(
+ (e) => e.id === "linear",
+ )!;
+ const testSpy = vi
+ .spyOn(McpService, "testServer")
+ .mockResolvedValue({ ok: true, tools: [] });
+ const getSpy = vi
+ .spyOn(SettingsService, "getSettings")
+ .mockResolvedValue(MOCK_DEFAULT_USER_SETTINGS);
+ const saveSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ renderWith(<InstallServerModal entry={linear} onClose={vi.fn()} />);
+ await screen.findByTestId("mcp-install-modal");
+ // Wait for useSettings() so the add-mcp-server mutation doesn't bail.
+ await waitFor(() => expect(getSpy).toHaveBeenCalled());
+
+ // Act: provide the optional Linear API key and install.
+ fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+ target: { value: "lin_api_secret" },
+ });
+ fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+ // Assert: both the pre-flight test and the persisted config target
+ // the new endpoint over streamable HTTP with the bearer credential.
+ await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+ expect(testSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: "shttp",
+ url: "https://mcp.linear.app/mcp",
+ api_key: "lin_api_secret",
+ }),
+ );
+ const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+ .agent_settings_diff as {
+ mcp_config: { mcpServers: Record<string, unknown> };
+ };
+ expect(sent.mcp_config.mcpServers).toMatchObject({
+ shttp: { url: "https://mcp.linear.app/mcp", auth: "lin_api_secret" },
+ });
+ });
+
it("closes from the top-right close button", async () => {
const onClose = vi.fn();
const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
diff --git a/__tests__/constants/extensions-catalogs.test.ts b/__tests__/constants/extensions-catalogs.test.ts
index 3233e40b45..d62605fb9b 100644
--- a/__tests__/constants/extensions-catalogs.test.ts
+++ b/__tests__/constants/extensions-catalogs.test.ts
@@ -34,6 +34,43 @@ describe("OpenHands extensions catalogs", () => {
);
});
+ it("patches Linear to the streamable HTTP /mcp endpoint with bearer auth", () => {
+ // Arrange: upstream still ships the removed /sse SSE transport; the
+ // marketplace catalog must serve the patched entry instead.
+ const catalog = getMcpMarketplaceCatalog(INTEGRATION_CATALOG);
+
+ // Act
+ const linear = catalog.find((entry) => entry.id === "linear")!;
+
+ // Assert
+ expect(getDefaultMcpTransport(linear)).toEqual({
+ kind: "shttp",
+ url: "https://mcp.linear.app/mcp",
+ apiKeyOptional: true,
+ });
+ expect(linear.docsUrl).toBe("https://linear.app/docs/mcp");
+ const mcpOption = linear.connectionOptions.find(
+ (option) => option.transport?.kind === "shttp",
+ );
+ expect(mcpOption?.auth.strategy).toBe("bearer");
+ });
+
+ it("does not mutate the imported catalog when patching Linear", () => {
+ // Arrange/Act: run the patch, then inspect the raw imported entry.
+ getMcpMarketplaceCatalog(INTEGRATION_CATALOG);
+ const raw = INTEGRATION_CATALOG.find((entry) => entry.id === "linear");
+
+ // Assert: the shared JSON module still carries the upstream values.
+ const rawOption = raw?.connectionOptions.find(
+ (option) => option.transport?.kind === "sse",
+ );
+ expect(rawOption?.transport).toEqual({
+ kind: "sse",
+ url: "https://mcp.linear.app/sse",
+ apiKeyOptional: true,
+ });
+ });
+
it("drops deprecated MCP entries that no longer have maintained replacements", () => {
const catalogIds = new Set(
getMcpMarketplaceCatalog(INTEGRATION_CATALOG).map((entry) => entry.id),
diff --git a/__tests__/utils/mcp-config.test.ts b/__tests__/utils/mcp-config.test.ts
index 1fa12ef79c..691018fbec 100644
--- a/__tests__/utils/mcp-config.test.ts
+++ b/__tests__/utils/mcp-config.test.ts
@@ -151,3 +151,102 @@ describe("toSdkMcpConfig", () => {
expect("myname" in out2).toBe(true);
});
});
+
+describe("parseMcpConfig β€” deprecated Linear SSE migration", () => {
+ // Linear removed its MCP SSE transport; persisted configs that still
+ // point at https://mcp.linear.app/sse must be rewritten to streamable
+ // HTTP at https://mcp.linear.app/mcp.
+
+ it("migrates a legacy Linear SSE server to the /mcp endpoint", () => {
+ // Arrange
+ const persisted = {
+ mcpServers: {
+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },
+ },
+ };
+
+ // Act
+ const parsed = parseMcpConfig(persisted);
+
+ // Assert
+ expect(parsed.sse_servers).toEqual([]);
+ expect(parsed.shttp_servers).toEqual([
+ { url: "https://mcp.linear.app/mcp" },
+ ]);
+ });
+
+ it("preserves the api key and tolerates a trailing slash when migrating", () => {
+ // Arrange
+ const persisted = {
+ mcpServers: {
+ sse: {
+ url: "https://mcp.linear.app/sse/",
+ transport: "sse",
+ auth: "lin_api_secret",
+ },
+ },
+ };
+
+ // Act
+ const parsed = parseMcpConfig(persisted);
+
+ // Assert
+ expect(parsed.shttp_servers).toEqual([
+ { url: "https://mcp.linear.app/mcp", api_key: "lin_api_secret" },
+ ]);
+ });
+
+ it("leaves non-Linear SSE servers untouched", () => {
+ // Arrange
+ const persisted = {
+ mcpServers: {
+ sse: { url: "https://other.example/sse", transport: "sse" },
+ },
+ };
+
+ // Act
+ const parsed = parseMcpConfig(persisted);
+
+ // Assert
+ expect(parsed.sse_servers).toEqual([{ url: "https://other.example/sse" }]);
+ expect(parsed.shttp_servers).toEqual([]);
+ });
+
+ it("keeps a hand-added /mcp entry instead of duplicating it on migration", () => {
+ // Arrange: legacy SSE install plus a manual /mcp entry that already
+ // carries its own credential β€” the manual entry must win.
+ const persisted = {
+ mcpServers: {
+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },
+ shttp: { url: "https://mcp.linear.app/mcp", auth: "manual_key" },
+ },
+ };
+
+ // Act
+ const parsed = parseMcpConfig(persisted);
+
+ // Assert
+ expect(parsed.shttp_servers).toEqual([
+ { url: "https://mcp.linear.app/mcp", api_key: "manual_key" },
+ ]);
+ });
+
+ it("persists the migration as an shttp server on the next save", () => {
+ // Arrange: the exact broken state from the field β€” the server key
+ // "sse" is what produced the rejected `sse_save_comment` tool name.
+ const persisted = {
+ mcpServers: {
+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },
+ },
+ };
+
+ // Act: parse (load) then serialize (what every MCP save does).
+ const written = toSdkMcpConfig(parseMcpConfig(persisted));
+
+ // Assert: re-persisted under the shttp key with no transport field,
+ // so the backend connects via streamable HTTP to the new endpoint.
+ expect(written).toEqual({
+ mcpServers: { shttp: { url: "https://mcp.linear.app/mcp" } },
+ });
+ });
+});
diff --git a/__tests__/utils/mcp-marketplace-utils.test.ts b/__tests__/utils/mcp-marketplace-utils.test.ts
index 5cfa5b835b..899647fdab 100644
--- a/__tests__/utils/mcp-marketplace-utils.test.ts
+++ b/__tests__/utils/mcp-marketplace-utils.test.ts
@@ -69,22 +69,22 @@ describe("findInstalledMatch", () => {
expect(result).toEqual(expect.objectContaining({ id: "stdio-0" }));
});
- it("matches SSE servers loosely on URL", () => {
+ it("matches HTTP servers loosely on URL", () => {
const result = findInstalledMatch(getDefaultMcpTransport(linearEntry)!, [
{
- id: "sse-0",
- type: "sse",
- url: "https://mcp.linear.app/sse/",
+ id: "shttp-0",
+ type: "shttp",
+ url: "https://mcp.linear.app/mcp/",
},
]);
- expect(result).toEqual(expect.objectContaining({ id: "sse-0" }));
+ expect(result).toEqual(expect.objectContaining({ id: "shttp-0" }));
});
it("returns null when servers carry malformed urls (defensive)", () => {
const result = findInstalledMatch(getDefaultMcpTransport(linearEntry)!, [
// Cast to any to simulate runtime data slipping past the type.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
- { id: "sse-0", type: "sse", url: undefined as any },
+ { id: "shttp-0", type: "shttp", url: undefined as any },
]);
expect(result).toBeNull();
});
@@ -236,19 +236,19 @@ describe("findCatalogEntryForServer", () => {
).toBeUndefined();
});
- it("matches an SSE server whose URL differs only by trailing slash", () => {
+ it("matches an HTTP server whose URL differs only by trailing slash", () => {
// Regression coverage for the strict-=== URL match that previously
// diverged from findInstalledMatch and caused installed cards to
// render the generic icon while the marketplace tile said
// "Installed".
const linear = mcpMarketplace.find((e) => e.id === "linear")!;
const linearTransport = getDefaultMcpTransport(linear);
- if (linearTransport?.kind !== "sse") {
- throw new Error("Linear template should be SSE");
+ if (linearTransport?.kind !== "shttp") {
+ throw new Error("Linear template should be shttp");
}
const normalizedUrl = linearTransport.url.replace(/\/$/, "");
const match = findCatalogEntryForServer(
- { id: "sse-0", type: "sse", url: `${normalizedUrl}/` },
+ { id: "shttp-0", type: "shttp", url: `${normalizedUrl}/` },
mcpMarketplace,
);
expect(match?.id).toBe("linear");
diff --git a/src/utils/mcp-config.ts b/src/utils/mcp-config.ts
index 68c8915c40..14e36f729e 100644
--- a/src/utils/mcp-config.ts
+++ b/src/utils/mcp-config.ts
@@ -12,6 +12,25 @@ const EMPTY_MCP_CONFIG: MCPConfig = {
shttp_servers: [],
};
+const LINEAR_DEPRECATED_SSE_URL = "https://mcp.linear.app/sse";
+const LINEAR_SHTTP_URL = "https://mcp.linear.app/mcp";
+
+/**
+ * Linear removed its MCP SSE transport (the /sse endpoint rejects every
+ * call since 2026-04-08). Detect persisted configs that still point at
+ * the dead endpoint so they can be migrated to streamable HTTP at the
+ * /mcp replacement. Matches only the exact deprecated URL (tolerating a
+ * trailing slash or query string) β€” nothing else is rewritten.
+ */
+function isDeprecatedLinearSse(
+ url: string,
+ transport: string | undefined,
+): boolean {
+ if (transport !== "sse") return false;
+ const normalized = url.split("?")[0].replace(/\/+$/, "");
+ return normalized === LINEAR_DEPRECATED_SSE_URL;
+}
+
type SdkMcpServerConfig = Record<string, SettingsValue>;
type SdkMcpConfig = { mcpServers: Record<string, SdkMcpServerConfig> };
@@ -37,6 +56,10 @@ export function parseMcpConfig(value: unknown): MCPConfig {
const sseServers: (string | MCPSSEServer)[] = [];
const stdioServers: MCPStdioServer[] = [];
const shttpServers: (string | MCPSHTTPServer)[] = [];
+ // Legacy Linear SSE entries rewritten to the /mcp endpoint. Collected
+ // separately and merged after the loop so an existing hand-added /mcp
+ // entry (with its own api_key/timeout) wins over the migrated one.
+ const migratedShttpServers: MCPSHTTPServer[] = [];
const mcpServers = obj.mcpServers as Record<string, Record<string, unknown>>;
@@ -51,7 +74,11 @@ export function parseMcpConfig(value: unknown): MCPConfig {
const apiKey =
typeof auth === "string" && auth !== "oauth" ? auth : undefined;
- if (transport === "sse") {
+ if (isDeprecatedLinearSse(url, transport)) {
+ const server: MCPSHTTPServer = { url: LINEAR_SHTTP_URL };
+ if (apiKey) server.api_key = apiKey;
+ migratedShttpServers.push(server);
+ } else if (transport === "sse") {
const server: MCPSSEServer = { url };
if (apiKey) server.api_key = apiKey;
sseServers.push(server);
@@ -78,6 +105,15 @@ export function parseMcpConfig(value: unknown): MCPConfig {
}
}
+ const normalizeUrl = (u: string) => u.replace(/\/+$/, "");
+ for (const migrated of migratedShttpServers) {
+ const alreadyPresent = shttpServers.some((entry) => {
+ const entryUrl = typeof entry === "string" ? entry : entry.url;
+ return normalizeUrl(entryUrl) === normalizeUrl(migrated.url);
+ });
+ if (!alreadyPresent) shttpServers.push(migrated);
+ }
+
return {
sse_servers: sseServers,
stdio_servers: stdioServers,
diff --git a/src/utils/mcp-marketplace-utils.ts b/src/utils/mcp-marketplace-utils.ts
index 24f6448bd2..9b7f7d7251 100644
--- a/src/utils/mcp-marketplace-utils.ts
+++ b/src/utils/mcp-marketplace-utils.ts
@@ -59,10 +59,56 @@ export function getDefaultMcpTransport(
return getDefaultMcpConnectionOption(entry)?.transport;
}
+const LINEAR_DEPRECATED_SSE_URL = "https://mcp.linear.app/sse";
+const LINEAR_SHTTP_URL = "https://mcp.linear.app/mcp";
+const LINEAR_DOCS_URL = "https://linear.app/docs/mcp";
+
+/**
+ * Upstream @openhands/extensions still ships Linear's deprecated SSE
+ * transport (removed upstream on 2026-04-08; the /sse endpoint now
+ * rejects every call). Rewrite the entry to streamable HTTP at the
+ * /mcp replacement endpoint until the pinned dependency catches up.
+ *
+ * The /mcp endpoint authenticates via OAuth 2.1 or a Linear API key
+ * sent as "Authorization: Bearer <token>". This client has no
+ * interactive OAuth flow for MCP installs, so switch the auth
+ * strategy from "none" to "bearer" β€” the install modal then offers
+ * an (optional) API key field and the agent server forwards it as a
+ * Bearer header.
+ *
+ * Patches immutably β€” the imported catalog JSON is shared module
+ * state and must not be mutated.
+ */
+function patchLinearEntry(entry: MarketplaceEntry): MarketplaceEntry {
+ if (entry.id !== "linear") return entry;
+ return {
+ ...entry,
+ docsUrl: LINEAR_DOCS_URL,
+ installHint:
+ "Authenticate with a Linear API key (Linear β†’ Settings β†’ Security & access) β€” sent as a Bearer token. Optional when the endpoint accepts your OAuth session.",
+ connectionOptions: entry.connectionOptions.map((option) =>
+ option.transport?.kind === "sse" &&
+ urlsMatch(option.transport.url, LINEAR_DEPRECATED_SSE_URL)
+ ? {
+ ...option,
+ auth: { ...option.auth, strategy: "bearer" as const },
+ transport: {
+ kind: "shttp" as const,
+ url: LINEAR_SHTTP_URL,
+ apiKeyOptional: option.transport.apiKeyOptional,
+ },
+ }
+ : option,
+ ),
+ };
+}
+
export function getMcpMarketplaceCatalog(
catalog: MarketplaceEntry[],
): MarketplaceEntry[] {
- return catalog.filter((entry) => !!getDefaultMcpConnectionOption(entry));
+ return catalog
+ .map(patchLinearEntry)
+ .filter((entry) => !!getDefaultMcpConnectionOption(entry));
}
const tryUrl = (raw: string): URL | null => {