# Claude Desktop

[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).