Configuration reference changedthird-party/claude-desktop/configuration
Nearest release: v2.1.314, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 30 Oct 2026 02:48 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 30 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+814added
Lines−814removed
From line
171
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits67to this page, all time
The whole hunk
from line 171, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 171
171171
172172One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`
173173
174> **More detail**
174> [accordion] More detail
175175>
176176> The app opens in third-party mode unless the user chose to sign in to Claude.ai at the login screen. `disableDeploymentModeChooser` removes that choice.
177177>
from line 219
219219
220220**Custom inference headers.** Extra headers sent with every model request. Routing and tenant headers only: do not put credentials here.
221221
222> **More detail**
222> [accordion] More detail
223223>
224224> This key is stored and distributed as plain configuration. For tokens, and for values that differ per user or session, have `inferenceCredentialHelper` print JSON with a `headers` field. On a conflict, the helper script's header takes priority.
225225
from line 235
235235
236236**Helper script.** Absolute path to an executable that prints the credential, optionally with per-request headers.
237237
238> **More detail**
238> [accordion] More detail
239239>
240240> The helper script must exit with code `0`. Its standard output must hold only one of these, with no banners, prompts or log lines:
241241>
from line 268
268268
269269**Helper script arguments.** Arguments passed to the helper script, one per entry, in order. Leave unset to run it with none.
270270
271> **More detail**
271> [accordion] More detail
272272>
273273> Do not put secrets in arguments: the diagnostic report and other processes on the device can see them.
274274>
from line 326
326326
327327[Admin Console](#the-works-with-column): Not available.
328328
329> **More detail**
329> [accordion] More detail
330330>
331331> This sets a route. It is not a network access control. If the proxy is unreachable, requests fail instead of connecting directly.
332332>
from line 352
352352
353353[Admin Console](#the-works-with-column): Not available.
354354
355> **More detail**
355> [accordion] More detail
356356>
357357> If the PAC file cannot be downloaded, the app connects directly. On macOS and Windows, the Cowork workspace VM gets its own copy at each start. If that download fails, the VM connects directly until it next starts, with no warning. Block direct connections on your network if that is unacceptable.
358358>
from line 370
370370
371371**Enable IPv6 in the workspace VM.** Give the Cowork workspace VM an IPv6 address so Claude’s tools can reach IPv6-only hosts through the device. macOS and Windows only.
372372
373> **More detail**
373> [accordion] More detail
374374>
375375> IPv6 works in the VM only where the device's own IPv6 works.
376376>
from line 434
434434>
435435> * Use inferenceIdpAuthFlow together with inferenceIdpOidc once every desktop in the fleet is on a release that reads them. The original spelling will keep working; no end date has been set.
436436
437> **More detail**
437> [accordion] More detail
438438>
439439> * **`browser`:** register the redirect URI `http://127.0.0.1:<port>/callback` with your identity provider (for Entra, `http://127.0.0.1/callback`).
440440> * **`broker`:** uses Web Account Manager on Windows or Company Portal on macOS, and does not work on Linux. It can satisfy Conditional Access policies that require a compliant or managed device, or token protection.
from line 461
461461
462462[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/gateway.md#single-sign-on-with-your-identity-provider)
463463
464> **More detail**
464> [accordion] More detail
465465>
466466> Used with `inferenceCredentialKind` set to `interactive`. Leave it unset for a gateway that runs its own sign-in and serves `<baseUrl>/.well-known/oauth-authorization-server`.
467467>
from line 469
469469>
470470> Register the redirect URI given under `inferenceGatewayOidcAuthFlow`.
471471
472> **Child attributes (11)**
472> [accordion] Child attributes (11)
473473>
474474> **clientId** `string` *required*
475475>
from line 493
493493>
494494> One of: `id_token` (default), `access_token`
495495>
496> > **More detail**
496> > [accordion] More detail
497497> >
498498> > An ID token's audience (`aud`) is `clientId`. An access token's audience must be your gateway or proxy.
499499> >
from line 503
503503>
504504> Space-separated scopes. Access-token mode needs the gateway or proxy API scope, and adds offline\_access unless Append offline\_access is off.
505505>
506> > **More detail**
506> > [accordion] More detail
507507> >
508508> > In ID-token mode, `offline_access` is not added to scopes that you set. Include it yourself, or users sign in again each time the token expires.
509509>
from line 511
511511>
512512> In access-token mode, add offline\_access to scopes so the identity provider returns a refresh token for silent refresh.
513513>
514> > **More detail**
514> > [accordion] More detail
515515> >
516516> > Turn off only if your authorization server rejects `offline_access` as an unknown scope. Then add the server’s own refresh-token scope to `scopes`.
517517>
from line 519
519519>
520520> Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier. Leave unset for Entra ID.
521521>
522> > **More detail**
522> > [accordion] More detail
523523> >
524524> > Use it only with `bearerTokenType` set to `access_token`, and only if your identity provider supports RFC 8707. Changing it signs users in again.
525525> >
from line 539
539539>
540540> Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
541541>
542> > **More detail**
542> > [accordion] More detail
543543> >
544544> > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
545545
from line 553
553553
554554One of: `browser`, `broker`
555555
556> **More detail**
556> [accordion] More detail
557557>
558558> * **`browser`:** register the redirect URI `http://127.0.0.1:<port>/callback` with your identity provider (for Entra, `http://127.0.0.1/callback`).
559559> * **`broker`:** uses Web Account Manager on Windows or Company Portal on macOS, and does not work on Linux. It can satisfy Conditional Access policies that require a compliant or managed device, or token protection.
from line 572
572572
573573**Identity provider (OIDC).** Your organization’s OpenID Connect identity provider. The user’s token is sent as the Bearer credential to the gateway or the Bedrock proxy.
574574
575> **More detail**
575> [accordion] More detail
576576>
577577> Used when `inferenceCredentialKind` is `external-idp`. Register the redirect URI given under `inferenceIdpAuthFlow` with your identity provider.
578578>
from line 580
580580>
581581> On Bedrock, set `inferenceBedrockBaseUrl` to a proxy that checks the token, because Amazon Bedrock itself does not accept it. Also list your models in `inferenceModels`.
582582
583> **Child attributes (11)**
583> [accordion] Child attributes (11)
584584>
585585> **clientId** `string` *required*
586586>
from line 604
604604>
605605> One of: `id_token` (default), `access_token`
606606>
607> > **More detail**
607> > [accordion] More detail
608608> >
609609> > An ID token's audience (`aud`) is `clientId`. An access token's audience must be your gateway or proxy.
610610> >
from line 614
614614>
615615> Space-separated scopes. Access-token mode needs the gateway or proxy API scope, and adds offline\_access unless Append offline\_access is off.
616616>
617> > **More detail**
617> > [accordion] More detail
618618> >
619619> > In ID-token mode, `offline_access` is not added to scopes that you set. Include it yourself, or users sign in again each time the token expires.
620620>
from line 622
622622>
623623> In access-token mode, add offline\_access to scopes so the identity provider returns a refresh token for silent refresh.
624624>
625> > **More detail**
625> > [accordion] More detail
626626> >
627627> > Turn off only if your authorization server rejects `offline_access` as an unknown scope. Then add the server’s own refresh-token scope to `scopes`.
628628>
from line 630
630630>
631631> Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier. Leave unset for Entra ID.
632632>
633> > **More detail**
633> > [accordion] More detail
634634> >
635635> > Use it only with `bearerTokenType` set to `access_token`, and only if your identity provider supports RFC 8707. Changing it signs users in again.
636636> >
from line 650
650650>
651651> Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
652652>
653> > **More detail**
653> > [accordion] More detail
654654> >
655655> > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
656656
from line 662
662662
663663**Stream idle timeout.** Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300.
664664
665> **More detail**
665> [accordion] More detail
666666>
667667> With pings arriving (SSE `ping` events or `:` comment lines), sessions accept at least about five minutes of them, then wait this many seconds more. With no pings, a silent response still fails after about 5 minutes whatever this value, so make the gateway send them.
668668>
from line 914
914914
915915One of: `browser`, `broker`
916916
917> **More detail**
917> [accordion] More detail
918918>
919919> * **`browser`:** register the redirect URI `http://127.0.0.1:<port>/callback` with your identity provider (for Entra, `http://127.0.0.1/callback`).
920920> * **`broker`:** uses Web Account Manager on Windows or Company Portal on macOS, and does not work on Linux. It can satisfy Conditional Access policies that require a compliant or managed device, or token protection.
from line 933
933933
934934**Workforce Identity IdP (OIDC).** Your organization’s OpenID Connect identity provider. Users sign in there, and the app exchanges their ID token at GCP STS.
935935
936> **Child attributes (9)**
936> [accordion] Child attributes (9)
937937>
938938> **clientId** `string` *required*
939939>
from line 973
973973>
974974> Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
975975>
976> > **More detail**
976> > [accordion] More detail
977977> >
978978> > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
979979
from line 1017
10171017
10181018**Azure AI Foundry base URL.** Full base URL for a gateway or proxy in front of Foundry, path included (replaces [https://RESOURCE.services.ai.azure.com/anthropic](https://RESOURCE.services.ai.azure.com/anthropic)).
10191019
1020> **More detail**
1020> [accordion] More detail
10211021>
10221022> Point it only at a gateway or proxy that you run. Requests carry the credential that the app would send to Foundry: the user's Entra ID token, the API key or the helper script's output.
10231023>
from line 1067
10671067
10681068One of: `device-code`, `browser`, `broker`
10691069
1070> **More detail**
1070> [accordion] More detail
10711071>
10721072> * **`device-code`:** shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled.
10731073> * **`browser`:** register `http://127.0.0.1/callback` under **Mobile and desktop applications**. It works with **Allow public client flows** disabled. Conditional Access policies that block device-code sign-in do not affect it.
from line 1083
10831083
10841084**Model discovery.** Auto-populate the model picker from the provider at launch.
10851085
1086> **More detail**
1086> [accordion] More detail
10871087>
10881088> Turn this off if your network cannot reach your inference provider's model-list endpoint.
10891089>
from line 1098
10981098
10991099**Use 1M wherever it’s available.** Every model that offers 1M context shows only its 1M option in the model picker.
11001100
1101> **More detail**
1101> [accordion] More detail
11021102>
11031103> A listed model offers 1M when its `inferenceModels` entry sets `supports1m`. Without a list, a model offers 1M when your gateway's model list marks it.
11041104
from line 1110
11101110
11111111**Model list.** Override the auto-discovered model list. First entry is the default.
11121112
1113> **More detail**
1113> [accordion] More detail
11141114>
11151115> Each entry is a model ID string or an object:
11161116>
from line 1131
11311131>
11321132> For Auto mode on a gateway, also list `claude-sonnet-5`. Its safety classifier calls that ID by default (see `autoModeEnabled`).
11331133
1134> **Child attributes (8)**
1134> [accordion] Child attributes (8)
11351135>
11361136> **name** `string` *required*
11371137>
from line 1163
11631163>
11641164> The Claude model behind an ID that the app cannot identify, such as a gateway alias. The ID gets that model’s effort levels and limits.
11651165>
1166> > **More detail**
1166> > [accordion] More detail
11671167> >
11681168> > Enter a Claude model ID such as `claude-sonnet-5`. Region prefixes, dates and upper case are fine. A family name without `claude-`, such as `sonnet-5`, is ignored. The model picker also ignores a model that Claude Desktop does not know.
11691169> >
from line 1185
11851185
11861186One of: `low`, `medium`, `high`, `xhigh`, `max`
11871187
1188> **More detail**
1188> [accordion] More detail
11891189>
11901190> * A user's own effort choice for that model still applies, unless `alwaysStartWithDefaultModel` is on.
11911191> * A level that the model does not offer becomes the nearest lower level, or its lowest if none is lower.
from line 1209
12091209
12101210**Show estimated cost.** Show an estimated cost on the Usage page, at Anthropic list price unless you set a multiplier or per-model rates.
12111211
1212> **More detail**
1212> [accordion] More detail
12131213>
12141214> The estimate is in USD. `inferenceModelPricingMultiplier` and `inferenceModelPricing` adjust it, and are ignored while this is off.
12151215>
from line 1233
12331233
12341234**Model pricing.** Per-model rates replacing Anthropic list price in the Usage page’s estimate.
12351235
1236> **Child attributes (5)**
1236> [accordion] Child attributes (5)
12371237>
12381238> **name** `string` *required*
12391239>
from line 1265
12651265
12661266[Admin Console](#the-works-with-column): Not available.
12671267
1268> **More detail**
1268> [accordion] More detail
12691269>
12701270> On unless set to `false`. The app fetches Anthropic's signed catalog from `downloads.claude.ai`, or from `modelCatalogUrl` if that is set. The catalog never changes which models are offered, their order or the default model.
12711271>
from line 1281
12811281
12821282[Admin Console](#the-works-with-column): Not available.
12831283
1284> **More detail**
1284> [accordion] More detail
12851285>
12861286> Mirror two Anthropic files unchanged: `https://downloads.claude.ai/model-catalog/v1/catalog.json` and its signature file. The app looks for the signature at this URL with `.raw-sig.json` added to the path.
12871287>
from line 1325
13251325
13261326[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md)
13271327
1328> **More detail**
1328> [accordion] More detail
13291329>
13301330> The app forwards the session's inference credential to the SSH host, plus your collector endpoint and auth headers when `otlpEndpoint` is set. List only hosts you trust with those.
13311331>
from line 1350
13501350
13511351[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md)
13521352
1353> **More detail**
1353> [accordion] More detail
13541354>
13551355> The app never runs another `ssh` in its place. If the program is missing, too old or cannot run, SSH sessions fail. So deliver this key only to devices that have the program.
13561356>
from line 1374
13741374
13751375[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md)
13761376
1377> **More detail**
1377> [accordion] More detail
13781378>
13791379> With `system-openssh`, your OpenSSH client's own Kerberos, certificate and `ssh_config` support applies. See `sshClientPath` for which program runs.
13801380>
from line 1401
14011401
14021402One of: `standard`, `off`
14031403
1404> **More detail**
1404> [accordion] More detail
14051405>
14061406> `standard` turns on Unified Claude. `off` turns Chat and Cowork off, which leaves only Code, or nothing where Code is off. `isClaudeCodeForDesktopEnabled` still decides Code.
14071407>
from line 1417
14171417
14181418**Advanced file analysis.** Allow Claude to run code in a local sandbox to analyze attached files it can’t read natively — like Excel and PowerPoint.
14191419
1420> **More detail**
1420> [accordion] More detail
14211421>
14221422> Of the user's files, the sandbox can read only those attached to the conversation and folders added to the chat's project through the app (read-only).
14231423>
from line 1437
14371437
14381438[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/web-tools.md#web-fetch)
14391439
1440> **More detail**
1440> [accordion] More detail
14411441>
14421442> Does not cover web search, model requests or MCP servers.
14431443>
from line 1455
14551455
14561456**Allowed workspace folders.** Folders that Claude can use in chat projects, Cowork and Code. Code’s shell commands are only partly limited. Unset: all folders.
14571457
1458> **More detail**
1458> [accordion] More detail
14591459>
14601460> Claude can read and write in every listed folder unless its `mode` is `ro`. An empty list allows none.
14611461>
from line 1464
14641464>
14651465> Do not list a home folder: it holds SSH keys and shell start-up files.
14661466
1467> **Child attributes (3)**
1467> [accordion] Child attributes (3)
14681468>
14691469> **path** `string` *required*
14701470>
from line 1480
14801480>
14811481> One of: `rw`, `ro`
14821482>
1483> > **More detail**
1483> > [accordion] More detail
14841484> >
14851485> > * **Code on the device:** Claude's file tools cannot change the folder. Shell commands still can.
14861486> > * **Code over SSH:** the same, but shell commands are partly limited where Claude Code's sandbox runs on the host. Nothing is enforced on Windows hosts.
from line 1495
14951495
14961496**Block reads outside working directories.** Keep Claude’s file tools from reading outside a Code session’s working directories. Shell commands are only partly limited.
14971497
1498> **More detail**
1498> [accordion] More detail
14991499>
15001500> * **File tools** refuse most reads outside the session folder and any `allowedWorkspaceFolders`, in every permission mode.
15011501> * **Shell commands:** where Claude Code's sandbox runs (see `allowedWorkspaceFolders`), most reads in the home folder and other user folders are refused. Elsewhere such reads ask for approval.
from line 1513
15131513
15141514**Allow Auto mode.** Offer Auto mode, where Claude decides which actions need approval. Unset: in Code only. True adds Cowork.
15151515
1516> **More detail**
1516> [accordion] More detail
15171517>
15181518> Unless it is `false`, new Code sessions normally start in Auto mode.
15191519>
from line 1543
15431543
15441544**Allow user-created skills.** Let users create and upload their own skills, and let Claude save skills. Skill files added outside the app are not blocked.
15451545
1546> **More detail**
1546> [accordion] More detail
15471547>
15481548> Skills already on the device stay usable. Plugins from your organization and bundled skills are not affected. To turn off bundled skills, use `disableBundledSkills`.
15491549
from line 1561
15611561
15621562[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/skill-scanning.md)
15631563
1564> **More detail**
1564> [accordion] More detail
15651565>
15661566> How well the scan catches unsafe skills depends on your model. A skill judged possibly unsafe becomes usable, with a caution. Scan tokens count toward the user's usage and token limit.
15671567>
from line 1583
15831583
15841584**Allow user-added plugin marketplaces.** Let users add plugin marketplaces. When off, the app hides the ones your organization did not add and normally does not load their plugins.
15851585
1586> **More detail**
1586> [accordion] More detail
15871587>
15881588> Nothing is deleted: turning it back on restores the hidden marketplaces.
15891589>
from line 1600
16001600
16011601**Allow user-added plugins.** Allow users to add their own plugins. When off, the app hides every option for adding one and refuses uploads.
16021602
1603> **More detail**
1603> [accordion] More detail
16041604>
16051605> Plugins that are already installed, or placed on disk outside the app, are not removed or blocked.
16061606>
from line 1614
16141614
16151615**Allow scheduled tasks.** Allow scheduled tasks in Cowork and Code. When off, scheduling is hidden, existing tasks stop running and Claude cannot create new ones.
16161616
1617> **More detail**
1617> [accordion] More detail
16181618>
16191619> Existing tasks are kept, not deleted, and run again when this is turned back on. While off, sessions also start without Claude Code's own scheduling tools, such as the `/loop` command.
16201620
from line 1626
16261626
16271627**Allow projects.** Let users group chats and Cowork tasks into projects. When off, projects are hidden, not deleted.
16281628
1629> **More detail**
1629> [accordion] More detail
16301630>
16311631> Turning this off only hides projects. Their tasks and chats stay in the list, ungrouped. Their data stays on the user's device, and they come back when you turn it on again.
16321632>
from line 1648
16481648
16491649**Allow Developer Mode.** Let users turn on Developer Mode. When off, the app’s developer tools and the option to install an unpacked extension are unavailable.
16501650
1651> **More detail**
1651> [accordion] More detail
16521652>
16531653> Unpacked extensions that are already installed keep working. An extension folder copied by hand into the app's extensions folder is not blocked. Packaged (`.mcpb`) extensions follow `isDesktopExtensionEnabled`, not this key.
16541654
from line 1660
16601660
16611661**Default Quick Entry shortcut.** Set the shortcut that opens Quick Entry, such as Ctrl+Alt+K, for users who haven’t set their own in Settings. Use “off” for no shortcut.
16621662
1663> **More detail**
1663> [accordion] More detail
16641664>
16651665> Unset keeps the built-in shortcut: double-tap Option on macOS, `Ctrl+Alt+Space` elsewhere.
16661666>
from line 1678
16781678
16791679**Allow screenshots of the screen and other apps.** Let users screenshot their screen or other apps’ windows in Quick Entry on macOS. When off, it never asks for Screen Recording access.
16801680
1681> **More detail**
1681> [accordion] More detail
16821682>
16831683> When off, another app's window that a user mentions with @ in a chat also comes without its picture.
16841684>
from line 1692
16921692
16931693**Allow sharing files open in other apps.** Let users attach the file open in another app’s window in Quick Entry on macOS. When off, it never asks for Accessibility access.
16941694
1695> **More detail**
1695> [accordion] More detail
16961696>
16971697> Off applies even where the Accessibility permission is already granted. Another app's window that a user mentions with @ in a chat then also comes without its file. Not covered: Claude's other uses of that permission, and files that users attach themselves.
16981698
from line 1704
17041704
17051705**Skip WebFetch domain check.** Skip Claude Code’s WebFetch domain lookup against api.anthropic.com in Code sessions. Off by default; turn on when that host is blocked.
17061706
1707> **More detail**
1707> [accordion] More detail
17081708>
17091709> Before fetching a page, Claude Code's WebFetch tool asks `api.anthropic.com` whether the domain is on Anthropic's content blocklist.
17101710>
from line 1719
17191719
17201720**Built-in tool policy.** Approval per tool or rule such as Bash(curl \*). “ask” prompts the user before each matching call. To block, use Disabled built-in tools.
17211721
1722> **More detail**
1722> [accordion] More detail
17231723>
17241724> Entries use the same tool names and rules as `disabledBuiltinTools`, with the same limits. Command rules are not a security boundary, and `Bash(…)` rules do not cover `PowerShell`.
17251725>
from line 1737
17371737
17381738**Disabled built-in tools.** Built-in tools, or rules such as Read(//etc/\*\*), blocked in Cowork and Code. Shell commands do not fully follow file-path rules.
17391739
1740> **More detail**
1740> [accordion] More detail
17411741>
17421742> An entry is a [tool name](https://code.claude.com/docs/en/tools-reference) such as `Bash`, or a [permission rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax) such as `Edit(//etc/**)`.
17431743>
from line 1755
17551755
17561756[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/gateway.md#mcp-tool-search)
17571757
1758> **More detail**
1758> [accordion] More detail
17591759>
17601760> Your gateway or provider must accept what tool search adds, such as `tool-search-tool-2025-10-19` in the `anthropic-beta` header. Otherwise requests fail with HTTP 400. On Foundry or a custom base URL, requests also carry Claude Code's other experimental betas.
17611761>
from line 1769
17691769
17701770**Organization instructions.** Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters.
17711771
1772> **More detail**
1772> [accordion] More detail
17731773>
17741774> Claude is told that they take priority over a user's personal preferences.
17751775>
from line 1801
18011801
18021802[Admin Console](#the-works-with-column): Not available.
18031803
1804> **More detail**
1804> [accordion] More detail
18051805>
18061806> In an MDM profile, this key also keeps that profile in charge. Without it, a user can sign in to Claude.ai with an organization that configures Claude Desktop in the Admin Console. The device then mostly follows that organization's configuration, at later launches too.
18071807>
from line 1829
18291829
18301830[Admin Console](#the-works-with-column): Set automatically.
18311831
1832> **More detail**
1832> [accordion] More detail
18331833>
18341834> The app checks the addresses of public sites that open or are framed in the browser (query removed) against Anthropic's site safety list on `releases.claude.com`.
18351835>
from line 1849
18491849
18501850[Admin Console](#the-works-with-column): Set automatically.
18511851
1852> **More detail**
1852> [accordion] More detail
18531853>
18541854> A `coworkEgressAllowedHosts` list other than `*` applies on top of either value: Claude cannot open sites outside it.
18551855>
from line 1865
18651865
18661866[Admin Console](#the-works-with-column): Set automatically.
18671867
1868> **More detail**
1868> [accordion] More detail
18691869>
18701870> Entries use the same format as `coworkEgressAllowedHosts`, except:
18711871>
from line 1884
18841884
18851885[Admin Console](#the-works-with-column): Set automatically.
18861886
1887> **More detail**
1887> [accordion] More detail
18881888>
18891889> Entries use the same format as `coworkEgressAllowedHosts`. `*` blocks every external site. `example.com` also covers `www.example.com`, but no other subdomain. An entry outside that format matches nothing.
18901890>
from line 1900
19001900
19011901**Claude.ai data import.** Lets users import Claude.ai chats and projects, and earlier Claude sessions on this device.
19021902
1903> **Child attributes (5)**
1903> [accordion] Child attributes (5)
19041904>
19051905> **enabled** `boolean` (default: false)
19061906>
from line 1910
19101910>
19111911> When set, users import by sign-in only, and only from the Claude.ai organizations with these IDs.
19121912>
1913> > **More detail**
1913> > [accordion] More detail
19141914> >
19151915> > * The list narrows `enabled`. It turns nothing on by itself and does not affect `automatic3pImport`.
19161916> > * An empty list, or one that cannot be read, allows no organization, so no import is offered. A null or empty string counts as unset.
from line 1920
19201920>
19211921> Copy this computer’s earlier third-party sessions into the app once, in the background. Independent of `enabled`.
19221922>
1923> > **More detail**
1923> > [accordion] More detail
19241924> >
19251925> > Unset is off, except in Admin Console organizations, where it is on unless an admin turns it off. Without the Admin Console, also set `deploymentOrganizationUuid`. Only sessions stored before you set it are copied.
19261926> >
from line 1935
19351935>
19361936> Lets users export this device’s chats, Cowork tasks and Code sessions as a zip to import elsewhere. No effect unless Enable import is on.
19371937>
1938> > **More detail**
1938> > [accordion] More detail
19391939> >
19401940> > Transcripts contain conversation content including tool outputs. Treat exported zips as sensitive data.
19411941>
from line 1957
19571957
19581958**Managed MCP servers.** Org-pushed MCP servers: remote (HTTP/SSE) or local (stdio command).
19591959
1960> **More detail**
1960> [accordion] More detail
19611961>
19621962> Values of an entry's `toolPolicy`, per tool name:
19631963>
from line 1967
19671967>
19681968> A name can contain `*`, as in `read_*`. When several wildcards match, the strictest applies. An exact name normally takes priority over a wildcard. To block by default, use `"*": "blocked"` plus exact `allow` entries.
19691969
1970> **Child attributes**
1970> [accordion] Child attributes
19711971>
19721972> **name** `string` *required*
19731973>
19741974> Must be unique. A rename resets each user’s on/off choice, tool permissions and device sign-in, and can break a plugin server’s match.
19751975>
1976> > **More detail**
1976> > [accordion] More detail
19771977> >
19781978> > After a rename:
19791979> >
from line 1988
19881988>
19891989> Lock the approval state for specific tools. Unlisted tools stay user-controlled.
19901990>
1991> > **More detail**
1991> > [accordion] More detail
19921992> >
19931993> > Also applies to an installed plugin's server that matches this entry by URL, or else by name (letter case is ignored).
19941994> >
from line 1996
19961996> > * For a server that only a plugin runs, use an entry with `transport: "policy-only"`.
19971997> > * Claude Code runs or connects to some plugin servers itself. For those: Claude Code's own managed settings, where a session has any, take priority by default.
19981998>
1999> **microsoft365**
2000>
2001> Applies when `server` is `microsoft365`. The in-app configuration window calls it **Microsoft 365**.
2002>
2003> **server** `string` *required*
2004>
2005> Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2006>
2007> Must be: `microsoft365`
2008>
2009> **tenantId** `string` *required*
2010>
2011> Your organization’s Microsoft Entra directory (tenant) ID.
2012>
2013> **clientId** `string` *required*
2014>
2015> OAuth app client ID for this built-in server.
2016>
2017> **azureCloud** `enum`
2018>
2019> Microsoft cloud for sign-in and Graph. Use global for commercial Microsoft 365. US Government clouds need your own app registration.
2020>
2021> One of: `global`, `us-gov-high`, `us-gov-dod`
2022>
2023> **continuousAccessEvaluation** `enum` (default: enabled)
2024>
2025> Requests Microsoft Graph tokens that last up to about 28 hours but can be revoked within minutes. “disabled” keeps one-hour tokens.
2026>
2027> One of: `enabled` (default), `disabled`
2028>
2029> > **More detail**
2030> >
2031> > With a Conditional Access policy on IP named locations or Global Secure Access compliant networks, a token presented from outside that network is cut off. Tenants without such a policy get no network-based replay protection.
2032> >
2033> > After a change, users sign in again.
2034>
2035> **scope** `string`
2036>
2037> What the server may request at sign-in. If blank, Desktop’s default read set is used.
2038>
2039> **websearch**
2040>
2041> Applies when `server` is `websearch`. The in-app configuration window calls it **Web search**.
2042>
2043> **headers** `object: name → value`
2044>
2045> Static headers sent on every request: routing and tenant headers only. No credentials here: use the headers helper script for those.
2046>
2047> **headersHelper** `string`
2048>
2049> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2050>
2051> Script that prints the auth header as a JSON object to stdout. Runs before each request (cached for the TTL below).
2052>
2053> > **More detail**
2054> >
2055> > The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2056>
2057> **headersHelperArgs** `string[]`
2058>
2059> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2060>
2061> Arguments passed to the headers helper script, one per entry, in order. Leave unset to run it with none.
2062>
2063> > **More detail**
2064> >
2065> > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2066> > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2067> > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2068>
2069> **headersHelperTtlSec** `integer`
2070>
2071> How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300.
2072>
2073> **headersHelperRefreshBufferSec** `integer`
2074>
2075> Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime.
2076>
2077> **server** `string` *required*
2078>
2079> Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2080>
2081> Must be: `websearch`
2082>
2083> **provider** `enum` *required*
2084>
2085> Runs web search from the user’s device, for inference providers without built-in search. Supply the API key with the headers helper script.
2086>
2087> One of: `brave`, `tavily`, `exa`, `custom`
2088>
2089> > **More detail**
2090> >
2091> > Not needed on the Anthropic API or Vertex, where the model's built-in web search is available.
2092> >
2093> > Every search provider except `custom` needs an auth header. The API key is a credential, so have `headersHelper` print the header rather than storing it in `headers`:
2094> >
2095> > * **Brave:** `X-Subscription-Token`
2096> > * **Exa:** `x-api-key`
2097> > * **Tavily:** `Authorization` (Bearer …)
2098>
2099> **platformOverrides** `object`
2100>
2101> On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2102>
2103> > **More detail**
2104> >
2105> > A value written here replaces the entry's value whole: lists and maps are not merged.
2106> >
2107> > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2108> > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2109> > * A mistake under any operating system drops the server on all of them.
2110> > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2111>
2112> > **Child attributes (3)**
2113> >
2114> > **platformOverrides.win32** `object: name → value`
2115> >
2116> > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2117> >
2118> > **platformOverrides.darwin** `object: name → value`
2119> >
2120> > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2121> >
2122> > **platformOverrides.linux** `object: name → value`
2123> >
2124> > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2125>
2126> **customUrl** `string`
2127>
2128> POST endpoint accepting \{q} JSON and returning a results\[] array. Only used when provider is Custom.
2129>
2130> **github**
2131>
2132> Applies when `server` is `github`. The in-app configuration window calls it **GitHub**.
2133>
2134> **server** `string` *required*
2135>
2136> Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2137>
2138> Must be: `github`
2139>
2140> **clientId** `string` *required*
2141>
2142> GitHub OAuth app client ID (device flow must be enabled on the app).
2143>
2144> **host** `string`
2145>
2146> Leave blank for github.com. For GitHub Enterprise Server, your instance’s base URL.
2147>
2148> **scope** `string`
2149>
2150> Space-separated GitHub OAuth scopes. Unset: Desktop’s default scopes. Ignored for GitHub Apps: their registration sets the permissions.
2151>
2152> **toolsets** `string`
2153>
2154> Comma-separated github-mcp-server toolsets to enable. If blank, the bundled server’s default toolsets are used.
2155>
2156> > **More detail**
2157> >
2158> > Every tool that can change something asks before each call unless `toolPolicy` says otherwise.
2159> >
2160> > These tools cannot be set looser than `ask`, and `allow` is treated as `ask`: `merge_pull_request`, `push_files`, `create_or_update_file`, `delete_file`, `actions_run_trigger`, `pull_request_review_write`, `delete_repository`. Where no prompt can be shown, their calls are refused.
2161>
2162> **readOnly** `boolean`
2163>
2164> Offer only read tools — the server registers no write tools at all.
2165>
2166> **http / sse**
2167>
2168> Applies when `transport` is `http` or `sse`. The in-app configuration window calls it **Streamable HTTP** or **SSE (legacy)**.
2169>
2170> **transport** `enum` *required*
2171>
2172> How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2173>
2174> One of: `http`, `sse`
2175>
2176> **url** `string` *required*
2177>
2178> HTTPS endpoint of the remote MCP server. Use the server’s final address: HTTP redirects are not followed.
2179>
2180> **oauth** `object`
2181>
2182> OAuth sign-in for a remote server: register a client automatically, use your own client ID, or use an Anthropic-hosted client identity.
2183>
2184> [Guide for this setting](https://claude.com/docs/third-party/claude-desktop/mcp-sign-in.md)
2185>
2186> > **More detail**
2187> >
2188> > Choose **Bring your own client** when the provider requires an OAuth client that you register, and set `clientId`. Add `clientSecret` and `authorizationServer` only when the provider also requires the secret.
2189>
2190> > **Child attributes**
2191> >
2192> > **dcr**
2193> >
2194> > Applies when `oauth.mode` is `dcr`. The in-app configuration window calls it **Auto-register (dynamic client registration)**. No other fields apply.
2195> >
2196> > Write `"oauth": true`. `{"mode": "dcr"}` means the same and takes no other member. To register automatically with scopes of your choice, write an object that sets any of `scope`, `appendOfflineAccess` and `additionalRedirectReferrerHosts` and nothing else, as Bring your own client describes.
2197> >
2198> > **byo**
2199> >
2200> > Applies when `oauth.mode` is `byo`. The in-app configuration window calls it **Bring your own client**.
2201> >
2202> > `mode` can be left out. Without `clientId` the object may set only `scope`, `appendOfflineAccess` and `additionalRedirectReferrerHosts`, and the app registers a client automatically; with any other member listed here and no `clientId`, the app drops the entry.
2203> >
2204> > **oauth.clientId** `string`
2205> >
2206> > OAuth client ID from your identity provider’s app registration. Unset: auto-register (dynamic client registration).
2207> >
2208> > **oauth.clientSecret** `string`
2209> >
2210> > Only if the provider requires one. The Admin Console stores only a Google Desktop-app secret (GOCSPX-…). For others use the helper script.
2211> >
2212> > **oauth.clientSecretHelper** `string`
1999> > [tab] microsoft365
2000> >
2001> > Applies when `server` is `microsoft365`. The in-app configuration window calls it **Microsoft 365**.
2002> >
2003> > **server** `string` *required*
2004> >
2005> > Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2006> >
2007> > Must be: `microsoft365`
2008> >
2009> > **tenantId** `string` *required*
2010> >
2011> > Your organization’s Microsoft Entra directory (tenant) ID.
2012> >
2013> > **clientId** `string` *required*
2014> >
2015> > OAuth app client ID for this built-in server.
2016> >
2017> > **azureCloud** `enum`
2018> >
2019> > Microsoft cloud for sign-in and Graph. Use global for commercial Microsoft 365. US Government clouds need your own app registration.
2020> >
2021> > One of: `global`, `us-gov-high`, `us-gov-dod`
2022> >
2023> > **continuousAccessEvaluation** `enum` (default: enabled)
2024> >
2025> > Requests Microsoft Graph tokens that last up to about 28 hours but can be revoked within minutes. “disabled” keeps one-hour tokens.
2026> >
2027> > One of: `enabled` (default), `disabled`
2028> >
2029> > > [accordion] More detail
2030> > >
2031> > > With a Conditional Access policy on IP named locations or Global Secure Access compliant networks, a token presented from outside that network is cut off. Tenants without such a policy get no network-based replay protection.
2032> > >
2033> > > After a change, users sign in again.
2034> >
2035> > **scope** `string`
2036> >
2037> > What the server may request at sign-in. If blank, Desktop’s default read set is used.
2038>
2039> > [tab] websearch
2040> >
2041> > Applies when `server` is `websearch`. The in-app configuration window calls it **Web search**.
2042> >
2043> > **headers** `object: name → value`
2044> >
2045> > Static headers sent on every request: routing and tenant headers only. No credentials here: use the headers helper script for those.
2046> >
2047> > **headersHelper** `string`
22132048> >
22142049> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
22152050> >
2216> > Script that prints the client secret as a JSON object with a single clientSecret key. Takes priority over Client secret.
2217> >
2218> > > **More detail**
2219> > >
2220> > > * Its standard output must be exactly `{"clientSecret": "…"}`, with no other keys or lines. Any other output stops the server from connecting.
2221> > > * It must exit with code `0` within 30 seconds.
2222> > > * It runs with no arguments each time the server connects and each time its sign-in is renewed in the background. Choose a script that does not prompt the user.
2051> > Script that prints the auth header as a JSON object to stdout. Runs before each request (cached for the TTL below).
2052> >
2053> > > [accordion] More detail
22232054> > >
22242055> > > The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
22252056> >
2226> > **oauth.authorizationServer** `string[]`
2227> >
2228> > Issuer URLs the OAuth sign-in may use, as a JSON array. Pre-filled by presets; ask your IdP admin if unsure.
2229> >
2230> > **oauth.authorizationUrl** `string`
2231> >
2232> > Only for IdPs that don’t serve a .well-known discovery document. Set together with Token URL; requires Client ID.
2233> >
2234> > **oauth.tokenUrl** `string`
2235> >
2236> > Only for IdPs that don’t serve a .well-known discovery document. Set together with Authorization URL; requires Client ID.
2237> >
2238> > **oauth.tenantId** `string`
2239> >
2240> > Required for single-tenant Entra apps. Leave blank for multi-tenant or non-Microsoft IdPs.
2241> >
2242> > > **More detail**
2243> > >
2244> > > For a GCC High or DoD tenant, leave this unset and set `authorizationServer` to `https://login.microsoftonline.us/<tenant-id>/v2.0`.
2245> >
2246> > **oauth.authFlow** `enum`
2247> >
2248> > How Entra sign-in runs for this server: the system browser (default) or the OS identity broker.
2249> >
2250> > One of: `browser`, `broker`
2251> >
2252> > > **More detail**
2253> > >
2254> > > `broker` signs in through the OS identity broker: Web Account Manager on Windows, the Company Portal SSO extension on macOS. It can satisfy Conditional Access policies that require a compliant or managed device, or token protection.
2255> > >
2256> > > * It requires `tenantId`, `clientId` and `scope`, and an Entra-registered device.
2257> > > * The app registration must list the [broker redirect URIs](https://claude.com/docs/third-party/claude-desktop/entra-broker.md).
2258> > > * `broker` is not supported on Linux. Where the broker is not available, sign-in falls back to the system browser.
2259> >
2260> > **oauth.scope** `string`
2261> >
2262> > Space-separated scopes to request. Unset: the scopes the server advertises. Required if Tenant ID is set or the resource parameter omitted.
2263> >
2264> > **oauth.appendOfflineAccess** `boolean`
2265> >
2266> > Adds offline\_access to the authorize request so the IdP returns a refresh token for silent renewal.
2267> >
2268> > > **More detail**
2269> > >
2270> > > Leave off if `scope` already includes `offline_access` or the server rejects it.
2271> > >
2272> > > If you set `authorizationUrl` and `tokenUrl`, this switch does not work on its own. Add `offline_access` to `scope` instead.
2273> >
2274> > **oauth.omitResource** `boolean`
2275> >
2276> > Sends no OAuth resource parameter. Use only if your identity provider rejects it. Requires Client ID, Scope and one sign-in server.
2277> >
2278> > > **More detail**
2279> > >
2280> > > By default, sign-in sends the URL that this server publishes as the OAuth `resource` parameter, which ties the token to this server. Microsoft Entra ID rejects it with `AADSTS9010010` when the URL is not an Application ID URI in your tenant.
2281> > >
2282> > > * **Requires:** `clientId`, a `scope` with an API scope, and exactly one of `tenantId`, a single `authorizationServer`, or `authorizationUrl` with `tokenUrl`. Otherwise the entry is not loaded.
2283> > > * **Risk:** `scope` alone now says which API the token is for, so check that it names this server's app. A scope for another app is accepted, and this server then receives a token meant for that app.
2284> > > * **Entra ID:** write the scope in full, as in `api://<app-id>/<scope>`.
2285> >
2286> > **oauth.callbackHost** `enum`
2287> >
2288> > Use localhost only if your IdP’s registered redirect URI specifies it.
2289> >
2290> > One of: `127.0.0.1`, `localhost`
2291> >
2292> > **oauth.callbackPort** `integer`
2293> >
2294> > Only set if your IdP requires an exact-match redirect port. Entra accepts any.
2295> >
2296> > **oauth.additionalRedirectReferrerHosts** `string`
2297> >
2298> > Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
2299> >
2300> > > **More detail**
2301> > >
2302> > > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
2303> >
2304> > **hosted**
2305> >
2306> > Applies when `oauth.mode` is `hosted`. The in-app configuration window calls it **Anthropic-hosted client identity (requires Claude.ai sign-in)**.
2307> >
2308> > Always write `"mode": "hosted"`. Without it the object is read as Bring your own client, which needs `clientId` beside `authorizationServer`, so the app drops the entry.
2309> >
2310> > **oauth.clientId** `string`
2311> >
2312> > Filled in by Claude.ai: the URL of Anthropic’s hosted client-metadata document. Do not set it.
2313> >
2314> > **oauth.authorizationServer** `string[]` *required*
2315> >
2316> > The exact issuer string(s) that the server’s authorization server advertises, as a JSON array. Anthropic signs the identity only for these.
2317> >
2318> > **oauth.scope** `string`
2319> >
2320> > Space-separated scopes to request. Unset: the scopes the server advertises. Required if Tenant ID is set or the resource parameter omitted.
2321>
2322> **headers** `object: name → value`
2323>
2324> Static headers sent on every request: routing and tenant headers only. No credentials here: use the headers helper script for those.
2325>
2326> **headersHelper** `string`
2327>
2328> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2329>
2330> Absolute path to an executable that prints a JSON object of HTTP headers on stdout. Merged over static headers; the helper wins on conflict.
2331>
2332> > **More detail**
2333> >
2334> > The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2335>
2336> **headersHelperArgs** `string[]`
2337>
2338> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2339>
2340> Arguments passed to the headers helper script, one per entry, in order. Leave unset to run it with none.
2341>
2342> > **More detail**
2343> >
2344> > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2345> > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2346> > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2347>
2348> **headersHelperTtlSec** `integer`
2349>
2350> How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300.
2351>
2352> **headersHelperRefreshBufferSec** `integer`
2353>
2354> Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime.
2355>
2356> **platformOverrides** `object`
2357>
2358> On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2359>
2360> > **More detail**
2361> >
2362> > A value written here replaces the entry's value whole: lists and maps are not merged.
2363> >
2364> > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2365> > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2366> > * A mistake under any operating system drops the server on all of them.
2367> > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2368>
2369> > **Child attributes (3)**
2370> >
2371> > **platformOverrides.win32** `object: name → value`
2372> >
2373> > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2374> >
2375> > **platformOverrides.darwin** `object: name → value`
2376> >
2377> > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2378> >
2379> > **platformOverrides.linux** `object: name → value`
2380> >
2381> > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2382>
2383> **toolTimeoutSec** `integer`
2384>
2385> Maximum time in seconds that Claude waits for one tool call to this server. Leave empty to use the MCP tool call timeout.
2386>
2387> > **More detail**
2388> >
2389> > For Claude's calls to this server it takes the place of `mcpToolTimeoutSec`. Use a whole number from 5 to 3600: any other value is ignored.
2390> >
2391> > * Progress messages from the server do not extend the limit.
2392> > * Time that a user spends on a sign-in or consent step during the call counts toward the limit. On a server that asks for sign-in, set a generous value.
2393>
2394> **icon** `string`
2395>
2396> Icon shown for this connector: a PNG or JPEG image as a base64 data: URI, at most 4,096 characters.
2397>
2398> > **More detail**
2399> >
2400> > A PNG of 48 by 48 pixels or smaller works well. Keep icons small: Windows Group Policy holds the whole `managedMcpServers` list in one value of at most 65,535 characters.
2401>
2402> **defaultState** `enum`
2403>
2404> Whether this connector starts on or off for each person.
2405>
2406> One of: `on`, `off`
2407>
2408> > **More detail**
2409> >
2410> > Unset means `on`.
2411> >
2412> > * This is a starting point, not a restriction: each user can turn the connector on. To withhold a connector, remove it or block its tools with `toolPolicy`.
2413> > * Adding `off` to a connector already in use turns it off for all users who have not switched it on themselves, scheduled tasks included.
2414> > * This setting does not apply to a plugin's server that matches this entry.
2415>
2416> **stdio**
2417>
2418> Applies when `transport` is `stdio`. The in-app configuration window calls it **Local command (stdio)**.
2419>
2420> **transport** `string` *required*
2421>
2422> How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2423>
2424> Must be: `stdio`
2425>
2426> **command** `string` *required*
2427>
2428> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2429>
2430> Absolute path to the server executable, run on the user’s machine.
2431>
2432> **args** `string[]`
2433>
2434> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2435>
2436> Arguments passed to the command, one per entry.
2437>
2438> **env** `object: name → value`
2439>
2440> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2441>
2442> Environment variables set for the command.
2443>
2444> **envHelper** `string`
2445>
2446> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2447>
2448> Script that prints environment variables as a JSON object to stdout. Runs when the local server starts (cached for the TTL below).
2449>
2450> > **More detail**
2451> >
2452> > * Its values take priority over `env`.
2453> > * If the script fails, the server does not start.
2454> > * A script with nothing to set must print `{}`. Empty output counts as a failure.
2455> > * The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2456>
2457> **envHelperArgs** `string[]`
2458>
2459> Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2460>
2461> Arguments passed to the environment helper script, one per entry, in order. Leave unset to run it with none.
2462>
2463> > **More detail**
2464> >
2465> > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2466> > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2467> > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2468>
2469> **envHelperTtlSec** `integer` (default: 300)
2470>
2471> Maximum age of a cached helper result, in seconds (default 300). Applies when the server starts or restarts.
2472>
2473> > **More detail**
2474> >
2475> > Set this at or below your token lifetime. Otherwise a server that crashes because its token expired can restart with the same cached values until this time is up.
2476>
2477> **startupTimeoutSec** `integer` (default: 120)
2478>
2479> Maximum wait in seconds for the server to start and list its tools.
2480>
2481> **platformOverrides** `object`
2482>
2483> On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2484>
2485> > **More detail**
2486> >
2487> > A value written here replaces the entry's value whole: lists and maps are not merged.
2488> >
2489> > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2490> > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2491> > * A mistake under any operating system drops the server on all of them.
2492> > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2493>
2494> > **Child attributes (3)**
2495> >
2496> > **platformOverrides.win32** `object: name → value`
2497> >
2498> > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2499> >
2500> > **platformOverrides.darwin** `object: name → value`
2501> >
2502> > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2503> >
2504> > **platformOverrides.linux** `object: name → value`
2505> >
2506> > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2507>
2508> **toolTimeoutSec** `integer`
2509>
2510> Maximum time in seconds that Claude waits for one tool call to this server. Leave empty to use the MCP tool call timeout.
2511>
2512> > **More detail**
2513> >
2514> > For Claude's calls to this server it takes the place of `mcpToolTimeoutSec`. Use a whole number from 5 to 3600: any other value is ignored.
2515> >
2516> > * Progress messages from the server do not extend the limit.
2517> > * Time that a user spends on a sign-in or consent step during the call counts toward the limit. On a server that asks for sign-in, set a generous value.
2518>
2519> **icon** `string`
2520>
2521> Icon shown for this connector: a PNG or JPEG image as a base64 data: URI, at most 4,096 characters.
2522>
2523> > **More detail**
2524> >
2525> > A PNG of 48 by 48 pixels or smaller works well. Keep icons small: Windows Group Policy holds the whole `managedMcpServers` list in one value of at most 65,535 characters.
2526>
2527> **policy-only**
2528>
2529> Applies when `transport` is `policy-only`. The in-app configuration window calls it **Tool permissions only (plugin server)**.
2530>
2531> **transport** `string` *required*
2532>
2533> How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2534>
2535> Must be: `policy-only`
2536>
2537> > **More detail**
2538> >
2539> > For a `policy-only` entry:
2540> >
2541> > * Set `name` to the server's name as the plugin declares it (letter case is ignored), and `toolPolicy` to the permissions. A name that matches no installed plugin server does nothing.
2542> > * It takes priority over `orgPluginSettings` for that server. With no `toolPolicy`, the server is left unrestricted.
2543> > * An older version drops the entry and applies `orgPluginSettings` instead. Until all devices are updated, keep the same permissions there, and do not deploy a list made only of `policy-only` entries.
2057> > **headersHelperArgs** `string[]`
2058> >
2059> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2060> >
2061> > Arguments passed to the headers helper script, one per entry, in order. Leave unset to run it with none.
2062> >
2063> > > [accordion] More detail
2064> > >
2065> > > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2066> > > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2067> > > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2068> >
2069> > **headersHelperTtlSec** `integer`
2070> >
2071> > How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300.
2072> >
2073> > **headersHelperRefreshBufferSec** `integer`
2074> >
2075> > Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime.
2076> >
2077> > **server** `string` *required*
2078> >
2079> > Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2080> >
2081> > Must be: `websearch`
2082> >
2083> > **provider** `enum` *required*
2084> >
2085> > Runs web search from the user’s device, for inference providers without built-in search. Supply the API key with the headers helper script.
2086> >
2087> > One of: `brave`, `tavily`, `exa`, `custom`
2088> >
2089> > > [accordion] More detail
2090> > >
2091> > > Not needed on the Anthropic API or Vertex, where the model's built-in web search is available.
2092> > >
2093> > > Every search provider except `custom` needs an auth header. The API key is a credential, so have `headersHelper` print the header rather than storing it in `headers`:
2094> > >
2095> > > * **Brave:** `X-Subscription-Token`
2096> > > * **Exa:** `x-api-key`
2097> > > * **Tavily:** `Authorization` (Bearer …)
2098> >
2099> > **platformOverrides** `object`
2100> >
2101> > On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2102> >
2103> > > [accordion] More detail
2104> > >
2105> > > A value written here replaces the entry's value whole: lists and maps are not merged.
2106> > >
2107> > > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2108> > > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2109> > > * A mistake under any operating system drops the server on all of them.
2110> > > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2111> >
2112> > > [accordion] Child attributes (3)
2113> > >
2114> > > **platformOverrides.win32** `object: name → value`
2115> > >
2116> > > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2117> > >
2118> > > **platformOverrides.darwin** `object: name → value`
2119> > >
2120> > > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2121> > >
2122> > > **platformOverrides.linux** `object: name → value`
2123> > >
2124> > > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2125> >
2126> > **customUrl** `string`
2127> >
2128> > POST endpoint accepting \{q} JSON and returning a results\[] array. Only used when provider is Custom.
2129>
2130> > [tab] github
2131> >
2132> > Applies when `server` is `github`. The in-app configuration window calls it **GitHub**.
2133> >
2134> > **server** `string` *required*
2135> >
2136> > Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields.
2137> >
2138> > Must be: `github`
2139> >
2140> > **clientId** `string` *required*
2141> >
2142> > GitHub OAuth app client ID (device flow must be enabled on the app).
2143> >
2144> > **host** `string`
2145> >
2146> > Leave blank for github.com. For GitHub Enterprise Server, your instance’s base URL.
2147> >
2148> > **scope** `string`
2149> >
2150> > Space-separated GitHub OAuth scopes. Unset: Desktop’s default scopes. Ignored for GitHub Apps: their registration sets the permissions.
2151> >
2152> > **toolsets** `string`
2153> >
2154> > Comma-separated github-mcp-server toolsets to enable. If blank, the bundled server’s default toolsets are used.
2155> >
2156> > > [accordion] More detail
2157> > >
2158> > > Every tool that can change something asks before each call unless `toolPolicy` says otherwise.
2159> > >
2160> > > These tools cannot be set looser than `ask`, and `allow` is treated as `ask`: `merge_pull_request`, `push_files`, `create_or_update_file`, `delete_file`, `actions_run_trigger`, `pull_request_review_write`, `delete_repository`. Where no prompt can be shown, their calls are refused.
2161> >
2162> > **readOnly** `boolean`
2163> >
2164> > Offer only read tools — the server registers no write tools at all.
2165>
2166> > [tab] http / sse
2167> >
2168> > Applies when `transport` is `http` or `sse`. The in-app configuration window calls it **Streamable HTTP** or **SSE (legacy)**.
2169> >
2170> > **transport** `enum` *required*
2171> >
2172> > How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2173> >
2174> > One of: `http`, `sse`
2175> >
2176> > **url** `string` *required*
2177> >
2178> > HTTPS endpoint of the remote MCP server. Use the server’s final address: HTTP redirects are not followed.
2179> >
2180> > **oauth** `object`
2181> >
2182> > OAuth sign-in for a remote server: register a client automatically, use your own client ID, or use an Anthropic-hosted client identity.
2183> >
2184> > [Guide for this setting](https://claude.com/docs/third-party/claude-desktop/mcp-sign-in.md)
2185> >
2186> > > [accordion] More detail
2187> > >
2188> > > Choose **Bring your own client** when the provider requires an OAuth client that you register, and set `clientId`. Add `clientSecret` and `authorizationServer` only when the provider also requires the secret.
2189> >
2190> > > [accordion] Child attributes
2191> > >
2192> > > > [tab] dcr
2193> > > >
2194> > > > Applies when `oauth.mode` is `dcr`. The in-app configuration window calls it **Auto-register (dynamic client registration)**. No other fields apply.
2195> > > >
2196> > > > Write `"oauth": true`. `{"mode": "dcr"}` means the same and takes no other member. To register automatically with scopes of your choice, write an object that sets any of `scope`, `appendOfflineAccess` and `additionalRedirectReferrerHosts` and nothing else, as Bring your own client describes.
2197> > >
2198> > > > [tab] byo
2199> > > >
2200> > > > Applies when `oauth.mode` is `byo`. The in-app configuration window calls it **Bring your own client**.
2201> > > >
2202> > > > `mode` can be left out. Without `clientId` the object may set only `scope`, `appendOfflineAccess` and `additionalRedirectReferrerHosts`, and the app registers a client automatically; with any other member listed here and no `clientId`, the app drops the entry.
2203> > > >
2204> > > > **oauth.clientId** `string`
2205> > > >
2206> > > > OAuth client ID from your identity provider’s app registration. Unset: auto-register (dynamic client registration).
2207> > > >
2208> > > > **oauth.clientSecret** `string`
2209> > > >
2210> > > > Only if the provider requires one. The Admin Console stores only a Google Desktop-app secret (GOCSPX-…). For others use the helper script.
2211> > > >
2212> > > > **oauth.clientSecretHelper** `string`
2213> > > >
2214> > > > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2215> > > >
2216> > > > Script that prints the client secret as a JSON object with a single clientSecret key. Takes priority over Client secret.
2217> > > >
2218> > > > > [accordion] More detail
2219> > > > >
2220> > > > > * Its standard output must be exactly `{"clientSecret": "…"}`, with no other keys or lines. Any other output stops the server from connecting.
2221> > > > > * It must exit with code `0` within 30 seconds.
2222> > > > > * It runs with no arguments each time the server connects and each time its sign-in is renewed in the background. Choose a script that does not prompt the user.
2223> > > > >
2224> > > > > The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2225> > > >
2226> > > > **oauth.authorizationServer** `string[]`
2227> > > >
2228> > > > Issuer URLs the OAuth sign-in may use, as a JSON array. Pre-filled by presets; ask your IdP admin if unsure.
2229> > > >
2230> > > > **oauth.authorizationUrl** `string`
2231> > > >
2232> > > > Only for IdPs that don’t serve a .well-known discovery document. Set together with Token URL; requires Client ID.
2233> > > >
2234> > > > **oauth.tokenUrl** `string`
2235> > > >
2236> > > > Only for IdPs that don’t serve a .well-known discovery document. Set together with Authorization URL; requires Client ID.
2237> > > >
2238> > > > **oauth.tenantId** `string`
2239> > > >
2240> > > > Required for single-tenant Entra apps. Leave blank for multi-tenant or non-Microsoft IdPs.
2241> > > >
2242> > > > > [accordion] More detail
2243> > > > >
2244> > > > > For a GCC High or DoD tenant, leave this unset and set `authorizationServer` to `https://login.microsoftonline.us/<tenant-id>/v2.0`.
2245> > > >
2246> > > > **oauth.authFlow** `enum`
2247> > > >
2248> > > > How Entra sign-in runs for this server: the system browser (default) or the OS identity broker.
2249> > > >
2250> > > > One of: `browser`, `broker`
2251> > > >
2252> > > > > [accordion] More detail
2253> > > > >
2254> > > > > `broker` signs in through the OS identity broker: Web Account Manager on Windows, the Company Portal SSO extension on macOS. It can satisfy Conditional Access policies that require a compliant or managed device, or token protection.
2255> > > > >
2256> > > > > * It requires `tenantId`, `clientId` and `scope`, and an Entra-registered device.
2257> > > > > * The app registration must list the [broker redirect URIs](https://claude.com/docs/third-party/claude-desktop/entra-broker.md).
2258> > > > > * `broker` is not supported on Linux. Where the broker is not available, sign-in falls back to the system browser.
2259> > > >
2260> > > > **oauth.scope** `string`
2261> > > >
2262> > > > Space-separated scopes to request. Unset: the scopes the server advertises. Required if Tenant ID is set or the resource parameter omitted.
2263> > > >
2264> > > > **oauth.appendOfflineAccess** `boolean`
2265> > > >
2266> > > > Adds offline\_access to the authorize request so the IdP returns a refresh token for silent renewal.
2267> > > >
2268> > > > > [accordion] More detail
2269> > > > >
2270> > > > > Leave off if `scope` already includes `offline_access` or the server rejects it.
2271> > > > >
2272> > > > > If you set `authorizationUrl` and `tokenUrl`, this switch does not work on its own. Add `offline_access` to `scope` instead.
2273> > > >
2274> > > > **oauth.omitResource** `boolean`
2275> > > >
2276> > > > Sends no OAuth resource parameter. Use only if your identity provider rejects it. Requires Client ID, Scope and one sign-in server.
2277> > > >
2278> > > > > [accordion] More detail
2279> > > > >
2280> > > > > By default, sign-in sends the URL that this server publishes as the OAuth `resource` parameter, which ties the token to this server. Microsoft Entra ID rejects it with `AADSTS9010010` when the URL is not an Application ID URI in your tenant.
2281> > > > >
2282> > > > > * **Requires:** `clientId`, a `scope` with an API scope, and exactly one of `tenantId`, a single `authorizationServer`, or `authorizationUrl` with `tokenUrl`. Otherwise the entry is not loaded.
2283> > > > > * **Risk:** `scope` alone now says which API the token is for, so check that it names this server's app. A scope for another app is accepted, and this server then receives a token meant for that app.
2284> > > > > * **Entra ID:** write the scope in full, as in `api://<app-id>/<scope>`.
2285> > > >
2286> > > > **oauth.callbackHost** `enum`
2287> > > >
2288> > > > Use localhost only if your IdP’s registered redirect URI specifies it.
2289> > > >
2290> > > > One of: `127.0.0.1`, `localhost`
2291> > > >
2292> > > > **oauth.callbackPort** `integer`
2293> > > >
2294> > > > Only set if your IdP requires an exact-match redirect port. Entra accepts any.
2295> > > >
2296> > > > **oauth.additionalRedirectReferrerHosts** `string`
2297> > > >
2298> > > > Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
2299> > > >
2300> > > > > [accordion] More detail
2301> > > > >
2302> > > > > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
2303> > >
2304> > > > [tab] hosted
2305> > > >
2306> > > > Applies when `oauth.mode` is `hosted`. The in-app configuration window calls it **Anthropic-hosted client identity (requires Claude.ai sign-in)**.
2307> > > >
2308> > > > Always write `"mode": "hosted"`. Without it the object is read as Bring your own client, which needs `clientId` beside `authorizationServer`, so the app drops the entry.
2309> > > >
2310> > > > **oauth.clientId** `string`
2311> > > >
2312> > > > Filled in by Claude.ai: the URL of Anthropic’s hosted client-metadata document. Do not set it.
2313> > > >
2314> > > > **oauth.authorizationServer** `string[]` *required*
2315> > > >
2316> > > > The exact issuer string(s) that the server’s authorization server advertises, as a JSON array. Anthropic signs the identity only for these.
2317> > > >
2318> > > > **oauth.scope** `string`
2319> > > >
2320> > > > Space-separated scopes to request. Unset: the scopes the server advertises. Required if Tenant ID is set or the resource parameter omitted.
2321> >
2322> > **headers** `object: name → value`
2323> >
2324> > Static headers sent on every request: routing and tenant headers only. No credentials here: use the headers helper script for those.
2325> >
2326> > **headersHelper** `string`
2327> >
2328> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2329> >
2330> > Absolute path to an executable that prints a JSON object of HTTP headers on stdout. Merged over static headers; the helper wins on conflict.
2331> >
2332> > > [accordion] More detail
2333> > >
2334> > > The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2335> >
2336> > **headersHelperArgs** `string[]`
2337> >
2338> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2339> >
2340> > Arguments passed to the headers helper script, one per entry, in order. Leave unset to run it with none.
2341> >
2342> > > [accordion] More detail
2343> > >
2344> > > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2345> > > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2346> > > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2347> >
2348> > **headersHelperTtlSec** `integer`
2349> >
2350> > How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300.
2351> >
2352> > **headersHelperRefreshBufferSec** `integer`
2353> >
2354> > Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime.
2355> >
2356> > **platformOverrides** `object`
2357> >
2358> > On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2359> >
2360> > > [accordion] More detail
2361> > >
2362> > > A value written here replaces the entry's value whole: lists and maps are not merged.
2363> > >
2364> > > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2365> > > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2366> > > * A mistake under any operating system drops the server on all of them.
2367> > > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2368> >
2369> > > [accordion] Child attributes (3)
2370> > >
2371> > > **platformOverrides.win32** `object: name → value`
2372> > >
2373> > > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2374> > >
2375> > > **platformOverrides.darwin** `object: name → value`
2376> > >
2377> > > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2378> > >
2379> > > **platformOverrides.linux** `object: name → value`
2380> > >
2381> > > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2382> >
2383> > **toolTimeoutSec** `integer`
2384> >
2385> > Maximum time in seconds that Claude waits for one tool call to this server. Leave empty to use the MCP tool call timeout.
2386> >
2387> > > [accordion] More detail
2388> > >
2389> > > For Claude's calls to this server it takes the place of `mcpToolTimeoutSec`. Use a whole number from 5 to 3600: any other value is ignored.
2390> > >
2391> > > * Progress messages from the server do not extend the limit.
2392> > > * Time that a user spends on a sign-in or consent step during the call counts toward the limit. On a server that asks for sign-in, set a generous value.
2393> >
2394> > **icon** `string`
2395> >
2396> > Icon shown for this connector: a PNG or JPEG image as a base64 data: URI, at most 4,096 characters.
2397> >
2398> > > [accordion] More detail
2399> > >
2400> > > A PNG of 48 by 48 pixels or smaller works well. Keep icons small: Windows Group Policy holds the whole `managedMcpServers` list in one value of at most 65,535 characters.
2401> >
2402> > **defaultState** `enum`
2403> >
2404> > Whether this connector starts on or off for each person.
2405> >
2406> > One of: `on`, `off`
2407> >
2408> > > [accordion] More detail
2409> > >
2410> > > Unset means `on`.
2411> > >
2412> > > * This is a starting point, not a restriction: each user can turn the connector on. To withhold a connector, remove it or block its tools with `toolPolicy`.
2413> > > * Adding `off` to a connector already in use turns it off for all users who have not switched it on themselves, scheduled tasks included.
2414> > > * This setting does not apply to a plugin's server that matches this entry.
2415>
2416> > [tab] stdio
2417> >
2418> > Applies when `transport` is `stdio`. The in-app configuration window calls it **Local command (stdio)**.
2419> >
2420> > **transport** `string` *required*
2421> >
2422> > How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2423> >
2424> > Must be: `stdio`
2425> >
2426> > **command** `string` *required*
2427> >
2428> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2429> >
2430> > Absolute path to the server executable, run on the user’s machine.
2431> >
2432> > **args** `string[]`
2433> >
2434> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2435> >
2436> > Arguments passed to the command, one per entry.
2437> >
2438> > **env** `object: name → value`
2439> >
2440> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2441> >
2442> > Environment variables set for the command.
2443> >
2444> > **envHelper** `string`
2445> >
2446> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2447> >
2448> > Script that prints environment variables as a JSON object to stdout. Runs when the local server starts (cached for the TTL below).
2449> >
2450> > > [accordion] More detail
2451> > >
2452> > > * Its values take priority over `env`.
2453> > > * If the script fails, the server does not start.
2454> > > * A script with nothing to set must print `{}`. Empty output counts as a failure.
2455> > > * The helper script normally runs with `CLAUDE_CODE_MCP_SERVER_NAME` set to this entry's `name`, so one script can serve several servers. Put the variable in double quotes, compare it with the names you expect, and do not pass it to another command.
2456> >
2457> > **envHelperArgs** `string[]`
2458> >
2459> > Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)
2460> >
2461> > Arguments passed to the environment helper script, one per entry, in order. Leave unset to run it with none.
2462> >
2463> > > [accordion] More detail
2464> > >
2465> > > * On every platform, an argument cannot be empty or contain a double quote, a percent sign or a control character.
2466> > > * Do not put secrets in arguments. They are visible in the app log and to other processes on the device.
2467> > > * Have the script fail when a needed argument is missing. An app version that does not know this setting passes none.
2468> >
2469> > **envHelperTtlSec** `integer` (default: 300)
2470> >
2471> > Maximum age of a cached helper result, in seconds (default 300). Applies when the server starts or restarts.
2472> >
2473> > > [accordion] More detail
2474> > >
2475> > > Set this at or below your token lifetime. Otherwise a server that crashes because its token expired can restart with the same cached values until this time is up.
2476> >
2477> > **startupTimeoutSec** `integer` (default: 120)
2478> >
2479> > Maximum wait in seconds for the server to start and list its tools.
2480> >
2481> > **platformOverrides** `object`
2482> >
2483> > On that operating system, each setting here replaces the entry’s own. A setting left out keeps the entry’s.
2484> >
2485> > > [accordion] More detail
2486> > >
2487> > > A value written here replaces the entry's value whole: lists and maps are not merged.
2488> > >
2489> > > * A local (`stdio`) entry can repeat `command`, `args`, `env`, `envHelper` and `envHelperArgs`. It always needs its own `command` too.
2490> > > * A remote or web search entry can repeat `headersHelper` and `headersHelperArgs`. If it gives `headersHelper` here, it needs its own too.
2491> > > * A mistake under any operating system drops the server on all of them.
2492> > > * An older version ignores this setting and runs the entry's own values. Until all devices are updated, put the Windows values in the entry itself.
2493> >
2494> > > [accordion] Child attributes (3)
2495> > >
2496> > > **platformOverrides.win32** `object: name → value`
2497> > >
2498> > > On Windows, these replace the entry’s own settings. A setting left out keeps the entry’s.
2499> > >
2500> > > **platformOverrides.darwin** `object: name → value`
2501> > >
2502> > > On macOS, these replace the entry’s own settings. A setting left out keeps the entry’s.
2503> > >
2504> > > **platformOverrides.linux** `object: name → value`
2505> > >
2506> > > On Linux, these replace the entry’s own settings. A setting left out keeps the entry’s.
2507> >
2508> > **toolTimeoutSec** `integer`
2509> >
2510> > Maximum time in seconds that Claude waits for one tool call to this server. Leave empty to use the MCP tool call timeout.
2511> >
2512> > > [accordion] More detail
2513> > >
2514> > > For Claude's calls to this server it takes the place of `mcpToolTimeoutSec`. Use a whole number from 5 to 3600: any other value is ignored.
2515> > >
2516> > > * Progress messages from the server do not extend the limit.
2517> > > * Time that a user spends on a sign-in or consent step during the call counts toward the limit. On a server that asks for sign-in, set a generous value.
2518> >
2519> > **icon** `string`
2520> >
2521> > Icon shown for this connector: a PNG or JPEG image as a base64 data: URI, at most 4,096 characters.
2522> >
2523> > > [accordion] More detail
2524> > >
2525> > > A PNG of 48 by 48 pixels or smaller works well. Keep icons small: Windows Group Policy holds the whole `managedMcpServers` list in one value of at most 65,535 characters.
2526>
2527> > [tab] policy-only
2528> >
2529> > Applies when `transport` is `policy-only`. The in-app configuration window calls it **Tool permissions only (plugin server)**.
2530> >
2531> > **transport** `string` *required*
2532> >
2533> > How the app connects: HTTP, legacy SSE or a local command (stdio). policy-only connects to nothing: it sets a plugin server’s tool policy.
2534> >
2535> > Must be: `policy-only`
2536> >
2537> > > [accordion] More detail
2538> > >
2539> > > For a `policy-only` entry:
2540> > >
2541> > > * Set `name` to the server's name as the plugin declares it (letter case is ignored), and `toolPolicy` to the permissions. A name that matches no installed plugin server does nothing.
2542> > > * It takes priority over `orgPluginSettings` for that server. With no `toolPolicy`, the server is left unrestricted.
2543> > > * An older version drops the entry and applies `orgPluginSettings` instead. Until all devices are updated, keep the same permissions there, and do not deploy a list made only of `policy-only` entries.
25442544
25452545***
25462546
from line 2550
25502550
25512551**Allow persistent tool approvals.** Offer the persistent “Always allow” approval options for MCP tools. Disable to keep tool approvals per-call or session-scoped only.
25522552
2553> **More detail**
2553> [accordion] More detail
25542554>
25552555> When off, persistent approvals that users saved earlier in Chat and Cowork stop applying. Scheduled tasks also stop offering and reusing them, unless `mcpScheduledTaskApprovalLifetimeDays` is 1 or more.
25562556>
from line 2564
25642564
25652565**Scheduled-task tool approval lifetime.** Days a scheduled task can reuse a persistent MCP tool approval before it asks again. 0 turns reuse off. Unset: no limit.
25662566
2567> **More detail**
2567> [accordion] More detail
25682568>
25692569> * If `mcpPersistentAlwaysAllowEnabled` is off, a limit of 1 or more brings the persistent option back for scheduled tasks only.
25702570> * In Code, any allow rule in a user's or a project's Claude Code settings keeps allowing the tool, even at `0`, until it is removed. Earlier approvals were usually saved as such rules.
from line 2578
25782578
25792579**Allow local MCP servers.** Lets users run local (stdio) MCP servers added in Developer settings. On third-party deployments, off also stops plugins’ local servers.
25802580
2581> **More detail**
2581> [accordion] More detail
25822582>
25832583> On third-party deployments, `false` covers `.mcpb` bundles and plugins from every marketplace, your organization's included. Plugins in the org-plugins directory on the device are not affected. In Code, it also stops the local servers that a user or a project configures for Claude Code.
25842584>
from line 2594
25942594
25952595**Allowed plugin MCP servers.** Remote MCP servers that user-installed and marketplace plugins can connect, as URL patterns. Empty list: none. Unset: no limit.
25962596
2597> **More detail**
2597> [accordion] More detail
25982598>
25992599> * **Entries:** `{"serverUrl": "https://*.example.com/*"}`. No other entry form is read.
26002600> * **Once set:** no entry allows a plugin's local (`stdio`) server, and servers that a user or a project configures for Claude Code are not connected.
from line 2602
26022602>
26032603> Claude Code's own managed settings, where a session has any, take priority by default.
26042604
2605> **Child attributes (1)**
2605> [accordion] Child attributes (1)
26062606>
26072607> **serverUrl** `string` *required*
26082608>
from line 2616
26162616
26172617**Blocked plugin MCP servers.** URL patterns of remote MCP servers that plugins cannot connect, even if the Allowed plugin MCP servers list allows them.
26182618
2619> **More detail**
2619> [accordion] More detail
26202620>
26212621> An entry matches an address, not a server. The same server under another host name or IP address, or behind a plugin's local server, is not matched. To keep a plugin's servers out whatever address they use, set `allowedPluginMcpServers`.
26222622>
from line 2626
26262626>
26272627> Claude Code's own managed settings, where a session has any, take priority by default.
26282628
2629> **Child attributes (1)**
2629> [accordion] Child attributes (1)
26302630>
26312631> **serverUrl** `string` *required*
26322632>
from line 2640
26402640
26412641**MCP tool call timeout.** Per-call timeout for MCP tool calls, in seconds. Unset: 180 in Chat and Cowork.
26422642
2643> **More detail**
2643> [accordion] More detail
26442644>
26452645> * **Unset:** Chat and Cowork use 180 seconds, and the app sets no timeout in Code. Calls to user-added local servers are also limited to 60 seconds.
26462646> * **Set:** the value applies in Code too.
from line 2659
26592659
26602660One of: `auto` (default), `disabled`, `required`
26612661
2662> **More detail**
2662> [accordion] More detail
26632663>
26642664> The OS identity broker is Web Account Manager on Windows and the Company Portal SSO extension on macOS. Linux has no broker, so `required` is not supported there.
26652665>
from line 2677
26772677
26782678One of: `enabled`, `disabled` (default)
26792679
2680> **More detail**
2680> [accordion] More detail
26812681>
26822682> It needs both of these:
26832683>
from line 2698
26982698
26992699**Allow desktop extensions.** Let Claude Desktop load desktop extensions (.dxt and .mcpb files). Unset: on where users sign in with Claude.ai.
27002700
2701> **More detail**
2701> [accordion] More detail
27022702>
27032703> In a third-party deployment, turning this on loads extensions that are already installed. Users cannot install new ones.
27042704
from line 2722
27222722
27232723[Admin Console](#the-works-with-column): Set automatically.
27242724
2725> **More detail**
2725> [accordion] More detail
27262726>
27272727> If unset, the app uses the organization of your Anthropic sign-in, where the connection has one. Otherwise, local data is stored under a placeholder UUID shared with other unconfigured deployments. Telemetry is then tagged with a value the app derives from your connection settings, or with that placeholder.
27282728>
from line 2738
27382738
27392739[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/telemetry.md#essential-telemetry)
27402740
2741> **More detail**
2741> [accordion] More detail
27422742>
27432743> Reports include **crash stacks**, **startup failure reasons**, **version/OS metadata**, and **crash dumps** (each an unfiltered copy of part of the app's memory). They carry a random install ID and an organization ID, which the app picks if you set none (see `deploymentOrganizationUuid`).
27442744>
from line 2761
27612761
27622762[Guide for this setting](https://claude.com/docs/third-party/claude-desktop/telemetry.md#non-essential-telemetry)
27632763
2764> **More detail**
2764> [accordion] More detail
27652765>
27662766> Applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set `disableDeploymentModeChooser` so the app stays in third-party mode.
27672767
from line 2773
27732773
27742774**Block nonessential services.** Connector icons, hosted artifact previews, MCP Apps widgets and the Linux spellcheck dictionary. Widgets fall back to text.
27752775
2776> **More detail**
2776> [accordion] More detail
27772777>
27782778> With this on:
27792779>
from line 2803
28032803
28042804One of: `http/protobuf` (default), `http/json`, `grpc`
28052805
2806> **More detail**
2806> [accordion] More detail
28072807>
28082808> With `grpc`, some exports still go over HTTP to the same endpoint, such as the app's own events.
28092809>
from line 2827
28272827
28282828One of: `none`, `inference-credential`
28292829
2830> **More detail**
2830> [accordion] More detail
28312831>
28322832> The credential can also make model requests as the user. For a collector you do not operate, use `otlpHeadersHelper` with a credential that can only send telemetry.
28332833>
from line 2845
28452845
28462846**OTLP headers helper script.** Full path to a helper script that prints collector headers as JSON. They take priority over OTLP headers and Collector authentication.
28472847
2848> **More detail**
2848> [accordion] More detail
28492849>
28502850> The app runs it with no arguments. Sample output: `{"Authorization": "Bearer …"}`.
28512851>
from line 2861
28612861
28622862**Resource attributes.** Extra attributes to attach to every span, metric and log. An enduser.id set here takes priority over the signed-in user’s identity.
28632863
2864> **More detail**
2864> [accordion] More detail
28652865>
28662866> `process.owner` (the OS login name) is always sent to your collector. Set it here to replace the value.
28672867
from line 2885
28852885
28862886Any of: `userPrompts`, `assistantResponses`, `toolDetails`, `toolContent`, `rawApiBodies`
28872887
2888> **More detail**
2888> [accordion] More detail
28892889>
28902890> This data never reaches Anthropic.
28912891>
from line 2907
29072907
29082908**Export traces.** Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session tracing.
29092909
2910> **More detail**
2910> [accordion] More detail
29112911>
29122912> Has no effect without `otlpEndpoint`. With it set, this key alone decides whether Cowork tasks and Code sessions export traces. Unset or `false` keeps traces off even if a user's or a project's Claude Code settings, or managed settings, turn tracing on.
29132913
from line 2919
29192919
29202920**Telemetry attribute length limit.** Maximum length, in characters, of captured content such as a raw API body. Unset: 61,440 in Cowork tasks and Code sessions.
29212921
2922> **More detail**
2922> [accordion] More detail
29232923>
29242924> In Cowork tasks and Code sessions it applies to model responses, tool content and raw API bodies, not to user prompts.
29252925>
from line 2939
29392939
29402940**Block auto-updates.** Stop Claude Desktop from fetching updates entirely (no time limit). You’ll need to push new versions yourself.
29412941
2942> **More detail**
2942> [accordion] More detail
29432943>
29442944> When you install a newer version while Claude is open, the app shows a restart notice in the sidebar. To have Claude restart by itself if nobody restarts it, use `installedUpdateEnforcementEnabled`.
29452945>
from line 2955
29552955
29562956**Restart to apply installed updates.** With auto-updates blocked, Claude restarts by itself for a newer version installed while it was open. On Windows it may stay closed.
29572957
2958> **More detail**
2958> [accordion] More detail
29592959>
29602960> `installedUpdateEnforcementHours` sets how long the app waits.
29612961>
from line 2972
29722972
29732973**Installed-update enforcement window.** Hours before Claude restarts for a newer version installed while it was open. Unset: 72 hours, then when idle. A number skips the idle wait.
29742974
2975> **More detail**
2975> [accordion] More detail
29762976>
29772977> Applies only while `disableAutoUpdates` is on and the restart is on (see `installedUpdateEnforcementEnabled`).
29782978>
from line 2990
29902990
29912991**Auto-update enforcement window.** Hours before a downloaded update force-installs. Only applies when auto-updates are enabled. Blank = 72-hour default.
29922992
2993> **More detail**
2993> [accordion] More detail
29942994>
29952995> * **Unset:** after 72 hours the app restarts once the device has been idle for 10 minutes.
29962996> * **Any number, even 72:** the app restarts when the time is up, whether or not the user is active.
from line 3007
30073007
30083008**Check for updates on releases.claude.com.** Read the update feed from releases.claude.com so api.anthropic.com can stay blocked.
30093009
3010> **More detail**
3010> [accordion] More detail
30113011>
30123012> The installer still downloads from `downloads.claude.ai`, so keep that host open.
30133013>
from line 3025
30253025
30263026One of: `stable` (default), `staggered`
30273027
3028> **More detail**
3028> [accordion] More detail
30293029>
30303030> `staggered` usually updates on Thursdays and is typically 7 to 14 days behind `stable`.
30313031>
from line 3046
30463046
30473047**Configuration relaunch window.** Hours users can keep working after a configuration change that needs a restart. 0: restart required at once. Unset: 24 hours.
30483048
3049> **More detail**
3049> [accordion] More detail
30503050>
30513051> When the time is up, a restart dialog blocks the app. The app then restarts by itself after 2 minutes with no activity and no running task.
30523052>
from line 3062
30623062
30633063**Configuration re-check interval.** Minutes between the running app’s checks for a changed managed configuration. Blank = 10 minutes.
30643064
3065> **More detail**
3065> [accordion] More detail
30663066>
30673067> A change that needs a restart starts the `relaunchEnforcementHours` countdown.
30683068>
from line 3080
30803080
30813081**Keep only your organization ID and restrictions on disk.** Between launches, keep on disk only your organization ID and restrictions, not its name or anything you have allowed.
30823082
3083> **More detail**
3083> [accordion] More detail
30843084>
30853085> While this is on, the app's crash reporting does not start on these devices. Error stack traces and performance timings still leave these devices unless `disableEssentialTelemetry` is on.
30863086>
from line 3100
31003100
31013101**Chat retention period.** Delete chats, with their files, after this many days without activity. Unset: no deletion. Projects and memory stay.
31023102
3103> **More detail**
3103> [accordion] More detail
31043104>
31053105> Applies only while the app runs in third-party mode. Deletion can start shortly after the app gets this configuration. Pinned sessions are not exempt. Opening an old chat or Cowork task without continuing it does not reliably keep it.
31063106>
from line 3122
31223122
31233123**Cowork retention period.** Delete Cowork tasks, with their uploads and outputs, after this many days without activity. Unset: no deletion. Spaces and memory stay.
31243124
3125> **More detail**
3125> [accordion] More detail
31263126>
31273127> Applies only while the app runs in third-party mode. Deletion can start shortly after the app gets this configuration. Pinned sessions are not exempt. Opening an old chat or Cowork task without continuing it does not reliably keep it.
31283128>
from line 3144
31443144
31453145**Code retention period.** Delete Code sessions, conversation included, after this many days without activity. Unset: no deletion. Uncommitted work stays on disk.
31463146
3147> **More detail**
3147> [accordion] More detail
31483148>
31493149> Applies only while the app runs in third-party mode. Deletion can start shortly after the app gets this configuration. Pinned sessions are not exempt. Opening an old chat or Cowork task without continuing it does not reliably keep it.
31503150>
from line 3166
31663166
31673167**Suspend session deletion.** Suspend the chat, Cowork and Code retention periods (legal hold). Claude Code’s own transcript cleanup (cleanupPeriodDays) still runs.
31683168
3169> **More detail**
3169> [accordion] More detail
31703170>
31713171> Meant to be set per user or group.
31723172>
from line 3185
31853185
31863186**Max tokens per window.** Caps each user’s input and output tokens per window. Cached tokens do not count, so it does not cap your bill. Unset: no limit.
31873187
3188> **More detail**
3188> [accordion] More detail
31893189>
31903190> Has no effect unless `inferenceTokenWindowHours` is also set. A user with two devices can have a separate count on each.
31913191
from line 3197
31973197
31983198**Token cap window.** Length of each token cap window, in hours. The count resets to zero when a window ends.
31993199
3200> **More detail**
3200> [accordion] More detail
32013201>
32023202> Used with `inferenceMaxTokensPerWindow`. Each user's window starts the first time they use the app after their previous window ends. So 24 hours does not mean midnight to midnight.
32033203
from line 3209
32093209
32103210**Token limit warning.** Warn users once they have used this percent of their token limit. Unset: 75. At 100, the only warning comes at the limit.
32113211
3212> **More detail**
3212> [accordion] More detail
32133213>
32143214> Has no effect unless `inferenceMaxTokensPerWindow` and `inferenceTokenWindowHours` are both set.
32153215>
from line 3225
32253225
32263226**End-user attribution.** Show the signed-in user’s identity in the app, add it to Claude’s system prompt, and send it to your OpenTelemetry collector as enduser.id.
32273227
3228> **More detail**
3228> [accordion] More detail
32293229>
32303230> The identity comes from the user's sign-in, or is the OS login name when sign-in gives none. A static `enduser.id` in `otlpResourceAttributes` takes priority in telemetry, and is sent even when this setting is off.
32313231>
from line 3267
32673267
32683268**Organization banner.** A persistent banner across the top of the app window after sign-in.
32693269
3270> **Child attributes (5)**
3270> [accordion] Child attributes (5)
32713271>
32723272> **enabled** `boolean`
32733273>
from line 3301
33013301
33023302**Status line.** Claude runs this program and shows the first line it prints above the message box in Cowork, Chat and Code. Off unless set.
33033303
3304> **More detail**
3304> [accordion] More detail
33053305>
33063306> * **Runs:** on the user's device, as the signed-in user, when a session opens, a turn ends, the app regains focus or the model changes.
33073307> * **Input:** one JSON line on standard input: `{"session_id": "…", "model": {"id": "…", "display_name": "…"}}`. Fields with no value are left out.
33083308> * **Output:** Claude shows the first non-empty line, up to 200 characters. ANSI codes 31 to 36 and 91 to 96 set the color.
33093309> * **Limits:** 10 seconds and 64 KiB of output. Past either, Claude stops the program.
33103310
3311> **Child attributes (1)**
3311> [accordion] Child attributes (1)
33123312>
33133313> **command** `string` *required*
33143314>
33153315> Full local path to the program or executable script.
33163316>
3317> > **More detail**
3317> > [accordion] More detail
33183318> >
33193319> > Users must not be able to change the file.
33203320> >
from line 3345
33453345
33463346**Plugin marketplaces.** Git repositories or hosted marketplace.json files shown as plugin marketplaces in the Directory’s Organization tab.
33473347
3348> **Child attributes**
3348> [accordion] Child attributes
33493349>
33503350> **expectedName** `string`
33513351>
33523352> Rejects the marketplace if its manifest name differs.
33533353>
3354> > **More detail**
3354> > [accordion] More detail
33553355> >
33563356> > Also use it to move a marketplace. A change to an entry's `url`, `repo` or `path` (not `ref`) counts as removing the marketplace, which uninstalls the plugins that users installed from it.
33573357> >
from line 3363
33633363>
33643364> One of: `available`, `auto_install`, `required`
33653365>
3366> > **More detail**
3366> > [accordion] More detail
33673367> >
33683368> > * `available` (default): users install from the Directory's Organization tab.
33693369> > * `auto_install`: installs once per pin. A plugin that a user removes stays removed until the pin changes.
from line 3377
33773377>
33783378> Executable that prints the access token to send.
33793379>
3380> > **More detail**
3380> > [accordion] More detail
33813381> >
33823382> > The helper script prints a token. It is sent as the Git password for user `x-access-token`, which GitHub, GitLab and Azure DevOps accept. For `url` sources it is sent as `Authorization: Bearer`.
33833383> >
33843384> > [Marketplace credentials](https://claude.com/docs/third-party/claude-desktop/extensions.md#marketplace-credentials) lists other forms, for hosts that need a username or for custom HTTP headers.
33853385>
3386> **github**
3387>
3388> Applies when `source` is `github`. The in-app configuration window calls it **GitHub**.
3389>
3390> **source** `string` *required*
3391>
3392> Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3393>
3394> Must be: `github`
3395>
3396> **repo** `string` *required*
3397>
3398> GitHub repository in owner/repo form. Case-insensitive.
3399>
3400> **ref** `string`
3401>
3402> Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA.
3403>
3404> **path** `string`
3405>
3406> Folder within the repository that contains the marketplace, when it isn’t at the root.
3407>
3408> **credentialKind** `enum`
3409>
3410> Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3411>
3412> One of: `anonymous`, `userGit`, `credentialHelper`
3413>
3414> **git**
3415>
3416> Applies when `source` is `git`. The in-app configuration window calls it **Git URL**.
3417>
3418> **source** `string` *required*
3419>
3420> Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3421>
3422> Must be: `git`
3423>
3424> **url** `string` *required*
3425>
3426> HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url).
3427>
3428> > **More detail**
3429> >
3430> > For a `url` source, `marketplace.json` lists each plugin as an `archive`: a zip `url` plus its `sha256`. [Host the marketplace over HTTPS](https://claude.com/docs/third-party/claude-desktop/extensions.md#host-the-marketplace-over-https-instead-of-git) has an example.
3431> >
3432> > * Archives must be on the same origin as the manifest. Open that host on your firewall. A credential is sent only to it.
3433> > * With `credentialKind` set to `inferenceCredential`, the manifest must be on your gateway's or bootstrap server's origin.
3434>
3435> **ref** `string`
3436>
3437> Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA.
3438>
3439> **path** `string`
3440>
3441> Folder within the repository that contains the marketplace, when it isn’t at the root.
3442>
3443> **credentialKind** `enum`
3444>
3445> Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3446>
3447> One of: `anonymous`, `userGit`, `credentialHelper`
3448>
3449> **url**
3450>
3451> Applies when `source` is `url`. The in-app configuration window calls it **Marketplace URL**.
3452>
3453> **source** `string` *required*
3454>
3455> Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3456>
3457> Must be: `url`
3458>
3459> **url** `string` *required*
3460>
3461> HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url).
3462>
3463> > **More detail**
3464> >
3465> > For a `url` source, `marketplace.json` lists each plugin as an `archive`: a zip `url` plus its `sha256`. [Host the marketplace over HTTPS](https://claude.com/docs/third-party/claude-desktop/extensions.md#host-the-marketplace-over-https-instead-of-git) has an example.
3466> >
3467> > * Archives must be on the same origin as the manifest. Open that host on your firewall. A credential is sent only to it.
3468> > * With `credentialKind` set to `inferenceCredential`, the manifest must be on your gateway's or bootstrap server's origin.
3469>
3470> **manifestSha256** `string`
3471>
3472> SHA-256 of the marketplace.json to accept (url sources). Any other file is refused. Without it, auto\_install and required act as available.
3473>
3474> **credentialKind** `enum`
3475>
3476> Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3477>
3478> One of: `anonymous`, `userGit`, `credentialHelper`, `inferenceCredential`
3386> > [tab] github
3387> >
3388> > Applies when `source` is `github`. The in-app configuration window calls it **GitHub**.
3389> >
3390> > **source** `string` *required*
3391> >
3392> > Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3393> >
3394> > Must be: `github`
3395> >
3396> > **repo** `string` *required*
3397> >
3398> > GitHub repository in owner/repo form. Case-insensitive.
3399> >
3400> > **ref** `string`
3401> >
3402> > Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA.
3403> >
3404> > **path** `string`
3405> >
3406> > Folder within the repository that contains the marketplace, when it isn’t at the root.
3407> >
3408> > **credentialKind** `enum`
3409> >
3410> > Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3411> >
3412> > One of: `anonymous`, `userGit`, `credentialHelper`
3413>
3414> > [tab] git
3415> >
3416> > Applies when `source` is `git`. The in-app configuration window calls it **Git URL**.
3417> >
3418> > **source** `string` *required*
3419> >
3420> > Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3421> >
3422> > Must be: `git`
3423> >
3424> > **url** `string` *required*
3425> >
3426> > HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url).
3427> >
3428> > > [accordion] More detail
3429> > >
3430> > > For a `url` source, `marketplace.json` lists each plugin as an `archive`: a zip `url` plus its `sha256`. [Host the marketplace over HTTPS](https://claude.com/docs/third-party/claude-desktop/extensions.md#host-the-marketplace-over-https-instead-of-git) has an example.
3431> > >
3432> > > * Archives must be on the same origin as the manifest. Open that host on your firewall. A credential is sent only to it.
3433> > > * With `credentialKind` set to `inferenceCredential`, the manifest must be on your gateway's or bootstrap server's origin.
3434> >
3435> > **ref** `string`
3436> >
3437> > Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA.
3438> >
3439> > **path** `string`
3440> >
3441> > Folder within the repository that contains the marketplace, when it isn’t at the root.
3442> >
3443> > **credentialKind** `enum`
3444> >
3445> > Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3446> >
3447> > One of: `anonymous`, `userGit`, `credentialHelper`
3448>
3449> > [tab] url
3450> >
3451> > Applies when `source` is `url`. The in-app configuration window calls it **Marketplace URL**.
3452> >
3453> > **source** `string` *required*
3454> >
3455> > Where the marketplace comes from: a GitHub repository (set repo), a Git remote (set url) or a hosted marketplace.json file (set url).
3456> >
3457> > Must be: `url`
3458> >
3459> > **url** `string` *required*
3460> >
3461> > HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url).
3462> >
3463> > > [accordion] More detail
3464> > >
3465> > > For a `url` source, `marketplace.json` lists each plugin as an `archive`: a zip `url` plus its `sha256`. [Host the marketplace over HTTPS](https://claude.com/docs/third-party/claude-desktop/extensions.md#host-the-marketplace-over-https-instead-of-git) has an example.
3466> > >
3467> > > * Archives must be on the same origin as the manifest. Open that host on your firewall. A credential is sent only to it.
3468> > > * With `credentialKind` set to `inferenceCredential`, the manifest must be on your gateway's or bootstrap server's origin.
3469> >
3470> > **manifestSha256** `string`
3471> >
3472> > SHA-256 of the marketplace.json to accept (url sources). Any other file is refused. Without it, auto\_install and required act as available.
3473> >
3474> > **credentialKind** `enum`
3475> >
3476> > Sent with a fetch: nothing (unset), the user’s Git credential, a helper script’s output, or the gateway or bootstrap credential (url only).
3477> >
3478> > One of: `anonymous`, `userGit`, `credentialHelper`, `inferenceCredential`
34793479
34803480***
34813481
from line 3485
34853485
34863486**Organization plugin settings.** Locks tool permissions on the MCP servers that plugins provide.
34873487
3488> **More detail**
3488> [accordion] More detail
34893489>
34903490> * If a `managedMcpServers` entry is for the same server (same URL, otherwise same name), the entry here is ignored. Put the locks in that entry's `toolPolicy`.
34913491> * Update all devices first: an older version ignores this list and enforces no locks.
34923492> * Claude Code's own managed settings, where a session has any, take priority by default.
34933493
3494> **Child attributes (2)**
3494> [accordion] Child attributes (2)
34953495>
34963496> **serverName** `string` *required*
34973497>
from line 3501
35013501>
35023502> Per-tool approval locks for this server.
35033503>
3504> > **Child attributes (2)**
3504> > [accordion] Child attributes (2)
35053505> >
35063506> > **tools.toolName** `string` *required*
35073507> >
from line 3561
35613561
35623562[Admin Console](#the-works-with-column): Not available.
35633563
3564> **More detail**
3564> [accordion] More detail
35653565>
35663566> When unset, the bootstrap sign-in uses a device code on the bootstrap server's own origin.
35673567>
35683568> In an MDM profile, write this key as one JSON string. Separate values such as `bootstrapOidc.clientId` do not work: the app silently uses the device-code sign-in instead.
35693569
3570> **Child attributes (8)**
3570> [accordion] Child attributes (8)
35713571>
35723572> **clientId** `string` *required*
35733573>
from line 3603
36033603>
36043604> Space-separated hostnames also accepted as the referrer of the sign-in callback, besides the authorization URL’s host.
36053605>
3606> > **More detail**
3606> > [accordion] More detail
36073607> >
36083608> > If a callback is rejected for a referrer mismatch, the app log names the rejected host. Add that hostname here.
36093609
from line 3623
36233623
36243624[Admin Console](#the-works-with-column): Not available.
36253625
3626> **More detail**
3626> [accordion] More detail
36273627>
36283628> If `bootstrapOidc` is unset, the app treats these headers as sufficient authentication and requires no per-user sign-in for the bootstrap fetch.
36293629>
from line 3647
36473647
36483648[Admin Console](#the-works-with-column): Not available.
36493649
3650> **More detail**
3650> [accordion] More detail
36513651>
36523652> Example output: `{"Authorization": "Bearer …"}`. The app runs the helper script with no arguments and reuses its output for a few minutes.
36533653>
from line 3710
37103710
37113711The profiles below are illustrative examples rather than built-in presets, and the labels are descriptive only. Use them as starting points and adjust for your environment. Layer the inference-provider keys for your cloud on top of whichever profile you choose.
37123712
3713**Standard**
3714
3715Recommended for most enterprise deployments. Telemetry and auto-updates stay on so Anthropic can diagnose issues and ship fixes; users can extend Claude Desktop with their own connectors.
3716
3717| Key | Value |
3718| - | - |
3719| [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `<your-org-uuid>` |
3720| [`autoUpdaterEnforcementHours`](#autoupdaterenforcementhours) | `24` |
3721| [`isDesktopExtensionSignatureRequired`](#isdesktopextensionsignaturerequired) | `true` |
3722| [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
3723
3724**Restricted**
3725
3726For regulated environments that need to control what users can connect Claude Desktop to, while keeping Anthropic supportability.
3727
3728| Key | Value |
3729| - | - |
3730| [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `<your-org-uuid>` |
3731| [`disableDeploymentModeChooser`](#disabledeploymentmodechooser) | `true` |
3732| [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
3733| [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
3734| [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
3735| [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
3736| [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
3737| [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `["*.example.corp"]` |
3738| [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
3739
3740**Locked down**
3741
3742For air-gapped or maximally restricted environments. **The app's own traffic goes only to your inference endpoint and OTLP collector**, plus `downloads.claude.ai` for the VM bundle and Claude CLI binary at session start unless you deploy the [offline installer](https://claude.com/docs/third-party/claude-desktop/installation.md#offline-installation). Code sessions on Windows, and on Linux without Claude Code's sandbox dependencies, [run shell commands unsandboxed](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy), so those commands can reach any host your network allows. To prevent that, [turn off Code](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code) on those devices. With this profile, Anthropic receives no telemetry or logs from the app and does not deliver updates, so your team owns log collection and update distribution. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content still reaches Anthropic-operated infrastructure under this profile, as described under [Data handling by provider](https://claude.com/docs/third-party/claude-desktop/overview.md#data-handling-by-provider).
3743
3744| Key | Value |
3745| - | - |
3746| [`disableDeploymentModeChooser`](#disabledeploymentmodechooser) | `true` |
3747| [`disableEssentialTelemetry`](#disableessentialtelemetry) | `true` |
3748| [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
3749| [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
3750| [`disableAutoUpdates`](#disableautoupdates) | `true` |
3751| [`modelCatalogEnabled`](#modelcatalogenabled) | `false` |
3752| [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
3753| [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
3754| [`skillCreationEnabled`](#skillcreationenabled) | `false` |
3755| [`userPluginMarketplacesEnabled`](#userpluginmarketplacesenabled) | `false` |
3756| [`userPluginUploadsEnabled`](#userpluginuploadsenabled) | `false` |
3757| [`scheduledTasksEnabled`](#scheduledtasksenabled) | `false` |
3758| [`disabledBuiltinTools`](#disabledbuiltintools) | `["WebSearch","WebFetch"]` |
3759| [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `[]` |
3760| [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
3761| [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
3713> [tab] Standard
3714>
3715> Recommended for most enterprise deployments. Telemetry and auto-updates stay on so Anthropic can diagnose issues and ship fixes; users can extend Claude Desktop with their own connectors.
3716>
3717> | Key | Value |
3718> | - | - |
3719> | [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `<your-org-uuid>` |
3720> | [`autoUpdaterEnforcementHours`](#autoupdaterenforcementhours) | `24` |
3721> | [`isDesktopExtensionSignatureRequired`](#isdesktopextensionsignaturerequired) | `true` |
3722> | [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
3723
3724> [tab] Restricted
3725>
3726> For regulated environments that need to control what users can connect Claude Desktop to, while keeping Anthropic supportability.
3727>
3728> | Key | Value |
3729> | - | - |
3730> | [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `<your-org-uuid>` |
3731> | [`disableDeploymentModeChooser`](#disabledeploymentmodechooser) | `true` |
3732> | [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
3733> | [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
3734> | [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
3735> | [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
3736> | [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
3737> | [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `["*.example.corp"]` |
3738> | [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
3739
3740> [tab] Locked down
3741>
3742> For air-gapped or maximally restricted environments. **The app's own traffic goes only to your inference endpoint and OTLP collector**, plus `downloads.claude.ai` for the VM bundle and Claude CLI binary at session start unless you deploy the [offline installer](https://claude.com/docs/third-party/claude-desktop/installation.md#offline-installation). Code sessions on Windows, and on Linux without Claude Code's sandbox dependencies, [run shell commands unsandboxed](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy), so those commands can reach any host your network allows. To prevent that, [turn off Code](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code) on those devices. With this profile, Anthropic receives no telemetry or logs from the app and does not deliver updates, so your team owns log collection and update distribution. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content still reaches Anthropic-operated infrastructure under this profile, as described under [Data handling by provider](https://claude.com/docs/third-party/claude-desktop/overview.md#data-handling-by-provider).
3743>
3744> | Key | Value |
3745> | - | - |
3746> | [`disableDeploymentModeChooser`](#disabledeploymentmodechooser) | `true` |
3747> | [`disableEssentialTelemetry`](#disableessentialtelemetry) | `true` |
3748> | [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
3749> | [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
3750> | [`disableAutoUpdates`](#disableautoupdates) | `true` |
3751> | [`modelCatalogEnabled`](#modelcatalogenabled) | `false` |
3752> | [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
3753> | [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
3754> | [`skillCreationEnabled`](#skillcreationenabled) | `false` |
3755> | [`userPluginMarketplacesEnabled`](#userpluginmarketplacesenabled) | `false` |
3756> | [`userPluginUploadsEnabled`](#userpluginuploadsenabled) | `false` |
3757> | [`scheduledTasksEnabled`](#scheduledtasksenabled) | `false` |
3758> | [`disabledBuiltinTools`](#disabledbuiltintools) | `["WebSearch","WebFetch"]` |
3759> | [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `[]` |
3760> | [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
3761> | [`otlpEndpoint`](#otlpendpoint) | `<your-collector>` |
37623762
37633763### Tool permissions for managed MCP servers
37643764
37653765
No line in this hunk matches that.