Claude Desktop
Claude Desktop 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.
Claude Desktop Setup
-
Create a new provider in the AI Gateway for Anthropic
-
Create a new app to use with Claude Desktop and assign it to the team you created
-
Copy the API URL and API Key shown at the top of the app page
-
Enter the API URL, API key, and model list in Claude Desktop's third-party inference settings
Before copying: 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 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:
-
From the menu bar (macOS) or the application menu (Windows), select Help → Troubleshooting → Enable Developer Mode.
-
Open Developer → Configure Third-Party Inference.
-
In the Connection section, set Inference provider to Gateway.
-
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. -
Leave Credential kind set to Static API key and Gateway auth scheme set to Bearer.
-
In the Models section, add the models the app may use to the Model list. See Add models to the Model list.
-
Click Apply locally. Claude Desktop writes the configuration and relaunches into it.
Claude Desktop appends /v1/messages to the base URL itself, so Gateway base
URL is the app's URL without the /v1 suffix.
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/modelreference, for exampleanthropic/claude-sonnet-5. A bare id such asclaude-sonnet-5fails 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 in the portal for the models it currently serves, and use those ids.
The app's Model Filtering 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 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.
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
and Deploy with MDM.