zuplo 7.6.9 → 7.7.0

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,37 @@ 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
-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
-```
+:::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": {
@@ -53,7 +64,8 @@ ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-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_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
   }
 }
 ```
@@ -68,20 +80,7 @@ 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.
 
-### Model names include your provider's name
-
-The gateway routes every request by a model reference of the form
-`providerName/model`, where `providerName` is the name of the provider **you
-configured** in your gateway — not a fixed vendor id. A single gateway can
-contain several providers that serve Anthropic models — Anthropic itself, Google
-Vertex AI, AWS Bedrock, or multiple keyed instances of the same vendor — so the
-gateway never guesses a provider for a bare model name like `claude-sonnet-5`.
-
-The examples on this page assume the provider is named `anthropic`. Use the name
-of your own provider: a provider named `my-anthropic` routes
-`my-anthropic/claude-sonnet-5`, and a Bedrock provider named `bedrock` routes
-`bedrock/anthropic.claude-sonnet-5` (the model part is always the id the
-provider itself understands).
+### Configure every Claude Code model variable
 
 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
@@ -96,8 +95,10 @@ the model variables above must be set to a prefixed reference:
   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` — what the `opus`/`sonnet`/`haiku` aliases
-  resolve to, so `claude --model opus` and `/model sonnet` keep working.
+  `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"'}
 

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/ai-gateway/providers.mdx

@@ -37,7 +37,7 @@ The following capabilities are supported across providers:
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
-| Vertex AI                  | ✅               | ✅         | ❌        | ❌       |
+| Vertex AI                  | ✅               | ✅         | ❌        | ✅       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
 | OpenAI-compatible (Custom) | ✅               | ✅         | ❌        | ❌       |
 
@@ -97,11 +97,15 @@ Two things make its setup different from every other provider:
   asks for both.
 
 Every Vertex model ID is publisher-qualified, so a model reference has two
-slashes: a provider named `vertexai` serves `vertexai/google/gemini-3.7-flash`
-and `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`. Model availability
-varies by location—most Model Garden models are served only from the `global`
-location. Vertex also hosts Anthropic's Claude models, but on a different API
-surface that the gateway doesn't route to.
+slashes: a provider named `vertexai` serves `vertexai/google/gemini-3.7-flash`,
+`vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`, and
+`vertexai/anthropic/claude-haiku-4-5@20251001`. Model availability varies by
+location—most Model Garden models are served only from the `global` location,
+and Google's regional endpoints serve Claude Sonnet 4.6 and earlier only, so
+`global` is the location that serves every Claude model. Vertex's Claude models
+serve the native Anthropic Messages API (`/v1/messages`) and nothing else: they
+aren't available on `/v1/chat/completions`, and each one must be enabled in
+Model Garden for your Google Cloud project before it answers.
 
 For prerequisites, Google Cloud setup, provider steps, code examples, and
 troubleshooting, see [Using Vertex AI](./vertex-ai.mdx).

package/docs/ai-gateway/universal-api.mdx

@@ -63,9 +63,9 @@ list—so clients that can't set a model still work.
 
 ## Supported endpoints
 
