multi-router.aidocs

Agents & Editors

Claude Desktop

Connecting Claude Desktop to a Claude Proxy through its third-party inference gateway settings.

Claude Desktop is Anthropic's desktop app for chat and local work. It connects to Multi-Router through its third-party inference settings, which send its requests to a gateway instead of to Anthropic. The gateway is a Claude Proxy on the Anthropic route with the Organization credential source: requests are served with the organization's Anthropic key, and the app's model picker lists the models the organization allows.

Chat and Code

Claude Desktop has two kinds of work, each connected to Multi-Router in its own place. The Code tab runs Claude Code inside the app and reads Claude Code's settings, so it connects through the Claude Code setup. The rest of the app, including chat, connects through the gateway settings on this page.

Part of the appConnected throughSetup
Chat and local workThe third-party inference gateway settingsThis page, from Setting up
Code tabClaude Code's settings, such as ~/.claude/settings.jsonClaude Code. Start a new Code session after changing them.

Requirements

Claude Desktop connects through a Claude Proxy and an API key set up as follows:

ItemRequirement
Claude ProxyThe Anthropic route, or a Custom route whose model group contains Anthropic models, with the Organization credential source. Claude Desktop sends requests in the Anthropic format only.
API keyScopes inference and models:read. The model picker reads its list with models:read.
Claude DesktopInstalled from claude.ai/download and signed in with a work account.

Credentials

Claude Desktop sends one credential with each request, the Gateway API key, so the Multi-Router API key is the only credential it holds. The Claude Proxy therefore uses the Organization credential source: Multi-Router identifies the person from their API key and sends the request to Anthropic with the organization's Anthropic key, and usage is billed to the organization's Anthropic account. A tools policy for Claude Desktop accepts the Organization credential source only, for the same reason.

Setting up

The gateway is set in Claude Desktop's developer settings:

  1. In Claude Desktop, choose Help, then Troubleshooting, then Enable Developer Mode.
  2. Choose Developer, then Configure Third-Party Inference, and open Connection.
  3. Fill in the fields below, and save.
  4. Quit and reopen Claude Desktop, which reads these settings when it starts.
FieldValue
Inference providerGateway
Gateway base URLhttps://api.multi-router.ai
Credential kindStatic API key
Gateway API keyThe Multi-Router API key
Gateway auth schemeBearer. The key then travels in the Authorization header on every request, including the model list.
Custom inference headersX-MR-Router with the Claude Proxy's id, such as rt_5Tc7Hn1GsR

To check the setup, open a new chat and say hello. The reply appears in Traffic under the Claude Proxy.

Models

Claude Desktop fills its model picker from the Claude Proxy, which lists each model its route serves and the router has switched on. A model group of Anthropic models on the Custom route therefore controls exactly which models people can pick. Leave the app's own model list setting, inferenceModels, unset so that the picker follows the proxy. The picker refreshes when Claude Desktop starts.

The list comes from the Claude Proxy and behaves as follows:

CasePicker
Each model the route servesOne entry, with the model's display name, such as Claude Opus 5.
A model switched off on the Claude ProxyRemoved from the picker the next time Claude Desktop starts.
A model added to the model groupAdded to the picker the next time Claude Desktop starts.
An API key without models:readEmpty, because the list request is refused with insufficient_scope. Add the scope to the key.

Example

A company gives its support team Claude Desktop with two approved models. An admin creates a model group named Support models containing Claude Opus 5 and Claude Sonnet 4.5, then a Claude Proxy named Support desktop on the Custom route with that group and the Organization credential source. Its id is rt_6Wp2Jd8LmS. Each person on the team gets an API key with the inference and models:read scopes, limited to that router, and enters these values in Claude Desktop:

Configure Third-Party Inference, Connectiontext
Inference provider:       Gateway
Gateway base URL:         https://api.multi-router.ai
Credential kind:          Static API key
Gateway API key:          <the person's Multi-Router API key>
Gateway auth scheme:      Bearer
Custom inference headers: X-MR-Router = rt_6Wp2Jd8LmS

After a restart, the model picker lists Claude Opus 5 and Claude Sonnet 4.5. When the admin later adds Claude Haiku 4.5 to Support models, it appears in everyone's picker the next time they open Claude Desktop, with no change on their machines. A budget on the Support desktop router caps the team's monthly spend, and Traffic shows each person's usage by their API key.

Rolling out to many people

IT teams roll the same settings out to many machines from the Configure Third-Party Inference screen: Export saves the settings as a .mobileconfig profile for macOS or a .reg file for Windows, which device management tools then install. Each person needs their own Multi-Router API key, so that Traffic and budgets apply to them individually.

In organizations that use Self-Service Provisioning, people set up Claude Desktop themselves from the Portal. Choosing Claude Desktop creates their own Claude Proxy from the organization's tools policy and an API key with the inference and models:read scopes. The Portal then shows the install and Developer Mode steps, each Connection field value with its own copy button, the key masked with Copy and Reveal key, and the steps to check the setup. See Self-Service Provisioning.

Rolling out the Code tab

The Code tab follows Claude Code's managed settings, which device management tools such as Jamf, Kandji and Intune install on each machine. Managed settings take precedence over each person's own settings, so every Code tab session goes through the Claude Proxy. The settings file and its contents are the same as for Claude Code:

PlatformManaged settings file
macOS/Library/Application Support/ClaudeCode/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json

With one file for every machine, apiKeyHelper gives each person their own Multi-Router API key from a vault. See Claude Code.

Changing settings and rotating keys

Claude Desktop reads its gateway settings only when it starts, so every change on a machine takes effect after the app is quit and reopened. Changes made in Multi-Router, such as the models a Claude Proxy serves, its route or its budgets, apply to requests at once and reach the model picker at the next start. To rotate a person's API key:

  1. Create a new API key with the same scopes and router limit.
  2. Enter it in the Gateway API key field, or redeploy the exported profile with the new key, and restart Claude Desktop.
  3. Disable the old key in Multi-Router once the new one is in use.

Usage in Traffic

Each Claude Desktop request appears in Traffic under the Claude Proxy in the Router column, with the person's API key in the request detail, the model, tokens and cost. Filtering Traffic by the Claude Proxy shows the team's usage, and the API key separates one person from another. When each person has their own Claude Proxy, as Self-Service Provisioning sets up, the Router column alone identifies the person. See Observability.

Troubleshooting

Claude Desktop shows Multi-Router's errors in the chat. The common ones are:

Symptom or messageCauseFix
400 your MR API token was sent in authorizationThe Claude Proxy uses the Developer credential source.Switch the Claude Proxy to the Organization credential source.
404 model is served on bedrock, not available on the Anthropic endpointThe Claude Proxy's route, or a model in its group, is served by Bedrock or Vertex.Use the Anthropic route, or a model group of Anthropic models.
The model picker is emptyThe API key lacks models:read, or the app was not restarted after setup.Add the scope to the key, then quit and reopen Claude Desktop.
401 invalid or missing API tokenThe Gateway API key is wrong, disabled or expired.Enter a current key and restart.
403 this Claude Proxy is disabledAn admin disabled the Claude Proxy.Enable the Claude Proxy.
429 budget is exhaustedA budget on the Claude Proxy reached its cap.Wait for the budget to reset, or raise it.

See Troubleshooting for every message.

Supported sessions

Through a gateway, Claude Desktop runs local sessions: chats and local work on the person's own machine. SSH sessions, cloud environments and Remote Control use a direct connection to Anthropic.

Kilo CodeClaude for Office
Was this helpful?