One read of Claude Documentationclaude-docs-20261020T180705Z
246 pages moved out of 277 read.
Pages moved
246
significant first
Pages read
277
in this capture
Captured
18:07 UTC
Corpus hash
cf94986ff2f8
corpus-hash
What this read moved
226-246 of 246, page 10 of 10This capture is too large to show at once. Changes 226-246 of 246 are below, significant first; the rest are on the following screens.
third-party/claude-desktop/credential-helper Changed · +3 / -3 lines
from line 6
66
77Configure the helper with the `inferenceCredentialHelper` key; see the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) for the full list of helper-related keys.
88
9<Note>
10 `inferenceCredentialHelper` supplies credentials for the inference connection only. An MCP server deployed through [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) uses the separate per-server `headersHelper` key, which follows the same execution model but prints a flat JSON header map and has its own cache and renewal settings (`headersHelperTtlSec`, default 300, versus `inferenceCredentialHelperTtlSec`, default 3600). See [Short-lived credentials with a headers helper](/docs/third-party/claude-desktop/extensions#short-lived-credentials-with-a-headers-helper).
11</Note>
9> [!NOTE]
10>
11> `inferenceCredentialHelper` supplies credentials for the inference connection only. An MCP server deployed through [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) uses the separate per-server `headersHelper` key, which follows the same execution model but prints a flat JSON header map and has its own cache and renewal settings (`headersHelperTtlSec`, default 300, versus `inferenceCredentialHelperTtlSec`, default 3600). See [Short-lived credentials with a headers helper](/docs/third-party/claude-desktop/extensions#short-lived-credentials-with-a-headers-helper).
1212
1313## What the helper must do
1414
third-party/claude-desktop/data-storage Changed · +6 / -6 lines
from line 20
2020| Windows | `%LOCALAPPDATA%\Claude-3p\` | (under the application-data directory) |
2121| Linux | `~/.config/Claude-3p/` | (under the application-data directory) |
2222
23<Note>
24 On Windows, earlier Claude Desktop releases stored this data under `%APPDATA%\Claude-3p\` (the Roaming profile). On first launch after upgrading, the app moves the existing directory to `%LOCALAPPDATA%` automatically; if Roaming is redirected to a network share, conversation history and configuration are copied and large regenerable caches are re-downloaded. Update any external tooling, backup jobs, or endpoint policies that reference the old path. macOS paths are unchanged.
25</Note>
23> [!NOTE]
24>
25> On Windows, earlier Claude Desktop releases stored this data under `%APPDATA%\Claude-3p\` (the Roaming profile). On first launch after upgrading, the app moves the existing directory to `%LOCALAPPDATA%` automatically; if Roaming is redirected to a network share, conversation history and configuration are copied and large regenerable caches are re-downloaded. Update any external tooling, backup jobs, or endpoint policies that reference the old path. macOS paths are unchanged.
2626
2727Within the application-data directory:
2828
from line 127
127127
128128### Copy the data to the new device
129129
130<Warning>
131 The copy holds full conversations. Encrypt any intermediate copy, restrict access to it, and delete it when you're done.
132</Warning>
130> [!WARNING]
131>
132> The copy holds full conversations. Encrypt any intermediate copy, restrict access to it, and delete it when you're done.
133133
1341341. Quit Claude Desktop on both devices. Closing its window isn't enough.
1351352. If the new device has an application-data directory (see [Where data lives](#where-data-lives)), delete it. This removes anything the user created in it.
third-party/claude-desktop/extensions Changed · +52 / -60 lines
from line 20
2020
2121The **Connectors** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) provides a form for each server: name, per-tool policy, headers or a headers helper script, transport, and URL.
2222
23<Frame caption="A managed MCP server in the Connectors section of the in-app configuration window.">
24 <img src="https://mintcdn.com/claude-ai/JnLDSb03Rtghdgpj/images/third-party/config-window-managed-mcp.png?fit=max&auto=format&n=JnLDSb03Rtghdgpj&q=85&s=294cce4e42a951fc5479c36676c3b3b5" alt="In-app configuration window showing a managed MCP server named sentry, with fields for name, tool policy, headers, headers helper script, Streamable HTTP transport, and URL." width="1794" height="1432" data-path="images/third-party/config-window-managed-mcp.png" />
25</Frame>
23
2624
2725In the exported configuration, each server is one entry in the `managedMcpServers` array:
2826
from line 43
4543]
4644```
4745
48<Note>
49 Every entry other than a [built-in server](/docs/third-party/claude-desktop/built-in-connectors) needs a `transport`. Claude Desktop doesn't read `type`, the field name that a plugin's `.mcp.json` file uses. It drops an entry that has no `transport` and reports a configuration error.
50</Note>
46> [!NOTE]
47>
48> Every entry other than a [built-in server](/docs/third-party/claude-desktop/built-in-connectors) needs a `transport`. Claude Desktop doesn't read `type`, the field name that a plugin's `.mcp.json` file uses. It drops an entry that has no `transport` and reports a configuration error.
5149
5250See the [`managedMcpServers` schema](/docs/third-party/claude-desktop/configuration#managedmcpservers) in the configuration reference for every field, including static headers, OAuth, and the headers-helper executable for short-lived tokens.
5351
from line 103
105103
106104While the connection is open, the TTL schedule triggers renewal, and a request that the server rejects with HTTP 401 or 403 also re-runs the helper and, when it returns new headers, is retried once with them (Claude Desktop 1.46388.1 or later). A failed helper run does not interrupt the connection; Claude Desktop keeps the current headers and retries on its schedule. A failure while the server is connecting shows the server as needing authentication.
107105
108<Note>
109 Mid-session renewal requires Claude Desktop 1.21459.0 or later. Earlier versions run the helper only when the server connects.
110</Note>
106> [!NOTE]
107>
108> Mid-session renewal requires Claude Desktop 1.21459.0 or later. Earlier versions run the helper only when the server connects.
111109
112110### Supported MCP servers
113111
114112Any MCP server reachable from the user's device over HTTPS works with Claude Desktop on 3P, including public servers from third parties and internal servers you build and host (including on internal gateways).
115113
116<Note>
117 Claude Desktop does not present a TLS client certificate when connecting to MCP servers, so a server that requires mutual TLS (mTLS) client-certificate authentication fails to connect. Terminate the client-certificate requirement before the MCP endpoint (for example, at a gateway or reverse proxy), and authenticate the connection with headers or OAuth instead.
118</Note>
114> [!NOTE]
115>
116> Claude Desktop does not present a TLS client certificate when connecting to MCP servers, so a server that requires mutual TLS (mTLS) client-certificate authentication fails to connect. Terminate the client-certificate requirement before the MCP endpoint (for example, at a gateway or reverse proxy), and authenticate the connection with headers or OAuth instead.
119117
120118The [Claude connector directory](https://claude.com/connectors) is the canonical catalog of vetted servers. **Every connector in the directory that is not labeled "Made by Anthropic" is accessible in Claude Desktop on 3P** and can be deployed via `managedMcpServers` or installed by users. Connectors labeled "Made by Anthropic" are hosted on Anthropic infrastructure and are available only in standard Claude Desktop.
121119
122<Note>
123 Some connectors return [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), interactive widgets that Claude Desktop renders in place of a plain-text tool result. Each widget loads in a sandboxed iframe on `*.claudemcpcontent.com`, and setting [`disableNonessentialServices`](/docs/third-party/claude-desktop/configuration#disablenonessentialservices) to `true` blocks that origin, so Claude Desktop shows the connector's text result instead of the widget. The same key also blocks artifact previews and connector favicons. To keep MCP Apps rendering, leave `disableNonessentialServices` unset or `false`, and allow the widget hosts listed under [Required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths) at your perimeter firewall.
124</Note>
120> [!NOTE]
121>
122> Some connectors return [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), interactive widgets that Claude Desktop renders in place of a plain-text tool result. Each widget loads in a sandboxed iframe on `*.claudemcpcontent.com`, and setting [`disableNonessentialServices`](/docs/third-party/claude-desktop/configuration#disablenonessentialservices) to `true` blocks that origin, so Claude Desktop shows the connector's text result instead of the widget. The same key also blocks artifact previews and connector favicons. To keep MCP Apps rendering, leave `disableNonessentialServices` unset or `false`, and allow the widget hosts listed under [Required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths) at your perimeter firewall.
125123
126124### Productivity suites
127125
128126Google Workspace and Microsoft 365 each have a dedicated setup path:
129127
130<Columns cols={2}>
131 <Card title="Google Workspace" icon="google" href="https://developers.google.com/workspace/guides/configure-mcp-servers">
132 Gmail, Calendar, Drive, Docs, and more via Google's own Workspace MCP servers. See [Google's setup guide](https://developers.google.com/workspace/guides/configure-mcp-servers) to get started.
133 </Card>
128> **[Google Workspace](https://developers.google.com/workspace/guides/configure-mcp-servers)**
129>
130> Gmail, Calendar, Drive, Docs, and more via Google's own Workspace MCP servers. See [Google's setup guide](https://developers.google.com/workspace/guides/configure-mcp-servers) to get started.
134131
135 <Card title="Microsoft 365" icon="microsoft" href="/docs/third-party/claude-desktop/connectors-m365">
136 Outlook, OneDrive, SharePoint, and Teams. Requires registering an app in your Entra tenant. The remote connector also needs an Anthropic allowlist step.
137 </Card>
138</Columns>
132> **[Microsoft 365](/docs/third-party/claude-desktop/connectors-m365)**
133>
134> Outlook, OneDrive, SharePoint, and Teams. Requires registering an app in your Entra tenant. The remote connector also needs an Anthropic allowlist step.
139135
140136## Plugin marketplaces (admin)
141137
from line 195
199195
200196You can add marketplaces directly in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): in the **Plugins** section, click **Add marketplace** and choose **Blank**, **GitHub repo**, **Git URL**, or **Marketplace URL**. The form validates the entry and exports the encoded JSON for you.
201197
202<Frame caption="The Plugins section of the in-app configuration window, with the Add marketplace menu and the organization plugins folder.">
203 <img src="https://mintcdn.com/claude-ai/JnLDSb03Rtghdgpj/images/third-party/config-window-plugin-marketplaces.png?fit=max&auto=format&n=JnLDSb03Rtghdgpj&q=85&s=a9bdd6d5bdbf22716340aedf1cc2d16b" alt="In-app configuration window Plugins section showing the plugin marketplaces card with an open Add marketplace menu offering Blank, GitHub repo, and Git URL, above the organization plugins folder path with two loaded plugins." width="1792" height="1238" data-path="images/third-party/config-window-plugin-marketplaces.png" />
204</Frame>
198
205199
206200To write the configuration yourself instead, add the repository to the [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) configuration key. The key is read from an MDM profile, local configuration, or the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) response. In an MDM profile the value is a JSON array encoded as a string (see [Value types](/docs/third-party/claude-desktop/configuration#value-types)). In a local configuration file or the bootstrap response the value is a native JSON array.
207201
from line 233
239233| `"auto_install"` | Every plugin is installed automatically the first time the pinned `ref` is seen. Users can uninstall individual plugins; when you later change the `ref`, each plugin is installed again at the new revision. |
240234| `"required"` | Every plugin is installed automatically and re-asserted on every sync. Users cannot uninstall or disable required plugins. |
241235
242<Warning>
243 `"auto_install"` and `"required"` marketplaces must carry an admin-side content pin so the exact plugin content deployed to every device is deterministic and auditable. Git sources must set `ref` to a full 40-character commit SHA; Claude Desktop refuses to auto-install from a branch or tag name. `url` sources must set `manifestSha256` to the SHA-256 of the exact `marketplace.json` bytes and give every archive a `sha256`; Claude Desktop refuses a served manifest with a different digest and skips unpinned archives.
244</Warning>
236> [!WARNING]
237>
238> `"auto_install"` and `"required"` marketplaces must carry an admin-side content pin so the exact plugin content deployed to every device is deterministic and auditable. Git sources must set `ref` to a full 40-character commit SHA; Claude Desktop refuses to auto-install from a branch or tag name. `url` sources must set `manifestSha256` to the SHA-256 of the exact `marketplace.json` bytes and give every archive a `sha256`; Claude Desktop refuses a served manifest with a different digest and skips unpinned archives.
245239
246240#### Per-plugin auto-install from a trusted origin
247241
from line 282
288282
289283## Organization plugins (admin)
290284
291<Tip>
292 For most deployments, distribute organization plugins via a [plugin marketplace](#plugin-marketplaces-admin) instead. Marketplaces let you manage plugin content in git or on any HTTPS file host and roll out updates by changing a single configuration value, rather than pushing files to every device. Use the directory path below when end-user devices cannot reach a git server or an HTTPS file host.
293</Tip>
285> [!TIP]
286>
287> For most deployments, distribute organization plugins via a [plugin marketplace](#plugin-marketplaces-admin) instead. Marketplaces let you manage plugin content in git or on any HTTPS file host and roll out updates by changing a single configuration value, rather than pushing files to every device. Use the directory path below when end-user devices cannot reach a git server or an HTTPS file host.
294288
295289[Plugins](/docs/plugins/overview) bundle MCP connectors, skills, slash commands, hooks, and sub-agents into a single directory. On this path, admins distribute plugins by placing them in a system-wide directory on each device, typically via the same MDM or software-distribution channel used for the app itself. Plugins distributed this way are available in Cowork sessions and Chat conversations. Code sessions do not load their skills, commands, sub-agents, or hooks, so a plugin that must reach Code sessions has to be distributed through a [plugin marketplace](#plugin-marketplaces-admin) instead.
296290
from line 327
333327| `skills/` | [Skill](/docs/skills/overview) directories. |
334328| `hooks/` | Hook definitions that run on agent lifecycle events. See [Plugin hooks](#plugin-hooks) for where they run. |
335329
336<Note>
337 Each entry in `org-plugins/` must carry a valid manifest: a `.claude-plugin/plugin.json`, or a top-level `SKILL.md` whose frontmatter declares `agents` or `mcpServers` (a skill folder that also acts as a plugin). A plain skill folder does not qualify on its own. To distribute a single skill, place it under `skills/<name>/SKILL.md` in a plugin that has a `plugin.json`. A directory with no valid manifest is not loaded and never appears in the user's plugin browser. The diagnostic report's plugin section shows the rejected entry and why. To distribute an MCP connector, declare it in a plugin's `.mcp.json` or use [`managedMcpServers`](#managed-mcp-servers-admin).
338</Note>
330> [!NOTE]
331>
332> Each entry in `org-plugins/` must carry a valid manifest: a `.claude-plugin/plugin.json`, or a top-level `SKILL.md` whose frontmatter declares `agents` or `mcpServers` (a skill folder that also acts as a plugin). A plain skill folder does not qualify on its own. To distribute a single skill, place it under `skills/<name>/SKILL.md` in a plugin that has a `plugin.json`. A directory with no valid manifest is not loaded and never appears in the user's plugin browser. The diagnostic report's plugin section shows the rejected entry and why. To distribute an MCP connector, declare it in a plugin's `.mcp.json` or use [`managedMcpServers`](#managed-mcp-servers-admin).
339333
340334See the [plugins reference](https://code.claude.com/docs/en/plugins) for the full file format of each component, including the hooks schema.
341335
342<Note>
343 Symlinks inside a plugin are followed as long as the target resolves to a path inside the plugin directory. Symlinks that point outside the plugin (for example, `skills/foo/SKILL.md → /etc/hosts`) are skipped. A symlinked top-level plugin directory (for example, `org-plugins/my-plugin → /opt/shared/my-plugin`) is also followed.
344</Note>
336> [!NOTE]
337>
338> Symlinks inside a plugin are followed as long as the target resolves to a path inside the plugin directory. Symlinks that point outside the plugin (for example, `skills/foo/SKILL.md → /etc/hosts`) are skipped. A symlinked top-level plugin directory (for example, `org-plugins/my-plugin → /opt/shared/my-plugin`) is also followed.
345339
346<Note>
347 MCP servers declared in a plugin's `.mcp.json` don't carry a `toolPolicy` field in the plugin file itself. To lock tools on a plugin-delivered server, set [`orgPluginSettings`](/docs/third-party/claude-desktop/configuration#orgpluginsettings) in managed configuration, keyed on the server's `name`, or add a [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry with `"transport": "policy-only"`, the server's `name`, and a `toolPolicy`. A `policy-only` entry connects to nothing. It only applies the permissions, and it takes precedence over `orgPluginSettings` for that server. A regular `managedMcpServers` entry that matches a plugin's server by URL or name governs that server the same way.
348</Note>
340> [!NOTE]
341>
342> MCP servers declared in a plugin's `.mcp.json` don't carry a `toolPolicy` field in the plugin file itself. To lock tools on a plugin-delivered server, set [`orgPluginSettings`](/docs/third-party/claude-desktop/configuration#orgpluginsettings) in managed configuration, keyed on the server's `name`, or add a [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry with `"transport": "policy-only"`, the server's `name`, and a `toolPolicy`. A `policy-only` entry connects to nothing. It only applies the permissions, and it takes precedence over `orgPluginSettings` for that server. A regular `managedMcpServers` entry that matches a plugin's server by URL or name governs that server the same way.
349343
350344### Auto-installing organization plugins
351345
from line 434
440434
441435## Related topics
442436
443<Columns cols={2}>
444 <Card title="Code" icon="code" href="/docs/third-party/claude-desktop/code">
445 How extensions and managed settings reach the embedded Claude Code engine.
446 </Card>
437> **[Code](/docs/third-party/claude-desktop/code)**
438>
439> How extensions and managed settings reach the embedded Claude Code engine.
447440
448 <Card title="MCP in Claude Code" icon="terminal" href="https://code.claude.com/docs/en/mcp">
449 Configure MCP servers for the standalone Claude Code CLI.
450 </Card>
441> **[MCP in Claude Code](https://code.claude.com/docs/en/mcp)**
442>
443> Configure MCP servers for the standalone Claude Code CLI.
451444
452 <Card title="Claude Code plugins" icon="terminal" href="https://code.claude.com/docs/en/plugins">
453 Plugin structure, marketplaces, and management for Claude Code.
454 </Card>
445> **[Claude Code plugins](https://code.claude.com/docs/en/plugins)**
446>
447> Plugin structure, marketplaces, and management for Claude Code.
455448
456 <Card title="Managed MCP in Claude Code" icon="terminal" href="https://code.claude.com/docs/en/managed-mcp">
457 Restrict which MCP servers Claude Code users can add.
458 </Card>
459</Columns>
449> **[Managed MCP in Claude Code](https://code.claude.com/docs/en/managed-mcp)**
450>
451> Restrict which MCP servers Claude Code users can add.
460452
third-party/claude-desktop/feature-matrix Changed · +68 / -82 lines
from line 8
88
99The Claude Enterprise features in this table are enduring differences between Claude Enterprise and Claude Desktop on 3P. Anthropic doesn't have the technical ability to bring these features to Claude Desktop on 3P based on its local and third-party [architecture](/docs/third-party/claude-desktop/overview#architecture).
1010
11<div className="feature-compare">
12 | Feature | Claude Enterprise | Claude Desktop on 3P |
13 | - | :-: | :-: |
14 | [Connect to your cloud provider for inference](/docs/third-party/claude-desktop/configuration#connection) | <Icon icon="xmark" color="#9E9E9E" /> No | <Icon icon="circle-check" iconType="solid" /> **Yes** |
15 | [Data residency in multiple regions](/docs/third-party/claude-desktop/overview#data-residency-and-international-deployment) | <Icon icon="xmark" color="#9E9E9E" /> No | <Icon icon="circle-check" iconType="solid" /> **Yes** |
16 | [Conversation history stored on device](/docs/third-party/claude-desktop/data-storage#where-data-lives) | <Icon icon="xmark" color="#9E9E9E" /> No | <Icon icon="circle-check" iconType="solid" /> **Yes** |
17 | Mobile and claude.ai web-based access | <Icon icon="circle-check" iconType="solid" /> **Yes** | <Icon icon="xmark" color="#9E9E9E" /> No |
18 | Sessions in Anthropic's cloud | <Icon icon="circle-check" iconType="solid" /> **Yes** | <Icon icon="xmark" color="#9E9E9E" /> No |
19 | Sharing between users | <Icon icon="circle-check" iconType="solid" /> **Yes** | <Icon icon="xmark" color="#9E9E9E" /> No |
20 | Voice mode | <Icon icon="circle-check" iconType="solid" /> **Yes** | <Icon icon="xmark" color="#9E9E9E" /> No |
21 | Claude Security and [Claude Tag](/docs/claude-tag/overview) | <Icon icon="circle-check" iconType="solid" /> **Yes** | <Icon icon="xmark" color="#9E9E9E" /> No |
22</div>
11| Feature | Claude Enterprise | Claude Desktop on 3P |
12| - | :-: | :-: |
13| [Connect to your cloud provider for inference](/docs/third-party/claude-desktop/configuration#connection) | No | **Yes** |
14| [Data residency in multiple regions](/docs/third-party/claude-desktop/overview#data-residency-and-international-deployment) | No | **Yes** |
15| [Conversation history stored on device](/docs/third-party/claude-desktop/data-storage#where-data-lives) | No | **Yes** |
16| Mobile and claude.ai web-based access | **Yes** | No |
17| Sessions in Anthropic's cloud | **Yes** | No |
18| Sharing between users | **Yes** | No |
19| Voice mode | **Yes** | No |
20| Claude Security and [Claude Tag](/docs/claude-tag/overview) | **Yes** | No |
2321
2422## Features in Claude Desktop on 3P
2523
from line 25
2725
2826Claude Desktop on 3P is administered from the web-based [admin console](/docs/third-party/claude-desktop/admin-console), and can also be configured through [MDM](/docs/third-party/claude-desktop/mdm) or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap).
2927
30<Card title="Everyday work" icon="briefcase" color="#737373" horizontal>
31 <div className="feature-chips not-prose">
32 * [Chat](/docs/third-party/claude-desktop/chat)
33 * [Cowork](/docs/third-party/claude-desktop/configuration#coworktabenabled)
34 * Projects
35 * Artifacts
36 * [Memory](/docs/third-party/claude-desktop/data-storage#memory)
37 * [Scheduled tasks](/docs/third-party/claude-desktop/configuration#scheduledtasksenabled)
38 * [Code execution for analysis](/docs/third-party/claude-desktop/chat#advanced-file-analysis)
39 * [File access, upload, and export](/docs/third-party/claude-desktop/local-access)
40 * Global languages
41 * [Automatically approve in Cowork](/docs/third-party/claude-desktop/configuration#automodeenabled)
42 </div>
43</Card>
28> **Everyday work**
29>
30> * [Chat](/docs/third-party/claude-desktop/chat)
31> * [Cowork](/docs/third-party/claude-desktop/configuration#coworktabenabled)
32> * Projects
33> * Artifacts
34> * [Memory](/docs/third-party/claude-desktop/data-storage#memory)
35> * [Scheduled tasks](/docs/third-party/claude-desktop/configuration#scheduledtasksenabled)
36> * [Code execution for analysis](/docs/third-party/claude-desktop/chat#advanced-file-analysis)
37> * [File access, upload, and export](/docs/third-party/claude-desktop/local-access)
38> * Global languages
39> * [Automatically approve in Cowork](/docs/third-party/claude-desktop/configuration#automodeenabled)
4440
45<Card title="Web and browser" icon="globe" color="#737373" horizontal>
46 <div className="feature-chips not-prose">
47 * [Built-in browser](/docs/third-party/claude-desktop/browser#built-in-browser)
48 * [Web search](/docs/third-party/claude-desktop/web-tools#web-search)
49 * [Claude in Chrome](/docs/third-party/claude-desktop/browser#claude-in-chrome)
50 </div>
51</Card>
41> **Web and browser**
42>
43> * [Built-in browser](/docs/third-party/claude-desktop/browser#built-in-browser)
44> * [Web search](/docs/third-party/claude-desktop/web-tools#web-search)
45> * [Claude in Chrome](/docs/third-party/claude-desktop/browser#claude-in-chrome)
5246
53<Card title="Connectors and extensions" icon="plug" color="#737373" horizontal>
54 <div className="feature-chips not-prose">
55 * [Microsoft 365](/docs/third-party/claude-desktop/connectors-m365) and [GitHub](/docs/third-party/claude-desktop/connectors-github) connectors
56 * [Local MCP](/docs/third-party/claude-desktop/extensions#user-extensions)
57 * [Remote MCP](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin)
58 * [Skills, plugins, and hooks](/docs/third-party/claude-desktop/extensions)
59 * [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin)
60 </div>
61</Card>
47> **Connectors and extensions**
48>
49> * [Microsoft 365](/docs/third-party/claude-desktop/connectors-m365) and [GitHub](/docs/third-party/claude-desktop/connectors-github) connectors
50> * [Local MCP](/docs/third-party/claude-desktop/extensions#user-extensions)
51> * [Remote MCP](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin)
52> * [Skills, plugins, and hooks](/docs/third-party/claude-desktop/extensions)
53> * [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin)
6254
63<Card title="Code" icon="code" color="#737373" horizontal>
64 <div className="feature-chips not-prose">
65 * [Code](/docs/third-party/claude-desktop/code)
66 * [Auto mode in Code](/docs/third-party/claude-desktop/configuration#automodeenabled)
67 * [SSH remote Code sessions](/docs/third-party/claude-desktop/ssh-remote-sessions)
68 </div>
69</Card>
55> **Code**
56>
57> * [Code](/docs/third-party/claude-desktop/code)
58> * [Auto mode in Code](/docs/third-party/claude-desktop/configuration#automodeenabled)
59> * [SSH remote Code sessions](/docs/third-party/claude-desktop/ssh-remote-sessions)
7060
71<Card title="Administration" icon="sliders" color="#737373" horizontal>
72 <div className="feature-chips not-prose">
73 * [Admin console](/docs/third-party/claude-desktop/admin-console)
74 * [Endpoint or gateway configuration](/docs/third-party/claude-desktop/configuration#connection)
75 * [Skills, hooks, and plugins distribution](/docs/third-party/claude-desktop/extensions#organization-plugins-admin)
76 * [MCP server allowlist](/docs/third-party/claude-desktop/extensions#controlling-user-extensions)
77 * [Feature toggles](/docs/third-party/claude-desktop/configuration#capabilities)
78 * [Auto-updates](/docs/third-party/claude-desktop/installation#updates)
79 * [Per-user usage caps](/docs/third-party/claude-desktop/configuration#inferencemaxtokensperwindow)
80 * [User management via UI](/docs/third-party/claude-desktop/admin-console#connect-your-identity-provider)
81 * [RBAC](/docs/third-party/claude-desktop/admin-console#per-group-permission-policies)
82 </div>
83</Card>
61> **Administration**
62>
63> * [Admin console](/docs/third-party/claude-desktop/admin-console)
64> * [Endpoint or gateway configuration](/docs/third-party/claude-desktop/configuration#connection)
65> * [Skills, hooks, and plugins distribution](/docs/third-party/claude-desktop/extensions#organization-plugins-admin)
66> * [MCP server allowlist](/docs/third-party/claude-desktop/extensions#controlling-user-extensions)
67> * [Feature toggles](/docs/third-party/claude-desktop/configuration#capabilities)
68> * [Auto-updates](/docs/third-party/claude-desktop/installation#updates)
69> * [Per-user usage caps](/docs/third-party/claude-desktop/configuration#inferencemaxtokensperwindow)
70> * [User management via UI](/docs/third-party/claude-desktop/admin-console#connect-your-identity-provider)
71> * [RBAC](/docs/third-party/claude-desktop/admin-console#per-group-permission-policies)
8472
85<Card title="Monitoring and retention" icon="chart-line" color="#737373" horizontal>
86 <div className="feature-chips not-prose">
87 * [OpenTelemetry export](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector)
88 * [Turning off telemetry](/docs/third-party/claude-desktop/telemetry#telemetry-categories)
89 * [Data retention policies](/docs/third-party/claude-desktop/data-storage#automatic-deletion-of-idle-sessions)
90 </div>
91</Card>
73> **Monitoring and retention**
74>
75> * [OpenTelemetry export](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector)
76> * [Turning off telemetry](/docs/third-party/claude-desktop/telemetry#telemetry-categories)
77> * [Data retention policies](/docs/third-party/claude-desktop/data-storage#automatic-deletion-of-idle-sessions)
9278
9379## Good to know about Claude Desktop on 3P
9480
95<Accordion title="Notes on setup, limits, monitoring, and data handling">
96 | Topic | What to know |
97 | - | - |
98 | Sessions and scheduled tasks | Sessions are local, except [Code sessions over SSH](/docs/third-party/claude-desktop/ssh-remote-sessions), and the device must be awake to run long processes and scheduled tasks. |
99 | Memory | [Memory](/docs/third-party/claude-desktop/data-storage#memory) in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Chat-history search and nightly summary generation are not available in Chat on 3P. |
100 | Web search | Amazon Bedrock deployments and gateways that do not forward Anthropic server tools need a [web search provider](/docs/third-party/claude-desktop/web-tools#web-search-options) configured first. |
101 | Claude in Chrome | Claude in Chrome works with Claude Desktop on 3P only in organizations managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console). |
102 | Automatically approve in Cowork | Cowork offers the **Automatically approve** mode when an administrator sets [`autoModeEnabled`](/docs/third-party/claude-desktop/configuration#automodeenabled) to `true`. |
103 | User management via UI and RBAC | With the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), administrators add users and groups, connect single sign-on and SCIM, assign administrator roles, and set per-group permission policies from **Organization settings** on claude.ai. Deployments configured through MDM or a bootstrap server manage access through those channels. |
104 | Monitoring | Many capabilities of the Compliance API and Analytics API can be achieved via [OpenTelemetry export](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector) to your own collector. |
105 | Telemetry | Claude Desktop on 3P sends [crash reports and product analytics](/docs/third-party/claude-desktop/telemetry#telemetry-categories) to Anthropic by default. This telemetry contains no prompt or response content, and you can fully disable it via managed configuration. |
106 | Data handling | [Data handling](/docs/third-party/claude-desktop/overview#data-handling-by-provider) at the inference endpoint depends on the provider you configure. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by Google Cloud and Amazon Bedrock respectively. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](/docs/third-party/claude-desktop/claude-api) page. |
107</Accordion>
81> **Notes on setup, limits, monitoring, and data handling**
82>
83> | Topic | What to know |
84> | - | - |
85> | Sessions and scheduled tasks | Sessions are local, except [Code sessions over SSH](/docs/third-party/claude-desktop/ssh-remote-sessions), and the device must be awake to run long processes and scheduled tasks. |
86> | Memory | [Memory](/docs/third-party/claude-desktop/data-storage#memory) in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Chat-history search and nightly summary generation are not available in Chat on 3P. |
87> | Web search | Amazon Bedrock deployments and gateways that do not forward Anthropic server tools need a [web search provider](/docs/third-party/claude-desktop/web-tools#web-search-options) configured first. |
88> | Claude in Chrome | Claude in Chrome works with Claude Desktop on 3P only in organizations managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console). |
89> | Automatically approve in Cowork | Cowork offers the **Automatically approve** mode when an administrator sets [`autoModeEnabled`](/docs/third-party/claude-desktop/configuration#automodeenabled) to `true`. |
90> | User management via UI and RBAC | With the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), administrators add users and groups, connect single sign-on and SCIM, assign administrator roles, and set per-group permission policies from **Organization settings** on claude.ai. Deployments configured through MDM or a bootstrap server manage access through those channels. |
91> | Monitoring | Many capabilities of the Compliance API and Analytics API can be achieved via [OpenTelemetry export](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector) to your own collector. |
92> | Telemetry | Claude Desktop on 3P sends [crash reports and product analytics](/docs/third-party/claude-desktop/telemetry#telemetry-categories) to Anthropic by default. This telemetry contains no prompt or response content, and you can fully disable it via managed configuration. |
93> | Data handling | [Data handling](/docs/third-party/claude-desktop/overview#data-handling-by-provider) at the inference endpoint depends on the provider you configure. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by Google Cloud and Amazon Bedrock respectively. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](/docs/third-party/claude-desktop/claude-api) page. |
10894
third-party/claude-desktop/foundry Changed · +43 / -47 lines
from line 4
44
55This page walks an IT administrator through a Microsoft Foundry deployment: creating the Microsoft Foundry resource, choosing the authentication path that fits your organization, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app).
66
7<Note>
8 Microsoft Foundry offers Claude models in two hosting options, Hosted on Azure and Hosted on Anthropic, and you choose one when you configure the model deployment in Microsoft Foundry. Under both options, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. Your use of Claude through Microsoft Foundry is subject to Anthropic's data use terms.
7> [!NOTE]
8>
9> Microsoft Foundry offers Claude models in two hosting options, Hosted on Azure and Hosted on Anthropic, and you choose one when you configure the model deployment in Microsoft Foundry. Under both options, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. Your use of Claude through Microsoft Foundry is subject to Anthropic's data use terms.
10>
11> Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
912
10 Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
11</Note>
12
1313## Choose an authentication approach
1414
1515| Scenario | Use | Per-user identity | Notes |
from line 22
2222
2323These steps are performed once per Azure subscription. You need permission to create resources and, for in-app sign-in, to register an application in Microsoft Entra ID.
2424
25<Steps>
26 <Step title="Create a Microsoft Foundry resource">
27 In the Azure portal, create a Microsoft Foundry resource in your subscription. Record the **resource name**; the app constructs the endpoint as `<resource-name>.services.ai.azure.com`. If the app should reach Microsoft Foundry through a gateway or proxy you operate instead, see [Route requests through a gateway](#route-requests-through-a-gateway). The resource name is still required in that case.
28 </Step>
25**1. Create a Microsoft Foundry resource**
2926
30 <Step title="Deploy the Claude models">
31 In the Microsoft Foundry portal for your resource, deploy the Claude models you intend to serve. Record each **deployment name**; you will list these in `inferenceModels`.
32 </Step>
27In the Azure portal, create a Microsoft Foundry resource in your subscription. Record the **resource name**; the app constructs the endpoint as `<resource-name>.services.ai.azure.com`. If the app should reach Microsoft Foundry through a gateway or proxy you operate instead, see [Route requests through a gateway](#route-requests-through-a-gateway). The resource name is still required in that case.
3328
34 <Step title="Obtain an API key (API-key approach only)">
35 If you chose the API-key approach, copy one of the resource's keys from the Azure portal. You will place it in the managed configuration in [Configure the app](#configure-the-app).
36 </Step>
29**2. Deploy the Claude models**
3730
38 <Step title="Register an Entra ID application (in-app sign-in only)">
39 If you chose in-app Entra ID sign-in, register an application in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Identity → Applications → App registrations → New registration**. On the registration:
31In the Microsoft Foundry portal for your resource, deploy the Claude models you intend to serve. Record each **deployment name**; you will list these in `inferenceModels`.
4032
41 * Under **API permissions**, select **Add a permission**, find **Azure Cognitive Services** in the API picker, and add the **Delegated** permission **user\_impersonation** so the issued token is accepted by your Microsoft Foundry resource. (The app requests this permission as the scope `https://cognitiveservices.azure.com/.default`.) All three sign-in flows need it. After adding the permission, select **Grant admin consent**; in tenants that disable user consent, sign-in fails with error code `AADSTS65001` until consent is granted.
42 * Under **Authentication**, complete the setup for the sign-in flow you plan to use (see [In-app Entra ID sign-in](#in-app-entra-id-sign-in) for how the flows differ):
43 * For the device-code flow (the default), enable **Allow public client flows**. Entra ID rejects device-code sign-in without it.
44 * For the browser flow (`inferenceFoundryAuthFlow` set to `browser`), select **Add a platform → Mobile and desktop applications** and add the redirect URI `http://127.0.0.1/callback`. Use the literal address `127.0.0.1`, not `localhost`: Entra ID matches the scheme, host, and path exactly and ignores only the port. The browser flow completes sign-in without **Allow public client flows**. Conditional Access policies that block the device-code authentication flow do not apply to the browser flow.
45 * For the broker flow (`inferenceFoundryAuthFlow` set to `broker`), enable **Allow public client flows** and add the platform's broker redirect URI under **Mobile and desktop applications**. See [Register the Entra ID application](/docs/third-party/claude-desktop/entra-broker#register-the-entra-id-application) on the OS identity broker page for the redirect URI values and why the public-client setting is required.
33**3. Obtain an API key (API-key approach only)**
4634
47 Record the **Directory (tenant) ID** and **Application (client) ID**.
35If you chose the API-key approach, copy one of the resource's keys from the Azure portal. You will place it in the managed configuration in [Configure the app](#configure-the-app).
4836
49 Grant the users or groups who will sign in a role on the Microsoft Foundry resource that permits inference (for example, **Cognitive Services User**).
50 </Step>
51</Steps>
37**4. Register an Entra ID application (in-app sign-in only)**
5238
39If you chose in-app Entra ID sign-in, register an application in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Identity → Applications → App registrations → New registration**. On the registration:
40
41* Under **API permissions**, select **Add a permission**, find **Azure Cognitive Services** in the API picker, and add the **Delegated** permission **user\_impersonation** so the issued token is accepted by your Microsoft Foundry resource. (The app requests this permission as the scope `https://cognitiveservices.azure.com/.default`.) All three sign-in flows need it. After adding the permission, select **Grant admin consent**; in tenants that disable user consent, sign-in fails with error code `AADSTS65001` until consent is granted.
42* Under **Authentication**, complete the setup for the sign-in flow you plan to use (see [In-app Entra ID sign-in](#in-app-entra-id-sign-in) for how the flows differ):
43 * For the device-code flow (the default), enable **Allow public client flows**. Entra ID rejects device-code sign-in without it.
44 * For the browser flow (`inferenceFoundryAuthFlow` set to `browser`), select **Add a platform → Mobile and desktop applications** and add the redirect URI `http://127.0.0.1/callback`. Use the literal address `127.0.0.1`, not `localhost`: Entra ID matches the scheme, host, and path exactly and ignores only the port. The browser flow completes sign-in without **Allow public client flows**. Conditional Access policies that block the device-code authentication flow do not apply to the browser flow.
45 * For the broker flow (`inferenceFoundryAuthFlow` set to `broker`), enable **Allow public client flows** and add the platform's broker redirect URI under **Mobile and desktop applications**. See [Register the Entra ID application](/docs/third-party/claude-desktop/entra-broker#register-the-entra-id-application) on the OS identity broker page for the redirect URI values and why the public-client setting is required.
46
47Record the **Directory (tenant) ID** and **Application (client) ID**.
48
49Grant the users or groups who will sign in a role on the Microsoft Foundry resource that permits inference (for example, **Cognitive Services User**).
50
5351## Prepare devices
5452
5553What each end-user device needs depends on the authentication approach you chose.
from line 74
7674
7775`inferenceFoundryTenantId`, `inferenceFoundryClientId`, and `inferenceFoundryAuthFlow` can be set through an MDM profile or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap). When a bootstrap server delivers `inferenceFoundryResource`, `inferenceFoundryTenantId`, or `inferenceFoundryClientId`, the values are among the [keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent), so users may see a one-time approval dialog depending on how `bootstrapUrl` reached the device.
7876
79<Note>
80 In-app sign-in and a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) are separate layers that work together. In-app sign-in supplies each user's inference credential, the Entra ID token that authorizes model calls. A bootstrap server supplies per-user configuration values when the app starts. A bootstrap server does not replace sign-in: a deployment with a bootstrap server still needs each user to sign in, and signing in does not deliver configuration.
81</Note>
77> [!NOTE]
78>
79> In-app sign-in and a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) are separate layers that work together. In-app sign-in supplies each user's inference credential, the Entra ID token that authorizes model calls. A bootstrap server supplies per-user configuration values when the app starts. A bootstrap server does not replace sign-in: a deployment with a bootstrap server still needs each user to sign in, and signing in does not deliver configuration.
8280
8381#### Allow network egress
8482
from line 113
115113
116114| Setting | Type | Availability | Default | Description |
117115| - | - | - | - | - |
118| <span id="inferencefoundryresource" />Azure AI Foundry resource name<br />`inferenceFoundryResource` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Azure AI Foundry resource name used to construct the endpoint URL. |
119| <span id="inferencefoundrybaseurl" />Azure AI Foundry base URL<br />`inferenceFoundryBaseUrl` | `string` | MDM + Bootstrap<br />Added in 2.110.0 | — | 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)). |
120| <span id="inferencefoundryapikey" />Azure AI Foundry API key<br />`inferenceFoundryApiKey` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | API key for Azure AI Foundry inference. |
121| <span id="inferencefoundrytenantid" />Entra ID tenant ID<br />`inferenceFoundryTenantId` | `string` | MDM + Bootstrap<br />Added in 1.9255.0 | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. |
122| <span id="inferencefoundryclientid" />Entra ID client ID<br />`inferenceFoundryClientId` | `string` | MDM + Bootstrap<br />Added in 1.9255.0 | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. |
123| <span id="inferencefoundryauthflow" />Entra ID sign-in flow<br />`inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap<br />Added in 1.19367.0 | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. |
116| Azure AI Foundry resource name `inferenceFoundryResource` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Azure AI Foundry resource name used to construct the endpoint URL. |
117| Azure AI Foundry base URL `inferenceFoundryBaseUrl` | `string` | MDM + Bootstrap Added in 2.110.0 | — | 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)). |
118| Azure AI Foundry API key `inferenceFoundryApiKey` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | API key for Azure AI Foundry inference. |
119| Entra ID tenant ID `inferenceFoundryTenantId` | `string` | MDM + Bootstrap Added in 1.9255.0 | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. |
120| Entra ID client ID `inferenceFoundryClientId` | `string` | MDM + Bootstrap Added in 1.9255.0 | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. |
121| Entra ID sign-in flow `inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap Added in 1.19367.0 | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. |
124122
125<AccordionGroup>
126 <Accordion title="inferenceFoundryBaseUrl details">
127 Set this only when the app reaches Foundry through a gateway or proxy you run, such as Azure API Management. Requests go to `<value>/v1/messages` instead of `https://<resource>.services.ai.azure.com/anthropic/v1/messages`, carrying the same credential and headers the app would send to Foundry: each user's Entra ID token for the Azure Cognitive Services audience as `Authorization: Bearer` with Entra sign-in, otherwise the API key or the credential helper's output. Claude Code sessions receive the value as `ANTHROPIC_FOUNDRY_BASE_URL`, so use the same value you would give Claude Code in a terminal. `inferenceFoundryResource` is still required and should name the resource behind the gateway; the app sends nothing to the resource directly while this is set. Must be https, or http to a proxy at a loopback address on the device itself (127.0.0.1, localhost or \[::1]).
128 </Accordion>
123> **inferenceFoundryBaseUrl details**
124>
125> Set this only when the app reaches Foundry through a gateway or proxy you run, such as Azure API Management. Requests go to `<value>/v1/messages` instead of `https://<resource>.services.ai.azure.com/anthropic/v1/messages`, carrying the same credential and headers the app would send to Foundry: each user's Entra ID token for the Azure Cognitive Services audience as `Authorization: Bearer` with Entra sign-in, otherwise the API key or the credential helper's output. Claude Code sessions receive the value as `ANTHROPIC_FOUNDRY_BASE_URL`, so use the same value you would give Claude Code in a terminal. `inferenceFoundryResource` is still required and should name the resource behind the gateway; the app sends nothing to the resource directly while this is set. Must be https, or http to a proxy at a loopback address on the device itself (127.0.0.1, localhost or \[::1]).
129126
130 <Accordion title="inferenceFoundryAuthFlow details">
131 * **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled.
132 * **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication.
133 * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
134
135 App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code.
136 </Accordion>
137</AccordionGroup>
127> **inferenceFoundryAuthFlow details**
128>
129> * **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled.
130> * **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication.
131> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
132>
133> App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code.
138134
139135You must also set `inferenceModels` to a list of Microsoft Foundry deployment names. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
140136
third-party/claude-desktop/gateway Changed · +140 / -144 lines
from line 41
4141
4242#### Set up single sign-on
4343
44<Steps>
45 <Step title="Register an application in Entra ID">
46 In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → App registrations** and select **New registration**. Give it a name such as `Claude Desktop gateway`, choose **Accounts in this organizational directory only**, and select **Register**.
44**1. Register an application in Entra ID**
4745
48 On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You will use both in the next two steps.
46In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → App registrations** and select **New registration**. Give it a name such as `Claude Desktop gateway`, choose **Accounts in this organizational directory only**, and select **Register**.
4947
50 Open the **Authentication** blade, select **Add a platform**, and choose **Mobile and desktop applications**. Under **Custom redirect URIs**, add exactly:
48On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You will use both in the next two steps.
5149
52 ```text theme={null}
53 http://127.0.0.1/callback
54 ```
50Open the **Authentication** blade, select **Add a platform**, and choose **Mobile and desktop applications**. Under **Custom redirect URIs**, add exactly:
5551
56 A few details that matter here: use `127.0.0.1` (not `localhost`), include the `/callback` path, and add it under the **Mobile and desktop applications** platform specifically. That platform is the only one Entra allows to use any local port, which the app needs because it picks a free port at sign-in time. You do not need a client secret or any additional API permissions.
57 </Step>
52```text theme={null}
53http://127.0.0.1/callback
54```
5855
59 <Step title="Configure your gateway to validate the token">
60 Tell your gateway to accept the bearer token only if it was issued by your tenant **for this application**. In LiteLLM that looks like:
56A few details that matter here: use `127.0.0.1` (not `localhost`), include the `/callback` path, and add it under the **Mobile and desktop applications** platform specifically. That platform is the only one Entra allows to use any local port, which the app needs because it picks a free port at sign-in time. You do not need a client secret or any additional API permissions.
6157
62 ```yaml theme={null}
63 general_settings:
64 litellm_jwtauth:
65 public_key_url: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
66 audience: YOUR_CLIENT_ID
67 user_id_jwt_field: oid
68 ```
58**2. Configure your gateway to validate the token**
6959
70 Replace `YOUR_TENANT_ID` and `YOUR_CLIENT_ID` with the values from step 1.
60Tell your gateway to accept the bearer token only if it was issued by your tenant **for this application**. In LiteLLM that looks like:
7161
72 <Warning>
73 The `audience` line is required. Without it, your gateway accepts tokens issued to any application in your tenant, not just this one.
74 </Warning>
62```yaml theme={null}
63general_settings:
64 litellm_jwtauth:
65 public_key_url: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
66 audience: YOUR_CLIENT_ID
67 user_id_jwt_field: oid
68```
7569
76 For Kong, Envoy, or Azure API Management, configure the equivalent JWT validation policy with the same JWKS URL and audience.
77 </Step>
70Replace `YOUR_TENANT_ID` and `YOUR_CLIENT_ID` with the values from step 1.
7871
79 <Step title="Configure in the app">
80 Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway** and **Credential kind** to **Interactive sign-in**. This hides the API-key field and reveals **Gateway SSO IdP (OIDC)**:
72> [!WARNING]
73>
74> The `audience` line is required. Without it, your gateway accepts tokens issued to any application in your tenant, not just this one.
8175
82 | Field | Value |
83 | - | - |
84 | Gateway base URL | `https://llm-gateway.example.corp` |
85 | Credential kind | **Interactive sign-in** |
86 | Gateway SSO IdP (OIDC) → Client ID | `YOUR_CLIENT_ID` |
87 | Gateway SSO IdP (OIDC) → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` |
88 | Gateway SSO IdP (OIDC) → Scopes | *leave empty for the default* |
89 | Gateway SSO IdP (OIDC) → Redirect port | *leave empty* |
76For Kong, Envoy, or Azure API Management, configure the equivalent JWT validation policy with the same JWKS URL and audience.
9077
91 Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
78**3. Configure in the app**
9279
93 When a user next opens Claude Desktop, they see a **Sign in to your organization** button. Clicking it opens their browser to your Entra sign-in page; once they approve, they return to the app and can start working. The app keeps them signed in and refreshes the token in the background. If the session is revoked or expires under your tenant's policy, the app shows a **Sign in again** prompt; clicking it reopens the sign-in page in the browser.
94 </Step>
95</Steps>
80Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway** and **Credential kind** to **Interactive sign-in**. This hides the API-key field and reveals **Gateway SSO IdP (OIDC)**:
9681
82| Field | Value |
83| - | - |
84| Gateway base URL | `https://llm-gateway.example.corp` |
85| Credential kind | **Interactive sign-in** |
86| Gateway SSO IdP (OIDC) → Client ID | `YOUR_CLIENT_ID` |
87| Gateway SSO IdP (OIDC) → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` |
88| Gateway SSO IdP (OIDC) → Scopes | *leave empty for the default* |
89| Gateway SSO IdP (OIDC) → Redirect port | *leave empty* |
90
91Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
92
93When a user next opens Claude Desktop, they see a **Sign in to your organization** button. Clicking it opens their browser to your Entra sign-in page; once they approve, they return to the app and can start working. The app keeps them signed in and refreshes the token in the background. If the session is revoked or expires under your tenant's policy, the app shows a **Sign in again** prompt; clicking it reopens the sign-in page in the browser.
94
9795#### Using Okta instead
9896
9997In the Okta Admin Console, create a **Native** application with the **Authorization Code** and **Refresh Token** grant types. Okta requires the redirect URI to match exactly, including the port, so pick a fixed port (for example `53180`), register `http://127.0.0.1:53180/callback`, and set that same port in **Gateway SSO IdP (OIDC)**:
from line 103
105103| Scopes | *leave empty for the default* |
106104| Redirect port | `53180` |
107105
108<Note>
109 Use the **issuer** value, not the **Metadata URI**. Okta's admin console shows the metadata URI (ending in `/.well-known/openid-configuration`) prominently — that is the discovery document the app fetches *from* the issuer, not the issuer itself. If you are unsure, open the metadata URI in a browser and copy the `"issuer"` field from the JSON response. For a custom Okta authorization server the issuer is `https://YOUR_ORG.okta.com/oauth2/AUTH_SERVER_ID`.
110</Note>
106> [!NOTE]
107>
108> Use the **issuer** value, not the **Metadata URI**. Okta's admin console shows the metadata URI (ending in `/.well-known/openid-configuration`) prominently — that is the discovery document the app fetches *from* the issuer, not the issuer itself. If you are unsure, open the metadata URI in a browser and copy the `"issuer"` field from the JSON response. For a custom Okta authorization server the issuer is `https://YOUR_ORG.okta.com/oauth2/AUTH_SERVER_ID`.
111109
112110Point your gateway's JWT validation at `https://YOUR_ORG.okta.com/oauth2/v1/keys` with `audience` set to the Okta client ID.
113111
from line 166
168166
169167| Setting | Type | Availability | Default | Description |
170168| - | - | - | - | - |
171| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Full URL of the inference gateway endpoint. |
172| <span id="inferencestreamidletimeoutsec" />Stream idle timeout<br />`inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap<br />Added in 1.44121.1 | — | Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800. |
173| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | API key for the configured inference gateway. |
174| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap<br />Added in 1.3036.0 | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"`; use inferenceCredentialKind: "interactive". The original spelling will keep working; no end date has been set. |
175| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap<br />Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. Deprecated: `inferenceGatewayOidcAuthFlow`; 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. |
176| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap<br />Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. Deprecated: `inferenceGatewayOidc`; use inferenceIdpOidc with inferenceCredentialKind: "external-idp" 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. |
177| <span id="inferenceidpauthflow" />Identity provider sign-in flow<br />`inferenceIdpAuthFlow` | `enum` | MDM + Bootstrap<br />Added in 2.7032.0 | — | How the identity-provider sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
178| <span id="inferenceidpoidc" />Identity provider (OIDC)<br />`inferenceIdpOidc` | `object` | MDM + Bootstrap<br />Added in 2.7032.0 | — | Your organization’s OpenID Connect identity provider. The user’s token is sent as the Bearer credential to the gateway or the Bedrock proxy. |
169| Gateway base URL `inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Full URL of the inference gateway endpoint. |
170| Stream idle timeout `inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap Added in 1.44121.1 | — | Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800. |
171| Gateway API key `inferenceGatewayApiKey` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | API key for the configured inference gateway. |
172| Gateway auth scheme `inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap Added in 1.3036.0 | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"`; use inferenceCredentialKind: "interactive". The original spelling will keep working; no end date has been set. |
173| Gateway sign-in flow `inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. Deprecated: `inferenceGatewayOidcAuthFlow`; 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. |
174| Gateway SSO IdP (OIDC) `inferenceGatewayOidc` | `object` | MDM + Bootstrap Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. Deprecated: `inferenceGatewayOidc`; use inferenceIdpOidc with inferenceCredentialKind: "external-idp" 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. |
175| Identity provider sign-in flow `inferenceIdpAuthFlow` | `enum` | MDM + Bootstrap Added in 2.7032.0 | — | How the identity-provider sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
176| Identity provider (OIDC) `inferenceIdpOidc` | `object` | MDM + Bootstrap Added in 2.7032.0 | — | Your organization’s OpenID Connect identity provider. The user’s token is sent as the Bearer credential to the gateway or the Bedrock proxy. |
179177
180<AccordionGroup>
181 <Accordion title="inferenceStreamIdleTimeoutSec details">
182 Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code's `CLAUDE_STREAM_IDLE_TIMEOUT_MS`). It only helps when the gateway writes SSE keep-alive `ping` events (or `:` comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code's defaults.
178> **inferenceStreamIdleTimeoutSec details**
179>
180> Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code's `CLAUDE_STREAM_IDLE_TIMEOUT_MS`). It only helps when the gateway writes SSE keep-alive `ping` events (or `:` comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code's defaults.
181>
182> A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. A common case is automatic compaction, in which a session sends its whole conversation in one streaming request and waits for a long summary; when that request fails, the error reads `Prompt is too long · automatic compaction failed:` followed by the cause. While this key is set, the app's value takes precedence over `CLAUDE_STREAM_IDLE_TIMEOUT_MS` in Claude Code's own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies.
183183
184 A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. A common case is automatic compaction, in which a session sends its whole conversation in one streaming request and waits for a long summary; when that request fails, the error reads `Prompt is too long · automatic compaction failed:` followed by the cause. While this key is set, the app's value takes precedence over `CLAUDE_STREAM_IDLE_TIMEOUT_MS` in Claude Code's own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies.
185 </Accordion>
184> **inferenceGatewayOidcAuthFlow details**
185>
186> * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration.
187> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
188>
189> Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control. A desktop that has the `external-idp` kind reads this key, together with `inferenceGatewayOidc`, as that kind's sign-in flow; it stays readable.
186190
187 <Accordion title="inferenceGatewayOidcAuthFlow details">
188 * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration.
189 * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
191> **inferenceGatewayOidc details**
192>
193> **External IdP mode.** The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at `<baseUrl>/.well-known/oauth-authorization-server`. A desktop that has the `external-idp` kind reads this block as that kind's identity-provider key; it stays readable, so a fleet keeps this spelling until every desktop is on such a release.
194>
195> **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the gateway validates signature, `iss`, and `aud` (the `clientId` configured here). `access_token` sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); `scopes` must then name the gateway's registered API scope. Either way the gateway must check `aud`, not just signature and issuer, or it accepts any token from your tenant.
196>
197> **IdP setup.** The callback is `http://127.0.0.1:<port>/callback` by default (`http://localhost:<port>/callback` with `redirectHost: "localhost"`); register exactly the one you use and include `/callback`. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback` (any port; omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the gateway API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with the exact URI `http://127.0.0.1:<port>/callback` and that port in `redirectPort`.
198>
199> **Refresh.** With `offline_access` the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an `id_token` on refresh, so a Google Workspace-backed gateway in `id_token` mode re-prompts about hourly; `access_token` mode is unaffected.
200>
201> | Field | Type | Default | Description |
202> | - | - | - | - |
203> | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
204> | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
205> | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
206> | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
207> | `bearerTokenType` | `enum` | `id_token` | Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server. One of: `id_token`, `access_token`. |
208> | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below. |
209> | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
210> | `resource` | `string` | — | Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID. |
211> | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
212> | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
213> | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
190214
191 Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control. A desktop that has the `external-idp` kind reads this key, together with `inferenceGatewayOidc`, as that kind's sign-in flow; it stays readable.
192 </Accordion>
215> **inferenceIdpAuthFlow details**
216>
217> * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceIdpOidc` for redirect-URI registration.
218> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceIdpOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
219>
220> Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes` and forwards it to the customer's own gateway or proxy; both endpoints of that trust relationship are inside the customer's control.
193221
194 <Accordion title="inferenceGatewayOidc details">
195 **External IdP mode.** The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at `<baseUrl>/.well-known/oauth-authorization-server`. A desktop that has the `external-idp` kind reads this block as that kind's identity-provider key; it stays readable, so a fleet keeps this spelling until every desktop is on such a release.
222> **inferenceIdpOidc details**
223>
224> Used with `inferenceCredentialKind: "external-idp"`. The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code (PKCE) sign-in in the browser with `clientId` (or through the OS broker, see `inferenceIdpAuthFlow`) and sends the token as `Authorization: Bearer` on every inference request: to `inferenceGatewayBaseUrl` on the gateway provider, or on Bedrock to `inferenceBedrockBaseUrl`, which is then required: only a proxy that validates the token accepts it, never Amazon Bedrock itself (to sign in straight to Bedrock use `interactive`, AWS IAM Identity Center). On Bedrock this kind has no model discovery: list the models in `inferenceModels`.
225>
226> **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the receiver validates signature, `iss` and `aud` (the `clientId` here). `access_token` sends the OAuth access token, for gateways and proxies that validate as an OAuth resource server; `scopes` must then name the registered API scope. Either way the receiver must check `aud`, or it accepts any token from your tenant.
227>
228> **IdP setup.** The callback is `http://127.0.0.1:<port>/callback` (`localhost` with `redirectHost: "localhost"`); register exactly that. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI `http://127.0.0.1/callback` (omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with `http://127.0.0.1:<port>/callback` and that port in `redirectPort`.
229>
230> **Refresh.** With `offline_access` the app renews the token silently and asks for a browser sign-in only when refresh fails (Google returns no `id_token` on refresh, so `id_token` mode there re-prompts about hourly).
231>
232> **Older names.** Gateway configurations written before this key use `inferenceGatewayOidc` / `inferenceGatewayOidcAuthFlow` with the `interactive` kind; they stay readable and mean the same sign-in.
233>
234> | Field | Type | Default | Description |
235> | - | - | - | - |
236> | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
237> | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
238> | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
239> | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
240> | `bearerTokenType` | `enum` | `id_token` | Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server. One of: `id_token`, `access_token`. |
241> | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below. |
242> | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
243> | `resource` | `string` | — | Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID. |
244> | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
245> | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
246> | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
196247
197 **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the gateway validates signature, `iss`, and `aud` (the `clientId` configured here). `access_token` sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); `scopes` must then name the gateway's registered API scope. Either way the gateway must check `aud`, not just signature and issuer, or it accepts any token from your tenant.
198
199 **IdP setup.** The callback is `http://127.0.0.1:<port>/callback` by default (`http://localhost:<port>/callback` with `redirectHost: "localhost"`); register exactly the one you use and include `/callback`. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback` (any port; omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the gateway API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with the exact URI `http://127.0.0.1:<port>/callback` and that port in `redirectPort`.
200
201 **Refresh.** With `offline_access` the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an `id_token` on refresh, so a Google Workspace-backed gateway in `id_token` mode re-prompts about hourly; `access_token` mode is unaffected.
202
203 | Field | Type | Default | Description |
204 | - | - | - | - |
205 | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
206 | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
207 | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
208 | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
209 | `bearerTokenType` | `enum` | `id_token` | Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server. One of: `id_token`, `access_token`. |
210 | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below. |
211 | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
212 | `resource` | `string` | — | Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID. |
213 | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
214 | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
215 | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
216 </Accordion>
217
218 <Accordion title="inferenceIdpAuthFlow details">
219 * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceIdpOidc` for redirect-URI registration.
220 * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceIdpOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
221
222 Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes` and forwards it to the customer's own gateway or proxy; both endpoints of that trust relationship are inside the customer's control.
223 </Accordion>
224
225 <Accordion title="inferenceIdpOidc details">
226 Used with `inferenceCredentialKind: "external-idp"`. The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code (PKCE) sign-in in the browser with `clientId` (or through the OS broker, see `inferenceIdpAuthFlow`) and sends the token as `Authorization: Bearer` on every inference request: to `inferenceGatewayBaseUrl` on the gateway provider, or on Bedrock to `inferenceBedrockBaseUrl`, which is then required: only a proxy that validates the token accepts it, never Amazon Bedrock itself (to sign in straight to Bedrock use `interactive`, AWS IAM Identity Center). On Bedrock this kind has no model discovery: list the models in `inferenceModels`.
227
228 **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the receiver validates signature, `iss` and `aud` (the `clientId` here). `access_token` sends the OAuth access token, for gateways and proxies that validate as an OAuth resource server; `scopes` must then name the registered API scope. Either way the receiver must check `aud`, or it accepts any token from your tenant.
229
230 **IdP setup.** The callback is `http://127.0.0.1:<port>/callback` (`localhost` with `redirectHost: "localhost"`); register exactly that. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI `http://127.0.0.1/callback` (omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with `http://127.0.0.1:<port>/callback` and that port in `redirectPort`.
231
232 **Refresh.** With `offline_access` the app renews the token silently and asks for a browser sign-in only when refresh fails (Google returns no `id_token` on refresh, so `id_token` mode there re-prompts about hourly).
233
234 **Older names.** Gateway configurations written before this key use `inferenceGatewayOidc` / `inferenceGatewayOidcAuthFlow` with the `interactive` kind; they stay readable and mean the same sign-in.
235
236 | Field | Type | Default | Description |
237 | - | - | - | - |
238 | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
239 | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
240 | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
241 | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
242 | `bearerTokenType` | `enum` | `id_token` | Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server. One of: `id_token`, `access_token`. |
243 | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below. |
244 | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
245 | `resource` | `string` | — | Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID. |
246 | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
247 | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
248 | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
249 </Accordion>
250</AccordionGroup>
251
252248To send additional HTTP headers on every inference request (tenant routing, org IDs, and similar), set [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders). It applies to all providers, not just gateways.
253249
254250### Single sign-on configuration keys
from line 275
279275
280276\* Either `issuer`, or both `authorizationUrl` and `tokenUrl`, is required.
281277
282<Warning>
283 `inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration#value-types). The in-app **Export** produces the correct format automatically.
284</Warning>
278> [!WARNING]
279>
280> `inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration#value-types). The in-app **Export** produces the correct format automatically.
285281
286282In a macOS `.mobileconfig` payload (Okta example):
287283
from line 338
342338
343339On Claude API, Google Cloud's Agent Platform, Amazon Bedrock, and Amazon Bedrock Mantle deployments with no custom base URL, tool search is on by default from Claude Desktop 1.49585.0 and `toolSearchEnabled` is not needed. These versions leave Claude Code's experimental beta features on for those providers, as terminal Claude Code does (on Google Cloud's Agent Platform, tool search applies to Claude 4.5 and newer models). To turn tool search off on these deployments, set `ENABLE_TOOL_SEARCH` to `false` in the `env` block of OS-level [Claude Code managed settings](https://code.claude.com/docs/en/settings#settings-files), with [`parentSettingsBehavior`](/docs/third-party/claude-desktop/code) set to `merge`. On earlier app versions these providers also have tool search off by default, and `toolSearchEnabled` turns it on.
344340
345<Warning>
346 Setting `toolSearchEnabled` causes sessions to send experimental request headers and fields to your gateway or provider. On gateway deployments running Claude Desktop 1.40609.0 or later this is only the tool-search request shape (the `tool-search-tool-2025-10-19` value in the `anthropic-beta` header, deferred tool loading, and `tool_reference` content blocks), and every other experimental Claude Code beta stays off. On earlier versions, on Microsoft Foundry, and on providers behind a custom base URL, the key instead lifts the experimental-beta suppression for these sessions, so requests also carry Claude Code's other experimental beta headers and fields for that provider. Enable it only if your gateway forwards and accepts what it will receive; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks.
347</Warning>
341> [!WARNING]
342>
343> Setting `toolSearchEnabled` causes sessions to send experimental request headers and fields to your gateway or provider. On gateway deployments running Claude Desktop 1.40609.0 or later this is only the tool-search request shape (the `tool-search-tool-2025-10-19` value in the `anthropic-beta` header, deferred tool loading, and `tool_reference` content blocks), and every other experimental Claude Code beta stays off. On earlier versions, on Microsoft Foundry, and on providers behind a custom base URL, the key instead lifts the experimental-beta suppression for these sessions, so requests also carry Claude Code's other experimental beta headers and fields for that provider. Enable it only if your gateway forwards and accepts what it will receive; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks.
348344
349345## Troubleshoot
350346
from line 357
361357
362358**Browser shows "Connected" but the app reports the sign-in failed, or `Token exchange failed (HTTP 401)`** — The browser step succeeded, but the identity provider rejected the follow-up token request. This usually means the IdP application is registered as a confidential (Web) client, which expects a client secret. Claude is a public PKCE client and doesn't send one. Register a public/native client instead: **Native Application** in Okta, or the **Mobile and desktop applications** platform in Entra ID. Application type generally can't be changed after creation, so you may need to create a new one.
363359
364<Note>
365 Google Workspace can be used as the identity provider, but in the default `id_token` mode Google does not issue a fresh ID token on background refresh, so users are prompted to sign in again roughly once an hour. Setting `bearerTokenType` to `access_token` avoids this. Entra ID and Okta are not affected in either mode.
366</Note>
360> [!NOTE]
361>
362> Google Workspace can be used as the identity provider, but in the default `id_token` mode Google does not issue a fresh ID token on background refresh, so users are prompted to sign in again roughly once an hour. Setting `bearerTokenType` to `access_token` avoids this. Entra ID and Okta are not affected in either mode.
367363
368364**Model picker is empty or missing models.** Check your gateway's `GET /v1/models` response and your `inferenceModels` list (see [Models](#models)). When `/v1/models` is unreachable or returns an error, the picker falls back to the `inferenceModels` list; if that list is empty, so is the picker.
369365
third-party/claude-desktop/import Changed · +34 / -64 lines
from line 35
3535
3636On Team and Enterprise workspaces, member data export is off by default. A workspace owner enables it on claude.ai under **Settings → Organization → Data and privacy → Allow members to export their own data**.
3737
38<Frame caption="The member data export toggle in claude.ai organization settings. Only workspace owners see this control.">
39 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-admin-toggle.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=f1f4696a2124cd36ee9a7366cb1c4772" alt="claude.ai organization settings, Data and privacy page, with the Allow members to export their own data toggle turned on and a confirmation toast reading Member data export enabled." width="1800" height="1125" data-path="images/third-party/import/import-admin-toggle.png" />
40</Frame>
38
4139
4240Members of the workspace can then export their own conversations. The toggle does not expose one member's data to another; each member can download only their own history.
4341
from line 43
4543
4644In Claude Desktop, go to **Settings → Import & export** and click **Import…** to open the **Import from Claude** wizard.
4745
48<Frame caption="Step 1 of the import wizard, before a source is chosen.">
49 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-wizard-start.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=526562f1c9c0abd66e9b56d0328808db" alt="Claude Desktop settings with Import and export selected and the Import from Claude wizard open on step 1, showing Sign in to claude.ai and Choose file buttons." width="1920" height="1440" data-path="images/third-party/import/import-wizard-start.png" />
50</Frame>
46
5147
5248The wizard has three steps: **Chats** (your claude.ai export), **Cowork & Code** (local sessions on this machine), and **Review**. Skip any step you don't need. A fourth step, **Duplicates**, appears after the import only when an imported project has the same name as one you already have. See [If a project already exists](#if-a-project-already-exists).
5349
from line 51
5551
5652You can pull your claude.ai history straight into the wizard by signing in, or download it from claude.ai yourself and choose the file.
5753
58<Tabs>
59 <Tab title="Sign in to claude.ai (recommended)">
60 Click **Sign in to claude.ai…**. Your browser opens to claude.ai; sign in if prompted, choose your organization if you belong to more than one, and click **Authorize**.
54**Sign in to claude.ai (recommended)**
6155
62 <Frame caption="The organization selector, shown if your claude.ai account belongs to more than one workspace.">
63 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-consent-org.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=1657a03028a7ceb3d173e71ba27f591d" alt="claude.ai organization selector titled Select organization, listing one organization." width="1600" height="720" data-path="images/third-party/import/import-consent-org.png" />
64 </Frame>
56Click **Sign in to claude.ai…**. Your browser opens to claude.ai; sign in if prompted, choose your organization if you belong to more than one, and click **Authorize**.
6557
66 <Frame caption="The authorization prompt. The only permission granted is a one-time export of your own data.">
67 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-consent-authorize.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=55be3501d41c9e61b49154db66b71d5b" alt="claude.ai authorization card reading Claude Desktop Import would like to connect to your Claude chat account, with an Authorize button." width="1400" height="1300" data-path="images/third-party/import/import-consent-authorize.png" />
68 </Frame>
58
6959
70 Back in Claude Desktop, click **Fetch export**. The wizard requests an export from claude.ai, downloads it, and shows what it found.
60
7161
72 <Frame caption="The wizard after the export finishes downloading.">
73 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-signed-in.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=dafc4cbfffd685321442cbd72fd73993" alt="Import from Claude wizard step 1 showing a claude.ai export row with the account email and a summary of 7 chats and 1 project." width="1920" height="1440" data-path="images/third-party/import/import-signed-in.png" />
74 </Frame>
75 </Tab>
62Back in Claude Desktop, click **Fetch export**. The wizard requests an export from claude.ai, downloads it, and shows what it found.
7663
77 <Tab title="Choose a downloaded file">
78 On claude.ai, go to **Settings → Privacy → Export data** and click **Export**. If you don't see **Export data**, ask a workspace owner to [enable member data export](#enable-member-data-export-admins).
64
7965
80 <Frame caption="The Export data page in claude.ai personal settings.">
81 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-web-export.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=1ed4aa5a08469420020d3ff83579c0de" alt="claude.ai settings Privacy page with the Export data subpage open, showing an Export button and a note that a download link will be sent by email." width="1800" height="1125" data-path="images/third-party/import/import-web-export.png" />
82 </Frame>
66**Choose a downloaded file**
8367
84 claude.ai emails you a download link when the export is ready. The link expires after 24 hours.
68On claude.ai, go to **Settings → Privacy → Export data** and click **Export**. If you don't see **Export data**, ask a workspace owner to [enable member data export](#enable-member-data-export-admins).
8569
86 <Frame caption="The export-ready email.">
87 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-email.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=cf883e9c401401686568c77cb6ac45c1" alt="Email from Claude titled Your data is ready for download with a Download data button." width="1800" height="1125" data-path="images/third-party/import/import-email.png" />
88 </Frame>
70
8971
90 Download the `.zip`, then in the import wizard click **Choose file…** and select it.
72claude.ai emails you a download link when the export is ready. The link expires after 24 hours.
9173
92 <Frame caption="Step 1 with a downloaded export selected.">
93 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-choose-file.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=5cb868969ebed88801296f696796d0f1" alt="Import from Claude wizard step 1 showing a selected member-data zip file with a summary of 7 chats and 1 project." width="1920" height="1440" data-path="images/third-party/import/import-choose-file.png" />
94 </Frame>
95 </Tab>
96</Tabs>
74
9775
76Download the `.zip`, then in the import wizard click **Choose file…** and select it.
77
78
79
9880Click **Continue**, or **Skip this step** if you only want to bring in local sessions.
9981
10082## Step 2: local Cowork and Code sessions
from line 83
10183
10284The wizard scans this machine for Cowork and Claude Code sessions from an earlier Claude Desktop install and lists what it finds. Choose how far back to include, and add any other folder that holds sessions (for example, a backup or a folder copied from another machine).
10385
104<Frame caption="Local sessions found on this machine.">
105 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-local-sessions.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=e17511922a814b0355cb540688a5c949" alt="Import from Claude wizard step 2, Cowork and Code, listing 5 local sessions with a time-range selector and an option to add another location." width="1920" height="1440" data-path="images/third-party/import/import-local-sessions.png" />
106</Frame>
86
10787
10888Sessions are copied, not moved. Your original history stays where it is.
10989
from line 91
11191
11292The **Review** step summarizes what will be added. Click **Import** to copy everything into your local session store.
11393
114<Frame caption="The review summary before import.">
115 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-review.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=c7939485c7185afbf1ef7518a94db2d6" alt="Import from Claude wizard step 3 showing a claude.ai export summary of 7 chats and 1 project alongside 5 local Cowork and Code sessions, with an Import button." width="1920" height="1440" data-path="images/third-party/import/import-review.png" />
116</Frame>
94
11795
118<Frame caption="Import complete. Imported chats appear in the sidebar and imported projects appear on the Projects page.">
119 <img src="https://mintcdn.com/claude-ai/XDpDaIQ3J0Amhn8h/images/third-party/import/import-success.png?fit=max&auto=format&n=XDpDaIQ3J0Amhn8h&q=85&s=f0a01a38e52d841b66c4215f9cda2db4" alt="Import from Claude wizard success screen showing a checkmark and the number of sessions imported, with a note that re-running import will not create duplicates." width="1920" height="1440" data-path="images/third-party/import/import-success.png" />
120</Frame>
96
12197
12298## If a project already exists
12399
124100When an imported project has the same name as a project already in Claude Desktop, the wizard adds a **Duplicates** step after the import finishes. This happens, for example, when you set up **Northwind** on this machine and then bring over history from another machine that also has a Northwind project. The step lists each match with two choices.
125101
126<Frame caption="The Duplicates step, listing imported projects that match ones you already have.">
127 <img src="https://mintcdn.com/claude-ai/XDpDaIQ3J0Amhn8h/images/third-party/import/import-duplicates.png?fit=max&auto=format&n=XDpDaIQ3J0Amhn8h&q=85&s=798f75d5a508ebcb7082373b5cf95d84" alt="Import from Claude wizard step 4, Duplicates, headed These projects already exist, listing five Northwind projects each with Merge into existing and Keep separate buttons and a Continue button." width="1920" height="1440" data-path="images/third-party/import/import-duplicates.png" />
128</Frame>
102
129103
130104* **Merge into existing** moves the imported chats and sessions into your existing project and removes the duplicate. Folders you attached to the duplicate move with them. If your existing project has no instructions of its own, the imported project's instructions are shown there for you to review and accept. Later imports from the same source land in the existing project as well.
131105* **Keep separate** leaves both projects in place. The imported one keeps a numbered name, such as **Northwind (1)**, and Claude Desktop stops offering to merge it.
from line 113
139113* A session from this app's earlier third-party configuration on this computer shows a **Continue this conversation?** prompt. Click **Continue** to send your message.
140114* Any other imported conversation or session shows a **Resume imported session?** prompt. Click **Trust and resume** to continue.
141115
142<Frame caption="The trust prompt shown the first time you resume a conversation imported from claude.ai.">
143 <img src="https://mintcdn.com/claude-ai/HpR2FaaZXZXkiUcV/images/third-party/import/import-trust-resume.png?fit=max&auto=format&n=HpR2FaaZXZXkiUcV&q=85&s=806d0d2018d7fc0f10afb71035b1f807" alt="An imported conversation open in Cowork with a yellow Resume imported session card offering Go back and Trust and resume buttons." width="1800" height="688" data-path="images/third-party/import/import-trust-resume.png" />
144</Frame>
116
145117
146118## Make an imported project folder readable in Chat
147119
148120When an import brings over a project, it puts a folder on the project. In Chat, Claude can't read that folder until you add it to the project again. Add the folder once for each imported project.
149121
150<Steps>
151 <Step title="Open the project">
152 Go to the **Projects** page and open the imported project.
153 </Step>
122**1. Open the project**
154123
155 <Step title="Note the folder path">
156 Next to **Context**, click **+**, then select **Choose a folder**. Under **Recent**, find the project's folder, which is dimmed and can't be selected, and note the path shown under its name.
157 </Step>
124Go to the **Projects** page and open the imported project.
158125
159 <Step title="Add the folder again">
160 Select **Choose a different folder**. In the folder dialog, go to the path you noted and select the project's folder.
161 </Step>
126**2. Note the folder path**
162127
163 <Step title="Start a new conversation">
164 Start a new conversation in the project. In the new conversation, Claude can read the files in the folder.
165 </Step>
166</Steps>
128Next to **Context**, click **+**, then select **Choose a folder**. Under **Recent**, find the project's folder, which is dimmed and can't be selected, and note the path shown under its name.
129
130**3. Add the folder again**
131
132Select **Choose a different folder**. In the folder dialog, go to the path you noted and select the project's folder.
133
134**4. Start a new conversation**
135
136Start a new conversation in the project. In the new conversation, Claude can read the files in the folder.
167137
168138Importing the project again doesn't make its folder readable. If you remove the import under **Import history** in **Settings > Import & export**, or archive the project, and then import from claude.ai again, the new project uses the same folder. Add the folder to the new project again.
169139
third-party/claude-desktop/installation Changed · +3 / -3 lines
from line 212
212212* **Take releases later** by setting [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel) to `staggered`, the slower channel. Devices on the default, `stable`, take each release as it rolls out. Devices on `staggered` update to the release that Anthropic has marked for that channel. On Thursdays, Anthropic marks a release that has fully rolled out on `stable`, a tested production build from at least one week prior. A device on a release newer than the marked one stays on it until Anthropic marks a release newer than its own. Features and fixes, including security fixes, reach `staggered` devices later.
213213* **Disable auto-update** (`disableAutoUpdates`) and redistribute new builds through your MDM on your own cadence. This is required for [air-gapped environments](#offline-installation) but means your IT team owns the update pipeline.
214214
215<Warning>
216 Moving a device from `staggered` to `stable` updates it to a newer release, and setting `staggered` again doesn't take it back to the older one. A device also follows `stable` if you remove `releaseChannel` or set it only where the device doesn't read it.
217</Warning>
215> [!WARNING]
216>
217> Moving a device from `staggered` to `stable` updates it to a newer release, and setting `staggered` again doesn't take it back to the older one. A device also follows `stable` if you remove `releaseChannel` or set it only where the device doesn't read it.
218218
219219Set `releaseChannel` in the first of these that the device has:
220220
third-party/claude-desktop/local-access Changed · +3 / -3 lines
from line 30
3030
3131The check is enforced against the **resolved** path, so symlinks and `..` traversal can't be used to escape an allowed root.
3232
33<Note>
34 The allowlist controls what users can **attach**. Within an attached read/write folder, the agent can read and write every file the user's OS account can reach. Data outside the allowed roots cannot be attached in Cowork and is out of reach of Claude's file tools in Code sessions. A Code session's shell commands are confined only by the sandbox described under [Code](/docs/third-party/claude-desktop/code#applied-as-managed-policy): where it applies they can change files only inside the roots and temporary locations but can still read outside them unless you also set [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), and where it does not apply (Windows devices, hosts without the sandbox dependencies) the allowlist does not confine them and that key can only turn such reads into approval prompts. To let the agent read data in Cowork without changing it, list the folder with `mode` set to `ro`.
35</Note>
33> [!NOTE]
34>
35> The allowlist controls what users can **attach**. Within an attached read/write folder, the agent can read and write every file the user's OS account can reach. Data outside the allowed roots cannot be attached in Cowork and is out of reach of Claude's file tools in Code sessions. A Code session's shell commands are confined only by the sandbox described under [Code](/docs/third-party/claude-desktop/code#applied-as-managed-policy): where it applies they can change files only inside the roots and temporary locations but can still read outside them unless you also set [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), and where it does not apply (Windows devices, hosts without the sandbox dependencies) the allowlist does not confine them and that key can only turn such reads into approval prompts. To let the agent read data in Cowork without changing it, list the folder with `mode` set to `ro`.
3636
3737## Network drives on Windows
3838
third-party/claude-desktop/mantle Changed · +14 / -16 lines
from line 47
4747
4848| Setting | Type | Availability | Default | Description |
4949| - | - | - | - | - |
50| <span id="inferencebedrockregion" />AWS region<br />`inferenceBedrockRegion` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. |
51| <span id="inferencebedrockbaseurl" />Bedrock base URL<br />`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. |
52| <span id="inferencebedrockservicetier" />Bedrock service tier<br />`inferenceBedrockServiceTier` | `enum` | MDM + Bootstrap<br />Added in 1.5186.0 | — | Sent as the X-Amzn-Bedrock-Service-Tier header. Leave unset for on-demand. One of: `flex`, `priority`. |
53| <span id="inferencebedrockbearertoken" />AWS bearer token<br />`inferenceBedrockBearerToken` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those. |
54| <span id="inferencebedrockssostarturl" />AWS SSO start URL<br />`inferenceBedrockSsoStartUrl` | `string` | MDM + Bootstrap<br />Added in 1.6259.0 | — | Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below. |
55| <span id="inferencebedrockssoregion" />AWS SSO region<br />`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap<br />Added in 1.6259.0 | — | IAM Identity Center home region. |
56| <span id="inferencebedrockssoaccountid" />AWS SSO account ID<br />`inferenceBedrockSsoAccountId` | `string` | MDM + Bootstrap<br />Added in 1.6259.0 | — | 12-digit AWS account ID assigned to users in IAM Identity Center. |
57| <span id="inferencebedrockssorolename" />AWS SSO role name<br />`inferenceBedrockSsoRoleName` | `string` | MDM + Bootstrap<br />Added in 1.6259.0 | — | IAM Identity Center permission-set name granting bedrock:InvokeModel\* on the account above. |
58| <span id="inferencebedrockprofile" />AWS profile name<br />`inferenceBedrockProfile` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. |
59| <span id="inferencebedrockawsdir" />AWS config directory<br />`inferenceBedrockAwsDir` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Folder with AWS config/credentials. Defaults to \~/.aws when no bearer token is set. |
60| <span id="inferencebedrockawsclipath" />AWS CLI path<br />`inferenceBedrockAwsCliPath` | `string` | MDM + Bootstrap<br />Added in 1.13576.0 | — | Absolute path to the aws executable. Leave unset to find it on PATH. |
50| AWS region `inferenceBedrockRegion` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. |
51| Bedrock base URL `inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. |
52| Bedrock service tier `inferenceBedrockServiceTier` | `enum` | MDM + Bootstrap Added in 1.5186.0 | — | Sent as the X-Amzn-Bedrock-Service-Tier header. Leave unset for on-demand. One of: `flex`, `priority`. |
53| AWS bearer token `inferenceBedrockBearerToken` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those. |
54| AWS SSO start URL `inferenceBedrockSsoStartUrl` | `string` | MDM + Bootstrap Added in 1.6259.0 | — | Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below. |
55| AWS SSO region `inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap Added in 1.6259.0 | — | IAM Identity Center home region. |
56| AWS SSO account ID `inferenceBedrockSsoAccountId` | `string` | MDM + Bootstrap Added in 1.6259.0 | — | 12-digit AWS account ID assigned to users in IAM Identity Center. |
57| AWS SSO role name `inferenceBedrockSsoRoleName` | `string` | MDM + Bootstrap Added in 1.6259.0 | — | IAM Identity Center permission-set name granting bedrock:InvokeModel\* on the account above. |
58| AWS profile name `inferenceBedrockProfile` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. |
59| AWS config directory `inferenceBedrockAwsDir` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Folder with AWS config/credentials. Defaults to \~/.aws when no bearer token is set. |
60| AWS CLI path `inferenceBedrockAwsCliPath` | `string` | MDM + Bootstrap Added in 1.13576.0 | — | Absolute path to the aws executable. Leave unset to find it on PATH. |
6161
62<AccordionGroup>
63 <Accordion title="inferenceBedrockServiceTier details">
64 Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.
65 </Accordion>
66</AccordionGroup>
62> **inferenceBedrockServiceTier details**
63>
64> Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.
6765
6866You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
6967
third-party/claude-desktop/mdm Changed · +52 / -56 lines
from line 10
1010
1111Roll out in this order; the numbered sections on this page cover each step in detail.
1212
13<Steps>
14 <Step title="Build a configuration in the app">
15 An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) on their own device.
16 </Step>
13**1. Build a configuration in the app**
1714
18 <Step title="Export the profile">
19 Export the validated configuration in the format your MDM expects.
20 </Step>
15An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) on their own device.
2116
22 <Step title="Allow required network egress">
23 Open the hostnames your configuration requires on your perimeter firewall; the configuration window lists them for the exact settings you chose.
24 </Step>
17**2. Export the profile**
2518
26 <Step title="Deploy the configuration, then the app">
27 Distribute the profile through your MDM, then push the installer. Deploying the configuration first means users open Claude for the first time and land directly in the third-party deployment.
28 </Step>
29</Steps>
19Export the validated configuration in the format your MDM expects.
3020
21**3. Allow required network egress**
22
23Open the hostnames your configuration requires on your perimeter firewall; the configuration window lists them for the exact settings you chose.
24
25**4. Deploy the configuration, then the app**
26
27Distribute the profile through your MDM, then push the installer. Deploying the configuration first means users open Claude for the first time and land directly in the third-party deployment.
28
3129## 1. Build a configuration in the app
3230
3331Launch Claude Desktop. **Do not sign in or create an Anthropic account**; stay on the login screen. From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the configuration window.
from line 34
3634
3735| Section | What you set |
3836| - | - |
39| **Connection** | Inference provider (Gateway, Claude API, Google Cloud's Agent Platform, Bedrock, Bedrock Mantle, or Foundry) and its credentials<br />Model list<br />Organization UUID<br />Optional credential-helper script |
40| **Capabilities** | Which of Cowork, Code, and Chat are available<br />Allowed egress hosts for the sandbox<br />Disabled built-in tools<br />Allowed workspace folders |
41| **Connectors** | Managed MCP servers pushed to all users<br />Whether users can add their own local MCP servers<br />Whether desktop extensions (`.mcpb`) are allowed<br />Whether unsigned extensions are rejected |
42| **Telemetry & updates** | OpenTelemetry collector endpoint<br />Whether auto-updates are blocked, and the enforcement window if not<br />The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) |
43| **Limits** | Per-device token cap and its window length<br />Retention periods after which idle chats, Cowork tasks, and Code sessions are deleted, and the hold that suspends deletion |
44| **Appearance** | Persistent banner shown across the app window<br />Deployment display name and subtitle<br />Whether the signed-in user's identity is shown and exported (end-user attribution)<br />Whether feature announcements are shown |
45| **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL<br />Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
46| **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature<br />**Copy hostnames**, **Download .txt**, and **Test connectivity** actions |
47| **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) delivery model instead of a full MDM profile<br />Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key |
37| **Connection** | Inference provider (Gateway, Claude API, Google Cloud's Agent Platform, Bedrock, Bedrock Mantle, or Foundry) and its credentials Model list Organization UUID Optional credential-helper script |
38| **Capabilities** | Which of Cowork, Code, and Chat are available Allowed egress hosts for the sandbox Disabled built-in tools Allowed workspace folders |
39| **Connectors** | Managed MCP servers pushed to all users Whether users can add their own local MCP servers Whether desktop extensions (`.mcpb`) are allowed Whether unsigned extensions are rejected |
40| **Telemetry & updates** | OpenTelemetry collector endpoint Whether auto-updates are blocked, and the enforcement window if not The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) |
41| **Limits** | Per-device token cap and its window length Retention periods after which idle chats, Cowork tasks, and Code sessions are deleted, and the hold that suspends deletion |
42| **Appearance** | Persistent banner shown across the app window Deployment display name and subtitle Whether the signed-in user's identity is shown and exported (end-user attribution) Whether feature announcements are shown |
43| **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
44| **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature **Copy hostnames**, **Download .txt**, and **Test connectivity** actions |
45| **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) delivery model instead of a full MDM profile Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key |
4846
4947To turn on [Unified Claude](/docs/third-party/claude-desktop/unified-claude#enabling-unified-claude), set `desktopHome` to `standard` in your MDM profile.
5048
51<Note>
52 When a managed (MDM-delivered) configuration is already present on the device, the configuration window opens read-only: it shows what the admin deployed, marks the configuration as organization-managed, and directs users to their IT administrator. To author a new configuration, use a device without a managed profile, or temporarily remove the profile. Profiles that set [only app-behavior keys](#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys) leave the window editable.
53</Note>
49> [!NOTE]
50>
51> When a managed (MDM-delivered) configuration is already present on the device, the configuration window opens read-only: it shows what the admin deployed, marks the configuration as organization-managed, and directs users to their IT administrator. To author a new configuration, use a device without a managed profile, or temporarily remove the profile. Profiles that set [only app-behavior keys](#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys) leave the window editable.
5452
5553## 2. Export the profile
5654
from line 81
8381
8482In your MDM, scope each exported profile to the corresponding device or user group. Targeting is handled by your MDM's assignment rules; the configuration name is for your authoring workflow and is not part of the deployed profile.
8583
86<Note>
87 On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap).
88</Note>
84> [!NOTE]
85>
86> On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap).
8987
9088## 3. Allow required network egress
9189
9290The hosts the app needs to reach depend on the configuration you built: your inference provider's endpoint is always required, and each telemetry, update, and service setting you leave enabled adds its own hosts. The configuration window shows the exact allowlist for your settings and can export it as a text file for your network team.
9391
94<Warning>
95 `downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the Claude Code binary. Without it, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. The [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation) builds both components into the installer package, so Chat conversations, Cowork tasks, and Code sessions on the device start without this host. The app still requests the model catalog from `downloads.claude.ai` unless [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) names a mirror inside your network, and sessions start whether or not that request succeeds.
96</Warning>
92> [!WARNING]
93>
94> `downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the Claude Code binary. Without it, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. The [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation) builds both components into the installer package, so Chat conversations, Cowork tasks, and Code sessions on the device start without this host. The app still requests the model catalog from `downloads.claude.ai` unless [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) names a mirror inside your network, and sessions start whether or not that request succeeds.
9795
9896Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the full list of hosts grouped by the setting that controls each one, and for the distinction between the perimeter firewall and the in-app sandbox allowlist.
9997
from line 99
10199
102100Push the exported configuration through your MDM. The app reads from these locations:
103101
104<Tabs>
105 <Tab title="macOS">
106 | Source | Path | Precedence |
107 | - | - | - |
108 | Managed (per-user) | `/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist` | Highest |
109 | Managed (machine) | `/Library/Managed Preferences/com.anthropic.claudefordesktop.plist` | |
110 | Local (user) | `~/Library/Application Support/Claude-3p/configLibrary/` | Lowest |
102**macOS**
111103
112 A `.mobileconfig` profile delivered by MDM lands in the Managed Preferences locations automatically. Both managed paths are read; where a key appears in both, the per-user value wins.
113 </Tab>
104| Source | Path | Precedence |
105| - | - | - |
106| Managed (per-user) | `/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist` | Highest |
107| Managed (machine) | `/Library/Managed Preferences/com.anthropic.claudefordesktop.plist` | |
108| Local (user) | `~/Library/Application Support/Claude-3p/configLibrary/` | Lowest |
114109
115 <Tab title="Windows">
116 | Source | Path | Precedence |
117 | - | - | - |
118 | Machine policy | `HKLM\SOFTWARE\Policies\Claude` | Highest |
119 | User policy | `HKCU\SOFTWARE\Policies\Claude` | |
120 | Local (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` | Lowest |
110A `.mobileconfig` profile delivered by MDM lands in the Managed Preferences locations automatically. Both managed paths are read; where a key appears in both, the per-user value wins.
121111
122 A Group Policy Object or Intune configuration profile writes to the registry policy paths. The hives are not merged: when machine policy is present (any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude`, including an empty string, and the key's unnamed default value when set), the app ignores `HKCU\SOFTWARE\Policies\Claude` entirely. Deploy the complete configuration to one hive; machine policy (`HKLM`) is the recommended location.
112**Windows**
123113
124 <Warning>
125 Values must sit directly under `HKLM\SOFTWARE\Policies\Claude` or `HKCU\SOFTWARE\Policies\Claude`. The app never reads values nested in a subkey, as some ADMX-based and Policy CSP tooling writes them: they do not apply as configuration and do not count as machine policy being present. Write values as `REG_SZ` (`REG_DWORD` is also accepted for boolean and integer keys and is read as its decimal value). Avoid `REG_EXPAND_SZ`: the app counts it as machine policy being present but cannot read its contents, so a single `REG_EXPAND_SZ` value under `HKLM` disables user policy without supplying any configuration. The app cannot see `REG_QWORD`, `REG_MULTI_SZ`, or `REG_BINARY` values at all.
126 </Warning>
114| Source | Path | Precedence |
115| - | - | - |
116| Machine policy | `HKLM\SOFTWARE\Policies\Claude` | Highest |
117| User policy | `HKCU\SOFTWARE\Policies\Claude` | |
118| Local (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` | Lowest |
127119
128 <Note>
129 In releases before v1.19367.0, the app read both hives and merged them key by key, with the `HKLM` value winning where a key appeared in both. Fleets that split keys across both hives must consolidate the full configuration into one hive before updating to v1.19367.0 or later.
130 </Note>
131 </Tab>
132</Tabs>
120A Group Policy Object or Intune configuration profile writes to the registry policy paths. The hives are not merged: when machine policy is present (any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude`, including an empty string, and the key's unnamed default value when set), the app ignores `HKCU\SOFTWARE\Policies\Claude` entirely. Deploy the complete configuration to one hive; machine policy (`HKLM`) is the recommended location.
121
122> [!WARNING]
123>
124> Values must sit directly under `HKLM\SOFTWARE\Policies\Claude` or `HKCU\SOFTWARE\Policies\Claude`. The app never reads values nested in a subkey, as some ADMX-based and Policy CSP tooling writes them: they do not apply as configuration and do not count as machine policy being present. Write values as `REG_SZ` (`REG_DWORD` is also accepted for boolean and integer keys and is read as its decimal value). Avoid `REG_EXPAND_SZ`: the app counts it as machine policy being present but cannot read its contents, so a single `REG_EXPAND_SZ` value under `HKLM` disables user policy without supplying any configuration. The app cannot see `REG_QWORD`, `REG_MULTI_SZ`, or `REG_BINARY` values at all.
125
126> [!NOTE]
127>
128> In releases before v1.19367.0, the app read both hives and merged them key by key, with the `HKLM` value winning where a key appeared in both. Fleets that split keys across both hives must consolidate the full configuration into one hive before updating to v1.19367.0 or later.
133129
134130When a managed source sets any key other than the [app-behavior keys](#update-keys-and-managed-precedence) listed below, the managed configuration takes effect, the in-app configuration window becomes read-only, and locally authored values in `configLibrary/` are ignored.
135131
third-party/claude-desktop/move-to-claude-enterprise Changed · +28 / -32 lines
from line 4
44
55Move Claude Desktop from your cloud provider, where the app is named Claude (third-party), to Claude Enterprise. After one configuration change, each user's work migrates when they sign in on the same computer.
66
7<img className="block dark:hidden" src="https://mintcdn.com/claude-ai/ijOo7DTs1r-Xf3X5/images/third-party/diagrams/move-to-claude-enterprise-flow.svg?fit=max&auto=format&n=ijOo7DTs1r-Xf3X5&q=85&s=ed9723f563092b8ab40c50ee46afd172" alt="Flow diagram: IT updates Claude Desktop, turns on two skills settings, and changes the configuration. Cloud provider controls stop applying. Each user signs in to Claude Enterprise. Claude Desktop migrates earlier work (chats, sessions, projects, scheduled tasks), then adds skills, plugins, extensions, and local MCP servers. The user approves tools in scheduled tasks, adds their instructions, and checks their skills." width="1000" height="548" data-path="images/third-party/diagrams/move-to-claude-enterprise-flow.svg" />
7
88
9<img className="hidden dark:block" src="https://mintcdn.com/claude-ai/ijOo7DTs1r-Xf3X5/images/third-party/diagrams/move-to-claude-enterprise-flow-dark.svg?fit=max&auto=format&n=ijOo7DTs1r-Xf3X5&q=85&s=a85b1f96e055e395d3ce901f425e06ec" alt="Flow diagram: IT updates Claude Desktop, turns on two skills settings, and changes the configuration. Cloud provider controls stop applying. Each user signs in to Claude Enterprise. Claude Desktop migrates earlier work (chats, sessions, projects, scheduled tasks), then adds skills, plugins, extensions, and local MCP servers. The user approves tools in scheduled tasks, adds their instructions, and checks their skills." width="1000" height="548" data-path="images/third-party/diagrams/move-to-claude-enterprise-flow-dark.svg" />
10
119## What is migrated
1210
1311The migration never changes or deletes the Claude (third-party) data.
from line 60
6260
6361Remove the old keys and set the new one in one change to the policy or profile that carries your Claude settings: an `HKEY_LOCAL_MACHINE` policy on Windows (not `HKEY_CURRENT_USER`), or a [configuration profile](/docs/third-party/claude-desktop/mdm) on macOS.
6462
65<Steps>
66 <Step title="Remove the cloud provider keys">
67 Remove every key that puts the app in third-party mode, such as those that start with `inference` or `bootstrap`. Also remove [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) and [`deploymentOrganizationUuid`](/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid). Leave other keys in place. If your settings come from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), copy the keys you want to keep into the policy or profile itself.
63**1. Remove the cloud provider keys**
6864
69 The desktop extensions feature is on after the change unless [`isDesktopExtensionEnabled`](/docs/third-party/claude-desktop/configuration#isdesktopextensionenabled) is set to `false`.
70 </Step>
65Remove every key that puts the app in third-party mode, such as those that start with `inference` or `bootstrap`. Also remove [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) and [`deploymentOrganizationUuid`](/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid). Leave other keys in place. If your settings come from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), copy the keys you want to keep into the policy or profile itself.
7166
72 <Step title="Set your organization ID">
73 Copy the **Organization ID** from [**Organization settings > Organization and access**](https://claude.ai/admin-settings/organization). Set `importThirdPartyHistoryIntoOrgUUID` to this ID, without braces or quotation marks. To keep Claude on these computers from using another organization or a personal account, where nothing migrates, you can also set `forceLoginOrgUUID` to the same ID. The app then blocks accounts that aren't in that organization.
67The desktop extensions feature is on after the change unless [`isDesktopExtensionEnabled`](/docs/third-party/claude-desktop/configuration#isdesktopextensionenabled) is set to `false`.
7468
75 On Windows, in an elevated PowerShell window:
69**2. Set your organization ID**
7670
77 ```powershell theme={null}
78 reg add "HKLM\SOFTWARE\Policies\Claude" /v importThirdPartyHistoryIntoOrgUUID /t REG_SZ /d "YOUR-ORGANIZATION-UUID" /f
79 # Optional: keeps these computers on this organization
80 reg add "HKLM\SOFTWARE\Policies\Claude" /v forceLoginOrgUUID /t REG_SZ /d "YOUR-ORGANIZATION-UUID" /f
81 ```
71Copy the **Organization ID** from [**Organization settings > Organization and access**](https://claude.ai/admin-settings/organization). Set `importThirdPartyHistoryIntoOrgUUID` to this ID, without braces or quotation marks. To keep Claude on these computers from using another organization or a personal account, where nothing migrates, you can also set `forceLoginOrgUUID` to the same ID. The app then blocks accounts that aren't in that organization.
8272
83 On macOS, in a custom settings payload for the preference domain `com.anthropic.claudefordesktop`:
73On Windows, in an elevated PowerShell window:
8474
85 ```xml theme={null}
86 <key>importThirdPartyHistoryIntoOrgUUID</key>
87 <string>YOUR-ORGANIZATION-UUID</string>
88 <!-- Optional: keeps these computers on this organization -->
89 <key>forceLoginOrgUUID</key>
90 <string>YOUR-ORGANIZATION-UUID</string>
91 ```
92 </Step>
75```powershell theme={null}
76reg add "HKLM\SOFTWARE\Policies\Claude" /v importThirdPartyHistoryIntoOrgUUID /t REG_SZ /d "YOUR-ORGANIZATION-UUID" /f
77# Optional: keeps these computers on this organization
78reg add "HKLM\SOFTWARE\Policies\Claude" /v forceLoginOrgUUID /t REG_SZ /d "YOUR-ORGANIZATION-UUID" /f
79```
9380
94 <Step title="Roll out in stages">
95 Deploy to a few computers on each operating system, then to the rest. Send users the [steps for each user](#steps-for-each-user).
96 </Step>
97</Steps>
81On macOS, in a custom settings payload for the preference domain `com.anthropic.claudefordesktop`:
9882
83```xml theme={null}
84<key>importThirdPartyHistoryIntoOrgUUID</key>
85<string>YOUR-ORGANIZATION-UUID</string>
86<!-- Optional: keeps these computers on this organization -->
87<key>forceLoginOrgUUID</key>
88<string>YOUR-ORGANIZATION-UUID</string>
89```
90
91**3. Roll out in stages**
92
93Deploy to a few computers on each operating system, then to the rest. Send users the [steps for each user](#steps-for-each-user).
94
9995Afterward, keep `importThirdPartyHistoryIntoOrgUUID` deployed and keep the Claude (third-party) data. **Settings > Import** needs both. To roll back, restore your earlier configuration. Work done after the migration stays in Claude Enterprise and doesn't appear in Claude (third-party).
10096
10197If nothing migrates, Claude shows no error on screen. Check that the key arrived as a device policy, that no third-party key remains, and that the user signed in to this organization. The app's `main.log` usually gives the reason.
from line 104
108104* In **Settings > Import**, click **Add instructions** for each set of instructions listed, and **Import…** if a skill is missing from **Customize > Skills**.
109105* Set up remote connectors again, and add any keys or sign-ins your plugins and extensions need.
110106
111<Warning>
112 Don't click **Remove** on the home page banner or in **Settings > Import**. It deletes your migrated chats, sessions, and projects, including any work you added after the migration.
113</Warning>
107> [!WARNING]
108>
109> Don't click **Remove** on the home page banner or in **Settings > Import**. It deletes your migrated chats, sessions, and projects, including any work you added after the migration.
114110
third-party/claude-desktop/network-proxy Changed · +9 / -9 lines
from line 37
3737
3838## Pin a proxy from managed configuration
3939
40<Note>
41 Pinning requires Claude Desktop 1.44121.1 or later. Earlier releases ignore the `egressProxyUrl` and `egressProxyPacUrl` keys and keep following the OS proxy settings.
42</Note>
40> [!NOTE]
41>
42> Pinning requires Claude Desktop 1.44121.1 or later. Earlier releases ignore the `egressProxyUrl` and `egressProxyPacUrl` keys and keep following the OS proxy settings.
4343
4444If you want the app, the agent, and (on macOS and Windows) Cowork's sandboxed shell to use a specific proxy regardless of what the device's OS settings say, set one of two managed configuration keys:
4545
from line 104
104104* **Helper scripts.** An `inferenceCredentialHelper` or MCP `headersHelper` script runs with the app's environment and no injected proxy variables, because helpers typically talk to internal vaults or identity providers that should not go through the inference proxy. If a helper needs a proxy, set it inside the script.
105105* **Programs that ignore proxy variables.** The agent passes `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` to the programs it launches on the device, but a program that does not honor those variables connects directly if the network allows it. The only complete control for this case is blocking direct egress at the network layer.
106106
107<Warning>
108 A proxy setting is routing, not enforcement. Nothing on this page prevents a process on the device from connecting directly if the network permits it. If you need a guarantee that traffic leaves only through your proxy, block direct egress at the firewall or secure web gateway and allow only the proxy. The inverse also holds: on an open network, a misconfigured or unreachable PAC script can quietly result in direct connections.
109</Warning>
107> [!WARNING]
108>
109> A proxy setting is routing, not enforcement. Nothing on this page prevents a process on the device from connecting directly if the network permits it. If you need a guarantee that traffic leaves only through your proxy, block direct egress at the firewall or secure web gateway and allow only the proxy. The inverse also holds: on an open network, a misconfigured or unreachable PAC script can quietly result in direct connections.
110110
111111### The agent uses one proxy
112112
from line 121
121121
122122## Interaction with Claude Code managed settings
123123
124<Note>
125 The precedence described here requires Claude Desktop 1.44121.1 or later, the same release as the pinned-proxy keys above.
126</Note>
124> [!NOTE]
125>
126> The precedence described here requires Claude Desktop 1.44121.1 or later, the same release as the pinned-proxy keys above.
127127
128128If you deploy Claude Code [managed settings](https://code.claude.com/docs/en/settings#settings-files) on the device (a `managed-settings.json` file or an OS-level Claude Code policy) and its `env` block sets `HTTPS_PROXY`, `HTTP_PROXY`, or `NO_PROXY`, those values apply to the agent in Chat, Cowork, and Code sessions alike and take precedence over what the app would have supplied. Precedence is per variable: a managed `HTTPS_PROXY` replaces the app's proxy while the app's loopback `NO_PROXY` entries stay in place, and a managed `NO_PROXY` replaces the app's list (the loopback entries are appended for you when the app is also supplying the proxy). See Claude Code's [network configuration](https://code.claude.com/docs/en/network-config) page for the variables themselves.
129129
third-party/claude-desktop/overview Changed · +12 / -14 lines
from line 81
8181
8282## Next steps
8383
84<Columns cols={2}>
85 <Card title="Installation and setup" icon="download" href="/docs/third-party/claude-desktop/installation">
86 Roll out Claude Desktop on 3P to your organization with MDM, or configure a single machine for evaluation.
87 </Card>
84> **[Installation and setup](/docs/third-party/claude-desktop/installation)**
85>
86> Roll out Claude Desktop on 3P to your organization with MDM, or configure a single machine for evaluation.
8887
89 <Card title="Configuration reference" icon="sliders" href="/docs/third-party/claude-desktop/configuration">
90 Every managed-configuration key, what it does, and recommended security profiles.
91 </Card>
88> **[Configuration reference](/docs/third-party/claude-desktop/configuration)**
89>
90> Every managed-configuration key, what it does, and recommended security profiles.
9291
93 <Card title="Extensions" icon="puzzle-piece" href="/docs/third-party/claude-desktop/extensions">
94 Deploy MCP servers, plugins, skills, and hooks across your fleet.
95 </Card>
92> **[Extensions](/docs/third-party/claude-desktop/extensions)**
93>
94> Deploy MCP servers, plugins, skills, and hooks across your fleet.
9695
97 <Card title="Telemetry and egress" icon="shield-halved" href="/docs/third-party/claude-desktop/telemetry">
98 What the app sends to Anthropic, how to turn it off, and the firewall allowlist you'll need.
99 </Card>
100</Columns>
96> **[Telemetry and egress](/docs/third-party/claude-desktop/telemetry)**
97>
98> What the app sends to Anthropic, how to turn it off, and the firewall allowlist you'll need.
10199
third-party/claude-desktop/ssh-remote-sessions Changed · +16 / -16 lines
from line 4
44
55An SSH remote session is a [Code](/docs/third-party/claude-desktop/code) session whose Claude Code engine runs on another machine that the user reaches over SSH, while the session's interface stays in Claude Desktop on the user's device. Claude Desktop connects to the host, places the engine there, and starts the session with the inference credential and policy from your managed configuration. Users can work on code that lives on a development server, a build box, or a cloud workstation without copying it to their device. In Claude Desktop on third-party (3P), SSH remote sessions are off until you set the [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) key, because enabling them sends your inference credential to the hosts users connect to.
66
7<Note>
8 SSH remote sessions are in beta in Claude Desktop on 3P and require Claude Desktop 1.40609.0 or later. The in-app configuration window marks `sshHostAllowlist` with a **Beta** pill.
9</Note>
7> [!NOTE]
8>
9> SSH remote sessions are in beta in Claude Desktop on 3P and require Claude Desktop 1.40609.0 or later. The in-app configuration window marks `sshHostAllowlist` with a **Beta** pill.
1010
1111## How a remote session works
1212
from line 92
9292
9393To cover every user of a host, put the hooks in [Claude Code managed settings](https://code.claude.com/docs/en/settings#settings-files) on the host instead, which on a Linux host is the file `/etc/claude-code/managed-settings.json`. If the host already has Claude Code managed settings, add the hooks to those and leave [`parentSettingsBehavior`](https://code.claude.com/docs/en/settings-reference#parentsettingsbehavior) as it is, set or unset. Changing it changes how those settings combine with the policy that Claude Desktop supplies. If the host has none yet, also set `parentSettingsBehavior` to `"merge"` in the managed settings that you create.
9494
95<Warning>
96 By default, Claude Code managed settings on the host replace the policy that Claude Desktop supplies, even if they hold only hooks (see [Managed configuration on the remote host](#managed-configuration-on-the-remote-host)). With `parentSettingsBehavior` set to `"merge"`, the policy that Claude Desktop supplies still applies, layered under the host's own policy.
97</Warning>
95> [!WARNING]
96>
97> By default, Claude Code managed settings on the host replace the policy that Claude Desktop supplies, even if they hold only hooks (see [Managed configuration on the remote host](#managed-configuration-on-the-remote-host)). With `parentSettingsBehavior` set to `"merge"`, the policy that Claude Desktop supplies still applies, layered under the host's own policy.
9898
9999### Where MCP servers run in a remote session
100100
from line 175
175175
176176## Inference credentials on the remote host
177177
178<Warning>
179 A remote session runs Claude Code on the SSH host with your organization's inference credential in its process environment, for as long as that process runs, including while Claude Desktop is closed. Anyone who can read that process's environment on the host, such as the same user account or a root user, can read the credential. List only hosts you trust with it, and prefer a credential that expires (single sign-on, or a credential helper that issues short-lived tokens) over a long-lived key.
180</Warning>
178> [!WARNING]
179>
180> A remote session runs Claude Code on the SSH host with your organization's inference credential in its process environment, for as long as that process runs, including while Claude Desktop is closed. Anyone who can read that process's environment on the host, such as the same user account or a root user, can read the credential. List only hosts you trust with it, and prefer a credential that expires (single sign-on, or a credential helper that issues short-lived tokens) over a long-lived key.
181181
182182The remote engine uses only the credential Claude Desktop passes in its environment. It ignores credentials already on the host, such as an AWS profile or application default credentials, and Claude Desktop copies no credential files there. Credential kinds that live in a file on the device are refused at session start.
183183
from line 392
392392
393393The sandbox lets shell commands that Claude runs with its Bash tool write in the folder the session was opened in, and the repository's `.git` folder is outside that folder. Of these commands, the ones that write to the `.git` folder fail, such as `git add` and `git commit`. Have the user start a new session at the top of the repository.
394394
395<Note>
396 These cases are covered elsewhere:
397
398 * **An `allowedWorkspaceFolders` entry with `mode` set to `ro`**: see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host)
399 * **A message with `unable to unlink old`**: see [A git command fails with `unable to unlink old`](https://code.claude.com/docs/en/sandboxing#a-git-command-fails-with-unable-to-unlink-old)
400 * **The other places that the sandbox lets these commands write to**: see [Filesystem isolation](https://code.claude.com/docs/en/sandboxing#filesystem-isolation) and the `allowedWorkspaceFolders` row under [Applied as managed policy](/docs/third-party/claude-desktop/code#applied-as-managed-policy)
401</Note>
395> [!NOTE]
396>
397> These cases are covered elsewhere:
398>
399> * **An `allowedWorkspaceFolders` entry with `mode` set to `ro`**: see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host)
400> * **A message with `unable to unlink old`**: see [A git command fails with `unable to unlink old`](https://code.claude.com/docs/en/sandboxing#a-git-command-fails-with-unable-to-unlink-old)
401> * **The other places that the sandbox lets these commands write to**: see [Filesystem isolation](https://code.claude.com/docs/en/sandboxing#filesystem-isolation) and the `allowedWorkspaceFolders` row under [Applied as managed policy](/docs/third-party/claude-desktop/code#applied-as-managed-policy)
402402
403403## Related
404404
third-party/claude-desktop/telemetry Changed · +60 / -61 lines
from line 22
2222
2323On Claude Desktop 2.7032.0 and later, the [**Keep only your organization ID and restrictions on disk**](/docs/third-party/claude-desktop/admin-console#configuration-kept-on-devices) switch in the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) also stops the app's crash and performance reports, even while `disableEssentialTelemetry` is `false`.
2424
25<Warning>
26 Disabling essential telemetry opts you into a **manual support model**. Anthropic will have zero remote visibility into failures on your fleet, so to get help with an issue your team will need to collect application logs from affected machines and send them to Anthropic directly. Leave this enabled during initial rollout.
27</Warning>
25> [!WARNING]
26>
27> Disabling essential telemetry opts you into a **manual support model**. Anthropic will have zero remote visibility into failures on your fleet, so to get help with an issue your team will need to collect application logs from affected machines and send them to Anthropic directly. Leave this enabled during initial rollout.
2828
2929### Non-essential telemetry
3030
from line 68
6868
6969Set [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) to the base address of your collector's OTLP/HTTP receiver, for example `https://otel-collector.example.com:4318`. The app appends the OpenTelemetry request paths itself (`/v1/logs`, `/v1/metrics`, and `/v1/traces` when [traces](#traces-beta) are enabled), so enter the address without those suffixes. A path prefix in front of them, such as `https://observability.example.com/otlp`, is kept.
7070
71<Note>
72 With `otlpEndpoint` set, all signals go to this one address. Claude Desktop sets Claude Code's per-signal endpoint variables (`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) itself. Chat, Cowork, and Code sessions ignore the same variables in Claude Code's own settings on the device, including managed settings. To send signals to different places, route them in your collector.
73</Note>
71> [!NOTE]
72>
73> With `otlpEndpoint` set, all signals go to this one address. Claude Desktop sets Claude Code's per-signal endpoint variables (`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) itself. Chat, Cowork, and Code sessions ignore the same variables in Claude Code's own settings on the device, including managed settings. To send signals to different places, route them in your collector.
7474
7575The receiver must implement the OpenTelemetry protocol (OTLP) over HTTP in both its protobuf and JSON encodings, as an OpenTelemetry Collector does by default. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and set `otlpEndpoint` to the collector's address. Each device opens its own connection to the collector, so the collector must present a TLS certificate the operating system trusts. See [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy#tls-intercepting-proxies) if a TLS-intercepting proxy sits in between.
7676
from line 156
1561561. **Perimeter firewall:** your corporate network controls what the device can reach. The hostnames below are what you allowlist here.
1571572. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) key controls what the agent's web-fetch and shell tools can reach. This is independent of the perimeter. See [Web Fetch](/docs/third-party/claude-desktop/web-tools#web-fetch) for where the key applies.
158158
159<Note>
160 The **Egress** section of the in-app configuration window is the authoritative source for your deployment. It computes the exact allowlist from your current settings, updates as you change them, and can export the list as a text file for your firewall team. Use the tables below as a static reference; defer to the configuration window for the precise set your build requires.
161</Note>
159> [!NOTE]
160>
161> The **Egress** section of the in-app configuration window is the authoritative source for your deployment. It computes the exact allowlist from your current settings, updates as you change them, and can export the list as a text file for your firewall team. Use the tables below as a static reference; defer to the configuration window for the precise set your build requires.
162162
163163All traffic is HTTPS on port 443. Allowlist by hostname (SNI); path-level rules aren't required.
164164
from line 175
175175
176176The host(s) for your configured provider. These carry conversation content.
177177
178<Tabs>
179 <Tab title="Google Cloud's Agent Platform">
180 | Host | Purpose |
181 | - | - |
182 | `<region>-aiplatform.googleapis.com` | Model inference for single regions. The `global` region uses `aiplatform.googleapis.com`, and the `eu` / `us` multi-regions use `aiplatform.eu.rep.googleapis.com` / `aiplatform.us.rep.googleapis.com`. Replaced by the host of `inferenceVertexBaseUrl` if set. |
183 | `oauth2.googleapis.com` | Google auth token exchange |
184 | `sts.googleapis.com` | Google auth token exchange |
185 | `accounts.google.com` | Google auth token exchange |
186 | `iamcredentials.googleapis.com` | Google auth token exchange |
187 </Tab>
178**Google Cloud's Agent Platform**
188179
189 <Tab title="Amazon Bedrock">
190 | Host | Purpose |
191 | - | - |
192 | `bedrock-runtime.<region>.amazonaws.com` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
193 | `bedrock.<region>.amazonaws.com` | Control plane (model discovery) |
194 | `sts.amazonaws.com`, `sts.<region>.amazonaws.com` | STS token exchange (profile auth only) |
195 | `portal.sso.<sso-region>.amazonaws.com`, `oidc.<sso-region>.amazonaws.com` | IAM Identity Center sign-in and token refresh, for [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock#in-app-aws-sign-in) and for named profiles that use IAM Identity Center. `<sso-region>` is `inferenceBedrockSsoRegion` (or the profile's `sso_region`) and can differ from the inference region. |
180| Host | Purpose |
181| - | - |
182| `<region>-aiplatform.googleapis.com` | Model inference for single regions. The `global` region uses `aiplatform.googleapis.com`, and the `eu` / `us` multi-regions use `aiplatform.eu.rep.googleapis.com` / `aiplatform.us.rep.googleapis.com`. Replaced by the host of `inferenceVertexBaseUrl` if set. |
183| `oauth2.googleapis.com` | Google auth token exchange |
184| `sts.googleapis.com` | Google auth token exchange |
185| `accounts.google.com` | Google auth token exchange |
186| `iamcredentials.googleapis.com` | Google auth token exchange |
196187
197 With `inferenceBedrockBearerToken` set, the runtime and control-plane hosts are required.
188**Amazon Bedrock**
198189
199 For AWS GovCloud regions (`us-gov-*`), the app automatically uses the FIPS endpoints instead: `bedrock-runtime-fips.<region>.amazonaws.com` and `bedrock-fips.<region>.amazonaws.com`.
200 </Tab>
190| Host | Purpose |
191| - | - |
192| `bedrock-runtime.<region>.amazonaws.com` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
193| `bedrock.<region>.amazonaws.com` | Control plane (model discovery) |
194| `sts.amazonaws.com`, `sts.<region>.amazonaws.com` | STS token exchange (profile auth only) |
195| `portal.sso.<sso-region>.amazonaws.com`, `oidc.<sso-region>.amazonaws.com` | IAM Identity Center sign-in and token refresh, for [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock#in-app-aws-sign-in) and for named profiles that use IAM Identity Center. `<sso-region>` is `inferenceBedrockSsoRegion` (or the profile's `sso_region`) and can differ from the inference region. |
201196
202 <Tab title="Amazon Bedrock Mantle">
203 | Host | Purpose |
204 | - | - |
205 | `bedrock-mantle.<region>.api.aws` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
206 </Tab>
197With `inferenceBedrockBearerToken` set, the runtime and control-plane hosts are required.
207198
208 <Tab title="Microsoft Foundry">
209 | Host | Purpose |
210 | - | - |
211 | `<resource>.services.ai.azure.com` | Model inference. Replaced by the host of `inferenceFoundryBaseUrl` if set. |
212 | `login.microsoftonline.com` | Entra ID auth (interactive sign-in only) |
213 </Tab>
199For AWS GovCloud regions (`us-gov-*`), the app automatically uses the FIPS endpoints instead: `bedrock-runtime-fips.<region>.amazonaws.com` and `bedrock-fips.<region>.amazonaws.com`.
214200
215 <Tab title="Gateway">
216 | Host | Purpose |
217 | - | - |
218 | Host of `inferenceGatewayBaseUrl` | Model inference |
219 </Tab>
201**Amazon Bedrock Mantle**
220202
221 <Tab title="Claude API">
222 | Host | Purpose |
223 | - | - |
224 | `api.anthropic.com` | Model inference; token exchange, renewal, and revocation for browser sign-in |
225 | `platform.claude.com` | Browser sign-in page. Dialed only when no static key or credential helper is configured; the in-app Egress list includes it for every Claude API deployment. |
226 | `hcaptcha.com`, `*.hcaptcha.com` | Browser check on the sign-in and approval pages of **Sign in with Claude Console**, which open in the user's default browser. Allow these hosts whether or not the in-app Egress list on your version of Claude Desktop shows them. If these hosts are blocked, signing in or approving can fail with a message that the browser couldn't be verified. |
227 </Tab>
228</Tabs>
203| Host | Purpose |
204| - | - |
205| `bedrock-mantle.<region>.api.aws` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
229206
207**Microsoft Foundry**
208
209| Host | Purpose |
210| - | - |
211| `<resource>.services.ai.azure.com` | Model inference. Replaced by the host of `inferenceFoundryBaseUrl` if set. |
212| `login.microsoftonline.com` | Entra ID auth (interactive sign-in only) |
213
214**Gateway**
215
216| Host | Purpose |
217| - | - |
218| Host of `inferenceGatewayBaseUrl` | Model inference |
219
220**Claude API**
221
222| Host | Purpose |
223| - | - |
224| `api.anthropic.com` | Model inference; token exchange, renewal, and revocation for browser sign-in |
225| `platform.claude.com` | Browser sign-in page. Dialed only when no static key or credential helper is configured; the in-app Egress list includes it for every Claude API deployment. Browser sign-in also needs the hosts that serve the browser check on the sign-in and approval pages, listed under [Optional features](#optional-features). |
226
230227### Auto-updates (`disableAutoUpdates: false`)
231228
232229| Host | Purpose |
from line 286
289286| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured |
290287| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured |
291288| `api.anthropic.com` | [Code](/docs/third-party/claude-desktop/code) sessions can use Web Fetch and [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch)) |
289| `hcaptcha.com`, `*.hcaptcha.com` | Users sign in with **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api) with no static key or credential helper). Its sign-in and approval pages open in the user's default browser and run a browser check from these hosts. Allow them even when the in-app Egress list doesn't show them. If they're blocked, signing in or approving can fail with a message that the browser couldn't be verified |
292290| `claude.ai`, `hcaptcha.com`, `*.hcaptcha.com`, `api.anthropic.com`, `storage.googleapis.com` | [Import from claude.ai](/docs/third-party/claude-desktop/import) is enabled (`claudeAiImport` with `enabled` set to `true`). Used only while a user signs in to claude.ai and fetches an export in the import wizard; importing a downloaded export file needs none of them. The two `hcaptcha.com` entries serve the browser check on the claude.ai sign-in and approval pages |
293291| `releases.claude.com` | The [built-in browser](/docs/third-party/claude-desktop/browser) is turned on (`builtinBrowserEnabled` set to `true`), for its [site safety check](/docs/third-party/claude-desktop/browser#site-safety-check) |
294292| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set). With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](/docs/third-party/claude-desktop/ssh-remote-sessions#host-requirements)) |
from line 309
311309These optional features add hosts back when you turn them on:
312310
313311* [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) download the remote-session components from `downloads.claude.ai`. The offline installer bundles those components for Linux x64 and arm64 hosts, so devices installed with it download them only when connecting to hosts on other platforms.
312* **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api) with no static key or credential helper) loads a browser check from `hcaptcha.com` and `*.hcaptcha.com` on its sign-in and approval pages.
314313* [Import from claude.ai](/docs/third-party/claude-desktop/import) reaches `claude.ai`, `api.anthropic.com`, and `storage.googleapis.com` (for the export download) only while a user signs in to claude.ai and fetches an export in the import wizard. The claude.ai sign-in and approval pages also load a browser check from `hcaptcha.com` and `*.hcaptcha.com`.
315314* The [built-in browser](/docs/third-party/claude-desktop/browser) contacts `releases.claude.com` for its [site safety check](/docs/third-party/claude-desktop/browser#site-safety-check).
316315* With the [remote Microsoft 365 connector](/docs/third-party/claude-desktop/connectors-m365#remote-connector), the app connects to the connector service that Anthropic hosts, at the host in the entry's `url` (`microsoft365.mcp.claude.com` in the setup steps).
317316
318An app that receives its configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still connects to Anthropic with all of these keys set. It never fetches the model catalog (its model names and options come from the console's settings), and it contacts `api.anthropic.com` at every launch and at each configuration check (every 10 minutes by default) to download its configuration. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in pages load a browser check from `hcaptcha.com` and `*.hcaptcha.com`. While the organization's **Report desktop usage to this organization** switch is on, the app also sends [usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) counts to `api.anthropic.com` every few minutes during use. You turn the telemetry categories for these apps on and off on the console's **Telemetry & updates** page.
317An app that receives its configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still connects to Anthropic with all of these keys set. It never fetches the model catalog (its model names and options come from the console's settings), and it contacts `api.anthropic.com` at every launch and at each configuration check (every 10 minutes by default) to download its configuration. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in and approval pages load a browser check from `hcaptcha.com` and `*.hcaptcha.com`, whichever sign-in method your organization uses. While the organization's **Report desktop usage to this organization** switch is on, the app also sends [usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) counts to `api.anthropic.com` every few minutes during use. You turn the telemetry categories for these apps on and off on the console's **Telemetry & updates** page.
319318
320319These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page.
321320
third-party/claude-desktop/unified-claude Changed · +3 / -3 lines
from line 2
22
33> Unified Claude combines Chat and Cowork into one experience, with Cowork's agentic capabilities.
44
5<Note>
6 Unified Claude is in beta. It is opt-in until November 10, when it becomes enforced for all Desktop 3P deployments. New [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) organizations start with Unified Claude on.
7</Note>
5> [!NOTE]
6>
7> Unified Claude is in beta. It is opt-in until November 10, when it becomes enforced for all Desktop 3P deployments. New [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) organizations start with Unified Claude on.
88
99Unified Claude combines Chat and Cowork into one experience in Claude Desktop 3P. Users get a single Claude interface for both quick chats and longer agentic tasks. [Code](/docs/third-party/claude-desktop/code) stays separate.
1010
third-party/claude-desktop/vertex Changed · +82 / -88 lines
from line 16
1616| Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | The helper executable on each device | Depends on what the helper obtains | The app sends the token the helper prints as the bearer on each inference request. |
1717| You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway) instead of Google Cloud's Agent Platform | None | At your gateway | The proxy holds the Google Cloud credentials; the app authenticates only to the proxy. |
1818
19<Warning>
20 If your Google Workspace or Cloud Identity organization enforces a **Google Cloud session length** of a few hours or less (Admin console → Security → Google Cloud session control), the in-app Google sign-in stores a refresh token that is subject to that policy, and users will be prompted to sign in again each time it expires. For short session policies, either mark your OAuth client as a [trusted app exempt from reauthentication](https://support.google.com/a/answer/9368756), or use a service-account key, Workforce Identity sign-in, or the gateway provider instead.
21</Warning>
19> [!WARNING]
20>
21> If your Google Workspace or Cloud Identity organization enforces a **Google Cloud session length** of a few hours or less (Admin console → Security → Google Cloud session control), the in-app Google sign-in stores a refresh token that is subject to that policy, and users will be prompted to sign in again each time it expires. For short session policies, either mark your OAuth client as a [trusted app exempt from reauthentication](https://support.google.com/a/answer/9368756), or use a service-account key, Workforce Identity sign-in, or the gateway provider instead.
2222
2323## How the two sign-in flows compare
2424
from line 124
124124
125125These steps are performed once per Google Cloud project, regardless of which authentication approach you chose. You need a project with Owner or Editor access.
126126
127<Steps>
128 <Step title="Enable the Vertex AI API">
129 In the [Google Cloud console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com), enable the **Vertex AI API** for your project.
130 </Step>
127**1. Enable the Vertex AI API**
131128
132 <Step title="Enable Claude models in Model Garden">
133 In the [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), locate the Claude models you intend to deploy and click **Enable** on each. Model availability varies by region; enable them in the region you will set as `inferenceVertexRegion`.
134 </Step>
129In the [Google Cloud console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com), enable the **Vertex AI API** for your project.
135130
136 <Step title="Grant users access to Google Cloud's Agent Platform">
137 Each authenticated principal needs permission to call the model. On the project's **IAM** page, grant the **Vertex AI User** role (`roles/aiplatform.user`) to:
131**2. Enable Claude models in Model Garden**
138132
139 * the service account, if using a service-account key file
140 * the Google group containing your users, if using in-app Google sign-in
133In the [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), locate the Claude models you intend to deploy and click **Enable** on each. Model availability varies by region; enable them in the region you will set as `inferenceVertexRegion`.
141134
142 If your organization uses a narrower custom role, it must include at minimum `aiplatform.endpoints.predict`.
143 </Step>
135**3. Grant users access to Google Cloud's Agent Platform**
144136
145 <Step title="Create an OAuth client (in-app Google sign-in only)">
146 If you chose in-app Google sign-in, create a Desktop-app OAuth client in your project. See [In-app Google sign-in](#in-app-google-sign-in) below for the full procedure, including consent-screen setup.
147 </Step>
137Each authenticated principal needs permission to call the model. On the project's **IAM** page, grant the **Vertex AI User** role (`roles/aiplatform.user`) to:
148138
149 <Step title="Federate to your IdP (optional)">
150 If your users authenticate with Microsoft Entra ID, Okta, or another identity provider and do not already have Google accounts, you have two options:
139* the service account, if using a service-account key file
140* the Google group containing your users, if using in-app Google sign-in
151141
152 * **Workforce Identity Federation** (recommended). Create a workforce pool with an OIDC provider, and use the [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approach. Users sign in directly with their corporate identity; no Google identity is provisioned.
153 * **Cloud Identity with SAML SSO.** Provision a free Cloud Identity tenant and configure SAML single sign-on to your IdP. Users then sign in through the in-app Google sign-in approach with a Google identity that is backed by your IdP. See [Set up SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) in the Cloud Identity documentation.
154 </Step>
155</Steps>
142If your organization uses a narrower custom role, it must include at minimum `aiplatform.endpoints.predict`.
156143
144**4. Create an OAuth client (in-app Google sign-in only)**
145
146If you chose in-app Google sign-in, create a Desktop-app OAuth client in your project. See [In-app Google sign-in](#in-app-google-sign-in) below for the full procedure, including consent-screen setup.
147
148**5. Federate to your IdP (optional)**
149
150If your users authenticate with Microsoft Entra ID, Okta, or another identity provider and do not already have Google accounts, you have two options:
151
152* **Workforce Identity Federation** (recommended). Create a workforce pool with an OIDC provider, and use the [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approach. Users sign in directly with their corporate identity; no Google identity is provisioned.
153* **Cloud Identity with SAML SSO.** Provision a free Cloud Identity tenant and configure SAML single sign-on to your IdP. Users then sign in through the in-app Google sign-in approach with a Google identity that is backed by your IdP. See [Set up SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) in the Cloud Identity documentation.
154
157155## Prepare devices
158156
159157What each end-user device needs depends on the authentication approach you chose.
from line 176
178176
179177#### Create the OAuth client
180178
181<Steps>
182 <Step title="Configure the OAuth consent screen">
183 In the Google Cloud Console, in the project where you enabled Claude models, open **APIs & Services → OAuth consent screen**.
179**1. Configure the OAuth consent screen**
184180
185 If your project belongs to a Google Workspace organization, select the **Internal** user type. Internal apps are limited to users in your Workspace and do not require Google verification, regardless of which scopes they request.
181In the Google Cloud Console, in the project where you enabled Claude models, open **APIs & Services → OAuth consent screen**.
186182
187 If the project is not in a Workspace organization, you must use the **External** user type. Because this flow requests the `https://www.googleapis.com/auth/cloud-platform` scope, Google classifies the app as using a sensitive scope, and publishing it beyond test users requires Google's OAuth verification process. For that reason, Internal is strongly recommended for enterprise deployments.
188 </Step>
183If your project belongs to a Google Workspace organization, select the **Internal** user type. Internal apps are limited to users in your Workspace and do not require Google verification, regardless of which scopes they request.
189184
190 <Step title="Create a Desktop OAuth client">
191 In **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type.
185If the project is not in a Workspace organization, you must use the **External** user type. Because this flow requests the `https://www.googleapis.com/auth/cloud-platform` scope, Google classifies the app as using a sensitive scope, and publishing it beyond test users requires Google's OAuth verification process. For that reason, Internal is strongly recommended for enterprise deployments.
192186
193 Record the generated **Client ID** (ending in `.apps.googleusercontent.com`) and **Client secret**. For installed applications, Google does not treat the client secret as confidential; the flow is protected by PKCE and by the loopback redirect, so it is safe to distribute the secret in a managed configuration profile.
187**2. Create a Desktop OAuth client**
194188
195 You do not need to add redirect URIs. Desktop-app clients permit loopback (`http://127.0.0.1:<port>`) redirects automatically.
196 </Step>
189In **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type.
197190
198 <Step title="Allow network egress">
199 The sign-in flow and subsequent token refreshes reach `accounts.google.com` and `oauth2.googleapis.com` from the user's device. These hosts are already included in the standard egress requirements for Google Cloud's Agent Platform, so if you allowed egress based on the **Egress** section of the configuration window, no additional firewall changes are needed.
200 </Step>
201</Steps>
191Record the generated **Client ID** (ending in `.apps.googleusercontent.com`) and **Client secret**. For installed applications, Google does not treat the client secret as confidential; the flow is protected by PKCE and by the loopback redirect, so it is safe to distribute the secret in a managed configuration profile.
202192
193You do not need to add redirect URIs. Desktop-app clients permit loopback (`http://127.0.0.1:<port>`) redirects automatically.
194
195**3. Allow network egress**
196
197The sign-in flow and subsequent token refreshes reach `accounts.google.com` and `oauth2.googleapis.com` from the user's device. These hosts are already included in the standard egress requirements for Google Cloud's Agent Platform, so if you allowed egress based on the **Egress** section of the configuration window, no additional firewall changes are needed.
198
203199#### Federate to a third-party identity provider
204200
205201The in-app sign-in always opens Google's authorization endpoint, because Google Cloud's Agent Platform only accepts Google-issued access tokens. To have users authenticate with your organization's own identity provider (Microsoft Entra ID, Okta, Ping, or an in-house SAML IdP) instead of a Google password, configure Cloud Identity as a broker:
from line 255
259255
260256| Setting | Type | Availability | Default | Description |
261257| - | - | - | - | - |
262| <span id="inferencevertexprojectid" />GCP project ID<br />`inferenceVertexProjectId` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Google Cloud project ID for Vertex AI inference. |
263| <span id="inferencevertexregion" />GCP region<br />`inferenceVertexRegion` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | GCP region where your Vertex AI Claude models are deployed. |
264| <span id="inferencevertexbaseurl" />Vertex AI base URL<br />`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | PSC endpoint, if using one. |
265| <span id="inferencevertexoauthclientid" />Vertex OAuth client ID<br />`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. |
266| <span id="inferencevertexoauthclientsecret" />Vertex OAuth client secret<br />`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config. |
267| <span id="inferencevertexoauthscopes" />Vertex OAuth scopes<br />`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. |
268| <span id="inferencevertexoauthloginhint" />Vertex OAuth login hint<br />`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap<br />Added in 1.12603.0 | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. |
269| <span id="inferencevertexworkforceaudience" />Workforce Identity audience<br />`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap<br />Added in 1.10628.0 | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. |
270| <span id="inferencevertexworkforceuserproject" />Workforce Identity billing project<br />`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap<br />Added in 1.10628.0 | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. |
271| <span id="inferencevertexworkforceauthflow" />Workforce Identity sign-in flow<br />`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap<br />Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
272| <span id="inferencevertexworkforceoidc" />Workforce Identity IdP (OIDC)<br />`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap<br />Added in 1.10628.0 | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. |
273| <span id="inferencevertexcredentialsfile" />GCP credentials file path<br />`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. |
258| GCP project ID `inferenceVertexProjectId` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Google Cloud project ID for Vertex AI inference. |
259| GCP region `inferenceVertexRegion` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | GCP region where your Vertex AI Claude models are deployed. |
260| Vertex AI base URL `inferenceVertexBaseUrl` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | PSC endpoint, if using one. |
261| Vertex OAuth client ID `inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. |
262| Vertex OAuth client secret `inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config. |
263| Vertex OAuth scopes `inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. |
264| Vertex OAuth login hint `inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap Added in 1.12603.0 | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. |
265| Workforce Identity audience `inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap Added in 1.10628.0 | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. |
266| Workforce Identity billing project `inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap Added in 1.10628.0 | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. |
267| Workforce Identity sign-in flow `inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
268| Workforce Identity IdP (OIDC) `inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap Added in 1.10628.0 | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. |
269| GCP credentials file path `inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. |
274270
275<AccordionGroup>
276 <Accordion title="inferenceVertexWorkforceAuthFlow details">
277 * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here.
278 * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
271> **inferenceVertexWorkforceAuthFlow details**
272>
273> * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here.
274> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
275>
276> The GCP STS token-exchange step is unchanged in either flow; only how the Entra id\_token is acquired differs.
279277
280 The GCP STS token-exchange step is unchanged in either flow; only how the Entra id\_token is acquired differs.
281 </Accordion>
282
283 <Accordion title="inferenceVertexWorkforceOidc details">
284 | Field | Type | Default | Description |
285 | - | - | - | - |
286 | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
287 | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
288 | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
289 | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
290 | `scopes` | `string` | — | Space-separated scopes. Defaults to openid profile email offline\_access. |
291 | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
292 | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
293 | `omitOfflineAccess` | `boolean` | — | Only enable if your IdP rejects the offline\_access scope on this client. Without it the app prompts for sign-in each time the token expires. |
294 | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
295 </Accordion>
296</AccordionGroup>
278> **inferenceVertexWorkforceOidc details**
279>
280> | Field | Type | Default | Description |
281> | - | - | - | - |
282> | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
283> | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
284> | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
285> | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
286> | `scopes` | `string` | — | Space-separated scopes. Defaults to openid profile email offline\_access. |
287> | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
288> | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
289> | `omitOfflineAccess` | `boolean` | — | Only enable if your IdP rejects the offline\_access scope on this client. Without it the app prompts for sign-in each time the token expires. |
290> | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
297291
298292If none of `inferenceVertexCredentialsFile`, the OAuth client keys, the Workforce Identity keys, or `inferenceCredentialHelper` is set, the Google client library falls back to the standard Application Default Credentials search path on the device (`~/.config/gcloud/application_default_credentials.json`, then the environment's metadata server).
299293
third-party/claude-desktop/web-tools Changed · +13 / -15 lines
from line 27
2727
2828Provider-side search runs on the provider's infrastructure, so queries and results travel over the same path as model inference and are subject to your provider's data-handling terms. It needs no additional firewall rules beyond the inference endpoint itself.
2929
30<Note>
31 `coworkEgressAllowedHosts` governs client-side egress (Web Fetch and in-sandbox shell network activity). The SDK Web Search tool in the table above executes server-side at your inference provider, so the allowlist does not apply to it. The built-in `websearch` server under [Web search options](#web-search-options) runs in the desktop app itself, outside the sandbox, and `coworkEgressAllowedHosts` does not apply to it either. Its search provider's host (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) does need to be reachable through your perimeter firewall and proxy, and the **Egress** section of the in-app configuration window lists that host. To let the agent fetch pages it finds via search, add the relevant hosts to `coworkEgressAllowedHosts` or set it to `["*"]`. Adding `"WebSearch"` to `disabledBuiltinTools` turns web search off entirely, both provider-side search and the built-in `websearch` server's tool.
32</Note>
30> [!NOTE]
31>
32> `coworkEgressAllowedHosts` governs client-side egress (Web Fetch and in-sandbox shell network activity). The SDK Web Search tool in the table above executes server-side at your inference provider, so the allowlist does not apply to it. The built-in `websearch` server under [Web search options](#web-search-options) runs in the desktop app itself, outside the sandbox, and `coworkEgressAllowedHosts` does not apply to it either. Its search provider's host (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) does need to be reachable through your perimeter firewall and proxy, and the **Egress** section of the in-app configuration window lists that host. To let the agent fetch pages it finds via search, add the relevant hosts to `coworkEgressAllowedHosts` or set it to `["*"]`. Adding `"WebSearch"` to `disabledBuiltinTools` turns web search off entirely, both provider-side search and the built-in `websearch` server's tool.
3333
3434### Web search options
3535
from line 52
5252
5353You can add it from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): under **Connectors**, add a **Web search** server, choose the search provider, and supply the vendor key as a header or through a headers helper script.
5454
55<Frame caption="The Web search server in the Connectors section of the in-app configuration window, with the search provider menu open.">
56 <img src="https://mintcdn.com/claude-ai/iVbkJluVpijKTo5a/images/third-party/config-window-web-search.png?fit=max&auto=format&n=iVbkJluVpijKTo5a&q=85&s=19cf4844972d9fd47addec8690db09c8" alt="Web search server card in the in-app configuration window with fields for name, tool policy, headers, and headers helper script, and a search provider menu offering brave, tavily, exa, and custom." width="1428" height="1330" data-path="images/third-party/config-window-web-search.png" />
57</Frame>
55
5856
5957In the exported configuration, set `provider` to a hosted search vendor (`brave`, `tavily`, or `exa`) for the lowest setup, or to `custom` with `customUrl` to point at a search server you run.
6058
from line 72
7472}
7573```
7674
77<Note>
78 A hosted-vendor key configured in `headers` or returned by `headersHelper` is the same key on every device, and a local user can extract it. The exposure is limited to billing abuse on that key (it grants no data access). For regulated environments, set spend caps and rotate the key on a schedule, or have `headersHelper` fetch a per-user key: Tavily and Exa support per-user or per-team keys; see their key-management docs.
79</Note>
75> [!NOTE]
76>
77> A hosted-vendor key configured in `headers` or returned by `headersHelper` is the same key on every device, and a local user can extract it. The exposure is limited to billing abuse on that key (it grants no data access). For regulated environments, set spend caps and rotate the key on a schedule, or have `headersHelper` fetch a per-user key: Tavily and Exa support per-user or per-team keys; see their key-management docs.
8078
8179Your own server:
8280
from line 124
126124
127125For audit, each search the model runs is recorded in the Cowork or Code session telemetry sent to your [OTLP collector](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector) as a `tool_result` event, whichever option you choose (a `WebSearch` event for provider-side or gateway-side search, an MCP tool event for the built-in or a remote search server). Add `toolDetails` to [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) to include the tool input, which carries the query text (long values are truncated). The built-in `websearch` server also emits a `builtin_websearch_call` event on the desktop application's own stream with the search provider, query length, result count, duration, and status, never the query text. The app exports that event only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, not at the default `error` level.
128126
129<Note>
130 If you previously routed inference through a LiteLLM proxy to add search, the built-in `websearch` server with `provider: "custom"` is an alternative that removes the proxy from the search path; gateway-side interception remains a valid choice if you prefer the search key to stay server-side.
131</Note>
127> [!NOTE]
128>
129> If you previously routed inference through a LiteLLM proxy to add search, the built-in `websearch` server with `provider: "custom"` is an alternative that removes the proxy from the search path; gateway-side interception remains a valid choice if you prefer the search key to stay server-side.
132130
133131## Web Fetch
134132
from line 142
144142
145143Wildcards match one or more leading subdomain labels (`*.example.com` matches `a.example.com` and `a.b.example.com`, but not `example.com`). A listed host that many organizations share, such as a cloud provider's API endpoint, is reachable from the agent's shell with any account's credentials. A command can then send data to an account outside your organization.
146144
147<Note>
148 Your perimeter firewall is a separate, outer layer from `coworkEgressAllowedHosts`, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the distinction.
149</Note>
145> [!NOTE]
146>
147> Your perimeter firewall is a separate, outer layer from `coworkEgressAllowedHosts`, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the distinction.
150148
151149The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool. A command-line tool that a [plugin](/docs/third-party/claude-desktop/extensions#controlling-user-extensions) adds to the Cowork sandbox can also reach the hosts its plugin declares, whatever the list holds. Claude Desktop's own connections for inference, sign-in, model discovery, telemetry export, and MCP servers aren't checked against it and need no entry.
152150
claude-science/connectors-and-skills Changed · +1 / -1 lines
from line 10
1010
1111| Connector | Sources |
1212| - | - |
13| Genomes | Ensembl (incl. VEP), UCSC |
13| Genomes | Ensembl (incl. VEP) |
1414| Genes & Ontologies | MyGene, UniProt, GO, Reactome, OLS |
1515| Variants | gnomAD, ClinVar, dbSNP |
1616| Human Genetics | GWAS Catalog, FinnGen, BioBank Japan |
third-party/claude-desktop/in-app-configuration Changed · +1 / -3 lines
from line 12
1212
1313To turn Developer mode off again, go to **Developer → Open Developer Config File**, change `"allowDevTools": true` to `false` in the file that opens (or delete the file), save it, then quit and reopen Claude Desktop. The **Developer** menu is gone on the next launch.
1414
15<Frame caption="The in-app configuration window, showing the Connection section for a gateway provider.">
16 <img src="https://mintcdn.com/claude-ai/kVj7_7KF4fI3bEAn/images/third-party/in-app-configuration-window.png?fit=max&auto=format&n=kVj7_7KF4fI3bEAn&q=85&s=c3f15a85dea85082bc6dbc9459e6a974" alt="Claude Desktop in-app configuration window with the sidebar of setting groups on the left and the Connection form on the right." width="1812" height="1462" data-path="images/third-party/in-app-configuration-window.png" />
17</Frame>
15
1816
1917The sidebar groups settings the same way the [configuration reference](/docs/third-party/claude-desktop/configuration) does. Fill in **Connection** first, then work down through the sections your deployment needs.
2018