zuplo 7.8.8 → 7.8.9

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

@@ -2,92 +2,70 @@
 title: Claude Code
 sidebar_label: Claude Code
 description:
-  Point Claude Code at an AI Gateway app so every Claude Code request is
-  authenticated, metered, and routed by the gateway.
+  Route Claude Code requests through a Zuplo AI Gateway app, with a provider key
+  or your Claude subscription.
 ---
 
-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.
+Route [Claude Code](https://www.claude.com/product/claude-code) through the
+Zuplo AI Gateway. The gateway authenticates, meters, and routes every session.
 
-The gateway can authenticate to Anthropic in two ways. Pick one before you
-configure Claude Code:
+The gateway authenticates to Anthropic in one of two ways:
 
-| Approach                                                  | The gateway sends Anthropic                                           | Claude Code sends the gateway                                             |
-| --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [Configured provider key](#use-a-configured-provider-key) | The Anthropic API key saved on your provider                          | The app's API key as `ANTHROPIC_AUTH_TOKEN`                               |
-| [Your Claude subscription](#use-your-claude-subscription) | The credential from your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login as-is |
+| Approach                                             | The gateway sends Anthropic                       | Claude Code sends the gateway                                       |
+| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
+| [Provider key](#use-a-provider-key)                  | The Anthropic API key saved on your provider      | The app's API key as `ANTHROPIC_AUTH_TOKEN`                         |
+| [Claude subscription](#use-your-claude-subscription) | Your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login |
 
-Both approaches share the same provider, team, and app setup, and the same model
-configuration.
-
-## Claude Code Setup
+## Prerequisites
 
 <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. If you plan to use your Claude subscription, configure the team's
-   [API Key Authentication policy](#configure-the-api-key-authentication-policy)
-   for passthrough before you create the app
+1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
 
-4. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
-   it to the team you created
+2. [Create a team](../managing-teams.mdx). For the subscription approach,
+   [configure its API Key Authentication policy](#configure-the-api-key-authentication-policy)
+   now.
 
-5. Copy the **API URL** and **API Key** shown at the top of the app page
+3. [Create an app](../managing-apps.mdx) for Claude Code and assign it to the
+   team.
 
-6. Add the gateway URL, the app's API key, and model mappings to
-   `.claude/settings.json`, following the section below for the approach you
-   chose
+4. Copy the **API URL** and **API Key** from the app page.
 
 </Stepper>
 
-### Before copying: replace the provider name
+## Configure Claude Code
 
-:::warning
+:::warning{title="Replace the provider name"}
 
-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 examples assume your provider is named `anthropic`. Replace that prefix with
+the name of **your** provider before copying anything. A provider named
+`my-anthropic` routes `my-anthropic/claude-sonnet-5`; a Bedrock provider named
+`bedrock` routes `bedrock/anthropic.claude-sonnet-5`. The model part must be an
+ID that provider serves. Check [your provider's page](../managing-providers.mdx)
+in the Portal.
 
 :::
 
-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.
-
-### Where Claude Code reads its settings
-
-You can configure Claude Code either globally or per project by editing the
-settings file:
+Claude Code reads `~/.claude/settings.json`, or `.claude/settings.json` in a
+project. Add the block for your approach, then restart Claude Code.
 
-- **Global:** `~/.claude/settings.json`
-- **Project-specific:** `.claude/settings.json` in your project directory
-
-Each approach below shows the `env` and `modelOverrides` blocks to add to that
-file. Restart Claude Code after saving it, and all your Claude Code LLM requests
-route through the AI Gateway.
-
-:::note
-
-Claude Code appends `/v1/messages` to the base URL itself, so
-`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
-
-:::
+### Rules
 
-## Use a configured provider key
+- `ANTHROPIC_BASE_URL` is the app's API URL _without_ `/v1`. Claude Code appends
+  `/v1/messages`.
+- Set every `ANTHROPIC_*_MODEL` variable and every `modelOverrides` entry.
+  Claude Code's built-in model names have no prefix. The variables map the
+  `opus`, `sonnet`, `haiku`, and `fable` aliases;
+  [`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
+  maps exact IDs; the `/model` picker can select either.
+- The app's
+  [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
+  policy controls which models the app can use.
 
-With this approach the gateway calls Anthropic with the API key you saved on the
-[provider](../managing-providers.mdx). Claude Code presents only the app's API
-key, and Anthropic bills the account that owns the provider key.
+## Use a provider key
 
-Add the following configuration to the settings file:
+The gateway calls Anthropic with the key saved on your provider. Anthropic bills
+that key's account. Your Claude subscription is not used.
 
 ```json
 {
@@ -111,58 +89,37 @@ Add the following configuration to the settings file:
 }
 ```
 
-`ANTHROPIC_AUTH_TOKEN` replaces whatever login Claude Code would otherwise use,
-so this approach doesn't consume your Claude subscription.
+`ANTHROPIC_AUTH_TOKEN` replaces your `claude.ai` login.
 
 ## Use your Claude subscription
 
-With this approach Claude Code stays signed in to `claude.ai` — for example with
-a Claude Max plan — and the gateway forwards that login credential to Anthropic
-as the request's provider credential. The app's API key travels in a separate
-`zp-gateway-api-key` header, so the gateway still authenticates the app, applies
-its policy chain, and meters its usage.
-
-Two pieces of configuration make this work: the app's **API Key Authentication**
-policy accepts the app key from the `zp-gateway-api-key` header and passes the
-`Authorization` header through, and Claude Code sends both headers.
+Claude Code stays signed in to `claude.ai`. The gateway forwards that login to
+Anthropic and reads the app's API key from a separate `zp-gateway-api-key`
+header, so it still authenticates the app, runs its policies, and meters usage.
 
 ### Configure the API Key Authentication policy
 
-The [API Key Authentication](../../policies/ai-gateway-auth-v2-inbound.mdx)
-policy needs three options for passthrough:
-
-| Option                  | Value                | Effect                                                   |
-| ----------------------- | -------------------- | -------------------------------------------------------- |
-| `credentialPassthrough` | On                   | Forward the caller's `Authorization` header to Anthropic |
-| `authHeader`            | `zp-gateway-api-key` | Read the app's API key from this header instead          |
-| `authScheme`            | Empty value          | The header holds the bare key, with no `Bearer` prefix   |
-
-You can set these options on the team's
-[policy template](../policy-templates.mdx), so every app created in the team
-starts with passthrough enabled, or on a single app's **Policies** tab. The
-steps below use the team template; the app's policy editor works the same way.
+On the team's [policy template](../policy-templates.mdx), or on one app's
+**Policies** tab, edit **API Key Authentication**:
 
 <Stepper>
 
-1. Open the team in the Zuplo Portal and select its **Policy Template** tab.
-
-2. Click the edit (pencil) icon on the **API Key Authentication** entry.
-
-3. Turn on **credentialPassthrough**.
+1. Turn on **credentialPassthrough**.
 
-4. Set **authHeader** to `zp-gateway-api-key`.
+2. Set **authHeader** to `zp-gateway-api-key`.
 
-5. Leave **authScheme** blank and click **Use an empty value for authScheme**.
-   The field then reports "Empty value set. The default (Bearer) is not
-   applied." Clearing the field alone isn't enough: a blank field omits the
-   option, so the `Bearer` default still applies and every request fails with
-   `401 Invalid Authorization Scheme`.
+3. Leave **authScheme** blank and click **Use an empty value for authScheme**.
+   The field reports "Empty value set. The default (Bearer) is not applied."
 
-6. Click **Apply**, then **Save changes**.
+4. Click **Apply**, then **Save changes**.
 
 </Stepper>
 
-The **JSON** editor mode shows the equivalent options:
+A blank **authScheme** field is not an empty value. It omits the option, the
+`Bearer` default still applies, and every request fails with
+`401 Invalid Authorization Scheme`.
+
+In the **JSON** editor:
 
 ```json
 {
@@ -172,29 +129,20 @@ The **JSON** editor mode shows the equivalent options:
 }
 ```
 
-### The provider still needs an API key
-
-The Portal requires an API key to save an Anthropic provider, and passthrough
-requests never send it: the request to Anthropic carries the caller's credential
-instead. Anything else that uses this provider's configured credential still
-needs a real key. That includes apps on this gateway that don't use passthrough
-and any
-[Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
-target, because fallback requests use the provider's configured credential
-rather than the caller's. If nothing on the gateway uses the configured
-credential, a placeholder value works.
+### Rules
 
-The app's playground in the Portal sends the app key as a bearer token in
-`Authorization`, so it can't call an app that uses passthrough. Test the app
-from Claude Code instead, as described below.
+- The provider still needs an API key to save. Passthrough requests never use
+  it. Apps without passthrough and every
+  [Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
+  target do. If nothing uses it, a placeholder value works.
+- The Portal playground sends the app key as `Authorization: Bearer`, so it
+  can't call a passthrough app. Test from Claude Code.
+- Do not set `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`, in the settings file
+  or in your shell. Either one replaces your login, and the gateway forwards it
+  to Anthropic instead.
 
 ### Configure Claude Code
 
-Add the following configuration to the settings file. Don't set
-`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` here or in your shell: either one
-replaces your `claude.ai` login, and the gateway would then forward that value
-to Anthropic as the credential.
-
 ```json
 {
   "env": {
@@ -217,73 +165,27 @@ to Anthropic as the credential.
 }
 ```
 
-`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header to every request
-Claude Code makes, while Claude Code keeps sending its own `Authorization`
-header from your login. The gateway consumes those incoming headers, uses the
-login credential to authenticate the Anthropic request, and never sends your app
-key to Anthropic.
+`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header. Claude Code
+keeps sending its own `Authorization` header from your login. The gateway never
+sends your app key to Anthropic.
 
-### Verify the subscription setup
-
-Restart Claude Code, then confirm which credential it's using and send one
-request through the gateway:
+## Verify
 
 ```bash
 claude auth status --text
 claude -p "Reply with the single word OK"
 ```
 
-The first command should report that you're signed in with your `claude.ai`
-account rather than an API key or auth token. The second returns a short reply,
-and the request appears in the app's usage in the Zuplo Portal. In an
-interactive session, `/status` shows the same login information.
-
-If the request fails:
-
-- `401` with `Invalid Authorization Scheme` — `authScheme` still has its
-  `Bearer` default. Set it to an explicit empty value in the policy.
-- `401` with `Header configured by options.authHeader is missing` — Claude Code
-  didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.
-- `401` with `credentialPassthrough requires a non-empty Authorization header` —
-  Claude Code isn't signed in. Run `claude` and use `/login`.
-- An authentication error from Anthropic — Anthropic rejected the forwarded
-  login credential. Sign in to Claude Code again.
-
-## 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
-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.
-
-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 startup model. Set it to a prefixed reference so the
-  gateway can route the first request.
-- `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-1`.
-
-Claude Code's `/model` picker can select either an alias or an exact model ID.
-`ANTHROPIC_DEFAULT_*_MODEL` maps aliases to gateway model names;
-[`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
-maps exact IDs. The examples configure both so either selection works through
-the gateway.
-
-:::caution{title='HTTP 400: model must use "providerName/model"'}
-
-This error means the selected model lacks its provider prefix. At startup, check
-`ANTHROPIC_MODEL`. After choosing a picker entry, check its `modelOverrides`
-entry, or type `/model fable` to use the configured alias. Restart Claude Code
-after editing the settings file.
+With the subscription approach, the first command reports a `claude.ai` login,
+not an API key or auth token. The request appears in the app's usage in the
+Zuplo Portal.
 
-:::
+## Troubleshooting
 
-The app's
-[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
-policy controls which models the app may use.
+| Error                                                                   | Fix                                                                                                                                        |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `400` `model must use "providerName/model"`                             | The selected model has no provider prefix. Check `ANTHROPIC_MODEL`, or the picker entry's `modelOverrides` mapping. Restart after editing. |
+| `401` `Invalid Authorization Scheme`                                    | `authScheme` still has its `Bearer` default. Set an explicit empty value.                                                                  |
+| `401` `Header configured by options.authHeader is missing`              | Claude Code didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.                                                            |
+| `401` `credentialPassthrough requires a non-empty Authorization header` | Claude Code isn't signed in. Run `claude` and use `/login`.                                                                                |
+| An authentication error from Anthropic                                  | Anthropic rejected the forwarded login. Sign in to Claude Code again.                                                                      |

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

@@ -2,156 +2,118 @@
 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.
+  Route Claude Desktop's Chat, Cowork, and Code sessions through a Zuplo AI
+  Gateway app.
 ---
 
-[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.
+Route [Claude Desktop](https://claude.com/download) through the Zuplo AI
+Gateway. The gateway authenticates, meters, and routes every Chat, Cowork, and
+Code session started from the 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
+## Prerequisites
 
 <Stepper>
 
-1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
-   Anthropic
+1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
 
-2. [Set up a new team](../managing-teams.mdx)
+2. [Create a 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
+3. [Create an app](../managing-apps.mdx) for Claude Desktop and assign it to the
+   team.
 
-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
+4. Copy the **API URL** and **API Key** from the app page.
 
 </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:
+## Configure Claude Desktop
 
 <Stepper>
 
-1. From the menu bar (macOS) or the application menu (Windows), select **Help →
-   Troubleshooting → Enable Developer Mode**.
+1. Select **Help → Troubleshooting → Enable Developer Mode** from the menu bar
+   (macOS) or the application menu (Windows).
 
 2. Open **Developer → Configure Third-Party Inference**.
 
-3. In the **Connection** section, set **Inference provider** to **Gateway**.
+3. Under **Connection**, set **Inference provider** to **Gateway**.
 
-4. In the **Gateway credentials** card, set **Gateway base URL** to the app's
-   API URL, for example
+4. Under **Gateway credentials**, 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).
+6. Under **Models**, add each model the app may use. See
+   [Add models](#add-models).
 
-7. Click **Apply locally**. Claude Desktop writes the configuration and
-   relaunches into it.
+7. Click **Apply locally**. Claude Desktop saves the configuration and
+   relaunches.
 
 </Stepper>
 
-:::note
+### Rules
 
-Claude Desktop appends `/v1/messages` to the base URL itself, so **Gateway base
-URL** is the app's URL _without_ the `/v1` suffix.
+- **Gateway base URL** is the app's API URL _without_ `/v1`. Claude Desktop
+  appends `/v1/messages`.
+- **Gateway auth scheme** stays **Bearer**. The gateway reads the API key from
+  the `Authorization: Bearer` header.
+- **Credential kind** stays **Static API key**. AI Gateway apps authenticate
+  with API keys, not identity-provider tokens.
 
-:::
+## Add models
 
-:::caution{title="Keep the auth scheme set to Bearer"}
+:::warning{title="Replace the provider name"}
 
-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.
+The examples assume your provider is named `anthropic`. Replace that prefix with
+the name of **your** provider before entering any model. A provider named
+`my-anthropic` routes `my-anthropic/claude-sonnet-5`; a Bedrock provider named
+`bedrock` routes `bedrock/anthropic.claude-sonnet-5`. The model part must be an
+ID that provider serves. Check [your provider's page](../managing-providers.mdx)
+in the Portal.
 
 :::
 
-### 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:
+The **Model list** replaces the models Claude Desktop discovers on its own.
+Click **Add** once per model:
 
 - **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.
+  `anthropic/claude-sonnet-5`. A bare ID fails with a `400`.
+- **Display name** — the name in the model picker. Leave it blank and Claude
+  Desktop formats one from the ID.
+- **Offer 1M-context variant** — off, unless your provider 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.
+  stands in for. The bare alias, for example `opus`, then resolves to it.
 
-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 first entry is the picker default. Include a Haiku-tier model: Claude
+Desktop runs background and sub-agent tasks on a small, fast model.
 
 The app's
 [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
-policy controls which models the app may use.
-
-### Verify the configuration
+policy controls which models the app can use.
 
-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).
+## Verify
 
-:::caution{title='HTTP 400: model must use "providerName/model"'}
+Send a message in Chat and start a Cowork session. Both appear in the app's
+usage in the Zuplo Portal, as do Code sessions started from the desktop app.
+Terminal Claude Code sessions use their own configuration. See
+[Claude Code](./claude-code.mdx).
 
-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.
+## Troubleshooting
 
-:::
+| Error                                                        | Fix                                                                                         |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `400` `The request body model must use "providerName/model"` | A model list entry has no provider prefix. Give every entry a full `providerName/model` ID. |
 
-### Deploy to a fleet
+## 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
+Use the configuration window's **Export** menu instead of **Apply locally**. It
+produces a `.mobileconfig` profile for macOS MDM tools such as Jamf, a `.reg`
+policy file for Intune or Group Policy, and related artifacts. Managed
+configuration overrides local settings. 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/integrations/codex.mdx

@@ -1,98 +1,104 @@
 ---
 title: Codex
 sidebar_label: Codex
-description:
-  Configure the Codex CLI to send its requests through an AI Gateway app, either
-  by rerouting the built-in OpenAI provider or by adding a Zuplo provider.
+description: Route Codex CLI requests through a Zuplo AI Gateway app.
 ---
 
-[Codex](https://developers.openai.com/codex) is a coding agent developed by
-OpenAI that you can run locally from your terminal and that can read, modify,
-and run code on your machine, in the chosen directory. It’s open-source, and
-built in Rust for speed and efficiency.
+[Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the
+terminal. This guide routes its requests through the Zuplo AI Gateway.
 
 ## Prerequisites
 
-In order to use the AI Gateway with Codex you will need to complete these steps
-first:
-
 <Stepper>
 
-1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
-   provider you want to use with Codex
+1. Create a [provider](../managing-providers.mdx) in the AI Gateway.
 
-2. [Set up a new team](../managing-teams.mdx)
+2. [Create a team](../managing-teams.mdx).
 
-3. Create a [new app](../managing-apps.mdx) to use specifically with Codex and
-   assign it to the team you created
+3. [Create an app](../managing-apps.mdx) for Codex and assign it to the team.
 
-4. Copy the **API URL** and **API Key** shown at the top of the app page
+4. Copy the **API URL** and **API Key** from the app page.
 
 </Stepper>
 
-## Configure Codex CLI
-
-There are two approaches you can take to using Codex with Zuplo's AI Gateway.
-
-1. **Route OpenAI through AI Gateway** - This would configure your OpenAI
-   provider in Codex to route requests through the AI Gateway rather than
-   directly to OpenAI
+## Configure Codex
 
-2. **Create a Zuplo specific provider** - Use Zuplo as a provider that be
-   selected in the Codex configuration and work with any OpenAI compatible
-   models
+:::warning{title="Replace the provider name"}
 
-Configuration steps for both options are below:
+The examples assume your provider is named `openai`. Replace that prefix with
+the name of **your** provider before copying anything. A provider named
+`my-openai` routes `my-openai/gpt-5`. The model part must be an ID that provider
+serves. Check [your provider's page](../managing-providers.mdx) in the Portal.
 
-### Route OpenAI through AI Gateway
+:::
 
-Open the [Codex configuration](https://developers.openai.com/codex/local-config)
-`~/.codex/config.toml` and modify the `model_providers.openai-chat-completions`
-entry so that the `base_url` points to your app's API URL with `/v1` appended,
-and set your `env_key` to the API Key of the app you created to use with Codex.
-The app page in the Zuplo Portal shows the API URL, which ends in the app's ID.
+Codex reads configuration from `~/.codex/config.toml`. Create this file (and the
+`~/.codex` directory if needed) if it does not exist. Add the following:
 
 ```toml
-[model_providers.openai-chat-completions]
-name = "OpenAI using Chat Completions"
+model_provider = "zuplo"
+model = "openai/gpt-5"
+
+[model_providers.zuplo]
+name = "Zuplo AI Gateway"
 base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
 env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+wire_api = "responses"
 ```
 
-Save the file and reload Codex. Your OpenAI requests will now be routed through
-the Zuplo AI Gateway.
+- `base_url` is the app's API URL with `/v1` appended.
+- `model` is `providerName/model`.
 
-### Zuplo AI Gateway provider
+Set the API key in your environment:
 
-To add a specific provider for the AI Gateway you can add an additional entry to
-the Codex `config.toml` file.
-
-```toml
-[model_providers.zuplo]
-name = "Zuplo AI Gateway"
-base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
-env_key = "ZUPLO_AI_GATEWAY_API_KEY"
+```bash
+export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
 ```
 
-Save the file and reload Codex. Your Zuplo AI Gateway provider will now be
-available and you can switch Codex over to use it at any time by running:
+Restart Codex. All requests now go through the gateway.
+
+### Rules
+
+- `model_provider = "zuplo"` is required. Without it, Codex uses its built-in
+  `openai` provider and bypasses the gateway.
+- `wire_api` must be `responses`. Codex speaks only the Responses API; it
+  [removed](https://github.com/openai/codex/discussions/7782) support for
+  `/v1/chat/completions`, and `wire_api = "chat"` fails to load.
+- Put this configuration in the user-level file. Codex ignores `model_provider`
+  and `model_providers` in a project-level `.codex/config.toml`.
+
+## Switch models
+
+Set `model` in `config.toml`, or pass it on the command line:
 
 ```bash
-codex --config model_provider="zuplo"
+codex --config model_provider="zuplo" --model "openai/gpt-5.6-sol"
 ```
 
-### Choosing a model
+Do not use the `/model` picker. It sends model names without the provider
+prefix, and the gateway rejects them with a `400`.
+
+Codex warns that it has no metadata for a prefixed model name. Requests still
+succeed.
 
 The app's
 [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
-policy controls which models the app may use. Codex names the model as
-`providerName/model`, where `providerName` is the provider name configured in
-your gateway:
+policy controls which models the app can use.
+
+## Verify
 
 ```bash
-codex --config model_provider="zuplo" --model "openai/gpt-5"
+codex exec "Reply with the single word OK"
 ```
 
-A request with no model, or a model without that prefix, gets a `400`. Adding
-[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx) with
-an allow list also supplies a default, letting requests omit the model.
+The session header shows `provider: zuplo`. The request appears in the app's
+usage in the Zuplo Portal.
+
+## Troubleshooting
+
+| Error                                                                                      | Fix                                                                 |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `400` `The request body model must use "providerName/model"`                               | Add the provider prefix to `model`. Do not use the `/model` picker. |
+| `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY`                            | Export the variable in the shell that runs Codex.                   |
+| `401` `Authorization Failed`                                                               | The API key is wrong. Copy it from the app's **API Key** tab.       |
+| Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`.   |

package/docs/articles/custom-domains.mdx

@@ -22,8 +22,9 @@ Zuplo supports two types of custom domains that can be configured separately:
    `cname.zuplodocs.com`. Learn more about the Developer Portal in the
    [Developer Portal documentation](/docs/dev-portal/overview).
 
-Both types of custom domains can be managed from the same Custom Domains section
-in your project settings and follow a similar configuration process.
+Manage both types of custom domains in
+[**Account Settings → Custom Domains**](https://portal.zuplo.com/+/account/settings/custom-domains).
+They follow a similar configuration process.
 
 :::note
 

package/docs/articles/source-control.mdx

@@ -65,9 +65,10 @@ If your code lives elsewhere but you want to use a specific CI/CD system:
 
 ## How Branch-Based Deployments Work
 
-Every Git branch maps to a Zuplo environment. Push to `main` and deploy to your
-main environment. Push to `feature-auth` and get a `feature-auth` environment
-automatically.
+With the GitHub integration, every Git branch maps to a Zuplo environment. Push
+to `main` and deploy to your main environment. Push to `feature-auth` and get a
+`feature-auth` environment automatically. For other providers, configure your
+CI/CD pipeline to deploy each branch.
 
 This enables powerful workflows like PR preview environments where reviewers can
 test changes against a live API before merging.

package/docs/articles/testing.mdx

@@ -140,11 +140,11 @@ and the same file supplies fixture values to `zuplo test`. See
 
 ## Test before merge
 
-Every branch pushed to your connected source control provider deploys as a
-preview environment: a full Zuplo deployment on the same edge network as
-production, at its own URL. Running your suite there is the highest-fidelity
-check available before a change merges, and it needs no shared staging
-environment.
+With the GitHub integration, pushing a feature branch automatically creates a
+preview environment at its own URL. For GitLab, Bitbucket, or Azure DevOps,
+configure a [CI/CD pipeline](./custom-ci-cd.mdx) to deploy the branch. Running
+your suite against a preview deployment lets you test changes before merging
+without a shared staging environment.
 
 - [Testing preview environments](./testing-preview-environments.mdx) — getting
   the URL into your tests, per-environment services and secrets, and what to

package/docs/articles/upstream-iam-auth.mdx

@@ -19,8 +19,8 @@ identity provider you control. For the alternatives, see
 
 ## Federated identity or stored credentials
 
-Every provider offers two paths, and the choice matters more than which cloud
-you're on.
+Zuplo offers federated identity and stored-credential policies. The available
+options depend on your cloud provider, as shown in the policy table below.
 
 **Federated identity** is the stronger option. Zuplo presents a short-lived,
 audience-bound OIDC token that proves which gateway is calling, and your cloud

package/docs/concepts/how-zuplo-works.mdx

@@ -87,7 +87,8 @@ workflow is:
 
 1. **Develop** locally or in the Zuplo Portal
 2. **Push** to your Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps)
-3. **Deploy** automatically - Zuplo builds and deploys your gateway globally
+3. **Deploy** automatically with the GitHub integration, or configure a CI/CD
+   pipeline to deploy from GitLab, Bitbucket, or Azure DevOps
 
 Deployments complete in seconds. Each Git branch gets its own isolated
 environment with its own URL, making it easy to test changes before merging to

package/docs/dev-portal/migration.mdx

@@ -125,8 +125,8 @@ process, continue with the manual migration steps below.
 
    :::caution
 
-   Currently, this migration must be done locally. It cannot be done in the
-   Zuplo Portal.
+   Follow these manual migration steps locally. To migrate in the Zuplo Portal,
+   use the [built-in migration tool](#migrate-in-the-portal).
 
    :::
 

package/docs/getting-started/dev-portal/index.mdx

@@ -8,8 +8,8 @@ centered: false
 toc: false
 title: Getting Started with Developer Portal
 description:
-  Publish docs and self-serve API keys with Zudoku with Zuplo, in the Portal,
-  locally with the CLI, or with an AI agent.
+  Publish interactive API docs and let consumers manage their API keys through a
+  developer portal built in the Portal, locally, or with an AI agent.
 ---
 
 <WizardSteps build="dev-portal" />

package/docs/getting-started/gateway/add-api-key-auth/index.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Add API key authentication - Portal
@@ -166,3 +167,5 @@ Let's get started.
    [our developer portal auth docs](/docs/dev-portal/zudoku/configuration/authentication).
 
 </Stepper>
+
+<TutorialPager build="gateway" method="portal" step="add-api-key-auth" />

package/docs/getting-started/gateway/add-api-key-auth/local.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Add API key authentication - Editor
@@ -154,3 +155,5 @@ Let's get started.
    :::
 
 </Stepper>
+
+<TutorialPager build="gateway" method="local" step="add-api-key-auth" />

package/docs/getting-started/gateway/add-rate-limiting/index.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Add rate limiting - Portal
@@ -81,3 +82,5 @@ limiter.
    echo API.
 
 </Stepper>
+
+<TutorialPager build="gateway" method="portal" step="add-rate-limiting" />

package/docs/getting-started/gateway/add-rate-limiting/local.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Add rate limiting - Editor
@@ -100,3 +101,5 @@ full power of the world's best rate limiter.
    your API.
 
 </Stepper>
+
+<TutorialPager build="gateway" method="local" step="add-rate-limiting" />

package/docs/getting-started/gateway/agent.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Getting Started with API Gateway - Agent
@@ -84,7 +85,7 @@ from inside your project directory.
    2. Add the rate-limiting inbound policy (rateLimitBy: ip, 2 requests / 1 minute) to every route.
    3. Add the api-key-inbound policy to every route, ordered before rate limiting.
    4. Make rate limiting dynamic: create modules/rate-limit.ts exporting rateLimit() that returns 1000 req/min for user.data.customerType === "premium", 5 for "free", 30 otherwise, and switch the policy to rateLimitBy: "function".
-   5. Run npm run dev and verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.
+   5. Use the already-running dev server to verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.
 
    Explain each config change in one line and stop before pushing to git.
    ```

package/docs/getting-started/gateway/deploy-to-the-edge/index.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Deploy to the edge - Portal
@@ -229,3 +230,5 @@ when running commits, pulls or try to open a pull request.
 - If the GitHub repository has been renamed or moved to a different
   organization, try disconnecting and reconnecting to it. You can do this by
   going to your Zuplo project's settings > Source Control section
+
+<TutorialPager build="gateway" method="portal" step="deploy-to-the-edge" />

package/docs/getting-started/gateway/deploy-to-the-edge/local.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Deploy to the edge - Editor
@@ -132,3 +133,5 @@ Zuplo project in the Portal. The local files alone cannot receive a deployment.
    :::
 
 </Stepper>
+
+<TutorialPager build="gateway" method="local" step="deploy-to-the-edge" />

package/docs/getting-started/gateway/dynamic-rate-limiting/index.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Dynamic rate limiting - Portal
@@ -175,3 +176,5 @@ less than an hour.
   questions answered
 - Start generating revenue from your new API with our
   [Monetization tutorial](../../../articles/monetization/index.mdx)
+
+<TutorialPager build="gateway" method="portal" step="dynamic-rate-limiting" />

package/docs/getting-started/gateway/dynamic-rate-limiting/local.mdx

@@ -1,5 +1,6 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
 title: Dynamic rate limiting - Editor
@@ -187,3 +188,5 @@ less than an hour.
   questions answered
 - Start generating revenue from your new API with our
   [Monetization tutorial](../../../articles/monetization/index.mdx)
+
+<TutorialPager build="gateway" method="local" step="dynamic-rate-limiting" />

package/docs/getting-started/gateway/setup-a-basic-gateway/index.mdx

@@ -1,8 +1,9 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
-title: Setup a basic gateway - Portal
+title: Set up a basic gateway - Portal
 description:
   Proxy an origin API through a managed Zuplo gateway, add your first route, and
   see traffic flowing end to end in the Zuplo Portal.
@@ -123,3 +124,5 @@ Note - Zuplo also supports building and running your API locally. To learn more
    response from Step 2.
 
 </Stepper>
+
+<TutorialPager build="gateway" method="portal" step="setup-a-basic-gateway" />

package/docs/getting-started/gateway/setup-a-basic-gateway/local.mdx

@@ -1,8 +1,9 @@
 ---
 category: API Management
+disablePager: true
 showLastModified: false
 suggestEdit: false
-title: Setup a basic gateway - Editor
+title: Set up a basic gateway - Editor
 description:
   Proxy an origin API through a managed Zuplo gateway, add your first route, and
   see traffic flowing end to end with the Zuplo CLI and your editor.
@@ -116,3 +117,5 @@ project template, which ships with a working todo API.
    gateway is now serving traffic locally.
 
 </Stepper>
+
+<TutorialPager build="gateway" method="local" step="setup-a-basic-gateway" />

package/docs/getting-started/mcp-gateway/local.mdx

@@ -4,8 +4,8 @@ showLastModified: false
 suggestEdit: false
 title: Getting Started with MCP Gateway - Editor
 description:
-  A step-by-step guide to building a mcp gateway with Zuplo using local
-  development.
+  Build an MCP Gateway locally with the Zuplo CLI, connect an upstream MCP
+  server, and test its tools with a local MCP client.
 ---
 
 <WizardSteps build="mcp-gateway" method="local" />
@@ -222,11 +222,33 @@ older project and the build complains about the compatibility date, see
 
 6. **Connect Claude Desktop**
 
-   Open Claude Desktop, go to **Settings → Connectors**, scroll to the bottom,
-   and click **Add custom connector**. Paste
-   `http://127.0.0.1:9000/mcp/linear-v1` and click **Add**.
+   Use a local stdio bridge so Claude Desktop can reach your local gateway.
+   Native remote connectors connect from Anthropic's servers and cannot reach
+   `127.0.0.1` on your computer.
 
-   Claude Desktop opens the gateway's OAuth flow in a browser:
+   In Claude Desktop, open **Settings → Developer → Edit Config** and add this
+   entry to `claude_desktop_config.json`, preserving any existing servers:
+
+   ```json title="claude_desktop_config.json"
+   {
+     "mcpServers": {
+       "Zuplo MCP": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "mcp-remote",
+           "http://127.0.0.1:9000/mcp/linear-v1",
+           "--allow-http"
+         ]
+       }
+     }
+   }
+   ```
+
+   Save the file and restart Claude Desktop. The bridge opens the gateway's
+   OAuth flow on first connection.
+
+   In the browser:
    1. The dev-login shortcut signs you in without any IdP prompt.
    2. The gateway's consent page lists Linear with a **Connect** button.
    3. Click **Connect**, complete Linear's OAuth flow, then click **Authorize**
@@ -234,9 +256,9 @@ older project and the build complains about the compatibility date, see
 
    :::tip{title="Checkpoint: Claude is connected"}
 
-   Back in Claude Desktop, the new connector appears in **Settings →
-   Connectors** marked as connected. Subsequent requests reuse the tokens the
-   gateway just issued.
+   Back in Claude Desktop, the **Zuplo MCP** server appears under **Settings →
+   Developer**. Its tools are available in chat. Subsequent requests reuse the
+   tokens the gateway just issued.
 
    :::
 

package/docs/getting-started/mcp-gateway/portal.mdx

@@ -4,7 +4,8 @@ showLastModified: false
 suggestEdit: false
 title: Getting Started with MCP Gateway - Portal
 description:
-  A step-by-step guide to building a mcp gateway with Zuplo using Zuplo Portal.
+  Connect an MCP client to Linear through a Zuplo MCP Gateway in the Portal,
+  then sign in and call a Linear tool through the gateway.
 ---
 
 <WizardSteps build="mcp-gateway" method="portal" />
@@ -155,9 +156,9 @@ your machine.
 
    :::tip{title="Upstream doesn't use OAuth?"}
 
-   Pick **None** to forward directly. The user's token is then either forwarded
-   to the upstream or removed at the point of login, depending on the upstream's
-   needs.
+   Pick **None** when the upstream doesn't require authentication. If gateway
+   OAuth is enabled, the gateway validates and removes its access token before
+   forwarding the request. It doesn't use that token to authenticate upstream.
 
    :::
 
@@ -240,8 +241,8 @@ your machine.
    Your route is live at `https://<your-gateway>/mcp/linear-v1`. Find the public
    URL via the **Gateway deployed** button in the toolbar.
 
-   Open Claude Desktop, go to **Settings → Connectors**, scroll to the bottom,
-   and click **Add custom connector**. Paste the route URL and click **Add**.
+   Open Claude Desktop, go to **Customize → Connectors**, click **+**, then
+   **Add custom connector**. Paste the route URL and click **Add**.
 
    Claude Desktop opens the gateway's OAuth flow in a browser:
    1. Sign in with your identity provider (Auth0 in this example).
@@ -251,7 +252,7 @@ your machine.
 
    :::tip{title="Checkpoint: Claude is connected"}
 
-   Back in Claude Desktop, the new connector appears in **Settings →
+   Back in Claude Desktop, the new connector appears in **Customize →
    Connectors** marked as connected. Subsequent requests reuse the tokens the
    gateway just issued.
 

package/docs/getting-started/mcp-server/local.mdx

@@ -4,8 +4,8 @@ showLastModified: false
 suggestEdit: false
 title: Getting Started with MCP Server - Editor
 description:
-  A step-by-step guide to building a mcp server with Zuplo using local
-  development.
+  Expose a sample API as an MCP server with the Zuplo CLI and your editor, then
+  connect an MCP client and call a tool locally.
 ---
 
 <WizardSteps build="mcp-server" method="local" />

package/docs/getting-started/migrate/index.mdx

@@ -8,8 +8,8 @@ centered: false
 toc: false
 title: Getting Started with API Migration
 description:
-  Import an OpenAPI document and put Zuplo in front of what you have with Zuplo,
-  in the Portal, locally with the CLI, or with an AI agent.
+  Import an OpenAPI document, route requests through Zuplo, and compare them
+  with your existing backend in the Portal, locally, or with an AI agent.
 ---
 
 <WizardSteps build="migrate" />

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

@@ -26,9 +26,13 @@ Claude's connector settings, then complete the browser-based OAuth flow.
 ## Get the route URL
 
 Each MCP route in `config/routes.oas.json` is reachable at
-`https://{deploymentUrl}/{routePath}` once deployed (or
-`http://127.0.0.1:9000/{routePath}` when running locally with `zuplo dev`). The
-`{routePath}` is the path you set on the route — for example `/mcp/linear-v1`.
+`https://{deploymentUrl}/{routePath}` once deployed. The `{routePath}` is the
+path you set on the route — for example `/mcp/linear-v1`.
+
+Native remote connectors connect from Anthropic's servers, so the gateway URL
+must be reachable from those servers. For a gateway running locally with
+`zuplo dev`, use the [manual configuration](#use-a-manual-config-file-advanced)
+with `http://127.0.0.1:9000/{routePath}`.
 
 ## Add the connector in Claude
 
@@ -37,14 +41,12 @@ identical in each.
 
 <Stepper>
 
-1. **Open connector settings.**
-   - **Claude Desktop:** open **Settings** → **Connectors**.
-   - **Claude.ai:** open **Settings** → **Connectors** in the web app.
+1. **Open connector settings.** In Claude Desktop or Claude.ai, open **Customize
+   → Connectors**.
 
 2. **Add a custom connector.**
 
-   Scroll to the bottom of the Connectors list and click **Add custom
-   connector**.
+   Click **+**, then **Add custom connector**.
 
 3. **Enter the gateway URL.**
 
@@ -76,7 +78,7 @@ identical in each.
 :::tip
 
 You can adjust which tools Claude is allowed to use per connector. Open the
-connector in Settings → Connectors and toggle individual tools on or off.
+connector in Customize → Connectors and toggle individual tools on or off.
 
 :::
 
@@ -102,21 +104,22 @@ in addition to DCR.
 If you need to script the install or share the configuration with a team, Claude
 Desktop also reads `claude_desktop_config.json`. This approach uses
 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio bridge to
-the remote gateway. Use it if your version of Claude Desktop doesn't yet support
-custom remote connectors natively, or if you want the connector to start
-automatically on every launch without going through the UI.
+the gateway. Use it for a gateway running on your computer or when you need
+file-based configuration. This approach requires Node.js and `npx`.
 
 1. In Claude Desktop, open **Settings** → **Developer** → **Edit Config**. This
    opens `claude_desktop_config.json` in your editor.
 2. Add or merge in the following entry, replacing `Zuplo MCP` with the name you
-   want to show, and the URL with your route URL:
+   want to show, and the URL with your route URL. For local development, use
+   `http://127.0.0.1:9000/{routePath}` instead of the HTTPS URL and append
+   `"--allow-http"` to the `args` array:
 
    ```json title="claude_desktop_config.json"
    {
      "mcpServers": {
        "Zuplo MCP": {
          "command": "npx",
-         "args": ["mcp-remote", "https://{deploymentUrl}/{routePath}"]
+         "args": ["-y", "mcp-remote", "https://{deploymentUrl}/{routePath}"]
        }
      }
    }
@@ -131,10 +134,9 @@ automatically on every launch without going through the UI.
 
 :::note
 
-The native custom-connector flow above is the recommended path because it
-supports all of Claude Desktop's MCP features out of the box and does not
-require Node.js. Use the `mcp-remote` bridge only when you specifically need the
-file-based configuration.
+Use native custom connectors for a deployed gateway. They do not require
+Node.js. Use the `mcp-remote` bridge for a local gateway or file-based
+configuration.
 
 :::
 
@@ -148,7 +150,7 @@ file-based configuration.
   configured correctly and that browser cookies are enabled for the gateway
   origin.
 - **Tools do not appear after a successful authorization.** Open the connector
-  in Settings → Connectors and check that each tool is enabled. Disabled tools
+  in Customize → Connectors and check that each tool is enabled. Disabled tools
   are hidden from the attachment menu.
 
 ## Related

package/docs/mcp-gateway/connect-clients/overview.mdx

@@ -119,7 +119,8 @@ tracks **what each client can consume**, not what the gateway forwards.
 
 ## Per-client guides
 
-- [Claude Desktop](./claude-desktop.mdx) — add via `claude_desktop_config.json`.
+- [Claude Desktop and Claude.ai](./claude-desktop.mdx) — add a custom remote
+  connector. For a local gateway, use the Claude Desktop manual configuration.
 - [Claude Code](./claude-code.mdx) — add via the `claude mcp add` CLI command.
 - [ChatGPT](./chatgpt.mdx) — add via Settings → Connectors (Developer Mode
   required).

package/package.json

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