Authentication overview

The Zuplo MCP Gateway sits in the middle of two independent OAuth relationships. MCP clients connect to the gateway and authenticate against it. The gateway, in turn, connects to each upstream MCP server and authenticates against it on the user's behalf. Both halves follow the same spec — the MCP authorization model at revision 2025-11-25 — but they're configured separately and use different policies.

This page explains both layers, the standards involved, and the moving parts (sessions, scopes, token lifetimes) you'll see throughout the gateway. The identity provider catalog below points at per-IdP setup guides; the upstream side has its own pages:

• Per-user OAuth to upstream MCP servers — the upstream side, conceptually
• Connect a gateway to an upstream OAuth provider — how-to
• Manual OAuth testing — how-to

The two layers

Every authenticated MCP request involves two distinct OAuth surfaces.

Downstream: gateway as OAuth server

When a client like Claude Desktop, Cursor, or Claude Code connects to a /mcp/{slug} route on the gateway, the client is the OAuth client and the gateway is both the OAuth 2.1 Resource Server (RS) and the OAuth 2.1 Authorization Server (AS).

The gateway publishes everything an MCP client needs to discover and complete an OAuth flow:

• An RFC 9728 Protected Resource Metadata document per route.
• An RFC 8414 Authorization Server Metadata document, both gateway-wide and per route.
• An RFC 7591 Dynamic Client Registration endpoint.
• An OAuth Client ID Metadata Document (CIMD) acceptor.
• /oauth/authorize, /oauth/token, /oauth/revoke, and /oauth/callback endpoints.

Browser identity is delegated to an OIDC identity provider you configure — Auth0, Okta, or any OIDC discovery-compatible IdP. The IdP authenticates the user; the gateway then issues its own bearer access token to the MCP client. The IdP's token never reaches the MCP client.

Upstream: gateway as OAuth client

When the gateway forwards a request to an upstream MCP server (Linear, Stripe, Notion, GitHub, your internal service, and so on), the gateway is the OAuth client and the upstream MCP server is the resource server. On behalf of each user, the gateway runs through the upstream provider's OAuth discovery, registers itself (preferring OIDC Client ID Metadata Documents, falling back to RFC 7591 Dynamic Client Registration), redirects the user through the upstream /authorize, captures the upstream tokens, and stores them encrypted at rest.

On subsequent MCP requests, the gateway resolves the stored upstream credential per user, refreshes it if necessary, and injects it as an Authorization: Bearer ... header when proxying to the upstream.

Standards observed

The gateway implements the following standards in their MCP-mandated subsets.

CIMD is the recommended client identification path going forward; DCR is retained for backwards compatibility with older MCP clients. Both work against the same /oauth/register and AS metadata surface — clients that support either are accommodated.

Downstream flow

The downstream OAuth flow follows the spec's authorization-code grant with PKCE plus the MCP resource parameter binding.

The flow is the standard MCP authorization handshake. The McpGatewayPlugin registers the /.well-known/... and /oauth/... endpoints automatically.

Upstream flow

The first request to a route whose upstream needs OAuth produces a connect-required error. The MCP client is expected to surface the returned URL to the user; the user completes upstream OAuth in a browser; the next MCP request succeeds.

The connect-required JSON-RPC error wraps an MCP UrlElicitationRequiredError, so clients that implement the URL-elicitation extension open the URL in a browser automatically. Older clients surface the URL as text for the user to open manually.

When the gateway has a stored upstream connection for the user, no connect-required error is returned — the proxy forwards transparently.

Identity providers

The gateway ships a generic OIDC policy plus first-class wrappers for the identity providers most teams use. You configure exactly one of these policies per project — the gateway rejects projects that declare more than one MCP OAuth policy.

Each wrapper has the same shape: it takes a small set of provider-specific fields (a domain, a tenant ID, a subdomain, and so on) plus clientId and clientSecret, and derives the OIDC issuer, JWKS URL, and browser-login endpoints automatically. Under the hood every wrapper composes the generic mcp-oauth-inbound policy with provider-flavored URLs.

The upstream side uses a separate policy, mcp-token-exchange-inbound, one per upstream MCP route. The downstream OAuth policy and the upstream token-exchange policy are usually paired on the same route.

