Home Docs Claude Documentation 17 Aug 2026

One change · claude-docs

Configuration reference changedthird-party/claude-desktop/configuration

Nearest release: v2.1.234, published 2 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here 17 Aug 2026 20:37 UTC

Lines+59added

Lines−57removed

From line 73 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits54to this page, all time

The whole hunk

from line 73, old and new numbered

lines

from line 73

7373

7474## Connection

7575

77| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| Custom inference headers `inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra HTTP headers sent on every inference request to the configured provider. For tenant routing, org IDs, Bedrock Guardrails, etc. Previously named `inferenceGatewayHeaders`. |

83| Re-run helper for silent refresh `inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. |

78| Custom inference headers `inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders`. |

8787

8888<AccordionGroup>

8989 <Accordion title="inferenceCustomHeaders details">

9090 Sent on every inference and model-discovery request (joined into the CLI's `ANTHROPIC_CUSTOM_HEADERS`).

9191

92 Use this for fleet-wide constants. For per-user or per-session values, have the **credential helper script** emit JSON with a `headers` field; those are merged over these static entries (helper wins on conflict).

92 Use this for fleet-wide, non-secret constants. **Do not put API keys, bearer tokens or other credentials here** — this map is stored and distributed as plain configuration. For tokens, and for per-user or per-session values, have the **credential helper script** emit JSON with a `headers` field; those are merged over these static entries (helper wins on conflict).

9393 </Accordion>

9494

9595 <Accordion title="inferenceCredentialHelper details">

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} theme={null} theme={null} theme={null} theme={null}

194 ```yaml theme={null}

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

196196 general_settings:

197197 litellm_jwtauth:

from line 244

244244

245245 **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:

246246

247 ```json theme={null} theme={null} theme={null} theme={null} theme={null}

247 ```json theme={null}

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

249249 ```

250250

251251 **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:

252252

253 ```json theme={null} theme={null} theme={null} theme={null} theme={null}

253 ```json theme={null}

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

255255 ```

256256

257257 **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:

258258

259 ```json theme={null} theme={null} theme={null} theme={null} theme={null}

259 ```json theme={null}

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

261261 ```

262262

263263 **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:

264264

265 ```json theme={null} theme={null} theme={null} theme={null} theme={null}

265 ```json theme={null}

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

267267 ```

268268

from line 279

279279

280280### Vertex

281281

283| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |

290| Vertex OAuth login hint `inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. |

296296

297297<AccordionGroup>

298298 <Accordion title="inferenceVertexWorkforceAuthFlow details">

from line 372

372372 </Accordion>

373373

374374 <Accordion title="builtinToolPolicy details">

375 `ask-session` applies to connector tool policies only — written here it is treated as `ask`. To remove a tool entirely, use **Disabled built-in tools** instead.

375 `ask-session` is accepted for compatibility and treated as `ask`. To remove a tool entirely, use **Disabled built-in tools** instead.

376376 </Accordion>

377377

378378 <Accordion title="autoModeEnabled details">

from line 412

412412

413413 Accepts exact hostnames (`api.github.com`), wildcards (`*.corp.com` matches subdomains at any depth — `docs.corp.com` and `a.b.corp.com` both match), and `*` to allow all. `*.corp.com` does not match `corp.com` itself; add both if you need the apex. IP addresses only match when listed exactly — wildcards never match IP addresses, so an unlisted IP destination is blocked. `localhost` and private-network addresses are blocked in the sandbox's web fetch regardless of this list; shell commands and package installs run inside a network sandbox that can only reach hosts on this list (plus your inference provider's endpoints). With `*`, the network sandbox is disabled and web fetch still blocks private addresses.

414414

415 Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting that entry to the named port; an entry with no port allows any port. A port on a wildcard applies to every matched subdomain. IPv6 literals are not supported. Entries outside this grammar are dropped individually, with a warning naming the entry in the app log; the remaining valid entries keep working. Port restrictions are enforced for the Cowork sandbox's web fetch today. The sandbox's shell and package-install egress enforces them once the app ships a VM image whose sandbox runtime supports ports; until then a port-scoped host is unreachable from shell (fails closed). Plugin CLIs additionally keep their own stricter in-VM filter and treat port-scoped entries as absent for now. In Code sessions, the Claude Code translation treats a port-restricted entry as its bare host (any port). The `:port` syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying port-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds); on older builds a port-scoped entry invalidates the sandbox's whole shell and package-install allowlist for the session (the older sandbox runtime rejects the entire list), and web fetch simply never matches it.

415 Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting that entry to the named port; an entry with no port allows any port. A port on a wildcard applies to every matched subdomain. IPv6 literals are not supported. Entries outside this grammar are dropped individually, with a warning naming the entry in the app log; the remaining valid entries keep working. Port restrictions are enforced for the Cowork sandbox's web fetch and for its shell and package-install egress. Plugin CLIs additionally keep their own stricter in-VM filter and treat port-scoped entries as absent for now. In Code sessions, the Claude Code translation treats a port-restricted entry as its bare host (any port). The `:port` syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying port-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds); on older builds a port-scoped entry invalidates the sandbox's whole shell and package-install allowlist for the session (the older sandbox runtime rejects the entire list), and web fetch simply never matches it.

