claude-docs-20260828T183740Z / documentation capture

What this read moved

1–10 of 10

third-party/claude-desktop/bootstrap Changed · +6 / -2 lines

from line 39

3939

4040Run the endpoint across multiple replicas or regions behind a load balancer. Do not rely on response caching for availability: responses are per-user and carry credentials (see the `Cache-Control: no-store` guidance under [Server responsibilities](#server-responsibilities)). If your configuration data lives in a database, a read replica of that store improves availability without caching responses.

4141

42A refetch that returns different values does **not** change the running session. The app keeps the configuration it launched with (inference credentials, egress allowlist, MCP servers, and renderer state such as the model picker all stay on the boot-time values) and applies the new response at the next app launch. Plan changes accordingly: when rotating an inference credential, keep the previous credential valid until your fleet has relaunched rather than expecting propagation within a refetch interval.

4343

44Claude Desktop 1.40609.0 and later enforce that restart. Once a background re-poll returns a changed response, the user can keep working for [`relaunchEnforcementHours`](/docs/third-party/claude-desktop/configuration#relaunchenforcementhours) (1 hour by default, at most 336 hours, or `0` to require the restart at once). After that the app blocks further use until it restarts, and it relaunches on its own once it has been idle for two minutes (no Claude task running and no keyboard or pointer input). Return `relaunchEnforcementHours` in the bootstrap response to change the window. The app reads it from the newest response, so changing it does not itself require a restart.

46When rotating an inference credential, keep the previous credential valid until your fleet has relaunched. For devices that are running, that is roughly the 30-minute re-poll interval plus the relaunch window. For devices that are off, it is their next launch.

4448## Server responsibilities

4549

4650Your bootstrap endpoint is a security boundary. The response can carry inference credentials, so an unauthenticated or under-authorized endpoint leaks those credentials to anyone who can reach the URL. Host it on your private network (VPC, corporate intranet, or behind your zero-trust access proxy) rather than the public internet; reachability from managed devices is sufficient.

from line 331

327331* Deployed through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux): delivered values are trusted without prompting, because the admin already made a device-level decision.

328332* Read from a local configuration file, or from user-scope registry policy: the dialog is shown by default.

329333

330The `trustBootstrapDelivery` key overrides the default in either direction, and the previous name `trustBootstrapLocalExec` is still accepted. The key is accepted from device management or the local configuration file only, never from the bootstrap response itself. When the rest of your configuration is a local file, set the key in that same file next to `bootstrapUrl`. Delivering only this key through device management makes the whole installation managed, and the app then ignores the local file entirely, including its `bootstrapUrl`.

334The `trustBootstrapDelivery` key overrides the default in either direction, and the previous name `trustBootstrapLocalExec` is accepted until October 7, 2026. The key is accepted from device management or the local configuration file only, never from the bootstrap response itself. When the rest of your configuration is a local file, set the key in that same file next to `bootstrapUrl`. Delivering only this key through device management makes the whole installation managed, and the app then ignores the local file entirely, including its `bootstrapUrl`.

331335

332336Consent gates only bootstrap-delivered values. The same keys delivered through device management apply without prompting. Versions that predate a key's availability ignore that key in a bootstrap response (the [configuration changelog](/docs/third-party/claude-desktop/configuration-changelog) records when each key became available), so a response can safely carry keys ahead of a fleet upgrade.

333337

third-party/claude-desktop/code Changed · +15 / -12 lines

from line 14

1414

1515These keys are passed directly to the Claude Code process as environment variables or launch options. They take effect on every Code session and cannot be overridden by user-level Claude Code settings or by a separately deployed `managed-settings.json`.

1616

17| Claude Desktop on 3P key | Effect in Code sessions |

18| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

19| `inferenceProvider` and all provider credential keys (`inferenceGateway*`, `inferenceVertex*`, `inferenceBedrock*`, `inferenceFoundry*`, `inferenceCredentialHelper*`) | Selects the inference backend and supplies credentials. Code sessions use the same provider, endpoint, and credentials as Cowork sessions. |

20| `inferenceModels` | Populates the model picker. The first entry is the default for new Code sessions. |

21| `autoModeEnabled` | Offers **Auto mode** in the Code session's permission selector. A separately deployed Claude Code managed-settings file that sets `disableAutoMode` to `"disable"` overrides this and keeps Auto mode hidden; see below. |

22| `disabledBuiltinTools` | Removes the listed tools from Code sessions. Tools your provider does not support, such as WebSearch on Amazon Bedrock, are removed automatically in addition to your list. |

23| `builtinToolPolicy` | Tools set to `"ask"` require approval on each call in Code sessions, enforced via a PreToolUse hook and Claude Code `permissions.ask` rules. |

24| `managedMcpServers` | Makes the same managed MCP servers available in Code sessions. The app handles the connection and authentication; the Code session sees only the resulting tool list. |

25| `otlpEndpoint`, `otlpProtocol`, `otlpHeaders`, `otlpResourceAttributes` | Routes Claude Code's OpenTelemetry metrics and logs to your collector. See [Telemetry](/docs/third-party/claude-desktop/telemetry). |

26| `disableEssentialTelemetry`, `disableNonessentialTelemetry` | Disables Claude Code's crash reporting and usage telemetry to Anthropic, mirroring Cowork. |

27| `disableAutoUpdates` | The embedded Claude Code engine never self-updates regardless of this key; its version is managed by the app's own updater. |

28| `inferenceMaxTokensPerWindow`, `inferenceTokenWindowHours` | The token budget is shared across Cowork and Code sessions and enforced before each turn. |

17| Claude Desktop on 3P key | Effect in Code sessions |

20| `inferenceModels` | Populates the model picker. The first entry is the default for new Code sessions. |

23| `builtinToolPolicy` | Tools set to `"ask"` require approval on each call in Code sessions, enforced via a PreToolUse hook and Claude Code `permissions.ask` rules. |

24| `skipWebFetchPreflight` | Turns off Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch) against `api.anthropic.com`. A separately deployed Claude Code managed-settings file that sets `skipWebFetchPreflight` takes precedence. |

25| `managedMcpServers` | Makes the same managed MCP servers available in Code sessions. The app handles the connection and authentication; the Code session sees only the resulting tool list. |

26| `mcpToolTimeoutSec` | Applies your per-call MCP tool timeout to Code sessions as well, taking precedence over a user-set `MCP_TOOL_TIMEOUT`. |

27| `organizationInstructions` | Appended to the Code session's system prompt after Claude Code's own. `CLAUDE.md` instructions still apply. |

28| `otlpEndpoint`, `otlpProtocol`, `otlpHeaders`, `otlpResourceAttributes` | Routes Claude Code's OpenTelemetry metrics and logs to your collector. See [Telemetry](/docs/third-party/claude-desktop/telemetry). |

29| `disableEssentialTelemetry`, `disableNonessentialTelemetry` | Disables Claude Code's crash reporting and usage telemetry to Anthropic, mirroring Cowork. |

30| `disableAutoUpdates` | The embedded Claude Code engine never self-updates regardless of this key; its version is managed by the app's own updater. |

31| `inferenceMaxTokensPerWindow`, `inferenceTokenWindowHours` | The token budget is shared across Cowork and Code sessions and enforced before each turn. |

2932

3033### Applied as managed policy

3134

third-party/claude-desktop/configuration Changed · +8 / -8 lines

from line 191

191191

192192 **The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`:

193193

194 ```yaml theme={null}

194 ```yaml theme={null} theme={null}

195195 # LiteLLM example — `audience` is REQUIRED, not optional

196196 general_settings:

197197 litellm_jwtauth:

from line 247

247247

248248 **Extended context** (`supports1m`) is a capability assertion you make about your deployment; only set it for models you've confirmed support the 1M-token window:

249249

250 ```json theme={null}

250 ```json theme={null} theme={null}

251251 [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"]

252252 ```

253253

from line 255

255255

256256 **Default to 1M context** (`prefer1m`) makes the 1M-context variant the default picker selection when this entry is the default model (the first entry); users can still switch to the standard variant, and an explicit user pick is always kept. No effect without `supports1m`. Under dynamic discovery (no explicit list), the equivalent flat key in the **Models** group applies instead:

257257

258 ```json theme={null}

258 ```json theme={null} theme={null}

259259 [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}]

