zuplo 6.70.53 → 6.70.55

package/docs/mcp-gateway/auth/overview.mdx

@@ -0,0 +1,314 @@
+---
+title: "Authentication overview"
+sidebar_label: "Overview"
+description:
+  How authentication works in the Zuplo MCP Gateway — the gateway as an OAuth
+  2.1 server for MCP clients, and as an OAuth client to each upstream MCP
+  server.
+---
+
+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](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+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](#identity-providers) below points at per-IdP setup
+guides; the upstream side has its own pages:
+
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx) — the upstream
+  side, conceptually
+- [Connect a gateway to an upstream OAuth provider](../how-to/connect-upstream-oauth.mdx)
+  — how-to
+- [Manual OAuth testing](./manual-oauth-testing.mdx) — 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.
+
+:::caution{title="Token passthrough is forbidden"}
+
+The MCP authorization spec
+[explicitly forbids](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices)
+forwarding an inbound bearer token to an upstream API. Inbound auth headers
+don't leak to the upstream — the gateway always uses an independent upstream
+credential. The gateway-issued token a client presents and the upstream token
+the gateway forwards are never the same token.
+
+:::
+
+## Standards observed
+
+The gateway implements the following standards in their MCP-mandated subsets.
+
+| Standard                                                                                                                           | Purpose                                                                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)                                                | Core authorization framework.                                                                                                                                                                               |
+| [RFC 7636 — PKCE](https://datatracker.ietf.org/doc/html/rfc7636)                                                                   | Required on every authorization code flow. `S256` is required when technically capable.                                                                                                                     |
+| [RFC 8414 — Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)                                          | Published at `/.well-known/oauth-authorization-server[/{routePath}]`.                                                                                                                                       |
+| [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)                                         | Accepted alongside RFC 8414 as authorization-server discovery (added in the `2025-11-25` MCP revision).                                                                                                     |
+| [RFC 9728 — Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)                                            | Published at `/.well-known/oauth-protected-resource/{routePath}` per MCP route.                                                                                                                             |
+| [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)                                            | Accepted at `/oauth/register`.                                                                                                                                                                              |
+| [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00) | Recommended client identification path per the `2025-11-25` MCP revision. The gateway advertises `client_id_metadata_document_supported: true` and accepts URLs as `client_id` values when CIMD is enabled. |
+| [RFC 8707 — Resource Indicators](https://datatracker.ietf.org/doc/html/rfc8707)                                                    | MCP clients **MUST** include the `resource` parameter on every authorization and token request. The gateway validates that incoming bearer tokens were minted for the route's canonical resource URI.       |
+| [RFC 6750 — Bearer tokens](https://datatracker.ietf.org/doc/html/rfc6750)                                                          | `Authorization: Bearer ...` only, header position only — tokens in query strings are rejected.                                                                                                              |
+| [RFC 7009 — Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)                                                       | Published at `/oauth/revoke`.                                                                                                                                                                               |
+
+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.
+
+<Diagram height="h-72">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo Gateway">
+    <DiagramNode id="endpoints" variant="zuplo">
+      OAuth endpoints
+    </DiagramNode>
+    <DiagramNode id="route" variant="zuplo">
+      MCP route
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="idp">Identity Provider</DiagramNode>
+  <DiagramEdge from="client" to="endpoints" label="OAuth flow" />
+  <DiagramEdge from="endpoints" to="idp" label="Browser login" />
+  <DiagramEdge from="client" to="route" label="MCP request" />
+</Diagram>
+
+The flow is the standard MCP authorization handshake. The
+[`McpGatewayPlugin`](../code-config/overview.mdx) 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.
+
+<Diagram height="h-72">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo Gateway">
+    <DiagramNode id="connect" variant="zuplo">
+      Upstream connect
+    </DiagramNode>
+    <DiagramNode id="route" variant="zuplo">
+      MCP route
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="provider">Upstream Provider</DiagramNode>
+  <DiagramNode id="upstream">Upstream MCP server</DiagramNode>
+  <DiagramEdge from="client" to="route" label="MCP request" />
+  <DiagramEdge from="connect" to="provider" label="Upstream OAuth" />
+  <DiagramEdge from="route" to="upstream" label="Proxied request" />
+</Diagram>
+
+The `connect-required` JSON-RPC error wraps an MCP
+[`UrlElicitationRequiredError`](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation),
+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.
+
+| Provider                                           | Policy                       | Required options                                          | Setup guide                                    |
+| -------------------------------------------------- | ---------------------------- | --------------------------------------------------------- | ---------------------------------------------- |
+| **Auth0**                                          | `mcp-auth0-oauth-inbound`    | `auth0Domain`, `clientId`, `clientSecret`                 | [Configuring Auth0](./configuring-auth0.mdx)   |
+| **Amazon Cognito**                                 | `mcp-cognito-oauth-inbound`  | `awsRegion`, `userPoolId`, `userPoolDomain`, client creds | [Cognito](./configuring-cognito.mdx)           |
+| **Clerk**                                          | `mcp-clerk-oauth-inbound`    | `frontendApiUrl`, `clientId`, `clientSecret`              | [Clerk](./configuring-clerk.mdx)               |
+| **Google**                                         | `mcp-google-oauth-inbound`   | `clientId`, `clientSecret`                                | [Google](./configuring-google.mdx)             |
+| **Keycloak**                                       | `mcp-keycloak-oauth-inbound` | `keycloakBaseUrl`, `realm`, client creds                  | [Keycloak](./configuring-keycloak.mdx)         |
+| **Logto**                                          | `mcp-logto-oauth-inbound`    | `logtoEndpoint`, `clientId`, `clientSecret`               | [Logto](./configuring-logto.mdx)               |
+| **Microsoft Entra ID**                             | `mcp-entra-oauth-inbound`    | `tenantId`, `clientId`, `clientSecret`                    | [Microsoft Entra](./configuring-entra.mdx)     |
+| **Okta**                                           | `mcp-okta-oauth-inbound`     | `oktaDomain`, client creds                                | [Okta](./configuring-okta.mdx)                 |
+| **OneLogin**                                       | `mcp-onelogin-oauth-inbound` | `oneLoginSubdomain`, client creds                         | [OneLogin](./configuring-onelogin.mdx)         |
+| **PingOne**                                        | `mcp-ping-oauth-inbound`     | `environmentId` (or `customDomain`), client creds         | [PingOne](./configuring-ping.mdx)              |
+| **WorkOS**                                         | `mcp-workos-oauth-inbound`   | `clientId`, `clientSecret`                                | [WorkOS](./configuring-workos.mdx)             |
+| Any other OIDC IdP (Ory Hydra, Authentik, custom…) | `mcp-oauth-inbound`          | `oidc.issuer`, `oidc.jwksUrl`, `browserLogin.url`         | [Generic OIDC](./configuring-generic-oidc.mdx) |
+
+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](../troubleshooting.mdx) 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](../reference.mdx) for the
+full URL catalog.
+
+| Path                                                  | Method    | Purpose                                                                        |
+| ----------------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
+| `/.well-known/oauth-authorization-server`             | GET       | RFC 8414 AS metadata (gateway-wide).                                           |
+| `/.well-known/oauth-authorization-server/{routePath}` | GET       | RFC 8414 AS metadata (per route, rebinds `issuer`).                            |
+| `/.well-known/oauth-protected-resource/{routePath}`   | GET       | RFC 9728 PRM (per route).                                                      |
+| `/oauth/register`                                     | POST      | RFC 7591 Dynamic Client Registration.                                          |
+| `/oauth/authorize`                                    | GET       | Gateway-wide authorize endpoint. Requires the `resource` parameter.            |
+| `/oauth/authorize/{routePath}`                        | GET       | Per-route authorize endpoint.                                                  |
+| `/oauth/callback`                                     | GET       | Browser-login callback from the IdP.                                           |
+| `/oauth/setup`                                        | GET, POST | Consent and multi-upstream connect page.                                       |
+| `/oauth/token`                                        | POST      | Token endpoint. Accepts `authorization_code` and `refresh_token` grants.       |
+| `/oauth/revoke`                                       | POST      | RFC 7009 revocation.                                                           |
+| `/.well-known/oauth-client/{connection}`              | GET       | OIDC Client ID Metadata Document for the upstream OAuth client (per upstream). |
+| `/auth/connections/{connection}/connect`              | GET       | Start the upstream OAuth flow.                                                 |
+| `/auth/connections/{connection}/callback`             | GET       | Upstream OAuth callback.                                                       |
+
+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](./upstream-oauth.mdx) — the upstream
+  side, conceptually: discovery, client registration modes, per-user storage,
+  refresh, and reconsent.
+- [Connect a gateway to an upstream OAuth provider](../how-to/connect-upstream-oauth.mdx)
+  — how to attach the `mcp-token-exchange-inbound` policy.
+- [Manual OAuth testing](./manual-oauth-testing.mdx) — verify the gateway's
+  OAuth surface end to end with `curl` and `openssl`.
+- [Identity provider setup guides](#identity-providers) — Auth0, Cognito, Clerk,
+  Google, Keycloak, Logto, Microsoft Entra, Okta, OneLogin, PingOne, WorkOS, and
+  any other OIDC provider.
+- [Reference](../reference.mdx) — full URL catalog, default TTLs, and OAuth
+  metadata extensions.

package/docs/mcp-gateway/auth/upstream-oauth.mdx

@@ -0,0 +1,221 @@
+---
+title: "Per-user OAuth to upstream MCP servers"
+sidebar_label: "Upstream OAuth"
+description:
+  How the Zuplo MCP Gateway acts as an OAuth client to upstream MCP servers —
+  the two auth modes, client registration, the consent flow users experience,
+  connect-required states, and token refresh.
+---
+
+The gateway sits between an MCP client and the upstream MCP servers a team
+relies on. The inbound OAuth surface is the one MCP clients connect to; the
+outbound surface is where the gateway authenticates to each upstream on the
+user's behalf. This page is about the outbound surface — the one the
+`mcp-token-exchange-inbound` policy controls.
+
+For the policy steps, options reference, and worked examples, see
+[Connect a gateway to an upstream OAuth provider](../how-to/connect-upstream-oauth.mdx).
+
+## Why the gateway acts as an OAuth client
+
+Modern MCP servers — Linear, Notion, Stripe, GitHub, Grafana Cloud, and many
+others — are OAuth-protected resources. They expect a `Bearer` token that
+represents a specific user (or service identity) granted by their own OAuth
+authorization server.
+
+When an MCP client connects to a Zuplo MCP Gateway route, it presents the
+gateway's bearer token. That token authenticates the user to the gateway but
+isn't valid against the upstream. The spec
+[explicitly forbids](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices)
+forwarding the inbound token to an upstream, so the gateway must mint an
+independent upstream credential and attach it to the upstream request.
+
+The gateway does that by acting as a standard OAuth client to each upstream —
+discovering the upstream's authorization server, registering itself as a client,
+redirecting the user through the upstream's authorization flow, capturing the
+resulting tokens, and storing them encrypted at rest. On subsequent requests,
+the gateway resolves the stored credential, refreshes it if necessary, and
+applies it to the upstream request.
+
+## The two auth modes
+
+`authMode` is the central knob. It decides who owns the upstream credential.
+
+### user-oauth
+
+Per-user is the default and the right choice for most upstreams. Each user has
+their own per-upstream OAuth connection. The first time a user hits the route,
+the gateway returns a connect-required error; the user completes the upstream
+provider's OAuth flow in a browser; the gateway stores the resulting tokens
+encrypted, keyed by the user's subject ID. Subsequent requests from that user
+are transparent.
+
+This mode is what Linear, Notion, Stripe, GitHub, and most SaaS MCP servers use.
+It preserves per-user attribution end to end — the upstream sees the specific
+user making the call, and the gateway's analytics record the same subject ID
+against every event.
+
+### shared-oauth
+
+Shared mode uses a single gateway-wide OAuth grant. There's no per-user connect
+flow. An administrator completes a one-time connection through the upstream's
+OAuth provider, and every authenticated user reuses that credential when calling
+the upstream. If no shared connection exists yet, the gateway returns an
+`admin_connect_required` error to let the client know an administrator action is
+needed.
+
+Shared mode is appropriate when the upstream uses a service account that
+represents the organization rather than individual users, or when auditing
+happens at the gateway level (per user) rather than at the upstream (where every
+call looks like the same service account).
+
+## Client registration
+
+The gateway needs to identify itself to the upstream OAuth provider before it
+can request tokens. The `clientRegistration` option controls how:
+
+- **CIMD with DCR fallback (`{ "mode": "auto" }`)** — the default. The gateway
+  publishes a per-upstream
+  [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)
+  at `/.well-known/oauth-client/{connection}?authProfileId=...` and tells the
+  upstream that URL is the client ID. If the upstream doesn't accept CIMD, the
+  gateway falls back to
+  [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591).
+  Auto mode requires nothing from the upstream provider beyond standard MCP
+  authorization spec support and has no client secrets to rotate.
+- **Manual** — the gateway uses a pre-registered `clientId` (and optional
+  `clientSecret`) and authenticates to the upstream token endpoint with a
+  configured method. Manual mode is the right choice when an organization
+  manages OAuth client lifecycle centrally, the upstream provider requires an
+  approved client, or one OAuth client should be shared across multiple routes.
+
+Both modes are first-class. CIMD documents are accessible to the upstream
+provider over HTTPS — the upstream fetches them as part of its OAuth
+registration flow. The CIMD URL includes the `authProfileId` query parameter so
+the gateway can scope client identity per `(upstream, authMode)` pair.
+
+## How the gateway picks scopes
+
+The gateway needs to know which OAuth scopes to request from the upstream. It
+considers three sources in order:
+
+1. **An explicit `scopes` array on the policy.** When set, the gateway uses
+   exactly those values on every upstream authorization request.
+2. **The `scope=` value from the upstream's most recent `WWW-Authenticate`
+   challenge.** Used when no explicit scopes are configured.
+3. **The `scopes_supported` array in the upstream's Protected Resource
+   Metadata.** Used as the final fallback before falling through to no `scope`
+   parameter at all.
+
+Explicit scopes always win. Microsoft 365, Slack, PostHog, Stripe, and Grafana
+Cloud are examples of upstreams that need explicit scopes — their PRM either
+lists too many scopes or none at all, so deferring to discovery alone isn't
+enough.
+
+## What the user sees
+
+The browser flow runs the first time a user hits an OAuth-protected upstream
+they haven't connected, and again whenever the upstream revokes the gateway's
+client. Modern MCP clients implement the URL-elicitation extension and open the
+URL automatically. Older clients surface the URL as part of the JSON-RPC error
+message; the user copies it into a browser.
+
+<Diagram height="h-72">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo Gateway">
+    <DiagramNode id="connect" variant="zuplo">
+      Upstream connect
+    </DiagramNode>
+    <DiagramNode id="route" variant="zuplo">
+      /mcp/linear-v1
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="oauth">Linear OAuth</DiagramNode>
+  <DiagramNode id="upstream">Linear MCP</DiagramNode>
+  <DiagramEdge from="client" to="route" label="MCP request" />
+  <DiagramEdge from="connect" to="oauth" label="Upstream OAuth" />
+  <DiagramEdge from="route" to="upstream" label="Proxied request" />
+</Diagram>
+
+Each MCP route proxies to exactly one upstream, so the consent page typically
+shows one upstream to connect. The consent page is part of the gateway and
+renders automatically whenever a user lands at `/oauth/setup` mid-flow.
+
+## Connect-required states
+
+When the gateway needs the user to act, it returns a JSON-RPC error with a
+`state` field that distinguishes the three reasons.
+
+| State                    | Meaning                                                                                                                  | Typical UI message                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `authenticating`         | First-time connection. User hasn't authorized the upstream yet.                                                          | "Connect to `{provider}` to continue."                                         |
+| `reconsent_required`     | Existing connection but the upstream revoked the client or invalidated the refresh token. The user needs to reauthorize. | "`{provider}` authorization must be renewed."                                  |
+| `admin_connect_required` | `authMode: shared-oauth` and no shared connection exists yet. Only an administrator can complete the flow.               | "An administrator must connect `{provider}` before this service is available." |
+
+The full JSON-RPC error payload looks like:
+
+```jsonc
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "error": {
+    "code": -32042,
+    "message": "Connect Linear to continue.",
+    "data": {
+      "state": "authenticating",
+      "upstreamServerId": "linear",
+      "operationId": "linear-mcp-server",
+      "authUrl": "https://gateway.example.com/auth/connections/linear/connect?browserTicket=eyJ...&operationId=linear-mcp-server",
+      "nextAction": "redirect",
+      "authProfileId": "linear:user-oauth",
+    },
+  },
+}
+```
+
+The `-32042` error code is MCP's `URLElicitationRequiredError`. Clients that
+support URL elicitation open `authUrl` directly; others render the message and
+let the user open the URL manually.
+
+## Refresh and 401 retry
+
+The gateway transparently refreshes the upstream access token from the stored
+refresh token. When the upstream returns a 401 mid-request — for example,
+because the upstream's session-bound token expired — the gateway refreshes the
+upstream credential and retries the upstream fetch once. If the refresh fails or
+produces another connect-required state, the gateway returns the JSON-RPC
+connect-required to the client and the user sees the reconsent flow.
+
+Stored refresh tokens stay valid as long as the upstream provider honors them.
+When an upstream's policy revokes a refresh token — for example, because the
+user revoked the connection from the upstream's dashboard — the next request
+surfaces `reconsent_required` and the user re-authorizes through the same
+browser flow.
+
+## Where the metadata URL comes from
+
+By default, the gateway derives the upstream Protected Resource Metadata URL
+from the route's `rewritePattern`:
+
+```text
+rewritePattern:                https://mcp.linear.app/mcp
+default PRM URL:               https://mcp.linear.app/.well-known/oauth-protected-resource/mcp
+```
+
+When the upstream serves PRM at a non-default path (Linear's PRM lives at the
+origin's root, not under `/mcp`), the policy's `protectedResourceMetadataUrl`
+option overrides the default. The canonical source of truth is the
+`resource_metadata=` parameter on the upstream's `WWW-Authenticate` challenge to
+an unauthenticated request.
+
+## Related
+
+- [Connect a gateway to an upstream OAuth provider](../how-to/connect-upstream-oauth.mdx)
+  — how to attach the policy, pick modes, and verify the connect flow.
+- [Authentication overview](./overview.mdx) — the two-layer model and how
+  inbound and outbound OAuth fit together.
+- [Manual OAuth testing](./manual-oauth-testing.mdx) — verify the gateway's
+  OAuth surface end to end with `curl` and `openssl`.
+- [Compatibility dates](../code-config/compatibility-dates.mdx) — the
+  `2026-03-01` requirement for upstream 401 retries and other MCP Gateway
+  behaviors.