zuplo 7.6.8 → 7.6.10

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -6,10 +6,9 @@ description:
   authenticated, metered, and routed by the gateway.
 ---
 
-The Zuplo AI Gateway supports the [Anthropic](https://docs.claude.com/en/home)
-`/v1/messages` API endpoint. This means that you can configure
-[Claude Code](https://www.claude.com/product/claude-code) to work seamlessly via
-the AI Gateway.
+You can configure [Claude Code](https://www.claude.com/product/claude-code) to
+send its model requests through the Zuplo AI Gateway, so the gateway
+authenticates, meters, and routes every Claude Code session.
 
 ## Claude Code Setup
 
@@ -25,25 +24,48 @@ the AI Gateway.
 
 4. Copy the **API URL** and **API Key** shown at the top of the app page
 
-5. Add the API key and gateway URL to your environment, or Claude Code settings,
-   using either approach below
+5. Add the API key, gateway URL, and model mappings to `.claude/settings.json`
 
 </Stepper>
 
-### Environment
+### Before copying: replace the provider name
 
-```
-ANTHROPIC_AUTH_TOKEN=<your-ai-gateway-app-api-key>
-ANTHROPIC_BASE_URL=https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e
-```
+:::warning
+
+The examples below assume your provider is named `anthropic`. Replace that
+prefix with the name of **your** provider before copying the configuration. For
+example, a provider named `my-anthropic` routes `my-anthropic/claude-sonnet-5`,
+while a Bedrock provider named `bedrock` routes
+`bedrock/anthropic.claude-sonnet-5`. The model part must be an id that provider
+understands.
+
+:::
+
+The gateway routes every request using `providerName/model`. The provider prefix
+picks which of your providers handles the request — a gateway can contain
+several providers that serve Anthropic models.
 
 ### Using settings.json
 
+You can configure Claude Code either globally or per project by editing the
+settings file:
+
+- **Global:** `~/.claude/settings.json`
+- **Project-specific:** `.claude/settings.json` in your project directory
+
+Add the following environment configuration to the settings file:
+
 ```json
 {
   "env": {
     "ANTHROPIC_AUTH_TOKEN": "<your-ai-gateway-app-api-key>",
-    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e"
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
   }
 }
 ```
@@ -58,16 +80,36 @@ Claude Code appends `/v1/messages` to the base URL itself, so
 Restart Claude and it will switch to using your new AI Gateway configuration and
 all your Claude Code LLM requests will route through the AI Gateway.
 
-### Choosing a model
+### Configure every Claude Code model variable
 
-The gateway routes models named as `providerName/model`, where `providerName` is
-the provider name configured in your gateway. Claude Code's default model names
-don't carry that prefix, so set the model explicitly:
+The model ids in these examples reflect what was current when this page was
+written, and ids differ across providers — a Bedrock provider serves different
+ids than Anthropic directly, and availability can vary by region. Check
+[your provider's page](../managing-providers.mdx) in the portal for the models
+it currently serves, and use those ids.
 
-```
-ANTHROPIC_MODEL=anthropic/claude-sonnet-4-5-20250929
-ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
-```
+None of Claude Code's built-in model names carry a provider prefix, so each of
+the model variables above must be set to a prefixed reference:
+
+- `ANTHROPIC_MODEL` — the main model. Required: without it Claude Code sends its
+  built-in default model unprefixed and the first request fails.
+- `ANTHROPIC_SMALL_FAST_MODEL` — the model for background tasks.
+- `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
+  `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` — what the
+  `opus`/`sonnet`/`haiku`/`fable` aliases resolve to, so `claude --model opus`
+  and `/model sonnet` keep working. In these examples,
+  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5`.
+
+:::caution{title='HTTP 400: model must use "providerName/model"'}
+
+If Claude Code fails immediately with
+`The request body model must use "providerName/model"`, the request carried a
+model name without a provider prefix. The tier alias variables
+(`ANTHROPIC_DEFAULT_*_MODEL`) alone don't prevent this — they don't cover Claude
+Code's built-in default model. Always set `ANTHROPIC_MODEL` to a prefixed model
+reference.
+
+:::
 
 The app's
 [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)

package/docs/ai-gateway/integrations/claude-desktop.mdx

@@ -0,0 +1,157 @@
+---
+title: Claude Desktop
+sidebar_label: Claude Desktop
+description:
+  Point Claude Desktop at an AI Gateway app so every Chat, Cowork, and Code
+  session is authenticated, metered, and routed by the gateway.
+---
+
+[Claude Desktop](https://claude.com/download) can use the Zuplo AI Gateway as
+its inference provider, so the gateway authenticates, meters, and routes every
+Chat, Cowork, and Code session started from the desktop app.
+
+This page covers routing Claude Desktop's model requests through the AI Gateway.
+To give Claude Desktop tools from a Zuplo MCP route instead, see
+[Connect Claude Desktop and Claude.ai](../../mcp-gateway/connect-clients/claude-desktop.mdx).
+
+## Claude Desktop Setup
+
+<Stepper>
+
+1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
+   Anthropic
+
+2. [Set up a new team](../managing-teams.mdx)
+
+3. Create a [new app](../managing-apps.mdx) to use with Claude Desktop and
+   assign it to the team you created
+
+4. Copy the **API URL** and **API Key** shown at the top of the app page
+
+5. Enter the API URL, API key, and model list in Claude Desktop's third-party
+   inference settings
+
+</Stepper>
+
+### Before copying: replace the provider name
+
+:::warning
+
+The examples below assume your provider is named `anthropic`. Replace that
+prefix with the name of **your** provider before copying the configuration. For
+example, a provider named `my-anthropic` routes `my-anthropic/claude-sonnet-5`,
+while a Bedrock provider named `bedrock` routes
+`bedrock/anthropic.claude-sonnet-5`. The model part must be an id that provider
+understands.
+
+:::
+
+The gateway routes every request using `providerName/model`. The provider prefix
+picks which of your providers handles the request — a gateway can contain
+several providers that serve Anthropic models.
+
+### Configure third-party inference
+
+Configure Claude Desktop's inference provider in its in-app configuration
+window, available on macOS and Windows:
+
+<Stepper>
+
+1. From the menu bar (macOS) or the application menu (Windows), select **Help →
+   Troubleshooting → Enable Developer Mode**.
+
+2. Open **Developer → Configure Third-Party Inference**.
+
+3. In the **Connection** section, set **Inference provider** to **Gateway**.
+
+4. In the **Gateway credentials** card, set **Gateway base URL** to the app's
+   API URL, for example
+   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`,
+   and **Gateway API key** to the app's API key.
+
+5. Leave **Credential kind** set to **Static API key** and **Gateway auth
+   scheme** set to **Bearer**.
+
+6. In the **Models** section, add the models the app may use to the **Model
+   list**. See [Add models to the Model list](#add-models-to-the-model-list).
+
+7. Click **Apply locally**. Claude Desktop writes the configuration and
+   relaunches into it.
+
+</Stepper>
+
+:::note
+
+Claude Desktop appends `/v1/messages` to the base URL itself, so **Gateway base
+URL** is the app's URL _without_ the `/v1` suffix.
+
+:::
+
+:::caution{title="Keep the auth scheme set to Bearer"}
+
+The gateway reads the API key from the `Authorization: Bearer` header, so keep
+**Gateway auth scheme** set to **Bearer**. Likewise, keep **Credential kind**
+set to **Static API key** — AI Gateway apps authenticate with their own API
+keys, not identity-provider tokens.
+
+:::
+
+### Add models to the Model list
+
+The **Model list** in the **Models** section overrides the model list Claude
+Desktop discovers on its own. Click **Add** once per model the app may use, and
+fill in each entry:
+
+- **Model ID** — the full `providerName/model` reference, for example
+  `anthropic/claude-sonnet-5`. A bare id such as `claude-sonnet-5` fails to
+  route through the gateway.
+- **Display name** — the name shown in the model picker, for example
+  `Claude Sonnet 5`. Leave it blank and Claude Desktop formats a name from the
+  id.
+- **Offer 1M-context variant** — leave this off unless your provider's
+  deployment accepts 1M-token context for the model.
+- **Tier alias** — the Claude tier (Opus, Sonnet, Haiku, or Fable) this model
+  stands in for. Setting it pins what the bare alias (for example `opus`)
+  resolves to, so tier names route to your prefixed model reference.
+
+The first entry is the default selection in the model picker. Include a
+Haiku-tier model — Claude Desktop runs background and sub-agent tasks on a
+small, fast model.
+
+The model ids in these examples reflect what was current when this page was
+written, and ids differ across providers — a Bedrock provider serves different
+ids than Anthropic directly, and availability can vary by region. Check
+[your provider's page](../managing-providers.mdx) in the portal for the models
+it currently serves, and use those ids.
+
+The app's
+[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
+policy controls which models the app may use.
+
+### Verify the configuration
+
+After Claude Desktop relaunches, send a message in a Chat conversation and start
+a Cowork session. Both requests route through the gateway and count against the
+[app](../managing-apps.mdx) in the Zuplo Portal, as do Code sessions started
+from the desktop app. Terminal Claude Code sessions outside the desktop app use
+a separate configuration — see [Claude Code](./claude-code.mdx).
+
+:::caution{title='HTTP 400: model must use "providerName/model"'}
+
+If a request fails with `The request body model must use "providerName/model"`,
+the selected model reference is missing its provider prefix. Give every entry in
+the model list a full `providerName/model` reference.
+
+:::
+
+### Deploy to a fleet
+
+To roll the configuration out to many devices, use the configuration window's
+**Export** menu instead of **Apply locally**. It generates a `.mobileconfig`
+profile for macOS MDM tools such as Jamf, a `.reg` policy file for Intune or
+Group Policy, and related deployment artifacts. Managed configuration takes
+precedence over local settings, so users can't point the app at a different
+endpoint. For the deployment workflow and the full configuration key reference,
+see Anthropic's
+[Deploy Claude Desktop with an LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway)
+and [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).

package/docs/articles/configuring-auth0-for-mcp-auth.mdx

@@ -174,11 +174,16 @@ will need to do the following:
        new OAuthProtectedResourcePlugin({
          authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["openid", "profile", "email", "offline_access"],
        }),
      );
    }
    ```
 
+   `scopesSupported` lists the scopes MCP clients request. Replace the example
+   values with the permissions your Auth0 API defines; keep `offline_access` if
+   clients need refresh tokens.
+
    See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
    for more details.

package/docs/articles/configuring-okta-for-mcp-auth.mdx

@@ -50,6 +50,19 @@ Next, you'll need to configure the scopes for your authorization server.
    tools").
 5. Check **Set as a default scope** and click **Create**.
 
+:::caution{title="Reserved Okta scopes break MCP clients"}
+
+Every Okta custom authorization server also publishes `device_sso` and
+`interclient_access` in its `scopes_supported` metadata. The **Include in public
+metadata** toggle for those two scopes is disabled, so you can't remove them. An
+MCP client that builds its scope list from the authorization server's metadata
+requests them together with `mcp:access`, and Okta rejects the authorization
+request with `illegal_scope_combination`. To keep clients off that list, set
+`scopesSupported` on the `OAuthProtectedResourcePlugin` in
+[Configure OAuth on Zuplo](#configure-oauth-on-zuplo) below.
+
+:::
+
 ## Create an OAuth Client Application
 
 Next, you'll need to create an OAuth client application for your MCP server.
@@ -102,7 +115,10 @@ Now create a rule for this policy:
      **Device Authorization**
    - **User is**: Select **Any user assigned the app**
    - **Scopes requested**: Select **The following scopes** and choose the scope
-     you created for the authorization server (that is, `mcp:access`)
+     you created for the authorization server (that is, `mcp:access`) and
+     `offline_access`, so clients can obtain refresh tokens. Okta rejects a
+     request that includes a scope no rule allows, so this list must cover every
+     scope you put in `scopesSupported` later in this guide.
 4. In the **THEN AND** section:
    - **Use this inline hook**: None (disabled)
    - **Access token lifetime is**: Set to desired value (for example, 1 hour)
@@ -128,7 +144,7 @@ will need to do the following:
        "options": {
          "oAuthResourceMetadataEnabled": true,
          "audience": "https://my-gateway.zuplo.dev/mcp",
-         "issuer": "https://your-okta-domain.okta.com/oauth2/your-auth-server-id"
+         "issuerUrl": "https://your-okta-domain.okta.com/oauth2/your-auth-server-id"
        }
      }
    }
@@ -136,10 +152,10 @@ will need to do the following:
 
    - Replace `my-gateway.zuplo.dev/mcp` with the audience you defined in your
      authorization server.
-   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
+   - Replace `your-okta-domain` in the `issuerUrl` field with your actual Okta
      domain.
-   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
-     your Okta authorization server.
+   - Replace `your-auth-server-id` in the `issuerUrl` field with the actual ID
+     of your Okta authorization server.
 
 2. Add the OAuth policy to the MCP Server route. For example:
 
@@ -179,19 +195,24 @@ will need to do the following:
            "https://your-okta-domain.okta.com/oauth2/your-auth-server-id",
          ],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["mcp:access", "offline_access"],
        }),
      );
    }
    ```
 
-   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
-     domain.
-   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
-     your Okta authorization server.
+   - Replace `your-okta-domain` in the `authorizationServers` value with your
+     actual Okta domain.
+   - Replace `your-auth-server-id` in the `authorizationServers` value with the
+     actual ID of your Okta authorization server.
+   - Set `scopesSupported` to the scopes you created in
+     [Configure Scopes](#configure-scopes). Keep `offline_access` if clients
+     need refresh tokens. Add `openid`, `profile`, or `email` only if your
+     tokens need those claims.
 
    This plugin populates the `.well-known` routes for the MCP server auth
    metadata discovery. This enables MCP clients to automatically discover the
-   authorization issuer endpoint. See the
+   authorization issuer endpoint and the scopes to request. See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
    for more details on this runtime plugin.
 
@@ -206,3 +227,20 @@ further instructions on testing your MCP server with `curl`.
 
 If you need more help debugging, see
 [Testing OAuth on Zuplo](../handlers/mcp-server.mdx#oauth-testing).
+
+## Troubleshooting
+
+### `illegal_scope_combination` in the Okta system log
+
+**Cause:** The MCP client requested `device_sso` or `interclient_access`
+together with your custom scopes. Okta publishes those two scopes in every
+custom authorization server's metadata and can't hide them, and a client that
+finds no scopes in the 401 challenge or the protected resource metadata falls
+back to that list. Okta rejects the combination and grants no scopes.
+
+**Fix:** Set `scopesSupported` on the `OAuthProtectedResourcePlugin` to the
+scopes you created, as shown in
+[Configure OAuth on Zuplo](#configure-oauth-on-zuplo), and redeploy. The gateway
+then advertises exactly those scopes in both the 401 challenge and the metadata
+document, so the client never consults the authorization server's list.
+Reconnect the client so it repeats discovery.

package/docs/articles/oauth-authentication.mdx

@@ -52,3 +52,37 @@ If you would like to remove the authorization header after you use one of the
 authorization policies, simply add the
 [Remove Request Headers](/docs/policies/remove-headers-inbound) policy after the
 authorization policy and set it to remove the `Authorization` header.
+
+## OAuth 2.0 Protected Resource Metadata
+
+OAuth clients, including MCP clients, discover how to obtain a token for your
+API through
+[OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728).
+Zuplo implements it in two parts:
+
+- The
+  [`OAuthProtectedResourcePlugin`](../programmable-api/oauth-protected-resource-plugin.mdx)
+  serves the metadata document at `/.well-known/oauth-protected-resource` and
+  every path beneath it. The document lists your authorization servers, a
+  human-readable resource name, and, when you set `scopesSupported`, the scopes
+  clients should request.
+- The `oAuthResourceMetadataEnabled` option on the JWT authentication policies
+  makes the policy answer requests without a bearer token with a 401 response
+  that carries a `WWW-Authenticate` header. The header's `resource_metadata`
+  parameter points at the metadata document for that route, and its `scope`
+  parameter repeats `scopesSupported` when the plugin sets it.
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:access offline_access"
+```
+
+The
+[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+requires clients to discover the authorization server this way, and tells them
+to take the scopes they request from the challenge first and from the metadata
+document second. Set `scopesSupported` whenever a policy protects an MCP server,
+so clients request the scopes your resource expects instead of every scope the
+authorization server advertises. See
+[Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes)
+for the full order of precedence and an Okta-specific pitfall.

package/docs/handlers/mcp-server.mdx

@@ -412,14 +412,24 @@ enable OAuth authentication on your MCP Server:
        new OAuthProtectedResourcePlugin({
          authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["mcp:access", "offline_access"],
        }),
      );
    }
    ```
 
+   `scopesSupported` lists the scopes MCP clients should request. The plugin
+   emits it as `scopes_supported` in the metadata document, and the OAuth policy
+   adds it as the `scope` parameter of its 401 `WWW-Authenticate` challenge.
+   Without it, some clients request every scope the authorization server
+   advertises. Replace the example values with the scopes your authorization
+   server defines for this resource.
+
    See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin.mdx)
-   for more details.
+   for all options and
+   [Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes)
+   for how clients pick scopes.
 
 ### API Key Auth
 
@@ -697,6 +707,12 @@ in the MCP Inspector UI to move to the next step.
    canonical URL of your Authorization server, and registered an OAuth policy to
    the route of your MCP server.
 
+   If the authorization server later rejects the authorization request with a
+   scope error (Okta reports `illegal_scope_combination`), the client built its
+   scope list from the authorization server's metadata. Set `scopesSupported` on
+   the plugin so the client requests only those scopes. See
+   [Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes).
+
 2. **Client Registration**: The MCP Inspector will try to use
    [Dynamic Client Registration](https://modelcontextprotocol.io/specification/draft/basic/authorization#dynamic-client-registration)
    to register a new client with the Authorization server. Note that not all MCP

package/docs/mcp-gateway/connect-clients/claude-desktop.mdx

@@ -153,6 +153,8 @@ file-based configuration.
 ## Related
 
 - [Connect MCP clients overview](./overview.mdx)
+- To route Claude Desktop's model requests through Zuplo instead, see the
+  [Claude Desktop AI Gateway integration](../../ai-gateway/integrations/claude-desktop.mdx)
 - Anthropic's official guide:
   [Connect to remote MCP servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)
 - Anthropic's setup article:

package/docs/policies/ai-gateway-smart-router-inbound/doc.md

@@ -1,21 +1,14 @@
 # AI Gateway Smart Router
 
 Use this policy to classify the last user prompt on Chat Completions, Responses,
-and Anthropic Messages requests. It calls a dedicated AI Gateway application
-(`/{classifierAppID}/v1/chat/completions`) and stores the result on
-`AIGatewaySmartRouter` for later policies in the same request.
+and Anthropic Messages requests. Using the classification results, configure
+where to route the request based on its complexity.
 
-When `smartRoutingEnabled` is true, it overwrites completions routing from
-`modelsByComplexity`. Place it **after** Model Filtering so an invalid client
-model is still rejected before classification runs. The classified model then
-replaces that selection.
+When `smartRoutingEnabled` is true, it overwrites completions routing based on
+the configuration in `modelsByComplexity`.
 
-Classification is optional. Timeouts, classifier errors, unreadable bodies, and
-invalid options fail open: the original request is forwarded.
-
-> **Loop prevention.** The classifier hop is an `invokeRoute` sub-request. The
-> policy no-ops when `context.parentContext` is set, so the classifier app can
-> share the same route chain without classifying its own request.
+> **Classification failure handling.** If the message classification fails or
+> times out, the request is forwarded to the original model.
 
 ## Required options
 
@@ -27,10 +20,9 @@ invalid options fail open: the original request is forwarded.
 - `modelsByComplexity` — `providerName/model` for each of `low`, `medium`, and
   `high`. Used for routing when `smartRoutingEnabled` is true.
 
-Omit `intents` and `classifierPrompt` to use the built-in taxonomy (code,
+Omit `intents` and `classifierPrompt` to use the built-in dictionary (code,
 summarization, translation, qa, conversation, classification, creative_writing,
-agentic, document_qa, other) and the built-in system prompt. Include
-`{{intents}}` in a custom prompt to inject the configured intent list.
+agentic, document_qa, other) and the built-in classification prompt.
 
 ## Example
 
@@ -67,30 +59,207 @@ filtering already selected a model. Filtering skips when routing is already set,
 so putting this policy first would also skip allow-list checks on the client's
 original model.
 
-## Read the result from custom code
+## How classification drives routing
+
+Complexity is classified independently of intent, as `low`, `medium`, or `high`.
+Smart Router looks up `modelsByComplexity[complexity]` and applies it only when
+**all** of the following hold:
+
+- `smartRoutingEnabled` is `true`.
+- The classified intent is a known one (not capped as an unknown intent).
+- `modelsByComplexity` has a model configured for that complexity.
+- `profile.confidence >= minConfidenceForRouting` (default `0.5`).
+
+When routing isn't applied, read `smartRouting.reason` from the result (see
+[Using classification results in custom code](#using-classification-results-in-custom-code))
+to see why: `disabled`, `unknown-intent`, `no-model`, `low-confidence`,
+`internal-error`, or `applied`.
+
+### Other advanced options
+
+| Option                    | Default | Purpose                                                                                                                                                                                             |
+| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minConfidenceForRouting` | `0.5`   | Raise it to route only on confident classifications; lower it to route more aggressively. Unknown intents are always capped just below this value, so they never qualify regardless of the setting. |
+| `classifierTimeoutMs`     | `8000`  | How long to wait for the classifier before giving up and forwarding the request unclassified.                                                                                                       |
+| `maxPromptChars`          | `8000`  | Truncates the prompt sent to the classifier, to keep classifier cost and latency bounded on very long prompts.                                                                                      |
+
+## Advanced configuration
+
+Use these options to control what the classifier evaluates and how strongly its
+result influences routing.
+
+### Custom intents
+
+`intents` replaces the built-in dictionary entirely — it's not additive. Provide
+a non-empty list of `{ id, description }` pairs:
+
+```json
+{
+  "intents": [
+    {
+      "id": "billing",
+      "description": "Questions about invoices, payments, or subscription plans."
+    },
+    {
+      "id": "support",
+      "description": "Troubleshooting or how-to questions about the product."
+    }
+  ]
+}
+```
+
+The `id` values become the enum the classifier model must return — the
+classifier calls a strict JSON-schema chat completion, so it can only return one
+of your configured ids. The `description` values are only shown to the
+classifier if your prompt includes `{{intents}}` (see below).
+
+If the classifier returns an `id` outside this list, Smart Router keeps it as an
+"unknown intent" and caps its confidence just below `minConfidenceForRouting`,
+so it's never eligible for routing.
+
+### Custom classifier prompt
+
+`classifierPrompt` replaces the built-in classifier prompt. It accepts either a
+string or an array of lines:
+
+```json
+{
+  "classifierPrompt": [
+    "You are an intent classifier for a billing support bot.",
+    "Return JSON only that matches the schema.",
+    "Intent (pick the single most specific match):",
+    "{{intents}}"
+  ]
+}
+```
+
+Include the literal placeholder `{{intents}}` anywhere in the prompt to have it
+replaced with a `- id: description` line for each configured intent (or the
+built-in ones, if `intents` is also omitted). Pairing a custom `intents` list
+with the built-in `classifierPrompt` (by omitting `classifierPrompt` entirely)
+works out of the box, because the built-in prompt already contains
+`{{intents}}`.
+
+## Using classification results in custom code
+
+`AIGatewaySmartRouter.get(context)` returns the result Smart Router stored on
+the request, or `undefined` if it didn't run (non-AI request, unreadable body,
+or a fail-open error):
 
 ```typescript
 import { AIGatewaySmartRouter } from "@zuplo/runtime";
 
 const result = AIGatewaySmartRouter.get(context);
-if (result?.profile.intent === "code") {
-  // ...
+```
+
+`result` has this shape:
+
+```typescript
+interface AIGatewaySmartRouterResult {
+  profile: {
+    intent: string;
+    complexity: "low" | "medium" | "high";
+    confidence: number;
+    reasons: string[];
+  };
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  classifierModel: string;
+  routing: { model?: string };
+  durationMs: number;
+  promptSource: "user" | "prior-user";
+  promptLength: number;
+  promptTruncated: boolean;
+  unknownIntent: boolean;
+  smartRouting: {
+    enabled: boolean;
+    applied: boolean;
+    reason:
+      | "applied"
+      | "disabled"
+      | "low-confidence"
+      | "no-model"
+      | "internal-error"
+      | "unknown-intent";
+    minConfidence: number;
+  };
 }
 ```
 