260260 ```

261261

262262 **Display label** (`labelOverride`) is for IDs the picker can't derive a friendly name from (Bedrock ARNs, gateway routing aliases). Display-only; `name` is still what the app sends:

263263

264 ```json theme={null}

264 ```json theme={null} theme={null}

265265 [{"name": "arn:aws:bedrock:us-east-1:123:application-inference-profile/abc", "labelOverride": "Claude Opus (Prod)"}]

266266 ```

267267

268268 **Tier mapping** (`anthropicFamilyTier`) tells the app which Claude tier (`haiku`/`sonnet`/`opus`/`fable`/`mythos`) an entry stands in for, so bare tier aliases (e.g. in Code sessions) resolve to your model. `isFamilyDefault: true` picks the winner when several entries share a tier:

269269

270 ```json theme={null}

270 ```json theme={null} theme={null}

271271 [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}]

272272 ```

273273

from line 292

292292 <Accordion title="inferenceModelPricing details">

293293 Each row replaces Anthropic list price for one model in the Usage page's estimate, in USD per million tokens (`inputPerMtok`, `outputPerMtok`, `cacheReadPerMtok`, `cacheWritePerMtok` — all four required; `cacheWritePerMtok` prices both 5-minute and 1-hour cache writes); any row also turns the estimate on. Mirrors Claude Code's managed `modelPricing.overrides`, and `name` is matched the same way: a built-in Claude model ID (e.g. `claude-sonnet-4-6`, or its Bedrock, Vertex, or Foundry ID) covers every dated and provider spelling of that model; any other value — a gateway alias, an inference-profile ARN — matches that exact ID only (case-insensitive) and wins over a built-in row. An ID Claude Code cannot map to a Claude model at all gets no estimate until a row here prices it. `inferenceModelPricingMultiplier` still applies on top of a row.

294294

295 ```json theme={null}

