feat(catalog): add OAuth server setup flow

[vishu-bh]

Screen.Recording.2026-09-15.at.11.53.30.mov

Summary

• Add an OAuth-specific catalog setup dialog built from existing shadcn primitives.
• Register credentials, launch authorization, enable the server, then discover tools.
• Surface caller-scoped OAuth status and re-authorization actions on catalog cards.

Backend dependency

Requires backend PRs IBM/mcp-context-forge#6588 and IBM/mcp-context-forge#6620. Handwritten frontend contract types are temporary until OpenAPI generation includes the merged API.

Validation

• npm run lint -- --max-warnings=0
• npx tsc --noEmit
• npm run test -- --run src/pages/ServerCatalog.test.tsx src/components/server-catalog/CatalogResults.test.tsx src/api/catalog.test.ts

NOTE

Please do not merge this till backend dependency is resolved. For the purpose of development handwritten contracts is added but it needs to be cleaned up once backend dependency is resolved

[marekdano]

1. 🔴 High — OAuth popup blocked on first-time setup

File: src/pages/ServerCatalog.tsx:638

handleOAuthSubmit does await registerServer(...) (an HTTP POST) before calling serversApi.triggerOAuthAuthorization(gatewayId). By the time window.open() runs inside that call, the browser no longer treats it as a direct response to the click, so popup blockers will block it (authWindow is null) — this will trigger on essentially every first-time OAuth registration.

Failure scenario: User clicks "Configure and authorize" on a new OAuth catalog server → popup blocked → "Failed to open OAuth authorization window" error. Retrying then hits the pendingOAuthGatewayId fast path, which calls triggerOAuthAuthorization synchronously and succeeds — so it looks like a transient glitch but is actually deterministic.

---

2. 🟠 Medium-High — Removed auth-type filter exposes unsupported servers

File: src/pages/ServerCatalog.tsx:454

The catalog's auth-type allow-list filter (previously SUPPORTED_AUTH_TYPE_SET) was removed. supportedServers = data?.servers ?? [] no longer filters by auth type, so servers with types outside Open/API Key/OAuth (e.g. Basic, mTLS) now render and are "Add"-able.

Failure scenario: Clicking "Add" on such a server falls through handleAdd's if/else chain straight to void registerServer(server) with no credentials — likely a generic server-side failure, or a silent no-auth registration. No test covers this path.

---

3. 🟡 Medium — Disconnect/Test not blocked during in-flight authorization

File: src/components/server-catalog/CatalogResults.tsx:202

The new Authorize action shares the isAdding pending flag with Test and Disconnect, but Test's/Disconnect's own disabled conditions were never updated to also check isAdding.

Failure scenario: User clicks Authorize (popup opens, isAdding true) → reopens the dropdown and clicks Disconnect (only checks isTesting || isDisconnecting) → gateway is deleted mid-authorization → when the popup resolves, toggleEnabled/fetchToolsAfterOAuth run against a deleted gateway id, surfacing a confusing error instead of being prevented up front.

[gcgoncalves]

NIT: Add aria-required to required form inputs and aria-describedby linking inputs with errors to paragraphs describing them.

[a-effort]

1. handleOAuthSubmit in src/pages/ServerCatalog.tsx opens a popup window before calling registerServer, so popup blockers do not interfere. If registerServer throws, the catch branch returns without closing that window. triggerOAuthAuthorization was never called so nothing closes it. Fix: call authWindow.close() in the catch block.

2. getOAuthCardState in src/components/server-catalog/CatalogResults.tsx is called for every registered card, not only OAuth ones. For open and api_key servers it falls through to the success default, which is currently correct, but only because no other branch matches. The function checks server.requires_oauth_config and oauthStatuses without first checking server.auth_type, so a future edit to the fallback or a gateway_id collision could silently produce the wrong badge. Suggest gating the whole OAuth state path on server.auth_type === 'OAuth2.1'.

3. In CatalogOAuthDialog.tsx, the clientSecret validation guard uses clientSecret.trim() to check non-emptiness, but the submitted body sends the raw clientSecret without trimming. A single-space value passes validation and is sent as-is. Every other field is trimmed before submission. If keeping whitespace in the secret is intentional, the guard should use clientSecret.length > 0 instead, and a comment should say so.

4. CatalogServerRegisterBody types name as string | undefined. The dialog submits name: name.trim() || null, which puts an explicit null on the wire. The backend may treat null and a missing field differently. The API-key dialog omits the field rather than sending null; this one should do the same.

Could you also share a screen recording or screenshots of the OAuth setup flow? Useful to see: the dialog form with validation errors, the card status badges, and the authorize action triggering the popup.

[marekdano]

Manual Testing Notes (catalog OAuth add flow)

Environment

• UI (BFF): localhost:3000
• API (mcpgateway): localhost:8000
• Branch under test: feature/catalog-oauth-add-flow

Steps

1. Opened the MCP server catalog, picked a GitHub-backed entry, and used the new OAuth add flow (CatalogOAuthDialog) to register it.

2. Triggered the OAuth popup and completed GitHub's consent screen.

3. GitHub redirected the popup to: http://localhost:8080/oauth/callback?code=...&iss=https%3A%2F%2Fgithub.com%2Flogin%2Foauth&state=popup...

4. Browser showed 502 Bad Gateway (nginx) — flow did not complete.

Result: ❌ Fail

Root cause

redirect_uri resolved to http://localhost:8080, which is neither the UI (:3000) nor the API (:8000) in this environment.

• APP_DOMAIN=http://localhost:8080 in the sibling mcp-context-forge/.env — a stale value left over from a docker-compose (nginx + gateway) stack, unrelated to the native :8000/:3000 setup used here.
• mcpgateway's GET /oauth/authorize/{id} defaults the outbound redirect_uri it sends to GitHub from APP_DOMAIN whenever the server's own oauth_config.redirect_uri isn't set.
• CatalogOAuthDialog.tsx (src/components/server-catalog/CatalogOAuthDialog.tsx:159-168) fetches /oauth/callback-url and displays it for the user to copy into their IdP app settings, but never includes redirect_uri in the oauth_credentials payload it submits. So a catalog-registered OAuth server always falls back to mcpgateway's APP_DOMAIN default instead of this deployment's own callback URL.

Fixing APP_DOMAIN to http://localhost:3000 (the BFF's public origin, which proxies the final hop to the gateway) resolves this catalog-registered OAuth server always falls back to mcpgateway's APP_DOMAIN default instead of this deployment's own callback URL.

Fixing APP_DOMAIN to http://localhost:3000 (the BFF's public origin, which proxies the final hop to the gateway) resolves this specific environment. Not a bug in this PR's code by itself, but it exposed a gap below.

Related gap found (worth a PR comment)

The regular "Add MCP Server" form (src/hooks/useMCPServerForm.ts) does not have this problem:

• Submits it: redirect_uri: oauthRedirectUri || undefined in oauth_config (:580).
• Guards submission with oauthRedirectUriUnresolved (:401) while that fetch is loading/failed, specifically to avoid silently sending redirect_uri: undefined and falling back to APP_DOMAIN.

CatalogOAuthDialog has none of this — no submitted redirect_uri, no unresolved-fetch guard. It's silently dependent on the gateway operator's APP_DOMAIN being correct for split deployments, which is exactly the scenario the /oauth/callback proxy (server/src/routes/proxy/oauth-callback.ts) was built to handle.

Suggested fix: have CatalogOAuthDialog submit redirect_uri: callbackUrl in oauth_credentials, matching useMCPServerForm.ts's behavior, and block submit while the callback URL fetch is unresolved.