-## How prompt text is chosen
+Read it from any policy placed after Smart Router in the chain. Common uses:
+
+- **Branch on intent or complexity** — apply a stricter rate limit, a different
+  DLP policy, or a longer timeout for `high` complexity or an `agentic` intent:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (result?.profile.complexity === "high") {
+    // e.g. apply a stricter rate limit or route to a review queue
+  }
+  ```
+
+- **Layer business logic on top of `modelsByComplexity`** — for example, cap the
+  model for free-tier callers regardless of classified complexity. Read the plan
+  from the caller's API key metadata, not from a raw request header (the caller
+  controls headers and could set or omit them to bypass the cap). The built-in
+  API Key Auth policy puts a key's metadata on `request.user.data` — set `plan`
+  there when you create the key, and it lands on every request that key makes:
+
+  ```typescript
+  import { AIGatewayModelRouting, AIGatewaySmartRouter } from "@zuplo/runtime";
+
+  const result = AIGatewaySmartRouter.get(context);
+  const isFreeTier = request.user?.data.plan === "free";
+  if (result?.profile.complexity === "high" && isFreeTier) {
+    await AIGatewayModelRouting.set(context, {
+      completions: "openai/gpt-4o-mini",
+    });
+  }
+  ```
+
+- **Observe why routing wasn't applied** — log when `smartRouting.reason` is
+  `low-confidence` or `unknown-intent` to tune `minConfidenceForRouting` or the
+  intent taxonomy:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (result && !result.smartRouting.applied) {
+    context.log.info(
+      { reason: result.smartRouting.reason },
+      "Smart routing skipped"
+    );
+  }
+  ```
+
+- **Surface classification for debugging** — add response headers in a
+  non-production environment to see what the classifier returned. This runs in
+  an outbound policy, so return a new `Response` carrying the headers — mutating
+  a cloned `Headers` object alone has no effect on what the caller receives:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (!result) {
+    return response;
+  }
+
+  const headers = new Headers(response.headers);
+  headers.set("x-classified-intent", result.profile.intent);
+  headers.set("x-classified-complexity", result.profile.complexity);
 