-| Endpoint               | Notes                                                                                                           |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `/v1/chat/completions` | Chat completions for every provider                                                                             |
-| `/v1/embeddings`       | Embeddings for every provider except Anthropic                                                                  |
-| `/v1/responses`        | OpenAI Responses API: OpenAI, and [Bedrock Mantle](./bedrock-mantle.mdx) OpenAI-compatible models that serve it |
-| `/v1/messages`         | Anthropic Messages API: Anthropic, and [Bedrock Mantle](./bedrock-mantle.mdx) Claude models                     |
+| Endpoint               | Notes                                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `/v1/chat/completions` | Chat completions for every provider                                                                                                 |
+| `/v1/embeddings`       | Embeddings for every provider except Anthropic                                                                                      |
+| `/v1/responses`        | OpenAI Responses API: OpenAI, and [Bedrock Mantle](./bedrock-mantle.mdx) OpenAI-compatible models that serve it                     |
+| `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Bedrock Mantle](./bedrock-mantle.mdx) and [Vertex AI](./vertex-ai.mdx) |

package/docs/ai-gateway/vertex-ai.mdx

@@ -9,16 +9,19 @@ description:
 ---
 
 **Vertex AI** is Google Cloud's managed model platform. Adding it as a provider
-serves both the Gemini family and Vertex's Model Garden partner models—DeepSeek,
-Qwen, GLM, Kimi, MiniMax, Gemma, and GPT-OSS—to your [apps](./apps.mdx) through
-the [Universal API](./universal-api.mdx), running on your Google Cloud project
-and your Google Cloud billing.
+serves the Gemini family, Vertex's Model Garden partner models—DeepSeek, Qwen,
+GLM, Kimi, MiniMax, Gemma, and GPT-OSS—and Anthropic's Claude models to your
+[apps](./apps.mdx) through the [Universal API](./universal-api.mdx), running on
+your Google Cloud project and your Google Cloud billing.
 
 Chat completions go to Vertex's **OpenAI-compatible endpoint**, so the gateway
 forwards OpenAI-shaped requests without translating them. Embeddings work too,
 though Vertex has no OpenAI-compatible embeddings endpoint—the gateway
 translates those onto Vertex's own embedding APIs, which is invisible from your
-app. What sets this provider apart is how you connect it: the endpoint is
+app. Claude models are different again: Vertex serves them on the native
+**Anthropic Messages API**, so they're available on `/v1/messages` only—see
+[Call Claude models on the Messages API](#call-claude-models-on-the-messages-api).
+What sets this provider apart is how you connect it: the endpoint is
 per-location, the Google Cloud project is a separate setting, and the credential
 is a **service account key file**—not an API key.
 
@@ -53,9 +56,11 @@ provider named `vertexai` serves all of these:
 - `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`
 - `vertexai/deepseek-ai/deepseek-v3.2-maas`
 - `vertexai/zai-org/glm-5-maas`
+- `vertexai/anthropic/claude-haiku-4-5@20251001`
 
-Copy model IDs from the model picker rather than typing them—the `-maas` suffix
-and the publisher prefix are both part of the ID.
+Copy model IDs from the model picker rather than typing them—the `-maas` suffix,
+the `@` version on the dated Claude models, and the publisher prefix are all
+part of the ID.
 
 ## How the gateway calls Vertex AI
 
@@ -79,6 +84,9 @@ bearer credential.
     <DiagramNode id="embed" variant="green">
       Vertex embedding APIs
     </DiagramNode>
+    <DiagramNode id="messages" variant="blue">
+      Anthropic Messages API (Claude)
+    </DiagramNode>
   </DiagramGroup>
   <DiagramEdge from="app" to="gateway" label="Universal API" />
   <DiagramEdge
@@ -89,6 +97,7 @@ bearer credential.
   />
   <DiagramEdge from="gateway" to="compat" label="chat completions" />
   <DiagramEdge from="gateway" to="embed" label="embeddings" />
+  <DiagramEdge from="gateway" to="messages" label="/v1/messages" />
 </Diagram>
 
 The request URL the gateway builds combines both settings you enter:
@@ -98,6 +107,14 @@ https://us-central1-aiplatform.googleapis.com
   /v1/projects/my-project-123/locations/us-central1/endpoints/openapi/chat/completions
 ```
 
+For a Claude model the gateway calls Vertex's Anthropic publisher surface
+instead, with the model in the URL:
+
+```
+https://aiplatform.googleapis.com
+  /v1/projects/my-project-123/locations/global/publishers/anthropic/models/claude-haiku-4-5@20251001:rawPredict
+```
+
 The **location** lives in the hostname, which is why the provider dialog asks
 for a location instead of an endpoint URL. The **project** doesn't appear in the
 hostname at all—it appears only in the path—so it can't be derived from the
@@ -107,25 +124,30 @@ send your traffic and your spend to someone else's Google Cloud project.
 
 ## Supported endpoints
 
-| Endpoint               | Vertex AI models |
-| ---------------------- | ---------------- |
-| `/v1/chat/completions` | ✅ Forwarded     |
-| `/v1/embeddings`       | ✅ Translated    |
-| `/v1/responses`        | ❌               |
-| `/v1/messages`         | ❌               |
+| Endpoint               | Gemini and Model Garden models | Claude models |
+| ---------------------- | ------------------------------ | ------------- |
+| `/v1/chat/completions` | ✅ Forwarded                   | ❌            |
+| `/v1/embeddings`       | ✅ Translated                  | ❌            |
+| `/v1/responses`        | ❌                             | ❌            |
+| `/v1/messages`         | ❌                             | ✅ Native     |
 