295 ```json theme={null} theme={null}

296296 {"inferenceModelPricingEnabled": true, "inferenceModelPricingMultiplier": 0.9, "inferenceModelPricing": [{"name": "claude-sonnet-4-6", "inputPerMtok": 2.4, "outputPerMtok": 12, "cacheReadPerMtok": 0.24, "cacheWritePerMtok": 3}]}

297297 ```

298298

from line 828

828828 <Accordion title="orgPluginSettings details">

829829 Locks per-tool permissions on MCP servers that arrive via the org-plugins directory — one entry per server name:

830830

831 ```json theme={null}

831 ```json theme={null} theme={null}

832832 [{"serverName": "internal-search", "tools": [{"toolName": "delete_document", "permission": "blocked"}]}]

833833 ```

834834

from line 959

959959* `"ask"` — the user approves every call; no session-scoped or standing grants are offered.

960960* `"blocked"` — the tool is removed from Claude's session; connector settings show it as blocked by your organization.

961961

962Tools with no policy entry stay user-controlled (built-in connectors apply default policies to some tools — see the reference above): the user is prompted and can approve once, approve for the rest of the task (offered for tools that can modify data), or grant a standing approval unless [`mcpPersistentAlwaysAllowEnabled`](#mcppersistentalwaysallowenabled) is `false`. Full prompt options require version 1.22209.0 or later; earlier third-party builds offered only per-call approval. The reference above also lists an `"ask-session"` value; it is accepted for compatibility and behaves exactly as `"ask"`. Managed policies take precedence over user grants, and enforcement happens in the desktop host process, not only in the prompt UI. A deny-by-default posture — `"*": "blocked"` plus exact `"allow"` entries for approved tools — is supported, including in Code sessions (where an allowed tool still gets Claude Code's own approval prompt). See the [`managedMcpServers` reference](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults.

962Tools with no policy entry stay user-controlled (built-in connectors apply default policies to some tools — see the reference above): the user is prompted and can approve once, approve for the rest of the task (offered for tools that can modify data), or grant a standing approval unless [`mcpPersistentAlwaysAllowEnabled`](#mcppersistentalwaysallowenabled) is `false`. Full prompt options require version 1.22209.0 or later; earlier third-party builds offered only per-call approval. The reference above also lists an `"ask-session"` value, which behaves exactly as `"ask"` and is accepted until October 7, 2026. After that date the app rejects an entry that uses it, so write `"ask"`. Managed policies take precedence over user grants, and enforcement happens in the desktop host process, not only in the prompt UI. A deny-by-default posture — `"*": "blocked"` plus exact `"allow"` entries for approved tools — is supported, including in Code sessions (where an allowed tool still gets Claude Code's own approval prompt). See the [`managedMcpServers` reference](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults.

963963

third-party/claude-desktop/connectors-m365 Changed · +9 / -9 lines

from line 191

191191 }

192192 ```

