zuplo 6.70.54 → 6.70.56

package/docs/mcp-gateway/auth/configuring-generic-oidc.mdx

@@ -0,0 +1,242 @@
+---
+title: "Configuring a generic OIDC provider"
+sidebar_label: "Generic OIDC"
+description:
+  Configure any OIDC-compatible identity provider — Ory Hydra, Authentik,
+  ZITADEL, FusionAuth, PingFederate, or a custom OIDC server — to back the MCP
+  Gateway's downstream OAuth using the mcp-oauth-inbound policy.
+---
+
+The `mcp-oauth-inbound` policy is the catch-all for OIDC identity providers that
+don't yet have a first-class wrapper. It accepts the OIDC URLs explicitly and
+otherwise behaves the same as every per-provider wrapper.
+
+Use this policy when your IdP doesn't appear in the
+[provider catalog](./overview.mdx#identity-providers). Common cases:
+
+- **Ory Hydra** — self-hosted OAuth 2.0/OIDC.
+- **Authentik** — open-source IdP.
+- **ZITADEL** — open-source IdP.
+- **FusionAuth** — self-hosted IdP.
+- **PingFederate** — enterprise IdP (use this policy, not
+  `mcp-ping-oauth-inbound`, which is for PingOne cloud).
+- **A custom OIDC server** you operate yourself.
+
+If your IdP is on the [catalog](./overview.mdx#identity-providers), use the
+dedicated wrapper instead — it validates provider-specific inputs at boot.
+
+Read the [authentication overview](./overview.mdx) first for the two-layer
+model.
+
+## What the gateway needs from your IdP
+
+The gateway needs three pieces of information about your IdP:
+
+1. The **OIDC issuer URL** — the value of `iss` in ID tokens.
+2. The **JWKS URL** — where the gateway fetches the IdP's public keys to verify
+   ID tokens.
+3. The **authorize URL** — where the gateway redirects the user's browser to log
+   in.
+
+For the federated authorization-code exchange you also need a token URL, a
+client ID, and a client secret. The [options reference](#full-options-reference)
+below lists every field.
+
+Most OIDC providers publish all four URLs in a discovery document at
+`{issuer}/.well-known/openid-configuration`. Fetch that document in a browser to
+copy the values.
+
+## Set up the OIDC application
+
+Each IdP exposes its application registration differently, but every flow lands
+at the same place:
+
+1. Create a new OIDC web application (or "regular web application", "OIDC
+   client", "confidential client" — terminology varies).
+2. Set the **redirect URI** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development with
+   `zuplo dev`.
+3. Note the **client ID** and **client secret**.
+4. Restrict the application to the users or groups who should be able to
+   authenticate against the gateway.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "oidc-managed-oauth",
+  "policyType": "mcp-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpOAuthInboundPolicy",
+    "options": {
+      "oidc": {
+        "issuer": "https://idp.example.com",
+        "jwksUrl": "https://idp.example.com/.well-known/jwks.json"
+      },
+      "browserLogin": {
+        "url": "https://idp.example.com/oauth2/authorize",
+        "tokenUrl": "https://idp.example.com/oauth2/token",
+        "clientId": "$env(OIDC_CLIENT_ID)",
+        "clientSecret": "$env(OIDC_CLIENT_SECRET)"
+      }
+    }
+  }
+}
+```
+
+Set `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` in your project's environment
+configuration (the secret goes in the secret store).
+
+Attach the policy to each MCP route in `config/routes.oas.json`:
+
+```jsonc
+{
+  "paths": {
+    "/mcp/linear-v1": {
+      "get,post": {
+        "operationId": "linear-mcp-server",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "module": "$import(@zuplo/runtime/mcp-gateway)",
+            "export": "McpProxyHandler",
+            "options": {
+              "rewritePattern": "https://mcp.linear.app/mcp",
+            },
+          },
+          "policies": {
+            "inbound": ["oidc-managed-oauth", "mcp-token-exchange-linear"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Register the gateway plugin in `modules/zuplo.runtime.ts`:
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(new McpGatewayPlugin());
+}
+```
+
+One MCP OAuth policy serves every MCP route in the project. The gateway rejects
+projects that declare more than one MCP OAuth policy.
+
+## Local development shortcut
+
+For local development without round-tripping a real IdP, set `browserLogin.url`
+to the loopback dev-login endpoint:
+
+```json
+{
+  "options": {
+    "oidc": {
+      "issuer": "http://localhost:9000/",
+      "jwksUrl": "http://localhost:9000/dev/jwks"
+    },
+    "browserLogin": {
+      "url": "http://127.0.0.1:9000/oauth/dev-login"
+    }
+  }
+}
+```
+
+When `browserLogin.url` points at `/oauth/dev-login`, you don't need `tokenUrl`,
+`clientId`, or `clientSecret`. The endpoint is only served on loopback origins;
+production deployments cannot reach it.
+
+See the [local development guide](../code-config/local-development.mdx) for the
+rest of the local setup.
+
+## Full options reference
+
+`mcp-oauth-inbound` has two required option groups: `oidc` and `browserLogin`.
+
+| Option                           | Required           | Default                | Notes                                                                                                       |
+| -------------------------------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `oidc.issuer`                    | yes                | —                      | The OIDC issuer URL. Must include the scheme.                                                               |
+| `oidc.jwksUrl`                   | yes                | —                      | JWKS endpoint that publishes the IdP's signing keys.                                                        |
+| `oidc.audience`                  | no                 | unset                  | Optional ID-token audience override. Leave unset when ID tokens use the OIDC `client_id` as their audience. |
+| `browserLogin.url`               | yes                | —                      | The IdP's `/authorize` endpoint. The loopback `/oauth/dev-login` shortcut works for local dev.              |
+| `browserLogin.tokenUrl`          | for federated OIDC | —                      | The IdP's token endpoint. Required for the federated authorization-code exchange.                           |
+| `browserLogin.clientId`          | for federated OIDC | —                      | OIDC client_id registered with the IdP.                                                                     |
+| `browserLogin.clientSecret`      | for federated OIDC | —                      | OIDC client_secret. Use `$env(...)`.                                                                        |
+| `browserLogin.scope`             | no                 | `openid profile email` | OIDC scopes requested during browser login.                                                                 |
+| `browserLogin.audience`          | no                 | unset                  | Optional `audience` parameter for Auth0-style API audiences.                                                |
+| `browserLogin.remoteTimeoutMs`   | no                 | `10000`                | Outbound timeout for IdP calls.                                                                             |
+| `browserLogin.stateTtlSeconds`   | no                 | `900`                  | Browser-login state record lifetime.                                                                        |
+| `browserLogin.sessionTtlSeconds` | no                 | `28800`                | Browser session cookie lifetime (8 hours).                                                                  |
+| `gateway.accessTokenTtlSeconds`  | no                 | `900`                  | Gateway-issued access token lifetime.                                                                       |
+| `gateway.refreshTokenTtlSeconds` | no                 | long-lived             | Gateway-issued refresh token lifetime.                                                                      |
+| `gateway.cimdEnabled`            | no                 | `true`                 | Advertise CIMD support in AS metadata.                                                                      |
+
+## Notes for specific providers
+
+- **Ory Hydra.** Discovery lives at `{issuer}/.well-known/openid-configuration`;
+  set the issuer to the public-facing Hydra URL.
+- **Authentik.** The issuer is `https://<authentik-host>/application/o/<slug>/`
+  (note the trailing slash). The metadata document is at that issuer plus
+  `.well-known/openid-configuration`.
+- **ZITADEL.** The issuer is your ZITADEL custom domain; metadata is at
+  `{issuer}/.well-known/openid-configuration`.
+- **FusionAuth.** The issuer is your FusionAuth host; metadata is at
+  `{issuer}/.well-known/openid-configuration`.
+- **PingFederate.** Use this generic policy (not the PingOne wrapper).
+  PingFederate deployments can customize issuer hosts, issuer paths, and
+  endpoint paths; copy the four URLs from your federation metadata.
+- **Google Workspace.** Google has a first-class wrapper —
+  [Configuring Google](./configuring-google.mdx).
+- **Microsoft Entra ID.** Entra has a first-class wrapper —
+  [Configuring Microsoft Entra](./configuring-entra.mdx).
+- **Keycloak.** Keycloak has a first-class wrapper —
+  [Configuring Keycloak](./configuring-keycloak.mdx).
+
+In every case, the gateway only needs the four URL fields (issuer, JWKS,
+authorize, token) plus a client ID and secret.
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to your IdP's login page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **The gateway returns 500 at boot.** A required option is missing or invalid.
+  Check the runtime logs for the configuration error.
+- **ID token verification fails.** The `oidc.jwksUrl` doesn't match the IdP's
+  actual JWKS endpoint, or the IdP rotated keys. Restart the gateway to clear
+  the JWKS cache.
+- **`invalid_audience` from the gateway's token endpoint.** The MCP client is
+  reusing a token bound to a different route. Each gateway-issued token is
+  scoped to one MCP route.
+- **MCP client can't discover the AS.** Confirm the `mcp-oauth-inbound` policy
+  is attached to the route in `routes.oas.json` and the `McpGatewayPlugin` is
+  registered in `modules/zuplo.runtime.ts`.
+- **Browser login redirects but the callback fails.** The
+  `https://<gateway-host>/oauth/callback` URL isn't on the application's
+  redirect URI allow-list at the IdP.
+
+## Related
+
+- [Authentication overview](./overview.mdx) — the provider catalog and the
+  two-layer OAuth model.
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)
+- [Manual OAuth testing](./manual-oauth-testing.mdx)

package/docs/mcp-gateway/auth/configuring-google.mdx

@@ -0,0 +1,117 @@
+---
+title: "Configuring Google"
+sidebar_label: "Google"
+description:
+  Configure Google as the identity provider behind the MCP Gateway's downstream
+  OAuth using the mcp-google-oauth-inbound policy. Covers OAuth client setup in
+  Google Cloud and wiring the policy in your gateway project.
+---
+
+The MCP Gateway can use Google as the identity provider behind its downstream
+OAuth flow. The `mcp-google-oauth-inbound` policy is a Google-friendly wrapper
+around the generic `mcp-oauth-inbound` policy: provide a Google OAuth client ID
+and client secret, and the policy uses Google's fixed OIDC issuer
+(`https://accounts.google.com`) and discovery document automatically.
+
+This guide walks through the Google Cloud Console setup, then wires the policy
+into a gateway project. Read the [authentication overview](./overview.mdx) first
+for the two-layer OAuth model.
+
+## Set up Google
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Google.
+Google handles browser login; the gateway issues its own access tokens that bind
+to MCP routes.
+
+### Create an OAuth client
+
+1. In the Google Cloud Console, switch to the project that should own the OAuth
+   client, then open **APIs & Services → Credentials**.
+2. Click **Create credentials → OAuth client ID**. (If prompted, configure the
+   **OAuth consent screen** first — pick **Internal** for Google Workspace
+   tenants or **External** for general use, then add the user types you want to
+   allow.)
+3. Choose **Web application** as the application type.
+4. Give the client a name (for example, `Zuplo MCP Gateway`).
+5. Under **Authorized redirect URIs**, add
+   `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development with
+   `zuplo dev`.
+6. Click **Create**.
+
+Note the **Client ID** (looks like
+`123456789012-abc123def456.apps.googleusercontent.com`) and the **Client
+secret** from the dialog. The wrapper rejects values that aren't in Google's
+OAuth client ID shape.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "google-managed-oauth",
+  "policyType": "mcp-google-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpGoogleOAuthInboundPolicy",
+    "options": {
+      "clientId": "$env(GOOGLE_CLIENT_ID)",
+      "clientSecret": "$env(GOOGLE_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Set the two environment variables in your project's environment configuration.
+The secret values belong in the project secret store.
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## What the wrapper derives
+
+Google publishes a fixed OIDC discovery document at
+`https://accounts.google.com/.well-known/openid-configuration`. The wrapper
+hard-codes the corresponding endpoints:
+
+| Generic field           | Derived value                                  |
+| ----------------------- | ---------------------------------------------- |
+| `oidc.issuer`           | `https://accounts.google.com`                  |
+| `oidc.jwksUrl`          | `https://www.googleapis.com/oauth2/v3/certs`   |
+| `browserLogin.url`      | `https://accounts.google.com/o/oauth2/v2/auth` |
+| `browserLogin.tokenUrl` | `https://oauth2.googleapis.com/token`          |
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the Google sign-in page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`clientId` rejected at boot.** The wrapper rejects values that don't use
+  Google's OAuth client ID shape — issuer URLs, API hostnames, project numbers.
+  Use the full `123456789012-abc123def456.apps.googleusercontent.com` form.
+- **`redirect_uri_mismatch` from Google.** The redirect URI on the OAuth client
+  doesn't match `https://<gateway-host>/oauth/callback` exactly. Match scheme,
+  host, and path.
+- **`access_denied` for Google Workspace users.** The OAuth consent screen is
+  set to **Internal** but the user belongs to a different workspace, or the user
+  isn't on the **Test users** list during pre-verification.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

package/docs/mcp-gateway/auth/configuring-keycloak.mdx

@@ -0,0 +1,125 @@
+---
+title: "Configuring Keycloak"
+sidebar_label: "Keycloak"
+description:
+  Configure Keycloak to back the MCP Gateway's downstream OAuth using the
+  mcp-keycloak-oauth-inbound policy. Covers realm client setup and wiring the
+  policy in your gateway project.
+---
+
+The MCP Gateway can use Keycloak as the identity provider behind its downstream
+OAuth flow. The `mcp-keycloak-oauth-inbound` policy is a Keycloak-friendly
+wrapper around the generic `mcp-oauth-inbound` policy: provide your Keycloak
+base URL, a realm name, a client ID, and a client secret, and the policy derives
+the realm-issuer URL, JWKS URL, and authorize and token URLs from Keycloak's
+standard OpenID Connect endpoint layout.
+
+This guide walks through the Keycloak admin console setup, then wires the policy
+into a gateway project. Read the [authentication overview](./overview.mdx) first
+for the two-layer OAuth model.
+
+## Set up Keycloak
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Keycloak.
+Keycloak handles browser login; the gateway issues its own access tokens that
+bind to MCP routes.
+
+### Create a client in the realm
+
+1. In the Keycloak admin console, switch to the realm you want the gateway to
+   use.
+2. Open **Clients** and click **Create client**.
+3. Give the client a Client ID (for example, `zuplo-mcp-gateway`) and click
+   **Next**.
+4. Enable **Client authentication** (so the client requires a secret) and leave
+   **Standard flow** (authorization code) enabled. Disable **Service accounts
+   roles** and **Direct access grants** — the gateway only needs the browser
+   code flow.
+5. Click **Next**.
+6. Set **Valid redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development.
+7. Set **Web origins** to `https://<gateway-host>` (and `http://localhost:9000`
+   for local dev).
+8. Click **Save**.
+
+### Note the client credentials
+
+Open the client's **Credentials** tab. Copy the **Client secret**. The **Client
+ID** is the value you set above.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "keycloak-managed-oauth",
+  "policyType": "mcp-keycloak-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpKeycloakOAuthInboundPolicy",
+    "options": {
+      "keycloakBaseUrl": "$env(KEYCLOAK_BASE_URL)",
+      "realm": "$env(KEYCLOAK_REALM)",
+      "clientId": "$env(KEYCLOAK_CLIENT_ID)",
+      "clientSecret": "$env(KEYCLOAK_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+:::caution
+
+`keycloakBaseUrl` is the Keycloak server root, without `/realms/{realm}` — set
+the realm separately on the `realm` option. If your deployment uses a path
+prefix (legacy `/auth`), include that in `keycloakBaseUrl`
+(`https://sso.example.com/auth`).
+
+:::
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## What the wrapper derives
+
+Given `keycloakBaseUrl: "https://sso.example.com"` and
+`realm: "customer-portal"`:
+
+| Generic field           | Derived value                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `oidc.issuer`           | `https://sso.example.com/realms/customer-portal`                               |
+| `oidc.jwksUrl`          | `https://sso.example.com/realms/customer-portal/protocol/openid-connect/certs` |
+| `browserLogin.url`      | `https://sso.example.com/realms/customer-portal/protocol/openid-connect/auth`  |
+| `browserLogin.tokenUrl` | `https://sso.example.com/realms/customer-portal/protocol/openid-connect/token` |
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the Keycloak sign-in page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`keycloakBaseUrl` rejected at boot.** The value includes `/realms/...`.
+  Strip the realm path; pass the realm name on the `realm` option instead.
+- **`Invalid redirect_uri` from Keycloak.** The callback URL on the client
+  doesn't match `https://<gateway-host>/oauth/callback`.
+- **`Invalid client credentials`.** The client isn't a confidential client
+  (Client authentication off), or the secret value doesn't match. Re-copy the
+  secret from the **Credentials** tab.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

package/docs/mcp-gateway/auth/configuring-logto.mdx

@@ -0,0 +1,116 @@
+---
+title: "Configuring Logto"
+sidebar_label: "Logto"
+description:
+  Configure Logto to back the MCP Gateway's downstream OAuth using the
+  mcp-logto-oauth-inbound policy. Covers application setup and wiring the policy
+  in your gateway project.
+---
+
+The MCP Gateway can use [Logto](https://logto.io/) as the identity provider
+behind its downstream OAuth flow. The `mcp-logto-oauth-inbound` policy is a
+Logto-friendly wrapper around the generic `mcp-oauth-inbound` policy: provide
+your Logto tenant endpoint, a client ID, and a client secret, and the policy
+derives the OIDC issuer, JWKS URL, and authorize and token URLs from Logto's
+`/oidc` mount point.
+
+This guide walks through the Logto console setup, then wires the policy into a
+gateway project. Read the [authentication overview](./overview.mdx) first for
+the two-layer OAuth model.
+
+## Set up Logto
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Logto.
+Logto handles browser login; the gateway issues its own access tokens that bind
+to MCP routes.
+
+### Create a Traditional Web application
+
+1. In the Logto Console, open **Applications** and click **Create application**.
+2. Pick **Traditional Web** as the application type. (Not SPA, not Native — the
+   gateway needs a confidential client with a secret.)
+3. Give the application a name (for example, `Zuplo MCP Gateway`) and click
+   **Create application**.
+4. On the application's **Settings** tab, set **Redirect URIs** to
+   `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development.
+5. Save.
+
+Note the **App ID** (= client ID) and **App secret** (= client secret) from the
+application's detail page.
+
+### Find your tenant endpoint
+
+Open **Settings → Domains** in the Logto Console. Your default tenant endpoint
+looks like `https://your-tenant.logto.app`. If you've configured a custom
+domain, use that instead. The wrapper takes the origin only — no `/oidc`, no
+`.well-known/...`, no trailing slash.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "logto-managed-oauth",
+  "policyType": "mcp-logto-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpLogtoOAuthInboundPolicy",
+    "options": {
+      "logtoEndpoint": "$env(LOGTO_ENDPOINT)",
+      "clientId": "$env(LOGTO_CLIENT_ID)",
+      "clientSecret": "$env(LOGTO_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Attach the policy to each MCP route in `config/routes.oas.json` and register the
+gateway plugin in `modules/zuplo.runtime.ts` (see
+[Configuring Auth0](./configuring-auth0.mdx#wire-the-policy-into-the-gateway)
+for the route and plugin patterns — they're identical across all wrappers).
+
+## What the wrapper derives
+
+Given `logtoEndpoint: "https://acme.logto.app"`:
+
+| Generic field           | Derived value                       |
+| ----------------------- | ----------------------------------- |
+| `oidc.issuer`           | `https://acme.logto.app/oidc`       |
+| `oidc.jwksUrl`          | `https://acme.logto.app/oidc/jwks`  |
+| `browserLogin.url`      | `https://acme.logto.app/oidc/auth`  |
+| `browserLogin.tokenUrl` | `https://acme.logto.app/oidc/token` |
+
+These endpoint shapes come from Logto's OIDC provider mounted at `/oidc` and its
+discovery document at
+`https://<your-logto-endpoint>/oidc/.well-known/openid-configuration`.
+
+## Test the configuration
+
+The fastest sanity check is to connect an MCP client:
+
+1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
+2. Add a remote MCP server pointing at one of your `/mcp/{slug}` routes.
+3. The client should redirect you to the Logto sign-in page. After login, the
+   gateway's consent screen renders. Approve it.
+4. The client receives an access token and can call `tools/list`.
+
+If something fails partway through, walk the flow manually using the
+[manual OAuth testing guide](./manual-oauth-testing.mdx) — it exercises every
+endpoint with `curl` so you can see the raw responses.
+
+## Common issues
+
+- **`logtoEndpoint` rejected at boot.** The value includes `/oidc`,
+  `/.well-known/openid-configuration`, or another path. Use the bare tenant
+  endpoint origin.
+- **`redirect_uri` rejected by Logto.** The redirect URI on the application
+  doesn't match `https://<gateway-host>/oauth/callback`. Match scheme, host, and
+  path.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)