Skip to content

🙌 OpenHands: AI-Driven Development

fix(mcp): install OAuth-only library entries through the MCP server's own OAuth

Alona55c5b7dd54d2
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 06e7e57b89..5fa478e813 100644
--- a/__tests__/components/features/mcp-page/install-server-modal.test.tsx
+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
@@ -416,6 +416,130 @@ describe("InstallServerModal", () => {
});
});
+ // @spec MCP-006 — Library installs never dead-end
+ it("installs an entry whose catalog OAuth names provider endpoints through the server's own OAuth", async () => {
+ // Arrange: an OHE-style cloud backend and an entry shaped like Sentry's,
+ // whose only MCP option carries the provider's own OAuth app details.
+ setRegisteredBackends([
+ {
+ id: "cloud-1",
+ name: "Cloud",
+ host: "https://app.all-hands.dev",
+ apiKey: "k",
+ kind: "cloud",
+ },
+ ]);
+ setActiveSelection({ backendId: "cloud-1" });
+ const entry: MarketplaceEntry = {
+ id: "provider-oauth",
+ name: "Provider OAuth",
+ description:
+ "Remote MCP server whose catalog option names provider OAuth.",
+ docsUrl: "https://example.com/docs",
+ iconBg: "#000000",
+ connectionOptions: [
+ {
+ id: "oauth-mcp",
+ provider: "mcp",
+ transport: { kind: "shttp", url: "https://mcp.example.com/mcp" },
+ auth: {
+ strategy: "oauth2",
+ oauth: {
+ authorizationUrl: "https://example.com/oauth/authorize",
+ tokenUrl: "https://example.com/oauth/token",
+ scopes: ["project:read"],
+ clientAuthentication: "body",
+ },
+ },
+ },
+ ],
+ };
+ const oauthSpy = vi.spyOn(McpService, "authorizeOAuth").mockResolvedValue({
+ ok: true,
+ tools: ["search_issues"],
+ oauth_state: { tokens: { access_token: "gAAAAencrypted" } },
+ });
+ const saveSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+ renderWith(
+ <InstallServerModal
+ existingServers={[]}
+ entry={entry}
+ onClose={vi.fn()}
+ />,
+ );
+ await screen.findByTestId("mcp-install-oauth-info");
+
+ // Act
+ fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+ // Assert: the server's own OAuth runs without the provider's app details,
+ // and the authorized server is saved.
+ await waitFor(() => expect(oauthSpy).toHaveBeenCalledTimes(1));
+ expect(oauthSpy.mock.calls[0][0]).toEqual({
+ id: "",
+ type: "shttp",
+ name: "provider-oauth",
+ url: "https://mcp.example.com/mcp",
+ auth: { strategy: "oauth2" },
+ });
+ await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+ const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+ .agent_settings_diff as { mcp_config: Record<string, unknown> };
+ expect(sent.mcp_config).toMatchObject({
+ "provider-oauth": {
+ url: "https://mcp.example.com/mcp",
+ auth: {
+ strategy: "oauth2",
+ state: { tokens: { access_token: "gAAAAencrypted" } },
+ },
+ },
+ });
+ });
+
+ // @spec MCP-006 — Library installs never dead-end
+ it("explains and disables Install when no option can be installed", async () => {
+ const entry = {
+ id: "stdio-oauth",
+ name: "Stdio OAuth",
+ description:
+ "An OAuth option on a transport this backend cannot authorize.",
+ docsUrl: "https://example.com/docs",
+ iconBg: "#000000",
+ connectionOptions: [
+ {
+ id: "oauth",
+ provider: "mcp",
+ transport: {
+ kind: "stdio",
+ serverName: "stdio-oauth",
+ command: "npx",
+ args: ["stdio-oauth-mcp"],
+ },
+ auth: { strategy: "oauth2" },
+ },
+ ],
+ } as MarketplaceEntry;
+ const oauthSpy = vi.spyOn(McpService, "authorizeOAuth");
+ const saveSpy = vi.spyOn(SettingsService, "saveSettings");
+ renderWith(
+ <InstallServerModal
+ existingServers={[]}
+ entry={entry}
+ onClose={vi.fn()}
+ />,
+ );
+
+ await screen.findByTestId("mcp-install-unavailable");
+ const install = screen.getByTestId("mcp-install-submit");
+ expect(install).toBeDisabled();
+ fireEvent.click(install);
+ expect(McpService.testServer).not.toHaveBeenCalled();
+ expect(oauthSpy).not.toHaveBeenCalled();
+ expect(saveSpy).not.toHaveBeenCalled();
+ });
+
it("styles the OAuth info box with theme surface and text tokens", async () => {
const entry: MarketplaceEntry = {
id: "synthetic-oauth",
diff --git a/__tests__/utils/mcp-marketplace-utils.test.ts b/__tests__/utils/mcp-marketplace-utils.test.ts
index f4def82c56..38e51bfc8c 100644
--- a/__tests__/utils/mcp-marketplace-utils.test.ts
+++ b/__tests__/utils/mcp-marketplace-utils.test.ts
@@ -103,7 +103,8 @@ describe("getInstallableMcpConnectionOption", () => {
expect(option?.transport.kind).toBe("stdio");
});
- it("returns undefined for provider OAuth entries without a local MCP auth contract", () => {
+ // @spec MCP-006 — Library installs never dead-end
+ it("falls back to the server's own OAuth when the only option has no OAuth metadata", () => {
const oauthOnlyEntry: Parameters<
typeof getInstallableMcpConnectionOption
>[0] = {
@@ -121,7 +122,44 @@ describe("getInstallableMcpConnectionOption", () => {
],
};
const option = getInstallableMcpConnectionOption(oauthOnlyEntry);
- expect(option).toBeUndefined();
+ expect(option?.auth).toEqual({ strategy: "oauth2" });
+ expect(option?.transport).toEqual({
+ kind: "shttp",
+ url: "https://example.com/mcp",
+ });
+ });
+
+ // @spec MCP-006 — Library installs never dead-end
+ it("installs Sentry from the catalog through its MCP server's own OAuth", () => {
+ const sentry = MCP_MARKETPLACE.find((e) => e.id === "sentry")!;
+ const option = getInstallableMcpConnectionOption(sentry);
+ expect(option?.transport).toMatchObject({
+ kind: "shttp",
+ url: "https://mcp.sentry.dev/mcp",
+ });
+ expect(option?.auth.strategy).toBe("oauth2");
+ expect(option?.auth.oauth?.authorizationUrl).toBeUndefined();
+ expect(getMcpOAuthAuthenticationConfig(option!)?.scopes).toBeUndefined();
+ });
+
+ it("does not offer a stdio OAuth option", () => {
+ const entry = {
+ ...slackEntry,
+ connectionOptions: [
+ {
+ id: "oauth",
+ provider: "mcp",
+ auth: { strategy: "oauth2" },
+ transport: {
+ kind: "stdio",
+ serverName: "example",
+ command: "npx",
+ args: ["example-mcp"],
+ },
+ },
+ ],
+ } as typeof slackEntry;
+ expect(getInstallableMcpConnectionOption(entry)).toBeUndefined();
});
it("returns MCP-server-managed OAuth options", () => {
@@ -547,22 +585,31 @@ describe("marketplace option normalization", () => {
"registrationUrl",
"additionalAuthorizationParams",
"additionalTokenParams",
- ] as const)("rejects hosted OAuth metadata: %s", (field) => {
- const option = {
- id: field,
- provider: "mcp",
- auth: {
- strategy: "oauth2",
- oauth: { clientAuthentication: "none", [field]: "configured" },
- },
- transport: { kind: "shttp", url: "https://example.com/mcp" },
- } as never;
- const entry = {
- ...slackEntry,
- connectionOptions: [option],
- } as typeof slackEntry;
- expect(getInstallableMcpConnectionOption(entry)).toBeUndefined();
- });
+ ] as const)(
+ "drops hosted OAuth metadata and uses the server's own OAuth: %s",
+ (field) => {
+ const option = {
+ id: field,
+ provider: "mcp",
+ auth: {
+ strategy: "oauth2",
+ oauth: {
+ clientAuthentication: "body",
+ scopes: ["project:read"],
+ [field]: "configured",
+ },
+ },
+ transport: { kind: "shttp", url: "https://example.com/mcp" },
+ } as never;
+ const entry = {
+ ...slackEntry,
+ connectionOptions: [option],
+ } as typeof slackEntry;
+ const installable = getInstallableMcpConnectionOption(entry);
+ expect(installable?.auth).toEqual({ strategy: "oauth2" });
+ expect(getMcpOAuthAuthenticationConfig(installable!)).toBeUndefined();
+ },
+ );
});
describe("URL and entry matching", () => {
diff --git a/specs/mcp-settings.md b/specs/mcp-settings.md
index 41b432569e..c199ae9f48 100644
--- a/specs/mcp-settings.md
+++ b/specs/mcp-settings.md
@@ -40,3 +40,14 @@
- [x] Both text roles meet 4.5:1 against the modal surface in every built-in
palette, independently of the danger/success control colors.
- [x] Embedded host overrides for those roles survive palette changes.
+
+### MCP-006: Library installs never dead-end
+
+- [x] An entry keeps its preferred installable option, such as an API-key
+ fallback, when one exists.
+- [x] When an entry's only remote option is OAuth, including an option that
+ names provider OAuth endpoints, Install connects through the MCP server's
+ own OAuth discovery. The catalog's provider endpoints, scopes and client
+ authentication are not sent.
+- [x] When no option can be installed, the dialog says so and Install is
+ disabled. Install never does nothing silently.
diff --git a/src/components/features/mcp-page/install-server-modal.tsx b/src/components/features/mcp-page/install-server-modal.tsx
index cf78063b4c..26ef024631 100644
--- a/src/components/features/mcp-page/install-server-modal.tsx
+++ b/src/components/features/mcp-page/install-server-modal.tsx
@@ -519,7 +519,13 @@ export function InstallServerModal({
if (template?.kind === "shttp" || template?.kind === "sse") {
return handleHttpServerSubmit();
}
- return handleStdioSubmit();
+ if (template?.kind === "stdio") {
+ return handleStdioSubmit();
+ }
+ // @spec MCP-006 — Library installs never dead-end
+ return setGlobalError(
+ t(I18nKey.MCP$INSTALL_UNAVAILABLE, { name: entry.name }),
+ );
};
// @spec MCP-004 — Form feedback follows readable theme text roles
@@ -812,6 +818,18 @@ export function InstallServerModal({
<div className="flex flex-col gap-3">{renderFields()}</div>
+ {/* @spec MCP-006 — Library installs never dead-end */}
+ {!option && (
+ <div
+ data-testid="mcp-install-unavailable"
+ className="flex flex-col gap-2 p-3 rounded-lg border border-border bg-tertiary"
+ >
+ <p className="text-sm text-text-secondary">
+ {t(I18nKey.MCP$INSTALL_UNAVAILABLE, { name: entry.name })}
+ </p>
+ </div>
+ )}
+
{/* @spec MCP-004 — Form feedback follows readable theme text roles */}
{globalError && (
<p
@@ -835,7 +853,7 @@ export function InstallServerModal({
<BrandButton
type="submit"
variant="primary"
- isDisabled={isPending}
+ isDisabled={isPending || !option}
testId="mcp-install-submit"
>
{isTesting || isAuthorizingOAuth
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index e5c56ed00f..ff61525c99 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -19133,6 +19133,24 @@
"ca": "Afegeix un servidor personalitzat",
"id": "Tambah server khusus"
},
+ "MCP$INSTALL_UNAVAILABLE": {
+ "en": "{{name}} can't be installed from the library here. Add it as a custom server instead.",
+ "ja": "{{name}} はここではライブラリからインストールできません。代わりにカスタムサーバーとして追加してください。",
+ "zh-CN": "无法在此处从库中安装 {{name}}。请改为将其添加为自定义服务器。",
+ "zh-TW": "無法在此處從資料庫安裝 {{name}}。請改為將其新增為自訂伺服器。",
+ "ko-KR": "{{name}}은(는) 여기에서 라이브러리로 설치할 수 없습니다. 대신 사용자 지정 서버로 추가하세요.",
+ "no": "{{name}} kan ikke installeres fra biblioteket her. Legg den til som en egendefinert server i stedet.",
+ "it": "{{name}} non può essere installato dalla libreria qui. Aggiungilo invece come server personalizzato.",
+ "pt": "{{name}} não pode ser instalado pela biblioteca aqui. Adicione-o como servidor personalizado.",
+ "es": "{{name}} no se puede instalar desde la biblioteca aquí. Añádelo como servidor personalizado.",
+ "ar": "لا يمكن تثبيت {{name}} من المكتبة هنا. أضفه كخادم مخصص بدلاً من ذلك.",
+ "fr": "{{name}} ne peut pas être installé depuis la bibliothèque ici. Ajoutez-le plutôt comme serveur personnalisé.",
+ "tr": "{{name}} burada kütüphaneden yüklenemez. Bunun yerine özel sunucu olarak ekleyin.",
+ "de": "{{name}} kann hier nicht aus der Bibliothek installiert werden. Füge ihn stattdessen als benutzerdefinierten Server hinzu.",
+ "uk": "{{name}} не можна встановити з бібліотеки тут. Натомість додайте його як власний сервер.",
+ "ca": "{{name}} no es pot instal·lar des de la biblioteca aquí. Afegeix-lo com a servidor personalitzat.",
+ "id": "{{name}} tidak dapat dipasang dari pustaka di sini. Tambahkan sebagai server khusus."
+ },
"MCP$ADD_CUSTOM_TITLE": {
"en": "Add custom MCP server",
"ja": "カスタム MCP サーバーを追加",
diff --git a/src/utils/mcp-marketplace-utils.ts b/src/utils/mcp-marketplace-utils.ts
index d65e9228cd..01f7feaa5f 100644
--- a/src/utils/mcp-marketplace-utils.ts
+++ b/src/utils/mcp-marketplace-utils.ts
@@ -50,10 +50,10 @@ function isLocallyInstallableMcpOption(
const oauth = option.auth.oauth;
if (!oauth) return false;
- // Local agent-server installs only support OAuth flows initiated by the MCP
- // server itself through fastmcp. Catalog entries that specify provider OAuth
- // endpoints still need the hosted integration-auth flow and should not be
- // exposed as locally installable static MCP configs.
+ // Both backends only run OAuth flows initiated by the MCP server itself
+ // through fastmcp. Provider OAuth endpoints in the catalog describe a hosted
+ // integration-auth flow, so prefer the entry's other options for these
+ // entries; `getDiscoveryOAuthOption` is the fallback when there are none.
return (
!oauth.authorizationUrl &&
!oauth.tokenUrl &&
@@ -63,10 +63,31 @@ function isLocallyInstallableMcpOption(
);
}
+/**
+ * Connects a remote OAuth option through the MCP server's own OAuth
+ * discovery and dynamic client registration. The catalog's provider
+ * endpoints, scopes and client authentication belong to the hosted flow and
+ * are dropped. A server without dynamic registration reports that from the
+ * authorization attempt instead of leaving Install without an action.
+ */
+function getDiscoveryOAuthOption(
+ option: McpMarketplaceConnectionOption,
+): McpMarketplaceConnectionOption | undefined {
+ if (option.auth.strategy !== "oauth2" || option.transport.kind === "stdio") {
+ return undefined;
+ }
+ return { ...option, auth: { strategy: "oauth2" } };
+}
+
export function getInstallableMcpConnectionOption(
entry: MarketplaceEntry,
): McpMarketplaceConnectionOption | undefined {
- return getMcpConnectionOptions(entry).find(isLocallyInstallableMcpOption);
+ const options = getMcpConnectionOptions(entry);
+ // @spec MCP-006 — Library installs never dead-end
+ return (
+ options.find(isLocallyInstallableMcpOption) ??
+ options.map(getDiscoveryOAuthOption).find(Boolean)
+ );
}
export function getDefaultMcpTransport(