Skip to content

OAuth: support custom authorization-request parameters per server (e.g. kc_idp_hint, login_hint, audience) #2018

Description

@cliffhall

Split from #1937 (asks 1 and 3).

Problem

There is no way to add a custom query parameter to the OAuth authorization request URL. Real deployments gate IdP selection, prompt behavior, or audience on such a parameter — Keycloak's kc_idp_hint, OIDC's login_hint / prompt / acr_values, Auth0's audience — and none of them can be driven from the Inspector today. For a tool whose job is debugging someone else's authorization setup, that is a real gap.

Why it can't be done today

The Inspector never builds the authorize URL; it delegates entirely to the SDK.

  • core/auth/mcpAuth.ts:50-58 forwards a fixed option set to the SDK's auth(). McpAuthOptions (:22-35) has no extra-params field, and all four call sites — core/mcp/oauthManager.ts:247, :324, :715, :844 — pass only that shape.
  • The SDK exposes no hook either. AuthOptions and startAuthorization accept only { metadata, clientInformation, redirectUrl, scope, state, resource } (node_modules/@modelcontextprotocol/client/dist/index.d.mts:573-631, :791-808), and the implementation hard-codes the emitted parameter list (index.mjs:1151-1159). OAuthClientProvider offers state(), addClientAuthentication, prepareTokenRequest, and validateResourceURL — none of which touch the authorization URL. (prepareTokenRequest affects the token request only.)

Why it does not need an SDK change

InspectorOAuthClientProvider.redirectToAuthorization(authorizationUrl: URL) (core/auth/providers.ts:274-288) receives the finished URL immediately before navigation. Appending parameters there is the seam, and the EMA leg already sets precedent by substituting the URL wholesale (core/auth/ema/transportProvider.ts:84-87).

Scope

  1. A per-server list of key/value pairs in Server Settings → Authorization, persisted on the server's OAuth config alongside scopes (clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx:681-700 is the neighboring control and the shape to follow).
  2. Applied in redirectToAuthorization so every client — web, CLI, TUI — inherits it from core/.
  3. Surfaced in the Network tab like any other authorization request, subject to the existing redaction rules.

Design constraints

  • Generic key/value, not an "OIDC option". idp_hint is not standard — Keycloak spells it kc_idp_hint, and other providers use entirely different names. A named OIDC toggle would fit one vendor and mislead about every other. The UI should say "Additional authorization parameters".
  • Reserve the protocol-critical keys. Reject (with an inline validation message, not silently) any attempt to set client_id, redirect_uri, response_type, code_challenge, code_challenge_method, state, scope, or resource. Letting a user override those breaks PKCE and RFC 8707 in ways that surface as opaque authorization-server errors rather than as an Inspector problem.
  • Parameters belong on the authorization request only, not on the token request.

Out of scope

The id_token handling from #1937 — see the sibling issue.

Testing

Unit coverage for the parameter-merge and reserved-key rejection logic in core/, plus the form validation path in clients/web. Both must clear the >=90% per-file gate.

Metadata

Metadata

Assignees

Labels

enhancementNew feature requestv2Issues and PRs for v2

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions