> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude Desktop & Cowork
> Connect Claude Desktop (Cowork on third-party inference) to the TrueFoundry AI Gateway.
[Claude Desktop](https://claude.com/download) can run in **Cowork on third-party (3P)** mode: the app routes inference to a gateway that implements the Anthropic [Messages API](https://docs.claude.com/en/api/messages) instead of signing in to claude.ai. The TrueFoundry AI Gateway is compatible with this mode.
For more details, see Anthropic’s [Installation and setup](https://claude.com/docs/cowork/3p/installation), [Configuration reference](https://claude.com/docs/cowork/3p/configuration), [Using an LLM gateway](https://claude.com/docs/cowork/3p/gateway), and the Help Center article [Install and configure Claude Cowork with third-party platforms](https://support.claude.com/en/articles/14680741-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](#enforce-fleet-wide-via-mdm-managed-preferences)**, which push the AI Gateway configuration into the `com.anthropic.claudefordesktop` domain and lock it down — the Claude Desktop equivalent of pushing `managed-settings.json` for [Claude Code](/docs/ai-gateway/claude-code).
## Prerequisites
Before you configure Claude Desktop, ensure you have:
1. **TrueFoundry account** — Create a [TrueFoundry account](https://www.truefoundry.com/register) and follow [Gateway quick start](/docs/ai-gateway/quick-start). You need your gateway base URL (see [Gateway base URL](/docs/ai-gateway/quick-start#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](/docs/ai-gateway/anthropic). 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](https://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 `). 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](https://docs.claude.com/en/docs/claude-code/sub-agents) 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](https://github.com/anthropics/claude-code/issues/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):
```json theme={"dark"}
[
"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//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](https://claude.com/docs/cowork/3p/configuration)).
| 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:////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 [Org connectors](#org-connectors-managedmcpservers) |
| `isLocalDevMcpEnabled` | `false` to stop users adding their own local MCP servers alongside the managed ones. Defaults to `true` |
| `claudeAiImport` | JSON object gating **[import of claude.ai history](#faqs)** — `enabled` lets users import a claude.ai export and earlier sessions on the machine, `bannerBehavior` (`off`, `detect`, `show`) controls the import prompt, and `exportEnabled` adds session export to a zip (no effect unless `enabled`). Everything is off by default, e.g. `{"enabled":true}`. Reaches the app via MDM on Claude Desktop **1.25927.0+**; earlier builds read this key only from a bootstrap server |
**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 theme={"dark"}
inferenceProvider
gateway
inferenceGatewayBaseUrl
https://gateway.example.truefoundry.com/api/llm
inferenceGatewayAuthScheme
bearer
inferenceGatewayApiKey
YOUR_TFY_API_KEY
inferenceCustomHeaders
{"X-TFY-METADATA":"{\"team\":\"platform\"}"}
modelDiscoveryEnabled
false
inferenceModels
[{"name":"tfy-ai-anthropic/claude-opus-4-6","anthropicFamilyTier":"opus","isFamilyDefault":true}]
```
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`](https://github.com/truefoundry/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 — see [Govern all AI traffic through the AI Gateway](/docs/ai-gateway/govern-traffic-through-ai-gateway). It only configures tools that are actually installed: an explicit flag for a tool that isn't present is skipped with a warning, and a machine with none of the three is a clean no-op (no login prompt) — so you can safely push all flags to your whole fleet.
## Org connectors (`managedMcpServers`)
In third-party mode the Anthropic connector directory is unavailable, so org connectors reach Claude Desktop **only** through the `managedMcpServers` managed preference. Point each entry at a server registered on the [TrueFoundry MCP Gateway](/docs/ai-gateway/mcp/mcp-overview) — the value is a JSON-encoded **array**:
```json theme={"dark"}
[
{
"name": "github",
"transport": "http",
"url": "https:////mcp/github/server",
"oauth": true
}
]
```
* **`oauth: true` needs no `clientId` and no pre-registered redirect URI.** Claude registers itself against the AI Gateway's authorization server through dynamic client registration, then each user clicks **Connect** and signs in as themselves — so tool calls are attributed per user instead of sharing one fleet-wide token.
* **Managed servers are listed, not connected.** They appear under **Customize → Connectors** with a **Connect** button.
* **Leave `toolPolicy` out** unless you are naming real tool names (`"create_issue": "allow"`). Its keys are individual tools, not patterns — an undocumented `{"*": "allow"}` risks the whole entry being rejected.
* **Connectors ride on the inference block.** If `inferenceProvider` is not `gateway`, the app is in first-party mode and ignores the entire managed configuration, connectors included — an empty pane with no error.
To roll this out fleet-wide alongside the inference keys, use the deployment scripts in [Enterprise security with MDM](/docs/ai-gateway/mcp/enterprise-security-claude#deployment-scripts) — they write the Claude Desktop array and the Claude Code `managed-mcp.json` from one connector list, then read both back to confirm they landed.
**macOS ordering.** `tfy-local-ai-setup` rewrites and re-locks the whole managed-preferences plist on each run, so `managedMcpServers` has to be re-applied *after* the binary on every run — not once at provisioning time. On Windows the values are written individually under `HKLM\SOFTWARE\Policies\Claude` and survive, but write them with `New-ItemProperty`: `reg add` strips the double quotes out of a JSON value and leaves the connectors pane empty.
## Web search
Claude Desktop's **Web Search** is a *server-side* tool — the app doesn't run the search itself, it asks the inference endpoint to. When Claude Desktop points at the TrueFoundry AI Gateway, there are two ways to satisfy it, and you can use both:
* **Provider-native passthrough** — the AI Gateway forwards Anthropic's `web_search` server tool to whichever provider serves the model. Available for every provider that supports it.
* **MCP web search** *(recommended for consistency across providers)* — search runs through an MCP server instead of the model provider, so it behaves the same no matter which model the request lands on.
### Provider-native passthrough
Claude Desktop emits Anthropic's `web_search_20250305` server tool. The AI Gateway passes it straight through to the model's provider (the request tool and the `web_search_tool_result` blocks in the response, plus the `num_search_queries` usage counter for billing) — there's **nothing extra to configure in Claude Desktop** beyond pointing it at the gateway.
The catch is that it only works when the routed model's provider actually executes the Anthropic web-search server tool (for example, the Anthropic API). A model whose provider doesn't run it will simply not return search results. Because that varies by provider, use the MCP option below when you want web search to work uniformly across every model in your picker.
### MCP web search (consistent across providers)
Add a web-search MCP server to Claude Desktop's [`managedMcpServers`](https://claude.com/docs/third-party/claude-desktop/configuration). Because the search executes at the MCP server rather than the model provider, it works on **every** model routed through the AI Gateway.
Point a remote `managedMcpServers` entry at a web-search MCP server running behind the [TrueFoundry MCP Gateway](/docs/ai-gateway/mcp/mcp-overview) — for example [Tavily](/docs/ai-gateway/mcp/tavily-mcp-server) or [Exa](/docs/ai-gateway/mcp/exa-mcp-server). This keeps the search key and tool access **server-side and centrally governed** (auth, allow-listing, and audit through TrueFoundry) instead of shipping a vendor key to every device:
```json theme={"dark"}
{
"managedMcpServers": [
{
"name": "web-search",
"transport": "http",
"url": "https:////mcp//server",
"oauth": true
}
]
}
```
Replace `` with the slug of the server you registered on the gateway (for example `tavily` or `exa`); `name` is just the local label Claude Desktop shows. `oauth: true` has each user sign in as themselves — the alternative is `headers` with the **same TrueFoundry token you use for inference**, or `headersHelper` pointing at a script that prints it, which keeps the token out of the config file but makes every search look like one shared identity. To auto-approve tools so users aren't prompted per query, add a `toolPolicy` naming the server's **real tool names** (`{"search": "allow"}`); a `{"*": "allow"}` wildcard is undocumented and risks the entry being dropped. See [Connect an MCP server from your IDE / client](/docs/ai-gateway/mcp/connect-mcp-from-ide) for the "Sign in with TrueFoundry" OAuth flow and the gateway MCP URL format.
Web Search returns links; **Web Fetch** (retrieving a page's contents) runs on the device and is gated by the `coworkEgressAllowedHosts` allowlist. If you want Claude to open the pages it finds, add those hosts to `coworkEgressAllowedHosts` (or set it to `["*"]`). See Anthropic's [Web search and web fetch](https://claude.com/docs/third-party/claude-desktop/web-tools) reference.
To enforce web search fleet-wide, push the same `managedMcpServers` value through [MDM managed preferences](#enforce-fleet-wide-via-mdm-managed-preferences) as a JSON-encoded string, alongside the connection keys above.
### Disabling web search
To turn off Claude Desktop's built-in web search — for example to block model-side web access, or to allow only the governed MCP server above — add `WebSearch` to `disabledBuiltinTools`:
```json theme={"dark"}
{
"disabledBuiltinTools": ["WebSearch"]
}
```
Add `"WebFetch"` to the same array to also block Claude from fetching page contents. In an MDM managed-preferences profile this value is stored as a **JSON-encoded string** (like the other array keys above), for example `"[\"WebSearch\"]"`.
## Verify the integration
1. Start a Cowork session and send a short test message.
2. In TrueFoundry, open **AI Gateway** → **Analytics** (see [Analytics overview](/docs/ai-gateway/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](/docs/ai-gateway/claude-code) and [Claude Code Max](/docs/ai-gateway/claude-code-max).
## FAQs
Yes. Claude Desktop has an **Import from Claude** wizard that copies claude.ai conversations and projects into the local session store, so users can pick up work they started on claude.ai and continue it against the TrueFoundry AI Gateway. It also picks up Cowork and Claude Code sessions already on the machine from an earlier **Claude Desktop** install.
**Import is off by default.** Users only get the wizard once the managed configuration sets `claudeAiImport` with `enabled` set to `true` (see [MDM managed preferences](#enforce-fleet-wide-via-mdm-managed-preferences) — like the other object-valued keys it is stored as a JSON-encoded string, e.g. `{"enabled":true}`). Two sibling subfields tune it, and neither does anything while `enabled` is `false`: `bannerBehavior` (`off`, `detect`, `show`) decides whether new chats and tasks prompt users to import, and `exportEnabled` adds the export half described below. MDM delivery of this key needs Claude Desktop **1.25927.0 or later** — earlier builds accept it only from a bootstrap server.
**On a claude.ai Team or Enterprise workspace**, a workspace owner must first allow members to export their own data, under claude.ai **Settings → Organization → Data and privacy → Allow members to export their own data**. Personal claude.ai accounts can always export. The toggle only lets each member download their own history.
**Running the import** — in Claude Desktop, go to **Settings → Import & export** → **Import…**. The wizard has three steps, any of which can be skipped:
1. **Chats** — either **Sign in to claude.ai…** and click **Fetch export**, or on claude.ai use **Settings → Privacy → Export data** and select the emailed `.zip` with **Choose file…**. The email download link expires after **24 hours**. The sign-in path has the app authorize against claude.ai and download the export itself, so the device needs egress to claude.ai for that step — on a locked-down or air-gapped fleet, the `.zip` path is the one that works.
2. **Cowork & Code** — local sessions found on this machine, with a time range and the option to add another folder (a backup, or one copied from another machine). Sessions are **copied, not moved**.
3. **Review** — confirm, then **Import**. A **Duplicates** step follows if an imported project name collides with an existing one, offering **Merge into existing** or **Keep separate**.
**Inference still comes from the AI Gateway.** The first time a user sends a message in an imported conversation, Claude Desktop shows a **Resume imported session?** prompt — **Trust and resume** continues the chat, and the reply is served by your configured gateway model, not by claude.ai. Because the imported transcript is replayed as context on that first turn, a long claude.ai chat can produce a large prompt: make sure the models you pin in the picker have enough context for the transcripts users bring over, and expect those requests in **AI Gateway → Analytics** like any other.
**What doesn't come over:** file contents. A member's own export never includes files uploaded to a project's knowledge base or attached to a conversation — that's a claude.ai security policy and applies to both import paths. The messages that referenced an attachment are imported; the file isn't. Only an organization-level export, which a workspace owner requests, includes file contents.
**It's a one-time copy, not a sync.** New claude.ai activity doesn't show up unless the user imports again, and re-running the import matches and skips what's already there rather than creating duplicates.
**Moving sessions between devices:** with `exportEnabled` also set to `true` under `claudeAiImport`, **Settings → Import & export** offers **Export…**, which writes this machine's chats, Cowork tasks, and Code sessions to a zip that the wizard can read on another device in step 2. The zip holds full conversation content — treat it as sensitive data.
**Terminal Claude Code history is not covered.** "Code sessions" throughout this wizard means Claude Desktop's **Code** tab. There is no Claude-Code-specific import key — Claude Code rides inside `claudeAiImport` — and neither half reaches the CLI: step 2 only finds sessions left by an earlier Claude Desktop install, and the export explicitly excludes terminal Claude Code sessions. A developer's own `~/.claude` history (`%USERPROFILE%\.claude` on Windows) stays where it is, and no managed key brings it over, so don't plan a CLI history migration around this flag. The similarly named `isClaudeCodeForDesktopEnabled` gates whether the **Code** tab appears at all and has nothing to do with import.
Full details in Anthropic's [Import history from claude.ai](https://claude.com/docs/third-party/claude-desktop/import).
## References
* [Cowork on 3P — Installation and setup](https://claude.com/docs/cowork/3p/installation)
* [Cowork on 3P — Configuration reference](https://claude.com/docs/cowork/3p/configuration)
* [Cowork on 3P — Using an LLM gateway](https://claude.com/docs/cowork/3p/gateway)
* [Cowork on 3P — Web search and web fetch](https://claude.com/docs/third-party/claude-desktop/web-tools)
* [Cowork on 3P — Import history from claude.ai](https://claude.com/docs/third-party/claude-desktop/import)
* [Install and configure Claude Cowork with third-party platforms](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.