-The policy reads the typed body from the route (`getFormat` / `getRequestBody`),
-then takes the last real user text:
+  return new Response(response.body, {
+    headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+  ```
 
-- `/v1/chat/completions` — OpenAI chat `messages[]`, even when the downstream
-  provider is Anthropic or Google (Zuplo translates below the policy chain).
-- `/v1/responses` — OpenAI Responses `input`.
-- `/v1/messages` — native Anthropic `messages[]`.
+## What content is evaluated
 
-Tool follow-up turns (`tool` / `function` roles, `tool_result` blocks,
-`function_call_output` items) are skipped so a prior user message is classified
-instead. Embeddings and other non-AI paths are skipped.
+The policy reads the last user message in order to classify its intent and
+complexity. Embeddings, tool messages and other non-AI paths are skipped.
 
 ## Fail-open behavior
 

package/docs/policies/ai-gateway-smart-router-inbound/intro.md

@@ -1,4 +1,3 @@
 Classifies the last user prompt by calling a dedicated classifier AI Gateway
 app, stores the result on `AIGatewaySmartRouter` for later policies, and
-optionally routes completions by classified complexity. Classifier failures fail
-open so the original request still reaches the model.
+optionally routes completions by classified complexity.

package/docs/policies/ai-gateway-smart-router-inbound/schema.json

@@ -58,7 +58,7 @@
             "classifierAppID": {
               "type": "string",
               "title": "Classifier App ID",
-              "description": "The AI Gateway application id whose `/v1/chat/completions` route runs the classifier. The policy calls `/{classifierAppID}/v1/chat/completions` via `context.invokeRoute`.",
+              "description": "The AI Gateway application id used to run the classifier prompt and evaluate the user's request.",
               "examples": ["config_1234"]
             },
             "classifierAppApiKey": {
@@ -70,20 +70,20 @@
             "classifierModel": {
               "type": "string",
               "title": "Classifier Model",
-              "description": "The `providerName/model` reference the classifier chat/completions request should use.",
+              "description": "The model (`providerName/model`) the classifier uses to evaluate the user's request. E.g. `openai/gpt-4o-mini`.",
               "pattern": "^[^/\\s]+/.+$",
               "examples": ["openai/gpt-4o-mini"]
             },
             "smartRoutingEnabled": {
               "type": "boolean",
               "title": "Smart Routing Enabled",
-              "description": "When true, apply model routing from `modelsByComplexity` when confidence is high enough and the intent is known. Classification still runs when false.",
+              "description": "When true, apply model routing based on the models set in `modelsByComplexity` when confidence score meets the `minConfidenceForRouting` threshold. When set to false, classification still runs but model routing is not applied, useful for debugging or testing the classifier prompt.",
               "default": false
             },
             "modelsByComplexity": {
               "type": "object",
               "title": "Models By Complexity",
-              "description": "`providerName/model` routing by classified complexity. All of `low`, `medium`, and `high` are required. Used only when `smartRoutingEnabled` is true.",
+              "description": "Enables which model will be used based on the classifier results (`low`, `medium` and `high`). This configuration is applied only when `smartRoutingEnabled` is true and confidence score meets the `minConfidenceForRouting` threshold.",
               "additionalProperties": false,
               "required": ["low", "medium", "high"],
               "properties": {
@@ -113,7 +113,7 @@
             "intents": {
               "type": "array",
               "title": "Intents",
-              "description": "Labels the classifier may assign. Used to build the JSON schema enum and injected into `classifierPrompt` at `{{intents}}`. Omit to use the built-in taxonomy (code, summarization, translation, qa, conversation, classification, creative\\_writing, agentic, document\\_qa, other).",
+              "description": "Dictionary of intents used to classify the user message being evaluated. Omit to use the built-in dictionary (code, summarization, translation, qa, conversation, classification, creative\\_writing, agentic, document\\_qa, other).",
               "minItems": 1,
               "items": {
                 "type": "object",
@@ -123,14 +123,14 @@
                   "id": {
                     "type": "string",
                     "title": "Intent ID",
-                    "description": "Stable intent identifier written into the classifier JSON schema enum.",
+                    "description": "Label used to classify the intent of the user message being evaluated.",
                     "minLength": 1,
                     "examples": ["code"]
                   },
                   "description": {
                     "type": "string",
                     "title": "Intent Description",
-                    "description": "Short description shown to the classifier for this intent.",
+                    "description": "Short description of the intent label.",
                     "examples": [
                       "Write, edit, refactor, debug, or review source code."
                     ]
@@ -140,7 +140,7 @@
             },
             "classifierPrompt": {
               "title": "Classifier Prompt",
-              "description": "System prompt for the classifier. If it includes `{{intents}}`, that placeholder is replaced with the configured intent id/description list. A string or an array of lines (joined with newlines). Omit to use the built-in classifier prompt.",
+              "description": "Prompt used to analyze and classify the user message. Omit to use the built-in classifier prompt.",
               "oneOf": [
                 {
                   "type": "string",
@@ -167,7 +167,7 @@
             "classifierTimeoutMs": {
               "type": "integer",
               "title": "Classifier Timeout (ms)",
-              "description": "How long to wait for the classifier `invokeRoute` call before skipping classification and forwarding the original request.",
+              "description": "Timeout configured for the classifier task. When exceeded, the request is forwarded without classification to the original model.",
               "minimum": 1,
               "maximum": 120000,
               "default": 8000,
@@ -176,7 +176,7 @@
             "maxPromptChars": {
               "type": "integer",
               "title": "Max Prompt Characters",
-              "description": "Maximum characters of user prompt sent to the classifier. Longer prompts are truncated.",
+              "description": "Maximum characters of user message sent to the classifier. Longer messages get truncated.",
               "minimum": 1,
               "default": 8000,
               "x-advanced": true

package/docs/policies/auth0-jwt-auth-inbound/doc.md

@@ -121,5 +121,10 @@ When configured, this enables OAuth clients to find metadata information about
 how to interact with your OAuth 2.0 protected resources according to
 [`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
 
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
 See [this document](/docs/articles/oauth-authentication) for more information
 about OAuth authorization in Zuplo.

package/docs/policies/auth0-jwt-auth-inbound/schema.json

@@ -56,7 +56,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/clerk-jwt-auth-inbound/doc.md

@@ -81,5 +81,10 @@ When configured, this enables OAuth clients to find metadata information about
 how to interact with your OAuth 2.0 protected resources according to
 [`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
 
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
 See [this document](/docs/articles/oauth-authentication) for more information
 about OAuth authorization in Zuplo.

package/docs/policies/clerk-jwt-auth-inbound/schema.json

@@ -51,7 +51,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/cognito-jwt-auth-inbound/doc.md

@@ -0,0 +1,17 @@
+## OAuth 2.0 Protected Resource Metadata
+
+The Cognito JWT Auth policy supports OAuth protected resource metadata
+discovery. To enable this feature, set the `oAuthResourceMetadataEnabled` option
+to `true` and add the
+[`OAuthProtectedResourcePlugin` to `modules/zuplo.runtime.ts`](/docs/programmable-api/oauth-protected-resource-plugin).
+When configured, this enables OAuth clients to find metadata information about
+how to interact with your OAuth 2.0 protected resources according to
+[`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
+See [this document](/docs/articles/oauth-authentication) for more information
+about OAuth authorization in Zuplo.

package/docs/policies/cognito-jwt-auth-inbound/schema.json

@@ -56,7 +56,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/firebase-jwt-inbound/doc.md

@@ -0,0 +1,17 @@
+## OAuth 2.0 Protected Resource Metadata
+
+The Firebase JWT Auth policy supports OAuth protected resource metadata
+discovery. To enable this feature, set the `oAuthResourceMetadataEnabled` option
+to `true` and add the
+[`OAuthProtectedResourcePlugin` to `modules/zuplo.runtime.ts`](/docs/programmable-api/oauth-protected-resource-plugin).
+When configured, this enables OAuth clients to find metadata information about
+how to interact with your OAuth 2.0 protected resources according to
+[`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
+See [this document](/docs/articles/oauth-authentication) for more information
+about OAuth authorization in Zuplo.

package/docs/policies/firebase-jwt-inbound/schema.json

@@ -51,7 +51,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/okta-jwt-auth-inbound/doc.md

@@ -0,0 +1,23 @@
+## OAuth 2.0 Protected Resource Metadata
+
+The Okta JWT Auth policy supports OAuth protected resource metadata discovery.
+To enable this feature, set the `oAuthResourceMetadataEnabled` option to `true`
+and add the
+[`OAuthProtectedResourcePlugin` to `modules/zuplo.runtime.ts`](/docs/programmable-api/oauth-protected-resource-plugin).
+When configured, this enables OAuth clients to find metadata information about
+how to interact with your OAuth 2.0 protected resources according to
+[`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
+Okta custom authorization servers always advertise the `device_sso` and
+`interclient_access` scopes in their own metadata and reject authorization
+requests that combine them with your scopes (`illegal_scope_combination`). Set
+`scopesSupported` on the plugin when this policy protects an MCP server, so
+clients never fall back to that list.
+
+See [this document](/docs/articles/oauth-authentication) for more information
+about OAuth authorization in Zuplo.

package/docs/policies/okta-jwt-auth-inbound/schema.json

@@ -56,7 +56,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/open-id-jwt-auth-inbound/doc.md

@@ -56,3 +56,21 @@ export async function myHandler(request: ZuploRequest, context: ZuploContext) {
 For a complete example of using the user object in a
 [RequestHandler](../handlers/custom-handler.md), see
 [Setting up JWT auth with Auth0](../policies/auth0-jwt-auth-inbound.md).
+
+## OAuth 2.0 Protected Resource Metadata
+
+The OpenID JWT Auth policy supports OAuth protected resource metadata discovery.
+To enable this feature, set the `oAuthResourceMetadataEnabled` option to `true`
+and add the
+[`OAuthProtectedResourcePlugin` to `modules/zuplo.runtime.ts`](/docs/programmable-api/oauth-protected-resource-plugin).
+When configured, this enables OAuth clients to find metadata information about
+how to interact with your OAuth 2.0 protected resources according to
+[`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
+See [this document](/docs/articles/oauth-authentication) for more information
+about OAuth authorization in Zuplo.

package/docs/policies/open-id-jwt-auth-inbound/schema.json

@@ -89,7 +89,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           },
           "examples": [

package/docs/policies/propel-auth-jwt-inbound/doc.md

@@ -84,5 +84,10 @@ When configured, this enables OAuth clients to find metadata information about
 how to interact with your OAuth 2.0 protected resources according to
 [`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
 
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.
+
 See [this document](/docs/articles/oauth-authentication) for more information
 about OAuth authorization in Zuplo.

package/docs/policies/propel-auth-jwt-inbound/schema.json

@@ -56,7 +56,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/policies/supabase-jwt-auth-inbound/doc.md

@@ -27,3 +27,8 @@ to `true` and add the
 When configured, this enables OAuth clients to find metadata information about
 how to interact with your OAuth 2.0 protected resources according to
 [`RFC 9728`](https://datatracker.ietf.org/doc/html/rfc9728).
+
+When the plugin is configured with `scopesSupported`, the 401 response also
+lists those scopes in the `scope` parameter of its `WWW-Authenticate` header, so
+MCP clients request exactly the scopes your resource expects instead of every
+scope the authorization server advertises.

package/docs/policies/supabase-jwt-auth-inbound/schema.json

@@ -66,7 +66,7 @@
               "type": "boolean",
               "default": false,
               "x-advanced": true,
-              "description": "Flag that determines whether OAuth protected resource metadata is enabled."
+              "description": "Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When `true`, requests without a bearer token receive a 401 whose `WWW-Authenticate` header points `resource_metadata` at the `/.well-known/oauth-protected-resource` document for the request path and, when the `OAuthProtectedResourcePlugin` declares `scopesSupported`, lists those scopes in `scope`. Requires the `OAuthProtectedResourcePlugin` in `zuplo.runtime.ts` or a user-defined route at that path."
             }
           }
         }

package/docs/programmable-api/oauth-protected-resource-plugin.mdx

@@ -13,13 +13,16 @@ more details.
 
 ## Usage
 
-This runtime plugin will register the `.well-known/oauth-protected-resource`
-route on your behalf. If you configure an
+This runtime plugin registers the `.well-known/oauth-protected-resource` route
+on your behalf, along with every path beneath it, such as
+`/.well-known/oauth-protected-resource/mcp`. If you configure an
 [OAuth Policy](../articles/oauth-authentication.mdx) on a route with the
-`oAuthResourceMetadataEnabled` option set to `true`, then the OAuth policy will
-automatically add the necessary `WWW-Authenticate` header to 401 responses, with
-the `resource_metadata` parameter set to the URL of the
-`.well-known/oauth-protected-resource` endpoint.
+`oAuthResourceMetadataEnabled` option set to `true`, the policy answers requests
+that carry no bearer token with a 401 response and a `WWW-Authenticate` header.
+The header's `resource_metadata` parameter is the URL of the
+`.well-known/oauth-protected-resource` endpoint for that route. When you set
+`scopesSupported`, the header also carries a `scope` parameter that lists those
+scopes.
 
 ```ts
 import {
@@ -32,6 +35,7 @@ export function runtimeInit(runtime: RuntimeExtensions) {
     new OAuthProtectedResourcePlugin({
       authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
       resourceName: "My MCP OAuth Resource",
+      scopesSupported: ["mcp:access", "offline_access"],
     }),
   );
 }
@@ -44,3 +48,71 @@ a human readable name for the resource.
 Note that the `.well-known/oauth-protected-resource` endpoint explicitly has a
 CORS policy of `anything-goes` since this is a public endpoint that should be
 accessible to anyone to check the server's OAuth configuration.
+
+## Options
+
+Construct the plugin inside `runtimeInit`. The plugin validates its options when
+you construct it, so an invalid value fails at startup with a
+`ConfigurationError` instead of failing a client's first login.
+
+| Option                 | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authorizationServers` | `string[]` | Canonical issuer URLs of the authorization servers that issue tokens for this resource. Each should comply with [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). Emitted as `authorization_servers`.                                                                                                                                                                                                                                                                                                                                                                    |
+| `resourceName`         | `string`   | Human-readable name of the resource, intended for display to end users. RFC 9728 recommends setting it. Emitted as `resource_name`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `scopesSupported`      | `string[]` | Scopes that clients should request when they obtain an access token for this resource. Emitted as `scopes_supported`, and as the `scope` parameter of the 401 `WWW-Authenticate` header by OAuth policies that have `oAuthResourceMetadataEnabled` set. Each entry must be one OAuth scope token ([RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)): printable ASCII with no spaces, double quotes, or backslashes. Use one entry per scope, never a space-delimited string. An empty array is rejected; omit the option to advertise no scopes. |
+
+## Advertising supported scopes
+
+An MCP client has to decide which scopes to request from the authorization
+server. The
+[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy)
+tells clients to consider these sources in order:
+
+1. **The `scope` parameter of the `WWW-Authenticate` challenge** on the 401
+   response. Clients treat these scopes as authoritative.
+2. **The `scopes_supported` array in the protected resource metadata** document,
+   when the challenge has no `scope` parameter.
+3. **The `scopes_supported` array in the authorization server's own metadata.**
+   The specification doesn't list this source, but some clients fall back to it
+   when the first two are empty. It usually contains every scope the server
+   knows about.
+4. **No `scope` parameter at all.**
+
+Setting `scopesSupported` fills the first two sources with the same list, so no
+client reaches the third. For example, a plugin configured with an Okta
+authorization server, `resourceName: "Acme MCP"`, and
+`scopesSupported: ["mcp:access", "offline_access"]` serves this document at
+`/.well-known/oauth-protected-resource/mcp`:
+
+```json
+{
+  "resource": "https://api.example.com/mcp",
+  "authorization_servers": ["https://acme.okta.com/oauth2/aus1a2b3c"],
+  "resource_name": "Acme MCP",
+  "scopes_supported": ["mcp:access", "offline_access"]
+}
+```
+
+A request to `/mcp` without a bearer token receives:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:access offline_access"
+```
+
+If you don't set `scopesSupported`, the document has no `scopes_supported` key
+and the header has no `scope` parameter. Requests that carry an invalid or
+expired token receive a 401 without the `WWW-Authenticate` header in either
+case.
+
+:::caution{title="Okta rejects its own default scopes"}
+
+Okta custom authorization servers always publish `device_sso` and
+`interclient_access` in their `scopes_supported` metadata. The **Include in
+public metadata** toggle for those two scopes is disabled, so you can't remove
+them. A client that falls back to that list requests them together with your
+scopes, and Okta rejects the authorization request with
+`illegal_scope_combination` and grants no scopes. Set `scopesSupported` whenever
+Okta is your authorization server.
+
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.8",
+  "version": "7.6.10",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.8",
-    "@zuplo/core": "7.6.8",
-    "@zuplo/runtime": "7.6.8",
-    "@zuplo/test": "7.6.8"
+    "@zuplo/cli": "7.6.10",
+    "@zuplo/core": "7.6.10",
+    "@zuplo/runtime": "7.6.10",
+    "@zuplo/test": "7.6.10"
   }
 }