Which wrapper should I pick?

• Use a first-class wrapper when one exists for your IdP. The wrappers validate provider-specific inputs at boot (Entra rejects multi-tenant aliases like common, Cognito separates the IDP service domain from the hosted UI domain, OneLogin asks for the bare subdomain) so most misconfigurations fail fast with an obvious error instead of a confusing OIDC failure later.
• Use mcp-oauth-inbound for any OIDC provider that doesn't ship a dedicated wrapper. Ory Hydra, Authentik, ZITADEL, FusionAuth, custom OIDC servers, and PingFederate (as opposed to PingOne) all work this way. You provide the OIDC URLs explicitly.

Sessions, scopes, and TTLs

The defaults below affect user-visible behavior and come up often in configuration.

Browser session

After the user completes browser login, the gateway sets a zuplo_mcp_session cookie. The cookie persists for 8 hours by default (browserLogin.sessionTtlSeconds). During that window, the user doesn't need to re-authenticate against the IdP for additional OAuth grants — the consent page renders immediately.

Gateway-issued tokens

The gateway-issued bearer access token defaults to 15 minutes of lifetime (gateway.accessTokenTtlSeconds = 900). MCP clients refresh as needed.

Refresh tokens default to roughly 10 years (gateway.refreshTokenTtlSeconds). This is intentional: the gateway is not the system of record for the user's session — the upstream IdP is. Imposing a shorter refresh-token lifetime than the IdP's own session policy forces the user back through browser login when the IdP would still accept a silent renewal. Customers who want a tighter ceiling can override the default in policy options.

Refresh tokens rotate on every use, and presenting a previously rotated refresh token revokes the entire grant (with a short grace window to handle concurrent refreshes).

Gateway scope

There is exactly one downstream OAuth scope today: mcp:tools. The gateway issues every access token with this scope, and the PRM advertises it as the only entry in scopes_supported. Future capability scopes will appear alongside mcp:tools rather than replacing it.

Upstream OAuth scopes are independent — they're whatever the upstream provider requires, configured per upstream on mcp-token-exchange-inbound.

Authentication binding

Every gateway-issued access token is bound to:

• The canonical resource URI of the MCP route the user authorized for, derived from the request origin and the route path.
• The operationId of the route, set in routes.oas.json.

The gateway rejects a token presented at a different route or a different canonical resource. A token issued for /mcp/linear-v1 cannot be reused on /mcp/stripe-v1.

The canonical resource URI is constructed from the incoming request origin. If you front the gateway with a custom domain or a proxy, the gateway derives its origin from the Host or X-Forwarded-Host header. A misconfigured proxy that strips or overwrites these headers makes the gateway advertise the wrong issuer in AS metadata. See Troubleshooting for symptoms.

Custom domain caveat

The gateway's issuer URL — the value that appears as issuer in AS metadata and as the authority of all generated endpoint URLs — is derived from the incoming request's origin. The gateway honors the Host and X-Forwarded-Host headers in that order.

When you put the gateway behind a custom domain (gateway.example.com), ensure your fronting proxy or CDN forwards the original Host (or sets X-Forwarded-Host) so the issuer in AS metadata matches the URL the MCP client connected to. A mismatch makes OAuth clients reject the gateway's metadata.

Endpoints reference

The gateway exposes the following authorization endpoints automatically once an MCP OAuth policy is configured. See the reference for the full URL catalog.

The well-known metadata endpoints serve CORS-permissive responses (Access-Control-Allow-Origin: *) because browser-resident MCP clients fetch them cross-origin. The token, register, revoke, callback, setup, and connect endpoints reject ambient credentials.

Related

• Per-user OAuth to upstream MCP servers — the upstream side, conceptually: discovery, client registration modes, per-user storage, refresh, and reconsent.
• Connect a gateway to an upstream OAuth provider — how to attach the mcp-token-exchange-inbound policy.
• Manual OAuth testing — verify the gateway's OAuth surface end to end with curl and openssl.
• Identity provider setup guides — Auth0, Cognito, Clerk, Google, Keycloak, Logto, Microsoft Entra, Okta, OneLogin, PingOne, WorkOS, and any other OIDC provider.
• Reference — full URL catalog, default TTLs, and OAuth metadata extensions.