Claude Desktop & Cowork

Connect Claude Desktop (Cowork on third-party inference) to the TrueFoundry AI Gateway.

Claude Desktop can run in third-party inference mode (Anthropic calls it Cowork on 3P): instead of signing in to claude.ai, the app routes inference to a gateway that implements the Anthropic Messages API. The TrueFoundry AI Gateway is compatible with this mode, and the setup is the same on every Claude plan.

For Anthropic’s own reference, see Installation and setup, Configuration reference, Using an LLM gateway, and the Help Center article Install and configure Claude Cowork with third-party platforms.

There are two ways to point Claude Desktop at the AI Gateway. The per-user UI below (Developer Mode → Configure third-party inference) is best for a single machine or a quick trial, but each user configures it and can change or remove it. To enforce it across a fleet, use MDM managed preferences, which push the AI Gateway configuration into the com.anthropic.claudefordesktop domain and lock it down.

Third-party mode replaces the first-party experience, and the user’s subscription plays no part in it. The app never signs in to claude.ai; inference is billed per token to the model account on the gateway (your Anthropic, Bedrock, or Vertex key). The Anthropic connector directory and claude.ai sync are unavailable, org connectors come from managed config instead. Who this suits:

• No Claude subscription: the clean case. Users need no Claude account; your API key pays.
• Enterprise: works, but the seat goes unused for everything inside Desktop. To keep seats paying, leave Desktop first-party and govern it with Anthropic Inference Hooks (guardrails and audit, no gateway cost tracking).
• Team, Pro, Max: works, but the person is already paying per user and you’d now pay API tokens as well. Rarely worth it; govern Desktop with aitori instead unless the user doesn’t need the subscription for anything else.

Prerequisites

Before you configure Claude Desktop, ensure you have:

1. TrueFoundry account, Create a TrueFoundry account and follow Gateway quick start. You need your gateway base URL (see Gateway base URL) and a TrueFoundry API key.
2. Models on the AI Gateway, Add the Claude models you plan to use via TrueFoundry (Anthropic direct, Bedrock, or Vertex). See Anthropic model integration. For Cowork, include Opus, Sonnet, and Haiku so primary chats and sub-agents can resolve cleanly (details below).
3. Claude Desktop, Install from claude.com/download. For manual setup, launch the app but do not sign in until you have opened the configuration window (Anthropic recommends staying on the login screen).

Enable Developer Mode

The third-party inference UI is behind Developer Mode.

macOS: Menu bar → Help → Troubleshooting → Enable Developer Mode.

Windows: Application menu (top-left on the login screen) → Help → Troubleshooting → Enable Developer Mode.

Open the configuration window

Developer → Configure third-party inference.

You should see a sidebar with sections such as Connection, Sandbox & workspace, Connectors & extensions, and others. Work through Connection first, then Identity & Models as needed.

Connection, point Claude Desktop at TrueFoundry

1. Under Connection, choose Gateway (Anthropic-compatible).
2. Set Gateway base URL to your TrueFoundry AI Gateway URL.
3. Set Gateway API key to your TrueFoundry API key.
4. Set Gateway auth scheme to bearer (sends Authorization: Bearer <key>). Use x-api-key only if your deployment expects that header instead.
5. Gateway extra headers (optional), one Name: Value per line for tenant routing or metadata, for example X-TFY-METADATA: {"team":"platform"}.

Identity & Models

Per Anthropic’s configuration docs, the model list for gateway inference is optional: when you leave it empty, Cowork calls the AI Gateway’s GET /v1/models endpoint and builds the picker from the response. The TrueFoundry AI Gateway exposes this endpoint, so you can rely on auto-discovery.

It is still recommended to set the model list explicitly. When you configure it, the picker shows exactly the models you list instead of everything /v1/models returns. That helps you:

• Pin Haiku: Cowork’s built-in Explore sub-agent is configured to use Haiku for fast, read-only work. User-dispatched sub-agents in Cowork have also been observed to route through Haiku (anthropics/claude-code#47488). If discovery returns no Haiku id or several ambiguous Haiku variants, sub-agent calls can fail or behave unpredictably. Listing your-account/claude-haiku-4-5 (or your org’s equivalent) removes that ambiguity.
• Shorten the picker when discovery is noisy: /v1/models may list many ids. An explicit list is optional but handy when you want Cowork users to see only the models you intend for this deployment.

Add each model as provider-account/model-id (same strings you use in the TrueFoundry playground). Example (replace tfy-ai-anthropic with your Anthropic model account name in TrueFoundry):

[
  "tfy-ai-anthropic/claude-opus-4-6",
  "tfy-ai-anthropic/claude-sonnet-4-6",
  "tfy-ai-anthropic/claude-haiku-4-5"
]

The first entry is the default in the model picker.

Apply locally and relaunch

Click Apply locally. Claude Desktop writes the configuration and relaunches. On the sign-in screen you should see the option to start in Cowork on 3P using the profile you just built.

Enforce fleet-wide via MDM (managed preferences)

The per-user UI above is convenient but not enforceable. For managed fleets, Claude Desktop reads Cowork on 3P configuration from OS-native managed preferences in the com.anthropic.claudefordesktop domain, the same class of control as pushing managed-settings.json for Claude Code. Push these keys via your MDM (Jamf, Kandji, Mosyle, Intune, Group Policy) or write and lock them with a script.

Config locations

OS	Path
macOS	/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist
Windows	HKLM\SOFTWARE\Policies\Claude
Linux	Not supported (Claude Desktop 3P does not run on Linux)

Keys: every value is stored as a string; arrays and objects are JSON-encoded strings (see Anthropic’s Configuration reference).

Key	Value
inferenceProvider	gateway, activates third-party gateway mode
inferenceGatewayBaseUrl	Your TrueFoundry AI Gateway base URL
inferenceGatewayAuthScheme	bearer (sends Authorization: Bearer …) or x-api-key
inferenceGatewayApiKey	Your TrueFoundry API key / token
inferenceCustomHeaders	JSON object of extra headers on every request, e.g. tenant/metadata routing, or carrying the token in a custom header
modelDiscoveryEnabled	false to pin the picker to inferenceModels and stop the app calling the AI Gateway’s GET /v1/models
inferenceModels	JSON array pinning the model picker (recommended). Set modelDiscoveryEnabled to false alongside it so only these models are offered
managedMcpServers	JSON array of org MCP connectors, [{"name":"github","transport":"http","url":"https://<gateway>/<tenant>/mcp/github/server","oauth":true}]. transport is a flat string with url as its sibling; the nested {"type":…} form is Claude Code’s shape, not Desktop’s. See Govern MCP traffic
isLocalDevMcpEnabled	false to stop users adding their own local MCP servers alongside the managed ones. Defaults to true
disabledBuiltinTools	JSON array of built-in tools to turn off, e.g. ["WebSearch","WebFetch"]. See Web search
claudeAiImport	JSON object gating import of claude.ai history into the local session store. Off by default; see Enforce with MDM
toolSearchEnabled	true to load MCP tool schemas lazily instead of inlining every connector’s schema into each session. See Enforce with MDM

Custom headers. inferenceCustomHeaders is a JSON object attached to every inference request, use it for tenant routing or metadata (for example X-TFY-METADATA), or to carry the credential in a custom header such as X-TFY-API-KEY (the same header Claude Code sends via ANTHROPIC_CUSTOM_HEADERS). Any header emitted by a credential helper merges over these.

Example macOS plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>inferenceProvider</key>
  <string>gateway</string>
  <key>inferenceGatewayBaseUrl</key>
  <string>https://gateway.example.truefoundry.com/api/llm</string>
  <key>inferenceGatewayAuthScheme</key>
  <string>bearer</string>
  <key>inferenceGatewayApiKey</key>
  <string>YOUR_TFY_API_KEY</string>
  <key>inferenceCustomHeaders</key>
  <string>{"X-TFY-METADATA":"{\"team\":\"platform\"}"}</string>
  <key>modelDiscoveryEnabled</key>
  <string>false</string>
  <key>inferenceModels</key>
  <string>[{"name":"tfy-ai-anthropic/claude-opus-4-6","anthropicFamilyTier":"opus","isFamilyDefault":true}]</string>
</dict>
</plist>

Claude Desktop loads managed preferences at launch, so restart the app after the profile lands. Confirm what it picked up with Help → Troubleshooting → Copy Managed Configuration Report (secrets redacted).

TrueFoundry ships tfy-local-ai-setup to automate this end-to-end: it runs the device-login flow as the signed-in user, writes the managed preferences above (with the token in the X-TFY-API-KEY header), immutably locks the file, and refreshes on a schedule. Run it with --claude-desktop (and --desktop-header 'Name: Value' for extra custom headers). The same binary also manages Claude Code and Codex, and only configures tools that are actually installed, so you can safely push all flags to your whole fleet. Deployment scripts and the token-refresh model are on Enforce with MDM.

Org connectors and web search

In third-party mode the Anthropic connector directory is unavailable, so org MCP connectors reach Claude Desktop only through the managedMcpServers managed preference, a JSON-encoded array of {"name", "transport", "url", "oauth"} entries pointing at servers on the TrueFoundry MCP Gateway. The same mechanism is how you give Desktop a governed web search that works on every model, and how you disable the built-in one.

The full reference, entry shape, oauth vs headers, toolPolicy, isLocalDevMcpEnabled, the macOS write-ordering caveat, and web search setup, is on Govern MCP traffic.

Guardrails

In third-party mode every model request passes through the gateway, so gateway guardrails and request logs apply in full: input and output checks, PII, prompt injection, moderation, and audit, configured once on the gateway with nothing to set in Desktop. See Guardrails overview. MCP tool calls are governed separately through the MCP Gateway; see Govern MCP traffic.

If Desktop stays first-party on an Enterprise plan, Anthropic Inference Hooks send each prompt to the gateway for an allow/deny verdict before inference. That gives guardrails and audit on content, but no cost tracking, budgets, or routing, because the model call itself never reaches the gateway.

Verify the integration

1. Start a Cowork session and send a short test message.
2. In TrueFoundry, open AI Gateway → Analytics (see Analytics overview) and confirm requests appear for your API key and chosen model.
3. For configuration diagnostics, use Help → Troubleshooting → Copy Managed Configuration Report, it summarizes detected keys and whether gateway credentials validated (secrets redacted).

Code tab and Claude Code CLI

The Code tab inside Claude Desktop uses Claude Code on the host. Some Cowork settings do not yet mirror one-to-one into Code-tab sessions. For terminal or VS Code workflows with environment variables and settings.json, follow Claude Code.

FAQs

Can users bring their existing claude.ai conversations into third-party mode?

Yes. Claude Desktop has an Import from Claude wizard (Settings → Import & export → Import…) that copies claude.ai conversations and projects into the local session store, so users pick up where they left off and the replies are served by your gateway models. It is off by default and can only be turned on through the claudeAiImport managed preference, so it is part of the MDM rollout rather than something users enable themselves.

Two things to know before you enable it: on a claude.ai Team or Enterprise workspace, a workspace owner must also allow members to export their own data, and the import never includes uploaded file contents, only the messages that referenced them. Terminal Claude Code history is not covered.

The key reference, recommended posture, and caveats are under Enforce with MDM. Anthropic’s walkthrough: Import history from claude.ai.

After pointing Desktop at the gateway, the Connectors panel is empty and I can't add a custom connector

Expected. Third-party mode bypasses the claude.ai account UI, and that panel is where Anthropic’s connector directory lives. Connectors still work, just differently: remote MCP servers (HTTP/SSE) are admin-pushed through the managedMcpServers managed preference, each pointing at a server on the MCP Gateway, and users click Connect to sign in as themselves; local stdio MCP servers remain user-addable via claude_desktop_config.json while isLocalDevMcpEnabled is true. Claude Desktop doesn’t support MDM-managed and user-added remote servers at the same time, so push a complete catalog. See Govern MCP traffic.

My chats and projects disappeared when I switched Desktop to the gateway

They aren’t lost. Connecting to a gateway creates a new local profile; the earlier conversations are still in the user’s claude.ai account. To bring them across, enable the claudeAiImport managed key and users get an Import from Claude wizard. On a Team or Enterprise workspace an owner must also allow members to export their own data, and uploaded file contents never come across. See Enforce with MDM.

Desktop discovers models fine but every message fails with 401 Invalid bearer token

The 401 is from Anthropic, not the gateway. The Anthropic model account that Desktop’s models route to has no API key (or an invalid one), so the gateway forwarded Desktop’s TrueFoundry bearer to Anthropic, which rejected it. Add a valid API key to the model account. Desktop can’t use subscription passthrough, so the model account it uses must always hold a key.

Every Desktop session starts with tens of thousands of tokens of MCP tool schemas

By default Desktop inlines the full schema of every managed connector into each session. Turn on tool search with the toolSearchEnabled managed preference (a plain boolean, MDM-only, Desktop 1.21459.0+); Desktop then loads a tool’s schema only when it is first used. Setting ENABLE_TOOL_SEARCH yourself has no effect, because Desktop strips it from the session environment while toolSearchEnabled is unset. Pilot with one group first: enabling it adds the tool-search-tool-2025-10-19 beta and tool_reference blocks to requests, which pass through on Anthropic direct but may be filtered on other providers. See Enforce with MDM.

References

• Cowork on 3P, Installation and setup
• Cowork on 3P, Configuration reference
• Cowork on 3P, Using an LLM gateway
• Cowork on 3P, Web search and web fetch
• Cowork on 3P, Import history from claude.ai
• Install and configure Claude Cowork with third-party platforms