193193

194 | Field | Required | Description |

195 | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

196 | `name` | Yes | Unique display name, shown to users in connector settings. |

197 | `server` | Yes | Must be `microsoft365`. Built-in entries use this field instead of `url`, `transport`, or `command`; an entry that mixes `server` with those fields is rejected. |

198 | `clientId` | Yes | The Application (client) ID of the local-mode app from step 1. |

199 | `tenantId` | Yes | Your Directory (tenant) ID. |

200 | `azureCloud` | No | `global` (default), `us-gov-high`, or `us-gov-dod`. Selects the Microsoft Entra and Microsoft Graph hosts for US Government clouds. |

201 | `scope` | No | Space-separated delegated Graph scopes to request instead of the default read set. A string array named `scopes` is also accepted. See [Configure scopes](#configure-scopes). |

202 | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |

194 | Field | Required | Description |

196 | `name` | Yes | Unique display name, shown to users in connector settings. |

197 | `server` | Yes | Must be `microsoft365`. Built-in entries use this field instead of `url`, `transport`, or `command`; an entry that mixes `server` with those fields is rejected. |

198 | `clientId` | Yes | The Application (client) ID of the local-mode app from step 1. |

199 | `tenantId` | Yes | Your Directory (tenant) ID. |

200 | `azureCloud` | No | `global` (default), `us-gov-high`, or `us-gov-dod`. Selects the Microsoft Entra and Microsoft Graph hosts for US Government clouds. |

201 | `scope` | No | Space-separated delegated Graph scopes to request instead of the default read set. A string array named `scopes` is also accepted until October 7, 2026. See [Configure scopes](#configure-scopes). |

202 | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |

203203

204204 The server ships inside the app, so nothing else needs to be installed on the device, and it activates only from managed configuration; users cannot add it themselves. Deploy the configuration through your device-management tool as usual.

205205 </Step>

third-party/claude-desktop/extensions Changed · +16 / -14 lines

from line 235

235235

236236Claude Desktop fetches marketplaces on the host operating system, outside the Cowork VM. The credential is used only for this fetch and is never passed into the VM or exposed to the model.

237237

238| `credentialKind` | How it authenticates |

239| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

240| `"anonymous"` | No credential is sent. Use for public repositories or unauthenticated file hosts. |

241| `"userGit"` | Uses the git credential helpers already configured for the signed-in OS user (for example, `git-credential-manager`, macOS Keychain, or a GitHub CLI credential helper). Use when each user already has read access through their own account. For `url` sources, the same credential is sent as HTTP Basic on the manifest and archive requests. |

242| `"credentialHelper"` | Runs the executable at `credentialHelper` and uses its trimmed stdout as the HTTPS password with username `x-access-token`. For `url` sources, the token is sent as `Authorization: Bearer <token>` on the manifest and archive requests. Follows the same stdout contract as an [inference credential helper](/docs/third-party/claude-desktop/credential-helper). |

243| `"inferenceCredential"` | `url` sources only. Sends the same `Authorization` bearer that Claude Desktop already sends to your inference gateway, so a marketplace hosted on the gateway is private to signed-in members without a separate credential. Works for [gateway single sign-on](/docs/third-party/claude-desktop/gateway#single-sign-on-with-your-identity-provider), a [credential helper](/docs/third-party/claude-desktop/credential-helper), and bearer-scheme API keys. Claude Desktop sends the credential only when the marketplace URL is on the same origin as `inferenceGatewayBaseUrl`. Until the user has signed in, or when the deployment sends the API key as `x-api-key` rather than a bearer, nothing is sent and the entry reports why in the diagnostic report. |

238| `credentialKind` | How it authenticates |

240| `"anonymous"` | No credential is sent. Use for public repositories or unauthenticated file hosts. |

242| `"credentialHelper"` | Runs the executable at `credentialHelper`. If it prints a bare token, the token is used as the git password for username `x-access-token` (accepted by GitHub, GitLab, and Azure DevOps) and, for `url` sources, sent as `Authorization: Bearer <token>` on the manifest and archive requests. For hosts that need a particular username, print git-credential lines `username=<user>` and `password=<token>` instead (for example `x-token-auth` for Bitbucket Data Center access tokens, or `gitlab+deploy-token-N` for a GitLab deploy token); `url` sources then use HTTP Basic. Print `authtype=Bearer` and `credential=<token>` to force a bearer header. Unlike an inference credential helper, it does not accept JSON output. Username forms require Claude Desktop 1.37937.0 or later. Otherwise follows the execution model of an [inference credential helper](/docs/third-party/claude-desktop/credential-helper). |

243| `"inferenceCredential"` | `url` sources only. Sends the credentials Claude Desktop already sends to your inference gateway or to your [bootstrap server](/docs/third-party/claude-desktop/bootstrap), so a marketplace hosted on either is private to signed-in members without a separate credential. On the gateway's origin it sends the same `Authorization` bearer as inference and works for [gateway single sign-on](/docs/third-party/claude-desktop/gateway#single-sign-on-with-your-identity-provider), a [credential helper](/docs/third-party/claude-desktop/credential-helper), and bearer-scheme API keys. On the bootstrap server's origin (Claude Desktop 1.37937.0 or later) it sends the bootstrap sign-in token or your `bootstrapHeaders` and `bootstrapHeadersHelper` headers. Claude Desktop sends a credential only when the marketplace URL is on one of those two origins. When there is nothing to send yet (no sign-in held and no bootstrap headers configured, or a gateway API key sent as `x-api-key` rather than a bearer), no request is made and the entry reports why in the diagnostic report. |

244244

245245Because the fetch happens on the host, the marketplace host does not need to be on the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) allowlist. It does need to be reachable from end-user devices.

246246

from line 352

352352

353353Admins can restrict or disable each user-extension surface independently via managed configuration:

354354

355| Key | Default | Effect when `false` |

356| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |

357| `isLocalDevMcpEnabled` | `true` | Users cannot add their own local MCP servers from **Settings → Developer**. |

358| `isDesktopExtensionEnabled` | `false` | Desktop extensions (`.mcpb`) bundled in plugins are not loaded. Set to `true` to allow them. |

359| `isDesktopExtensionSignatureRequired` | `false` | (When `true`) Unsigned `.mcpb` extensions are rejected. |

360| `skillCreationEnabled` | `true` | Users cannot create or upload skills in the app. Claude does not offer to create or update skills in conversations. |

355| Key | Default | Effect when `false` |

356| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

357| `isLocalDevMcpEnabled` | `true` | Users cannot add their own local MCP servers from **Settings → Developer**. |

358| `isDesktopExtensionEnabled` | `false` | Desktop extensions (`.mcpb`) bundled in plugins are not loaded. Set to `true` to allow them. |

359| `isDesktopExtensionSignatureRequired` | `false` | (When `true`) Unsigned `.mcpb` extensions are rejected. |

360| `skillCreationEnabled` | `true` | Users cannot create or upload skills in the app. Claude does not offer to create or update skills in conversations. |

361| `userPluginMarketplacesEnabled` | `true` | Users cannot add plugin marketplaces of their own; the add-marketplace options are hidden. Marketplaces you provision with `allowedPluginMarketplaces` are unaffected. Requires Claude Desktop 1.37937.0 or later. |

362| `userPluginUploadsEnabled` | `true` | Users cannot upload plugin files or create plugins with Claude; every in-app option for adding a plugin of their own is hidden. Plugins from your marketplaces and the organization plugins directory are unaffected. Requires Claude Desktop 1.37937.0 or later. |

361363

362Setting `isLocalDevMcpEnabled` to `false` and leaving `isDesktopExtensionEnabled` at `false` restricts MCP servers and connectors to those delivered through `managedMcpServers` and `org-plugins/`. Setting [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) to `false` turns off skill creation and upload in the app. Skills already on the device keep working, as do skills from [organization plugins](#organization-plugins-admin). Users can still install plugins regardless of these settings. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete example.

364Setting `isLocalDevMcpEnabled` to `false` and leaving `isDesktopExtensionEnabled` at `false` restricts MCP servers and connectors to those delivered through `managedMcpServers` and `org-plugins/`. Setting [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) to `false` turns off skill creation and upload in the app. Skills already on the device keep working, as do skills from [organization plugins](#organization-plugins-admin). Users can still install plugins from the marketplaces you provision regardless of these settings. Setting `userPluginMarketplacesEnabled` and `userPluginUploadsEnabled` to `false` removes only the options for adding marketplaces and plugins of their own, and anything a user added earlier stays in place. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete example.

363365

364366## Related topics

365367

third-party/claude-desktop/gateway Changed · +3 / -3 lines

from line 187

187187

188188 **The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`:

189189

190 ```yaml theme={null}

190 ```yaml theme={null} theme={null}

191191 # LiteLLM example — `audience` is REQUIRED, not optional

192192 general_settings:

193193 litellm_jwtauth:

from line 258

258258<string>{"issuer":"https://YOUR_ORG.okta.com","clientId":"YOUR_CLIENT_ID","redirectPort":53180}</string>

259259```

260260

261Earlier app versions used `inferenceGatewayAuthScheme: "sso"` to select this mode. That value is deprecated; set `inferenceCredentialKind: "interactive"` instead. Existing deployments that still send `inferenceGatewayAuthScheme: "sso"` continue to work until October 7, 2026. After that date the value no longer selects browser sign-in, so set `inferenceCredentialKind: "interactive"` before then.

262262

263263### Models

264264

from line 283

283283To turn tool search on for Claude Desktop, set the [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) configuration key. Requires app version 1.21459.0 or later.

284284

285285<Warning>

286 Setting `toolSearchEnabled` causes sessions to send experimental `anthropic-beta` request headers, and the beta request fields that ride with them, to your gateway. Enable it only if your gateway forwards and accepts those headers and fields; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks. As a preflight, run terminal Claude Code through the same gateway with `ENABLE_TOOL_SEARCH=true`: Claude Desktop sends the same request surface, so if the terminal works, Claude Desktop will too. Enabling the key also re-enables Claude Code's other experimental beta features for these sessions. Do not enable it on [Vertex](/docs/third-party/claude-desktop/vertex) deployments: Vertex rejects the tool-search beta header.

286 Setting `toolSearchEnabled` causes sessions to send experimental request headers and fields to your gateway. On Claude Desktop 1.40609.0 and later this is only the tool-search request shape (the `tool-search-tool-2025-10-19` value in the `anthropic-beta` header, deferred tool loading, and `tool_reference` content blocks); every other experimental Claude Code beta stays off. Earlier versions instead lift the experimental-beta suppression for these sessions, so requests also carry Claude Code's other experimental beta headers and fields. Enable it only if your gateway forwards and accepts what it will receive; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks.

287287</Warning>

288288

289289## Troubleshoot

third-party/claude-desktop/telemetry Changed · +10 / -9 lines

from line 249

249249

250250### Optional features

251251

252| Host | Required when |

253| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

254| Host of `otlpEndpoint` | OpenTelemetry export is configured |

255| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled |

256| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured |

257| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured |

258| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured |

259| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set), including on devices installed with the offline installer |

252| Host | Required when |

254| Host of `otlpEndpoint` | OpenTelemetry export is configured |

255| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled |

256| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured |

258| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured |

259| `api.anthropic.com` | [Code](/docs/third-party/claude-desktop/code) sessions can use Web Fetch and [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch)) |

260| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set), including on devices installed with the offline installer |

260261

261262## Disabling all Anthropic-bound connections

262263

263With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. The only required egress is `downloads.claude.ai` (for the VM bundle at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. Enabling [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) adds `downloads.claude.ai` back for every device, because the offline installer does not include the remote-session components.

264With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code) sessions otherwise checks each fetched domain with `api.anthropic.com`. The only required egress is `downloads.claude.ai` (for the VM bundle at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. Enabling [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) adds `downloads.claude.ai` back for every device, because the offline installer does not include the remote-session components.

264265

265266These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page.

266267

third-party/claude-desktop/web-tools Changed · +19 / -17 lines

from line 13

1313

1414Web Search is a **server-side tool** executed by your inference provider, not by the desktop app. Availability depends on which provider you've configured:

1515

16| Provider | Web Search |

17| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

18| Google Cloud's Agent Platform | Available |

19| Microsoft Foundry | Available on deployments [hosted on Anthropic](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) only; for deployments hosted on Azure, use the [built-in web search](#built-in-web-search) below |

20| Amazon Bedrock | Not available natively; use the [built-in web search](#built-in-web-search) below |

21| Anthropic API | Available |

22| Gateway | Available if your gateway implements Anthropic's `web_search` server tool, passes it through to a provider that does, or runs the search itself; see [Gateway-side search](#gateway-side-search) |

16| Provider | Web Search |

18| Google Cloud's Agent Platform | Available |

19| Microsoft Foundry | Available on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) |

20| Amazon Bedrock | Not available natively; use the [built-in web search](#built-in-web-search) below |

21| Anthropic API | Available |

2323

24On Microsoft Foundry, Web Search availability depends on the [hosting option](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) you chose when you deployed the model. Deployments hosted on Azure do not support server-side tools, including web search, and return an error for requests that use them. See [features not supported when hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) in the Claude in Microsoft Foundry documentation for the full list. For those deployments, configure the [built-in web search](#built-in-web-search) instead. Once it is configured, the app stops offering provider-side search and routes the model's search calls to the built-in server. If you want no web search at all, add `"WebSearch"` to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) instead. That entry also blocks the built-in web search tool, so do not combine the two.

24On Microsoft Foundry, Web Search works on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) with no additional configuration. Deployments hosted on Azure support only the basic web search tool version (`web_search_20250305`), which is the version Claude Desktop uses; see [features not supported when hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) in the Claude in Microsoft Foundry documentation for what else differs when hosted on Azure. On any provider you can configure the [built-in web search](#built-in-web-search) to choose the search backend yourself. Once it is configured, the app stops offering provider-side search and routes the model's search calls to the built-in server. If you want no web search at all, add `"WebSearch"` to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) instead. That entry also blocks the built-in web search tool, so do not combine the two.

2525

26The [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) passes the `web_search` tool through to its upstream provider, so Web Search works in Claude Desktop behind that gateway when the upstream is Google Cloud's Agent Platform, a Microsoft Foundry deployment hosted on Anthropic, or the Anthropic API. Claude Desktop can't see which upstream the gateway routes to and offers the tool regardless, so if the gateway routes any model to Amazon Bedrock or to a Microsoft Foundry deployment hosted on Azure, configure the [built-in web search](#built-in-web-search), which replaces provider-side search on every route. To turn web search off instead, add `"WebSearch"` to `disabledBuiltinTools` in the gateway's [Claude Desktop overlay](https://code.claude.com/docs/en/claude-apps-gateway-config#claude-desktop-overlay). That entry also blocks the built-in web search tool if one is configured.

26The [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) passes the `web_search` tool through to its upstream provider, so Web Search works in Claude Desktop behind that gateway when the upstream is Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API. Claude Desktop can't see which upstream the gateway routes to and offers the tool regardless, so if the gateway routes any model to Amazon Bedrock, configure the [built-in web search](#built-in-web-search), which replaces provider-side search on every route. To turn web search off instead, add `"WebSearch"` to `disabledBuiltinTools` in the gateway's [Claude Desktop overlay](https://code.claude.com/docs/en/claude-apps-gateway-config#claude-desktop-overlay). That entry also blocks the built-in web search tool if one is configured.

2727

2828Provider-side search runs on the provider's infrastructure, so queries and results travel over the same path as model inference and are subject to your provider's data-handling terms. It needs no additional firewall rules beyond the inference endpoint itself.

2929

from line 33

3333

3434### Web search options

3535

36If your inference provider supports native search (Google Cloud's Agent Platform, or a Microsoft Foundry deployment hosted on Anthropic), that's the simplest path and no additional configuration is required. Use the built-in `websearch` server when your provider has no native search (Amazon Bedrock, a Microsoft Foundry deployment hosted on Azure, or a custom gateway), or with any provider when you want to choose the search backend.

36If your inference provider supports native search (Google Cloud's Agent Platform or Microsoft Foundry), that's the simplest path and no additional configuration is required. Use the built-in `websearch` server when your provider has no native search (Amazon Bedrock or a custom gateway), or with any provider when you want to choose the search backend.

3737

39| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------------- |

41| [Built-in](#built-in-web-search) | Amazon Bedrock, Microsoft Foundry (hosted on Azure), or a custom gateway; or any provider when you want to choose the search backend | `managedMcpServers` | Brave, Tavily, Exa, or your own server |

39| ------------------------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------- |

4444

4545#### Provider-native search

4646

47Google Cloud's Agent Platform grounding and Microsoft Foundry deployments hosted on Anthropic both execute search inside the model call. There's nothing to configure in Claude Desktop. Any setup happens on the cloud provider's side. Amazon Bedrock and Microsoft Foundry deployments hosted on Azure have no native equivalent (Amazon Bedrock AgentCore is a remote MCP server; see [Remote search MCP](#remote-search-mcp)).

47Google Cloud's Agent Platform grounding and Microsoft Foundry both execute search inside the model call. There's nothing to configure in Claude Desktop. Any setup happens on the cloud provider's side. Amazon Bedrock has no native equivalent (Amazon Bedrock AgentCore is a remote MCP server; see [Remote search MCP](#remote-search-mcp)).

4848

4949#### Built-in web search

5050

from line 147

147147</Note>

148148

149149The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool.

150

151In [Code](/docs/third-party/claude-desktop/code) sessions, Claude Code's Web Fetch tool also asks `api.anthropic.com` whether each domain is on Anthropic's blocklist before fetching, and refuses the fetch if that lookup cannot complete. If your devices cannot reach `api.anthropic.com`, or you do not want fetched hostnames sent there, set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true`. The key requires Claude Desktop 1.37937.0 or later. Cowork sessions do not perform this lookup.

150152

151153## Disabling web tools

152154

third-party/claude-desktop/feature-matrix Changed · +1 / -1 lines

from line 47

4747| Claude Tag | ✓ | — |

4848| Computer use | — | — |

4949

50§ Amazon Bedrock deployments, Microsoft Foundry deployments [hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), and gateways that do not forward Anthropic server tools need a web search provider configured first; see [Web search options](/docs/third-party/claude-desktop/web-tools#web-search-options).

50§ Amazon Bedrock deployments and gateways that do not forward Anthropic server tools need a web search provider configured first; see [Web search options](/docs/third-party/claude-desktop/web-tools#web-search-options).

5151

5252† Memory in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Users can review, delete, or pause it under **Settings → Cowork → Memory**; see [Memory](/docs/third-party/claude-desktop/data-storage#memory). Chat-history search and nightly summary generation are not available in Chat on 3P.

5353

third-party/claude-desktop/overview Changed · +1 / -1 lines

from line 70

7070

7171Because inference runs in your cloud tenant, Claude Desktop on 3P operates inside whatever compliance boundary your provider and region give you. The desktop application itself contacts Anthropic-operated hosts only to download the VM workspace bundle and Claude CLI binary (always required), and for crash reporting, product analytics, non-essential services (connector favicons, artifact previews, and MCP Apps widgets), and auto-updates. Each of the latter four can be disabled independently via managed configuration.

7272

73With Anthropic-bound telemetry, non-essential services, and updates all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM bundle at session start. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the full set of network paths and how to lock them down.

73With Anthropic-bound telemetry, non-essential services, and updates all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM bundle at session start. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code) sessions otherwise checks each fetched domain with `api.anthropic.com`. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the full set of network paths and how to lock them down.

7474

7575## HIPAA

7676