zuplo 6.70.54 → 6.70.56

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

@@ -0,0 +1,216 @@
+---
+title: "Configuring Auth0"
+sidebar_label: "Auth0"
+description:
+  Configure Auth0 to back the MCP Gateway's downstream OAuth using the
+  mcp-auth0-oauth-inbound policy. Covers tenant setup, application
+  configuration, and wiring the policy in your gateway project.
+---
+
+The MCP Gateway can use Auth0 as the identity provider behind its downstream
+OAuth flow. The `mcp-auth0-oauth-inbound` policy is an Auth0-friendly wrapper
+around the generic `mcp-oauth-inbound` policy: provide your Auth0 domain, a
+client ID, and a client secret, and the policy derives the OIDC issuer, JWKS
+URL, and Auth0 authorize and token URLs for you.
+
+This guide walks through the Auth0 dashboard setup, then shows how to wire the
+policy into your gateway project. Read the
+[authentication overview](./overview.mdx) first for the two-layer model and the
+role each policy plays.
+
+:::note
+
+This guide assumes you have a working Auth0 tenant. The
+[Auth0 MCP client registration guide](https://auth0.com/ai/docs/mcp/guides/registering-your-mcp-client-application)
+is the authoritative source for Auth0-side configuration.
+
+:::
+
+Most projects only need three options: `auth0Domain`, `clientId`, and
+`clientSecret`. `audience`, `scope`, and the TTL options are all optional.
+
+:::caution
+
+`auth0Domain` is a **bare hostname**, not a URL. Use `my-tenant.us.auth0.com`,
+not `https://my-tenant.us.auth0.com/`.
+
+:::
+
+## Set up the Auth0 tenant
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Auth0.
+Auth0 handles browser login and identity; the gateway issues its own access
+tokens that bind to MCP routes. The Auth0 application you create represents the
+**gateway's identity** against Auth0, not the MCP client.
+
+### Create an Auth0 application
+
+1. In the Auth0 Dashboard, open **Applications > Applications** and click
+   **Create Application**.
+2. Set a name (for example, `Zuplo MCP Gateway`).
+3. Choose **Regular Web Application** as the application type and click
+   **Create**.
+4. On the **Settings** tab, note the **Domain**, **Client ID**, and **Client
+   Secret**. You'll wire these into the policy in the next section.
+
+### Configure callback and origin URLs
+
+The gateway completes browser login by redirecting back to its own
+`/oauth/callback` endpoint, so Auth0 needs that URL on its allow-list.
+
+On the same **Settings** tab:
+
+1. Set **Allowed Callback URLs** to your gateway's
+   `https://<gateway-host>/oauth/callback`. For local development against
+   `zuplo dev`, add `http://localhost:9000/oauth/callback` as well.
+2. Set **Allowed Web Origins** to the gateway origin `https://<gateway-host>`
+   (plus `http://localhost:9000` for local dev).
+3. Save changes.
+
+### Optional: Set an audience
+
+If you want Auth0 to issue identity-bound API access tokens (for example, to
+validate Auth0-issued tokens against a specific resource server), create an API
+under **Applications > APIs** with an identifier like
+`https://gateway.example.com` and pass that identifier as the `audience` option
+on the policy. When omitted, Auth0 acts only as the browser identity layer and
+the gateway alone owns the OAuth grant the MCP client receives.
+
+### Connections and dynamic client registration
+
+The downstream OAuth flow only requires Auth0 to authenticate the user and
+return an ID token. CIMD and DCR on Auth0's side concern the **upstream MCP
+server's** trust of clients, not the gateway's trust of Auth0. If you also
+configure Auth0 itself as an upstream MCP authorization provider (rare), follow
+Auth0's own guide for
+[enabling CIMD](https://auth0.com/ai/docs/mcp/guides/registering-your-mcp-client-application/manual-cimd-registration)
+or
+[enabling DCR](https://auth0.com/ai/docs/mcp/guides/registering-your-mcp-client-application/dynamic-client-registration).
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "auth0-managed-oauth",
+  "policyType": "mcp-auth0-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpAuth0OAuthInboundPolicy",
+    "options": {
+      "auth0Domain": "$env(AUTH0_DOMAIN)",
+      "clientId": "$env(AUTH0_CLIENT_ID)",
+      "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Set the three environment variables in your Zuplo project's environment
+configuration. `AUTH0_DOMAIN` is the bare hostname; the secret values belong in
+the project secret store.
+
+Attach the policy to each MCP route in `config/routes.oas.json`:
+
+```jsonc
+{
+  "paths": {
+    "/mcp/linear": {
+      "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": ["auth0-managed-oauth", "mcp-token-exchange-linear"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Finally, register the gateway plugin in `modules/zuplo.runtime.ts` so the
+runtime registers the OAuth endpoints automatically:
+
+```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 — there's no need to
+declare it more than once. Attaching the same policy by name to each route is
+the canonical pattern.
+
+## Full options reference
+
+`mcp-auth0-oauth-inbound` has three required options and a few optional
+overrides. The complete schema is documented on the policy reference page; the
+fields you'll touch most often are:
+
+| Option                                    | Required | Default                | Notes                                                                                      |
+| ----------------------------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------ |
+| `auth0Domain`                             | yes      | —                      | Bare hostname (`my-tenant.us.auth0.com`). No scheme, must contain a dot.                   |
+| `clientId`                                | yes      | —                      | Auth0 application client ID.                                                               |
+| `clientSecret`                            | yes      | —                      | Auth0 application client secret. Use `$env(...)` to source from a secret.                  |
+| `audience`                                | no       | unset                  | Optional Auth0 API identifier. Sent as the `?audience=` parameter to Auth0's `/authorize`. |
+| `scope`                                   | no       | `openid profile email` | OIDC scopes requested during browser login.                                                |
+| `gateway.accessTokenTtlSeconds`           | no       | `900`                  | Gateway-issued access token lifetime.                                                      |
+| `gateway.refreshTokenTtlSeconds`          | no       | long-lived             | Gateway-issued refresh token lifetime. Override only if you need to shorten sessions.      |
+| `gateway.cimdEnabled`                     | no       | `true`                 | Advertise CIMD support in AS metadata.                                                     |
+| `browserLoginOverrides.sessionTtlSeconds` | no       | `28800`                | Browser session cookie lifetime (8 hours).                                                 |
+| `browserLoginOverrides.stateTtlSeconds`   | no       | `900`                  | Browser-login state record lifetime.                                                       |
+| `browserLoginOverrides.remoteTimeoutMs`   | no       | `10000`                | Outbound timeout to Auth0 (token exchange, JWKS fetch).                                    |
+
+## Test the configuration
+
+The fastest sanity check is to try connecting 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 on the
+   gateway.
+3. The client should redirect you to Auth0'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
+
+- **"Invalid Auth0 domain" at boot.** The `auth0Domain` value includes a scheme
+  prefix or doesn't contain a dot. Use `my-tenant.us.auth0.com`.
+- **Browser login redirects but the callback fails.** The
+  `https://<gateway-host>/oauth/callback` URL isn't on the **Allowed Callback
+  URLs** list for the Auth0 application.
+- **Token endpoint returns `invalid_audience`.** The MCP client is reusing a
+  token bound to a different route. Each gateway-issued token binds to one
+  `operationId`; the client must obtain a separate token per route.
+- **Issuer in AS metadata is wrong.** The gateway derives its issuer from the
+  incoming request origin. Check that your custom domain or proxy forwards the
+  correct `Host` or `X-Forwarded-Host` header. See
+  [Troubleshooting](../troubleshooting.mdx).
+- **MCP client can't discover the AS.** Confirm the `mcp-auth0-oauth-inbound`
+  policy is attached to the route in `routes.oas.json` and that the
+  `McpGatewayPlugin` is registered in `modules/zuplo.runtime.ts`. The internal
+  OAuth endpoints register only when both are present.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- `mcp-auth0-oauth-inbound` policy reference
+- [Configuring Okta or any other OIDC IdP](./configuring-okta.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)

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

@@ -0,0 +1,153 @@
+---
+title: "Configuring Clerk"
+sidebar_label: "Clerk"
+description:
+  Configure Clerk to back the MCP Gateway's downstream OAuth using the
+  mcp-clerk-oauth-inbound policy. Covers OAuth application setup and wiring the
+  policy in your gateway project.
+---
+
+The MCP Gateway can use [Clerk](https://clerk.com/) as the identity provider
+behind its downstream OAuth flow. The `mcp-clerk-oauth-inbound` policy is a
+Clerk-friendly wrapper around the generic `mcp-oauth-inbound` policy: provide
+your Clerk Frontend API URL, a client ID, and a client secret, and the policy
+derives the OIDC issuer, JWKS URL, and authorize and token URLs for you.
+
+This guide walks through the Clerk dashboard setup, then wires the policy into a
+gateway project. Read the [authentication overview](./overview.mdx) first for
+the two-layer OAuth model.
+
+## Set up Clerk
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Clerk.
+Clerk handles browser login; the gateway issues its own access tokens that bind
+to MCP routes.
+
+### Create an OAuth application
+
+1. In the Clerk Dashboard, switch to the instance you want the gateway to use,
+   then open **Configure → OAuth Applications**.
+2. Click **Add OAuth application**.
+3. Give the application a name (for example, `Zuplo MCP Gateway`).
+4. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development with
+   `zuplo dev`.
+5. Select the OIDC scopes the gateway needs — `openid`, `profile`, and `email`
+   are enough.
+6. Click **Save**.
+
+Note the **Client ID** and **Client Secret** from the application's detail page.
+You'll wire these into the policy in the next section.
+
+### Find the Frontend API URL
+
+Open **Configure → Domains** in the Clerk Dashboard. The **Frontend API URL** is
+shown at the top — it looks like `https://verb-noun-00.clerk.accounts.dev` on
+development instances or `https://clerk.example.com` on production instances
+with a custom domain. Copy the origin (no trailing path).
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "clerk-managed-oauth",
+  "policyType": "mcp-clerk-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpClerkOAuthInboundPolicy",
+    "options": {
+      "frontendApiUrl": "$env(CLERK_FRONTEND_API_URL)",
+      "clientId": "$env(CLERK_CLIENT_ID)",
+      "clientSecret": "$env(CLERK_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+:::caution
+
+`frontendApiUrl` is the origin only. Don't include a path, query string, or
+fragment — the policy fails at boot if any of those are present.
+
+:::
+
+Set the three environment variables in your project's environment configuration.
+`CLERK_FRONTEND_API_URL` goes in plain config; the secret values belong in the
+project 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": ["clerk-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());
+}
+```
+
+## What the wrapper derives
+
+| Generic field           | Derived value                            |
+| ----------------------- | ---------------------------------------- |
+| `oidc.issuer`           | `{frontendApiUrl}`                       |
+| `oidc.jwksUrl`          | `{frontendApiUrl}/.well-known/jwks.json` |
+| `browserLogin.url`      | `{frontendApiUrl}/oauth/authorize`       |
+| `browserLogin.tokenUrl` | `{frontendApiUrl}/oauth/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 Clerk'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 policy rejects `frontendApiUrl` at boot.** The value includes a path,
+  query string, or fragment. Use only the origin (`https://clerk.example.com`).
+- **Browser login redirects but the callback fails.** The
+  `https://<gateway-host>/oauth/callback` URL isn't on the OAuth application's
+  redirect URIs allow-list in Clerk.
+
+## 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-cognito.mdx

@@ -0,0 +1,128 @@
+---
+title: "Configuring Amazon Cognito"
+sidebar_label: "Amazon Cognito"
+description:
+  Configure Amazon Cognito to back the MCP Gateway's downstream OAuth using the
+  mcp-cognito-oauth-inbound policy. Covers user pool setup, hosted UI domain,
+  and wiring the policy in your gateway project.
+---
+
+The MCP Gateway can use Amazon Cognito as the identity provider behind its
+downstream OAuth flow. The `mcp-cognito-oauth-inbound` policy is a
+Cognito-friendly wrapper around the generic `mcp-oauth-inbound` policy: provide
+your AWS region, user pool ID, hosted UI domain, client ID, and client secret,
+and the policy derives the OIDC issuer, JWKS URL, and authorize and token URLs
+for you.
+
+This guide walks through the Cognito user pool setup, then wires the policy into
+a gateway project. Read the [authentication overview](./overview.mdx) first for
+the two-layer OAuth model.
+
+:::note
+
+Cognito splits OIDC across two domains: discovery and JWKS are served from the
+Cognito IDP service domain (`cognito-idp.{region}.amazonaws.com/{userPoolId}`),
+while browser login is served from the **user pool hosted UI domain**. The
+wrapper handles both.
+
+:::
+
+## Set up Cognito
+
+### Create or pick a user pool
+
+1. In the AWS Cognito console, open **User pools** and either pick an existing
+   pool or create a new one. Note the **User pool ID** (it looks like
+   `us-east-1_AbCdEf123`).
+2. Under **App integration**, set up a **hosted UI domain**. You can use a
+   Cognito-prefix domain like `my-pool.auth.us-east-1.amazoncognito.com` or a
+   custom domain like `auth.example.com`. The wrapper takes only the host — no
+   scheme, no path.
+
+### Create an app client
+
+1. Under **App integration → App clients**, click **Create app client**.
+2. Choose **Confidential client**. The client must have a client secret — the
+   gateway needs it for the federated token exchange.
+3. Set **Allowed callback URLs** to `https://<gateway-host>/oauth/callback`. Add
+   `http://localhost:9000/oauth/callback` for local development.
+4. Enable **Authorization code grant** under allowed OAuth flows.
+5. Enable the OIDC scopes the gateway needs — `openid`, `profile`, and `email`.
+6. Click **Create app client**.
+
+Note the **Client ID** and **Client Secret** from the app client's detail page.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "cognito-managed-oauth",
+  "policyType": "mcp-cognito-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpCognitoOAuthInboundPolicy",
+    "options": {
+      "awsRegion": "us-east-1",
+      "userPoolId": "$env(COGNITO_USER_POOL_ID)",
+      "userPoolDomain": "$env(COGNITO_USER_POOL_DOMAIN)",
+      "clientId": "$env(COGNITO_CLIENT_ID)",
+      "clientSecret": "$env(COGNITO_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+:::caution
+
+`userPoolDomain` is the hosted UI host only — no `https://`, no trailing slash,
+no path. The policy fails at boot if any of those are present.
+
+:::
+
+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
+
+| Generic field           | Derived value                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| `oidc.issuer`           | `https://cognito-idp.{awsRegion}.amazonaws.com/{userPoolId}`                       |
+| `oidc.jwksUrl`          | `https://cognito-idp.{awsRegion}.amazonaws.com/{userPoolId}/.well-known/jwks.json` |
+| `browserLogin.url`      | `https://{userPoolDomain}/oauth2/authorize`                                        |
+| `browserLogin.tokenUrl` | `https://{userPoolDomain}/oauth2/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 Cognito hosted UI 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
+
+- **The policy rejects `userPoolDomain` at boot.** The value includes
+  `https://`, a trailing slash, or an OAuth path. Strip those — use only
+  `auth.example.com` or `my-pool.auth.us-east-1.amazoncognito.com`.
+- **Browser login lands on a Cognito error page.** The callback URL on the app
+  client doesn't match. Set it to `https://<gateway-host>/oauth/callback`
+  exactly.
+- **`invalid_client` from Cognito's token endpoint.** The app client doesn't
+  have a client secret, or the secret value doesn't match. Cognito confidential
+  clients require both ID and secret.
+
+## 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-entra.mdx

@@ -0,0 +1,134 @@
+---
+title: "Configuring Microsoft Entra ID"
+sidebar_label: "Microsoft Entra"
+description:
+  Configure Microsoft Entra ID to back the MCP Gateway's downstream OAuth using
+  the mcp-entra-oauth-inbound policy. Covers app registration and wiring the
+  policy in your gateway project.
+---
+
+The MCP Gateway can use Microsoft Entra ID (formerly Azure AD) as the identity
+provider behind its downstream OAuth flow. The `mcp-entra-oauth-inbound` policy
+is an Entra-friendly wrapper around the generic `mcp-oauth-inbound` policy:
+provide your Entra tenant UUID, a client ID, and a client secret, and the policy
+derives the v2 OIDC issuer, JWKS URL, and authorize and token URLs for you.
+
+This guide walks through the Microsoft Entra admin center setup, then wires the
+policy into a gateway project. Read the
+[authentication overview](./overview.mdx) first for the two-layer OAuth model.
+
+:::caution
+
+This policy is **single-tenant**. The multi-tenant aliases `common`,
+`organizations`, and `consumers` are not supported because Entra's issuer claim
+is tenant-specific and the gateway enforces an exact issuer match. Use a real
+tenant UUID.
+
+:::
+
+## Set up Microsoft Entra
+
+The MCP Gateway acts as an OAuth 2.1 authorization server in front of Entra.
+Entra handles browser login; the gateway issues its own access tokens that bind
+to MCP routes.
+
+### Register an application
+
+1. In the Microsoft Entra admin center, open **Identity → Applications → App
+   registrations** and click **New registration**.
+2. Give the application a name (for example, `Zuplo MCP Gateway`).
+3. Under **Supported account types**, choose **Accounts in this organizational
+   directory only (single tenant)**. The wrapper does not support multi-tenant
+   modes.
+4. Under **Redirect URI**, choose **Web** and set the value to
+   `https://<gateway-host>/oauth/callback`. Click **Register**.
+5. On the application's **Overview** page, note the **Application (client) ID**
+   and the **Directory (tenant) ID**. Both are UUIDs.
+
+### Add a client secret
+
+1. Open **Certificates & secrets** on the application and click **New client
+   secret**.
+2. Set a description and an expiration window, then click **Add**.
+3. Copy the secret **Value** immediately — Entra only shows it once.
+
+### Add the local development redirect URI
+
+1. Open **Authentication** on the application.
+2. Add `http://localhost:9000/oauth/callback` under **Web → Redirect URIs**.
+3. Save.
+
+### Optional: restrict access
+
+By default any user in the tenant can sign in. To restrict access to specific
+groups, open **Enterprise applications**, find the same application, and use
+**Properties → Assignment required** plus **Users and groups** assignments.
+
+## Wire the policy into the gateway
+
+Add the policy to `config/policies.json`:
+
+```json
+{
+  "name": "entra-managed-oauth",
+  "policyType": "mcp-entra-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpEntraOAuthInboundPolicy",
+    "options": {
+      "tenantId": "$env(ENTRA_TENANT_ID)",
+      "clientId": "$env(ENTRA_CLIENT_ID)",
+      "clientSecret": "$env(ENTRA_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Set the three 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
+
+| Generic field           | Derived value                                                        |
+| ----------------------- | -------------------------------------------------------------------- |
+| `oidc.issuer`           | `https://login.microsoftonline.com/{tenantId}/v2.0`                  |
+| `oidc.jwksUrl`          | `https://login.microsoftonline.com/{tenantId}/discovery/v2.0/keys`   |
+| `browserLogin.url`      | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` |
+| `browserLogin.tokenUrl` | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/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 Microsoft 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
+
+- **`tenantId` rejected at boot.** The wrapper accepts only a tenant UUID, not a
+  verified domain, `common`, `organizations`, or `consumers`. Look up the tenant
+  ID under **Overview** in the Entra admin center.
+- **`AADSTS50011` redirect URI mismatch.** The redirect URI on the app
+  registration doesn't match `https://<gateway-host>/oauth/callback` exactly.
+  Match scheme, host, and path.
+- **`AADSTS700016` application not found.** The client ID doesn't belong to the
+  tenant the wrapper is configured with. Make sure `tenantId` and `clientId`
+  come from the same app registration.
+
+## Related
+
+- [Authentication overview](./overview.mdx)
+- [Configuring a generic OIDC provider](./configuring-generic-oidc.mdx)
+- [Per-user OAuth to upstream MCP servers](./upstream-oauth.mdx)