Zuplo
Integrations

Claude Desktop

Route Claude Desktop through the Zuplo AI Gateway. The gateway authenticates, meters, and routes every Chat, Cowork, and Code session started from the app.

To give Claude Desktop tools from a Zuplo MCP route instead, see Connect Claude Desktop and Claude.ai.

Prerequisites

Create an Anthropic provider in the AI Gateway, then get a gateway URL and key in one of two ways:

  • Use your personal API key (recommended). Claude Desktop runs on your own machine, so call the project's User App. Open the My Keys tab of your AI Gateway project, copy the Gateway URL, and create a key under My API keys. Your requests count against your own budget.
  • Use an app. For a shared setup, such as deploying to a fleet with one key, create a pool and an app for Claude Desktop, then copy the app's API URL and API Key.

The rest of this guide calls these your gateway URL and gateway key.

Configure Claude Desktop

  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. Under Connection, set Inference provider to Gateway.

  4. Under Gateway credentials, set Gateway base URL to your gateway URL, for example https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64, and Gateway API key to your gateway key.

  5. Leave Credential kind set to Static API key and Gateway auth scheme set to Bearer.

  6. Under Models, add each model you may use. See Add models.

  7. Click Apply locally. Claude Desktop saves the configuration and relaunches.

Rules

  • Gateway base URL is your gateway 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. The AI Gateway authenticates with personal or app API keys, not identity-provider tokens.

Add models

Replace the provider name

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 in the Portal.

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 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. The bare alias, for example opus, then resolves to it.

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 Model Filtering policy on the User App or the app controls which models you can use.

Verify

Send a message in Chat and start a Cowork session. Both appear in your usage on the My Keys tab, or in the app's usage if you used an app, as do Code sessions started from the desktop app. Terminal Claude Code sessions use their own configuration. See Claude Code.

Troubleshooting

ErrorFix
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.
403 This User App route requires a personal API key issued for this User AppWith a personal key: the key is missing, wrong, from another project, or not sent as Authorization: Bearer. Create a key on My Keys and use the Gateway URL from the same project.

Deploy to a fleet

A fleet deployment shares one gateway key across machines, so use an app's API URL and API key rather than a personal key. 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 and Deploy with MDM.

Last modified on
Claude CodeCodex