416416

417417 Hosts you add here also need to be open on your network firewall, on the listed ports. See **Egress Requirements** for the full allowlist.

418418 </Accordion>

from line 420

420420

421421## Connectors

422422

424| ----------------------------------------------------------------------- | -------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |

426426

427427<AccordionGroup>

428428 <Accordion title="claudeAiImport details">

430430 | ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

432433 | `bannerBehavior` | `enum` | — | Prompt to import at the top of a new chat or task. `detect`: only when earlier Claude sessions are found on this computer. `show`: always. Hidden when unset. One of: `off`, `detect`, `show`. |

433434 </Accordion>

434435</AccordionGroup>

from line 465

464465 <Accordion title="managedMcpServers details">

465466 For OAuth-authenticated entries, the app builds the redirect URI as `http://<callbackHost>:<callbackPort>/callback`; register that exact value with the OAuth provider. Tokens refresh automatically during a session, so users aren't interrupted when the initial access token expires.

466467

467 `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, forwarded `blocked`/`ask` wildcard rules take precedence over a less strict exact key, and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), and a wildcard `ask-session` key likewise keeps every matching tool on the ask-session clamp, even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > ask-session > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"ask-session"` requires approval on the tool's first use per session; a session-scoped **Allow for this task** covers the rest of that session, a new session re-prompts, and persistent always-allow stays unavailable. Scheduled tasks do not honor ask-session grants: every run prompts and blocks until attended, exactly as `ask` (use `allow` for tools that must run unattended). `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked`/`ask`/`ask-session` are forwarded as Claude Code permission rules (`ask-session` as an ask rule, with the once-per-session behavior applied by the desktop); `allow` is not.

468 `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, a forwarded `ask` wildcard rule, or a `blocked` wildcard other than the bare `"*"`, takes precedence over a less strict exact key (the deny-by-default form, `"*": "blocked"` plus exact `"allow"` entries, is honored in Code sessions too), and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"ask-session"` is accepted for compatibility and behaves exactly as `"ask"`. `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked` and `ask` (including `ask-session`) are forwarded as Claude Code permission rules; `allow` is not.

468469

469470 For the bundled Microsoft 365 connector, the send tools (`outlook_send_mail`, `outlook_send_draft`, `outlook_forward_mail`, `outlook_create_event`, `outlook_update_event`, `teams_send_chat_message`, `teams_send_channel_message`, `teams_reply_channel_message`) cannot be loosened below `ask` — an `allow` setting resolves to `ask`.

470471

from line 478

477478 | `azureCloud` | `enum` | — | Microsoft cloud for sign-in and Graph. Leave as global for commercial Microsoft 365; US Government clouds require your own app registration (Client ID). One of: `global`, `us-gov-high`, `us-gov-dod`. |

485 | `provider` | `enum` | — | Runs search from the desktop, for inference providers without native web search. Supply the provider’s API key through the headers helper script below. One of: `brave`, `tavily`, `exa`, `custom`. |

485486 | `customUrl` | `string` | — | POST endpoint accepting \{q} JSON and returning a results\[] array. Only used when provider is Custom. |

from line 587

586587| --------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

from line 695

694695

695696## Plugins

696697

698| ------------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |

699| ------------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

701702

702703<AccordionGroup>

703704 <Accordion title="orgPluginSettings details">

704705 Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form:

705706

706 ```json theme={null} theme={null} theme={null} theme={null} theme={null}

707 ```json theme={null}

707708 {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}}

708709 ```

709710

from line 719

718719 </Accordion>

719720

720721 <Accordion title="allowedPluginMarketplaces details">

722 | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |

725 | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch. |

731 | `url` | `string` | — | HTTPS Git remote URL for the marketplace repository. |

723 | ------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

726 | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch. |

730 | `credentialKind` | `enum` | — | How fetches authenticate: anonymously, with the user’s git credentials, via a helper executable, or as inference does (url sources the gateway hosts). One of: `anonymous`, `userGit`, `credentialHelper`, `inferenceCredential`. |

732 | `url` | `string` | — | HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url). |

732734 </Accordion>

733735</AccordionGroup>

734736

This page’s history 54 edits

23 Oct 2026 +49 −47
22 Oct 2026 +3296 −789
22 Oct 2026 +20 −20
22 Oct 2026 +456 −373
20 Oct 2026 +5 −5
20 Oct 2026 +1064 −1114

The page’s own history →

Where it came from

The captureclaude-docs
Upstream pageclaude.com

Around it

Every changethe ledger
That day17 Aug 2026