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
201-225 of 246, page 9 of 10This capture is too large to show at once. Changes 201-225 of 246 are below, significant first; the rest are on the following screens.
plugins/create-with-claude Changed · +42 / -50 lines
from line 6
66
77A plugin you create this way is for you. It lives on your account, and on a Team or Enterprise plan you can [share it](/docs/plugins/share) with specific people or your whole organization from its page in Customize. It isn't a directory listing; if you later want that, see [Submit a plugin you created with Claude](#submit-a-plugin-you-created-with-claude) at the end of this page.
88
9<Note>
10 * If you'd rather write the files yourself, see [Plugin structure and testing](/docs/plugins/build)
11 * If you want to make a plugin available to everyone in your organization, see [Publish a plugin to your organization](/docs/plugins/share#publish-a-plugin-to-your-organization)
12</Note>
9> [!NOTE]
10>
11> * If you'd rather write the files yourself, see [Plugin structure and testing](/docs/plugins/build)
12> * If you want to make a plugin available to everyone in your organization, see [Publish a plugin to your organization](/docs/plugins/share#publish-a-plugin-to-your-organization)
1313
1414To begin, [start a new plugin from the Add menu](#start-from-the-add-menu), [describe it to Claude and save it](#describe-and-save-the-plugin), then [review the plugin Claude made](#review-what-claude-made).
1515
from line 21
2121
2222To start a new plugin:
2323
24<Steps>
25 <Step title="Open the Add menu">
26 Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and select **Add**.
27 </Step>
24**1. Open the Add menu**
2825
29 <Step title="Choose how to create it">
30 Choose one of these:
26Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and select **Add**.
3127
32 * **Create with Claude**: start a new conversation, or a new Cowork task in the desktop app, with a request to create a plugin already filled in for you to send. Choose this when you can describe the task you want the plugin to handle but don't want to write skill files
33 * **Create a plugin**: fill in a form with the plugin's name and what it helps with, then write its skills, commands, and connectors in an editor. Choose this when you already know what each piece should say
34 </Step>
35</Steps>
28**2. Choose how to create it**
3629
30Choose one of these:
31
32* **Create with Claude**: start a new conversation, or a new Cowork task in the desktop app, with a request to create a plugin already filled in for you to send. Choose this when you can describe the task you want the plugin to handle but don't want to write skill files
33* **Create a plugin**: fill in a form with the plugin's name and what it helps with, then write its skills, commands, and connectors in an editor. Choose this when you already know what each piece should say
34
3735If neither item appears in the **Add** menu, plugin creation isn't available on your account. Your organization can turn it off, and so can your IT department's configuration of the desktop app. [Manage plugins for your organization](/docs/plugins/admin#control-what-members-add-themselves) covers the organization setting.
3836
3937### Describe and save the plugin
from line 38
4038
4139After you choose **Create with Claude**, a conversation opens where you tell Claude what the plugin is for, and Claude assembles it as a `.plugin` file that you save to your account:
4240
43<Steps>
44 <Step title="Describe what the plugin is for">
45 Tell Claude the job the plugin should help with, in the same words you'd use to explain it to a colleague: the task, when it comes up, and what a good result looks like.
46 </Step>
41**1. Describe what the plugin is for**
4742
48 <Step title="Answer Claude's questions">
49 Answer Claude's follow-up questions, such as which of your connectors the plugin should use. You can change any of it later.
50 </Step>
43Tell Claude the job the plugin should help with, in the same words you'd use to explain it to a colleague: the task, when it comes up, and what a good result looks like.
5144
52 <Step title="Save the plugin Claude assembles">
53 Claude writes the skills and commands, includes the connectors you chose, and shows the result as a file card in the conversation. Select **Save plugin** on that card to add it to your account. It's then listed under **Customize > Plugins**, on the **Yours** view.
54 </Step>
55</Steps>
45**2. Answer Claude's questions**
5646
47Answer Claude's follow-up questions, such as which of your connectors the plugin should use. You can change any of it later.
48
49**3. Save the plugin Claude assembles**
50
51Claude writes the skills and commands, includes the connectors you chose, and shows the result as a file card in the conversation. Select **Save plugin** on that card to add it to your account. It's then listed under **Customize > Plugins**, on the **Yours** view.
52
5753### Review what Claude made
5854
5955Check the plugin before you rely on it:
6056
61<Steps>
62 <Step title="Open the plugin">
63 Open **Customize > Plugins** and select the new plugin.
64 </Step>
57**1. Open the plugin**
6558
66 <Step title="Read what it contains">
67 Read the skills, commands, and connectors it contains.
68 </Step>
59Open **Customize > Plugins** and select the new plugin.
6960
70 <Step title="Sign in to its connectors">
71 Sign in to any bundled connector from the plugin's page.
72 </Step>
61**2. Read what it contains**
7362
74 <Step title="Try it on a real request">
75 Start a chat, or a Cowork task in the desktop app, with the kind of request the plugin is for, and check that Claude follows the plugin's skills.
76 </Step>
77</Steps>
63Read the skills, commands, and connectors it contains.
7864
65**3. Sign in to its connectors**
66
67Sign in to any bundled connector from the plugin's page.
68
69**4. Try it on a real request**
70
71Start a chat, or a Cowork task in the desktop app, with the kind of request the plugin is for, and check that Claude follows the plugin's skills.
72
7973## Use, disable, or remove your plugin
8074
8175The plugin is on your account for the organization you created it in, so it's available in your chats, in Cowork, and in Claude Code as a synced plugin.
from line 85
9185
9286Anthropic's directory reads plugins from a GitHub repository, so a plugin that lives only on your account can't be submitted as it is. If you decide you want it listed, get its files from the same conversation and go through the normal submission route:
9387
94<Steps>
95 <Step title="Ask Claude for the plugin as a folder">
96 In the conversation where Claude made the plugin, ask for it "as a plugin folder I can push to GitHub for the directory", download the zip Claude produces, and check that it has `.claude-plugin/plugin.json`, the `skills/` folder, a `README.md`, and a `LICENSE`.
97 </Step>
88**1. Ask Claude for the plugin as a folder**
9889
99 <Step title="Check the manifest and README">
100 Unzip the folder and compare `plugin.json` with [Write the manifest](/docs/plugins/build#write-the-manifest). Claude may include fields the manifest doesn't use and leaves placeholders such as your name for you to fill in. If you have Claude Code installed, run `claude plugin validate` on the folder, as [Check the plugin on your machine](/docs/plugins/pre-submission-checklist#check-the-plugin-on-your-machine-optional) describes.
101 </Step>
90In the conversation where Claude made the plugin, ask for it "as a plugin folder I can push to GitHub for the directory", download the zip Claude produces, and check that it has `.claude-plugin/plugin.json`, the `skills/` folder, a `README.md`, and a `LICENSE`.
10291
103 <Step title="Push and submit">
104 Push the folder to a public GitHub repository, then follow [Submit a plugin](/docs/plugins/submit).
105 </Step>
106</Steps>
92**2. Check the manifest and README**
93
94Unzip the folder and compare `plugin.json` with [Write the manifest](/docs/plugins/build#write-the-manifest). Claude may include fields the manifest doesn't use and leaves placeholders such as your name for you to fill in. If you have Claude Code installed, run `claude plugin validate` on the folder, as [Check the plugin on your machine](/docs/plugins/pre-submission-checklist#check-the-plugin-on-your-machine-optional) describes.
95
96**3. Push and submit**
97
98Push the folder to a public GitHub repository, then follow [Submit a plugin](/docs/plugins/submit).
10799
108100## Next steps
109101
plugins/org-rollout Changed · +29 / -33 lines
from line 9
99
1010This page is for the person rolling out a plugin their organization built, on a Team or Enterprise plan.
1111
12<Note>
13 * If you want to list a plugin publicly, see [Publish to the directory](/docs/directory/publish)
14 * If you haven't built the plugin yet, see [Build your first plugin](/docs/plugins/quickstart) and [Plugin structure and testing](/docs/plugins/build)
15</Note>
12> [!NOTE]
13>
14> * If you want to list a plugin publicly, see [Publish to the directory](/docs/directory/publish)
15> * If you haven't built the plugin yet, see [Build your first plugin](/docs/plugins/quickstart) and [Plugin structure and testing](/docs/plugins/build)
1616
1717## Choose a rollout route
1818
from line 33
3333
3434Use both routes when the plugin is for people in chat and Cowork and also for developers whose Claude Code sessions don't sync from a claude.ai account.
3535
36<Steps>
37 <Step title="Lay out the repository as a marketplace">
38 Put the plugin in a Git repository with a `.claude-plugin/marketplace.json` that lists it. You use the same repository for both routes. [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs covers the format.
39 </Step>
36**1. Lay out the repository as a marketplace**
4037
41 <Step title="Check the repository against the organization sync rules">
42 Organization sync is stricter than Claude Code about the repository's visibility and about which plugin source types it accepts, and it rejects a plugin with a top-level `bin/` directory. Check [the plugin sources that organization sync accepts](/docs/plugins/org-sync#plugin-sources-that-organization-sync-accepts) before you continue.
43 </Step>
38Put the plugin in a Git repository with a `.claude-plugin/marketplace.json` that lists it. You use the same repository for both routes. [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs covers the format.
4439
45 <Step title="Sync the repository from organization settings">
46 In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), add the repository as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes, then [set each plugin's availability](/docs/plugins/admin#set-availability).
47 </Step>
40**2. Check the repository against the organization sync rules**
4841
49 <Step title="Register the same marketplace in managed settings">
50 Set `extraKnownMarketplaces` and `enabledPlugins` as [Pre-install and require plugins](https://code.claude.com/docs/en/plugins/org#pre-install-and-require-plugins) describes. To limit developers to your marketplace, see [Restrict what users can install](https://code.claude.com/docs/en/plugins/org#restrict-what-users-can-install).
51 </Step>
42Organization sync is stricter than Claude Code about the repository's visibility and about which plugin source types it accepts, and it rejects a plugin with a top-level `bin/` directory. Check [the plugin sources that organization sync accepts](/docs/plugins/org-sync#plugin-sources-that-organization-sync-accepts) before you continue.
5243
53 <Step title="Confirm on each surface">
54 * **In claude.ai**: as a member, open [**Customize > Plugins**](https://claude.ai/customize/plugins) and check that the plugin appears there
55 * **On a developer's machine**: start Claude Code and run `/plugin`, which lists the marketplace and the plugin
56 </Step>
57</Steps>
44**3. Sync the repository from organization settings**
5845
46In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), add the repository as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes, then [set each plugin's availability](/docs/plugins/admin#set-availability).
47
48**4. Register the same marketplace in managed settings**
49
50Set `extraKnownMarketplaces` and `enabledPlugins` as [Pre-install and require plugins](https://code.claude.com/docs/en/plugins/org#pre-install-and-require-plugins) describes. To limit developers to your marketplace, see [Restrict what users can install](https://code.claude.com/docs/en/plugins/org#restrict-what-users-can-install).
51
52**5. Confirm on each surface**
53
54* **In claude.ai**: as a member, open [**Customize > Plugins**](https://claude.ai/customize/plugins) and check that the plugin appears there
55* **On a developer's machine**: start Claude Code and run `/plugin`, which lists the marketplace and the plugin
56
5957### If a developer has the plugin from both routes
6058
6159A developer can end up with the plugin from both routes. Claude Code loads one plugin per name. It loads the copy that managed settings install and reports the synced copy as not loaded, as [Name conflicts](https://code.claude.com/docs/en/plugins/loading#name-conflicts) describes.
from line 72
7472
7573**Re-sync** syncs the marketplace now, so members get the version on the default branch without waiting for a push. To re-sync:
7674
77<Steps>
78 <Step title="Open the Marketplaces tab">
79 Go to [**Organization settings > Plugins & skills > Marketplaces**](https://claude.ai/admin-settings/skills?tab=marketplaces).
80 </Step>
75**1. Open the Marketplaces tab**
8176
82 <Step title="Re-sync the marketplace">
83 Open the menu in the marketplace's row and select **Re-sync**.
84 </Step>
77Go to [**Organization settings > Plugins & skills > Marketplaces**](https://claude.ai/admin-settings/skills?tab=marketplaces).
8578
86 <Step title="Retry if you synced recently">
87 If you see **You synced recently**, wait the number of seconds the message gives, then select **Re-sync** again.
88 </Step>
89</Steps>
79**2. Re-sync the marketplace**
80
81Open the menu in the marketplace's row and select **Re-sync**.
82
83**3. Retry if you synced recently**
84
85If you see **You synced recently**, wait the number of seconds the message gives, then select **Re-sync** again.
9086
9187### Update through managed settings
9288
plugins/org-sync Changed · +34 / -38 lines
from line 6
66
77This page is for the Owner who adds the repository and for the engineer who maintains it. It covers the requirements the repository and its plugin entries must meet for the sync to accept them.
88
9<Note>
10 * If you're choosing who gets each plugin once the repository syncs, see [Manage plugins for your organization](/docs/plugins/admin#set-availability)
11 * If you're writing the `marketplace.json` file, see [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs
12</Note>
9> [!NOTE]
10>
11> * If you're choosing who gets each plugin once the repository syncs, see [Manage plugins for your organization](/docs/plugins/admin#set-availability)
12> * If you're writing the `marketplace.json` file, see [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs
1313
1414To get started, check [how organization sync gets access to your repository](#give-organization-sync-access-to-your-repository) for your Git host, then check your `marketplace.json` against [the plugin sources that organization sync accepts](#plugin-sources-that-organization-sync-accepts).
1515
from line 25
2525
2626When you sync a marketplace from github.com, organization sync reads the repository through the Claude GitHub App, and you choose the availability its plugins start with as you add it. To sync a marketplace from a private or internal repository on github.com:
2727
28<Steps>
29 <Step title="Open Plugins & skills">
30 Go to [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory).
31 </Step>
28**1. Open Plugins & skills**
3229
33 <Step title="Select Sync from GitHub">
34 Select **Add**, then **Sync from GitHub**.
35 </Step>
30Go to [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory).
3631
37 <Step title="Connect to GitHub">
38 If the dialog shows **Connect to GitHub**, select it and authorize. GitHub returns you to the dialog.
39 </Step>
32**2. Select Sync from GitHub**
4033
41 <Step title="Choose the repository">
42 Search for the repository or enter it as `owner/repo`. The list shows private and internal repositories.
43 </Step>
34Select **Add**, then **Sync from GitHub**.
4435
45 <Step title="Install the Claude GitHub App if needed">
46 If the repository isn't in the list, select **Install the Claude GitHub App** under **Repository missing?**, grant the app access to the repository on GitHub, and return to the dialog.
47 </Step>
36**3. Connect to GitHub**
4837
49 <Step title="Leave automatic sync on">
50 Leave **Sync automatically** on to sync each time someone pushes to the default branch. Claude creates the webhook on the repository for you.
51 </Step>
38If the dialog shows **Connect to GitHub**, select it and authorize. GitHub returns you to the dialog.
5239
53 <Step title="Choose the default access">
54 Choose the **Default access** for the plugins in this marketplace.
55 </Step>
40**4. Choose the repository**
5641
57 <Step title="Create the marketplace">
58 Select **Create**.
59 </Step>
60</Steps>
42Search for the repository or enter it as `owner/repo`. The list shows private and internal repositories.
6143
44**5. Install the Claude GitHub App if needed**
45
46If the repository isn't in the list, select **Install the Claude GitHub App** under **Repository missing?**, grant the app access to the repository on GitHub, and return to the dialog.
47
48**6. Leave automatic sync on**
49
50Leave **Sync automatically** on to sync each time someone pushes to the default branch. Claude creates the webhook on the repository for you.
51
52**7. Choose the default access**
53
54Choose the **Default access** for the plugins in this marketplace.
55
56**8. Create the marketplace**
57
58Select **Create**.
59
6260The marketplace's page opens, and **Last synced** shows **Syncing...** until the first sync finishes. If the dialog says **The Claude GitHub App is not installed on** the repository, grant the Claude GitHub App access to the repository on GitHub and try again.
6361
6462To turn on automatic sync later, open the marketplace from the [**Marketplaces**](https://claude.ai/admin-settings/skills?tab=marketplaces) tab and turn on **Sync automatically**. If it shows **No webhook yet**, select **Configure webhook**, then **Enable webhook**.
from line 65
6765
6866Syncing a marketplace from GitLab needs a GitLab configuration for the host first, which holds the access token that organization sync reads the repository with. To sync a marketplace from gitlab.com or a self-managed GitLab instance:
6967
70<Steps>
71 <Step title="Add a GitLab configuration">
72 As an [Owner](https://code.claude.com/docs/en/server-managed-settings#access-control), add a GitLab configuration for that host at [**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control#gitlab). GitLab configurations are in public beta and apply only to plugin marketplace sync.
73 </Step>
68**1. Add a GitLab configuration**
7469
75 <Step title="Sync from GitLab">
76 In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), select **Add**, then **Sync from GitLab**, as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes. When you add it, enter the project's HTTPS URL, such as `https://gitlab.example.com/platform/claude-plugins`.
77 </Step>
78</Steps>
70As an [Owner](https://code.claude.com/docs/en/server-managed-settings#access-control), add a GitLab configuration for that host at [**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control#gitlab). GitLab configurations are in public beta and apply only to plugin marketplace sync.
71
72**2. Sync from GitLab**
73
74In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), select **Add**, then **Sync from GitLab**, as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes. When you add it, enter the project's HTTPS URL, such as `https://gitlab.example.com/platform/claude-plugins`.
7975
8076Organization sync reads the project's default branch. If you turn on **Sync automatically**, only pushes to the default branch start a sync.
8177
plugins/overview Changed · +5 / -5 lines
from line 6
66
77This page is for people using plugins in claude.ai, the Claude desktop app, and Cowork.
88
9<Note>
10 * If you want to build a plugin or submit one to the directory, see [Plugin structure and testing](/docs/plugins/build) and [Publish to the directory](/docs/directory/publish)
11 * If you install and manage plugins from the Claude Code command line, see [Install plugins](https://code.claude.com/docs/en/plugins/install) in the Claude Code docs
12 * If you have a `.mcpb` file to install into the Claude desktop app, see [Install a local connector in the desktop app](/docs/connectors/custom/add-unlisted#install-a-local-connector-in-the-desktop-app)
13</Note>
9> [!NOTE]
10>
11> * If you want to build a plugin or submit one to the directory, see [Plugin structure and testing](/docs/plugins/build) and [Publish to the directory](/docs/directory/publish)
12> * If you install and manage plugins from the Claude Code command line, see [Install plugins](https://code.claude.com/docs/en/plugins/install) in the Claude Code docs
13> * If you have a `.mcpb` file to install into the Claude desktop app, see [Install a local connector in the desktop app](/docs/connectors/custom/add-unlisted#install-a-local-connector-in-the-desktop-app)
1414
1515To get started, [find and add a plugin](#find-and-add-a-plugin), then see [how to use it in each app](#use-a-plugin) and [where it becomes available on your account](#find-the-plugin-in-each-app).
1616
plugins/platform-support Changed · +6 / -6 lines
from line 6
66
77This page is for anyone checking a component or behavior before relying on it, whether you're installing a plugin, building one, or submitting one to the directory.
88
9<Note>
10 * If you want to install and manage plugins, see [Plugins](/docs/plugins/overview)
11 * If you're building a plugin, see [Plugin structure and testing](/docs/plugins/build)
12 * If you run Claude Desktop on your own model provider, see its [Feature matrix](/docs/third-party/claude-desktop/feature-matrix) for feature availability
13 * If you want to know where MCP Apps render, see [Add interactive UI with MCP Apps](/docs/connectors/building/mcp-apps/getting-started)
14</Note>
9> [!NOTE]
10>
11> * If you want to install and manage plugins, see [Plugins](/docs/plugins/overview)
12> * If you're building a plugin, see [Plugin structure and testing](/docs/plugins/build)
13> * If you run Claude Desktop on your own model provider, see its [Feature matrix](/docs/third-party/claude-desktop/feature-matrix) for feature availability
14> * If you want to know where MCP Apps render, see [Add interactive UI with MCP Apps](/docs/connectors/building/mcp-apps/getting-started)
1515
1616## Compare component support by app
1717
plugins/pre-submission-checklist Changed · +21 / -25 lines
from line 32
3232
3333The portal's **Validate** button runs every check in this page's tables against your repository and gives you a report before you submit anything.
3434
35<Steps>
36 <Step title="Start a submission">
37 Open the [developer portal](https://claude.ai/directory/manage) and select **Submit new**.
38 </Step>
35**1. Start a submission**
3936
40 <Step title="Choose Plugin bundle">
41 When the portal asks **What would you like to submit?**, select **Plugin bundle**.
42 </Step>
37Open the [developer portal](https://claude.ai/directory/manage) and select **Submit new**.
4338
44 <Step title="Enter the repository">
45 On the **Source** step, enter the repository. [Submit your plugin](/docs/plugins/submit#submit-a-plugin) describes each field.
46 </Step>
39**2. Choose Plugin bundle**
4740
48 <Step title="Validate">
49 Select **Validate**. The report lists each finding with its result and, for many findings, a fix.
50 </Step>
41When the portal asks **What would you like to submit?**, select **Plugin bundle**.
5142
52 <Step title="Fix blocking findings and validate again">
53 The report covers only the commit that validation read, so it doesn't change when you push a fix. Push the fix, then select **Re-validate** on the **Source** step of the same form. When the new report has no findings with the **Blocks** result, continue through the form to submit the plugin.
54 </Step>
55</Steps>
43**3. Enter the repository**
5644
45On the **Source** step, enter the repository. [Submit your plugin](/docs/plugins/submit#submit-a-plugin) describes each field.
46
47**4. Validate**
48
49Select **Validate**. The report lists each finding with its result and, for many findings, a fix.
50
51**5. Fix blocking findings and validate again**
52
53The report covers only the commit that validation read, so it doesn't change when you push a fix. Push the fix, then select **Re-validate** on the **Source** step of the same form. When the new report has no findings with the **Blocks** result, continue through the form to submit the plugin.
54
5755### Read a validation result
5856
5957Validation produces a report in the submission form, and the scan's results appear on the plugin's page in the developer portal. Each finding has one of these results:
from line 179
181179
182180Validation and the scan check how the plugin is built. They don't check whether the plugin helps the people who install it. Before you submit, test the plugin's output and how it loads on the surfaces your users will use:
183181
184<Steps>
185 <Step title="Compare output with and without the plugin">
186 Run the plugin's skills on real prompts and compare the output with what Claude produces without the plugin. [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) runs that comparison for the whole plugin in Claude Code, and [Measure whether the skill improves the output](/docs/skills/how-to#measure-whether-the-skill-improves-the-output) covers one skill at a time.
187 </Step>
182**1. Compare output with and without the plugin**
188183
189 <Step title="Load the plugin on each surface">
190 Load the plugin on each surface your users will use, as [Test the plugin on each surface](/docs/plugins/build#test-the-plugin-on-each-surface) describes.
191 </Step>
192</Steps>
184Run the plugin's skills on real prompts and compare the output with what Claude produces without the plugin. [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) runs that comparison for the whole plugin in Claude Code, and [Measure whether the skill improves the output](/docs/skills/how-to#measure-whether-the-skill-improves-the-output) covers one skill at a time.
185
186**2. Load the plugin on each surface**
187
188Load the plugin on each surface your users will use, as [Test the plugin on each surface](/docs/plugins/build#test-the-plugin-on-each-surface) describes.
193189
194190## Next steps
195191
plugins/quickstart Changed · +91 / -95 lines
from line 6
66
77This quickstart is for developers who have Claude Code installed and want to learn the plugin format by building one. You can follow it with a product that has a remote MCP server, or with only a skill.
88
9<Note>
10 * If you want to make a plugin from a conversation without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude)
11 * If you want to distribute a plugin only inside your own organization, see [Roll out a plugin to your whole organization](/docs/plugins/org-rollout)
12 * If you want to look up the folder layout, the manifest fields, or what each surface loads, see [Plugin structure and testing](/docs/plugins/build)
13</Note>
9> [!NOTE]
10>
11> * If you want to make a plugin from a conversation without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude)
12> * If you want to distribute a plugin only inside your own organization, see [Roll out a plugin to your whole organization](/docs/plugins/org-rollout)
13> * If you want to look up the folder layout, the manifest fields, or what each surface loads, see [Plugin structure and testing](/docs/plugins/build)
1414
1515## Before you create the plugin
1616
from line 23
2323
2424The steps in this section build a plugin named `expense-reports` for a fictional finance product whose MCP server is at `mcp.example.com`. Replace the names and values with your own.
2525
26<Steps>
27 <Step title="Write the manifest">
28 Create a folder named `expense-reports`, and create `.claude-plugin/plugin.json` inside it. Put only the manifest inside `.claude-plugin/`. Everything else goes at the plugin's top level.
26**1. Write the manifest**
2927
30 The example has the fields that every surface and the directory read:
28Create a folder named `expense-reports`, and create `.claude-plugin/plugin.json` inside it. Put only the manifest inside `.claude-plugin/`. Everything else goes at the plugin's top level.
3129
32 ```json theme={null}
33 {
34 "name": "expense-reports",
35 "displayName": "Expense Reports",
36 "version": "1.0.0",
37 "description": "File, track, and approve expense reports from a conversation, using your finance system's connector and your company's approval rules.",
38 "author": { "name": "Example Corp", "url": "https://example.com" },
39 "license": "MIT"
40 }
41 ```
30The example has the fields that every surface and the directory read:
4231
43 People install and refer to the plugin by its `name`. Use lowercase words joined by hyphens, make the name specific to your product, and never change it after release. [Manifest and plugin name](/docs/plugins/pre-submission-checklist#manifest-and-plugin-name) lists the directory's checks on the name.
44 </Step>
32```json theme={null}
33{
34 "name": "expense-reports",
35 "displayName": "Expense Reports",
36 "version": "1.0.0",
37 "description": "File, track, and approve expense reports from a conversation, using your finance system's connector and your company's approval rules.",
38 "author": { "name": "Example Corp", "url": "https://example.com" },
39 "license": "MIT"
40}
41```
4542
46 <Step title="Add a skill">
47 Create `skills/file-expense/SKILL.md`. A skill tells Claude when and how to do a task. The example calls tools from the MCP connector that you add in the next step, so leave the tool calls out of your own skill if your plugin has no connector:
43People install and refer to the plugin by its `name`. Use lowercase words joined by hyphens, make the name specific to your product, and never change it after release. [Manifest and plugin name](/docs/plugins/pre-submission-checklist#manifest-and-plugin-name) lists the directory's checks on the name.
4844
49 ```markdown theme={null}
50 ---
51 name: file-expense
52 description: File an expense report. Use when the user mentions a receipt, reimbursement, or expense, or asks to submit spending for approval.
53 ---
45**2. Add a skill**
5446
55 To file an expense:
47Create `skills/file-expense/SKILL.md`. A skill tells Claude when and how to do a task. The example calls tools from the MCP connector that you add in the next step, so leave the tool calls out of your own skill if your plugin has no connector:
5648
57 1. Ask for the receipt if the user hasn't attached one, and read the amount, date, merchant, and currency from it.
58 2. Call the expenses connector's `create_report` tool with those fields. Default the category from the merchant type; ask only if it's ambiguous.
59 3. If the amount is over the user's approval limit (check with `get_policy`), add their manager as approver before submitting.
60 4. Reply with the report number and its approval status. Don't paste the full API response.
61 ```
49```markdown theme={null}
50---
51name: file-expense
52description: File an expense report. Use when the user mentions a receipt, reimbursement, or expense, or asks to submit spending for approval.
53---
6254
63 Claude decides when to load the skill from the `description` line, so write it as the situations a user would be in. [Create custom skills](/docs/skills/how-to) covers the frontmatter fields, resource files, scripts, and testing.
64 </Step>
55To file an expense:
6556
66 <Step title="Add an MCP connector">
67 Skip this step if your plugin has only a skill. If your product has a remote MCP server, create `.mcp.json` at the plugin root and reference the server by URL:
571. Ask for the receipt if the user hasn't attached one, and read the amount, date, merchant, and currency from it.
582. Call the expenses connector's `create_report` tool with those fields. Default the category from the merchant type; ask only if it's ambiguous.
593. If the amount is over the user's approval limit (check with `get_policy`), add their manager as approver before submitting.
604. Reply with the report number and its approval status. Don't paste the full API response.
61```
6862
69 ```json theme={null}
70 {
71 "mcpServers": {
72 "expenses": {
73 "type": "http",
74 "url": "https://mcp.example.com/mcp"
75 }
76 }
63Claude decides when to load the skill from the `description` line, so write it as the situations a user would be in. [Create custom skills](/docs/skills/how-to) covers the frontmatter fields, resource files, scripts, and testing.
64
65**3. Add an MCP connector**
66
67Skip this step if your plugin has only a skill. If your product has a remote MCP server, create `.mcp.json` at the plugin root and reference the server by URL:
68
69```json theme={null}
70{
71 "mcpServers": {
72 "expenses": {
73 "type": "http",
74 "url": "https://mcp.example.com/mcp"
7775 }
78 ```
76 }
77}
78```
7979
80 There is no server at `mcp.example.com`, so this example connector fails to connect when you test the plugin. Replace the URL with your own server's, or leave `.mcp.json` out.
80There is no server at `mcp.example.com`, so this example connector fails to connect when you test the plugin. Replace the URL with your own server's, or leave `.mcp.json` out.
8181
82 Don't put API keys or other secrets in this file, because every person who installs the plugin receives its files. On claude.ai and in Cowork, the entry is listed on the plugin's **Connectors** tab, where the user [adds or connects it](/docs/plugins/overview#bundled-connectors) and signs in through your server's OAuth flow. On Team and Enterprise plans, an Owner adds the connector for the organization, and members then connect with their own account.
83 </Step>
82Don't put API keys or other secrets in this file, because every person who installs the plugin receives its files. On claude.ai and in Cowork, the entry is listed on the plugin's **Connectors** tab, where the user [adds or connects it](/docs/plugins/overview#bundled-connectors) and signs in through your server's OAuth flow. On Team and Enterprise plans, an Owner adds the connector for the organization, and members then connect with their own account.
8483
85 <Step title="Write the README">
86 Create `README.md` in the plugin folder with at least 40 words. Words inside code blocks don't count. Say what the plugin does, how to use it, and what data it sends. The directory shows your README as the listing's description, and [README and license](/docs/plugins/pre-submission-checklist#readme-and-license) lists what validation checks.
84**4. Write the README**
8785
88 This README covers those three points for the example plugin:
86Create `README.md` in the plugin folder with at least 40 words. Words inside code blocks don't count. Say what the plugin does, how to use it, and what data it sends. The directory shows your README as the listing's description, and [README and license](/docs/plugins/pre-submission-checklist#readme-and-license) lists what validation checks.
8987
90 ```markdown theme={null}
91 # Expense Reports
88This README covers those three points for the example plugin:
9289
93 File, track, and approve expense reports from a conversation with Claude.
90```markdown theme={null}
91# Expense Reports
9492
95 ## Use it
93File, track, and approve expense reports from a conversation with Claude.
9694
97 Attach a receipt and ask Claude to file it. Claude reads the amount, date,
98 and merchant, files the report through the Expense Reports connector, and
99 replies with the report number. Ask what's waiting on you to list the
100 reports that need your approval.
95## Use it
10196
102 ## Data
97Attach a receipt and ask Claude to file it. Claude reads the amount, date,
98and merchant, files the report through the Expense Reports connector, and
99replies with the report number. Ask what's waiting on you to list the
100reports that need your approval.
103101
104 The plugin sends receipt details and report fields to your Example Corp
105 account through mcp.example.com. It stores nothing itself.
106 ```
107 </Step>
102## Data
108103
109 <Step title="Check the license">
110 The directory requires a `LICENSE` file in the plugin folder or `license` in `plugin.json`, and validation blocks a plugin that has neither. The example manifest sets `license`, which meets the requirement. If you remove that field, add a `LICENSE` file to the plugin folder instead.
111 </Step>
112</Steps>
104The plugin sends receipt details and report fields to your Example Corp
105account through mcp.example.com. It stores nothing itself.
106```
113107
108**5. Check the license**
109
110The directory requires a `LICENSE` file in the plugin folder or `license` in `plugin.json`, and validation blocks a plugin that has neither. The example manifest sets `license`, which meets the requirement. If you remove that field, add a `LICENSE` file to the plugin folder instead.
111
114112## Test the plugin in Claude Code
115113
116114Load the plugin from your working copy before you push it. From the folder that contains `expense-reports`, start a Claude Code session with the plugin loaded:
from line 145
147145
148146The directory reads plugins from repositories on github.com, so the plugin folder goes in a GitHub repository.
149147
150<Steps>
151 <Step title="Create the repository">
152 Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
153 </Step>
148**1. Create the repository**
154149
155 <Step title="Remove system files">
156 Remove `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `__MACOSX` entries from the plugin folder, and add them to `.gitignore`. Validation blocks a plugin that contains them.
157 </Step>
150Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
158151
159 <Step title="Commit and push">
160 From inside the `expense-reports` folder, commit the files and push them. The example pushes to a repository named `example-corp/expense-reports`, so replace that name with your own:
152**2. Remove system files**
161153
162 ```bash theme={null}
163 git init -b main
164 git add .
165 git commit -m "Add the expense-reports plugin"
166 git remote add origin https://github.com/example-corp/expense-reports.git
167 git push -u origin main
168 ```
154Remove `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `__MACOSX` entries from the plugin folder, and add them to `.gitignore`. Validation blocks a plugin that contains them.
169155
170 The repository's page on github.com now shows `.claude-plugin/`, `skills/`, and the other plugin files at the repository root.
171 </Step>
172</Steps>
156**3. Commit and push**
157
158From inside the `expense-reports` folder, commit the files and push them. The example pushes to a repository named `example-corp/expense-reports`, so replace that name with your own:
159
160```bash theme={null}
161git init -b main
162git add .
163git commit -m "Add the expense-reports plugin"
164git remote add origin https://github.com/example-corp/expense-reports.git
165git push -u origin main
166```
167
168The repository's page on github.com now shows `.claude-plugin/`, `skills/`, and the other plugin files at the repository root.
173169
174170## Submit your own plugin
175171
plugins/share Changed · +10 / -12 lines
from line 6
66
77This page is for someone on a Team or Enterprise plan who created or uploaded a plugin, for example with [Create a plugin with Claude](/docs/plugins/create-with-claude).
88
9<Note>
10 * If you're an Owner reviewing what members publish, see [Manage plugins for your organization](/docs/plugins/admin)
11 * If you want a wider audience than your organization, see [Plugin structure and testing](/docs/plugins/build) and [Publish to the directory](/docs/directory/publish)
12</Note>
9> [!NOTE]
10>
11> * If you're an Owner reviewing what members publish, see [Manage plugins for your organization](/docs/plugins/admin)
12> * If you want a wider audience than your organization, see [Plugin structure and testing](/docs/plugins/build) and [Publish to the directory](/docs/directory/publish)
1313
1414To give the plugin to people you name, go to [Share a plugin with specific people](#share-a-plugin-with-specific-people). To reach the whole organization, go to [Publish a plugin to your organization](#publish-a-plugin-to-your-organization).
1515
from line 30
3030
3131Sharing gives the people you name your plugin in their **Customize > Plugins** list, turned off until they turn it on. To share with specific people:
3232
33<Steps>
34 <Step title="Open the plugin and select Share">
35 Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and open the plugin. Select **Share** at the top of its page. The plugin's menu in your **Your plugins** list has the same **Share** item.
36 </Step>
33**1. Open the plugin and select Share**
3734
38 <Step title="Add people">
39 Add each person by name or email address, then confirm the share.
40 </Step>
41</Steps>
35Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and open the plugin. Select **Share** at the top of its page. The plugin's menu in your **Your plugins** list has the same **Share** item.
36
37**2. Add people**
38
39Add each person by name or email address, then confirm the share.
4240
4341### What the people you share with get
4442
plugins/submit Changed · +43 / -45 lines
from line 6
66
77Use this page if your plugin is already in a GitHub repository and you want it listed. If the plugin references a remote MCP server you run, submit that server as an MCP connector too, as [Submit your plugin, and your MCP server as a connector](/docs/directory/publish#submit-your-plugin-and-your-mcp-server-as-a-connector) explains.
88
9<Note>
10 * To build the plugin first, see [Plugin structure and testing](/docs/plugins/build)
11 * To share it without a public listing, see [Share a plugin with teammates](/docs/plugins/share) or [Roll out a plugin to your whole organization](/docs/plugins/org-rollout)
12 * If you submitted through the earlier Claude Console form, see [Move an earlier submission to the developer portal](/docs/directory/publish#move-an-earlier-submission-to-the-developer-portal)
13</Note>
9> [!NOTE]
10>
11> * To build the plugin first, see [Plugin structure and testing](/docs/plugins/build)
12> * To share it without a public listing, see [Share a plugin with teammates](/docs/plugins/share) or [Roll out a plugin to your whole organization](/docs/plugins/org-rollout)
13> * If you submitted through the earlier Claude Console form, see [Move an earlier submission to the developer portal](/docs/directory/publish#move-an-earlier-submission-to-the-developer-portal)
1414
1515## Before you submit a plugin
1616
from line 27
2727
2828Each plugin folder is its own submission in the developer portal at [claude.ai/directory/manage](https://claude.ai/directory/manage), so a repository that holds several plugins needs one submission for each.
2929
30<Steps>
31 <Step title="Open the portal">
32 1. Open the [developer portal](https://claude.ai/directory/manage) and select **Submit new**.
33 2. When the portal asks **What would you like to submit?**, select **Plugin bundle**.
30**1. Open the portal**
3431
35 <Note>
36 The other option, **MCP connector**, submits one remote MCP server as its own connector listing. If your plugin references an MCP server you built and you haven't submitted that server yet, submit it separately with **MCP connector** by following [Submit your connector](/docs/connectors/building/submission). [Submit your plugin, and your MCP server as a connector](/docs/directory/publish#submit-your-plugin-and-your-mcp-server-as-a-connector) explains why you submit both.
37 </Note>
38 </Step>
321. Open the [developer portal](https://claude.ai/directory/manage) and select **Submit new**.
332. When the portal asks **What would you like to submit?**, select **Plugin bundle**.
3934
40 <Step title="Enter the source and validate">
41 On the **Source** step, fill in the fields:
35> [!NOTE]
36>
37> The other option, **MCP connector**, submits one remote MCP server as its own connector listing. If your plugin references an MCP server you built and you haven't submitted that server yet, submit it separately with **MCP connector** by following [Submit your connector](/docs/connectors/building/submission). [Submit your plugin, and your MCP server as a connector](/docs/directory/publish#submit-your-plugin-and-your-mcp-server-as-a-connector) explains why you submit both.
4238
43 * **Repository**: the GitHub repository's URL, or `owner/repo`. If you paste a link to a folder on a branch, the portal fills in the path and branch for you
44 * **Plugin path (optional)**: the folder that holds `.claude-plugin/plugin.json`, if the plugin isn't at the repository root
45 * **Branch or tag (optional)**: the branch or tag that the directory follows for new versions. The portal calls this the tracked branch or tag. Leave the field empty to follow the repository's default branch. A tag stays on its commit until you change the tag. If the branch name contains a slash, type the name in this field or enter `owner/repo@branch` in **Repository**, instead of pasting a folder link
39**2. Enter the source and validate**
4640
47 Then validate the plugin:
41On the **Source** step, fill in the fields:
4842
49 1. Select **Validate** to run the directory's validation checks on the plugin.
50 2. If a finding blocks submission, fix it in the repository and push the fix.
51 3. Validate again.
43* **Repository**: the GitHub repository's URL, or `owner/repo`. If you paste a link to a folder on a branch, the portal fills in the path and branch for you
44* **Plugin path (optional)**: the folder that holds `.claude-plugin/plugin.json`, if the plugin isn't at the repository root
45* **Branch or tag (optional)**: the branch or tag that the directory follows for new versions. The portal calls this the tracked branch or tag. Leave the field empty to follow the repository's default branch. A tag stays on its commit until you change the tag. If the branch name contains a slash, type the name in this field or enter `owner/repo@branch` in **Repository**, instead of pasting a folder link
5246
53 The [plugin pre-submission checklist](/docs/plugins/pre-submission-checklist) explains what each kind of finding means.
47Then validate the plugin:
5448
55 A validation result applies to one commit. If you push to the branch after validating, validate again before you continue.
56 </Step>
491. Select **Validate** to run the directory's validation checks on the plugin.
502. If a finding blocks submission, fix it in the repository and push the fix.
513. Validate again.
5752
58 <Step title="Check the listing details">
59 The **Listing details** step shows how the plugin appears in the directory, read from `plugin.json` and the README. To change a field before you submit, edit `plugin.json` or the README in the repository and validate again. Once the plugin is listed, its name and short description follow the version that's live, so to change them later, edit `plugin.json` or the README and publish a new version.
60 </Step>
53The [plugin pre-submission checklist](/docs/plugins/pre-submission-checklist) explains what each kind of finding means.
6154
62 <Step title="Answer the data handling questions">
63 On the **Data handling** step, answer each question: whether the plugin reads or stores personal data, whether it sends data to services other than its declared connectors, how long it keeps data, and whether it's intended for people under 18.
64 </Step>
55A validation result applies to one commit. If you push to the branch after validating, validate again before you continue.
6556
66 <Step title="Complete the compliance step">
67 On the **Compliance** step, check the contact email and select the acknowledgements:
57**3. Check the listing details**
6858
69 1. Check that the contact email is an address where Anthropic can reach you about the submission.
70 2. Select all four acknowledgements.
71 </Step>
59The **Listing details** step shows how the plugin appears in the directory, read from `plugin.json` and the README. To change a field before you submit, edit `plugin.json` or the README in the repository and validate again. Once the plugin is listed, its name and short description follow the version that's live, so to change them later, edit `plugin.json` or the README and publish a new version.
7260
73 <Step title="Review and submit">
74 On the **Review and submit** step, confirm the details, choose how new versions arrive, and submit:
61**4. Answer the data handling questions**
7562
76 1. Confirm the details.
77 2. Under **How new versions reach the directory**, choose **GitHub push webhook**, which is selected by default, or **Scheduled check only**. With either option, the directory also checks the tracked branch or tag for new commits on a schedule.
78 3. Select **Submit for review**.
63On the **Data handling** step, answer each question: whether the plugin reads or stores personal data, whether it sends data to services other than its declared connectors, how long it keeps data, and whether it's intended for people under 18.
7964
80 If you kept **GitHub push webhook**, the **Plugin submitted for review** page offers **Set up push updates**. You need admin access to the repository on GitHub to set up the webhook.
65**5. Complete the compliance step**
8166
82 To set it up later, open the plugin from **Submissions** in the developer portal and select **Set up** under **Updates** on the **Settings** tab.
83 </Step>
84</Steps>
67On the **Compliance** step, check the contact email and select the acknowledgements:
68
691. Check that the contact email is an address where Anthropic can reach you about the submission.
702. Select all four acknowledgements.
71
72**6. Review and submit**
73
74On the **Review and submit** step, confirm the details, choose how new versions arrive, and submit:
75
761. Confirm the details.
772. Under **How new versions reach the directory**, choose **GitHub push webhook**, which is selected by default, or **Scheduled check only**. With either option, the directory also checks the tracked branch or tag for new commits on a schedule.
783. Select **Submit for review**.
79
80If you kept **GitHub push webhook**, the **Plugin submitted for review** page offers **Set up push updates**. You need admin access to the repository on GitHub to set up the webhook.
81
82To set it up later, open the plugin from **Submissions** in the developer portal and select **Set up** under **Updates** on the **Settings** tab.
8583
8684### Submission limits and duplicates
8785
skills/how-to Changed · +119 / -488 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 2
22
33> Create a custom skill for Claude: write the SKILL.md file, add resources and scripts, package the skill, and test it.
44
5export const Piece = ({id, children}) => <div className="pe-piece" data-piece={id}>{children}</div>;
6
7export const PluginExplorer = ({children, variant}) => {
8 const SKILL_PIECES = [{
9 id: 'skillmd',
10 required: 'Required',
11 name: 'SKILL.md',
12 path: 'brand-guidelines/SKILL.md',
13 lines: [{
14 depth: 0,
15 kind: 'file',
16 text: 'SKILL.md'
17 }],
18 href: 'https://agentskills.io/specification',
19 linkText: 'Go to the Agent Skills specification'
20 }, {
21 id: 'references',
22 name: 'Reference file',
23 path: 'brand-guidelines/references/voice-and-tone.md',
24 lines: [{
25 depth: 0,
26 kind: 'folder',
27 text: 'references/'
28 }, {
29 depth: 1,
30 kind: 'file',
31 text: 'voice-and-tone.md'
32 }],
33 href: 'https://agentskills.io/specification',
34 linkText: 'Go to the Agent Skills specification'
35 }, {
36 id: 'assets',
37 name: 'Asset',
38 path: 'brand-guidelines/assets/slide-template.md',
39 lines: [{
40 depth: 0,
41 kind: 'folder',
42 text: 'assets/'
43 }, {
44 depth: 1,
45 kind: 'file',
46 text: 'slide-template.md'
47 }],
48 href: 'https://agentskills.io/specification',
49 linkText: 'Go to the Agent Skills specification'
50 }, {
51 id: 'scripts',
52 name: 'Script',
53 path: 'brand-guidelines/scripts/check_contrast.py',
54 lines: [{
55 depth: 0,
56 kind: 'folder',
57 text: 'scripts/'
58 }, {
59 depth: 1,
60 kind: 'file',
61 text: 'check_contrast.py'
62 }],
63 href: 'https://code.claude.com/docs/en/skills',
64 linkText: 'Go to Skills in Claude Code'
65 }];
66 const PLUGIN_PIECES = [{
67 id: 'manifest',
68 required: 'Required',
69 name: 'Manifest',
70 path: '.claude-plugin/plugin.json',
71 lines: [{
72 depth: 0,
73 kind: 'folder',
74 text: '.claude-plugin/'
75 }, {
76 depth: 1,
77 kind: 'file',
78 text: 'plugin.json'
79 }],
80 href: '/plugins/build#write-the-manifest',
81 linkText: 'Go to Write the manifest'
82 }, {
83 id: 'skills',
84 name: 'Skill',
85 path: 'skills/file-expense/SKILL.md',
86 lines: [{
87 depth: 0,
88 kind: 'folder',
89 text: 'skills/'
90 }, {
91 depth: 1,
92 kind: 'folder',
93 text: 'file-expense/'
94 }, {
95 depth: 2,
96 kind: 'file',
97 text: 'SKILL.md'
98 }],
99 href: '/skills/how-to',
100 linkText: 'Go to Create custom skills'
101 }, {
102 id: 'references',
103 name: 'Skill reference file',
104 path: 'skills/file-expense/references/categories.md',
105 lines: [{
106 depth: 2,
107 kind: 'folder',
108 text: 'references/'
109 }, {
110 depth: 3,
111 kind: 'file',
112 text: 'categories.md'
113 }],
114 href: '/skills/how-to#add-resources',
115 linkText: 'Go to Add resources'
116 }, {
117 id: 'scripts',
118 name: 'Skill script',
119 path: 'skills/file-expense/scripts/total.py',
120 lines: [{
121 depth: 2,
122 kind: 'folder',
123 text: 'scripts/'
124 }, {
125 depth: 3,
126 kind: 'file',
127 text: 'total.py'
128 }],
129 href: '/skills/how-to#add-scripts',
130 linkText: 'Go to Add scripts'
131 }, {
132 id: 'commands',
133 name: 'Command',
134 path: 'commands/summarize.md',
135 lines: [{
136 depth: 0,
137 kind: 'folder',
138 text: 'commands/'
139 }, {
140 depth: 1,
141 kind: 'file',
142 text: 'summarize.md'
143 }],
144 href: '/plugins/platform-support#compare-component-support-by-app',
145 linkText: 'Go to component support by app'
146 }, {
147 id: 'mcp',
148 name: 'MCP connector',
149 path: '.mcp.json',
150 lines: [{
151 depth: 0,
152 kind: 'file',
153 text: '.mcp.json'
154 }],
155 href: '/plugins/build#bundle-an-mcp-connector-with-its-skill',
156 linkText: 'Go to Bundle an MCP connector with its skill'
157 }, {
158 id: 'readme',
159 required: 'Required to publish',
160 name: 'README',
161 path: 'README.md',
162 lines: [{
163 depth: 0,
164 kind: 'file',
165 text: 'README.md'
166 }],
167 href: '/plugins/pre-submission-checklist#readme-and-license',
168 linkText: 'Go to README and license checks'
169 }, {
170 id: 'license',
171 required: 'Required to publish',
172 name: 'License',
173 path: 'LICENSE',
174 lines: [{
175 depth: 0,
176 kind: 'file',
177 text: 'LICENSE'
178 }],
179 href: '/plugins/pre-submission-checklist#readme-and-license',
180 linkText: 'Go to README and license checks'
181 }];
182 const isSkill = variant === 'skill';
183 const PIECES = isSkill ? SKILL_PIECES : PLUGIN_PIECES;
184 const rootLabel = isSkill ? 'brand-guidelines/' : 'expense-reports/';
185 const title = isSkill ? 'What goes in the skill folder' : 'What goes in the plugin folder';
186 const treeCaption = isSkill ? 'Skill folder' : 'Plugin folder';
187 const [selectedId, setSelectedId] = useState(isSkill ? 'skillmd' : 'manifest');
188 const [isFullscreen, setIsFullscreen] = useState(false);
189 const rootRef = useRef(null);
190 useEffect(() => {
191 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);
192 document.addEventListener('fullscreenchange', onFsChange);
193 return () => document.removeEventListener('fullscreenchange', onFsChange);
194 }, []);
195 const toggleFullscreen = () => {
196 if (!rootRef.current) return;
197 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});
198 };
199 const selected = PIECES.find(p => p.id === selectedId) || PIECES[0];
200 const onTreeKeyDown = e => {
201 const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
202 if (keys.indexOf(e.key) === -1) return;
203 const i = PIECES.findIndex(p => p.id === selectedId);
204 let next = i;
205 if (e.key === 'ArrowDown') next = Math.min(PIECES.length - 1, i + 1);
206 if (e.key === 'ArrowUp') next = Math.max(0, i - 1);
207 if (e.key === 'Home') next = 0;
208 if (e.key === 'End') next = PIECES.length - 1;
209 e.preventDefault();
210 if (next === i) return;
211 const id = PIECES[next].id;
212 setSelectedId(id);
213 const el = document.getElementById('pe-node-' + id);
214 if (el) el.focus();
215 };
216 const FolderIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
217 <path d="M1.5 4.5a1 1 0 0 1 1-1h3.2l1.3 1.5h6a1 1 0 0 1 1 1V12a1 1 0 0 1-1 1h-10.5a1 1 0 0 1-1-1z" />
218 </svg>;
219 const FileIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
220 <path d="M4 1.5h5.5L13 5v9.5H4z" />
221 <path d="M9.5 1.5V5H13" />
222 </svg>;
223 return <div ref={rootRef} className={isFullscreen ? 'pe-root pe-fullscreen not-prose' : 'pe-root not-prose'} data-selected={selected.id}>
224 <style>{`
225 .pe-root {
226 --pe-mono: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
227 --pe-accent: #D97757;
228 --pe-accent-text: #A8502F;
229 --pe-accent-bg: rgba(217,119,87,0.10);
230 --pe-bg: #FFFFFF;
231 --pe-surface: #FAFAF7;
232 --pe-hover: #F0EEE6;
233 --pe-border: #E8E6DC;
234 --pe-text: #141413;
235 --pe-text-2: #3D3D3A;
236 --pe-text-3: #5E5D59;
237 font-family: inherit;
238 background: var(--pe-bg);
239 color: var(--pe-text);
240 border: 1px solid var(--pe-border);
241 border-radius: 12px;
242 margin: 1.5rem 0;
243 overflow: hidden;
244 box-sizing: border-box;
245 }
246 .dark .pe-root {
247 --pe-accent-text: #EBA98F;
248 --pe-accent-bg: rgba(217,119,87,0.18);
249 --pe-bg: #1A1918;
250 --pe-surface: #232221;
251 --pe-hover: #2E2D2B;
252 --pe-border: #3A3936;
253 --pe-text: #F1EFE9;
254 --pe-text-2: #D6D4CA;
255 --pe-text-3: #B8B5AD;
256 }
257 .pe-root *, .pe-root *::before, .pe-root *::after { box-sizing: border-box; }
258 .pe-head { display: flex; align-items: flex-start; gap: 12px; padding: 18px 24px 16px; border-bottom: 1px solid var(--pe-border); }
259 .pe-head-text { flex: 1; min-width: 0; }
260 .pe-fs-btn { flex-shrink: 0; width: 32px; height: 32px; display: inline-flex; align-items: center; justify-content: center; border: 1px solid var(--pe-border); border-radius: 6px; background: var(--pe-surface); color: var(--pe-text-2); font-size: 15px; line-height: 1; cursor: pointer; }
261 .pe-fs-btn:hover { background: var(--pe-hover); }
262 .pe-fs-btn:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }
263 .pe-fullscreen { border-radius: 0; height: 100vh; display: flex; flex-direction: column; overflow: auto; }
264 .pe-fullscreen .pe-body { flex: 1; }
265 .pe-title { font-size: 19px; font-weight: 600; line-height: 1.3; color: var(--pe-text); margin: 0; }
266 .pe-sub { font-size: 15px; line-height: 1.5; color: var(--pe-text-3); margin: 4px 0 0; }
267 .pe-sub code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }
268 .pe-body { display: flex; align-items: stretch; }
269 .pe-tree-pane { width: 270px; flex-shrink: 0; background: var(--pe-surface); border-right: 1px solid var(--pe-border); padding: 16px 0 12px; }
270 .pe-panel { flex: 1; min-width: 0; padding: 16px 24px 24px; }
271 .pe-caption { font-size: 13px; font-weight: 600; color: var(--pe-text-3); margin: 0 0 10px; }
272 .pe-tree-pane .pe-caption { padding: 0 16px; }
273 .pe-rootline { display: flex; align-items: center; gap: 7px; padding: 3px 16px; font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-text-3); }
274 .pe-node {
275 display: block; width: 100%; margin: 0; padding: 3px 16px 3px 30px; text-align: left; cursor: pointer;
276 background: transparent; color: var(--pe-text-2);
277 border: none; border-left: 3px solid transparent;
278 font-family: var(--pe-mono); font-size: 13.5px; line-height: 1.4;
279 }
280 .pe-node:hover { background: var(--pe-hover); }
281 .pe-node:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: -2px; }
282 .pe-node[aria-pressed="true"] { background: var(--pe-accent-bg); border-left-color: var(--pe-accent); color: var(--pe-accent-text); font-weight: 600; }
283 .pe-line { display: flex; align-items: center; gap: 7px; padding: 2px 0; }
284 .pe-line span { overflow-wrap: anywhere; }
285 .pe-line > span:not(.pe-req) { white-space: nowrap; flex-shrink: 0; }
286 .pe-req { flex-shrink: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; margin-left: 8px; padding: 0 6px; border-radius: 999px; font-size: 11px; line-height: 18px; font-family: var(--pe-sans, inherit); letter-spacing: .02em; color: var(--pe-accent-text); border: 1px solid var(--pe-border); background: var(--pe-surface); white-space: nowrap; }
287 .pe-piece { display: none; font-size: 16px; line-height: 1.6; color: var(--pe-text-2); }
288 ${PIECES.map(p => '.pe-root[data-selected="' + p.id + '"] .pe-piece[data-piece="' + p.id + '"]').join(',\n ')} { display: block; }
289 .pe-piece p { margin: 0 0 10px; }
290 .pe-piece p:last-child { margin-bottom: 0; }
291 .pe-piece ul { list-style: disc; padding-left: 1.25em; margin: 0 0 10px; }
292 .pe-piece li { margin: 2px 0; }
293 .pe-piece code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }
294 .pe-piece .code-block { margin: 12px 0 0; }
295 .pe-piece pre code { padding: 0; border: none; background: none; }
296 .pe-piece a { color: var(--pe-accent-text); }
297 .pe-line-compact { display: none; }
298 .pe-icon { flex-shrink: 0; }
299 .pe-name { font-size: 22px; font-weight: 600; line-height: 1.25; letter-spacing: -0.2px; color: var(--pe-text); margin: 0; }
300 .pe-path { font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-accent-text); margin: 4px 0 0; overflow-wrap: anywhere; }
301 .pe-block { margin: 20px 0 0; }
302 .pe-link {
303 display: inline-block; margin: 24px 0 0; padding: 8px 14px; border-radius: 8px;
304 font-size: 14.5px; font-weight: 600; text-decoration: none;
305 color: var(--pe-accent-text); background: var(--pe-accent-bg); border: 1px solid var(--pe-accent);
306 }
307 .pe-link:hover { filter: brightness(0.97); }
308 .pe-link:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }
309 @media (max-width: 700px) {
310 .pe-head { padding: 16px 16px 14px; }
311 .pe-body { flex-direction: column; }
312 .pe-tree-pane { width: 100%; border-right: none; border-bottom: 1px solid var(--pe-border); }
313 .pe-line-tree { display: none; }
314 .pe-line-compact { display: flex; }
315 .pe-panel { padding: 16px 16px 20px; }
316 }
317 `}</style>
318
319 <div className="pe-head">
320 <div className="pe-head-text">
321 <div className="pe-title">{title}</div>
322 {isSkill ? <div className="pe-sub">This example skill, <code>brand-guidelines</code>, has one of each kind of file a skill can carry. Select a file to read what it's for and see a minimal example.</div> : <div className="pe-sub">This example plugin, <code>expense-reports</code>, has one of each file that chat, Cowork, and Claude Code all load, plus the README and license the directory requires. Select a file to read what it’s for and see a minimal example.</div>}
323 </div>
324 <button type="button" className="pe-fs-btn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>
325 {isFullscreen ? '⤡' : '⛶'}
326 </button>
327 </div>
328
329 <div className="pe-body">
330 <div className="pe-tree-pane">
331 <div className="pe-caption" id="pe-tree-caption">{treeCaption}</div>
332 <div role="group" aria-labelledby="pe-tree-caption" onKeyDown={onTreeKeyDown}>
333 <div className="pe-rootline"><FolderIcon /><span>{rootLabel}</span></div>
334 {PIECES.map(p => <button key={p.id} id={'pe-node-' + p.id} type="button" className="pe-node" aria-pressed={p.id === selected.id} aria-label={p.name + ', ' + p.path} onClick={() => setSelectedId(p.id)}>
335 {p.lines.map((line, i) => <span key={i} className="pe-line pe-line-tree" style={{
336 paddingLeft: line.depth * 18 + 'px'
337 }}>
338 {line.kind === 'folder' ? <FolderIcon /> : <FileIcon />}
339 <span>{line.text}</span>
340 {p.required && i === p.lines.length - 1 ? <span className="pe-req" title={p.required}>Required</span> : null}
341 </span>)}
342 <span className="pe-line pe-line-compact">
343 <FileIcon />
344 <span>{p.path}</span>
345 {p.required ? <span className="pe-req" title={p.required}>Required</span> : null}
346 </span>
347 </button>)}
348 </div>
349 </div>
350
351 <div className="pe-panel" role="region" aria-labelledby="pe-panel-caption" aria-live="polite" aria-atomic="true">
352 <div className="pe-caption" id="pe-panel-caption">Selected file</div>
353 <div className="pe-name">{selected.name}{selected.required ? <span className="pe-req">{selected.required}</span> : null}</div>
354 <div className="pe-path">{selected.path}</div>
355
356 <div className="pe-block">{children}</div>
357
358 <a className="pe-link" href={selected.href}>{selected.linkText}</a>
359 </div>
360 </div>
361 </div>;
362};
363
3645A custom skill is a folder with a `SKILL.md` file of instructions, and optionally scripts and reference files, that Claude loads when a task matches the skill's description. This guide is for anyone writing a skill of their own. It explains how to create, structure, and test one.
3656
3667If you already know what the skill should do, start with the [directory structure](#directory-structure). If you're not sure a skill is the right tool, read [Decide what skill to create](#decide-what-skill-to-create) first.
3678
368<Note>
369 Skills follow the [Agent Skills specification](https://agentskills.io/specification). See the specification for more in-depth information.
370</Note>
9> [!NOTE]
10>
11> Skills follow the [Agent Skills specification](https://agentskills.io/specification). See the specification for more in-depth information.
37112
37213## Decide what skill to create
37314
from line 26
38526
38627A skill is a folder named after the skill. The only required file is `SKILL.md`; the other folders are optional and hold material that `SKILL.md` points Claude to. Select a file in the explorer to see what goes in it and what Claude does with it.
38728
388<PluginExplorer variant="skill">
389 <Piece id="skillmd">
390 <p>The one required file. Its frontmatter names and describes the skill, and Claude reads the <code>description</code> to decide when the skill applies. The body holds the instructions Claude follows once it does.</p>
391 <p>In this example, the skill applies Acme's brand guidelines and tells Claude where the supporting files are:</p>
392
393 ```markdown SKILL.md theme={null}
394 ---
395 name: brand-guidelines
396 description: Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage.
397 ---
398 Use these guidelines whenever you produce a document or deck for Acme.
399
400 1. Use the colors and fonts in the sections below.
401 2. For wording, follow `references/voice-and-tone.md`.
402 3. For slides, start from `assets/slide-template.md`.
403 4. Before you finish, run `python3 ${CLAUDE_SKILL_DIR}/scripts/check_contrast.py` on any color pairs you chose.
404 ```
405 </Piece>
406
407 <Piece id="references">
408 <p>Longer background that Claude reads only when a step calls for it, so it doesn't crowd <code>SKILL.md</code>. Mention the file by path at the step where Claude needs it.</p>
409 <p>In this example, the file holds the writing rules the instructions point to in step 2:</p>
410
411 ```markdown references/voice-and-tone.md theme={null}
412 # Voice and tone
413 - Write in the second person and the present tense.
414 - Prefer short sentences. Avoid exclamation marks.
415 - Product names are always capitalized: Acme Cloud, Acme Sync.
416 ```
417 </Piece>
418
419 <Piece id="assets">
420 <p>Templates, images, and data files that Claude copies or fills in rather than reads for guidance.</p>
421 <p>In this example, the asset is the slide outline that step 3 tells Claude to start from:</p>
422
423 ```markdown assets/slide-template.md theme={null}
424 # [Deck title]
425 ## Agenda
426 ## [Section 1]
427 ## [Section 2]
428 ## Next steps
429 ```
430 </Piece>
431
432 <Piece id="scripts">
433 <p>Code that Claude runs while following the skill, for work that is more reliable as a program than as instructions. Reference it from `SKILL.md` with `${CLAUDE_SKILL_DIR}` so the path resolves wherever the skill is installed.</p>
434 <p>In this example, the script checks that a text and background color pair has enough contrast:</p>
435
436 ```python scripts/check_contrast.py theme={null}
437 import sys
438
439 def luminance(hex_color):
440 r, g, b = (int(hex_color[i:i+2], 16) / 255 for i in (1, 3, 5))
441 f = lambda c: c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
442 return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b)
443
444 fg, bg = sys.argv[1], sys.argv[2]
445 l1, l2 = sorted((luminance(fg), luminance(bg)), reverse=True)
446 ratio = (l1 + 0.05) / (l2 + 0.05)
447 print(f"{ratio:.2f}", "OK" if ratio >= 4.5 else "LOW")
448 ```
449 </Piece>
450</PluginExplorer>
29What goes in the skill folder
30
31This example skill, `brand-guidelines`, has one of each kind of file a skill can carry. Select a file to read what it's for and see a minimal example.
32
33Skill folder
34
35brand-guidelines/
36
37Selected file
38
39The one required file. Its frontmatter names and describes the skill, and Claude reads the `description` to decide when the skill applies. The body holds the instructions Claude follows once it does.In this example, the skill applies Acme's brand guidelines and tells Claude where the supporting files are:
40
41```markdown SKILL.md theme={null}
42---
43name: brand-guidelines
44description: Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage.
45---
46Use these guidelines whenever you produce a document or deck for Acme.
47
481. Use the colors and fonts in the sections below.
492. For wording, follow `references/voice-and-tone.md`.
503. For slides, start from `assets/slide-template.md`.
514. Before you finish, run `python3 ${CLAUDE_SKILL_DIR}/scripts/check_contrast.py` on any color pairs you chose.
52```
53
54Longer background that Claude reads only when a step calls for it, so it doesn't crowd `SKILL.md`. Mention the file by path at the step where Claude needs it.In this example, the file holds the writing rules the instructions point to in step 2:
55
56```markdown references/voice-and-tone.md theme={null}
57# Voice and tone
58- Write in the second person and the present tense.
59- Prefer short sentences. Avoid exclamation marks.
60- Product names are always capitalized: Acme Cloud, Acme Sync.
61```
62
63Templates, images, and data files that Claude copies or fills in rather than reads for guidance.In this example, the asset is the slide outline that step 3 tells Claude to start from:
64
65```markdown assets/slide-template.md theme={null}
66# [Deck title]
67## Agenda
68## [Section 1]
69## [Section 2]
70## Next steps
71```
72
73Code that Claude runs while following the skill, for work that is more reliable as a program than as instructions. Reference it from `SKILL.md` with `${CLAUDE_SKILL_DIR}` so the path resolves wherever the skill is installed.In this example, the script checks that a text and background color pair has enough contrast:
74
75```python scripts/check_contrast.py theme={null}
76import sys
77
78def luminance(hex_color):
79 r, g, b = (int(hex_color[i:i+2], 16) / 255 for i in (1, 3, 5))
80 f = lambda c: c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
81 return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b)
82
83fg, bg = sys.argv[1], sys.argv[2]
84l1, l2 = sorted((luminance(fg), luminance(bg)), reverse=True)
85ratio = (l1 + 0.05) / (l2 + 0.05)
86print(f"{ratio:.2f}", "OK" if ratio >= 4.5 else "LOW")
87```
45188
45289As a plain tree, the same skill looks like this. The directory name must match the `name` field in your `SKILL.md`, and everything except `SKILL.md` is optional:
45390
from line 212
575212 └── scripts/
576213```
577214
578<Steps>
579 <Step title="Check the directory name">
580 Make sure the directory name matches the `name` field in `SKILL.md`.
581 </Step>
582
583 <Step title="Zip the directory from its parent folder">
584 Where the `zip` command is available, such as on macOS and Linux, run it from the folder that contains the skill directory, so the directory becomes the top level of the archive:
585
586 ```bash theme={null}
587 zip -r my-skill.zip my-skill/
588 ```
589
590 If you use another tool to create the ZIP, compress the skill folder itself rather than the files inside it.
591 </Step>
592
593 <Step title="Confirm the structure">
594 List the archive and check that every entry starts with `my-skill/`:
595
596 ```bash theme={null}
597 unzip -l my-skill.zip
598 ```
599
600 If `SKILL.md` appears without the `my-skill/` prefix, you zipped the contents instead of the folder; zip again from the parent folder.
601 </Step>
602</Steps>
215**1. Check the directory name**
216
217Make sure the directory name matches the `name` field in `SKILL.md`.
218
219**2. Zip the directory from its parent folder**
220
221Where the `zip` command is available, such as on macOS and Linux, run it from the folder that contains the skill directory, so the directory becomes the top level of the archive:
222
223```bash theme={null}
224zip -r my-skill.zip my-skill/
225```
226
227If you use another tool to create the ZIP, compress the skill folder itself rather than the files inside it.
228
229**3. Confirm the structure**
230
231List the archive and check that every entry starts with `my-skill/`:
232
233```bash theme={null}
234unzip -l my-skill.zip
235```
236
237If `SKILL.md` appears without the `my-skill/` prefix, you zipped the contents instead of the folder; zip again from the parent folder.
603238
604239To check the skill's contents rather than the archive shape, [validate it before uploading](#before-uploading) with `skills-ref validate` or `claude plugin validate`, or ask Claude to review the folder against the [Agent Skills specification](https://agentskills.io/specification).
605240
from line 246
611246
612247Before you upload the ZIP, check the skill's files:
613248
614<Steps>
615 <Step title="Review SKILL.md">
616 Review `SKILL.md` for clarity.
617 </Step>
618
619 <Step title="Check the description">
620 Verify the description accurately reflects when Claude should use the skill.
621 </Step>
622
623 <Step title="Check referenced files">
624 Check that all referenced files exist.
625 </Step>
626
627 <Step title="Validate the skill">
628 Check the frontmatter against the Agent Skills specification with the [`skills-ref` reference tool](https://github.com/agentskills/agentskills/tree/main/skills-ref). It isn't preinstalled: clone that repository and install it into a Python virtual environment as its README describes, which puts `skills-ref` on your `PATH` while the environment is active. Then, from the folder that contains the skill directory, run:
629
630 ```bash theme={null}
631 skills-ref validate ./my-skill
632 ```
633
634 A skill that passes prints `Valid skill: ./my-skill`. Otherwise the command lists each problem, such as a `name` that doesn't match the directory or a frontmatter field the specification doesn't define.
635
636 If the skill is inside a plugin folder, running `claude plugin validate ./my-plugin` in your terminal also parses each skill's frontmatter: it reports a `SKILL.md` whose frontmatter doesn't parse, and prints `✔ Validation passed` when the plugin passes.
637 </Step>
638</Steps>
249**1. Review SKILL.md**
250
251Review `SKILL.md` for clarity.
252
253**2. Check the description**
254
255Verify the description accurately reflects when Claude should use the skill.
256
257**3. Check referenced files**
258
259Check that all referenced files exist.
260
261**4. Validate the skill**
262
263Check the frontmatter against the Agent Skills specification with the [`skills-ref` reference tool](https://github.com/agentskills/agentskills/tree/main/skills-ref). It isn't preinstalled: clone that repository and install it into a Python virtual environment as its README describes, which puts `skills-ref` on your `PATH` while the environment is active. Then, from the folder that contains the skill directory, run:
264
265```bash theme={null}
266skills-ref validate ./my-skill
267```
268
269A skill that passes prints `Valid skill: ./my-skill`. Otherwise the command lists each problem, such as a `name` that doesn't match the directory or a frontmatter field the specification doesn't define.
270
271If the skill is inside a plugin folder, running `claude plugin validate ./my-plugin` in your terminal also parses each skill's frontmatter: it reports a `SKILL.md` whose frontmatter doesn't parse, and prints `✔ Validation passed` when the plugin passes.
639272
640273### In Claude Code
641274
from line 278
645278
646279After you upload, confirm that Claude loads the skill when it should:
647280
648<Steps>
649 <Step title="Turn the skill on">
650 Go to [**Customize > Skills**](https://claude.ai/customize/skills) in claude.ai or the desktop app and turn the skill on.
651 </Step>
652
653 <Step title="Try prompts that should trigger it">
654 Send prompts that should trigger the skill, and review Claude's thinking to confirm it's loading the skill.
655 </Step>
656
657 <Step title="Iterate on the description">
658 Iterate on the description if Claude isn't using it when expected.
659 </Step>
660</Steps>
281**1. Turn the skill on**
282
283Go to [**Customize > Skills**](https://claude.ai/customize/skills) in claude.ai or the desktop app and turn the skill on.
284
285**2. Try prompts that should trigger it**
286
287Send prompts that should trigger the skill, and review Claude's thinking to confirm it's loading the skill.
288
289**3. Iterate on the description**
290
291Iterate on the description if Claude isn't using it when expected.
661292
662293### Measure whether the skill improves the output
663294
664295
skills/overview Changed · +13 / -15 lines
from line 6
66
77This page is for people who want to find, turn on, and use skills in Claude.
88
9<Note>
10 * Skills are available on Pro, Max, Team, and Enterprise plans. They run in Claude's code sandbox, so **Code execution and file creation** must be on: turn it on under [**Settings > Capabilities**](https://claude.ai/settings/capabilities), or on Team and Enterprise plans ask an Owner to turn it on under **Organization settings > Capabilities**
11 * If you want to write a skill of your own, see [Create custom skills](/docs/skills/how-to)
12</Note>
9> [!NOTE]
10>
11> * Skills are available on Pro, Max, Team, and Enterprise plans. They run in Claude's code sandbox, so **Code execution and file creation** must be on: turn it on under [**Settings > Capabilities**](https://claude.ai/settings/capabilities), or on Team and Enterprise plans ask an Owner to turn it on under **Organization settings > Capabilities**
12> * If you want to write a skill of your own, see [Create custom skills](/docs/skills/how-to)
1313
1414For the steps, go to [Find, turn on, and use skills](#find-turn-on-and-use-skills).
1515
from line 27
2727
2828All of your skills are listed at [**Customize > Skills**](https://claude.ai/customize/skills) in claude.ai and the desktop app, including skills that came inside a plugin.
2929
30<Steps>
31 <Step title="Open Customize > Skills">
32 The **Your skills** tab lists the skills you have, grouped by where they came from: **Created by you**, **From your organization**, **Shared with you**, and **From Anthropic & Partners**. The **Discover** tab lists skills you can add.
33 </Step>
30**1. Open Customize > Skills**
3431
35 <Step title="Turn a skill on">
36 Select **Turn on** on the skill's row, or open the skill and use the switch at the top of its page. A skill's instructions and any scripts it carries run as part of your conversation, and skills someone shares with you or that you upload yourself aren't reviewed by Anthropic, so open the skill and read its `SKILL.md` and files before you turn it on.
37 </Step>
32The **Your skills** tab lists the skills you have, grouped by where they came from: **Created by you**, **From your organization**, **Shared with you**, and **From Anthropic & Partners**. The **Discover** tab lists skills you can add.
3833
39 <Step title="Use it in a conversation">
40 Describe your task, and Claude loads a skill that's turned on when the task matches the skill's description. To pick one yourself, type `/` in the message box and select the skill.
41 </Step>
42</Steps>
34**2. Turn a skill on**
35
36Select **Turn on** on the skill's row, or open the skill and use the switch at the top of its page. A skill's instructions and any scripts it carries run as part of your conversation, and skills someone shares with you or that you upload yourself aren't reviewed by Anthropic, so open the skill and read its `SKILL.md` and files before you turn it on.
37
38**3. Use it in a conversation**
39
40Describe your task, and Claude loads a skill that's turned on when the task matches the skill's description. To pick one yourself, type `/` in the message box and select the skill.
4341
4442A plugin's skills appear on **Your skills** too, labeled with the plugin's name. They turn on and off with the plugin, which you manage from [**Customize > Plugins**](/docs/plugins/overview#manage-installed-plugins).
4543
third-party/claude-desktop/admin-console Changed · +89 / -95 lines
from line 2
22
33> Manage your organization's Claude Desktop 3P configuration centrally with the Enterprise Admin Console, hosted by Anthropic
44
5<Info>
6 The Enterprise Admin Console for Desktop 3P is generally available.
7</Info>
5> [!NOTE]
6>
7> The Enterprise Admin Console for Desktop 3P is generally available.
88
9<Note>
10 To use the Enterprise Admin Console, contact your Anthropic representative to have an organization provisioned.
11</Note>
9> [!NOTE]
10>
11> To use the Enterprise Admin Console, contact your Anthropic representative to have an organization provisioned.
1212
1313With the Enterprise Admin Console, Anthropic hosts your organization's [Claude Desktop 3P](/docs/third-party/claude-desktop/overview) configuration, and your administrators manage it centrally instead of pushing files to each device. You sign in to the console in a browser and choose your inference provider, the app's settings, and which groups of users get which settings, rather than authoring an [MDM](/docs/third-party/claude-desktop/mdm) profile or running a [bootstrap server](/docs/third-party/claude-desktop/bootstrap). Your users sign in to Claude Desktop with their work account, through your single sign-on if you connect it. The app then downloads the settings that apply to them and sends every model request to your provider.
1414
from line 41
4141| Essential telemetry (crash and error reports) and non-essential telemetry (product analytics) | **Yes**, unless you turn them off on the **Telemetry & updates** page. Neither contains prompt or response content. [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) describes what each category contains. |
4242| Usage analytics: session, token, and estimated-cost counts per user, conversation, and model | **Yes**, if you turn on the **Report desktop usage to this organization** switch on the **Telemetry & updates** page. The switch is off by default. Users' apps report new counts only while the switch is on, and turning the switch off doesn't delete counts that Anthropic has already received. The counts contain no prompt, response, or file content. [Usage analytics](#usage-analytics) lists exactly what each report contains. |
4343
44The app contacts `api.anthropic.com` at every launch to check the user's sign-in and download the configuration. While the app runs, it contacts `api.anthropic.com` again every 10 minutes by default to check for configuration changes. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in pages run a browser check from `hcaptcha.com` and `*.hcaptcha.com`. If those two hosts are blocked, signing in with an email link or Google can fail with a message that the browser couldn't be verified.
44The app contacts `api.anthropic.com` at every launch to check the user's sign-in and download the configuration. While the app runs, it contacts `api.anthropic.com` again every 10 minutes by default to check for configuration changes. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in and approval pages run a browser check from `hcaptcha.com` and `*.hcaptcha.com`. If those two hosts are blocked, signing in can fail with a message that the browser couldn't be verified, whichever sign-in method your organization uses.
4545
4646`api.anthropic.com`, `claude.ai`, `hcaptcha.com`, and `*.hcaptcha.com` are in addition to the hosts listed on [Telemetry and egress](/docs/third-party/claude-desktop/telemetry). While usage analytics is on, the app also sends its token and session counts to `api.anthropic.com` every few minutes during use and when it quits, so usage analytics needs no additional firewall entry.
4747
from line 65
6565
6666Sign in at [claude.ai](https://claude.ai), switch to the organization, and open **Organization settings**. The **Desktop 3P** section in the left navigation has one page per settings area, listed under [What you can configure](#what-you-can-configure). Each field sets one of the documented [configuration keys](/docs/third-party/claude-desktop/configuration), and the console checks values as you type and again when you click **Save changes**.
6767
68<Note>
69 Save the **Connection** page, where you choose your inference provider, before the other pages. The console doesn't accept **Save changes** on any other page until a connection is saved. A user who signs in to Claude Desktop and clicks **Restart** before a connection is saved stays in standard Claude Desktop instead of switching to your configuration. After you save the connection, ask those users to quit and reopen Claude Desktop, then restart when prompted.
70</Note>
68> [!NOTE]
69>
70> Save the **Connection** page, where you choose your inference provider, before the other pages. The console doesn't accept **Save changes** on any other page until a connection is saved. A user who signs in to Claude Desktop and clicks **Restart** before a connection is saved stays in standard Claude Desktop instead of switching to your configuration. After you save the connection, ask those users to quit and reopen Claude Desktop, then restart when prompted.
7171
7272### Start from an existing configuration file
7373
from line 108
108108
109109### Choose how users authenticate to your provider
110110
111<Tip>
112 Choose an interactive sign-in wherever your provider offers one. It is the recommended credential kind for a deployment managed from the console. Users sign in inside the app with their own accounts, and there is no shared credential to distribute to devices or rotate.
113</Tip>
111> [!TIP]
112>
113> Choose an interactive sign-in wherever your provider offers one. It is the recommended credential kind for a deployment managed from the console. Users sign in inside the app with their own accounts, and there is no shared credential to distribute to devices or rotate.
114114
115115The console never holds a provider credential. The **Credential kind** field on the **Connection** page tells Claude Desktop how each user's device obtains one, and offers the kinds your provider supports: **Interactive sign-in** in the app, **Identity provider sign-in (OIDC)** (for example, for [Amazon Bedrock behind an authenticating proxy](/docs/third-party/claude-desktop/bedrock#sign-in-with-your-identity-provider)), **Workforce Identity** (Google Cloud's Agent Platform only), **Cloud vendor profile** (an AWS profile or Google Cloud credentials file already on the device), or **Helper script** (a [credential helper](/docs/third-party/claude-desktop/credential-helper) on the device). Static API keys and bearer tokens aren't offered, because the console refuses to store them. The same **Connection** settings go to every user, so a credential kind that depends on something present on each device works only if your device management puts it there.
116116
from line 164
164164
165165While Unified Claude is on, it overrides the **Chat**, [**Advanced file analysis**](/docs/third-party/claude-desktop/chat#advanced-file-analysis), and **Cowork** switches, including where you turned one of them off.
166166
167<Warning>
168 While Unified Claude is on for your organization, it is on for every group. That includes a group whose policy turns Chat or Cowork off. You can't return a group to separate Chat and Cowork until you turn Unified Claude off for your organization.
167> [!WARNING]
168>
169> While Unified Claude is on for your organization, it is on for every group. That includes a group whose policy turns Chat or Cowork off. You can't return a group to separate Chat and Cowork until you turn Unified Claude off for your organization.
170>
171> To keep Chat, advanced file analysis, and Cowork off for a group, turn off the **Chat and Cowork unified view** switch in the group's policy. Where Unified Claude is still off for your organization, set the group's switches before you turn Unified Claude on. Turn on the group's **Opt into the new Chat and Cowork unified view** switch. If the **Chat and Cowork unified view** switch under it is on, turn it off. To keep a group's own **Chat** and **Cowork** switches in effect, keep Unified Claude off for your organization. Turn it on only in the policies of the groups that should have it. For a member of several groups, Unified Claude comes from the highest-ranked of their policies that sets it, even when a higher-ranked policy turns Chat or Cowork off.
169172
170 To keep Chat, advanced file analysis, and Cowork off for a group, turn off the **Chat and Cowork unified view** switch in the group's policy. Where Unified Claude is still off for your organization, set the group's switches before you turn Unified Claude on. Turn on the group's **Opt into the new Chat and Cowork unified view** switch. If the **Chat and Cowork unified view** switch under it is on, turn it off. To keep a group's own **Chat** and **Cowork** switches in effect, keep Unified Claude off for your organization. Turn it on only in the policies of the groups that should have it. For a member of several groups, Unified Claude comes from the highest-ranked of their policies that sets it, even when a higher-ranked policy turns Chat or Cowork off.
171</Warning>
172
173173To turn on Unified Claude for your whole organization, open **Organization settings** and go to the **Capabilities** page under **Desktop 3P**. Under **Allowed surfaces**, turn on the **Opt into the new Chat and Cowork unified view** switch. If the **Chat and Cowork unified view** switch under it is off, turn it on. Click **Save changes**.
174174
175175To turn on Unified Claude for some groups only:
176176
177<Steps>
178 <Step title="Make sure Unified Claude is off for your organization">
179 Open **Organization settings** and go to the **Capabilities** page under **Desktop 3P**. If the **Opt into the new Chat and Cowork unified view** switch under **Allowed surfaces** is off, continue with the next step. If the switch is on, turn it off, set the **Chat** and **Cowork** switches that reappear, and click **Save changes**.
180 </Step>
177**1. Make sure Unified Claude is off for your organization**
181178
182 <Step title="Open the group's policy">
183 Go to the **Permission policies** page under **People**. Open the group's policy, or click **Add permission policy** and pick the group, as described under [Per-group permission policies](#per-group-permission-policies).
184 </Step>
179Open **Organization settings** and go to the **Capabilities** page under **Desktop 3P**. If the **Opt into the new Chat and Cowork unified view** switch under **Allowed surfaces** is off, continue with the next step. If the switch is on, turn it off, set the **Chat** and **Cowork** switches that reappear, and click **Save changes**.
185180
186 <Step title="Turn on Unified Claude for the group">
187 In the policy's **Capabilities** section, turn on the **Opt into the new Chat and Cowork unified view** switch. If the **Chat and Cowork unified view** switch under it is off, turn it on.
188 </Step>
181**2. Open the group's policy**
189182
190 <Step title="Save the policy">
191 Click **Save changes**.
192 </Step>
193</Steps>
183Go to the **Permission policies** page under **People**. Open the group's policy, or click **Add permission policy** and pick the group, as described under [Per-group permission policies](#per-group-permission-policies).
194184
185**3. Turn on Unified Claude for the group**
186
187In the policy's **Capabilities** section, turn on the **Opt into the new Chat and Cowork unified view** switch. If the **Chat and Cowork unified view** switch under it is off, turn it on.
188
189**4. Save the policy**
190
191Click **Save changes**.
192
195193Turn off Unified Claude for your organization or for a group:
196194
197195* **For your whole organization**: open **Organization settings** and go to the **Capabilities** page under **Desktop 3P**. Under **Allowed surfaces**, turn off the **Opt into the new Chat and Cowork unified view** switch. The **Chat** and **Cowork** switches reappear in the positions they had. Switches that nobody set are at their defaults. Cowork is on, and Chat and advanced file analysis are off. Set the switches as you want, then click **Save changes**.
from line 266
268266
269267A device picks up the configuration from the admin console the first time the user signs in to Claude in the app. Walk through it on a test device first.
270268
271<Steps>
272 <Step title="Sign in to Claude">
273 Open Claude Desktop and sign in on the standard sign-in screen with your work email address, through your organization's single sign-on if you use it.
274 </Step>
269**1. Sign in to Claude**
275270
276 <Step title="Restart when prompted">
277 The app shows a dialog titled with your organization's name that reads "Your organization's Claude settings have changed. Restart to apply them." You can't dismiss the dialog. Click **Restart**, and the app relaunches in third-party mode with your configuration. An account that also belongs to another Claude organization sees a **Switch and restart** prompt instead, as described under [Users in more than one Claude organization](#users-in-more-than-one-claude-organization).
278 </Step>
271Open Claude Desktop and sign in on the standard sign-in screen with your work email address, through your organization's single sign-on if you use it.
279272
280 <Step title="Sign in to the inference provider">
281 If your connection uses an interactive sign-in, sign in to your inference provider or gateway next, as with MDM or bootstrap delivery.
282 </Step>
273**2. Restart when prompted**
283274
284 <Step title="Check the result">
285 The account menu at the bottom of the sidebar shows your organization's name and an **Inference configuration** item marked **Managed by your organization**, and **Settings → Privacy** names your inference provider. On a device whose managed profile sets any key other than the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence), the account menu shows your organization's name without the **Inference configuration** item.
286 </Step>
287</Steps>
275The app shows a dialog titled with your organization's name that reads "Your organization's Claude settings have changed. Restart to apply them." You can't dismiss the dialog. Click **Restart**, and the app relaunches in third-party mode with your configuration. An account that also belongs to another Claude organization sees a **Switch and restart** prompt instead, as described under [Users in more than one Claude organization](#users-in-more-than-one-claude-organization).
288276
277**3. Sign in to the inference provider**
278
279If your connection uses an interactive sign-in, sign in to your inference provider or gateway next, as with MDM or bootstrap delivery.
280
281**4. Check the result**
282
283The account menu at the bottom of the sidebar shows your organization's name and an **Inference configuration** item marked **Managed by your organization**, and **Settings → Privacy** names your inference provider. On a device whose managed profile sets any key other than the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence), the account menu shows your organization's name without the **Inference configuration** item.
284
289285If something looks wrong, **Help → Troubleshooting → Generate Diagnostic Report** produces a report that shows where the app read its configuration from. You can share it with your Anthropic representative.
290286
291287Give each user their own computer login. Claude Desktop keeps conversation history for each computer login and organization, not for each Claude account, and **Sign out** doesn't delete it. Members of your organization who share a computer login see each other's conversations. If people must share a login, ask each person to choose **Sign out** from the account menu when they finish, so that the next person signs in with their own Claude account.
from line 315
319315
320316If your fleet gets its Claude Desktop configuration from [MDM](/docs/third-party/claude-desktop/mdm), a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), or the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), you can move it to the admin console and keep your inference provider, unless that provider is the [Claude API](#limitations). Users' earlier work [stays on each device](#where-your-data-goes). The app copies that work on the same device so it appears under your organization. Try these steps on a test device first.
321317
322<Steps>
323 <Step title="Import your configuration">
324 Upload your current configuration, as described under [Start from an existing configuration file](#start-from-an-existing-configuration-file). Put settings that differ between groups of users in [per-group permission policies](#per-group-permission-policies).
325 </Step>
318**1. Import your configuration**
326319
327 <Step title="Finish the configuration before users sign in">
328 Set every setting you rely on in the console, because the console's configuration replaces the profile's. Add your [plugin marketplaces](#plugin-marketplaces) on the **Plugins** page. To migrate users' work, check that the **Automatically import earlier third-party sessions** switch under **Claude.ai data import** on the **Connectors** page is on (the default). To skip the migration, turn it off. Devices that already migrated keep their items.
320Upload your current configuration, as described under [Start from an existing configuration file](#start-from-an-existing-configuration-file). Put settings that differ between groups of users in [per-group permission policies](#per-group-permission-policies).
329321
330 <Warning>
331 The app migrates users' work once on each device, the next time it starts after the user signs in to your organization. It skips uploaded plugins, saved skills, and scheduled tasks if the console has turned that feature off, and optional plugins that your organization doesn't offer yet. Changing those settings later doesn't migrate the skipped items.
332 </Warning>
333 </Step>
322**2. Finish the configuration before users sign in**
334323
335 <Step title="Update Claude Desktop">
336 Update devices to Claude Desktop 2.42304.0 or later. Earlier releases migrate fewer items.
337 </Step>
324Set every setting you rely on in the console, because the console's configuration replaces the profile's. Add your [plugin marketplaces](#plugin-marketplaces) on the **Plugins** page. To migrate users' work, check that the **Automatically import earlier third-party sessions** switch under **Claude.ai data import** on the **Connectors** page is on (the default). To skip the migration, turn it off. Devices that already migrated keep their items.
338325
339 <Step title="Remove the managed profile">
340 Remove the Claude Desktop configuration profile or registry policy, including one that carries only bootstrap keys. You can keep a profile that sets only the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence).
326> [!WARNING]
327>
328> The app migrates users' work once on each device, the next time it starts after the user signs in to your organization. It skips uploaded plugins, saved skills, and scheduled tasks if the console has turned that feature off, and optional plugins that your organization doesn't offer yet. Changing those settings later doesn't migrate the skipped items.
341329
342 * **Devices that keep a profile with any other key**: see [Devices with a managed profile](#devices-with-a-managed-profile)
343 * **Devices configured in the app**: the user signs out and chooses the Anthropic sign-in option, as described under [Single-machine setup](/docs/third-party/claude-desktop/installation#single-machine-setup)
344 </Step>
330**3. Update Claude Desktop**
345331
346 <Step title="Have users sign in">
347 Have users sign in to Claude with their work email address and restart the app when asked, as described under [Onboard users](#onboard-users).
348 </Step>
349</Steps>
332Update devices to Claude Desktop 2.42304.0 or later. Earlier releases migrate fewer items.
350333
334**4. Remove the managed profile**
335
336Remove the Claude Desktop configuration profile or registry policy, including one that carries only bootstrap keys. You can keep a profile that sets only the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence).
337
338* **Devices that keep a profile with any other key**: see [Devices with a managed profile](#devices-with-a-managed-profile)
339* **Devices configured in the app**: the user signs out and chooses the Anthropic sign-in option, as described under [Single-machine setup](/docs/third-party/claude-desktop/installation#single-machine-setup)
340
341**5. Have users sign in**
342
343Have users sign in to Claude with their work email address and restart the app when asked, as described under [Onboard users](#onboard-users).
344
351345### What is migrated
352346
353347The app migrates these items in the background. The originals stay in place, so migrated sessions use disk space a second time.
from line 418
424418
425419For the macOS and Windows locations where the app reads a managed profile's keys, see [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration).
426420
427<Warning>
428 On a device that uses the admin console, adding either key to a profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) changes which settings apply. See [Which settings apply on a device with a managed profile](#which-settings-apply-on-a-device-with-a-managed-profile). With `disableDeploymentModeChooser` set to `true`, the profile becomes the device's whole configuration, and the device stops using the admin console. To require members who also belong to another organization to switch to yours, leave such a profile as it is and turn on [**Require this organization in Claude Desktop**](#users-in-more-than-one-claude-organization).
429</Warning>
421> [!WARNING]
422>
423> On a device that uses the admin console, adding either key to a profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) changes which settings apply. See [Which settings apply on a device with a managed profile](#which-settings-apply-on-a-device-with-a-managed-profile). With `disableDeploymentModeChooser` set to `true`, the profile becomes the device's whole configuration, and the device stops using the admin console. To require members who also belong to another organization to switch to yours, leave such a profile as it is and turn on [**Require this organization in Claude Desktop**](#users-in-more-than-one-claude-organization).
430424
431425## Remove users or return to MDM
432426
from line 428
434428
435429When you remove a user from the organization, Anthropic revokes their Claude Desktop sign-in to that organization. A running app isn't interrupted. At its next launch the app can no longer download the organization's configuration. It shows either your organization's sign-in screen, where **Return to Claude.ai sign-in** returns the device to standard Claude Desktop, or a **Restart required** prompt whose **Restart** button does the same.
436430
437<Note>
438 Removing a user doesn't end their access to your inference provider. To stop model requests from an app that is still running, also end their access at your provider or identity provider.
439</Note>
431> [!NOTE]
432>
433> Removing a user doesn't end their access to your inference provider. To stop model requests from an app that is still running, also end their access at your provider or identity provider.
440434
441435To return a whole fleet to [MDM](/docs/third-party/claude-desktop/mdm) or [bootstrap](/docs/third-party/claude-desktop/bootstrap) delivery, deploy the profile again with [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) set to `true`. The device returns to the profile's configuration at the app's next launch. From Claude Desktop 1.46388.1, a running app also notices the profile or policy at its next configuration re-check and asks the user to relaunch. To move a fleet to standard Claude Desktop instead, deploy a profile of standard Claude Desktop keys that sets [`forceLoginOrgUUID`](/docs/cowork/hipaa-setup#what-each-claude-desktop-key-does) to another organization's ID, the one your users move to.
442436
443<Warning>
444 Keep `disableDeploymentModeChooser` (or, for standard Claude Desktop, `forceLoginOrgUUID`) in the profile. On Claude Desktop 2.37337.0 or later, without the key the device goes back to the admin console's configuration at its next launch, without asking the user. If the user's sign-in to your organization has expired or you removed the user, the app shows your organization's sign-in screen or a **Restart required** prompt instead.
437> [!WARNING]
438>
439> Keep `disableDeploymentModeChooser` (or, for standard Claude Desktop, `forceLoginOrgUUID`) in the profile. On Claude Desktop 2.37337.0 or later, without the key the device goes back to the admin console's configuration at its next launch, without asking the user. If the user's sign-in to your organization has expired or you removed the user, the app shows your organization's sign-in screen or a **Restart required** prompt instead.
440>
441> A device that left the admin console's configuration on an earlier release goes back too, so add `disableDeploymentModeChooser` to the profile before devices update. A key that you add later takes effect at the device's next launch.
445442
446 A device that left the admin console's configuration on an earlier release goes back too, so add `disableDeploymentModeChooser` to the profile before devices update. A key that you add later takes effect at the device's next launch.
447</Warning>
448
449443Conversations created under the admin console's configuration stay on the device but no longer appear in the app's history after the device returns to the profile. Users can bring them into the app's history from **Settings → Import & export** in the app, as described under [Open the import wizard](/docs/third-party/claude-desktop/import#open-the-import-wizard), after you set the [`claudeAiImport`](/docs/third-party/claude-desktop/configuration#claudeaiimport) key with `enabled` set to `true` in the profile or policy you deploy.
450444
451445## Manage the configuration with the Admin API
from line 496
502496
503497A write goes through the same server checks as a save in the admin console, but the console checks more before it saves, for example that the connection to your inference provider is complete. A write can therefore store a connection that users' apps can't use. Put every setting your provider requires in `config`, including [how users authenticate](#choose-how-users-authenticate-to-your-provider), so that users' apps can pick up the change as described under [Configuration updates](#configuration-updates). Owners receive the email alert described there when a write changes where users' apps connect or sign in, what can run on their devices, or the `status`. In place of an administrator, the alert names the key by its ID (`apikey_…`).
504498
505<Warning>
506 Setting `status` to `disabled` stops serving the configuration to users' apps, as if none had been saved. A running app isn't interrupted. At its next launch it shows a **Restart required** prompt whose **Restart** button returns the device to standard Claude Desktop, signed out. New sign-ins also stay in standard Claude Desktop. To serve the configuration again, set `status` back to `active` with another API write, or open **Organization settings**, go to the **Connection** page under **Desktop 3P**, and click **Turn on** in the banner at the top of the page. After that, users who clicked **Restart** sign in again as described under [Onboard users](#onboard-users).
507</Warning>
499> [!WARNING]
500>
501> Setting `status` to `disabled` stops serving the configuration to users' apps, as if none had been saved. A running app isn't interrupted. At its next launch it shows a **Restart required** prompt whose **Restart** button returns the device to standard Claude Desktop, signed out. New sign-ins also stay in standard Claude Desktop. To serve the configuration again, set `status` back to `active` with another API write, or open **Organization settings**, go to the **Connection** page under **Desktop 3P**, and click **Turn on** in the banner at the top of the page. After that, users who clicked **Restart** sign in again as described under [Onboard users](#onboard-users).
508502
509503### Admin API errors
510504
third-party/claude-desktop/bedrock Changed · +57 / -61 lines
from line 24
2424
2525These steps are performed once per AWS organization, regardless of which authentication approach you chose. You need an AWS account with permission to manage Amazon Bedrock model access and IAM Identity Center.
2626
27<Steps>
28 <Step title="Enable Claude models in Amazon Bedrock">
29 In the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), open **Model access** and request access to the Claude models you intend to deploy. Access is granted per region, so enable the models in the same region you will set as `inferenceBedrockRegion`.
30 </Step>
27**1. Enable Claude models in Amazon Bedrock**
3128
32 <Step title="Create an IAM Identity Center permission set">
33 Skip this step if you chose the bearer-token or identity provider sign-in approach. The named-profile and in-app AWS sign-in approaches both use IAM Identity Center to issue per-user AWS credentials.
29In the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), open **Model access** and request access to the Claude models you intend to deploy. Access is granted per region, so enable the models in the same region you will set as `inferenceBedrockRegion`.
3430
35 In the [IAM Identity Center console](https://console.aws.amazon.com/singlesignon/), create a permission set with an inline policy that allows Amazon Bedrock inference. The minimal policy is:
31**2. Create an IAM Identity Center permission set**
3632
37 ```json theme={null}
38 {
39 "Version": "2012-10-17",
40 "Statement": [{
41 "Effect": "Allow",
42 "Action": [
43 "bedrock:InvokeModel",
44 "bedrock:InvokeModelWithResponseStream"
45 ],
46 "Resource": "*"
47 }]
48 }
49 ```
33Skip this step if you chose the bearer-token or identity provider sign-in approach. The named-profile and in-app AWS sign-in approaches both use IAM Identity Center to issue per-user AWS credentials.
5034
51 Set the permission set's **Session duration** to between 8 and 12 hours. This value sets how long each set of temporary AWS credentials lasts before the app requests a new set from IAM Identity Center. It does not control how often users sign in. Sign-in frequency follows the access portal session duration, described under [What users experience](#what-users-experience).
52 </Step>
35In the [IAM Identity Center console](https://console.aws.amazon.com/singlesignon/), create a permission set with an inline policy that allows Amazon Bedrock inference. The minimal policy is:
5336
54 <Step title="Federate Identity Center to your IdP (optional)">
55 If your organization uses Microsoft Entra ID, Okta, or another SAML identity provider, you can configure it as the identity source for IAM Identity Center so users sign in with their existing corporate credentials. The per-device steps on this page are unchanged. See [Connect to an external identity provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) in the AWS documentation.
56 </Step>
37```json theme={null}
38{
39 "Version": "2012-10-17",
40 "Statement": [{
41 "Effect": "Allow",
42 "Action": [
43 "bedrock:InvokeModel",
44 "bedrock:InvokeModelWithResponseStream"
45 ],
46 "Resource": "*"
47 }]
48}
49```
5750
58 <Step title="Assign users to the permission set">
59 In IAM Identity Center, assign the permission set to the AWS account that hosts Amazon Bedrock, and add the users or groups who should have access.
60 </Step>
51Set the permission set's **Session duration** to between 8 and 12 hours. This value sets how long each set of temporary AWS credentials lasts before the app requests a new set from IAM Identity Center. It does not control how often users sign in. Sign-in frequency follows the access portal session duration, described under [What users experience](#what-users-experience).
6152
62 <Step title="Record the values you need for device configuration">
63 From the IAM Identity Center **Settings** page, note:
53**3. Federate Identity Center to your IdP (optional)**
6454
65 * **AWS access portal URL**: of the form `https://d-xxxxxxxxxx.awsapps.com/start` (or your custom subdomain)
66 * **Identity Center region**: the region where Identity Center is enabled, which may differ from your Amazon Bedrock region
67 * **AWS account ID**: the 12-digit ID of the account where you enabled Amazon Bedrock
68 * **Permission set name**: the name you gave the permission set above
69 </Step>
70</Steps>
55If your organization uses Microsoft Entra ID, Okta, or another SAML identity provider, you can configure it as the identity source for IAM Identity Center so users sign in with their existing corporate credentials. The per-device steps on this page are unchanged. See [Connect to an external identity provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) in the AWS documentation.
7156
57**4. Assign users to the permission set**
58
59In IAM Identity Center, assign the permission set to the AWS account that hosts Amazon Bedrock, and add the users or groups who should have access.
60
61**5. Record the values you need for device configuration**
62
63From the IAM Identity Center **Settings** page, note:
64
65* **AWS access portal URL**: of the form `https://d-xxxxxxxxxx.awsapps.com/start` (or your custom subdomain)
66* **Identity Center region**: the region where Identity Center is enabled, which may differ from your Amazon Bedrock region
67* **AWS account ID**: the 12-digit ID of the account where you enabled Amazon Bedrock
68* **Permission set name**: the name you gave the permission set above
69
7270## Prepare devices
7371
7472What each end-user device needs depends on the authentication approach you chose.
from line 188
190188
191189| Setting | Type | Availability | Default | Description |
192190| - | - | - | - | - |
193| <span id="inferencebedrockregion" />AWS region<br />`inferenceBedrockRegion` | `string` | MDM + Bootstrap<br />Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. |
194| <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. |
195| <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`. |
196| <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. |
197| <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. |
198| <span id="inferencebedrockssoregion" />AWS SSO region<br />`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap<br />Added in 1.6259.0 | — | IAM Identity Center home region. |
199| <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. |
200| <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. |
201| <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. |
202| <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. |
203| <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. |
191| AWS region `inferenceBedrockRegion` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. |
192| Bedrock base URL `inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. |
193| 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`. |
194| 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. |
195| 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. |
196| AWS SSO region `inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap Added in 1.6259.0 | — | IAM Identity Center home region. |
197| 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. |
198| 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. |
199| AWS profile name `inferenceBedrockProfile` | `string` | MDM + Bootstrap Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. |
200| 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. |
201| 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. |
204202
205<AccordionGroup>
206 <Accordion title="inferenceBedrockServiceTier details">
207 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.
208 </Accordion>
209</AccordionGroup>
203> **inferenceBedrockServiceTier details**
204>
205> 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.
210206
211207Set `inferenceModels` to a list of Amazon Bedrock inference-profile IDs, for example `us.anthropic.claude-sonnet-5`. When using a bearer token or credential helper, Claude Desktop auto-discovers available Claude models from your account if this is unset; otherwise the list is required. Application-inference-profile ARNs and provisioned-throughput ARNs are also accepted; pair them with a [`labelOverride`](/docs/third-party/claude-desktop/configuration#inferencemodels) so the picker shows a readable name instead of the raw ARN. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
212208
third-party/claude-desktop/bootstrap Changed · +148 / -156 lines
from line 2
22
33> Host an HTTPS endpoint that returns each user's configuration, for organizations without MDM or with role-based configuration too complex for per-group profiles
44
5<Note>
6 Requires Claude Desktop **1.10628.0** or later. Earlier builds ignore the `bootstrapUrl` keys.
7</Note>
5> [!NOTE]
6>
7> Requires Claude Desktop **1.10628.0** or later. Earlier builds ignore the `bootstrapUrl` keys.
88
99A **bootstrap server** is an HTTPS endpoint you host that authenticates each user against your identity provider and returns that user's configuration as JSON. Use it when your organization doesn't have MDM, or when configuration varies too widely for per-group profiles: per-user gateway credentials, per-team model allowlists, or per-user OpenTelemetry attribution. When one configuration or a few group-scoped profiles cover your fleet, [deploying with MDM](/docs/third-party/claude-desktop/mdm) is simpler; most MDMs support role-based distribution.
1010
1111When a bootstrap response is available, it **is** the effective configuration. The MDM profile supplies the trust anchor (`bootstrapUrl`, optional `bootstrapOidc` or `bootstrapHeaders`/`bootstrapHeadersHelper`, and the `bootstrapEnabled` opt-out), and Claude Desktop does not consult MDM for any key the bootstrap server is permitted to set. A bootstrap-settable key that your response **omits** is treated as unset, not inherited from MDM, so return every key you want applied.
1212
13<Warning>
14 Your bootstrap server is fully trusted. Its response can set inference credentials, the egress allowlist, MCP servers, and every other key in the [published schema](#response-schema). Treat compromise of this endpoint as credential compromise: restrict who can deploy it, log every response, and harden it as you would any secrets-issuing service.
15</Warning>
13> [!WARNING]
14>
15> Your bootstrap server is fully trusted. Its response can set inference credentials, the egress allowlist, MCP servers, and every other key in the [published schema](#response-schema). Treat compromise of this endpoint as credential compromise: restrict who can deploy it, log every response, and harden it as you would any secrets-issuing service.
1616
1717Before the server can take over, each device needs the bootstrap keys that point at it. There are two ways to get them onto a device:
1818
from line 145
145145
146146### Separate identity provider (PKCE)
147147
148<Steps>
149 <Step title="Register a public client in your identity provider">
150 Register a native or public application with a loopback redirect URI and no client secret. The registration is identical to the one used for [gateway single sign-on](/docs/third-party/claude-desktop/gateway#set-up-single-sign-on); if you already have that, reuse it. See the [provider notes](#provider-notes) below for redirect-URI specifics.
148**1. Register a public client in your identity provider**
151149
152 For Microsoft Entra ID, also set an **Application ID URI** on the registration (App registration → **Expose an API** → **Set**; accept the default `api://CLIENT_ID`). The `CLIENT_ID/.default` scope in the next step does not resolve without it.
153 </Step>
150Register a native or public application with a loopback redirect URI and no client secret. The registration is identical to the one used for [gateway single sign-on](/docs/third-party/claude-desktop/gateway#set-up-single-sign-on); if you already have that, reuse it. See the [provider notes](#provider-notes) below for redirect-URI specifics.
154151
155 <Step title="Choose the scope your server will validate">
156 The app sends the OAuth **access token** as the bearer. Your server validates that token's `aud`, so the scope you request must produce a token whose audience your server accepts. This is provider-specific:
152For Microsoft Entra ID, also set an **Application ID URI** on the registration (App registration → **Expose an API** → **Set**; accept the default `api://CLIENT_ID`). The `CLIENT_ID/.default` scope in the next step does not resolve without it.
157153
158 | Provider | Scope to request | Resulting `aud` |
159 | - | - | - |
160 | Microsoft Entra ID | `openid offline_access CLIENT_ID/.default` | your client ID |
161 | Okta (custom authorization server) | `openid offline_access YOUR_API_SCOPE` | your authorization server's audience |
162 | Generic OIDC | `openid offline_access` plus your API's resource scope | provider-specific |
154**2. Choose the scope your server will validate**
163155
164 Include `offline_access` so the app receives a refresh token and can renew silently between launches.
156The app sends the OAuth **access token** as the bearer. Your server validates that token's `aud`, so the scope you request must produce a token whose audience your server accepts. This is provider-specific:
165157
166 <Warning>
167 For Entra, use the bare-GUID form `CLIENT_ID/.default`, **not** `api://CLIENT_ID/.default`. The `api://` form works on the initial authorize but fails on the refresh grant with `AADSTS90009` when the client and resource are the same application.
168 </Warning>
169 </Step>
158| Provider | Scope to request | Resulting `aud` |
159| - | - | - |
160| Microsoft Entra ID | `openid offline_access CLIENT_ID/.default` | your client ID |
161| Okta (custom authorization server) | `openid offline_access YOUR_API_SCOPE` | your authorization server's audience |
162| Generic OIDC | `openid offline_access` plus your API's resource scope | provider-specific |
170163
171 <Step title="Validate the token in your server">
172 See [Server responsibilities](#server-responsibilities). What the token's `iss` and `aud` look like depends on your provider:
164Include `offline_access` so the app receives a refresh token and can renew silently between launches.
173165
174 | Provider | `iss` to expect | `aud` to expect | JWKS URL |
175 | - | - | - | - |
176 | Microsoft Entra ID (token version `2`) | `https://login.microsoftonline.com/TENANT/v2.0` | your client ID | `https://login.microsoftonline.com/TENANT/discovery/v2.0/keys` |
177 | Okta (custom authorization server) | `https://YOUR_DOMAIN.okta.com/oauth2/AUTH_SERVER_ID` | the audience configured on that authorization server | `<issuer>/v1/keys` |
166> [!WARNING]
167>
168> For Entra, use the bare-GUID form `CLIENT_ID/.default`, **not** `api://CLIENT_ID/.default`. The `api://` form works on the initial authorize but fails on the refresh grant with `AADSTS90009` when the client and resource are the same application.
178169
179 **Entra token version.** A new Entra app registration emits v1-format access tokens by default, with `iss` = `https://sts.windows.net/TENANT/` and `aud` = `api://CLIENT_ID`. Set the accepted-token-version field in the registration's **Manifest** to `2` so tokens match the table above. The portal shows this field as either `accessTokenAcceptedVersion` or `api.requestedAccessTokenVersion` depending on the manifest view; set whichever you see. If you cannot change it, your server must accept both the v1 and v2 forms.
170**3. Validate the token in your server**
180171
181 **Group and role claims.** Entra does not emit `groups` or `roles` in access tokens by default. Enable the groups claim under App registration → **Token configuration**, or define **App roles** and assign users via **Enterprise applications**. The `oid` claim is always present. For Okta, add a `groups` claim on your custom authorization server with a group filter.
182 </Step>
172See [Server responsibilities](#server-responsibilities). What the token's `iss` and `aud` look like depends on your provider:
183173
184 <Step title="Configure and export from Claude Desktop">
185 Install Claude Desktop on an admin workstation (see [Installation](/docs/third-party/claude-desktop/installation)). From the menu bar, open **Developer → Configure Third-Party Inference…**. In the **Source** section, fill in the **Bootstrap config URL** card:
174| Provider | `iss` to expect | `aud` to expect | JWKS URL |
175| - | - | - | - |
176| Microsoft Entra ID (token version `2`) | `https://login.microsoftonline.com/TENANT/v2.0` | your client ID | `https://login.microsoftonline.com/TENANT/discovery/v2.0/keys` |
177| Okta (custom authorization server) | `https://YOUR_DOMAIN.okta.com/oauth2/AUTH_SERVER_ID` | the audience configured on that authorization server | `<issuer>/v1/keys` |
186178
187 | Field | Value |
188 | - | - |
189 | Bootstrap config URL | `https://YOUR_BOOTSTRAP_HOST/user/bootstrap` |
190 | Bootstrap OIDC parameters → Client ID | `YOUR_CLIENT_ID` |
191 | Bootstrap OIDC parameters → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` |
192 | Bootstrap OIDC parameters → Scopes | `openid offline_access YOUR_CLIENT_ID/.default` |
193 | Bootstrap OIDC parameters → Redirect port | leave empty for Entra; set for Okta |
179**Entra token version.** A new Entra app registration emits v1-format access tokens by default, with `iss` = `https://sts.windows.net/TENANT/` and `aud` = `api://CLIENT_ID`. Set the accepted-token-version field in the registration's **Manifest** to `2` so tokens match the table above. The portal shows this field as either `accessTokenAcceptedVersion` or `api.requestedAccessTokenVersion` depending on the manifest view; set whichever you see. If you cannot change it, your server must accept both the v1 and v2 forms.
194180
195 Click **Sign in** to test against your typed values. Once authenticated, the card shows the keys your server supplied. Click **Export** and choose the template format your MDM expects (such as `.mobileconfig`, ADMX, or `.reg`). See [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) for per-platform instructions.
196 </Step>
197</Steps>
181**Group and role claims.** Entra does not emit `groups` or `roles` in access tokens by default. Enable the groups claim under App registration → **Token configuration**, or define **App roles** and assign users via **Enterprise applications**. The `oid` claim is always present. For Okta, add a `groups` claim on your custom authorization server with a group filter.
198182
183**4. Configure and export from Claude Desktop**
184
185Install Claude Desktop on an admin workstation (see [Installation](/docs/third-party/claude-desktop/installation)). From the menu bar, open **Developer → Configure Third-Party Inference…**. In the **Source** section, fill in the **Bootstrap config URL** card:
186
187| Field | Value |
188| - | - |
189| Bootstrap config URL | `https://YOUR_BOOTSTRAP_HOST/user/bootstrap` |
190| Bootstrap OIDC parameters → Client ID | `YOUR_CLIENT_ID` |
191| Bootstrap OIDC parameters → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` |
192| Bootstrap OIDC parameters → Scopes | `openid offline_access YOUR_CLIENT_ID/.default` |
193| Bootstrap OIDC parameters → Redirect port | leave empty for Entra; set for Okta |
194
195Click **Sign in** to test against your typed values. Once authenticated, the card shows the keys your server supplied. Click **Export** and choose the template format your MDM expects (such as `.mobileconfig`, ADMX, or `.reg`). See [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) for per-platform instructions.
196
199197#### Provider notes
200198
201199| Provider | Redirect URI to register | Redirect port field | Additional setup |
from line 210
212210
213211Set only `bootstrapUrl` in MDM. The app discovers your authorization endpoints via RFC 8414 and runs an RFC 8628 device-code grant. The bearer is reused for inference when `inferenceGatewayBaseUrl` shares the `bootstrapUrl` origin and `inferenceCredentialKind` is `interactive`, so the user signs in once for both.
214212
215<Steps>
216 <Step title="Publish RFC 8414 discovery metadata">
217 Serve a metadata document under the `bootstrapUrl` path. If `bootstrapUrl` ends in `/bootstrap` or `/user/bootstrap`, that suffix is stripped to form the issuer base.
213**1. Publish RFC 8414 discovery metadata**
218214
219 ```text theme={null}
220 GET https://YOUR_BOOTSTRAP_HOST/.well-known/oauth-authorization-server
221 ```
215Serve a metadata document under the `bootstrapUrl` path. If `bootstrapUrl` ends in `/bootstrap` or `/user/bootstrap`, that suffix is stripped to form the issuer base.
222216
223 ```json theme={null}
224 {
225 "issuer": "https://YOUR_BOOTSTRAP_HOST",
226 "token_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/token",
227 "device_authorization_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/device"
228 }
229 ```
217```text theme={null}
218GET https://YOUR_BOOTSTRAP_HOST/.well-known/oauth-authorization-server
219```
230220
231 Every endpoint URL must share the `bootstrapUrl` origin. Metadata that points off-origin is rejected.
232 </Step>
221```json theme={null}
222{
223 "issuer": "https://YOUR_BOOTSTRAP_HOST",
224 "token_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/token",
225 "device_authorization_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/device"
226}
227```
233228
234 <Step title="Implement the device-code grant">
235 `POST` to `device_authorization_endpoint` returns:
229Every endpoint URL must share the `bootstrapUrl` origin. Metadata that points off-origin is rejected.
236230
237 ```json theme={null}
238 {
239 "device_code": "EXAMPLE-DEVICE-CODE-OPAQUE-TO-CLIENT",
240 "user_code": "ABCD-EFGH",
241 "verification_uri": "https://YOUR_BOOTSTRAP_HOST/activate",
242 "verification_uri_complete": "https://YOUR_BOOTSTRAP_HOST/activate?user_code=ABCD-EFGH",
243 "interval": 5,
244 "expires_in": 600
245 }
246 ```
231**2. Implement the device-code grant**
247232
248 `verification_uri` and `verification_uri_complete` must share the `bootstrapUrl` origin; federate behind your own pages rather than returning an upstream provider's URL directly. The app opens the verification URL in the user's browser and shows the user code.
233`POST` to `device_authorization_endpoint` returns:
249234
250 The app polls `token_endpoint` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` and the `device_code`. Return `{"error":"authorization_pending"}` until the user approves, then:
235```json theme={null}
236{
237 "device_code": "EXAMPLE-DEVICE-CODE-OPAQUE-TO-CLIENT",
238 "user_code": "ABCD-EFGH",
239 "verification_uri": "https://YOUR_BOOTSTRAP_HOST/activate",
240 "verification_uri_complete": "https://YOUR_BOOTSTRAP_HOST/activate?user_code=ABCD-EFGH",
241 "interval": 5,
242 "expires_in": 600
243}
244```
251245
252 ```json theme={null}
253 { "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 3600 }
254 ```
246`verification_uri` and `verification_uri_complete` must share the `bootstrapUrl` origin; federate behind your own pages rather than returning an upstream provider's URL directly. The app opens the verification URL in the user's browser and shows the user code.
255247
256 The polling interval is clamped between 1 and 30 seconds; the grant times out after 5 minutes; the token lifetime you return is clamped between 5 minutes and 30 days (24 hours before 1.17377.1).
248The app polls `token_endpoint` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` and the `device_code`. Return `{"error":"authorization_pending"}` until the user approves, then:
257249
258 When `inferenceGatewayBaseUrl` shares the `bootstrapUrl` origin, so the same sign-in also serves inference, you may also return a `refresh_token` (optionally with `refresh_token_expires_in` in seconds): as the access token nears expiry during use, Claude Desktop 1.34493.0 and later renews it with an RFC 6749 `grant_type=refresh_token` POST to your `token_endpoint` rather than interrupting the user. The configuration fetch at launch still asks the user to sign in if the access token itself has already expired. Answer `400` with `{"error":"invalid_grant"}` to revoke the refresh token and require a fresh sign-in.
259 </Step>
250```json theme={null}
251{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 3600 }
252```
260253
261 <Step title="Serve the configuration endpoint">
262 On `GET <bootstrapUrl>` with a valid bearer, look up the user from the token claims and return their configuration (see [the HTTP contract](#the-http-contract)).
263 </Step>
264</Steps>
254The polling interval is clamped between 1 and 30 seconds; the grant times out after 5 minutes; the token lifetime you return is clamped between 5 minutes and 30 days (24 hours before 1.17377.1).
265255
256When `inferenceGatewayBaseUrl` shares the `bootstrapUrl` origin, so the same sign-in also serves inference, you may also return a `refresh_token` (optionally with `refresh_token_expires_in` in seconds): as the access token nears expiry during use, Claude Desktop 1.34493.0 and later renews it with an RFC 6749 `grant_type=refresh_token` POST to your `token_endpoint` rather than interrupting the user. The configuration fetch at launch still asks the user to sign in if the access token itself has already expired. Answer `400` with `{"error":"invalid_grant"}` to revoke the refresh token and require a fresh sign-in.
257
258**3. Serve the configuration endpoint**
259
260On `GET <bootstrapUrl>` with a valid bearer, look up the user from the token claims and return their configuration (see [the HTTP contract](#the-http-contract)).
261
266262### Request headers (no per-user sign-in)
267263
268264Requires Claude Desktop 1.32885.1 or later. Set `bootstrapHeaders` to a JSON object of headers to send on every bootstrap fetch, or `bootstrapHeadersHelper` to the absolute path of an executable that prints such an object on stdout (run with no arguments; its output is cached for a few minutes and merged over the static headers, the helper winning on a conflict). When either key is set and `bootstrapOidc` is not, the app treats the headers as sufficient authentication and fetches the configuration without prompting the user to sign in. If your server answers `401` or `403`, the app discards the cached helper output so the next fetch (the next background check, or a relaunch) re-runs the helper. At launch the app also shows a sign-in prompt; that sign-in succeeds only if your server implements the [device-code grant](#bootstrap-server-as-authorization-server-device-code), so a headers-only server should return `401`/`403` only for a genuinely unusable credential. A `401`/`403` on a background check keeps the running configuration and retries at the next check without prompting. A signed-in user's bearer token replaces any `Authorization` header you configured. Both keys are read from device management or the local configuration file only, never from the bootstrap response, and header values are masked in the diagnostic report. [Origin pinning](#origin-pinning) applies in this mode exactly as in device-code mode. Use this instead of embedding `user:password@` in `bootstrapUrl`, which the app refuses.
from line 302
306302| `401`, `403` | Discard the cached token and prompt the user to sign in again. A `401` on a background refresh keeps the running configuration. When the same sign-in also serves inference, the app treats it as an ended session and asks the user to sign in again (1.34493.0 and later); otherwise it retries at the next check without prompting. Return `401` when the token is missing, expired, or the wrong audience; return `403` when the token is valid but the caller is not entitled. |
307303| Other non-2xx, or `3xx` | Fetch error. Falls back to the last good response from this session if one exists; otherwise the app stays in the degraded sign-in state. |
308304
309<Warning>
310 A `200` that is not a JSON object (an empty body, an HTML page from a captive portal or load balancer, or a JSON array) is a parse error. Make sure intermediate proxies do not rewrite the response.
311</Warning>
305> [!WARNING]
306>
307> A `200` that is not a JSON object (an empty body, an HTML page from a captive portal or load balancer, or a JSON array) is a parse error. Make sure intermediate proxies do not rewrite the response.
312308
313309### Response schema
314310
from line 319
323319
324320The response can supply any key in that schema, including inference credentials, model allowlists, MCP servers, the egress allowlist, telemetry endpoints, and the organization banner.
325321
326<Note>
327 Organization plugins and skills can be delivered over the network by returning `allowedPluginMarketplaces` in the bootstrap response (see [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin)), or through the filesystem `org-plugins/` directory described in [Connectors and extensions](/docs/third-party/claude-desktop/extensions).
328</Note>
322> [!NOTE]
323>
324> Organization plugins and skills can be delivered over the network by returning `allowedPluginMarketplaces` in the bootstrap response (see [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin)), or through the filesystem `org-plugins/` directory described in [Connectors and extensions](/docs/third-party/claude-desktop/extensions).
329325
330326A small set of keys are **structurally excluded** and ignored if returned:
331327
from line 357
361357| `$schemaVersion` | `integer` | Wire-format marker: `2` for the nested format (bootstrap-config-v2, what the app's own JSON export writes), `1` for the flat format (bootstrap-config-v1). Optional: the client infers the format from the document shape; set it to state the format explicitly. |
362358| `expiresAt` | `number` | Unix epoch (seconds or milliseconds) after which the client should re-fetch this document. Optional; when absent the client uses its default refresh interval. |
363359
364<AccordionGroup>
365 <Accordion title="$schemaVersion details">
366 Omitted → the client infers the version from the document shape (any cluster key present → 2, otherwise 1).
367 </Accordion>
360> **\$schemaVersion details**
361>
362> Omitted → the client infers the version from the document shape (any cluster key present → 2, otherwise 1).
368363
369 <Accordion title="expiresAt details">
370 Omitted → cache for 1 hour. A number ≥ 10¹² is read as Unix epoch **milliseconds**; below that, **seconds**.
364> **expiresAt details**
365>
366> Omitted → cache for 1 hour. A number ≥ 10¹² is read as Unix epoch **milliseconds**; below that, **seconds**.
367>
368> A failed re-fetch keeps the last good response from the current session and retries; the app only enters the degraded state when there has never been a usable response this session.
371369
372 A failed re-fetch keeps the last good response from the current session and retries; the app only enters the degraded state when there has never been a usable response this session.
373 </Accordion>
374</AccordionGroup>
375
376370### Origin pinning
377371
378372When no `bootstrapOidc` is set (device-code or request-headers mode), the response is fenced: `inferenceGatewayBaseUrl`, `inferenceVertexBaseUrl`, `inferenceBedrockBaseUrl`, and `inferenceFoundryBaseUrl` must share the `bootstrapUrl` origin or the field is dropped. A compromised configuration response cannot redirect inference to an attacker-controlled host because the only host it can name is your bootstrap server's own origin.
from line 377
383377
384378| Setting | Type | Availability | Default | Description |
385379| - | - | - | - | - |
386| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only<br />Added in 1.10628.0 | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. |
387| <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only<br />Added in 1.10628.0 | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. |
388| <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only<br />Added in 1.10628.0 | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). |
389| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only<br />Added in 1.32885.1 | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. |
390| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only<br />Added in 1.32885.1 | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. |
391| <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only<br />Added in 1.26832.0 | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. |
380| Use bootstrap config `bootstrapEnabled` | `boolean` | MDM only Added in 1.10628.0 | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. |
381| Bootstrap config URL `bootstrapUrl` | `string` | MDM only Added in 1.10628.0 | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. |
382| Bootstrap OIDC parameters `bootstrapOidc` | `object` | MDM only Added in 1.10628.0 | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). |
383| Bootstrap request headers `bootstrapHeaders` | `object` | MDM only Added in 1.32885.1 | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. |
384| Bootstrap headers helper script `bootstrapHeadersHelper` | `string` | MDM only Added in 1.32885.1 | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. |
385| Trust bootstrap-delivered settings `trustBootstrapDelivery` | `boolean` | MDM only Added in 1.26832.0 | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. |
392386
393<AccordionGroup>
394 <Accordion title="bootstrapOidc details">
395 Set this to use a separate identity provider (Microsoft Entra ID, Okta, Ping, or any compliant OIDC provider) for the bootstrap sign-in. The app runs an authorization-code-with-PKCE flow in the system browser. Omit to use device-code mode against the bootstrap server's own origin.
387> **bootstrapOidc details**
388>
389> Set this to use a separate identity provider (Microsoft Entra ID, Okta, Ping, or any compliant OIDC provider) for the bootstrap sign-in. The app runs an authorization-code-with-PKCE flow in the system browser. Omit to use device-code mode against the bootstrap server's own origin.
390>
391> This is an **object-typed key** — in an MDM profile it is a single JSON-string value, not separate keys with dotted names like `bootstrapOidc.clientId`. Writing the sub-fields as separate registry values causes the app to silently fall through to device-code mode.
392>
393> | Field | Type | Default | Description |
394> | - | - | - | - |
395> | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
396> | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
397> | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
398> | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
399> | `scopes` | `string` | — | Space-separated; the token’s audience must match what your bootstrap server validates. |
400> | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
401> | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
402> | `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. |
396403
397 This is an **object-typed key** — in an MDM profile it is a single JSON-string value, not separate keys with dotted names like `bootstrapOidc.clientId`. Writing the sub-fields as separate registry values causes the app to silently fall through to device-code mode.
404> **bootstrapHeaders details**
405>
406> Static headers sent on every request to the bootstrap config URL — for a service-account credential (`Authorization: Basic …`, an API key header) or a routing/tenant header. When either this or the headers helper script is set and no separate `bootstrapOidc` provider is configured, the app treats the headers as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. These headers (and the helper script's below) also accompany requests to a plugin marketplace this server hosts on its own origin (`allowedPluginMarketplaces` with `credentialKind: "inferenceCredential"`). Header values are masked in diagnostics and telemetry. For a rotating token, use the headers helper script instead.
398407
399 | Field | Type | Default | Description |
400 | - | - | - | - |
401 | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
402 | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
403 | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
404 | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
405 | `scopes` | `string` | — | Space-separated; the token’s audience must match what your bootstrap server validates. |
406 | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. |
407 | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
408 | `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. |
409 </Accordion>
410
411 <Accordion title="bootstrapHeaders details">
412 Static headers sent on every request to the bootstrap config URL — for a service-account credential (`Authorization: Basic …`, an API key header) or a routing/tenant header. When either this or the headers helper script is set and no separate `bootstrapOidc` provider is configured, the app treats the headers as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. These headers (and the helper script's below) also accompany requests to a plugin marketplace this server hosts on its own origin (`allowedPluginMarketplaces` with `credentialKind: "inferenceCredential"`). Header values are masked in diagnostics and telemetry. For a rotating token, use the headers helper script instead.
413 </Accordion>
414
415 <Accordion title="bootstrapHeadersHelper details">
416 Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. `{"Authorization": "Bearer …"}`. The app runs it (no arguments; output cached for a few minutes) before each bootstrap config fetch and merges the result over **Bootstrap request headers** (the helper wins on conflict). Use this instead of embedding `user:pass@` in the bootstrap URL, or when the bootstrap server needs a rotating token from a secrets manager. When either this or the static headers are set and no separate `bootstrapOidc` provider is configured, the app treats them as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. If a per-user sign-in also runs (`bootstrapOidc` or the server’s own device-code flow), that Bearer token wins on `Authorization`.
417 </Accordion>
418</AccordionGroup>
408> **bootstrapHeadersHelper details**
409>
410> Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. `{"Authorization": "Bearer …"}`. The app runs it (no arguments; output cached for a few minutes) before each bootstrap config fetch and merges the result over **Bootstrap request headers** (the helper wins on conflict). Use this instead of embedding `user:pass@` in the bootstrap URL, or when the bootstrap server needs a rotating token from a secrets manager. When either this or the static headers are set and no separate `bootstrapOidc` provider is configured, the app treats them as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. If a per-user sign-in also runs (`bootstrapOidc` or the server’s own device-code flow), that Bearer token wins on `Authorization`.
419411
420412No `inferenceProvider` is needed in the MDM profile when using bootstrap; the response supplies it.
421413
third-party/claude-desktop/built-in-connectors Changed · +3 / -3 lines
from line 16
1616
1717Each guide covers its server in full, including how the built-in server compares with the remote alternative where one exists.
1818
19<Note>
20 In the in-app configuration window, the **Add server** menu lists built-in servers separately from remote templates. A remote template (Box, or the Microsoft 365 remote connector) only pre-fills the form for a server that runs outside the app. The servers on this page are the ones bundled inside the app.
21</Note>
19> [!NOTE]
20>
21> In the in-app configuration window, the **Add server** menu lists built-in servers separately from remote templates. A remote template (Box, or the Microsoft 365 remote connector) only pre-fills the form for a server that runs outside the app. The servers on this page are the ones bundled inside the app.
2222
2323## How built-in servers behave
2424
third-party/claude-desktop/chat Changed · +18 / -18 lines
from line 2
22
33> What Chat can and cannot do in Claude Desktop on 3P, and how to configure it
44
5<Note>
6 When [Unified Claude](/docs/third-party/claude-desktop/unified-claude) is on, a message sent from the home screen starts a Cowork session on a device that can run Cowork.
7</Note>
5> [!NOTE]
6>
7> When [Unified Claude](/docs/third-party/claude-desktop/unified-claude) is on, a message sent from the home screen starts a Cowork session on a device that can run Cowork.
88
99Chat in Claude Desktop on third-party (3P) is a conversational surface for quick questions and drafting. Unlike [Cowork](/docs/cowork/overview) and [Code](/docs/third-party/claude-desktop/code), which run agentic sessions with access to folders you grant and a code-execution environment, a Chat conversation runs with a deliberately small tool surface: it can search and fetch the web under your admin configuration, read files attached to the conversation, read and update the project's memory and read the files in the project's folders when the conversation is inside a project, write files into a scratch space of its own, and use skills from the plugins you provision, and nothing else on the machine. Chat is off by default and is enabled with a single configuration key.
1010
from line 61
6161
6262The data flow end to end: an attached file is copied into the conversation's local uploads directory, mounted read-only into the sandbox when analysis runs, and any outputs are written to the conversation's scratch directory on local disk. File content leaves the device only as conversation context sent to your configured inference provider, in web search queries to your configured search backend, through web fetches your egress allowlist permits, through [sandbox network access](#sandbox-network-access), in a connector tool call permitted by your `toolPolicy` configuration and the user's approvals, or, if you have enabled [content capture](/docs/third-party/claude-desktop/telemetry#content-capture), in telemetry to your own collector.
6363
64<Note>
65 Advanced file analysis uses the same shell tool as Cowork's sandbox, so adding `"Bash"` to `disabledBuiltinTools` disables it even when `chatAdvancedFileAnalysisEnabled` is `true`. Running it requires the sandbox VM bundle, which the app downloads from Anthropic unless you deployed the offline installer (see [required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths)).
66</Note>
64> [!NOTE]
65>
66> Advanced file analysis uses the same shell tool as Cowork's sandbox, so adding `"Bash"` to `disabledBuiltinTools` disables it even when `chatAdvancedFileAnalysisEnabled` is `true`. Running it requires the sandbox VM bundle, which the app downloads from Anthropic unless you deployed the offline installer (see [required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths)).
6767
6868### Sandbox network access
6969
from line 72
7272* **Other hosts.** A web request to any other host gets a `403 Forbidden` response with the header `X-Proxy-Error: blocked-by-allowlist`. `pip install` reports this as `Tunnel connection failed: 403 Forbidden`.
7373* **Package installs.** Package managers contact their default index, so list its hosts. For pip, list `pypi.org` and `files.pythonhosted.org`. To install from a private mirror, list its host. The command must name the mirror, for example with pip's `--index-url`.
7474
75<Warning>
76 By default, commands in the sandbox run without an approval prompt. A command can upload anything the sandbox can read to a listed host, and can run what it downloads from one. [Web fetch](/docs/third-party/claude-desktop/web-tools#web-fetch) in Chat uses the same list, so a host you list for web fetch is also open to sandbox commands. With `"*"` in the list, network filtering in the sandbox is off, so commands can reach any host.
75> [!WARNING]
76>
77> By default, commands in the sandbox run without an approval prompt. A command can upload anything the sandbox can read to a listed host, and can run what it downloads from one. [Web fetch](/docs/third-party/claude-desktop/web-tools#web-fetch) in Chat uses the same list, so a host you list for web fetch is also open to sandbox commands. With `"*"` in the list, network filtering in the sandbox is off, so commands can reach any host.
78>
79> * **To have Claude ask before each command**, set `"Bash"` to `"ask"` in [`builtinToolPolicy`](/docs/third-party/claude-desktop/configuration#builtintoolpolicy). That policy also applies to Cowork and Code sessions.
80> * **To keep web fetch but turn off sandbox commands**, set [`chatAdvancedFileAnalysisEnabled`](#configuration) to `false`.
7781
78 * **To have Claude ask before each command**, set `"Bash"` to `"ask"` in [`builtinToolPolicy`](/docs/third-party/claude-desktop/configuration#builtintoolpolicy). That policy also applies to Cowork and Code sessions.
79 * **To keep web fetch but turn off sandbox commands**, set [`chatAdvancedFileAnalysisEnabled`](#configuration) to `false`.
80</Warning>
82> [!NOTE]
83>
84> Sandbox network access requires Claude Desktop 2.42304.0 or later. On earlier versions, requests to listed hosts get a `403 Forbidden` response. After a device updates, commands can reach the listed hosts with no change to your configuration, in existing conversations too. If Claude says in an existing conversation that the sandbox has no network access, ask the user to start a new conversation.
8185
82<Note>
83 Sandbox network access requires Claude Desktop 2.42304.0 or later. On earlier versions, requests to listed hosts get a `403 Forbidden` response. After a device updates, commands can reach the listed hosts with no change to your configuration, in existing conversations too. If Claude says in an existing conversation that the sandbox has no network access, ask the user to start a new conversation.
84</Note>
85
8686## Configuration
8787
8888| Key | Default | Effect |
from line 94
9494
9595When `chatTabEnabled` is `true`, Claude Desktop presents Chat and Cowork together as **Home** in its sidebar, next to **Code**. From Home, the user chooses **Chat** or **Cowork** in the message box, and the sidebar lists chats and tasks together. When the key is unset or `false`, the sidebar shows **Cowork** in place of Home and the message box offers no choice. If [`coworkTabEnabled`](/docs/third-party/claude-desktop/configuration#coworktabenabled) is `false` while Chat is enabled, the message box offers Chat only.
9696
97<Note>
98 This layout applies to Claude Desktop 1.26832.0 and later. Earlier versions show **Chat** (when enabled), **Cowork**, and **Code** as separate tabs, controlled by the same keys.
99</Note>
97> [!NOTE]
98>
99> This layout applies to Claude Desktop 1.26832.0 and later. Earlier versions show **Chat** (when enabled), **Cowork**, and **Code** as separate tabs, controlled by the same keys.
100100
101101Enforcement of `chatTabEnabled` happens in the app's main process: when the key is unset or `false`, Chat does not appear in the app, and the app additionally refuses to start or continue a Chat conversation, including conversations created before an admin turned the key off.
102102
third-party/claude-desktop/claude-api Changed · +4 / -4 lines
from line 4
44
55To use Anthropic's Claude API directly as the inference provider, set [`inferenceProvider`](/docs/third-party/claude-desktop/configuration#inferenceprovider) to `anthropic` and choose how users authenticate, as described in [Choose an authentication approach](#choose-an-authentication-approach). This is the first-party path: inference goes straight to Anthropic rather than to a Claude deployment on Google Cloud's Agent Platform, Amazon Bedrock, or Microsoft Foundry.
66
7<Note>
8 When `inferenceProvider` is `anthropic`, inference traffic goes to Anthropic's API endpoints rather than staying within your cloud provider. The data-residency and compliance statements on these pages do not apply to this option.
9</Note>
7> [!NOTE]
8>
9> When `inferenceProvider` is `anthropic`, inference traffic goes to Anthropic's API endpoints rather than staying within your cloud provider. The data-residency and compliance statements on these pages do not apply to this option.
1010
1111## Choose an authentication approach
1212
from line 22
2222
2323| Setting | Type | Availability | Default | Description |
2424| - | - | - | - | - |
25| <span id="inferenceanthropicapikey" />Claude API key<br />`inferenceAnthropicApiKey` | `string` | MDM + Bootstrap<br />Added in 1.8089.0 | — | Leave blank to sign in with your browser, or to supply the key via a credential helper. |
25| Claude API key `inferenceAnthropicApiKey` | `string` | MDM + Bootstrap Added in 1.8089.0 | — | Leave blank to sign in with your browser, or to supply the key via a credential helper. |
2626
third-party/claude-desktop/code Changed · +8 / -8 lines
from line 51
5151
5252The network and filesystem sandboxes apply on macOS, and on Linux devices and [SSH hosts](/docs/third-party/claude-desktop/ssh-remote-sessions#managed-configuration-on-the-remote-host) with Claude Code's [sandbox dependencies](https://code.claude.com/docs/en/sandboxing) installed. Claude Code doesn't sandbox shell commands on Windows devices, and on a Linux device or SSH host without the dependencies commands run unsandboxed. In those cases, and when `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset, `blockReadsOutsideWorkingDirectories` still confines Claude's file tools but can only ask the user to approve shell commands that read outside the working directories or that Claude Code can't verify. For what a remote session shows, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).
5353
54<Warning>
55 Shell commands that run unsandboxed can reach hosts outside `coworkEgressAllowedHosts` and change files outside `allowedWorkspaceFolders`. Where the sandbox runs, a command that matches [`sandbox.excludedCommands`](https://code.claude.com/docs/en/sandboxing#run-commands-outside-the-sandbox-with-excludedcommands) in the user's own Claude Code settings also runs outside it, after Claude Code's regular permission flow. To keep Code off devices where the sandbox can't run, [turn off Code](#disabling-code) in the configuration you deploy to them. For SSH hosts, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).
56</Warning>
54> [!WARNING]
55>
56> Shell commands that run unsandboxed can reach hosts outside `coworkEgressAllowedHosts` and change files outside `allowedWorkspaceFolders`. Where the sandbox runs, a command that matches [`sandbox.excludedCommands`](https://code.claude.com/docs/en/sandboxing#run-commands-outside-the-sandbox-with-excludedcommands) in the user's own Claude Code settings also runs outside it, after Claude Code's regular permission flow. To keep Code off devices where the sandbox can't run, [turn off Code](#disabling-code) in the configuration you deploy to them. For SSH hosts, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).
5757
5858Under `blockReadsOutsideWorkingDirectories`, sandboxed shell commands can still read system locations such as `/usr`, the session's plugin and attachment folders (which become read-only), and the user's git configuration files (`~/.gitconfig` and the `config`, `ignore`, and `attributes` files under `~/.config/git`), which can themselves hold credentials such as tokens in remote URLs. Other files under the home folder outside the working directories are hidden from them, including `~/.ssh`, stored git credentials, included git configuration files, signing keys, and the target of a symlinked git configuration file, so git operations that need those files fail in the session until the user re-opens the paths. In a local session Claude also cannot read a file attached or `@`-mentioned from outside the working directories, so users should move such files into the session's folder or an allowed folder first.
5959
from line 75
7575
7676With `"merge"`, two Claude Code policy keys weaken `blockReadsOutsideWorkingDirectories`. `sandbox.filesystem.allowManagedReadPathsOnly` limits the block to Claude's file tools, so a shell command that reads outside the working directories asks for approval instead of failing, and `allowManagedPermissionRulesOnly` removes the session's read access to its plugin and attachment folders, so skills that read their own files stop working. Leave both out of your Claude Code policy if you rely on the block.
7777
78<Note>
79 With the [Claude API](/docs/third-party/claude-desktop/claude-api) as the inference provider, Code sessions ask Anthropic for the server-managed settings of [the organization that owns the credential](https://code.claude.com/docs/en/server-managed-settings#platform-availability). This holds for an API key in your configuration, an API key from a credential helper, and **Sign in with Claude Console**. If that organization has server-managed settings, set [`parentSettingsBehavior`](https://code.claude.com/docs/en/managed-settings#let-an-embedding-host-add-policy) to `"merge"` in them to keep Claude Desktop's [policy values](#applied-as-managed-policy). While server-managed settings apply, Claude Code by default [ignores most keys](https://code.claude.com/docs/en/managed-settings#how-claude-code-combines-managed-sources) in a file or OS profile on the device, and a `"merge"` set there has no effect.
80
81 Without a Claude Code `managed-settings.json` file, OS profile, or server-managed settings, Claude Desktop's policy applies automatically and you don't need to set `parentSettingsBehavior`.
82</Note>
78> [!NOTE]
79>
80> With the [Claude API](/docs/third-party/claude-desktop/claude-api) as the inference provider, Code sessions ask Anthropic for the server-managed settings of [the organization that owns the credential](https://code.claude.com/docs/en/server-managed-settings#platform-availability). This holds for an API key in your configuration, an API key from a credential helper, and **Sign in with Claude Console**. If that organization has server-managed settings, set [`parentSettingsBehavior`](https://code.claude.com/docs/en/managed-settings#let-an-embedding-host-add-policy) to `"merge"` in them to keep Claude Desktop's [policy values](#applied-as-managed-policy). While server-managed settings apply, Claude Code by default [ignores most keys](https://code.claude.com/docs/en/managed-settings#how-claude-code-combines-managed-sources) in a file or OS profile on the device, and a `"merge"` set there has no effect.
81>
82> Without a Claude Code `managed-settings.json` file, OS profile, or server-managed settings, Claude Desktop's policy applies automatically and you don't need to set `parentSettingsBehavior`.
8383
8484## Claude Code mods
8585
third-party/claude-desktop/configuration Changed · +1064 / -1114 lines
Nothing in the body moved in this read. What changed is above.
third-party/claude-desktop/configuration-changelog Changed · +1289 / -1373 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 4
44
55Configuration keys by Claude Desktop release. Each section lists keys added in that release, with the MDM key name (for plist/registry deployment) and the equivalent JSON shape (for local-file or bootstrap remote configuration).
66
7<Update label="v3.1623.0" description="2026-10-20">
8 <div className="cfg-keys">
9 | MDM key | Type | Description |
10 | - | - | - |
11 | [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel) | `enum` | Release channel |
12 | [`quickEntryDefaultShortcut`](/docs/third-party/claude-desktop/configuration#quickentrydefaultshortcut) | `string` | Default Quick Entry shortcut |
13 </div>
14
15 **JSON (e.g. for non-MDM users or Bootstrap):**
16
17 ```json theme={null}
18 {
19 "autoUpdate": {
20 "releaseChannel": "<stable|staggered>"
7**v3.1623.0**
8
9| MDM key | Type | Description |
10| - | - | - |
11| [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel) | `enum` | Release channel |
12| [`quickEntryDefaultShortcut`](/docs/third-party/claude-desktop/configuration#quickentrydefaultshortcut) | `string` | Default Quick Entry shortcut |
13
14**JSON (e.g. for non-MDM users or Bootstrap):**
15
16```json theme={null}
17{
18 "autoUpdate": {
19 "releaseChannel": "<stable|staggered>"
20 },
21 "workspace": {
22 "quickEntryDefaultShortcut": "<string>"
23 }
24}
25```
26
27**Changed:**
28
29* A remote or local `managedMcpServers` entry accepts an `icon` value: a PNG or JPEG as a base64 `data:` URI of at most 4,096 characters. Any other non-blank value is ignored, with a configuration warning. Earlier releases ignore `icon` and keep the entry.
30* `builtinToolPolicy` accepts every built-in tool name this release's Claude Code publishes, such as `CronCreate` or `LSP`. An earlier release drops each name it does not know with a configuration error and, if none is left, asks before each tool it knows.
31* `isLocalDevMcpEnabled`: `false` now also stops local MCP servers from plugins (your organization's marketplaces included, not the org-plugins directory), from Claude Code's `managed-mcp.json` if they use `${VAR}`, and in Code from Claude Code's own configuration files.
32* `relaunchEnforcementHours`: no waiting period when a device-management profile that sets more than the app-behavior keys first applies to an app that started without one, and the app will run on that profile after restarting.
33* `sshHostAllowlist` (beta): a session's jump hosts (`ProxyJump`, or a `ProxyCommand` written `ssh -W %h:%p host`) must now be on the list too, by `HostName`.
34
35**v2.42304.2**
36
37No configuration changes in this release.
38
39**v2.42304.0**
40
41**Changed:**
42
43* `chatAdvancedFileAnalysisEnabled` and `coworkEgressAllowedHosts`: commands in Chat's file-analysis sandbox can now reach the listed hosts. With no list, or an empty one, they have no network access.
44* `mcpPersistentAlwaysAllowEnabled`: `false` now also applies to Code sessions on the device, in WSL and over SSH.
45* `claudeAiImport.automatic3pImport` now also reinstalls, without asking, the optional plugins that a user had switched on from any optional `allowedPluginMarketplaces` entry with the same source in the old and new organization.
46
47**v2.37337.1**
48
49| MDM key | Type | Description |
50| - | - | - |
51| [`developerModeEnabled`](/docs/third-party/claude-desktop/configuration#developermodeenabled) | `boolean` | Allow Developer Mode |
52
53**JSON (e.g. for non-MDM users or Bootstrap):**
54
55```json theme={null}
56{
57 "workspace": {
58 "developerModeEnabled": "<boolean>"
59 }
60}
61```
62
63**Changed:**
64
65* `coworkEgressAllowedHosts`: your inference provider's, gateway's, and OTLP collector's hosts and `api.anthropic.com` are no longer added automatically. List them if tools call them.
66* `managedMcpServers[].toolPolicy`: a value other than `allow`, `ask`, or `blocked` now blocks that tool, and a `toolPolicy` that is not a map of tool names blocks every tool. The entry is kept, with a configuration error, instead of being dropped.
67* `sshTransport` (beta): a value that cannot be read now counts as `builtin`.
68* `disableNonessentialServices` no longer turns off Chart.js, Grid.js, and Mermaid in artifacts, which now come with the app.
69* `modelCatalogEnabled`: with `false`, picker names, descriptions, and effort options now come from the catalog bundled with the app.
70* `coworkTabEnabled`: with `false`, Cowork tasks now stay listed in the sidebar and open read-only instead of disappearing.
71* `disabledBuiltinTools`: a `WebFetch` or bare `Bash` entry added by device management now also applies to open Cowork and Chat conversations, and a tool name spelled with underscores or hyphens raises a configuration warning.
72
73**Removed:**
74
75The former key names below are now unrecognized keys: the setting no longer applies and the deprecation notice no longer appears. This replaces what the v1.40609.0 entry says these names do after the cut-off.
76
77* `isDxtEnabled`: use `isDesktopExtensionEnabled` instead. Until then extensions are off on third-party deployments and allowed on standard deployments.
78* `isDxtSignatureRequired`: use `isDesktopExtensionSignatureRequired` instead. Until then unsigned extensions load.
79* `enduserAttribution`: use `endUserAttribution` instead. Until then end-user attribution is on. In the Windows registry, where names ignore case, the former name still reads as `endUserAttribution`.
80* `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. Until then a `bootstrapUrl` set by device management (on Windows, machine policy only) is trusted without asking each user, and any other `bootstrapUrl` asks each user.
81* `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. Until then no custom inference headers are sent.
82* The deprecation notices for these spellings, which stopped being accepted on October 7, 2026 and are listed under v1.40609.0: header maps written as a string or list, `inferenceGatewayAuthScheme: "auto"`, `ask-session`, the older `managedMcpServers` entry forms, and the `orgPluginSettings` record form. Such a value is now reported like any other invalid value.
83
84**v2.31226.1**
85
86No configuration changes in this release.
87
88**v2.31226.0**
89
90| MDM key | Type | Description |
91| - | - | - |
92| [`otlpAttrMaxChars`](/docs/third-party/claude-desktop/configuration#otlpattrmaxchars) | `integer` | Telemetry attribute length limit |
93| [`desktopHome`](/docs/third-party/claude-desktop/configuration#desktophome) | `enum` | Desktop home |
94
95**JSON (e.g. for non-MDM users or Bootstrap):**
96
97```json theme={null}
98{
99 "otlp": {
100 "attrMaxChars": "<integer>"
101 },
102 "chatSurface": {
103 "desktopHome": "<standard|off>"
104 }
105}
106```
107
108**Changed:**
109
110* `allowedWorkspaceFolders`: in SSH sessions Claude's file tools can no longer modify a folder marked `ro`, as in a local Code session. Not enforced on Windows hosts, or on a host with Claude Code managed settings of its own (unless they set `parentSettingsBehavior` to `merge`).
111* `claudeAiImport.automatic3pImport` now also brings over Cowork artifacts, projects, memory and global instructions, scheduled tasks from Cowork and Code, uploaded plugins (unless `userPluginUploadsEnabled` is off), saved skills (unless `skillCreationEnabled` is off) and the optional plugins a user had on from the organization's plugins directory or a marketplace served from its gateway's or bootstrap server's own address, also on computers that moved under an earlier release.
112* `inferenceModels[].prefer1m` and `modelPrefer1mContext` now show one model picker entry for each model that offers 1M and has the preference, and start its new sessions at 1M, whichever entry a user had picked. Earlier releases only moved the starting selection of the first model.
113
114**v2.26454.2**
115
116No configuration changes in this release.
117
118**v2.26454.0**
119
120| MDM key | Type | Description |
121| - | - | - |
122| [`microsoftAuthDefaultAccount`](/docs/third-party/claude-desktop/configuration#microsoftauthdefaultaccount) | `enum` | Microsoft 365 sign-in with the Windows account |
123
124**JSON (e.g. for non-MDM users or Bootstrap):**
125
126```json theme={null}
127{
128 "authentication": {
129 "microsoftAuthDefaultAccount": "<enabled|disabled>"
130 }
131}
132```
133
134**Changed:**
135
136* `claudeAiImport` accepts a new `allowedOrganizationUuids` value, a list of Claude.ai organization IDs: when set, users can import history only by signing in to Claude.ai, and only from an organization on the list; a sign-in to any other organization or to a personal account is refused, and importing from a file or from earlier sessions on this computer is turned off. The list turns nothing on by itself, and `automatic3pImport` is not affected. Earlier releases ignore the list and keep allowing every import they allowed before, so the list limits imports only on devices running this release or later.
137* `disableAutoUpdates` now also decides when Cowork's workspace is downloaded: in the background, instead of at the first task, unless it is `true`.
138
139**Deprecated** (no end date has been set; this release and later keep reading the original spelling):
140
141* `inferenceGatewayAuthScheme: "sso"`: use `inferenceCredentialKind: "interactive"` instead. If `inferenceCredentialKind` is not set, this release and later keep reading the original spelling as `inferenceCredentialKind: "interactive"` after October 7, 2026. Earlier releases stop reading it on that date, as announced under v1.40609.0.
142
143**v2.19675.1**
144
145**Changed:**
146
147* `allowedWorkspaceFolders`, when set, now also limits which of a project's folders a chat can read: only those inside a listed folder.
148
149**v2.19675.0**
150
151No configuration changes in this release.
152
153**v2.16120.0**
154
155| MDM key | Type | Description |
156| - | - | - |
157| [`deniedPluginMcpServers`](/docs/third-party/claude-desktop/configuration#deniedpluginmcpservers) | `object[]` | Blocked plugin MCP servers |
158
159**JSON (e.g. for non-MDM users or Bootstrap):**
160
161```json theme={null}
162{
163 "mcp": {
164 "deniedPluginServers": [
165 {
166 "serverUrl": "<string>"
167 }
168 ]
169 }
170}
171```
172
173**Changed:**
174
175* `userPluginMarketplacesEnabled`: when set to `false`, plugin marketplaces your organization did not provision are now hidden in every tab, installs and updates from them are refused, and the sessions the app starts load plugins only from your organization's marketplaces, the organization plugins directory, the app's own uploads and the user's own skills folder; nothing is deleted, and removing the key or setting it to `true` restores them. Earlier releases only blocked adding marketplaces, so on devices where the key is already `false`, plugins from marketplaces users added before stop loading once the app updates.
176
177**v2.9939.4**
178
179No configuration changes in this release.
180
181**v2.9939.2**
182
183**Changed:**
184
185* `autoModeEnabled` no longer defaults to `false`. Left unset, the Code tab offers Auto mode and new Code tab sessions start in it where the model supports it; `true` does the same and also offers it in Cowork (Cowork sessions still start by asking before each action); `false` removes it from both tabs. Earlier releases treat an unset key as `false`, so Auto mode stays off on devices that have not updated.
186* `inferenceIdpOidc` and `inferenceGatewayOidc`: `resource` accepts, besides a web address, an identifier with a scheme of its own that is not a web address, such as an AD FS relying-party identifier (`urn:…`), which is sent to the identity provider exactly as written; a value with no scheme is still sent as `https://<value>`. Earlier releases accept only a web address here and ignore the whole sign-in object, not just `resource`, when it carries such an identifier, so deploy one only once every device has updated.
187
188**v2.7032.0**
189
190| MDM key | Type | Description |
191| - | - | - |
192| [`inferenceIdpAuthFlow`](/docs/third-party/claude-desktop/configuration#inferenceidpauthflow) | `enum` | Identity provider sign-in flow |
193| [`inferenceIdpOidc`](/docs/third-party/claude-desktop/configuration#inferenceidpoidc) | `object` | Identity provider (OIDC) |
194| [`mcpScheduledTaskApprovalLifetimeDays`](/docs/third-party/claude-desktop/configuration#mcpscheduledtaskapprovallifetimedays) | `integer` | Scheduled-task tool approval lifetime |
195| [`keepAwakeEnabled`](/docs/third-party/claude-desktop/configuration#keepawakeenabled) | `boolean` | Allow keep awake |
196
197**Set in the Claude admin console only:**
198
199* [`disableLocalConfigCache`](/docs/third-party/claude-desktop/configuration#disablelocalconfigcache) — Keep only your organization ID and restrictions on disk
200
201**JSON (e.g. for non-MDM users or Bootstrap):**
202
203```json theme={null}
204{
205 "inference": {
206 "credential": {
207 "authFlow": "<browser|broker>",
208 "oidc": {
209 "clientId": "<string>",
210 "issuer": "<string>",
211 "authorizationUrl": "<string>",
212 "tokenUrl": "<string>",
213 "bearerTokenType": "<id_token|access_token>",
214 "scopes": "<string>",
215 "appendOfflineAccess": "<boolean>",
216 "resource": "<string>",
217 "redirectPort": "<integer>",
218 "redirectHost": "<127.0.0.1|localhost>",
219 "additionalRedirectReferrerHosts": "<string>"
220 }
221 }
222 },
223 "mcp": {
224 "scheduledTaskApprovalLifetimeDays": "<integer>"
225 },
226 "workspace": {
227 "keepAwakeEnabled": "<boolean>"
228 }
229}
230```
231
232**Changed:**
233
234* `inferenceCredentialKind` accepts `external-idp` for the gateway and Bedrock providers: users sign in through your organization's OpenID Connect identity provider (`inferenceIdpOidc`, `inferenceIdpAuthFlow`) and the token is sent as the Bearer credential, on Bedrock to a token-validating proxy at `inferenceBedrockBaseUrl`, which that kind requires.
235
236**Deprecated** (no end date has been set; the original spellings keep working):
237
238* `inferenceCredentialKind: "interactive"` together with `inferenceGatewayOidc` (gateway): use `"external-idp"` instead once every desktop in the fleet is on 2.7032.0 or later; 2.7032.0 and later read the original spelling as `"external-idp"`.
239* `inferenceGatewayOidc`: use `inferenceIdpOidc` with `inferenceCredentialKind: "external-idp"` instead, once every desktop in the fleet is on 2.7032.0 or later.
240* `inferenceGatewayOidcAuthFlow`: use `inferenceIdpAuthFlow` together with `inferenceIdpOidc` instead, once every desktop in the fleet is on 2.7032.0 or later.
241
242**v2.2553.13**
243
244No configuration changes in this release.
245
246**v2.2553.1**
247
248No configuration changes in this release.
249
250**v2.2553.0**
251
252| MDM key | Type | Description |
253| - | - | - |
254| [`inferenceCredentialHelperWindows`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperwindows) | `string` | Helper script (Windows) |
255| [`allowedPluginMcpServers`](/docs/third-party/claude-desktop/configuration#allowedpluginmcpservers) | `object[]` | Allowed plugin MCP servers |
256| [`builtinBrowserEnabled`](/docs/third-party/claude-desktop/configuration#builtinbrowserenabled) | `boolean` | Allow the built-in browser |
257| [`builtinBrowserDefaultDomainPolicy`](/docs/third-party/claude-desktop/configuration#builtinbrowserdefaultdomainpolicy) | `enum` | Default site policy in the built-in browser |
258| [`builtinBrowserAllowedDomains`](/docs/third-party/claude-desktop/configuration#builtinbrowseralloweddomains) | `string[]` | Allowed sites in the built-in browser |
259| [`builtinBrowserBlockedDomains`](/docs/third-party/claude-desktop/configuration#builtinbrowserblockeddomains) | `string[]` | Blocked sites in the built-in browser |
260
261**JSON (e.g. for non-MDM users or Bootstrap):**
262
263```json theme={null}
264{
265 "inference": {
266 "credential": {
267 "commandWindows": "<string>"
268 }
269 },
270 "mcp": {
271 "allowedPluginServers": [
272 {
273 "serverUrl": "<string>"
274 }
275 ]
276 },
277 "builtinBrowser": {
278 "enabled": "<boolean>",
279 "defaultDomainPolicy": "<allow|block>",
280 "allowedDomains": ["<string>"],
281 "blockedDomains": ["<string>"]
282 }
283}
284```
285
286**Changed:**
287
288* `inferenceFoundryResource` now requires the user's consent when delivered by a bootstrap URL the user configured themselves (`consentRequired`), as `inferenceFoundryBaseUrl` and the other providers' endpoint settings already do; declining quits the app, and because the resource name is required each such Foundry install prompts once after updating. A bootstrap URL set by device management, or covered by `trustBootstrapDelivery: true`, never prompts, and values delivered by MDM are unchanged. Earlier releases apply a served value without asking.
289
290**v2.110.0**
291
292| MDM key | Type | Description |
293| - | - | - |
294| [`inferenceCredentialHelperArgs`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) | `string[]` | Helper script arguments |
295| [`inferenceFoundryBaseUrl`](/docs/third-party/claude-desktop/configuration#inferencefoundrybaseurl) | `string` | Azure AI Foundry base URL |
296| [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort) | `enum` | Default model effort |
297| [`alwaysStartWithDefaultModel`](/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) | `boolean` | Always start with the default model |
298| [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) | `boolean` | Model catalog metadata |
299| [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) | `string` | Model catalog URL |
300| [`scheduledTasksEnabled`](/docs/third-party/claude-desktop/configuration#scheduledtasksenabled) | `boolean` | Allow scheduled tasks |
301
302**JSON (e.g. for non-MDM users or Bootstrap):**
303
304```json theme={null}
305{
306 "inference": {
307 "credential": {
308 "args": ["<string>"]
21309 },
22 "workspace": {
23 "quickEntryDefaultShortcut": "<string>"
24 }
25 }
26 ```
27
28 **Changed:**
29
30 * A remote or local `managedMcpServers` entry accepts an `icon` value: a PNG or JPEG as a base64 `data:` URI of at most 4,096 characters. Any other non-blank value is ignored, with a configuration warning. Earlier releases ignore `icon` and keep the entry.
31 * `builtinToolPolicy` accepts every built-in tool name this release's Claude Code publishes, such as `CronCreate` or `LSP`. An earlier release drops each name it does not know with a configuration error and, if none is left, asks before each tool it knows.
32 * `isLocalDevMcpEnabled`: `false` now also stops local MCP servers from plugins (your organization's marketplaces included, not the org-plugins directory), from Claude Code's `managed-mcp.json` if they use `${VAR}`, and in Code from Claude Code's own configuration files.
33 * `relaunchEnforcementHours`: no waiting period when a device-management profile that sets more than the app-behavior keys first applies to an app that started without one, and the app will run on that profile after restarting.
34 * `sshHostAllowlist` (beta): a session's jump hosts (`ProxyJump`, or a `ProxyCommand` written `ssh -W %h:%p host`) must now be on the list too, by `HostName`.
35</Update>
36
37<Update label="v2.42304.2" description="2026-10-19">
38 No configuration changes in this release.
39</Update>
40
41<Update label="v2.42304.0" description="2026-10-15">
42 **Changed:**
43
44 * `chatAdvancedFileAnalysisEnabled` and `coworkEgressAllowedHosts`: commands in Chat's file-analysis sandbox can now reach the listed hosts. With no list, or an empty one, they have no network access.
45 * `mcpPersistentAlwaysAllowEnabled`: `false` now also applies to Code sessions on the device, in WSL and over SSH.
46 * `claudeAiImport.automatic3pImport` now also reinstalls, without asking, the optional plugins that a user had switched on from any optional `allowedPluginMarketplaces` entry with the same source in the old and new organization.
47</Update>
48
49<Update label="v2.37337.1" description="2026-10-13">
50 <div className="cfg-keys">
51 | MDM key | Type | Description |
52 | - | - | - |
53 | [`developerModeEnabled`](/docs/third-party/claude-desktop/configuration#developermodeenabled) | `boolean` | Allow Developer Mode |
54 </div>
55
56 **JSON (e.g. for non-MDM users or Bootstrap):**
57
58 ```json theme={null}
59 {
60 "workspace": {
61 "developerModeEnabled": "<boolean>"
62 }
63 }
64 ```
65
66 **Changed:**
67
68 * `coworkEgressAllowedHosts`: your inference provider's, gateway's, and OTLP collector's hosts and `api.anthropic.com` are no longer added automatically. List them if tools call them.
69 * `managedMcpServers[].toolPolicy`: a value other than `allow`, `ask`, or `blocked` now blocks that tool, and a `toolPolicy` that is not a map of tool names blocks every tool. The entry is kept, with a configuration error, instead of being dropped.
70 * `sshTransport` (beta): a value that cannot be read now counts as `builtin`.
71 * `disableNonessentialServices` no longer turns off Chart.js, Grid.js, and Mermaid in artifacts, which now come with the app.
72 * `modelCatalogEnabled`: with `false`, picker names, descriptions, and effort options now come from the catalog bundled with the app.
73 * `coworkTabEnabled`: with `false`, Cowork tasks now stay listed in the sidebar and open read-only instead of disappearing.
74 * `disabledBuiltinTools`: a `WebFetch` or bare `Bash` entry added by device management now also applies to open Cowork and Chat conversations, and a tool name spelled with underscores or hyphens raises a configuration warning.
75
76 **Removed:**
77
78 The former key names below are now unrecognized keys: the setting no longer applies and the deprecation notice no longer appears. This replaces what the v1.40609.0 entry says these names do after the cut-off.
79
80 * `isDxtEnabled`: use `isDesktopExtensionEnabled` instead. Until then extensions are off on third-party deployments and allowed on standard deployments.
81 * `isDxtSignatureRequired`: use `isDesktopExtensionSignatureRequired` instead. Until then unsigned extensions load.
82 * `enduserAttribution`: use `endUserAttribution` instead. Until then end-user attribution is on. In the Windows registry, where names ignore case, the former name still reads as `endUserAttribution`.
83 * `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. Until then a `bootstrapUrl` set by device management (on Windows, machine policy only) is trusted without asking each user, and any other `bootstrapUrl` asks each user.
84 * `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. Until then no custom inference headers are sent.
85 * The deprecation notices for these spellings, which stopped being accepted on October 7, 2026 and are listed under v1.40609.0: header maps written as a string or list, `inferenceGatewayAuthScheme: "auto"`, `ask-session`, the older `managedMcpServers` entry forms, and the `orgPluginSettings` record form. Such a value is now reported like any other invalid value.
86</Update>
87
88<Update label="v2.31226.1" description="2026-10-09">
89 No configuration changes in this release.
90</Update>
91
92<Update label="v2.31226.0" description="2026-10-08">
93 <div className="cfg-keys">
94 | MDM key | Type | Description |
95 | - | - | - |
96 | [`otlpAttrMaxChars`](/docs/third-party/claude-desktop/configuration#otlpattrmaxchars) | `integer` | Telemetry attribute length limit |
97 | [`desktopHome`](/docs/third-party/claude-desktop/configuration#desktophome) | `enum` | Desktop home |
98 </div>
99
100 **JSON (e.g. for non-MDM users or Bootstrap):**
101
102 ```json theme={null}
103 {
104 "otlp": {
105 "attrMaxChars": "<integer>"
106 },
107 "chatSurface": {
108 "desktopHome": "<standard|off>"
109 }
110 }
111 ```
112
113 **Changed:**
114
115 * `allowedWorkspaceFolders`: in SSH sessions Claude's file tools can no longer modify a folder marked `ro`, as in a local Code session. Not enforced on Windows hosts, or on a host with Claude Code managed settings of its own (unless they set `parentSettingsBehavior` to `merge`).
116 * `claudeAiImport.automatic3pImport` now also brings over Cowork artifacts, projects, memory and global instructions, scheduled tasks from Cowork and Code, uploaded plugins (unless `userPluginUploadsEnabled` is off), saved skills (unless `skillCreationEnabled` is off) and the optional plugins a user had on from the organization's plugins directory or a marketplace served from its gateway's or bootstrap server's own address, also on computers that moved under an earlier release.
117 * `inferenceModels[].prefer1m` and `modelPrefer1mContext` now show one model picker entry for each model that offers 1M and has the preference, and start its new sessions at 1M, whichever entry a user had picked. Earlier releases only moved the starting selection of the first model.
118</Update>
119
120<Update label="v2.26454.2" description="2026-10-07">
121 No configuration changes in this release.
122</Update>
123
124<Update label="v2.26454.0" description="2026-10-06">
125 <div className="cfg-keys">
126 | MDM key | Type | Description |
127 | - | - | - |
128 | [`microsoftAuthDefaultAccount`](/docs/third-party/claude-desktop/configuration#microsoftauthdefaultaccount) | `enum` | Microsoft 365 sign-in with the Windows account |
129 </div>
130
131 **JSON (e.g. for non-MDM users or Bootstrap):**
132
133 ```json theme={null}
134 {
135 "authentication": {
136 "microsoftAuthDefaultAccount": "<enabled|disabled>"
137 }
138 }
139 ```
140
141 **Changed:**
142
143 * `claudeAiImport` accepts a new `allowedOrganizationUuids` value, a list of Claude.ai organization IDs: when set, users can import history only by signing in to Claude.ai, and only from an organization on the list; a sign-in to any other organization or to a personal account is refused, and importing from a file or from earlier sessions on this computer is turned off. The list turns nothing on by itself, and `automatic3pImport` is not affected. Earlier releases ignore the list and keep allowing every import they allowed before, so the list limits imports only on devices running this release or later.
144 * `disableAutoUpdates` now also decides when Cowork's workspace is downloaded: in the background, instead of at the first task, unless it is `true`.
145
146 **Deprecated** (no end date has been set; this release and later keep reading the original spelling):
147
148 * `inferenceGatewayAuthScheme: "sso"`: use `inferenceCredentialKind: "interactive"` instead. If `inferenceCredentialKind` is not set, this release and later keep reading the original spelling as `inferenceCredentialKind: "interactive"` after October 7, 2026. Earlier releases stop reading it on that date, as announced under v1.40609.0.
149</Update>
150
151<Update label="v2.19675.1" description="2026-10-05">
152 **Changed:**
153
154 * `allowedWorkspaceFolders`, when set, now also limits which of a project's folders a chat can read: only those inside a listed folder.
155</Update>
156
157<Update label="v2.19675.0" description="2026-10-01">
158 No configuration changes in this release.
159</Update>
160
161<Update label="v2.16120.0" description="2026-09-29">
162 <div className="cfg-keys">
163 | MDM key | Type | Description |
164 | - | - | - |
165 | [`deniedPluginMcpServers`](/docs/third-party/claude-desktop/configuration#deniedpluginmcpservers) | `object[]` | Blocked plugin MCP servers |
166 </div>
167
168 **JSON (e.g. for non-MDM users or Bootstrap):**
169
170 ```json theme={null}
171 {
172 "mcp": {
173 "deniedPluginServers": [
310 "baseUrl": "<string>"
311 },
312 "models": {
313 "defaultEffort": "<low|medium|high|xhigh|max>",
314 "alwaysStartWithDefault": "<boolean>",
315 "catalogEnabled": "<boolean>",
316 "catalogUrl": "<string>"
317 },
318 "workspace": {
319 "scheduledTasksEnabled": "<boolean>"
320 }
321}
322```
323
324**Changed:**
325
326* `bootstrapOidc`, `inferenceGatewayOidc`, and `inferenceVertexWorkforceOidc` accept a new `redirectHost` value, `127.0.0.1` (the default) or `localhost`, which sets the host named in the browser sign-in's redirect URI (`http://<host>:<port>/callback`) for identity providers that only accept `localhost`; register exactly the URI you use. Earlier releases ignore the value and keep using `http://127.0.0.1:<port>/callback`, so a `localhost`-only registration still fails sign-in on them until they update.
327* An `inferenceModels` entry accepts a new `maxEffort` value (`low`, `medium`, `high`, `xhigh`, or `max`): effort levels above it are hidden for that model in Chat, Cowork, and Code and never requested, and Code sessions are held to it; an unrecognized value caps that model at `low`. Earlier releases ignore the value and keep offering every effort level, so the cap holds only on devices running this release or later.
328* A `managedMcpServers` entry accepts a new `transport` value, `policy-only`: the entry sets `toolPolicy` for an MCP server that an installed plugin provides, matched by `name`, without the app connecting to or launching anything, and takes precedence over `orgPluginSettings` for that server in Chat, Cowork, and Code. Earlier releases drop a `policy-only` entry (it appears under Configuration parse errors in the diagnostic report) and apply `orgPluginSettings` to that server instead; if every entry in the list is `policy-only` they cannot read `managedMcpServers` at all and, until they update, leave MCP servers that users added themselves or that a project's `.mcp.json` declares out of Code sessions. Keep the same permissions in `orgPluginSettings` while earlier releases are in use, and do not deploy a list made only of `policy-only` entries until every device has updated.
329
330**v1.52386.6**
331
332No configuration changes in this release.
333
334**v1.52386.3**
335
336No configuration changes in this release.
337
338**v1.52386.0**
339
340| MDM key | Type | Description |
341| - | - | - |
342| [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) · Beta | `enum` | SSH connection engine |
343| [`chatSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#chatsessionretentiondays) | `integer` | Chat retention period |
344| [`coworkSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#coworksessionretentiondays) | `integer` | Cowork retention period |
345| [`codeSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#codesessionretentiondays) | `integer` | Code retention period |
346| [`sessionRetentionHold`](/docs/third-party/claude-desktop/configuration#sessionretentionhold) | `boolean` | Suspend session deletion |
347| [`coworkVmIpv6Enabled`](/docs/third-party/claude-desktop/configuration#coworkvmipv6enabled) | `boolean` | Enable IPv6 in the workspace VM |
348
349**JSON (e.g. for non-MDM users or Bootstrap):**
350
351```json theme={null}
352{
353 "codeSurface": {
354 "sshTransport": "<auto|system-openssh|builtin>"
355 },
356 "sessionRetention": {
357 "chatDays": "<integer>",
358 "coworkDays": "<integer>",
359 "codeDays": "<integer>",
360 "legalHold": "<boolean>"
361 },
362 "workspace": {
363 "vmIpv6Enabled": "<boolean>"
364 }
365}
366```
367
368**v1.49585.0**
369
370**Changed:**
371
372* `managedMcpServers`: the built-in Microsoft 365 server entry (`"server": "microsoft365"`) accepts a new `continuousAccessEvaluation` value, `enabled` (the default) or `disabled`. When enabled, the bundled connector requests Continuous Access Evaluation-capable Microsoft Graph tokens, which live up to about 28 hours but are cut off within minutes when an administrator revokes sessions or disables the account, or, where the tenant enforces a location or compliant-network Conditional Access policy, when the token is used from outside that network; `disabled` keeps standard one-hour tokens. A change applies to tokens issued after the connector next starts.
373* `microsoftAuthBroker` accepts a new `required` value: Microsoft 365 sign-in fails when the OS sign-in broker (WAM on Windows, the Company Portal SSO extension on macOS) is unavailable instead of falling back to the browser, so the refresh token stays broker-held, and the connector removes the token cache an earlier browser sign-in left on disk. Linux has no broker, so `required` is not supported there. Earlier releases treat `required` as `disabled` (browser-only sign-in), so deploy it once every device is on this release or later.
374
375**v1.46388.4**
376
377No configuration changes in this release.
378
379**v1.46388.3**
380
381No configuration changes in this release.
382
383**v1.46388.2**
384
385No configuration changes in this release.
386
387**v1.46388.1**
388
389| MDM key | Type | Description |
390| - | - | - |
391| [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath) · Beta | `string` | SSH client program |
392| [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes) | `integer` | Configuration re-check interval |
393| [`disableBypassPermissionsMode`](/docs/third-party/claude-desktop/configuration#disablebypasspermissionsmode) | `boolean` | Disable bypass permissions mode |
394| [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories) | `boolean` | Block reads outside working directories |
395
396**JSON (e.g. for non-MDM users or Bootstrap):**
397
398```json theme={null}
399{
400 "codeSurface": {
401 "sshClientPath": "<string>"
402 },
403 "lifecycle": {
404 "configRecheckIntervalMinutes": "<integer>"
405 },
406 "workspace": {
407 "disableBypassPermissionsMode": "<boolean>",
408 "blockReadsOutsideWorkingDirectories": "<boolean>"
409 }
410}
411```
412
413**Changed:**
414
415* **Breaking:** `relaunchEnforcementHours` moved in the nested served format from `bootstrap.relaunchEnforcementHours` to `lifecycle.relaunchEnforcementHours` (beside the new `lifecycle.configRecheckIntervalMinutes`). This release no longer reads the old path and earlier releases do not read the new one, so move the value under `lifecycle`; the MDM / flat key name `relaunchEnforcementHours` is unchanged. The key can now also be set from device management (availability MDM and served), and the default when no tier sets it is 24 hours (was 1).
416
417**v1.44121.4**
418
419No configuration changes in this release.
420
421**v1.44121.2**
422
423No configuration changes in this release.
424
425**v1.44121.1**
426
427| MDM key | Type | Description |
428| - | - | - |
429| [`inferenceStreamIdleTimeoutSec`](/docs/third-party/claude-desktop/configuration#inferencestreamidletimeoutsec) | `integer` | Stream idle timeout |
430| [`egressProxyUrl`](/docs/third-party/claude-desktop/configuration#egressproxyurl) | `string` | Proxy server URL |
431| [`egressProxyPacUrl`](/docs/third-party/claude-desktop/configuration#egressproxypacurl) | `string` | Proxy auto-config (PAC) URL |
432| [`claudeAiImport.automatic3pImport`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield (beta): when `true` and `deploymentOrganizationUuid` is set, the app copies this computer's earlier third-party sessions stored before an organization ID was configured into that organization's session store, once per device and in the background; independent of `enabled` (default `false`). |
433
434**JSON (e.g. for non-MDM users or Bootstrap):**
435
436```json theme={null}
437{
438 "inference": {
439 "streamIdleTimeoutSec": "<integer>"
440 },
441 "workspace": {
442 "egressProxyUrl": "<string>",
443 "egressProxyPacUrl": "<string>"
444 },
445 "claudeAiImport": {
446 "automatic3pImport": "<boolean>"
447 }
448}
449```
450
451`egressProxyUrl` and `egressProxyPacUrl` are read from device management or a local configuration file only; a value served by a bootstrap URL is not applied.
452
453**Changed:**
454
455* **Breaking:** `inferenceModelPricingMultiplier` and `inferenceModelPricing` no longer turn on the Usage page's cost estimate by themselves; they apply only while `inferenceModelPricingEnabled` is `true` and are ignored otherwise. A configuration that sets either without `inferenceModelPricingEnabled: true` now shows token counts only; add that key to keep the estimate.
456
457**v1.40609.1**
458
459No configuration changes in this release.
460
461**v1.40609.0**
462
463| MDM key | Type | Description |
464| - | - | - |
465| [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) · Beta | `string[]` | SSH host allowlist |
466| [`disableConfigDeprecationWarnings`](/docs/third-party/claude-desktop/configuration#disableconfigdeprecationwarnings) | `boolean` | Hide configuration deprecation warnings |
467
468**JSON (e.g. for non-MDM users or Bootstrap):**
469
470```json theme={null}
471{
472 "codeSurface": {
473 "sshHostAllowlist": ["<string>"]
474 },
475 "bootstrap": {
476 "relaunchEnforcementHours": "<integer>"
477 },
478 "appearance": {
479 "disableConfigDeprecationWarnings": "<boolean>"
480 }
481}
482```
483
484`relaunchEnforcementHours` is read from served configuration only (a bootstrap URL); a value in a local configuration file or in device management is ignored with a warning.
485
486**Changed:**
487
488* `inferenceVertexProjectId` and `inferenceVertexWorkforceUserProject` now require the user's consent when delivered by a bootstrap URL the user configured themselves (`consentRequired`); a bootstrap URL set by device management, or covered by `trustBootstrapDelivery: true`, never prompts. Both keys must match the Google Cloud project format (`^[a-z0-9][a-z0-9.:-]*$`).
489* `inferenceCredentialKind` accepts `interactive` for Vertex AI (Google sign-in); the Vertex `oauth` value is deprecated (below).
490* `orgPluginSettings` is published as an array of `{ "serverName", "tools": [{ "toolName", "permission" }] }` entries; the `{ "mcpServers": {…} }` record form is deprecated (below).
491* The published bootstrap JSON schema now rejects `authorityHost` on the Microsoft 365 entry, so a configuration that still uses it fails schema validation in tools that check against the schema; the app itself keeps mapping it to `azureCloud` until October 7, 2026.
492* `allowedPluginMarketplaces` is no longer marked Beta.
493
494**Deprecated** (each accepted until October 7, 2026, 12:00 PM Pacific Time; users see an in-app warning from September 10, 2026, which `disableConfigDeprecationWarnings` hides, and a final reminder in the 24 hours before the cut-off, which it does not):
495
496* `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. After the cut-off no custom inference headers are sent.
497* `inferenceCustomHeaders`, `otlpHeaders`, `otlpResourceAttributes` and `bootstrapHeaders` written as a `"Name=value,…"` string or a `["Name: value", …]` list: use a JSON object such as `{"Name": "value"}` instead. After the cut-off a string or list value is rejected as malformed and no headers (or resource attributes) are sent.
498* `inferenceGatewayAuthScheme: "sso"`: use `inferenceCredentialKind: "interactive"` instead. After the cut-off the value is reported as invalid and, unless another credential field says how to sign in, the gateway connection has no credential and inference does not start.
499* `inferenceGatewayAuthScheme: "auto"`: use `"bearer"` instead, or remove the key (`bearer` is the default). After the cut-off the value is reported as invalid and the default applies.
500* `inferenceCredentialKind: "oauth"` (Vertex AI): use `"interactive"` instead. After the cut-off `oauth` is reported as invalid and the kind is derived from the credential fields present.
501* `inferenceCredentialKind: "interactive"` together with `inferenceVertexWorkforceAudience` (Vertex AI): use `"workforce"` instead, or remove the audience if Google sign-in is meant. After the cut-off the audience no longer implies Workforce Identity; `interactive` then needs `inferenceVertexOAuthClientId` or inference does not start.
502* `isDxtEnabled` and `isDxtSignatureRequired`: use `isDesktopExtensionEnabled` and `isDesktopExtensionSignatureRequired` instead. After the cut-off the old names are unreadable: extensions are disabled, or only signed extensions load, until the name is updated.
503* `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. After the cut-off the key reads `false` and each user is asked to consent to bootstrap-delivered values.
504* `enduserAttribution`: use `endUserAttribution` instead. After the cut-off the key reads `false` and end-user attribution stays off.
505* `orgPluginSettings` as a `{ "mcpServers": {…} }` record: use the array form instead (read by desktop 1.15200.0 and later; older desktops ignore the array and enforce no tool locks). After the cut-off the record is rejected and every plugin-delivered MCP tool is blocked until the value is rewritten.
506* `ask-session` in `builtinToolPolicy`, `orgPluginSettings[].tools[].permission` and `managedMcpServers[].toolPolicy`: use `ask` instead. After the cut-off it is treated as an unrecognized value: `ask` for a built-in tool, `blocked` for a plugin-delivered tool, and an invalid entry for a managed server.
507* In `managedMcpServers` entries: replace `scopes` with `scope` (one space-separated string); remove `transport: "builtin"` and `source`; replace `authorityHost` with `azureCloud: "us-gov-high"` for a GCC High tenant; write `oauth` as `true` or an oauth object rather than a number or string; replace `oauth.scopes` (or `oauth.scope` as a list) with `oauth.scope` as one string; add `transport: "http"` (or `"sse"` / `"stdio"`) to an entry with no `transport` that is not a built-in server (a built-in Microsoft 365 or GitHub entry takes no `transport`). After the cut-off such an entry is rejected and that connector is unavailable until it is rewritten (`source` is ignored by the desktop but refused by a customer-run Apps Gateway).
508
509**v1.37937.3**
510
511No configuration changes in this release.
512
513**v1.37937.2**
514
515No configuration changes in this release.
516
517**v1.37937.1**
518
519No configuration changes in this release.
520
521**v1.37937.0**
522
523| MDM key | Type | Description |
524| - | - | - |
525| [`inferenceModelPricingEnabled`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingenabled) | `boolean` | Show estimated cost |
526| [`inferenceModelPricingMultiplier`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingmultiplier) | `number` | Price multiplier |
527| [`inferenceModelPricing`](/docs/third-party/claude-desktop/configuration#inferencemodelpricing) | `object[]` | Model pricing |
528| [`userPluginMarketplacesEnabled`](/docs/third-party/claude-desktop/configuration#userpluginmarketplacesenabled) | `boolean` | Allow user-added plugin marketplaces |
529| [`userPluginUploadsEnabled`](/docs/third-party/claude-desktop/configuration#userpluginuploadsenabled) | `boolean` | Allow user-added plugins |
530| [`mcpToolTimeoutSec`](/docs/third-party/claude-desktop/configuration#mcptooltimeoutsec) | `integer` | MCP tool call timeout |
531| [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) | `boolean` | Skip WebFetch domain check |
532| [`organizationInstructions`](/docs/third-party/claude-desktop/configuration#organizationinstructions) | `string` | Organization instructions |
533
534**JSON (e.g. for non-MDM users or Bootstrap):**
535
536```json theme={null}
537{
538 "models": {
539 "pricing": {
540 "enabled": "<boolean>",
541 "multiplier": "<number>",
542 "models": [
174543 {
175 "serverUrl": "<string>"
544 "name": "<string>",
545 "inputPerMtok": "<number>",
546 "outputPerMtok": "<number>",
547 "cacheReadPerMtok": "<number>",
548 "cacheWritePerMtok": "<number>"
176549 }
177550 ]
178551 }
179 }
180 ```
181
182 **Changed:**
183
184 * `userPluginMarketplacesEnabled`: when set to `false`, plugin marketplaces your organization did not provision are now hidden in every tab, installs and updates from them are refused, and the sessions the app starts load plugins only from your organization's marketplaces, the organization plugins directory, the app's own uploads and the user's own skills folder; nothing is deleted, and removing the key or setting it to `true` restores them. Earlier releases only blocked adding marketplaces, so on devices where the key is already `false`, plugins from marketplaces users added before stop loading once the app updates.
185</Update>
186
187<Update label="v2.9939.4" description="2026-09-27">
188 No configuration changes in this release.
189</Update>
190
191<Update label="v2.9939.2" description="2026-09-24">
192 **Changed:**
193
194 * `autoModeEnabled` no longer defaults to `false`. Left unset, the Code tab offers Auto mode and new Code tab sessions start in it where the model supports it; `true` does the same and also offers it in Cowork (Cowork sessions still start by asking before each action); `false` removes it from both tabs. Earlier releases treat an unset key as `false`, so Auto mode stays off on devices that have not updated.
195 * `inferenceIdpOidc` and `inferenceGatewayOidc`: `resource` accepts, besides a web address, an identifier with a scheme of its own that is not a web address, such as an AD FS relying-party identifier (`urn:…`), which is sent to the identity provider exactly as written; a value with no scheme is still sent as `https://<value>`. Earlier releases accept only a web address here and ignore the whole sign-in object, not just `resource`, when it carries such an identifier, so deploy one only once every device has updated.
196</Update>
197
198<Update label="v2.7032.0" description="2026-09-22">
199 <div className="cfg-keys">
200 | MDM key | Type | Description |
201 | - | - | - |
202 | [`inferenceIdpAuthFlow`](/docs/third-party/claude-desktop/configuration#inferenceidpauthflow) | `enum` | Identity provider sign-in flow |
203 | [`inferenceIdpOidc`](/docs/third-party/claude-desktop/configuration#inferenceidpoidc) | `object` | Identity provider (OIDC) |
204 | [`mcpScheduledTaskApprovalLifetimeDays`](/docs/third-party/claude-desktop/configuration#mcpscheduledtaskapprovallifetimedays) | `integer` | Scheduled-task tool approval lifetime |
205 | [`keepAwakeEnabled`](/docs/third-party/claude-desktop/configuration#keepawakeenabled) | `boolean` | Allow keep awake |
206 </div>
207
208 **Set in the Claude admin console only:**
209
210 * [`disableLocalConfigCache`](/docs/third-party/claude-desktop/configuration#disablelocalconfigcache) — Keep only your organization ID and restrictions on disk
211
212 **JSON (e.g. for non-MDM users or Bootstrap):**
213
214 ```json theme={null}
215 {
216 "inference": {
217 "credential": {
218 "authFlow": "<browser|broker>",
219 "oidc": {
220 "clientId": "<string>",
221 "issuer": "<string>",
222 "authorizationUrl": "<string>",
223 "tokenUrl": "<string>",
224 "bearerTokenType": "<id_token|access_token>",
225 "scopes": "<string>",
226 "appendOfflineAccess": "<boolean>",
227 "resource": "<string>",
228 "redirectPort": "<integer>",
229 "redirectHost": "<127.0.0.1|localhost>",
230 "additionalRedirectReferrerHosts": "<string>"
231 }
552 },
553 "plugins": {
554 "userPluginMarketplacesEnabled": "<boolean>",
555 "userPluginUploadsEnabled": "<boolean>"
556 },
557 "mcp": {
558 "toolTimeoutSec": "<integer>"
559 },
560 "workspace": {
561 "skipWebFetchPreflight": "<boolean>",
562 "organizationInstructions": "<string>"
563 }
564}
565```
566
567**Changed:**
568
569* `builtinToolPolicy` accepts argument-scoped Claude Code permission rules such as `Bash(curl *)` or `Edit(**/*.env)` as keys, in addition to bare tool names; `WebSearch` and `WebFetch` take the bare name only, and a key that is not a usable rule is dropped with a configuration error. Deploy argument-scoped entries once your whole fleet is on this release: an older build drops an argument-scoped `ask` entry as an unknown tool, so that tool runs without a prompt.
570
571**v1.34493.1**
572
573No configuration changes in this release.
574
575**v1.34493.0**
576
577No configuration changes in this release.
578
579**v1.32885.1**
580
581| MDM key | Type | Description |
582| - | - | - |
583| [`bootstrapHeaders`](/docs/third-party/claude-desktop/configuration#bootstrapheaders) | `object` | Bootstrap request headers |
584| [`bootstrapHeadersHelper`](/docs/third-party/claude-desktop/configuration#bootstrapheadershelper) | `string` | Bootstrap headers helper script |
585
586**JSON (e.g. for non-MDM users or Bootstrap):**
587
588```json theme={null}
589{
590 "bootstrap": {
591 "headers": "<object>",
592 "headersHelper": "<string>"
593 }
594}
595```
596
597**Changed:**
598
599* `managedMcpServers[].oauth` accepts a new `mode` value, `hosted`: the app signs in to that MCP server with an Anthropic-hosted client identity (Anthropic vouches for the client on each token request) instead of a client you register yourself, pinned to the exact issuer URL(s) you list in `authorizationServer`; it requires the Claude.ai sign-in and is available once the hosted signer is enabled for your organization.
600
601**v1.32352.1**
602
603No configuration changes in this release.
604
605**v1.32352.0**
606
607| MDM key | Type | Description |
608| - | - | - |
609| [`claudeAiImport.exportEnabled`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield: lets users export this computer's chats, Cowork tasks, and Code sessions from Settings > Import & export as a zip that another install can import; no effect unless `enabled` is `true` (default `false`). |
610| [`allowedPluginMarketplaces[].manifestSha256`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) | `string` | New subfield (beta): SHA-256 of the exact hosted `marketplace.json` a `url` marketplace may serve; required when `installationPreference` is `auto_install` or `required`, and a served manifest with any other digest is refused. |
611
612**JSON (e.g. for non-MDM users or Bootstrap):**
613
614```json theme={null}
615{
616 "claudeAiImport": {
617 "exportEnabled": "<boolean>"
618 },
619 "plugins": {
620 "marketplaces": [
621 {
622 "source": "url",
623 "url": "<string>",
624 "manifestSha256": "<string>",
625 "credentialKind": "<anonymous|userGit|credentialHelper|inferenceCredential>"
232626 }
627 ]
628 }
629}
630```
631
632**Changed:**
633
634* **Breaking:** Managed-config URL settings now reject values that embed credentials (`https://user:password@host…`). Configurations that relied on this fail to load until the credentials are removed; use `bootstrapHeaders` / `bootstrapHeadersHelper` (available from 1.32885.1) to send authentication instead.
635* `allowedPluginMarketplaces[].source` (beta) accepts a new `url` value: a hosted `marketplace.json` whose plugins are zip archives, fetched over HTTPS with no git on the device; set `url` to the manifest address (`repo`, `ref`, and `path` do not apply).
636* `allowedPluginMarketplaces[].credentialKind` (beta) accepts a new `inferenceCredential` value, for `url` marketplaces on the inference gateway's own origin: fetches carry the same bearer credential the app already sends the gateway for inference.
637
638**v1.30096.5**
639
640No configuration changes in this release.
641
642**v1.30096.1**
643
644| MDM key | Type | Description |
645| - | - | - |
646| [`otlpAuthMode`](/docs/third-party/claude-desktop/configuration#otlpauthmode) | `enum` | Collector authentication |
647| [`otlpHeadersHelper`](/docs/third-party/claude-desktop/configuration#otlpheadershelper) | `string` | OpenTelemetry headers helper script |
648| [`inferenceGatewayOidc.resource`](/docs/third-party/claude-desktop/configuration#inferencegatewayoidc) | `string` | New subfield: RFC 8707 resource indicator sent on gateway sign-in and token refresh so the IdP audience-restricts the access token to the gateway; leave unset for Microsoft Entra ID. |
649
650**JSON (e.g. for non-MDM users or Bootstrap):**
651
652```json theme={null}
653{
654 "otlp": {
655 "authMode": "<none|inference-credential>",
656 "headersHelper": "<string>"
657 },
658 "inference": {
659 "credential": {
660 "oidc": {
661 "resource": "<string>"
662 }
663 }
664 }
665}
666```
667
668**Changed:**
669
670* `inferenceBedrockBaseUrl` and `inferenceVertexBaseUrl`: only affects users who entered the bootstrap server URL themselves (in Settings or a local config file). Those users are now asked once to allow a Bedrock or Vertex endpoint that server delivers (and again if it changes) before it takes effect, the same `trustBootstrapDelivery` consent prompt `inferenceGatewayBaseUrl` already shows; the provider's default endpoint is used until they allow it. Managed deployments (bootstrap URL set by device management, or `trustBootstrapDelivery: true`) see no change.
671
672**v1.28929.0**
673
674| MDM key | Type | Description |
675| - | - | - |
676| [`modelPrefer1mContext`](/docs/third-party/claude-desktop/configuration#modelprefer1mcontext) | `boolean` | Default to 1M context |
677| [`claudeAiImport.enabled`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield: turns history import on; the banner and import actions stay off until set to `true` (default `false`). |
678| [`claudeAiImport.bannerBehavior`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `enum` | New subfield: when the import banner appears: `off` (default), `detect`, or `show`. |
679
680**JSON (e.g. for non-MDM users or Bootstrap):**
681
682```json theme={null}
683{
684 "models": {
685 "prefer1mContext": "<boolean>"
686 },
687 "claudeAiImport": {
688 "enabled": "<boolean>",
689 "bannerBehavior": "<off|detect|show>"
690 }
691}
692```
693
694**Changed:**
695
696* `inferenceGatewayBaseUrl` delivered by a bootstrap server now goes through the `trustBootstrapDelivery` consent prompt: unless the bootstrap URL came from device management or `trustBootstrapDelivery` is `true`, each user is asked once to allow the address, and again if it changes, before it takes effect.
697
698**v1.26832.0**
699
700| MDM key | Type | Description |
701| - | - | - |
702| [`updateViaUpdatesHost`](/docs/third-party/claude-desktop/configuration#updateviaupdateshost) | `boolean` | Check for updates on releases.claude.com |
703| [`allowedWorkspaceFolders[].mode`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) | `enum` | New subfield: `ro` makes the folder read-only in Cowork; Code enforces file tools only. |
704
705**JSON (e.g. for non-MDM users or Bootstrap):**
706
707```json theme={null}
708{
709 "autoUpdate": {
710 "viaUpdatesHost": "<boolean>"
711 }
712}
713```
714
715`trustBootstrapLocalExec` was renamed to `trustBootstrapDelivery`; the previous name is still accepted.
716
717**v1.25927.0**
718
719| MDM key | Type | Description |
720| - | - | - |
721| [`inferenceGatewayOidcAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencegatewayoidcauthflow) | `enum` | Gateway sign-in flow |
722| [`inferenceVertexWorkforceAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceauthflow) | `enum` | Workforce Identity sign-in flow |
723| [`trustBootstrapLocalExec`](/docs/third-party/claude-desktop/configuration#trustbootstrapdelivery) | `boolean` | Trust bootstrap-delivered local commands |
724| [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) | `boolean` | Allow user-created skills |
725
726**JSON (e.g. for non-MDM users or Bootstrap):**
727
728```json theme={null}
729{
730 "inference": {
731 "credential": {
732 "authFlow": "<browser|broker>"
733 }
734 },
735 "bootstrap": {
736 "trustBootstrapLocalExec": "<boolean>"
737 },
738 "workspace": {
739 "skillCreationEnabled": "<boolean>"
740 }
741}
742```
743
744**Changed:**
745
746* `claudeAiImport`, `deploymentDisplayName`, and `deploymentDisplaySubtitle` now accept values from MDM and a local configuration file as well as a bootstrap server, and `disableDeepLinkRegistration`, `microsoftAuthBroker`, `userContentRendererUrl`, `inferenceFoundryTenantId`, `inferenceFoundryClientId`, `inferenceCredentialHelper` (with its TTL, timeout, and silent-refresh keys), `inferenceBedrockProfile`, `inferenceBedrockAwsDir`, `inferenceBedrockAwsCliPath`, and `inferenceVertexCredentialsFile` can now be delivered by a bootstrap server. The keys that name a local executable go through the `trustBootstrapLocalExec` consent prompt.
747* `managedMcpServers` gains a built-in `github` server: set `server` to `github` and supply your own GitHub OAuth app client ID with the device flow enabled. The new `host`, `toolsets`, and `readOnly` subfields point the connector at a GitHub Enterprise Server instance, choose which toolsets load, and offer read tools only.
748* `managedMcpServers[].oauth.authFlow` is a new subfield that lets a managed connector sign in through the operating system's Microsoft Entra account broker on Windows and macOS, so Conditional Access policies that require a managed device no longer block it. Devices without a broker keep using browser sign-in.
749* `enduserAttribution` is renamed to the corrected spelling `endUserAttribution`. The previous spelling is still accepted and now records a configuration warning.
750* `organizationPluginsUrl` is deprecated and removed from the configuration reference. The key is still honored, but organization plugins are better configured with `allowedPluginMarketplaces`.
751
752**v1.24012.11**
753
754No configuration changes in this release.
755
756**v1.24012.9**
757
758| MDM key | Type | Description |
759| - | - | - |
760| [`mcpPersistentAlwaysAllowEnabled`](/docs/third-party/claude-desktop/configuration#mcppersistentalwaysallowenabled) | `boolean` | Allow persistent tool approvals |
761
762**JSON (e.g. for non-MDM users or Bootstrap):**
763
764```json theme={null}
765{
766 "mcp": {
767 "persistentAlwaysAllowEnabled": "<boolean>"
768 }
769}
770```
771
772**v1.24012.0**
773
774| MDM key | Type | Description |
775| - | - | - |
776| [`enduserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) | `boolean` | End-user attribution |
777| [`userContentRendererUrl`](/docs/third-party/claude-desktop/configuration#usercontentrendererurl) | `string` | Artifact preview iframe origin |
778
779**JSON (e.g. for non-MDM users or Bootstrap):**
780
781```json theme={null}
782{
783 "deploymentDisplayName": "<string>",
784 "deploymentDisplaySubtitle": "<string>",
785 "enduserAttribution": "<boolean>",
786 "userContentRendererUrl": "<string>"
787}
788```
789
790**v1.22209.3**
791
792No configuration changes in this release.
793
794**v1.22209.0**
795
796| MDM key | Type | Description |
797| - | - | - |
798| [`otlpTracesEnabled`](/docs/third-party/claude-desktop/configuration#otlptracesenabled) | `boolean` | Export traces (beta) |
799
800**JSON (e.g. for non-MDM users or Bootstrap):**
801
802```json theme={null}
803{
804 "otlp": {
805 "tracesEnabled": "<boolean>"
806 }
807}
808```
809
810**v1.21459.3**
811
812No configuration changes in this release.
813
814**v1.21459.0**
815
816| MDM key | Type | Description |
817| - | - | - |
818| [`disableFeatureDiscovery`](/docs/third-party/claude-desktop/configuration#disablefeaturediscovery) | `boolean` | Hide feature announcements |
819| [`inferenceModels[].prefer1m`](/docs/third-party/claude-desktop/configuration#inferencemodels) | `boolean` | New subfield: make the 1M-context variant the default picker selection when this model is the default entry. |
820| [`managedMcpServers[].envHelper`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `string` | New subfield: helper executable that prints environment variables as JSON for a managed stdio server. |
821| [`managedMcpServers[].envHelperTtlSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: maximum age in seconds of a cached `envHelper` result (default 300). |
822| [`managedMcpServers[].headersHelperRefreshBufferSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: how many seconds before credential expiry the `headersHelper` re-runs (default 60). |
823| [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) | `boolean` | Enable tool search |
824
825**JSON (e.g. for non-MDM users or Bootstrap):**
826
827```json theme={null}
828{
829 "featureDiscovery": {
830 "disabled": "<boolean>"
831 },
832 "workspace": {
833 "toolSearchEnabled": "<boolean>"
834 }
835}
836```
837
838**Changed:**
839
840* `chatTabEnabled` and `chatAdvancedFileAnalysisEnabled` are no longer Beta: the Chat tab and advanced file analysis are generally available. Availability and defaults are unchanged, and both remain opt-in.
841* `orgPluginSettings[].tools.permission` accepts a new `ask-session` value. In this release the value is accepted but behaves as `ask` (a prompt on every use); the once-per-session approval flow is not yet enabled.
842
843**v1.20186.9**
844
845No configuration changes in this release.
846
847**v1.20186.0**
848
849No configuration changes in this release.
850
851**v1.19367.0**
852
853| MDM key | Type | Description |
854| - | - | - |
855| [`inferenceFoundryAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencefoundryauthflow) | `enum` | Entra ID sign-in flow |
856| [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) | `enum` | Microsoft 365 native sign-in broker |
857| [`managedMcpServers[].startupTimeoutSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: maximum wait in seconds for the server to start and list its tools. |
858
859**JSON (e.g. for non-MDM users or Bootstrap):**
860
861```json theme={null}
862{
863 "inference": {
864 "credential": {
865 "authFlow": "<device-code|browser>"
866 }
867 },
868 "authentication": {
869 "microsoftAuthBroker": "<auto|disabled>"
870 }
871}
872```
873
874**Changed:**
875
876* `isDesktopExtensionEnabled` — default changed from `true` to `false`: Desktop Extensions (`.dxt`, `.mcpb`) no longer load unless explicitly enabled.
877* `allowedPluginMarketplaces` (beta) — can now be delivered per-user through the bootstrap server; previously MDM-only.
878
879**v1.18286.2**
880
881No configuration changes in this release.
882
883**v1.18286.0**
884
885**Removed:**
886
887* `disableDefaultPlugins` — third-party deployments always skip the default plugin marketplaces and standard deployments always include them, so the key no longer has an effect.
888
889**v1.17377.2**
890
891No configuration changes in this release.
892
893**v1.17377.1**
894
895| MDM key | Type | Description |
896| - | - | - |
897| [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) | `object[]` | Admin-configured plugin marketplace git URLs appear under the Directory's Organization tab. (MDM-only; not settable via bootstrap JSON.) |
898| [`inferenceVertexWorkforceOidc.omitOfflineAccess`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) | `boolean` | New subfield: omit `offline_access` from the OIDC scope request. |
899
900**JSON (Non-MDM User, Bootstrap Remote):**
901
902```json theme={null}
903{
904 "inference": {
905 "credential": {
906 "oidc": {
907 "omitOfflineAccess": "<boolean>"
908 }
909 }
910 }
911}
912```
913
914**v1.15962.2**
915
916No configuration changes in this release.
917
918**v1.15962.1**
919
920No configuration changes in this release.
921
922**v1.15962.0**
923
924| MDM key | Type | Description |
925| - | - | - |
926| [`otlpContentCapture`](/docs/third-party/claude-desktop/configuration#otlpcontentcapture) | `enum[]` | Content capture categories |
927| [`disableBundledSkills`](/docs/third-party/claude-desktop/configuration#disablebundledskills) | `boolean` | Disable bundled skills and workflows |
928| [`managedMcpServers[].server`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `enum` | Gained `"websearch"` — managed web search (Brave, Tavily, Exa or custom) |
929
930**JSON (Non-MDM User, Bootstrap Remote):**
931
932```json theme={null}
933{
934 "otlp": {
935 "contentCapture": [
936 "<userPrompts|assistantResponses|toolDetails|toolContent|rawApiBodies>"
937 ]
938 },
939 "workspace": {
940 "disableBundledSkills": "<boolean>"
941 },
942 "mcp": {
943 "managedServers": [
944 {
945 "name": "Web search",
946 "server": "websearch",
947 "provider": "<brave|tavily|exa|custom>",
948 "headers": { "<header-name>": "<string>" },
949 "customUrl": "<string, provider=custom only>"
950 }
951 ]
952 }
953}
954```
955
956**v1.15200.0**
957
958No configuration changes in this release.
959
960**v1.14271.0**
961
962| MDM key | Type | Description |
963| - | - | - |
964| `chatAdvancedFileAnalysisEnabled` | `boolean` | Advanced file analysis |
965| `inferenceSessionLifetimeSec` | `integer` | Sign-in session lifetime |
966
967**JSON (Non-MDM User, Bootstrap Remote):**
968
969```json theme={null}
970{
971 "chatSurface": {
972 "advancedFileAnalysis": "<boolean>"
973 },
974 "inference": {
975 "sessionLifetimeSec": "<integer>"
976 }
977}
978```
979
980**Deprecated:**
981
982* `betaFeaturesEnabled` — Allow beta features (added and deprecated in this release)
983
984**v1.13576.0**
985
986| MDM key | Type | Description |
987| - | - | - |
988| `chatTabEnabled` | `boolean` | Allow Chat tab |
989| `inferenceBedrockAwsCliPath` | `string` | AWS CLI path |
990
991**JSON (Non-MDM User, Bootstrap Remote):**
992
993```json theme={null}
994{
995 "chatSurface": {
996 "enabled": "<boolean>"
997 },
998 "inference": {
999 "awsEnv": {
1000 "awsCliPath": "<string>"
1001 }
1002 }
1003}
1004```
1005
1006**v1.12603.0**
1007
1008| MDM key | Type | Description |
1009| - | - | - |
1010| `inferenceVertexOAuthLoginHint` | `string` | Vertex OAuth login hint |
1011
1012**JSON (Non-MDM User, Bootstrap Remote):**
1013
1014```json theme={null}
1015{
1016 "inference": {
1017 "credential": {
1018 "loginHint": "<string>"
1019 }
1020 }
1021}
1022```
1023
1024**v1.10628.0**
1025
1026| MDM key | Type | Description |
1027| - | - | - |
1028| `inferenceVertexWorkforceAudience` | `string` | Workforce Identity audience |
1029| `inferenceVertexWorkforceUserProject` | `string` | Workforce Identity billing project |
1030| `inferenceVertexWorkforceOidc` | `object` | Workforce Identity IdP (OIDC) |
1031| `organizationPluginsUrl` | `string` | Organization plugins endpoint |
1032| `autoModeEnabled` | `boolean` | Allow Auto mode |
1033| `inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | Re-run helper for silent refresh |
1034| `bootstrapEnabled` | `boolean` | Use bootstrap config |
1035| `bootstrapUrl` | `string` | Bootstrap config URL |
1036| `bootstrapOidc` | `object` | Bootstrap OIDC parameters |
1037
1038**JSON (Non-MDM User, Bootstrap Remote):**
1039
1040```json theme={null}
1041{
1042 "inference": {
1043 "credential": {
1044 "audience": "<string>",
1045 "userProject": "<string>",
1046 "oidc": {
1047 "issuer": "<string>",
1048 "authorizationUrl": "<string>",
1049 "tokenUrl": "<string>",
1050 "clientId": "<string>",
1051 "scopes": "<string>",
1052 "redirectPort": "<integer>"
1053 },
1054 "silentRefreshEnabled": "<boolean>"
1055 }
1056 }
1057}
1058```
1059
1060**v1.9659.0**
1061
1062| MDM key | Type | Description |
1063| - | - | - |
1064| `coworkTabEnabled` | `boolean` | Allow Cowork tab |
1065
1066**JSON (Non-MDM User, Bootstrap Remote):**
1067
1068```json theme={null}
1069{
1070 "coworkSurface": {
1071 "enabled": "<boolean>"
1072 }
1073}
1074```
1075
1076**v1.9255.0**
1077
1078| MDM key | Type | Description |
1079| - | - | - |
1080| `otlpDesktopLogLevel` | `enum` | Desktop telemetry export level |
1081| `inferenceFoundryTenantId` | `string` | Entra ID tenant ID |
1082| `inferenceFoundryClientId` | `string` | Entra ID client ID |
1083
1084**JSON (Non-MDM User, Bootstrap Remote):**
1085
1086```json theme={null}
1087{
1088 "otlp": {
1089 "desktopLogLevel": "<off|error|warn|info|debug>"
1090 },
1091 "inference": {
1092 "credential": {
1093 "tenantId": "<string>",
1094 "clientId": "<string>"
1095 }
1096 }
1097}
1098```
1099
1100**v1.8555.0**
1101
1102| MDM key | Type | Description |
1103| - | - | - |
1104| `inferenceCredentialKind` | `enum` | Credential kind |
1105
1106**JSON (Non-MDM User, Bootstrap Remote):**
1107
1108```json theme={null}
1109{
1110 "inference": {
1111 "credential": {
1112 "kind": "<static|helper-script|interactive|vendor-profile>"
1113 }
1114 }
1115}
1116```
1117
1118**v1.8089.0**
1119
1120| MDM key | Type | Description |
1121| - | - | - |
1122| `inferenceAnthropicApiKey` | `string` | Claude API key |
1123| `inferenceCustomHeaders` | `object` | Custom inference headers (renamed from `inferenceGatewayHeaders`) |
1124| `modelDiscoveryEnabled` | `boolean` | Model discovery |
1125| `orgPluginSettings` | `object` | Organization plugin settings |
1126| `builtinToolPolicy` | `object` | Built-in tool policy |
1127| `inferenceCredentialHelperTimeoutSec` | `integer` | Credential helper timeout |
1128
1129**JSON (Non-MDM User, Bootstrap Remote):**
1130
1131```json theme={null}
1132{
1133 "inference": {
1134 "credential": {
1135 "apiKey": "<string>",
1136 "timeoutSec": "<integer>"
2331137 },
234 "mcp": {
235 "scheduledTaskApprovalLifetimeDays": "<integer>"
236 },
237 "workspace": {
238 "keepAwakeEnabled": "<boolean>"
239 }
240 }
241 ```
242
243 **Changed:**
244
245 * `inferenceCredentialKind` accepts `external-idp` for the gateway and Bedrock providers: users sign in through your organization's OpenID Connect identity provider (`inferenceIdpOidc`, `inferenceIdpAuthFlow`) and the token is sent as the Bearer credential, on Bedrock to a token-validating proxy at `inferenceBedrockBaseUrl`, which that kind requires.
246
247 **Deprecated** (no end date has been set; the original spellings keep working):
248
249 * `inferenceCredentialKind: "interactive"` together with `inferenceGatewayOidc` (gateway): use `"external-idp"` instead once every desktop in the fleet is on 2.7032.0 or later; 2.7032.0 and later read the original spelling as `"external-idp"`.
250 * `inferenceGatewayOidc`: use `inferenceIdpOidc` with `inferenceCredentialKind: "external-idp"` instead, once every desktop in the fleet is on 2.7032.0 or later.
251 * `inferenceGatewayOidcAuthFlow`: use `inferenceIdpAuthFlow` together with `inferenceIdpOidc` instead, once every desktop in the fleet is on 2.7032.0 or later.
252</Update>
253
254<Update label="v2.2553.13" description="2026-09-21">
255 No configuration changes in this release.
256</Update>
257
258<Update label="v2.2553.1" description="2026-09-18">
259 No configuration changes in this release.
260</Update>
261
262<Update label="v2.2553.0" description="2026-09-17">
263 <div className="cfg-keys">
264 | MDM key | Type | Description |
265 | - | - | - |
266 | [`inferenceCredentialHelperWindows`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperwindows) | `string` | Helper script (Windows) |
267 | [`allowedPluginMcpServers`](/docs/third-party/claude-desktop/configuration#allowedpluginmcpservers) | `object[]` | Allowed plugin MCP servers |
268 | [`builtinBrowserEnabled`](/docs/third-party/claude-desktop/configuration#builtinbrowserenabled) | `boolean` | Allow the built-in browser |
269 | [`builtinBrowserDefaultDomainPolicy`](/docs/third-party/claude-desktop/configuration#builtinbrowserdefaultdomainpolicy) | `enum` | Default site policy in the built-in browser |
270 | [`builtinBrowserAllowedDomains`](/docs/third-party/claude-desktop/configuration#builtinbrowseralloweddomains) | `string[]` | Allowed sites in the built-in browser |
271 | [`builtinBrowserBlockedDomains`](/docs/third-party/claude-desktop/configuration#builtinbrowserblockeddomains) | `string[]` | Blocked sites in the built-in browser |
272 </div>
273
274 **JSON (e.g. for non-MDM users or Bootstrap):**
275
276 ```json theme={null}
277 {
278 "inference": {
279 "credential": {
280 "commandWindows": "<string>"
1138 "customHeaders": "<object>"
1139 }
1140}
1141```
1142
1143**v1.7196.0**
1144
1145| MDM key | Type | Description |
1146| - | - | - |
1147| `banner` | `object` | Organization banner |
1148
1149**v1.6889.0**
1150
1151| MDM key | Type | Description |
1152| - | - | - |
1153| `disableDeepLinkRegistration` | `boolean` | Disable claude:// deep-link handling |
1154| `inferenceGatewayOidc` | `object` | Gateway SSO IdP (OIDC) |
1155
1156**JSON (Non-MDM User, Bootstrap Remote):**
1157
1158```json theme={null}
1159{
1160 "inference": {
1161 "credential": {
1162 "oidc": {
1163 "issuer": "<string>",
1164 "authorizationUrl": "<string>",
1165 "tokenUrl": "<string>",
1166 "clientId": "<string>",
1167 "scopes": "<string>",
1168 "redirectPort": "<integer>",
1169 "bearerTokenType": "<id_token|access_token>",
1170 "appendOfflineAccess": "<boolean>"
2811171 }
282 },
283 "mcp": {
284 "allowedPluginServers": [
285 {
286 "serverUrl": "<string>"
287 }
288 ]
289 },
290 "builtinBrowser": {
291 "enabled": "<boolean>",
292 "defaultDomainPolicy": "<allow|block>",
293 "allowedDomains": ["<string>"],
294 "blockedDomains": ["<string>"]
295 }
296 }
297 ```
298
299 **Changed:**
300
301 * `inferenceFoundryResource` now requires the user's consent when delivered by a bootstrap URL the user configured themselves (`consentRequired`), as `inferenceFoundryBaseUrl` and the other providers' endpoint settings already do; declining quits the app, and because the resource name is required each such Foundry install prompts once after updating. A bootstrap URL set by device management, or covered by `trustBootstrapDelivery: true`, never prompts, and values delivered by MDM are unchanged. Earlier releases apply a served value without asking.
302</Update>
303
304<Update label="v2.110.0" description="2026-09-15">
305 <div className="cfg-keys">
306 | MDM key | Type | Description |
307 | - | - | - |
308 | [`inferenceCredentialHelperArgs`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) | `string[]` | Helper script arguments |
309 | [`inferenceFoundryBaseUrl`](/docs/third-party/claude-desktop/configuration#inferencefoundrybaseurl) | `string` | Azure AI Foundry base URL |
310 | [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort) | `enum` | Default model effort |
311 | [`alwaysStartWithDefaultModel`](/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) | `boolean` | Always start with the default model |
312 | [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) | `boolean` | Model catalog metadata |
313 | [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) | `string` | Model catalog URL |
314 | [`scheduledTasksEnabled`](/docs/third-party/claude-desktop/configuration#scheduledtasksenabled) | `boolean` | Allow scheduled tasks |
315 </div>
316
317 **JSON (e.g. for non-MDM users or Bootstrap):**
318
319 ```json theme={null}
320 {
321 "inference": {
322 "credential": {
323 "args": ["<string>"]
324 },
325 "baseUrl": "<string>"
326 },
327 "models": {
328 "defaultEffort": "<low|medium|high|xhigh|max>",
329 "alwaysStartWithDefault": "<boolean>",
330 "catalogEnabled": "<boolean>",
331 "catalogUrl": "<string>"
332 },
333 "workspace": {
334 "scheduledTasksEnabled": "<boolean>"
335 }
336 }
337 ```
338
339 **Changed:**
340
341 * `bootstrapOidc`, `inferenceGatewayOidc`, and `inferenceVertexWorkforceOidc` accept a new `redirectHost` value, `127.0.0.1` (the default) or `localhost`, which sets the host named in the browser sign-in's redirect URI (`http://<host>:<port>/callback`) for identity providers that only accept `localhost`; register exactly the URI you use. Earlier releases ignore the value and keep using `http://127.0.0.1:<port>/callback`, so a `localhost`-only registration still fails sign-in on them until they update.
342 * An `inferenceModels` entry accepts a new `maxEffort` value (`low`, `medium`, `high`, `xhigh`, or `max`): effort levels above it are hidden for that model in Chat, Cowork, and Code and never requested, and Code sessions are held to it; an unrecognized value caps that model at `low`. Earlier releases ignore the value and keep offering every effort level, so the cap holds only on devices running this release or later.
343 * A `managedMcpServers` entry accepts a new `transport` value, `policy-only`: the entry sets `toolPolicy` for an MCP server that an installed plugin provides, matched by `name`, without the app connecting to or launching anything, and takes precedence over `orgPluginSettings` for that server in Chat, Cowork, and Code. Earlier releases drop a `policy-only` entry (it appears under Configuration parse errors in the diagnostic report) and apply `orgPluginSettings` to that server instead; if every entry in the list is `policy-only` they cannot read `managedMcpServers` at all and, until they update, leave MCP servers that users added themselves or that a project's `.mcp.json` declares out of Code sessions. Keep the same permissions in `orgPluginSettings` while earlier releases are in use, and do not deploy a list made only of `policy-only` entries until every device has updated.
344</Update>
345
346<Update label="v1.52386.6" description="2026-09-13">
347 No configuration changes in this release.
348</Update>
349
350<Update label="v1.52386.3" description="2026-09-11">
351 No configuration changes in this release.
352</Update>
353
354<Update label="v1.52386.0" description="2026-09-10">
355 <div className="cfg-keys">
356 | MDM key | Type | Description |
357 | - | - | - |
358 | [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) · Beta | `enum` | SSH connection engine |
359 | [`chatSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#chatsessionretentiondays) | `integer` | Chat retention period |
360 | [`coworkSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#coworksessionretentiondays) | `integer` | Cowork retention period |
361 | [`codeSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#codesessionretentiondays) | `integer` | Code retention period |
362 | [`sessionRetentionHold`](/docs/third-party/claude-desktop/configuration#sessionretentionhold) | `boolean` | Suspend session deletion |
363 | [`coworkVmIpv6Enabled`](/docs/third-party/claude-desktop/configuration#coworkvmipv6enabled) | `boolean` | Enable IPv6 in the workspace VM |
364 </div>
365
366 **JSON (e.g. for non-MDM users or Bootstrap):**
367
368 ```json theme={null}
369 {
370 "codeSurface": {
371 "sshTransport": "<auto|system-openssh|builtin>"
372 },
373 "sessionRetention": {
374 "chatDays": "<integer>",
375 "coworkDays": "<integer>",
376 "codeDays": "<integer>",
377 "legalHold": "<boolean>"
378 },
379 "workspace": {
380 "vmIpv6Enabled": "<boolean>"
381 }
382 }
383 ```
384</Update>
385
386<Update label="v1.49585.0" description="2026-09-08">
387 **Changed:**
388
389 * `managedMcpServers`: the built-in Microsoft 365 server entry (`"server": "microsoft365"`) accepts a new `continuousAccessEvaluation` value, `enabled` (the default) or `disabled`. When enabled, the bundled connector requests Continuous Access Evaluation-capable Microsoft Graph tokens, which live up to about 28 hours but are cut off within minutes when an administrator revokes sessions or disables the account, or, where the tenant enforces a location or compliant-network Conditional Access policy, when the token is used from outside that network; `disabled` keeps standard one-hour tokens. A change applies to tokens issued after the connector next starts.
390 * `microsoftAuthBroker` accepts a new `required` value: Microsoft 365 sign-in fails when the OS sign-in broker (WAM on Windows, the Company Portal SSO extension on macOS) is unavailable instead of falling back to the browser, so the refresh token stays broker-held, and the connector removes the token cache an earlier browser sign-in left on disk. Linux has no broker, so `required` is not supported there. Earlier releases treat `required` as `disabled` (browser-only sign-in), so deploy it once every device is on this release or later.
391</Update>
392
393<Update label="v1.46388.4" description="2026-09-05">
394 No configuration changes in this release.
395</Update>
396
397<Update label="v1.46388.3" description="2026-09-04">
398 No configuration changes in this release.
399</Update>
400
401<Update label="v1.46388.2" description="2026-09-04">
402 No configuration changes in this release.
403</Update>
404
405<Update label="v1.46388.1" description="2026-09-04">
406 <div className="cfg-keys">
407 | MDM key | Type | Description |
408 | - | - | - |
409 | [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath) · Beta | `string` | SSH client program |
410 | [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes) | `integer` | Configuration re-check interval |
411 | [`disableBypassPermissionsMode`](/docs/third-party/claude-desktop/configuration#disablebypasspermissionsmode) | `boolean` | Disable bypass permissions mode |
412 | [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories) | `boolean` | Block reads outside working directories |
413 </div>
414
415 **JSON (e.g. for non-MDM users or Bootstrap):**
416
417 ```json theme={null}
418 {
419 "codeSurface": {
420 "sshClientPath": "<string>"
421 },
422 "lifecycle": {
423 "configRecheckIntervalMinutes": "<integer>"
424 },
425 "workspace": {
426 "disableBypassPermissionsMode": "<boolean>",
427 "blockReadsOutsideWorkingDirectories": "<boolean>"
428 }
429 }
430 ```
431
432 **Changed:**
433
434 * **Breaking:** `relaunchEnforcementHours` moved in the nested served format from `bootstrap.relaunchEnforcementHours` to `lifecycle.relaunchEnforcementHours` (beside the new `lifecycle.configRecheckIntervalMinutes`). This release no longer reads the old path and earlier releases do not read the new one, so move the value under `lifecycle`; the MDM / flat key name `relaunchEnforcementHours` is unchanged. The key can now also be set from device management (availability MDM and served), and the default when no tier sets it is 24 hours (was 1).
435</Update>
436
437<Update label="v1.44121.4" description="2026-09-02">
438 No configuration changes in this release.
439</Update>
440
441<Update label="v1.44121.2" description="2026-09-02">
442 No configuration changes in this release.
443</Update>
444
445<Update label="v1.44121.1" description="2026-09-02">
446 <div className="cfg-keys">
447 | MDM key | Type | Description |
448 | - | - | - |
449 | [`inferenceStreamIdleTimeoutSec`](/docs/third-party/claude-desktop/configuration#inferencestreamidletimeoutsec) | `integer` | Stream idle timeout |
450 | [`egressProxyUrl`](/docs/third-party/claude-desktop/configuration#egressproxyurl) | `string` | Proxy server URL |
451 | [`egressProxyPacUrl`](/docs/third-party/claude-desktop/configuration#egressproxypacurl) | `string` | Proxy auto-config (PAC) URL |
452 | [`claudeAiImport.automatic3pImport`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield (beta): when `true` and `deploymentOrganizationUuid` is set, the app copies this computer's earlier third-party sessions stored before an organization ID was configured into that organization's session store, once per device and in the background; independent of `enabled` (default `false`). |
453 </div>
454
455 **JSON (e.g. for non-MDM users or Bootstrap):**
456
457 ```json theme={null}
458 {
459 "inference": {
460 "streamIdleTimeoutSec": "<integer>"
461 },
462 "workspace": {
463 "egressProxyUrl": "<string>",
464 "egressProxyPacUrl": "<string>"
465 },
466 "claudeAiImport": {
467 "automatic3pImport": "<boolean>"
468 }
469 }
470 ```
471
472 `egressProxyUrl` and `egressProxyPacUrl` are read from device management or a local configuration file only; a value served by a bootstrap URL is not applied.
473
474 **Changed:**
475
476 * **Breaking:** `inferenceModelPricingMultiplier` and `inferenceModelPricing` no longer turn on the Usage page's cost estimate by themselves; they apply only while `inferenceModelPricingEnabled` is `true` and are ignored otherwise. A configuration that sets either without `inferenceModelPricingEnabled: true` now shows token counts only; add that key to keep the estimate.
477</Update>
478
479<Update label="v1.40609.1" description="2026-08-30">
480 No configuration changes in this release.
481</Update>
482
483<Update label="v1.40609.0" description="2026-08-27">
484 <div className="cfg-keys">
485 | MDM key | Type | Description |
486 | - | - | - |
487 | [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) · Beta | `string[]` | SSH host allowlist |
488 | [`disableConfigDeprecationWarnings`](/docs/third-party/claude-desktop/configuration#disableconfigdeprecationwarnings) | `boolean` | Hide configuration deprecation warnings |
489 </div>
490
491 **JSON (e.g. for non-MDM users or Bootstrap):**
492
493 ```json theme={null}
494 {
495 "codeSurface": {
496 "sshHostAllowlist": ["<string>"]
497 },
498 "bootstrap": {
499 "relaunchEnforcementHours": "<integer>"
500 },
501 "appearance": {
502 "disableConfigDeprecationWarnings": "<boolean>"
503 }
504 }
505 ```
506
507 `relaunchEnforcementHours` is read from served configuration only (a bootstrap URL); a value in a local configuration file or in device management is ignored with a warning.
508
509 **Changed:**
510
511 * `inferenceVertexProjectId` and `inferenceVertexWorkforceUserProject` now require the user's consent when delivered by a bootstrap URL the user configured themselves (`consentRequired`); a bootstrap URL set by device management, or covered by `trustBootstrapDelivery: true`, never prompts. Both keys must match the Google Cloud project format (`^[a-z0-9][a-z0-9.:-]*$`).
512 * `inferenceCredentialKind` accepts `interactive` for Vertex AI (Google sign-in); the Vertex `oauth` value is deprecated (below).
513 * `orgPluginSettings` is published as an array of `{ "serverName", "tools": [{ "toolName", "permission" }] }` entries; the `{ "mcpServers": {…} }` record form is deprecated (below).
514 * The published bootstrap JSON schema now rejects `authorityHost` on the Microsoft 365 entry, so a configuration that still uses it fails schema validation in tools that check against the schema; the app itself keeps mapping it to `azureCloud` until October 7, 2026.
515 * `allowedPluginMarketplaces` is no longer marked Beta.
516
517 **Deprecated** (each accepted until October 7, 2026, 12:00 PM Pacific Time; users see an in-app warning from September 10, 2026, which `disableConfigDeprecationWarnings` hides, and a final reminder in the 24 hours before the cut-off, which it does not):
518
519 * `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. After the cut-off no custom inference headers are sent.
520 * `inferenceCustomHeaders`, `otlpHeaders`, `otlpResourceAttributes` and `bootstrapHeaders` written as a `"Name=value,…"` string or a `["Name: value", …]` list: use a JSON object such as `{"Name": "value"}` instead. After the cut-off a string or list value is rejected as malformed and no headers (or resource attributes) are sent.
521 * `inferenceGatewayAuthScheme: "sso"`: use `inferenceCredentialKind: "interactive"` instead. After the cut-off the value is reported as invalid and, unless another credential field says how to sign in, the gateway connection has no credential and inference does not start.
522 * `inferenceGatewayAuthScheme: "auto"`: use `"bearer"` instead, or remove the key (`bearer` is the default). After the cut-off the value is reported as invalid and the default applies.
523 * `inferenceCredentialKind: "oauth"` (Vertex AI): use `"interactive"` instead. After the cut-off `oauth` is reported as invalid and the kind is derived from the credential fields present.
524 * `inferenceCredentialKind: "interactive"` together with `inferenceVertexWorkforceAudience` (Vertex AI): use `"workforce"` instead, or remove the audience if Google sign-in is meant. After the cut-off the audience no longer implies Workforce Identity; `interactive` then needs `inferenceVertexOAuthClientId` or inference does not start.
525 * `isDxtEnabled` and `isDxtSignatureRequired`: use `isDesktopExtensionEnabled` and `isDesktopExtensionSignatureRequired` instead. After the cut-off the old names are unreadable: extensions are disabled, or only signed extensions load, until the name is updated.
526 * `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. After the cut-off the key reads `false` and each user is asked to consent to bootstrap-delivered values.
527 * `enduserAttribution`: use `endUserAttribution` instead. After the cut-off the key reads `false` and end-user attribution stays off.
528 * `orgPluginSettings` as a `{ "mcpServers": {…} }` record: use the array form instead (read by desktop 1.15200.0 and later; older desktops ignore the array and enforce no tool locks). After the cut-off the record is rejected and every plugin-delivered MCP tool is blocked until the value is rewritten.
529 * `ask-session` in `builtinToolPolicy`, `orgPluginSettings[].tools[].permission` and `managedMcpServers[].toolPolicy`: use `ask` instead. After the cut-off it is treated as an unrecognized value: `ask` for a built-in tool, `blocked` for a plugin-delivered tool, and an invalid entry for a managed server.
530 * In `managedMcpServers` entries: replace `scopes` with `scope` (one space-separated string); remove `transport: "builtin"` and `source`; replace `authorityHost` with `azureCloud: "us-gov-high"` for a GCC High tenant; write `oauth` as `true` or an oauth object rather than a number or string; replace `oauth.scopes` (or `oauth.scope` as a list) with `oauth.scope` as one string; add `transport: "http"` (or `"sse"` / `"stdio"`) to an entry with no `transport` that is not a built-in server (a built-in Microsoft 365 or GitHub entry takes no `transport`). After the cut-off such an entry is rejected and that connector is unavailable until it is rewritten (`source` is ignored by the desktop but refused by a customer-run Apps Gateway).
531</Update>
532
533<Update label="v1.37937.3" description="2026-08-26">
534 No configuration changes in this release.
535</Update>
536
537<Update label="v1.37937.2" description="2026-08-26">
538 No configuration changes in this release.
539</Update>
540
541<Update label="v1.37937.1" description="2026-08-25">
542 No configuration changes in this release.
543</Update>
544
545<Update label="v1.37937.0" description="2026-08-25">
546 <div className="cfg-keys">
547 | MDM key | Type | Description |
548 | - | - | - |
549 | [`inferenceModelPricingEnabled`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingenabled) | `boolean` | Show estimated cost |
550 | [`inferenceModelPricingMultiplier`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingmultiplier) | `number` | Price multiplier |
551 | [`inferenceModelPricing`](/docs/third-party/claude-desktop/configuration#inferencemodelpricing) | `object[]` | Model pricing |
552 | [`userPluginMarketplacesEnabled`](/docs/third-party/claude-desktop/configuration#userpluginmarketplacesenabled) | `boolean` | Allow user-added plugin marketplaces |
553 | [`userPluginUploadsEnabled`](/docs/third-party/claude-desktop/configuration#userpluginuploadsenabled) | `boolean` | Allow user-added plugins |
554 | [`mcpToolTimeoutSec`](/docs/third-party/claude-desktop/configuration#mcptooltimeoutsec) | `integer` | MCP tool call timeout |
555 | [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) | `boolean` | Skip WebFetch domain check |
556 | [`organizationInstructions`](/docs/third-party/claude-desktop/configuration#organizationinstructions) | `string` | Organization instructions |
557 </div>
558
559 **JSON (e.g. for non-MDM users or Bootstrap):**
560
561 ```json theme={null}
562 {
563 "models": {
564 "pricing": {
565 "enabled": "<boolean>",
566 "multiplier": "<number>",
567 "models": [
568 {
569 "name": "<string>",
570 "inputPerMtok": "<number>",
571 "outputPerMtok": "<number>",
572 "cacheReadPerMtok": "<number>",
573 "cacheWritePerMtok": "<number>"
574 }
575 ]
576 }
577 },
578 "plugins": {
579 "userPluginMarketplacesEnabled": "<boolean>",
580 "userPluginUploadsEnabled": "<boolean>"
581 },
582 "mcp": {
583 "toolTimeoutSec": "<integer>"
584 },
585 "workspace": {
586 "skipWebFetchPreflight": "<boolean>",
587 "organizationInstructions": "<string>"
588 }
589 }
590 ```
591
592 **Changed:**
593
594 * `builtinToolPolicy` accepts argument-scoped Claude Code permission rules such as `Bash(curl *)` or `Edit(**/*.env)` as keys, in addition to bare tool names; `WebSearch` and `WebFetch` take the bare name only, and a key that is not a usable rule is dropped with a configuration error. Deploy argument-scoped entries once your whole fleet is on this release: an older build drops an argument-scoped `ask` entry as an unknown tool, so that tool runs without a prompt.
595</Update>
596
597<Update label="v1.34493.1" description="2026-08-21">
598 No configuration changes in this release.
599</Update>
600
601<Update label="v1.34493.0" description="2026-08-20">
602 No configuration changes in this release.
603</Update>
604
605<Update label="v1.32885.1" description="2026-08-18">
606 <div className="cfg-keys">
607 | MDM key | Type | Description |
608 | - | - | - |
609 | [`bootstrapHeaders`](/docs/third-party/claude-desktop/configuration#bootstrapheaders) | `object` | Bootstrap request headers |
610 | [`bootstrapHeadersHelper`](/docs/third-party/claude-desktop/configuration#bootstrapheadershelper) | `string` | Bootstrap headers helper script |
611 </div>
612
613 **JSON (e.g. for non-MDM users or Bootstrap):**
614
615 ```json theme={null}
616 {
617 "bootstrap": {
618 "headers": "<object>",
619 "headersHelper": "<string>"
620 }
621 }
622 ```
623
624 **Changed:**
625
626 * `managedMcpServers[].oauth` accepts a new `mode` value, `hosted`: the app signs in to that MCP server with an Anthropic-hosted client identity (Anthropic vouches for the client on each token request) instead of a client you register yourself, pinned to the exact issuer URL(s) you list in `authorizationServer`; it requires the Claude.ai sign-in and is available once the hosted signer is enabled for your organization.
627</Update>
628
629<Update label="v1.32352.1" description="2026-08-18">
630 No configuration changes in this release.
631</Update>
632
633<Update label="v1.32352.0" description="2026-08-17">
634 <div className="cfg-keys">
635 | MDM key | Type | Description |
636 | - | - | - |
637 | [`claudeAiImport.exportEnabled`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield: lets users export this computer's chats, Cowork tasks, and Code sessions from Settings > Import & export as a zip that another install can import; no effect unless `enabled` is `true` (default `false`). |
638 | [`allowedPluginMarketplaces[].manifestSha256`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) | `string` | New subfield (beta): SHA-256 of the exact hosted `marketplace.json` a `url` marketplace may serve; required when `installationPreference` is `auto_install` or `required`, and a served manifest with any other digest is refused. |
639 </div>
640
641 **JSON (e.g. for non-MDM users or Bootstrap):**
642
643 ```json theme={null}
644 {
645 "claudeAiImport": {
646 "exportEnabled": "<boolean>"
647 },
648 "plugins": {
649 "marketplaces": [
650 {
651 "source": "url",
652 "url": "<string>",
653 "manifestSha256": "<string>",
654 "credentialKind": "<anonymous|userGit|credentialHelper|inferenceCredential>"
655 }
656 ]
657 }
658 }
659 ```
660
661 **Changed:**
662
663 * **Breaking:** Managed-config URL settings now reject values that embed credentials (`https://user:password@host…`). Configurations that relied on this fail to load until the credentials are removed; use `bootstrapHeaders` / `bootstrapHeadersHelper` (available from 1.32885.1) to send authentication instead.
664 * `allowedPluginMarketplaces[].source` (beta) accepts a new `url` value: a hosted `marketplace.json` whose plugins are zip archives, fetched over HTTPS with no git on the device; set `url` to the manifest address (`repo`, `ref`, and `path` do not apply).
665 * `allowedPluginMarketplaces[].credentialKind` (beta) accepts a new `inferenceCredential` value, for `url` marketplaces on the inference gateway's own origin: fetches carry the same bearer credential the app already sends the gateway for inference.
666</Update>
667
668<Update label="v1.30096.5" description="2026-08-14">
669 No configuration changes in this release.
670</Update>
671
672<Update label="v1.30096.1" description="2026-08-13">
673 <div className="cfg-keys">
674 | MDM key | Type | Description |
675 | - | - | - |
676 | [`otlpAuthMode`](/docs/third-party/claude-desktop/configuration#otlpauthmode) | `enum` | Collector authentication |
677 | [`otlpHeadersHelper`](/docs/third-party/claude-desktop/configuration#otlpheadershelper) | `string` | OpenTelemetry headers helper script |
678 | [`inferenceGatewayOidc.resource`](/docs/third-party/claude-desktop/configuration#inferencegatewayoidc) | `string` | New subfield: RFC 8707 resource indicator sent on gateway sign-in and token refresh so the IdP audience-restricts the access token to the gateway; leave unset for Microsoft Entra ID. |
679 </div>
680
681 **JSON (e.g. for non-MDM users or Bootstrap):**
682
683 ```json theme={null}
684 {
685 "otlp": {
686 "authMode": "<none|inference-credential>",
687 "headersHelper": "<string>"
688 },
689 "inference": {
690 "credential": {
691 "oidc": {
692 "resource": "<string>"
693 }
694 }
695 }
696 }
697 ```
698
699 **Changed:**
700
701 * `inferenceBedrockBaseUrl` and `inferenceVertexBaseUrl`: only affects users who entered the bootstrap server URL themselves (in Settings or a local config file). Those users are now asked once to allow a Bedrock or Vertex endpoint that server delivers (and again if it changes) before it takes effect, the same `trustBootstrapDelivery` consent prompt `inferenceGatewayBaseUrl` already shows; the provider's default endpoint is used until they allow it. Managed deployments (bootstrap URL set by device management, or `trustBootstrapDelivery: true`) see no change.
702</Update>
703
704<Update label="v1.28929.0" description="2026-08-11">
705 <div className="cfg-keys">
706 | MDM key | Type | Description |
707 | - | - | - |
708 | [`modelPrefer1mContext`](/docs/third-party/claude-desktop/configuration#modelprefer1mcontext) | `boolean` | Default to 1M context |
709 | [`claudeAiImport.enabled`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `boolean` | New subfield: turns history import on; the banner and import actions stay off until set to `true` (default `false`). |
710 | [`claudeAiImport.bannerBehavior`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `enum` | New subfield: when the import banner appears: `off` (default), `detect`, or `show`. |
711 </div>
712
713 **JSON (e.g. for non-MDM users or Bootstrap):**
714
715 ```json theme={null}
716 {
717 "models": {
718 "prefer1mContext": "<boolean>"
719 },
720 "claudeAiImport": {
721 "enabled": "<boolean>",
722 "bannerBehavior": "<off|detect|show>"
723 }
724 }
725 ```
726
727 **Changed:**
728
729 * `inferenceGatewayBaseUrl` delivered by a bootstrap server now goes through the `trustBootstrapDelivery` consent prompt: unless the bootstrap URL came from device management or `trustBootstrapDelivery` is `true`, each user is asked once to allow the address, and again if it changes, before it takes effect.
730</Update>
731
732<Update label="v1.26832.0" description="2026-08-06">
733 <div className="cfg-keys">
734 | MDM key | Type | Description |
735 | - | - | - |
736 | [`updateViaUpdatesHost`](/docs/third-party/claude-desktop/configuration#updateviaupdateshost) | `boolean` | Check for updates on releases.claude.com |
737 | [`allowedWorkspaceFolders[].mode`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) | `enum` | New subfield: `ro` makes the folder read-only in Cowork; Code enforces file tools only. |
738 </div>
739
740 **JSON (e.g. for non-MDM users or Bootstrap):**
741
742 ```json theme={null}
743 {
744 "autoUpdate": {
745 "viaUpdatesHost": "<boolean>"
746 }
747 }
748 ```
749
750 `trustBootstrapLocalExec` was renamed to `trustBootstrapDelivery`; the previous name is still accepted.
751</Update>
752
753<Update label="v1.25927.0" description="2026-08-04">
754 <div className="cfg-keys">
755 | MDM key | Type | Description |
756 | - | - | - |
757 | [`inferenceGatewayOidcAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencegatewayoidcauthflow) | `enum` | Gateway sign-in flow |
758 | [`inferenceVertexWorkforceAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceauthflow) | `enum` | Workforce Identity sign-in flow |
759 | [`trustBootstrapLocalExec`](/docs/third-party/claude-desktop/configuration#trustbootstrapdelivery) | `boolean` | Trust bootstrap-delivered local commands |
760 | [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) | `boolean` | Allow user-created skills |
761 </div>
762
763 **JSON (e.g. for non-MDM users or Bootstrap):**
764
765 ```json theme={null}
766 {
767 "inference": {
768 "credential": {
769 "authFlow": "<browser|broker>"
770 }
771 },
772 "bootstrap": {
773 "trustBootstrapLocalExec": "<boolean>"
774 },
775 "workspace": {
776 "skillCreationEnabled": "<boolean>"
777 }
778 }
779 ```
780
781 **Changed:**
782
783 * `claudeAiImport`, `deploymentDisplayName`, and `deploymentDisplaySubtitle` now accept values from MDM and a local configuration file as well as a bootstrap server, and `disableDeepLinkRegistration`, `microsoftAuthBroker`, `userContentRendererUrl`, `inferenceFoundryTenantId`, `inferenceFoundryClientId`, `inferenceCredentialHelper` (with its TTL, timeout, and silent-refresh keys), `inferenceBedrockProfile`, `inferenceBedrockAwsDir`, `inferenceBedrockAwsCliPath`, and `inferenceVertexCredentialsFile` can now be delivered by a bootstrap server. The keys that name a local executable go through the `trustBootstrapLocalExec` consent prompt.
784 * `managedMcpServers` gains a built-in `github` server: set `server` to `github` and supply your own GitHub OAuth app client ID with the device flow enabled. The new `host`, `toolsets`, and `readOnly` subfields point the connector at a GitHub Enterprise Server instance, choose which toolsets load, and offer read tools only.
785 * `managedMcpServers[].oauth.authFlow` is a new subfield that lets a managed connector sign in through the operating system's Microsoft Entra account broker on Windows and macOS, so Conditional Access policies that require a managed device no longer block it. Devices without a broker keep using browser sign-in.
786 * `enduserAttribution` is renamed to the corrected spelling `endUserAttribution`. The previous spelling is still accepted and now records a configuration warning.
787 * `organizationPluginsUrl` is deprecated and removed from the configuration reference. The key is still honored, but organization plugins are better configured with `allowedPluginMarketplaces`.
788</Update>
789
790<Update label="v1.24012.11" description="2026-08-03">
791 No configuration changes in this release.
792</Update>
793
794<Update label="v1.24012.9" description="2026-07-24">
795 <div className="cfg-keys">
796 | MDM key | Type | Description |
797 | - | - | - |
798 | [`mcpPersistentAlwaysAllowEnabled`](/docs/third-party/claude-desktop/configuration#mcppersistentalwaysallowenabled) | `boolean` | Allow persistent tool approvals |
799 </div>
800
801 **JSON (e.g. for non-MDM users or Bootstrap):**
802
803 ```json theme={null}
804 {
805 "mcp": {
806 "persistentAlwaysAllowEnabled": "<boolean>"
807 }
808 }
809 ```
810</Update>
811
812<Update label="v1.24012.0" description="2026-07-21">
813 <div className="cfg-keys">
814 | MDM key | Type | Description |
815 | - | - | - |
816 | [`enduserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) | `boolean` | End-user attribution |
817 | [`userContentRendererUrl`](/docs/third-party/claude-desktop/configuration#usercontentrendererurl) | `string` | Artifact preview iframe origin |
818 </div>
819
820 **JSON (e.g. for non-MDM users or Bootstrap):**
821
822 ```json theme={null}
823 {
824 "deploymentDisplayName": "<string>",
825 "deploymentDisplaySubtitle": "<string>",
826 "enduserAttribution": "<boolean>",
827 "userContentRendererUrl": "<string>"
828 }
829 ```
830</Update>
831
832<Update label="v1.22209.3" description="2026-07-19">
833 No configuration changes in this release.
834</Update>
835
836<Update label="v1.22209.0" description="2026-07-16">
837 <div className="cfg-keys">
838 | MDM key | Type | Description |
839 | - | - | - |
840 | [`otlpTracesEnabled`](/docs/third-party/claude-desktop/configuration#otlptracesenabled) | `boolean` | Export traces (beta) |
841 </div>
842
843 **JSON (e.g. for non-MDM users or Bootstrap):**
844
845 ```json theme={null}
846 {
847 "otlp": {
848 "tracesEnabled": "<boolean>"
849 }
850 }
851 ```
852</Update>
853
854<Update label="v1.21459.3" description="2026-07-16">
855 No configuration changes in this release.
856</Update>
857
858<Update label="v1.21459.0" description="2026-07-14">
859 <div className="cfg-keys">
860 | MDM key | Type | Description |
861 | - | - | - |
862 | [`disableFeatureDiscovery`](/docs/third-party/claude-desktop/configuration#disablefeaturediscovery) | `boolean` | Hide feature announcements |
863 | [`inferenceModels[].prefer1m`](/docs/third-party/claude-desktop/configuration#inferencemodels) | `boolean` | New subfield: make the 1M-context variant the default picker selection when this model is the default entry. |
864 | [`managedMcpServers[].envHelper`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `string` | New subfield: helper executable that prints environment variables as JSON for a managed stdio server. |
865 | [`managedMcpServers[].envHelperTtlSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: maximum age in seconds of a cached `envHelper` result (default 300). |
866 | [`managedMcpServers[].headersHelperRefreshBufferSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: how many seconds before credential expiry the `headersHelper` re-runs (default 60). |
867 | [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) | `boolean` | Enable tool search |
868 </div>
869
870 **JSON (e.g. for non-MDM users or Bootstrap):**
871
872 ```json theme={null}
873 {
874 "featureDiscovery": {
875 "disabled": "<boolean>"
876 },
877 "workspace": {
878 "toolSearchEnabled": "<boolean>"
879 }
880 }
881 ```
882
883 **Changed:**
884
885 * `chatTabEnabled` and `chatAdvancedFileAnalysisEnabled` are no longer Beta: the Chat tab and advanced file analysis are generally available. Availability and defaults are unchanged, and both remain opt-in.
886 * `orgPluginSettings[].tools.permission` accepts a new `ask-session` value. In this release the value is accepted but behaves as `ask` (a prompt on every use); the once-per-session approval flow is not yet enabled.
887</Update>
888
889<Update label="v1.20186.9" description="2026-07-14">
890 No configuration changes in this release.
891</Update>
892
893<Update label="v1.20186.0" description="2026-07-09">
894 No configuration changes in this release.
895</Update>
896
897<Update label="v1.19367.0" description="2026-07-07">
898 <div className="cfg-keys">
899 | MDM key | Type | Description |
900 | - | - | - |
901 | [`inferenceFoundryAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencefoundryauthflow) | `enum` | Entra ID sign-in flow |
902 | [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) | `enum` | Microsoft 365 native sign-in broker |
903 | [`managedMcpServers[].startupTimeoutSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: maximum wait in seconds for the server to start and list its tools. |
904 </div>
905
906 **JSON (e.g. for non-MDM users or Bootstrap):**
907
908 ```json theme={null}
909 {
910 "inference": {
911 "credential": {
912 "authFlow": "<device-code|browser>"
913 }
914 },
915 "authentication": {
916 "microsoftAuthBroker": "<auto|disabled>"
917 }
918 }
919 ```
920
921 **Changed:**
922
923 * `isDesktopExtensionEnabled` — default changed from `true` to `false`: Desktop Extensions (`.dxt`, `.mcpb`) no longer load unless explicitly enabled.
924 * `allowedPluginMarketplaces` (beta) — can now be delivered per-user through the bootstrap server; previously MDM-only.
925</Update>
926
927<Update label="v1.18286.2" description="2026-07-07">
928 No configuration changes in this release.
929</Update>
930
931<Update label="v1.18286.0" description="2026-07-02">
932 **Removed:**
933
934 * `disableDefaultPlugins` — third-party deployments always skip the default plugin marketplaces and standard deployments always include them, so the key no longer has an effect.
935</Update>
936
937<Update label="v1.17377.2" description="2026-07-01">
938 No configuration changes in this release.
939</Update>
940
941<Update label="v1.17377.1" description="2026-06-30">
942 <div className="cfg-keys">
943 | MDM key | Type | Description |
944 | - | - | - |
945 | [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) | `object[]` | Admin-configured plugin marketplace git URLs appear under the Directory's Organization tab. (MDM-only; not settable via bootstrap JSON.) |
946 | [`inferenceVertexWorkforceOidc.omitOfflineAccess`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) | `boolean` | New subfield: omit `offline_access` from the OIDC scope request. |
947 </div>
948
949 **JSON (Non-MDM User, Bootstrap Remote):**
950
951 ```json theme={null}
952 {
953 "inference": {
954 "credential": {
955 "oidc": {
956 "omitOfflineAccess": "<boolean>"
957 }
958 }
959 }
960 }
961 ```
962</Update>
963
964<Update label="v1.15962.2" description="2026-06-30">
965 No configuration changes in this release.
966</Update>
967
968<Update label="v1.15962.1" description="2026-06-26">
969 No configuration changes in this release.
970</Update>
971
972<Update label="v1.15962.0" description="2026-06-25">
973 <div className="cfg-keys">
974 | MDM key | Type | Description |
975 | - | - | - |
976 | [`otlpContentCapture`](/docs/third-party/claude-desktop/configuration#otlpcontentcapture) | `enum[]` | Content capture categories |
977 | [`disableBundledSkills`](/docs/third-party/claude-desktop/configuration#disablebundledskills) | `boolean` | Disable bundled skills and workflows |
978 | [`managedMcpServers[].server`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `enum` | Gained `"websearch"` — managed web search (Brave, Tavily, Exa or custom) |
979 </div>
980
981 **JSON (Non-MDM User, Bootstrap Remote):**
982
983 ```json theme={null}
984 {
985 "otlp": {
986 "contentCapture": [
987 "<userPrompts|assistantResponses|toolDetails|toolContent|rawApiBodies>"
988 ]
989 },
990 "workspace": {
991 "disableBundledSkills": "<boolean>"
992 },
993 "mcp": {
994 "managedServers": [
995 {
996 "name": "Web search",
997 "server": "websearch",
998 "provider": "<brave|tavily|exa|custom>",
999 "headers": { "<header-name>": "<string>" },
1000 "customUrl": "<string, provider=custom only>"
1001 }
1002 ]
1003 }
1004 }
1005 ```
1006</Update>
1007
1008<Update label="v1.15200.0" description="2026-06-23">
1009 No configuration changes in this release.
1010</Update>
1011
1012<Update label="v1.14271.0" description="2026-06-18">
1013 <div className="cfg-keys">
1014 | MDM key | Type | Description |
1015 | - | - | - |
1016 | `chatAdvancedFileAnalysisEnabled` | `boolean` | Advanced file analysis |
1017 | `inferenceSessionLifetimeSec` | `integer` | Sign-in session lifetime |
1018 </div>
1019
1020 **JSON (Non-MDM User, Bootstrap Remote):**
1021
1022 ```json theme={null}
1023 {
1024 "chatSurface": {
1025 "advancedFileAnalysis": "<boolean>"
1026 },
1027 "inference": {
1028 "sessionLifetimeSec": "<integer>"
1029 }
1030 }
1031 ```
1032
1033 **Deprecated:**
1034
1035 * `betaFeaturesEnabled` — Allow beta features (added and deprecated in this release)
1036</Update>
1037
1038<Update label="v1.13576.0" description="2026-06-16">
1039 <div className="cfg-keys">
1040 | MDM key | Type | Description |
1041 | - | - | - |
1042 | `chatTabEnabled` | `boolean` | Allow Chat tab |
1043 | `inferenceBedrockAwsCliPath` | `string` | AWS CLI path |
1044 </div>
1045
1046 **JSON (Non-MDM User, Bootstrap Remote):**
1047
1048 ```json theme={null}
1049 {
1050 "chatSurface": {
1051 "enabled": "<boolean>"
1052 },
1053 "inference": {
1054 "awsEnv": {
1055 "awsCliPath": "<string>"
1056 }
1057 }
1058 }
1059 ```
1060</Update>
1061
1062<Update label="v1.12603.0" description="2026-06-11">
1063 <div className="cfg-keys">
1064 | MDM key | Type | Description |
1065 | - | - | - |
1066 | `inferenceVertexOAuthLoginHint` | `string` | Vertex OAuth login hint |
1067 </div>
1068
1069 **JSON (Non-MDM User, Bootstrap Remote):**
1070
1071 ```json theme={null}
1072 {
1073 "inference": {
1074 "credential": {
1075 "loginHint": "<string>"
1076 }
1077 }
1078 }
1079 ```
1080</Update>
1081
1082<Update label="v1.10628.0" description="2026-06-02">
1083 <div className="cfg-keys">
1084 | MDM key | Type | Description |
1085 | - | - | - |
1086 | `inferenceVertexWorkforceAudience` | `string` | Workforce Identity audience |
1087 | `inferenceVertexWorkforceUserProject` | `string` | Workforce Identity billing project |
1088 | `inferenceVertexWorkforceOidc` | `object` | Workforce Identity IdP (OIDC) |
1089 | `organizationPluginsUrl` | `string` | Organization plugins endpoint |
1090 | `autoModeEnabled` | `boolean` | Allow Auto mode |
1091 | `inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | Re-run helper for silent refresh |
1092 | `bootstrapEnabled` | `boolean` | Use bootstrap config |
1093 | `bootstrapUrl` | `string` | Bootstrap config URL |
1094 | `bootstrapOidc` | `object` | Bootstrap OIDC parameters |
1095 </div>
1096
1097 **JSON (Non-MDM User, Bootstrap Remote):**
1098
1099 ```json theme={null}
1100 {
1101 "inference": {
1102 "credential": {
1103 "audience": "<string>",
1104 "userProject": "<string>",
1105 "oidc": {
1106 "issuer": "<string>",
1107 "authorizationUrl": "<string>",
1108 "tokenUrl": "<string>",
1109 "clientId": "<string>",
1110 "scopes": "<string>",
1111 "redirectPort": "<integer>"
1112 },
1113 "silentRefreshEnabled": "<boolean>"
1114 }
1115 }
1116 }
1117 ```
1118</Update>
1119
1120<Update label="v1.9659.0" description="2026-05-27">
1121 <div className="cfg-keys">
1122 | MDM key | Type | Description |
1123 | - | - | - |
1124 | `coworkTabEnabled` | `boolean` | Allow Cowork tab |
1125 </div>
1126
1127 **JSON (Non-MDM User, Bootstrap Remote):**
1128
1129 ```json theme={null}
1130 {
1131 "coworkSurface": {
1132 "enabled": "<boolean>"
1133 }
1134 }
1135 ```
1136</Update>
1137
1138<Update label="v1.9255.0" description="2026-05-26">
1139 <div className="cfg-keys">
1140 | MDM key | Type | Description |
1141 | - | - | - |
1142 | `otlpDesktopLogLevel` | `enum` | Desktop telemetry export level |
1143 | `inferenceFoundryTenantId` | `string` | Entra ID tenant ID |
1144 | `inferenceFoundryClientId` | `string` | Entra ID client ID |
1145 </div>
1146
1147 **JSON (Non-MDM User, Bootstrap Remote):**
1148
1149 ```json theme={null}
1150 {
1151 "otlp": {
1152 "desktopLogLevel": "<off|error|warn|info|debug>"
1153 },
1154 "inference": {
1155 "credential": {
1156 "tenantId": "<string>",
1157 "clientId": "<string>"
1158 }
1159 }
1160 }
1161 ```
1162</Update>
1163
1164<Update label="v1.8555.0" description="2026-05-21">
1165 <div className="cfg-keys">
1166 | MDM key | Type | Description |
1167 | - | - | - |
1168 | `inferenceCredentialKind` | `enum` | Credential kind |
1169 </div>
1170
1171 **JSON (Non-MDM User, Bootstrap Remote):**
1172
1173 ```json theme={null}
1174 {
1175 "inference": {
1176 "credential": {
1177 "kind": "<static|helper-script|interactive|vendor-profile>"
1178 }
1179 }
1180 }
1181 ```
1182</Update>
1183
1184<Update label="v1.8089.0" description="2026-05-19">
1185 <div className="cfg-keys">
1186 | MDM key | Type | Description |
1187 | - | - | - |
1188 | `inferenceAnthropicApiKey` | `string` | Claude API key |
1189 | `inferenceCustomHeaders` | `object` | Custom inference headers (renamed from `inferenceGatewayHeaders`) |
1190 | `modelDiscoveryEnabled` | `boolean` | Model discovery |
1191 | `orgPluginSettings` | `object` | Organization plugin settings |
1192 | `builtinToolPolicy` | `object` | Built-in tool policy |
1193 | `inferenceCredentialHelperTimeoutSec` | `integer` | Credential helper timeout |
1194 </div>
1195
1196 **JSON (Non-MDM User, Bootstrap Remote):**
1197
1198 ```json theme={null}
1199 {
1200 "inference": {
1201 "credential": {
1202 "apiKey": "<string>",
1203 "timeoutSec": "<integer>"
1204 },
1205 "customHeaders": "<object>"
1206 }
1207 }
1208 ```
1209</Update>
1210
1211<Update label="v1.7196.0" description="2026-05-12">
1212 <div className="cfg-keys">
1213 | MDM key | Type | Description |
1214 | - | - | - |
1215 | `banner` | `object` | Organization banner |
1216 </div>
1217</Update>
1218
1219<Update label="v1.6889.0" description="2026-05-08">
1220 <div className="cfg-keys">
1221 | MDM key | Type | Description |
1222 | - | - | - |
1223 | `disableDeepLinkRegistration` | `boolean` | Disable claude:// deep-link handling |
1224 | `inferenceGatewayOidc` | `object` | Gateway SSO IdP (OIDC) |
1225 </div>
1226
1227 **JSON (Non-MDM User, Bootstrap Remote):**
1228
1229 ```json theme={null}
1230 {
1231 "inference": {
1232 "credential": {
1233 "oidc": {
1234 "issuer": "<string>",
1235 "authorizationUrl": "<string>",
1236 "tokenUrl": "<string>",
1237 "clientId": "<string>",
1238 "scopes": "<string>",
1239 "redirectPort": "<integer>",
1240 "bearerTokenType": "<id_token|access_token>",
1241 "appendOfflineAccess": "<boolean>"
1242 }
1243 }
1244 }
1245 }
1246 ```
1247</Update>
1248
1249<Update label="v1.6259.0" description="2026-05-05">
1250 <div className="cfg-keys">
1251 | MDM key | Type | Description |
1252 | - | - | - |
1253 | `inferenceBedrockSsoStartUrl` | `string` | AWS SSO start URL |
1254 | `inferenceBedrockSsoRegion` | `string` | AWS SSO region |
1255 | `inferenceBedrockSsoAccountId` | `string` | AWS SSO account ID |
1256 | `inferenceBedrockSsoRoleName` | `string` | AWS SSO role name |
1257 </div>
1258
1259 **JSON (Non-MDM User, Bootstrap Remote):**
1260
1261 ```json theme={null}
1262 {
1263 "inference": {
1264 "credential": {
1265 "ssoStartUrl": "<string>",
1266 "ssoRegion": "<string>",
1267 "ssoAccountId": "<string>",
1268 "ssoRoleName": "<string>"
1269 }
1270 }
1271 }
1272 ```
1273</Update>
1274
1275<Update label="v1.5354.0" description="2026-04-29">
1276 <div className="cfg-keys">
1277 | MDM key | Type | Description |
1278 | - | - | - |
1279 | `otlpResourceAttributes` | `object` | OpenTelemetry resource attributes |
1280 </div>
1281
1282 **JSON (Non-MDM User, Bootstrap Remote):**
1283
1284 ```json theme={null}
1285 {
1286 "otlp": {
1287 "resourceAttributes": "<object>"
1288 }
1289 }
1290 ```
1291</Update>
1292
1293<Update label="v1.5186.0" description="2026-04-28">
1294 <div className="cfg-keys">
1295 | MDM key | Type | Description |
1296 | - | - | - |
1297 | `inferenceBedrockServiceTier` | `enum` | Bedrock service tier |
1298 </div>
1299
1300 **JSON (Non-MDM User, Bootstrap Remote):**
1301
1302 ```json theme={null}
1303 {
1304 "inference": {
1305 "serviceTier": "<flex|priority>"
1306 }
1307 }
1308 ```
1309</Update>
1310
1311<Update label="v1.3834.0" description="2026-04-21">
1312 <div className="cfg-keys">
1313 | MDM key | Type | Description |
1314 | - | - | - |
1315 | `disableDeploymentModeChooser` | `boolean` | Disable Claude.ai sign-in |
1316 </div>
1317</Update>
1318
1319<Update label="v1.3036.0" description="2026-04-16">
1320 <div className="cfg-keys">
1321 | MDM key | Type | Description |
1322 | - | - | - |
1323 | `inferenceGatewayAuthScheme` | `enum` | Gateway auth scheme |
1324 </div>
1325
1326 **JSON (Non-MDM User, Bootstrap Remote):**
1327
1328 ```json theme={null}
1329 {
1330 "inference": {
1331 "credential": {
1332 "authScheme": "<auto|x-api-key|bearer|sso>"
1333 }
1334 }
1335 }
1336 ```
1337</Update>
1338
1339<Update label="Baseline">
1340 <div className="cfg-keys">
1341 | MDM key | Type | Description |
1342 | - | - | - |
1343 | `isDesktopExtensionEnabled` | `boolean` | Allow desktop extensions (renamed from `isDxtEnabled`) |
1344 | `isDesktopExtensionSignatureRequired` | `boolean` | Require signed extensions (renamed from `isDxtSignatureRequired`) |
1345 | `isLocalDevMcpEnabled` | `boolean` | Allow user-added MCP servers |
1346 | `isClaudeCodeForDesktopEnabled` | `boolean` | Allow Claude Code tab |
1347 | `coworkEgressAllowedHosts` | `array<string>` | Allowed egress hosts |
1348 | `otlpEndpoint` | `string` | OpenTelemetry collector endpoint |
1349 | `otlpProtocol` | `enum` | OpenTelemetry exporter protocol |
1350 | `otlpHeaders` | `object` | OpenTelemetry exporter headers |
1351 | `autoUpdaterEnforcementHours` | `integer` | Auto-update enforcement window |
1352 | `disableAutoUpdates` | `boolean` | Block auto-updates |
1353 | `inferenceProvider` | `enum` | Inference provider |
1354 | `inferenceGatewayBaseUrl` | `string` | Gateway base URL |
1355 | `inferenceGatewayApiKey` | `string` | Gateway API key |
1356 | `inferenceVertexProjectId` | `string` | GCP project ID |
1357 | `inferenceVertexRegion` | `string` | GCP region |
1358 | `inferenceVertexCredentialsFile` | `string` | GCP credentials file path |
1359 | `inferenceVertexOAuthClientId` | `string` | Vertex OAuth client ID |
1360 | `inferenceVertexOAuthClientSecret` | `string` | Vertex OAuth client secret |
1361 | `inferenceVertexOAuthScopes` | `string` | Vertex OAuth scopes |
1362 | `inferenceVertexBaseUrl` | `string` | Vertex AI base URL |
1363 | `inferenceBedrockRegion` | `string` | AWS region |
1364 | `inferenceBedrockBearerToken` | `string` | AWS bearer token |
1365 | `inferenceBedrockBaseUrl` | `string` | Bedrock base URL |
1366 | `inferenceBedrockProfile` | `string` | AWS profile name |
1367 | `inferenceBedrockAwsDir` | `string` | AWS config directory |
1368 | `inferenceFoundryResource` | `string` | Azure AI Foundry resource name |
1369 | `inferenceFoundryApiKey` | `string` | Azure AI Foundry API key |
1370 | `inferenceModels` | `array<string\|object>` | Model list |
1371 | `deploymentOrganizationUuid` | `string` | Organization UUID |
1372 | `disableEssentialTelemetry` | `boolean` | Block essential telemetry |
1373 | `disableNonessentialTelemetry` | `boolean` | Block nonessential telemetry |
1374 | `disableNonessentialServices` | `boolean` | Block nonessential services |
1375 | `managedMcpServers` | `array<object\|object\|object\|null>` | Managed MCP servers |
1376 | `disabledBuiltinTools` | `array<string>` | Disabled built-in tools |
1377 | `allowedWorkspaceFolders` | `array<string\|object>` | Allowed workspace folders |
1378 | `inferenceCredentialHelper` | `string` | Helper script |
1379 | `inferenceCredentialHelperTtlSec` | `integer` | Helper script TTL |
1380 | `inferenceMaxTokensPerWindow` | `integer` | Max tokens per window |
1381 | `inferenceTokenWindowHours` | `integer` | Token cap window |
1382 </div>
1383
1384 **Deprecated:**
1385
1386 * `requireCoworkFullVmSandbox` — Require full VM sandbox
1387</Update>
1172 }
1173 }
1174}
1175```
1176
1177**v1.6259.0**
1178
1179| MDM key | Type | Description |
1180| - | - | - |
1181| `inferenceBedrockSsoStartUrl` | `string` | AWS SSO start URL |
1182| `inferenceBedrockSsoRegion` | `string` | AWS SSO region |
1183| `inferenceBedrockSsoAccountId` | `string` | AWS SSO account ID |
1184| `inferenceBedrockSsoRoleName` | `string` | AWS SSO role name |
1185
1186**JSON (Non-MDM User, Bootstrap Remote):**
1187
1188```json theme={null}
1189{
1190 "inference": {
1191 "credential": {
1192 "ssoStartUrl": "<string>",
1193 "ssoRegion": "<string>",
1194 "ssoAccountId": "<string>",
1195 "ssoRoleName": "<string>"
1196 }
1197 }
1198}
1199```
1200
1201**v1.5354.0**
1202
1203| MDM key | Type | Description |
1204| - | - | - |
1205| `otlpResourceAttributes` | `object` | OpenTelemetry resource attributes |
1206
1207**JSON (Non-MDM User, Bootstrap Remote):**
1208
1209```json theme={null}
1210{
1211 "otlp": {
1212 "resourceAttributes": "<object>"
1213 }
1214}
1215```
1216
1217**v1.5186.0**
1218
1219| MDM key | Type | Description |
1220| - | - | - |
1221| `inferenceBedrockServiceTier` | `enum` | Bedrock service tier |
1222
1223**JSON (Non-MDM User, Bootstrap Remote):**
1224
1225```json theme={null}
1226{
1227 "inference": {
1228 "serviceTier": "<flex|priority>"
1229 }
1230}
1231```
1232
1233**v1.3834.0**
1234
1235| MDM key | Type | Description |
1236| - | - | - |
1237| `disableDeploymentModeChooser` | `boolean` | Disable Claude.ai sign-in |
1238
1239**v1.3036.0**
1240
1241| MDM key | Type | Description |
1242| - | - | - |
1243| `inferenceGatewayAuthScheme` | `enum` | Gateway auth scheme |
1244
1245**JSON (Non-MDM User, Bootstrap Remote):**
1246
1247```json theme={null}
1248{
1249 "inference": {
1250 "credential": {
1251 "authScheme": "<auto|x-api-key|bearer|sso>"
1252 }
1253 }
1254}
1255```
1256
1257**Baseline**
1258
1259| MDM key | Type | Description |
1260| - | - | - |
1261| `isDesktopExtensionEnabled` | `boolean` | Allow desktop extensions (renamed from `isDxtEnabled`) |
1262| `isDesktopExtensionSignatureRequired` | `boolean` | Require signed extensions (renamed from `isDxtSignatureRequired`) |
1263| `isLocalDevMcpEnabled` | `boolean` | Allow user-added MCP servers |
1264| `isClaudeCodeForDesktopEnabled` | `boolean` | Allow Claude Code tab |
1265| `coworkEgressAllowedHosts` | `array<string>` | Allowed egress hosts |
1266| `otlpEndpoint` | `string` | OpenTelemetry collector endpoint |
1267| `otlpProtocol` | `enum` | OpenTelemetry exporter protocol |
1268| `otlpHeaders` | `object` | OpenTelemetry exporter headers |
1269| `autoUpdaterEnforcementHours` | `integer` | Auto-update enforcement window |
1270| `disableAutoUpdates` | `boolean` | Block auto-updates |
1271| `inferenceProvider` | `enum` | Inference provider |
1272| `inferenceGatewayBaseUrl` | `string` | Gateway base URL |
1273| `inferenceGatewayApiKey` | `string` | Gateway API key |
1274| `inferenceVertexProjectId` | `string` | GCP project ID |
1275| `inferenceVertexRegion` | `string` | GCP region |
1276| `inferenceVertexCredentialsFile` | `string` | GCP credentials file path |
1277| `inferenceVertexOAuthClientId` | `string` | Vertex OAuth client ID |
1278| `inferenceVertexOAuthClientSecret` | `string` | Vertex OAuth client secret |
1279| `inferenceVertexOAuthScopes` | `string` | Vertex OAuth scopes |
1280| `inferenceVertexBaseUrl` | `string` | Vertex AI base URL |
1281| `inferenceBedrockRegion` | `string` | AWS region |
1282| `inferenceBedrockBearerToken` | `string` | AWS bearer token |
1283| `inferenceBedrockBaseUrl` | `string` | Bedrock base URL |
1284| `inferenceBedrockProfile` | `string` | AWS profile name |
1285| `inferenceBedrockAwsDir` | `string` | AWS config directory |
1286| `inferenceFoundryResource` | `string` | Azure AI Foundry resource name |
1287| `inferenceFoundryApiKey` | `string` | Azure AI Foundry API key |
1288| `inferenceModels` | `array<string\|object>` | Model list |
1289| `deploymentOrganizationUuid` | `string` | Organization UUID |
1290| `disableEssentialTelemetry` | `boolean` | Block essential telemetry |
1291| `disableNonessentialTelemetry` | `boolean` | Block nonessential telemetry |
1292| `disableNonessentialServices` | `boolean` | Block nonessential services |
1293| `managedMcpServers` | `array<object\|object\|object\|null>` | Managed MCP servers |
1294| `disabledBuiltinTools` | `array<string>` | Disabled built-in tools |
1295| `allowedWorkspaceFolders` | `array<string\|object>` | Allowed workspace folders |
1296| `inferenceCredentialHelper` | `string` | Helper script |
1297| `inferenceCredentialHelperTtlSec` | `integer` | Helper script TTL |
1298| `inferenceMaxTokensPerWindow` | `integer` | Max tokens per window |
1299| `inferenceTokenWindowHours` | `integer` | Token cap window |
1300
1301**Deprecated:**
1302
1303* `requireCoworkFullVmSandbox` — Require full VM sandbox
13881304
third-party/claude-desktop/connectors-box Changed · +46 / -48 lines
from line 10
1010
1111## Set up the Box server
1212
13<Steps>
14 <Step title="Create the client in Box">
15 In the Box Admin Console, create integration credentials for the Box MCP server as described in Box's [remote MCP server guide](https://developer.box.com/guides/box-mcp/remote), with `http://127.0.0.1:53280/callback` as the redirect URI, and copy the generated client ID and client secret.
16 </Step>
13**1. Create the client in Box**
1714
18 <Step title="Install the secret helper script on every device">
19 Write a script that prints the client secret as the JSON object `{"clientSecret": "…"}` and nothing else on stdout (the full contract is under [Where the client secret goes](/docs/third-party/claude-desktop/mcp-sign-in#where-the-client-secret-goes)). On macOS, save the script (for example at `/usr/local/bin/box-mcp-secret`) and mark it executable:
15In the Box Admin Console, create integration credentials for the Box MCP server as described in Box's [remote MCP server guide](https://developer.box.com/guides/box-mcp/remote), with `http://127.0.0.1:53280/callback` as the redirect URI, and copy the generated client ID and client secret.
2016
21 ```bash theme={null}
22 #!/bin/sh
23 printf '{"clientSecret":"%s"}' "YOUR_BOX_CLIENT_SECRET"
24 ```
17**2. Install the secret helper script on every device**
2518
26 On Windows, save it as a `.cmd` file, for example `C:\Program Files\Corp\box-mcp-secret.cmd`:
19Write a script that prints the client secret as the JSON object `{"clientSecret": "…"}` and nothing else on stdout (the full contract is under [Where the client secret goes](/docs/third-party/claude-desktop/mcp-sign-in#where-the-client-secret-goes)). On macOS, save the script (for example at `/usr/local/bin/box-mcp-secret`) and mark it executable:
2720
28 ```bat theme={null}
29 @echo off
30 echo {"clientSecret":"YOUR_BOX_CLIENT_SECRET"}
31 ```
21```bash theme={null}
22#!/bin/sh
23printf '{"clientSecret":"%s"}' "YOUR_BOX_CLIENT_SECRET"
24```
3225
33 A secret written into the script is readable by anyone who can read the file. Where your devices have a secret store or vault CLI, have the script read the secret from there instead.
26On Windows, save it as a `.cmd` file, for example `C:\Program Files\Corp\box-mcp-secret.cmd`:
3427
35 Distribute the script through your device management to the same absolute path on every device, in a location users can't modify. An entry holds one path for the whole organization, so if your fleet mixes macOS and Windows, add one entry per platform with its own name and script path, and assign each to the matching group of users with [per-group permission policies](/docs/third-party/claude-desktop/admin-console#per-group-permission-policies).
36 </Step>
28```bat theme={null}
29@echo off
30echo {"clientSecret":"YOUR_BOX_CLIENT_SECRET"}
31```
3732
38 <Step title="Add the server in the Enterprise Admin Console">
39 In the Enterprise Admin Console ([claude.ai](https://claude.ai) → **Organization settings**), open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank** and fill in the entry:
33A secret written into the script is readable by anyone who can read the file. Where your devices have a secret store or vault CLI, have the script read the secret from there instead.
4034
41 | Field | Value |
42 | - | - |
43 | **Name** | `Box` |
44 | **Transport** | **Streamable HTTP** |
45 | **URL** | `https://mcp.box.com` |
46 | **OAuth** | **Bring your own client** |
47 | **Client ID** | The client ID from step 1 |
48 | **Client secret helper script** | The script's absolute path from step 2, for example `/usr/local/bin/box-mcp-secret` |
49 | **Authorization server** | `["https://api.box.com"]` |
35Distribute the script through your device management to the same absolute path on every device, in a location users can't modify. An entry holds one path for the whole organization, so if your fleet mixes macOS and Windows, add one entry per platform with its own name and script path, and assign each to the matching group of users with [per-group permission policies](/docs/third-party/claude-desktop/admin-console#per-group-permission-policies).
5036
51 Click **Save changes**. Users' apps pick up the new entry as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates). Devices need outbound HTTPS access to `mcp.box.com`, `account.box.com`, and `api.box.com`.
37**3. Add the server in the Enterprise Admin Console**
5238
53 If you manage configuration through MDM or a bootstrap server instead, the equivalent entry can carry the secret inline:
39In the Enterprise Admin Console ([claude.ai](https://claude.ai) → **Organization settings**), open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank** and fill in the entry:
5440
55 ```json theme={null}
56 {
57 "name": "Box",
58 "transport": "http",
59 "url": "https://mcp.box.com",
60 "oauth": {
61 "clientId": "YOUR_BOX_CLIENT_ID",
62 "clientSecret": "YOUR_BOX_CLIENT_SECRET",
63 "authorizationServer": ["https://api.box.com"]
64 }
65 }
66 ```
67 </Step>
41| Field | Value |
42| - | - |
43| **Name** | `Box` |
44| **Transport** | **Streamable HTTP** |
45| **URL** | `https://mcp.box.com` |
46| **OAuth** | **Bring your own client** |
47| **Client ID** | The client ID from step 1 |
48| **Client secret helper script** | The script's absolute path from step 2, for example `/usr/local/bin/box-mcp-secret` |
49| **Authorization server** | `["https://api.box.com"]` |
6850
69 <Step title="Have users connect">
70 Each user opens **Customize → Connectors** in Claude Desktop, clicks **Connect** next to **Box**, and signs in to Box in the browser.
71 </Step>
72</Steps>
51Click **Save changes**. Users' apps pick up the new entry as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates). Devices need outbound HTTPS access to `mcp.box.com`, `account.box.com`, and `api.box.com`.
52
53If you manage configuration through MDM or a bootstrap server instead, the equivalent entry can carry the secret inline:
54
55```json theme={null}
56{
57 "name": "Box",
58 "transport": "http",
59 "url": "https://mcp.box.com",
60 "oauth": {
61 "clientId": "YOUR_BOX_CLIENT_ID",
62 "clientSecret": "YOUR_BOX_CLIENT_SECRET",
63 "authorizationServer": ["https://api.box.com"]
64 }
65}
66```
67
68**4. Have users connect**
69
70Each user opens **Customize → Connectors** in Claude Desktop, clicks **Connect** next to **Box**, and signs in to Box in the browser.
7371
third-party/claude-desktop/connectors-github Changed · +38 / -40 lines
from line 42
4242
4343### Set up the local connector
4444
45<Steps>
46 <Step title="Register a GitHub OAuth app">
47 In your GitHub organization, open **Settings → Developer settings → OAuth Apps → New OAuth App** and register an app for Claude Desktop:
45**1. Register a GitHub OAuth app**
4846
49 1. Set **Application name** and **Homepage URL** to values your users will recognize on the authorization screen.
50 2. Enter any valid URL as the **Authorization callback URL**. The device flow does not use a redirect, but GitHub requires the field.
51 3. After registering, select **Enable Device Flow** on the app's settings page and save. Sign-in fails without it.
52 4. Note the app's **Client ID**. Do not create a client secret; the device flow does not use one, and Claude Desktop never asks for it.
47In your GitHub organization, open **Settings → Developer settings → OAuth Apps → New OAuth App** and register an app for Claude Desktop:
5348
54 A GitHub App works in place of an OAuth app: put its client ID in the same field. Its permissions come from the app registration itself (the entry's `scope` field is ignored), it must be installed where users need access, and its user tokens expire after about eight hours, so users sign in again more often than with an OAuth app.
55 </Step>
491. Set **Application name** and **Homepage URL** to values your users will recognize on the authorization screen.
502. Enter any valid URL as the **Authorization callback URL**. The device flow does not use a redirect, but GitHub requires the field.
513. After registering, select **Enable Device Flow** on the app's settings page and save. Sign-in fails without it.
524. Note the app's **Client ID**. Do not create a client secret; the device flow does not use one, and Claude Desktop never asks for it.
5653
57 <Step title="Add the managed entry">
58 In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server**, and choose **GitHub** under the **Built-in** group. Enter the client ID from step 1, select **Test this connection** to verify that the bundled server starts and lists its tools, and select **Save**.
54A GitHub App works in place of an OAuth app: put its client ID in the same field. Its permissions come from the app registration itself (the entry's `scope` field is ignored), it must be installed where users need access, and its user tokens expire after about eight hours, so users sign in again more often than with an OAuth app.
5955
60 If you manage configuration through JSON or a plist directly, add an entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) with the `server` field set to `github`:
56**2. Add the managed entry**
6157
62 ```json theme={null}
63 {
64 "name": "GitHub",
65 "server": "github",
66 "clientId": "OAUTH_APP_CLIENT_ID_FROM_STEP_1"
67 }
68 ```
58In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server**, and choose **GitHub** under the **Built-in** group. Enter the client ID from step 1, select **Test this connection** to verify that the bundled server starts and lists its tools, and select **Save**.
6959
70 | Field | Required | Description |
71 | - | - | - |
72 | `name` | Yes | Unique display name, shown to users in connector settings. |
73 | `server` | Yes | Must be `github`. |
74 | `clientId` | Yes | The client ID of the OAuth app (or GitHub App) from step 1. |
75 | `host` | No | Base URL of your GitHub Enterprise Server instance, for example `https://github.example.com`. Leave unset for github.com. HTTPS is required. |
76 | `scope` | No | Space-separated OAuth scopes to request at sign-in, for example `repo read:org`. Defaults to `repo read:org read:user`. Ignored for GitHub Apps. |
77 | `toolsets` | No | Comma-separated [github-mcp-server toolsets](https://github.com/github/github-mcp-server) to enable, for example `context,repos,issues,pull_requests`. Defaults to the bundled server's default toolsets. |
78 | `readOnly` | No | `true` starts the server with read tools only; write tools are not registered at all. |
79 | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |
60If you manage configuration through JSON or a plist directly, add an entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) with the `server` field set to `github`:
8061
81 In the in-app configuration window, the GitHub form offers the client ID, GitHub Enterprise Server URL, toolsets, and read-only fields; set `scope` through exported JSON or your device-management tool if you need a non-default scope set.
82 </Step>
62```json theme={null}
63{
64 "name": "GitHub",
65 "server": "github",
66 "clientId": "OAUTH_APP_CLIENT_ID_FROM_STEP_1"
67}
68```
8369
84 <Step title="Allow the required network hosts">
85 The server and the sign-in flow call GitHub directly from the device, so in addition to the [base egress hosts](/docs/third-party/claude-desktop/telemetry#required-egress-paths), devices need outbound HTTPS access to:
70| Field | Required | Description |
71| - | - | - |
72| `name` | Yes | Unique display name, shown to users in connector settings. |
73| `server` | Yes | Must be `github`. |
74| `clientId` | Yes | The client ID of the OAuth app (or GitHub App) from step 1. |
75| `host` | No | Base URL of your GitHub Enterprise Server instance, for example `https://github.example.com`. Leave unset for github.com. HTTPS is required. |
76| `scope` | No | Space-separated OAuth scopes to request at sign-in, for example `repo read:org`. Defaults to `repo read:org read:user`. Ignored for GitHub Apps. |
77| `toolsets` | No | Comma-separated [github-mcp-server toolsets](https://github.com/github/github-mcp-server) to enable, for example `context,repos,issues,pull_requests`. Defaults to the bundled server's default toolsets. |
78| `readOnly` | No | `true` starts the server with read tools only; write tools are not registered at all. |
79| `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |
8680
87 | Host | Purpose |
88 | - | - |
89 | `github.com` | OAuth device-flow sign-in |
90 | `api.github.com` | GitHub API calls |
81In the in-app configuration window, the GitHub form offers the client ID, GitHub Enterprise Server URL, toolsets, and read-only fields; set `scope` through exported JSON or your device-management tool if you need a non-default scope set.
9182
92 GitHub Enterprise Server deployments need access to the instance's own host instead. No egress to any Anthropic host is needed for GitHub data.
93 </Step>
94</Steps>
83**3. Allow the required network hosts**
84
85The server and the sign-in flow call GitHub directly from the device, so in addition to the [base egress hosts](/docs/third-party/claude-desktop/telemetry#required-egress-paths), devices need outbound HTTPS access to:
86
87| Host | Purpose |
88| - | - |
89| `github.com` | OAuth device-flow sign-in |
90| `api.github.com` | GitHub API calls |
91
92GitHub Enterprise Server deployments need access to the instance's own host instead. No egress to any Anthropic host is needed for GitHub data.
9593
9694### How users sign in
9795
third-party/claude-desktop/connectors-google-cloud Changed · +37 / -41 lines
from line 10
1010
1111## Set up the BigQuery server
1212
13<Steps>
14 <Step title="Prepare the Google Cloud project">
15 In the Google Cloud project that holds your BigQuery data, enable the BigQuery MCP server and grant each user the **MCP Tool User** role (`roles/mcp.toolUser`) together with the BigQuery roles their queries need. Google's [Use the BigQuery MCP server](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp) guide covers both.
16 </Step>
13**1. Prepare the Google Cloud project**
1714
18 <Step title="Create a Desktop-app OAuth client in Google Cloud">
19 If the project has no OAuth consent screen, configure one first in the Google Cloud Console under **APIs & Services → OAuth consent screen**. Choose the **Internal** user type when all users are in your Google Workspace organization. With **External**, add every user as a test user while the app is in testing, or Google blocks their sign-in.
15In the Google Cloud project that holds your BigQuery data, enable the BigQuery MCP server and grant each user the **MCP Tool User** role (`roles/mcp.toolUser`) together with the BigQuery roles their queries need. Google's [Use the BigQuery MCP server](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp) guide covers both.
2016
21 Then open **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type. When Google shows the new client, copy its **Client ID** (ends in `.apps.googleusercontent.com`) and **Client secret** (begins with `GOCSPX-`). You don't add redirect URIs, because Desktop-app clients accept loopback redirects automatically.
22 </Step>
17**2. Create a Desktop-app OAuth client in Google Cloud**
2318
24 <Step title="Add the server in the Enterprise Admin Console">
25 In the Enterprise Admin Console ([claude.ai](https://claude.ai) → **Organization settings**), open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank** and fill in the entry:
19If the project has no OAuth consent screen, configure one first in the Google Cloud Console under **APIs & Services → OAuth consent screen**. Choose the **Internal** user type when all users are in your Google Workspace organization. With **External**, add every user as a test user while the app is in testing, or Google blocks their sign-in.
2620
27 | Field | Value |
28 | - | - |
29 | **Name** | `BigQuery` |
30 | **Transport** | **Streamable HTTP** |
31 | **URL** | `https://bigquery.googleapis.com/mcp` |
32 | **OAuth** | **Bring your own client** |
33 | **Client ID** | The client ID from step 2 |
34 | **Client secret** | The client secret from step 2 |
35 | **Authorization server** | `["https://accounts.google.com"]` |
21Then open **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type. When Google shows the new client, copy its **Client ID** (ends in `.apps.googleusercontent.com`) and **Client secret** (begins with `GOCSPX-`). You don't add redirect URIs, because Desktop-app clients accept loopback redirects automatically.
3622
37 <Frame caption="A BigQuery entry on the Connectors page with OAuth set to Bring your own client.">
38 <img src="https://mintcdn.com/claude-ai/l0HgWAJ4dDJ1-I-u/images/third-party/admin-console-managed-mcp-oauth.png?fit=max&auto=format&n=l0HgWAJ4dDJ1-I-u&q=85&s=efa91a216efb8f99c1e4aefc0ed5b16a" alt="Managed MCP server entry named BigQuery in the Enterprise Admin Console, with Transport set to Streamable HTTP, the BigQuery MCP URL, OAuth set to Bring your own client, and the Client ID, Client secret, and Authorization server fields filled in." width="1952" height="1705" data-path="images/third-party/admin-console-managed-mcp-oauth.png" />
39 </Frame>
23**3. Add the server in the Enterprise Admin Console**
4024
41 Click **Save changes**. Users' apps pick up the new entry as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates). Devices need outbound HTTPS access to `bigquery.googleapis.com`, `accounts.google.com`, and `oauth2.googleapis.com`.
25In the Enterprise Admin Console ([claude.ai](https://claude.ai) → **Organization settings**), open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank** and fill in the entry:
4226
43 If you manage configuration through MDM or a bootstrap server instead, the equivalent [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry is:
27| Field | Value |
28| - | - |
29| **Name** | `BigQuery` |
30| **Transport** | **Streamable HTTP** |
31| **URL** | `https://bigquery.googleapis.com/mcp` |
32| **OAuth** | **Bring your own client** |
33| **Client ID** | The client ID from step 2 |
34| **Client secret** | The client secret from step 2 |
35| **Authorization server** | `["https://accounts.google.com"]` |
4436
45 ```json theme={null}
46 {
47 "name": "BigQuery",
48 "transport": "http",
49 "url": "https://bigquery.googleapis.com/mcp",
50 "oauth": {
51 "clientId": "CLIENT_ID.apps.googleusercontent.com",
52 "clientSecret": "GOCSPX-YOUR_CLIENT_SECRET",
53 "authorizationServer": ["https://accounts.google.com"]
54 }
55 }
56 ```
57 </Step>
37
5838
59 <Step title="Have users connect">
60 Each user opens **Customize → Connectors** in Claude Desktop, clicks **Connect** next to **BigQuery**, and approves Google's consent screen in the browser. Claude Desktop asks Google for offline access automatically, so the token refreshes in the background without another sign-in.
61 </Step>
62</Steps>
39Click **Save changes**. Users' apps pick up the new entry as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates). Devices need outbound HTTPS access to `bigquery.googleapis.com`, `accounts.google.com`, and `oauth2.googleapis.com`.
40
41If you manage configuration through MDM or a bootstrap server instead, the equivalent [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry is:
42
43```json theme={null}
44{
45 "name": "BigQuery",
46 "transport": "http",
47 "url": "https://bigquery.googleapis.com/mcp",
48 "oauth": {
49 "clientId": "CLIENT_ID.apps.googleusercontent.com",
50 "clientSecret": "GOCSPX-YOUR_CLIENT_SECRET",
51 "authorizationServer": ["https://accounts.google.com"]
52 }
53}
54```
55
56**4. Have users connect**
57
58Each user opens **Customize → Connectors** in Claude Desktop, clicks **Connect** next to **BigQuery**, and approves Google's consent screen in the browser. Claude Desktop asks Google for offline access automatically, so the token refreshes in the background without another sign-in.
6359
6460## Other Google servers
6561
third-party/claude-desktop/connectors-m365 Changed · +179 / -185 lines
from line 2
22
33> Give Claude access to your organization's Outlook, OneDrive, SharePoint, and Teams data through a connector you register in your own Microsoft Entra tenant.
44
5<Info>
6 The remote connector is hosted by Anthropic. Data in transit passes through Anthropic's infrastructure, which is based in the United States. Anthropic does not collect or store any data that transits through the server. To keep all Microsoft 365 traffic between the user's device and Microsoft instead, use the [local connector](#local-connector).
7</Info>
5> [!NOTE]
6>
7> The remote connector is hosted by Anthropic. Data in transit passes through Anthropic's infrastructure, which is based in the United States. Anthropic does not collect or store any data that transits through the server. To keep all Microsoft 365 traffic between the user's device and Microsoft instead, use the [local connector](#local-connector).
88
99When Claude Desktop is deployed on third-party inference, Claude can read your organization's Microsoft 365 data (Outlook mail and calendar, OneDrive, SharePoint, and Teams) through a connector registered in your own Microsoft Entra tenant. Two connectors are available: a [remote connector](#remote-connector) hosted by Anthropic, and a [local connector](#local-connector) built into the desktop app.
1010
from line 54
5454
5555The four steps below cover tenant consent, app registration, allowlisting, and desktop configuration.
5656
57<Steps>
58 <Step title="Consent the Anthropic connector app into your tenant">
59 A tenant administrator must consent to Anthropic's multi-tenant connector app once for the organization. This creates a service principal in your tenant; no secret is exchanged.
57**1. Consent the Anthropic connector app into your tenant**
6058
61 Open the following URL after replacing `YOUR_TENANT_ID` with the Directory (tenant) ID shown in **Entra admin center → Overview**.
59A tenant administrator must consent to Anthropic's multi-tenant connector app once for the organization. This creates a service principal in your tenant; no secret is exchanged.
6260
63 ```text theme={null}
64 https://login.microsoftonline.com/YOUR_TENANT_ID/adminconsent?client_id=07c030f6-5743-41b7-ba00-0a6e85f37c17
65 ```
61Open the following URL after replacing `YOUR_TENANT_ID` with the Directory (tenant) ID shown in **Entra admin center → Overview**.
6662
67 The consent screen lists the delegated Microsoft Graph permissions the connector requests. The read permissions include:
63```text theme={null}
64https://login.microsoftonline.com/YOUR_TENANT_ID/adminconsent?client_id=07c030f6-5743-41b7-ba00-0a6e85f37c17
65```
6866
69 | Scope | Purpose |
70 | - | - |
71 | `User.Read` | Read the signed-in user's profile |
72 | `Mail.Read`, `Mail.Read.Shared` | Read mail in the user's and shared mailboxes |
73 | `Calendars.Read`, `Calendars.Read.Shared` | Read events in the user's and shared calendars |
74 | `Files.Read.All` | Read files the user can access in OneDrive and SharePoint |
75 | `Sites.Read.All` | Read SharePoint site content the user can access |
76 | `Chat.Read`, `ChatMessage.Read` | Read Teams chat messages the user can access |
77 | `offline_access` | Allow the desktop to refresh its token without re-prompting |
67The consent screen lists the delegated Microsoft Graph permissions the connector requests. The read permissions include:
7868
79 The screen also lists the write permissions, such as `Mail.Send` and `Files.ReadWrite.All`. Accepting approves the whole list for every user in your tenant, which makes write actions available to every remote connector user. To keep the connector read-only or limit write actions to specific users, accept, then revoke the write scopes before you deploy the configuration in step 4. See [Control write actions on the remote connector](#control-write-actions-on-the-remote-connector).
69| Scope | Purpose |
70| - | - |
71| `User.Read` | Read the signed-in user's profile |
72| `Mail.Read`, `Mail.Read.Shared` | Read mail in the user's and shared mailboxes |
73| `Calendars.Read`, `Calendars.Read.Shared` | Read events in the user's and shared calendars |
74| `Files.Read.All` | Read files the user can access in OneDrive and SharePoint |
75| `Sites.Read.All` | Read SharePoint site content the user can access |
76| `Chat.Read`, `ChatMessage.Read` | Read Teams chat messages the user can access |
77| `offline_access` | Allow the desktop to refresh its token without re-prompting |
8078
81 Review the permissions and select **Accept**.
79The screen also lists the write permissions, such as `Mail.Send` and `Files.ReadWrite.All`. Accepting approves the whole list for every user in your tenant, which makes write actions available to every remote connector user. To keep the connector read-only or limit write actions to specific users, accept, then revoke the write scopes before you deploy the configuration in step 4. See [Control write actions on the remote connector](#control-write-actions-on-the-remote-connector).
8280
83 <Note>
84 FedRAMP and GovCloud deployments use a different connector app ID and a
85 different connector service hostname. Contact your Anthropic representative
86 for the app ID to use in this URL and in the scope string in step 4, and for
87 the connector URL to use in step 4.
88 </Note>
89 </Step>
81Review the permissions and select **Accept**.
9082
91 <Step title="Register a desktop client app in your tenant">
92 Create the public client that Claude Desktop will sign in as.
83> [!NOTE]
84>
85> FedRAMP and GovCloud deployments use a different connector app ID and a
86> different connector service hostname. Contact your Anthropic representative
87> for the app ID to use in this URL and in the scope string in step 4, and for
88> the connector URL to use in step 4.
9389
94 1. In **Entra admin center → App registrations → New registration**, set **Name** to `Claude Desktop` (or your preferred name), set **Supported account types** to *Accounts in this organizational directory only*, and add a **Redirect URI** of platform *Mobile and desktop applications* with the value `http://127.0.0.1/callback`.
95 2. Select **Register**, then note the **Application (client) ID** and **Directory (tenant) ID** shown on the overview page.
96 3. Under **API permissions → Add a permission → APIs my organization uses**, search for `Anthropic` (or paste the connector app ID from step 1), select **Delegated permissions → access\_as\_user**, then **Add permissions**.
97 4. Select **Grant admin consent for \{your organization}**.
90**2. Register a desktop client app in your tenant**
9891
99 No client secret is needed; this is a public client that uses PKCE.
100 </Step>
92Create the public client that Claude Desktop will sign in as.
10193
102 <Step title="Send Anthropic your IDs">
103 Anthropic maintains an allowlist of tenant and client IDs that may call the connector service. Email your Anthropic representative, or open a support ticket, with your Directory (tenant) ID and the Application (client) ID from step 2. Allowlisting is typically completed within two to three business days, as it requires a connector service deployment.
941. In **Entra admin center → App registrations → New registration**, set **Name** to `Claude Desktop` (or your preferred name), set **Supported account types** to *Accounts in this organizational directory only*, and add a **Redirect URI** of platform *Mobile and desktop applications* with the value `http://127.0.0.1/callback`.
952. Select **Register**, then note the **Application (client) ID** and **Directory (tenant) ID** shown on the overview page.
963. Under **API permissions → Add a permission → APIs my organization uses**, search for `Anthropic` (or paste the connector app ID from step 1), select **Delegated permissions → access\_as\_user**, then **Add permissions**.
974. Select **Grant admin consent for \{your organization}**.
10498
105 Until the allowlist is updated, sign-in will succeed but the connector returns *Client application is not authorized for this resource*.
106 </Step>
99No client secret is needed; this is a public client that uses PKCE.
107100
108 <Step title="Configure Claude Desktop">
109 In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server → Microsoft 365**, and enter the values below.
101**3. Send Anthropic your IDs**
110102
111 | Field | Value |
112 | - | - |
113 | Client ID | The Application (client) ID from step 2 |
114 | Tenant ID | Your Directory (tenant) ID |
115 | Scope | `api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access` |
103Anthropic maintains an allowlist of tenant and client IDs that may call the connector service. Email your Anthropic representative, or open a support ticket, with your Directory (tenant) ID and the Application (client) ID from step 2. Allowlisting is typically completed within two to three business days, as it requires a connector service deployment.
116104
117 Select **Save**, then deploy the configuration through your device-management tool as usual.
105Until the allowlist is updated, sign-in will succeed but the connector returns *Client application is not authorized for this resource*.
118106
119 If you manage configuration through JSON or a plist directly instead of the in-app configuration window, add the following entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers).
107**4. Configure Claude Desktop**
120108
121 ```json theme={null}
122 {
123 "name": "m365",
124 "url": "https://microsoft365.mcp.claude.com/mcp",
125 "transport": "http",
126 "oauth": {
127 "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_2",
128 "tenantId": "DIRECTORY_TENANT_ID",
129 "scope": "api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access"
130 }
131 }
132 ```
133 </Step>
134</Steps>
109In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server → Microsoft 365**, and enter the values below.
135110
111| Field | Value |
112| - | - |
113| Client ID | The Application (client) ID from step 2 |
114| Tenant ID | Your Directory (tenant) ID |
115| Scope | `api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access` |
116
117Select **Save**, then deploy the configuration through your device-management tool as usual.
118
119If you manage configuration through JSON or a plist directly instead of the in-app configuration window, add the following entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers).
120
121```json theme={null}
122{
123 "name": "m365",
124 "url": "https://microsoft365.mcp.claude.com/mcp",
125 "transport": "http",
126 "oauth": {
127 "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_2",
128 "tenantId": "DIRECTORY_TENANT_ID",
129 "scope": "api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access"
130 }
131}
132```
133
136134### Sign in as a user
137135
138136After the configuration is deployed, each user opens **Customize → Connectors** in Claude Desktop and selects **Connect** next to Microsoft 365. Their browser opens to your tenant's sign-in page; once they consent, the connector is ready to use in conversations.
from line 152
154152
155153These controls apply to the connector service at `microsoft365.mcp.claude.com`. For write actions on a FedRAMP or GovCloud deployment, contact your Anthropic representative.
156154
157<Warning>
158 The Microsoft 365 connector in claude.ai uses the same connector app. When an administrator approves the write scopes for the whole tenant, for either product, write actions become available to every remote connector user in that tenant. Both the admin consent link in [Set up the remote connector](#set-up-the-remote-connector) and **Grant admin consent for \{your organization}** on the **M365 MCP Server for Claude** app's **Permissions** page approve every permission the connector requests, including the write scopes.
159</Warning>
155> [!WARNING]
156>
157> The Microsoft 365 connector in claude.ai uses the same connector app. When an administrator approves the write scopes for the whole tenant, for either product, write actions become available to every remote connector user in that tenant. Both the admin consent link in [Set up the remote connector](#set-up-the-remote-connector) and **Grant admin consent for \{your organization}** on the **M365 MCP Server for Claude** app's **Permissions** page approve every permission the connector requests, including the write scopes.
160158
161159Choose a control by who should have write actions:
162160
from line 248
250248
251249### Set up the local connector
252250
253<Steps>
254 <Step title="Register a public client app for local mode">
255 <Warning>
256 Do not reuse the desktop client app you registered for the remote connector. That app is consented only for the connector's own scope, so its tokens can reach nothing but the connector service. The local-mode app needs Microsoft Graph permissions directly, and adding those to the remote connector app's client ID would let any token minted for it read Microsoft 365 data directly, tenant-wide. Register a separate app dedicated to local mode.
257 </Warning>
251**1. Register a public client app for local mode**
258252
259 1. In **Entra admin center → App registrations → New registration**, set **Name** to `Claude Desktop M365 Local` (or your preferred name) and set **Supported account types** to *Accounts in this organizational directory only*.
260 2. Under **Authentication**, open the **Redirect URI configuration** tab and select **Add redirect URI** (on older versions of the portal, select **+ Add a platform** instead). Choose the **Mobile and desktop applications** card (the Windows, UWP, and Console card, not the iOS / macOS card, which takes a bundle ID rather than a redirect URI). Leave the suggested redirect URIs unchecked, enter `http://localhost` in the **Custom redirect URIs** box, and select **Configure**. This is the standard loopback redirect for desktop apps: during browser sign-in, Microsoft Entra redirects to a listener on the device itself, so the response never leaves the machine. For brokered sign-in on managed devices, also add the per-platform broker redirect URI shown under [How users sign in](#how-users-sign-in). Add it to the same platform by selecting **Edit** on the **Mobile and desktop applications** section that appears on the Authentication page, rather than adding another platform, and select **Save** at the top when you finish (on older versions of the portal, add the broker URI via the **Add URI** row inside the platform section instead). After you save, Microsoft Entra may display the `msauth` URI under a separate **iOS / macOS** section. That placement is expected because both sections map to `publicClient.redirectUris` in the app's manifest.
261 3. Under **Authentication**, set **Allow public client flows** to **Yes**, and select **Save**. The control is on the **Settings** tab under **Web and SPA settings** (on older versions of the portal, under **Advanced settings**). Brokered sign-in on managed devices issues token requests without a redirect URI, so Microsoft Entra relies on this setting to classify the app as a public client. With it set to No, brokered silent token acquisition fails with `AADSTS7000218`. To prevent device-code phishing, apply a tenant Conditional Access policy that blocks the device-code authentication flow. Conditional Access policies target the resource a token is requested for rather than the requesting client, so scope the policy to All resources, not to this registration.
262 4. Under **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add the scopes the connector will request (the default set is listed under [Configure scopes](#configure-scopes)), then select **Grant admin consent for \{your organization}**.
263 5. Note the **Application (client) ID** and **Directory (tenant) ID** from the overview page.
264 </Step>
253> [!WARNING]
254>
255> Do not reuse the desktop client app you registered for the remote connector. That app is consented only for the connector's own scope, so its tokens can reach nothing but the connector service. The local-mode app needs Microsoft Graph permissions directly, and adding those to the remote connector app's client ID would let any token minted for it read Microsoft 365 data directly, tenant-wide. Register a separate app dedicated to local mode.
265256
266 <Step title="Configure Claude Desktop">
267 In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server**, and choose **Microsoft 365** under the **Built-in** group. Enter the values below, then select **Test this connection** to verify that the server starts and lists its tools, and select **Save**.
2571. In **Entra admin center → App registrations → New registration**, set **Name** to `Claude Desktop M365 Local` (or your preferred name) and set **Supported account types** to *Accounts in this organizational directory only*.
2582. Under **Authentication**, open the **Redirect URI configuration** tab and select **Add redirect URI** (on older versions of the portal, select **+ Add a platform** instead). Choose the **Mobile and desktop applications** card (the Windows, UWP, and Console card, not the iOS / macOS card, which takes a bundle ID rather than a redirect URI). Leave the suggested redirect URIs unchecked, enter `http://localhost` in the **Custom redirect URIs** box, and select **Configure**. This is the standard loopback redirect for desktop apps: during browser sign-in, Microsoft Entra redirects to a listener on the device itself, so the response never leaves the machine. For brokered sign-in on managed devices, also add the per-platform broker redirect URI shown under [How users sign in](#how-users-sign-in). Add it to the same platform by selecting **Edit** on the **Mobile and desktop applications** section that appears on the Authentication page, rather than adding another platform, and select **Save** at the top when you finish (on older versions of the portal, add the broker URI via the **Add URI** row inside the platform section instead). After you save, Microsoft Entra may display the `msauth` URI under a separate **iOS / macOS** section. That placement is expected because both sections map to `publicClient.redirectUris` in the app's manifest.
2593. Under **Authentication**, set **Allow public client flows** to **Yes**, and select **Save**. The control is on the **Settings** tab under **Web and SPA settings** (on older versions of the portal, under **Advanced settings**). Brokered sign-in on managed devices issues token requests without a redirect URI, so Microsoft Entra relies on this setting to classify the app as a public client. With it set to No, brokered silent token acquisition fails with `AADSTS7000218`. To prevent device-code phishing, apply a tenant Conditional Access policy that blocks the device-code authentication flow. Conditional Access policies target the resource a token is requested for rather than the requesting client, so scope the policy to All resources, not to this registration.
2604. Under **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add the scopes the connector will request (the default set is listed under [Configure scopes](#configure-scopes)), then select **Grant admin consent for \{your organization}**.
2615. Note the **Application (client) ID** and **Directory (tenant) ID** from the overview page.
268262
269 | Field | Value |
270 | - | - |
271 | Tenant ID | Your Directory (tenant) ID |
272 | Client ID | The Application (client) ID from step 1 |
273 | Azure cloud | `global` (default), `us-gov-high`, or `us-gov-dod` |
274 | Access | Leave empty for standard read access, or list scopes explicitly (see [Configure scopes](#configure-scopes)) |
263**2. Configure Claude Desktop**
275264
276 If you manage configuration through JSON or a plist directly, add an entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) with the `server` field set to `microsoft365`:
265In the Claude Desktop [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration), open **Connectors**, select **Add server**, and choose **Microsoft 365** under the **Built-in** group. Enter the values below, then select **Test this connection** to verify that the server starts and lists its tools, and select **Save**.
277266
278 ```json theme={null}
279 {
280 "name": "Microsoft 365",
281 "server": "microsoft365",
282 "tenantId": "DIRECTORY_TENANT_ID",
283 "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_1"
284 }
285 ```
267| Field | Value |
268| - | - |
269| Tenant ID | Your Directory (tenant) ID |
270| Client ID | The Application (client) ID from step 1 |
271| Azure cloud | `global` (default), `us-gov-high`, or `us-gov-dod` |
272| Access | Leave empty for standard read access, or list scopes explicitly (see [Configure scopes](#configure-scopes)) |
286273
287 | Field | Required | Description |
288 | - | - | - |
289 | `name` | Yes | Unique display name, shown to users in connector settings. |
290 | `server` | Yes | Must be `microsoft365`. Built-in entries use this field instead of `url`, `transport`, or `command`; an entry that mixes `server` with those fields is rejected. |
291 | `clientId` | Yes | The Application (client) ID of the local-mode app from step 1. |
292 | `tenantId` | Yes | Your Directory (tenant) ID. |
293 | `azureCloud` | No | `global` (default), `us-gov-high`, or `us-gov-dod`. Selects the Microsoft Entra and Microsoft Graph hosts for US Government clouds. |
294 | `continuousAccessEvaluation` | No | `enabled` (default) or `disabled`. When enabled, the connector requests Continuous Access Evaluation-capable Microsoft Graph tokens, which live up to about 28 hours and stop working within minutes after an administrator revokes the user's sessions or disables the account in Entra, and, where your tenant enforces an IP named-location or Global Secure Access compliant-network Conditional Access policy, when the token is used from outside that network. `disabled` keeps standard one-hour tokens. A change applies to tokens issued after the connector next starts, and an already-issued token stays in use until it expires (select **Disconnect**, then **Connect**, to sign in again immediately). Requires Claude Desktop 1.49585.0 or later; earlier versions ignore the field and request standard one-hour tokens. |
295 | `scope` | No | Space-separated delegated Graph scopes to request instead of the default read set. The app rejects an entry that has a `scopes` array, so write the scopes as one string. See [Configure scopes](#configure-scopes). |
296 | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |
274If you manage configuration through JSON or a plist directly, add an entry to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) with the `server` field set to `microsoft365`:
297275
298 The server ships inside the app, so nothing else needs to be installed on the device, and it activates only from managed configuration; users cannot add it themselves. Deploy the configuration through your device-management tool as usual.
299 </Step>
276```json theme={null}
277{
278 "name": "Microsoft 365",
279 "server": "microsoft365",
280 "tenantId": "DIRECTORY_TENANT_ID",
281 "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_1"
282}
283```
300284
301 <Step title="Allow the required network hosts for local mode">
302 The local connector calls Microsoft directly from the device, so in addition to the [base egress hosts](/docs/third-party/claude-desktop/telemetry#required-egress-paths), devices need outbound HTTPS access to:
285| Field | Required | Description |
286| - | - | - |
287| `name` | Yes | Unique display name, shown to users in connector settings. |
288| `server` | Yes | Must be `microsoft365`. Built-in entries use this field instead of `url`, `transport`, or `command`; an entry that mixes `server` with those fields is rejected. |
289| `clientId` | Yes | The Application (client) ID of the local-mode app from step 1. |
290| `tenantId` | Yes | Your Directory (tenant) ID. |
291| `azureCloud` | No | `global` (default), `us-gov-high`, or `us-gov-dod`. Selects the Microsoft Entra and Microsoft Graph hosts for US Government clouds. |
292| `continuousAccessEvaluation` | No | `enabled` (default) or `disabled`. When enabled, the connector requests Continuous Access Evaluation-capable Microsoft Graph tokens, which live up to about 28 hours and stop working within minutes after an administrator revokes the user's sessions or disables the account in Entra, and, where your tenant enforces an IP named-location or Global Secure Access compliant-network Conditional Access policy, when the token is used from outside that network. `disabled` keeps standard one-hour tokens. A change applies to tokens issued after the connector next starts, and an already-issued token stays in use until it expires (select **Disconnect**, then **Connect**, to sign in again immediately). Requires Claude Desktop 1.49585.0 or later; earlier versions ignore the field and request standard one-hour tokens. |
293| `scope` | No | Space-separated delegated Graph scopes to request instead of the default read set. The app rejects an entry that has a `scopes` array, so write the scopes as one string. See [Configure scopes](#configure-scopes). |
294| `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). |
303295
304 | Host | Purpose |
305 | - | - |
306 | `login.microsoftonline.com` | Microsoft Entra sign-in |
307 | `graph.microsoft.com` | Microsoft Graph data APIs |
308 | Your tenant's SharePoint and OneDrive hosts | Downloads of OneDrive and SharePoint files |
296The server ships inside the app, so nothing else needs to be installed on the device, and it activates only from managed configuration; users cannot add it themselves. Deploy the configuration through your device-management tool as usual.
309297
310 To read Office documents, such as Word and PowerPoint files, the connector asks Microsoft Graph for a PDF version and follows the redirect Graph returns. Microsoft chooses the host in that redirect.
298**3. Allow the required network hosts for local mode**
311299
312 US Government cloud deployments use `login.microsoftonline.us` and `graph.microsoft.us` (or `dod-graph.microsoft.us` for `us-gov-dod`) instead of `login.microsoftonline.com` and `graph.microsoft.com`, matching the `azureCloud` setting. GCC High (`us-gov-high`) support has been confirmed in customer deployments. No egress to any Anthropic host is needed for Microsoft 365 data with the local connector.
313 </Step>
314</Steps>
300The local connector calls Microsoft directly from the device, so in addition to the [base egress hosts](/docs/third-party/claude-desktop/telemetry#required-egress-paths), devices need outbound HTTPS access to:
315301
302| Host | Purpose |
303| - | - |
304| `login.microsoftonline.com` | Microsoft Entra sign-in |
305| `graph.microsoft.com` | Microsoft Graph data APIs |
306| Your tenant's SharePoint and OneDrive hosts | Downloads of OneDrive and SharePoint files |
307
308To read Office documents, such as Word and PowerPoint files, the connector asks Microsoft Graph for a PDF version and follows the redirect Graph returns. Microsoft chooses the host in that redirect.
309
310US Government cloud deployments use `login.microsoftonline.us` and `graph.microsoft.us` (or `dod-graph.microsoft.us` for `us-gov-dod`) instead of `login.microsoftonline.com` and `graph.microsoft.com`, matching the `azureCloud` setting. GCC High (`us-gov-high`) support has been confirmed in customer deployments. No egress to any Anthropic host is needed for Microsoft 365 data with the local connector.
311
316312### Configure scopes
317313
318314With no `scope` field, the connector requests the standard read set at sign-in:
from line 340
344340
345341The `scope` field accepts only scopes the connector can use. An entry containing an unrecognized scope name is rejected as a whole at configuration load, with an error in the app's main log listing the valid names, and the connector does not appear.
346342
347<Note>
348 Narrowing or removing `scope` shrinks what the connector requests at the next sign-in, but it does not narrow tokens already obtainable for the registration: Microsoft Entra issues tokens carrying every scope previously consented for the app, regardless of what is requested. To revoke access, remove the consent in Entra under **Enterprise applications → your app → Permissions**.
349</Note>
343> [!NOTE]
344>
345> Narrowing or removing `scope` shrinks what the connector requests at the next sign-in, but it does not narrow tokens already obtainable for the registration: Microsoft Entra issues tokens carrying every scope previously consented for the app, regardless of what is requested. To revoke access, remove the consent in Entra under **Enterprise applications → your app → Permissions**.
350346
351347The connector provides these read and search tools:
352348
from line 392
396392
397393Browser sign-in works on tenants without device-based Conditional Access policies. It satisfies device policies only when the browser itself carries the device identity: on Windows, a browser signed in with the work account on an Entra-joined device (such as Microsoft Edge) provides this; on macOS, deploy Microsoft's Enterprise SSO browser integration, or use brokered sign-in instead.
398394
399<AccordionGroup>
400 <Accordion title="Requirements for brokered sign-in on Windows">
401 Brokered sign-in on Windows requires Claude Desktop version 1.13576.0 or later.
395> **Requirements for brokered sign-in on Windows**
396>
397> Brokered sign-in on Windows requires Claude Desktop version 1.13576.0 or later.
398>
399> * Windows 10 or later (desktop editions). The broker (Web Account Manager, or WAM) is built into Windows; no separate install is needed.
400> * The device is joined or registered to Entra ID (Entra joined, Entra hybrid joined, or Entra registered). For device-based Conditional Access, the device must also be marked compliant in Intune or hybrid-joined, as your policy requires.
401> * The broker redirect URI is registered on the local-mode app under **Mobile and desktop applications**, with `APPLICATION_CLIENT_ID` replaced by the Application (client) ID from step 1:
402>
403> ```text theme={null}
404> ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID
405> ```
406>
407> If a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself carries the device identity (see above); fix the broker requirement that caused the fallback and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.
408>
409> A missing broker redirect URI does not trigger the fallback on Windows. The broker shows Entra error `AADSTS50011` in its own sign-in dialog, and closing that dialog counts as canceling, so every sign-in attempt ends at the same error until you register the URI above. To have users sign in through the browser instead of the broker, set [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) to `disabled` in the managed configuration. Tokens from browser sign-in carry no device identity claim unless the browser itself provides one (see above), so device-based Conditional Access policies block them.
410>
411> To have **Connect** sign in with the work account already signed in to Windows, without the account picker, set [`microsoftAuthDefaultAccount`](/docs/third-party/claude-desktop/configuration#microsoftauthdefaultaccount) to `enabled`. See the key's reference entry for the requirements and the cases where users still get the picker.
402412
403 * Windows 10 or later (desktop editions). The broker (Web Account Manager, or WAM) is built into Windows; no separate install is needed.
404 * The device is joined or registered to Entra ID (Entra joined, Entra hybrid joined, or Entra registered). For device-based Conditional Access, the device must also be marked compliant in Intune or hybrid-joined, as your policy requires.
405 * The broker redirect URI is registered on the local-mode app under **Mobile and desktop applications**, with `APPLICATION_CLIENT_ID` replaced by the Application (client) ID from step 1:
406
407 ```text theme={null}
408 ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID
409 ```
410
411 If a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself carries the device identity (see above); fix the broker requirement that caused the fallback and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.
412
413 A missing broker redirect URI does not trigger the fallback on Windows. The broker shows Entra error `AADSTS50011` in its own sign-in dialog, and closing that dialog counts as canceling, so every sign-in attempt ends at the same error until you register the URI above. To have users sign in through the browser instead of the broker, set [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) to `disabled` in the managed configuration. Tokens from browser sign-in carry no device identity claim unless the browser itself provides one (see above), so device-based Conditional Access policies block them.
414
415 To have **Connect** sign in with the work account already signed in to Windows, without the account picker, set [`microsoftAuthDefaultAccount`](/docs/third-party/claude-desktop/configuration#microsoftauthdefaultaccount) to `enabled`. See the key's reference entry for the requirements and the cases where users still get the picker.
416 </Accordion>
417
418 <Accordion title="Requirements for brokered sign-in on macOS">
419 Brokered sign-in on macOS requires Claude Desktop version 1.19367.0 or later.
420
421 * The Mac is enrolled in an MDM (Intune, Jamf, or similar), registered in Entra ID, and marked compliant. For non-Intune MDMs, use the partner device-compliance integration that reports compliance to Intune and Entra.
422 * **Intune Company Portal** is installed; it provides the broker.
423 * An **Extensible SSO** configuration profile of type **Redirect**, pointed at the Microsoft Enterprise SSO plug-in, is deployed through MDM. The broker is unavailable without it.
424 * The broker redirect URI is registered on the local-mode app under **Mobile and desktop applications** (it appears under the **iOS / macOS** section after saving):
425
426 ```text theme={null}
427 msauth.com.anthropic.claudefordesktop://auth
428 ```
429
430 If the app registration also lists `msauth.com.anthropic.claudefordesktop.helper://auth`, remove that entry. Claude Desktop does not use it.
431
432 If the broker rejects the app's sign-in request, or a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself is signed in through the device's SSO integration; fix the broker requirement that caused the fallback (most often a missing broker redirect URI or SSO profile) and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.
433 </Accordion>
434</AccordionGroup>
413> **Requirements for brokered sign-in on macOS**
414>
415> Brokered sign-in on macOS requires Claude Desktop version 1.19367.0 or later.
416>
417> * The Mac is enrolled in an MDM (Intune, Jamf, or similar), registered in Entra ID, and marked compliant. For non-Intune MDMs, use the partner device-compliance integration that reports compliance to Intune and Entra.
418> * **Intune Company Portal** is installed; it provides the broker.
419> * An **Extensible SSO** configuration profile of type **Redirect**, pointed at the Microsoft Enterprise SSO plug-in, is deployed through MDM. The broker is unavailable without it.
420> * The broker redirect URI is registered on the local-mode app under **Mobile and desktop applications** (it appears under the **iOS / macOS** section after saving):
421>
422> ```text theme={null}
423> msauth.com.anthropic.claudefordesktop://auth
424> ```
425>
426> If the app registration also lists `msauth.com.anthropic.claudefordesktop.helper://auth`, remove that entry. Claude Desktop does not use it.
427>
428> If the broker rejects the app's sign-in request, or a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself is signed in through the device's SSO integration; fix the broker requirement that caused the fallback (most often a missing broker redirect URI or SSO profile) and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.
435429
436430### Token storage and sign-out
437431
third-party/claude-desktop/connectors-salesforce Changed · +51 / -53 lines
from line 6
66
77## Set up Salesforce
88
9<Steps>
10 <Step title="Prepare your Salesforce org">
11 In Salesforce Setup, turn on **Enable MCP Service**, then create an External Client App for Claude Desktop with these OAuth settings:
9**1. Prepare your Salesforce org**
1210
13 * The callback URL `http://127.0.0.1:53280/callback`
14 * The OAuth scopes `mcp_api` and `refresh_token`
15 * Proof Key for Code Exchange (PKCE) required
16 * Access tokens issued as JSON Web Tokens (JWTs)
17 * An OAuth policy that lets users self-authorize
11In Salesforce Setup, turn on **Enable MCP Service**, then create an External Client App for Claude Desktop with these OAuth settings:
1812
19 Copy the app's **Consumer Key**, which is its client ID. With PKCE, Claude Desktop needs no client secret.
20 </Step>
13* The callback URL `http://127.0.0.1:53280/callback`
14* The OAuth scopes `mcp_api` and `refresh_token`
15* Proof Key for Code Exchange (PKCE) required
16* Access tokens issued as JSON Web Tokens (JWTs)
17* An OAuth policy that lets users self-authorize
2118
22 <Step title="Add the Salesforce marketplace">
23 **In the Enterprise Admin Console.** Go to [claude.ai](https://claude.ai) → **Organization settings** and open the **Plugins** page under **Desktop 3P**. Under **Plugin marketplaces**, click **Add** and choose **Salesforce** under **From partners**. The new entry has **Source** set to **GitHub**, **Repository** set to `salesforce/salesforce-skills`, and **Ref** set to `claude-prod`, the branch Salesforce publishes its releases to. Leave **Installation** empty and click **Save changes**.
19Copy the app's **Consumer Key**, which is its client ID. With PKCE, Claude Desktop needs no client secret.
2420
25 **With MDM or a bootstrap server.** Add this entry to the [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) key of your managed configuration or bootstrap response:
21**2. Add the Salesforce marketplace**
2622
27 ```json theme={null}
28 {
29 "source": "github",
30 "repo": "salesforce/salesforce-skills",
31 "ref": "claude-prod"
32 }
33 ```
23**In the Enterprise Admin Console.** Go to [claude.ai](https://claude.ai) → **Organization settings** and open the **Plugins** page under **Desktop 3P**. Under **Plugin marketplaces**, click **Add** and choose **Salesforce** under **From partners**. The new entry has **Source** set to **GitHub**, **Repository** set to `salesforce/salesforce-skills`, and **Ref** set to `claude-prod`, the branch Salesforce publishes its releases to. Leave **Installation** empty and click **Save changes**.
3424
35 Either way the marketplace stays **available**, and each user installs the plugin once, as described in step 4. To install the plugin on every device without user action instead, set the ref to a full 40-character commit SHA and the installation preference to `auto_install`. [Marketplace installation preferences](/docs/third-party/claude-desktop/extensions#marketplace-installation-preferences) explains why the SHA is required, and [Roll out marketplace updates](/docs/third-party/claude-desktop/extensions#roll-out-marketplace-updates) explains how to move to a newer release.
36 </Step>
25**With MDM or a bootstrap server.** Add this entry to the [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration#allowedpluginmarketplaces) key of your managed configuration or bootstrap response:
3726
38 <Step title="Add the Salesforce MCP server">
39 **In the Enterprise Admin Console.** Go to [claude.ai](https://claude.ai) → **Organization settings** and open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank**, fill in the entry as below, and click **Save changes**. [Set up sign-in for managed MCP servers](/docs/third-party/claude-desktop/mcp-sign-in) explains each **OAuth** field, and users' apps pick up console changes as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates).
27```json theme={null}
28{
29 "source": "github",
30 "repo": "salesforce/salesforce-skills",
31 "ref": "claude-prod"
32}
33```
4034
41 | Field | Value |
42 | - | - |
43 | **Name** | `salesforce-h360` |
44 | **Transport** | **Streamable HTTP** |
45 | **URL** | `https://api.salesforce.com/platform/mcp/v1/platform/headless-360` |
46 | **OAuth** | **Bring your own client** |
47 | **Client ID** | The Consumer Key from step 1 |
48 | **Authorization server** | `["https://login.salesforce.com"]` |
35Either way the marketplace stays **available**, and each user installs the plugin once, as described in step 4. To install the plugin on every device without user action instead, set the ref to a full 40-character commit SHA and the installation preference to `auto_install`. [Marketplace installation preferences](/docs/third-party/claude-desktop/extensions#marketplace-installation-preferences) explains why the SHA is required, and [Roll out marketplace updates](/docs/third-party/claude-desktop/extensions#roll-out-marketplace-updates) explains how to move to a newer release.
4936
50 **With MDM or a bootstrap server.** Add this entry to the [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) key of your managed configuration or bootstrap response:
37**3. Add the Salesforce MCP server**
5138
52 ```json theme={null}
53 {
54 "name": "salesforce-h360",
55 "transport": "http",
56 "url": "https://api.salesforce.com/platform/mcp/v1/platform/headless-360",
57 "oauth": {
58 "clientId": "YOUR_CONSUMER_KEY",
59 "authorizationServer": ["https://login.salesforce.com"]
60 }
61 }
62 ```
39**In the Enterprise Admin Console.** Go to [claude.ai](https://claude.ai) → **Organization settings** and open the **Connectors** page under **Desktop 3P**. Under **Managed MCP servers**, click **Add → Blank**, fill in the entry as below, and click **Save changes**. [Set up sign-in for managed MCP servers](/docs/third-party/claude-desktop/mcp-sign-in) explains each **OAuth** field, and users' apps pick up console changes as described under [Configuration updates](/docs/third-party/claude-desktop/admin-console#configuration-updates).
6340
64 Keep the name exactly as shown. The Salesforce plugin defines an MCP server with this name, and Claude Desktop matches your entry to it by name and connects it with your client ID. Without the entry, users get the plugin's skills but not its Salesforce tools.
41| Field | Value |
42| - | - |
43| **Name** | `salesforce-h360` |
44| **Transport** | **Streamable HTTP** |
45| **URL** | `https://api.salesforce.com/platform/mcp/v1/platform/headless-360` |
46| **OAuth** | **Bring your own client** |
47| **Client ID** | The Consumer Key from step 1 |
48| **Authorization server** | `["https://login.salesforce.com"]` |
6549
66 Enter exactly one URL as the authorization server. To send users to your org's My Domain login page instead of the shared Salesforce login page, enter that URL, for example `["https://yourorg.my.salesforce.com"]`.
50**With MDM or a bootstrap server.** Add this entry to the [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) key of your managed configuration or bootstrap response:
6751
68 For a Salesforce sandbox org, create the External Client App in the sandbox and enter the sandbox's login URL as the authorization server, for example `["https://test.salesforce.com"]`. Set the URL to `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360`.
52```json theme={null}
53{
54 "name": "salesforce-h360",
55 "transport": "http",
56 "url": "https://api.salesforce.com/platform/mcp/v1/platform/headless-360",
57 "oauth": {
58 "clientId": "YOUR_CONSUMER_KEY",
59 "authorizationServer": ["https://login.salesforce.com"]
60 }
61}
62```
6963
70 Devices need git installed to fetch the marketplace, and outbound HTTPS access to `github.com`, `api.salesforce.com`, and your Salesforce login host.
71 </Step>
64Keep the name exactly as shown. The Salesforce plugin defines an MCP server with this name, and Claude Desktop matches your entry to it by name and connects it with your client ID. Without the entry, users get the plugin's skills but not its Salesforce tools.
7265
73 <Step title="Have users install the plugin and connect">
74 Each user opens **Customize → Plugins** in Claude Desktop and clicks **Discover**, which opens the **Directory**. On its **Organization** tab the user selects your marketplace's tab and clicks the **+** button on the Salesforce plugin to install it. The user then opens **Customize → Connectors**, clicks **Connect** next to **salesforce-h360**, and signs in to Salesforce in the browser.
75 </Step>
76</Steps>
66Enter exactly one URL as the authorization server. To send users to your org's My Domain login page instead of the shared Salesforce login page, enter that URL, for example `["https://yourorg.my.salesforce.com"]`.
67
68For a Salesforce sandbox org, create the External Client App in the sandbox and enter the sandbox's login URL as the authorization server, for example `["https://test.salesforce.com"]`. Set the URL to `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360`.
69
70Devices need git installed to fetch the marketplace, and outbound HTTPS access to `github.com`, `api.salesforce.com`, and your Salesforce login host.
71
72**4. Have users install the plugin and connect**
73
74Each user opens **Customize → Plugins** in Claude Desktop and clicks **Discover**, which opens the **Directory**. On its **Organization** tab the user selects your marketplace's tab and clicks the **+** button on the Salesforce plugin to install it. The user then opens **Customize → Connectors**, clicks **Connect** next to **salesforce-h360**, and signs in to Salesforce in the browser.
7775