-Streaming (`stream: true`) works on chat completions.
+Streaming (`stream: true`) works on chat completions and on Messages.
 
-The gateway rejects `/v1/responses` and `/v1/messages` requests for Vertex
-models with a `400` error before any upstream call, because Vertex serves
-neither the OpenAI Responses API nor the Anthropic Messages API.
+The gateway's model catalog records which API serves each model, and the gateway
+routes every request accordingly. It rejects a request for a model on an
+endpoint that doesn't serve it with a `400` before any upstream call:
+`/v1/responses` for every Vertex model, `/v1/messages` for Gemini and Model
+Garden models, and `/v1/chat/completions` or `/v1/embeddings` for Claude
+models—that last error names `/v1/messages` as the endpoint to use.
 
-:::note{title="Anthropic models on Vertex aren't supported"}
+:::note{title="Claude models are Messages-only on Vertex"}
 
-Vertex also hosts Anthropic's Claude models, but on a different API surface than
-the one this provider uses. The gateway can't route to them. To use Claude
-models, add the [Anthropic](./providers.mdx) provider or
-[Bedrock Mantle](./bedrock-mantle.mdx).
+Vertex serves Anthropic's Claude models on the native Anthropic Messages API,
+not on its OpenAI-compatible endpoint, so the gateway doesn't translate chat
+completions for them the way it does for Claude models on
+[Bedrock Mantle](./bedrock-mantle.mdx). Use an Anthropic client and
+`/v1/messages`—see
+[Call Claude models on the Messages API](#call-claude-models-on-the-messages-api).
 
 :::
 
@@ -145,7 +167,14 @@ is not available in region 'us-central1'
 ```
 
 Set the provider's **Location** to `global` if you plan to use Model Garden
-models, or add a second Vertex provider for a specific region and route to
+models or Claude models. Google's regional endpoints serve Claude Sonnet 4.6 and
+earlier, only in the regions listed on each model's Model Garden card, and only
+where the model is enabled for your project. Claude models newer than Sonnet 4.6
+are served by the `global` endpoint (and by Google's `us` and `eu` multi-region
+endpoints, which the gateway doesn't accept as a location yet). For a Claude
+model in a location that doesn't serve it, or where it isn't enabled for your
+project, Vertex answers a `400` saying the model "is not servable in region".
+Alternatively, add a second Vertex provider for a specific region and route to
 whichever one serves the model you want.
 
 ## Before you begin
@@ -179,6 +208,16 @@ what the provider dialog asks for.
 1. Enable the **Vertex AI API** on the project, under **APIs & Services →
    Library**. Confirm billing is enabled for the project as well.
 
+1. To use Claude models, enable each one in **Vertex AI → Model Garden**: search
+   for "Claude", open the model card, and click **Enable** for the locations
+   your providers use—a model enabled for `global` only answers a `400` saying
+   it "is not servable in region" from a regional provider. Until a model is
+   enabled, Vertex answers every request for it with a `404` saying the model
+   "was not found or your project does not have access to it"—the same message
+   it gives a misspelled model ID. Some Claude models also require the project
+   to turn on data sharing for the `anthropic` publisher; the `403` Vertex
+   returns in that case names the setting.
+
 1. Create a service account under **IAM & Admin → Service Accounts**.
 
 1. Grant that service account the **Vertex AI User** (`roles/aiplatform.user`)
@@ -335,6 +374,41 @@ than a partial charge:
   API also accepts—is rejected, because Vertex has no way to represent it. Send
   the original text.
 
+### Call Claude models on the Messages API
+
+Claude models serve the native
+[Anthropic Messages API](./universal-api.mdx#supported-endpoints) at
+`/v1/messages`, including streaming and `/v1/messages/count_tokens`. With the
+Anthropic SDK, set `baseURL` to the app's URL _without_ `/v1`—the SDK appends
+`/v1/messages` itself—and pass the app's API key as `authToken`, not `apiKey`:
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic({
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+  authToken: process.env.ZUPLO_APP_API_KEY, // apiKey would send x-api-key, which the gateway ignores
+});
+
+const message = await client.messages.create({
+  model: "vertexai/anthropic/claude-haiku-4-5@20251001",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Say hi" }],
+});
+```
+
+The gateway takes care of what Vertex does differently from Anthropic's own API:
+it addresses the model in the request URL and drops it from the body, adds the
+`anthropic_version` field Vertex requires, and authenticates with the access
+token it minted from your service account. Your request body is otherwise
+forwarded as-is, so system prompts, tool use, and streaming work as they do
+against Anthropic directly. Client headers such as `anthropic-beta` pass
+through, narrowed to the values Vertex accepts.
+
+Claude models aren't available on `/v1/chat/completions`—a request there returns
+a `400` that points at `/v1/messages`.
+
 ## Troubleshooting
 
 **The dialog rejects your credential.** Vertex uses a service account, not an
@@ -359,9 +433,11 @@ permissions, so it's easy to mistake for a credential problem.
 project than the one configured on the provider. Grant the role on the same
 project you entered as the **Google Cloud Project ID**.
 
-**A request fails with `400` saying the model isn't available in the region.**
-The model isn't served from your provider's location. Most Model Garden models
-are global-only—see
+**A request fails with `400` saying the model isn't available in the region, or
+that a Claude model "is not servable in region".** The model isn't served from
+your provider's location, or isn't enabled for that location in your project.
+Most Model Garden models are global-only, and Claude models are served from
+`global` and the regions on each model's card—see
 [Model availability](#model-availability-depends-on-the-location). Set the
 provider's **Location** to `global`, or use a provider that points at a location
 serving that model.
@@ -370,10 +446,28 @@ serving that model.
 at most 250 inputs per request and text input only. See
 [Embeddings](#embeddings).
 
-**A `/v1/responses` or `/v1/messages` request fails with `400`.** Vertex's
-OpenAI-compatible endpoint serves neither API. Use `/v1/chat/completions`, or
-another provider for those endpoints—see
-[Supported endpoints](#supported-endpoints).
+**A `/v1/responses` request fails with `400`.** Vertex serves the OpenAI
+Responses API for none of its models. Use `/v1/chat/completions`, or another
+provider—see [Supported endpoints](#supported-endpoints).
+
+**A `/v1/messages` request for a Gemini or Model Garden model fails with
+`400`.** Only Claude models serve the Messages API on Vertex. Use
+`/v1/chat/completions` for the others.
+
+**A Claude model fails with `400` on `/v1/chat/completions`.** Claude models are
+Messages-only on Vertex. Send the request to `/v1/messages` with an Anthropic
+client—see
+[Call Claude models on the Messages API](#call-claude-models-on-the-messages-api).
+
+**A Claude request fails with `404` saying the model "was not found or your
+project does not have access to it".** Either the model isn't enabled in Model
+Garden for your project (see [Set up Google Cloud](#set-up-google-cloud)) or the
+model ID is wrong. Enabling a model applies to every location; a location that
+doesn't serve the model is the separate `400` described above.
+
+**A Claude request fails with `403` about data sharing.** Some Claude models
+require the project to turn on data sharing for the `anthropic` publisher. The
+error names the `setPublisherModelConfig` setting to change.
 
 ## Next steps
 

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-model-filtering-v2-inbound/doc.md

@@ -160,7 +160,8 @@ served on the OpenAI API, and `/v1/messages` one served on the Anthropic API. A
 selection qualifies when its Provider Assignment is backed by that provider
 type, or when the provider catalog declares the selected model's dialect as that
 format — Bedrock Mantle serves its `openai`-dialect models on `/v1/responses`
-and its `anthropic`-dialect models on `/v1/messages`. Provider Names may be
+and its `anthropic`-dialect models on `/v1/messages`, and Vertex AI serves its
+`anthropic`-dialect Claude models on `/v1/messages`. Provider Names may be
 custom labels; validation never infers anything from the label or the model
 name, and a model the catalog does not declare is rejected.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.9",
+  "version": "7.7.0",
   "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.9",
-    "@zuplo/core": "7.6.9",
-    "@zuplo/runtime": "7.6.9",
-    "@zuplo/test": "7.6.9"
+    "@zuplo/cli": "7.7.0",
+    "@zuplo/core": "7.7.0",
+    "@zuplo/runtime": "7.7.0",
+    "@zuplo/test": "7.7.0"
   }
 }