# Admin controls Source: https://claude.com/docs/claude-science/admin-controls Organization settings for Claude Science on Team and Enterprise plans (Featured connectors and skills, custom connectors and skills, the network allowlist, package mirror, SSH hosts, Modal, scientific model endpoints, and memory) and which other claude.ai admin controls apply to the app. Members sign in to Claude Science with their Claude account, so your identity and billing controls apply automatically. Because the app stores conversations on each member's computer, most of the data-handling controls Anthropic provides don't reach that data today. [Organization settings](#organization-settings) describes the controls on the claude.ai **Organization settings** > **Claude Science** page itself, which govern the connectors, skills, compute, network access, and memory that members can use in the Claude Science app. [How other admin settings apply to Claude Science](#how-other-admin-settings-apply-to-claude-science) lists every other claude.ai admin setting and whether it applies to Claude Science today. Status values describe Claude Science specifically; other Claude products may differ. ## Organization settings The [**Organization settings** > **Claude Science**](https://claude.ai/admin-settings/claude-science) page in claude.ai holds the controls that apply to every member of your Team or Enterprise organization who uses the app. An Owner or Primary Owner turns Claude Science on there (see [Enable Claude Science](/docs/claude-science/enable-claude-science)), and the other controls unlock once Claude Science is on. Each section below covers one control: what it governs, its default, and what changes for members when you turn it off. ### Defaults by plan Each control starts at a default that depends on your plan and on whether HIPAA compliance is enabled for your organization. The page always shows the value in force for your organization. | Control | Default for Team | Default for Enterprise¹ | | ----------------------------------------------------------- | ------------------------------ | ------------------------------ | | Featured connectors and Featured skills | All on | All on | | Allow custom connectors | On | Off | | Allow custom skills | On | On | | Manage network allowlist | Off (members manage their own) | Off (members manage their own) | | Organization package mirror | Not set | Not set | | Allow members to connect SSH hosts | On | On | | Allow members to connect to Modal | On | Off | | Show scientific model endpoint providers on the Compute tab | On | On | | Turn on memory for your team | On | On | ¹ For HIPAA-eligible organizations, note that Claude Science (beta) is not covered under your Business Associate Agreement (BAA) and should not be used with protected health information (PHI). Administrators who enable Claude Science are responsible for ensuring their workforce uses it in compliance with applicable legal obligations. Featured and custom connectors, SSH hosts, Modal, scientific model endpoints, and memory are all off by default for HIPAA-eligible organizations. ### How changes reach members Changes you save reach each member's running app within a few minutes and apply on the member's next turn or request. An app that is closed picks up your changes when it next starts, and an app that can't reach claude.ai keeps applying the last settings it received. The settings apply to members running version 0.1.41 or later of the Claude Science app. A member still on an earlier version isn't governed by these settings until the member updates (see [Required updates](/docs/claude-science/manage-on-devices#required-updates)). For Team and Enterprise organizations, Claude Science enforces a minimum version of 0.1.41. A member on an older version sees a notice that the version is no longer supported, with an **Update now** button. If the update doesn't complete after a second try, the member can install the current version from the [Claude Science download page](https://claude.com/product/claude-science) (on Linux, rerun the install command in [Get started](/docs/claude-science/get-started#install)); projects and settings on the computer are kept. Each member's app also has to reach claude.ai regularly to confirm these settings. If an app can't reach claude.ai for 72 hours, it pauses memory, custom connectors, SSH hosts, Modal, model endpoints, and adding custom skills until it reconnects, and keeps applying the network allowlist, package mirror, and Featured connector and skill choices it last received. Turning a control off doesn't delete anything on the members' computers. What members set up under that control (custom connectors, SSH hosts, their Modal connection, saved memories, and their own choices) stays on their computer, and that feature cannot be used inside the Claude Science app while the control is off. The setting shows grayed out in the app with a note that an admin turned it off, and everything works again as before if you turn the control back on. A control that is off by your plan's default instead shows a note that an admin can turn it on. When the **Allow custom skills** switch is off, skills a member added earlier keep working (see [Custom skills](#custom-skills)). ### Featured connectors and skills Featured connectors and Featured skills come with Claude Science, and admins can control whether they are enabled or disabled for your members (see [Connectors and skills](/docs/claude-science/connectors-and-skills)). The **Featured connectors** and **Featured skills** sections list them with one switch per item, so you can choose which ones members can use. Every item is on by default for Team and Enterprise organizations. In an organization with HIPAA compliance enabled, every Featured connector and skill starts disabled; turn on the ones you have reviewed. Each section shows how many items are enabled. Expand it to see the list, and select an item to see its tools or instructions, author, license, and third-party terms. Besides switching every current item in that list, **Enable all** and **Disable all** set how items added in later versions of Claude Science start: on after **Enable all**, off after **Disable all**. If you use neither, new items start on (off in an organization with HIPAA compliance enabled). The individual switches affect only that item, so to keep today's items on while new ones start off, choose **Disable all** and then turn on the items you want. In the **Featured connectors** list, the rows marked **Web** (PubMed, Clinical Trials, ChEMBL, and bioRxiv) are connectors Anthropic hosts in the Claude connector directory rather than locally as part of the app. The switches for those four add or remove the connector for your whole organization on **Organization settings** > **Connectors**, need a role that can manage your organization's connectors, and aren't changed by **Enable all** or **Disable all**. For organizations with HIPAA compliance enabled, manage those four on the **Connectors** page instead. When you turn a connector or skill off, Claude can no longer use it for any member. A connector is no longer offered to Claude, and a skill is left out of the skills Claude can load, from the member's next turn. The item stays listed in the member's settings, grayed, with a note that it's disabled by your admin. Members can still turn off, in their own app, any item you leave on. The app remembers each member's choice, so it applies again if you turn an item off and later back on. Turning a Featured skill off doesn't stop a member from writing a skill of their own; whether members can add their own skills is governed by [Custom skills](#custom-skills). When you turn Claude Science on, the [**Turn on Claude Science** dialog](/docs/claude-science/enable-claude-science#turn-on-claude-science) notes: "By continuing, you authorize your team to let Claude use the optional enabled resources on their behalf. These resources and content they reach may be subject to third-party terms (viewable in Settings), and your users are solely responsible for compliance." ### Custom connectors Custom connectors are Model Context Protocol (MCP) servers a member adds under **Settings** > **Connectors** in the Claude Science app, either a remote server at an HTTPS URL or a local command on their computer (see [Custom connectors](/docs/claude-science/custom-connectors)). The **Allow custom connectors** switch decides whether members can add and use them. It's on by default for Team organizations and off by default for Enterprise organizations. Organizations with HIPAA compliance enabled can't turn it on. When the switch is off, members can't add, change, or authorize custom connectors, and Claude no longer sees the custom connectors members may have added earlier. Those connectors stay listed in the member's settings, grayed, with a note that custom connectors are disabled by your admin. Featured connectors and the Directory connectors you publish from **Organization settings** > **Connectors** aren't affected by this switch. ### Custom skills Skills are instructions, sometimes with helper code, that Claude loads when a task calls for them (see [Skills](/docs/claude-science/connectors-and-skills#skills)). Members add their own by writing one, uploading one, importing one from a public GitHub repository (or a private repo if a [GitHub credential](/docs/claude-science/connectors-and-skills#skills) is stored), or asking Claude to create one from a session. The **Allow custom skills** switch decides whether members can add skills of their own, including creating one from the Claude Science app so it's also available to them in claude.ai. It's on by default for Team and Enterprise organizations, including those with HIPAA compliance enabled. When the switch is off, members can't add new skills of their own or publish them, and the app notes that custom skills are disabled by your admin. Skills a member added earlier still work and can still be edited, and Featured skills aren't affected. Custom skills are how members teach Claude their own workflows and analysis pipelines, so Anthropic recommends leaving this switch on. ### Organization skills Add skills for everyone in your organization in claude.ai, under **Organization settings** > **Skills** > **Organization skills**. Upload each skill as a .zip file. Members see it in the Claude Science app under **Settings** > **Skills**, in the **Organization** section. Organization skills go to every member. To update a skill, upload a new version in claude.ai. To let members manage their own skills, host them in a GitHub repository. Put one `skills//SKILL.md` folder per skill in the repository and share the link. Members import them in the Claude Science app under **Settings** > **Skills** > **Add skill** > **Import from GitHub**. Claude Science records the commit each skill came from. **Check for updates** flags skills that are behind the repository's latest commit; each member chooses when to import again. Private repositories work after a member adds a GitHub token in the Claude Science app under **Settings** > **Credentials**. To stop members from adding their own skills, turn off the **Allow custom skills** switch on the **Organization settings** > **Claude Science** page (see [Custom skills](#custom-skills)). ### Network allowlist When Claude runs code for a member, that code can reach only the domains on the analysis sandbox's network allowlist: the package hosts, the scientific databases behind the Featured connectors, and hosts the member approved. See [Sandbox](/docs/claude-science/core-concepts#sandbox) and the domain tables in [Network requirements](/docs/claude-science/network-requirements#analysis-sandbox-domains). By default, each member manages that list on their own computer. The **Manage network allowlist** switch transfers control of the list from members to you. While it's on, every member's app uses the organization's list instead of the member's own, and members see the list in their **Network** settings read-only, apart from domains they have blocked themselves, with a note that the domain allowlist is controlled by their admin. It's off by default for Team and Enterprise organizations, and on for organizations with HIPAA compliance enabled, which can't turn it off. Turning the switch on sets aside what members allowed themselves, including the domains a deployed configuration file adds with its `[sandbox.network]` keys; those settings are kept and apply again when you turn the switch off. Domains the file denies stay denied. Your list is enforced by the app's sandbox (see [Sandbox](/docs/claude-science/core-concepts#sandbox)). On a computer where the sandbox is turned off or can't start, the app pauses new sessions and messages and tells the member the computer doesn't meet the organization's security requirements, until the member restarts the app with the sandbox on or you turn the switch off. Turning the switch off keeps your saved list, which applies again the next time you turn it on. With the switch on, **Claude Science domains** shows the Featured domains in the same groups as the app, such as **Package management**, **Literature & citations**, and **NCBI / NIH**, with one switch per domain. A group switch turns all of its domains on or off. Below it, **Custom domains** adds your own. The rules for an entry are: * An exact name such as `data.example.org`, or a wildcard such as `*.example.org` * A wildcard covers subdomains only, so `*.example.org` doesn't cover `example.org` itself; add both if you need both * No IP addresses and no single-label names such as `intranet` * The list holds up to 600 domains, counting built-in and custom ones together * There's no **Save** button: each change is saved as soon as you make it Until you change the list, members use Claude Science's Featured list, including domains added in later versions of Claude Science. Once you change it, the list is saved exactly as you left it, so a domain added in a later version stays off until you turn it on. **Reset** returns to the Featured list and removes your custom domains, for all members. You can also turn off the **Package management** domains (PyPI, conda, CRAN and Bioconductor, npm, and GitHub), with limits. The PyPI and conda domains can be turned off only while the [organization package mirror](#organization-package-mirror) covers them. Turning the CRAN and Bioconductor, npm, or GitHub domains off means members can't install packages from them, and the page asks you to confirm. The domains the sandbox always blocks (see [Network requirements](/docs/claude-science/network-requirements#domains-the-sandbox-always-blocks)) stay blocked whichever list is in force. The allowlist governs the network connections of code Claude runs in the sandbox on the member's computer, the local-command connectors that run inside it, and, while you manage it, the [model endpoints](#scientific-model-endpoints) members connect by host name. Jobs on SSH hosts use the host's own network, so the allowlist doesn't apply to them, and the [**Allow members to connect SSH hosts**](#ssh-hosts) switch is the control for those. Modal jobs run in Modal's cloud. While you manage the list, a member's Modal jobs run only if the member has set **Network restrictions** for Modal in the app to **Allowlist** or **No network**. Unrestricted Modal jobs are refused. ### Organization package mirror Analysis environments install Python and conda packages from the public hosts unless a mirror is set. Members or IT can set a mirror per computer under **Settings** > **Network** > **Package mirror** or in the [configuration file](/docs/claude-science/configuration-file-reference#package-download-keys). See [Point package installs at an internal mirror](/docs/claude-science/corporate-networks#point-package-installs-at-an-internal-mirror) for the mirror layout and credentials. The **Organization package mirror** section sets the same two addresses once for every member: a **Conda channel URL** and a **Python package index URL (PyPI)**. The section applies whether or not you manage the [network allowlist](#network-allowlist), and there is no organization mirror by default. Addresses must start with `https://`, name a host rather than an IP address (an intranet name such as `https://artifactory:8443` works), use the standard port or 8443, and carry no sign-in details. To test an address before you save it, open Claude Science on a computer inside your network, go to **Settings** > **Network** > **Package mirror** > **Configure**, paste the address, and select **Check**. An address that breaks these rules is ignored for that registry, the member's own mirror setting applies instead, and the member's app notes it in its log. An address that passes them but can't be reached isn't ignored, and package installs fail with an error that names the mirror. An organization mirror takes precedence over a mirror a member set in Settings or in their configuration file. The member's values are kept but not used, and their Settings show that the package mirror is controlled by their admin. The mirror host is allowed automatically and the public hosts it replaces are removed from the allowlist, as for a member-set mirror. While you manage the network allowlist, those hosts stay removed even if they are switched on in your list. Mirror credentials stay with each member. A member signs in to your mirror once per mirror host under **Settings** > **Network** > **Package mirror** > **Mirror credentials**, and the organization settings never store a credential. ### SSH hosts Members can register a machine they reach over SSH, such as a lab workstation or an HPC login node, so Claude can run jobs on it (see [Remote compute clusters](/docs/claude-science/remote-compute-clusters)). The **Allow members to connect SSH hosts** switch decides whether they can. It's on by default for Team and Enterprise organizations, and off by default for organizations with HIPAA compliance enabled, which can turn it on. When the switch is off, members can't add SSH hosts, and hosts they added earlier are kept but refuse new commands and file transfers; the app shows that SSH host setup is disabled by your admin. A job that is already running can still be stopped and its results collected. Jobs on an SSH host run outside the sandbox, as the member's own user on that machine, with access to everything that account can read and write there. The app uses the member's existing SSH configuration and keys and installs nothing on the host. Job scripts and inputs travel directly from the member's computer to the host, and outputs come back the same way, without passing through Anthropic. Code on the host uses the host's network, so the [network allowlist](#network-allowlist) doesn't apply to it. ### Modal [Modal](https://modal.com/) is a third-party cloud computing service. Members can connect a Modal account they own so Claude can run jobs that need a GPU or more memory than their computer has. Modal bills that account directly, and Anthropic never sees a payment method (see [Compute providers](/docs/claude-science/compute-providers#connecting-modal)). The **Allow members to connect to Modal** switch decides whether members can connect Modal in the Claude Science app in **Settings** > **Compute**. It's on by default for Team organizations, off by default for Enterprise organizations, and off by default for organizations with HIPAA compliance enabled, which can turn it on. When the switch is off, members can't set up Modal or start new Modal jobs, and the app shows that Modal setup is disabled by your admin. A job that is already running can still be stopped, and the member's Modal settings are kept. With the switch on, **Modal workspaces** lets you limit which Modal workspaces members can connect to. By default members can connect to any workspace. Select **Restrict to a workspace** and enter each workspace name as Modal shows it; capitalization doesn't matter. The app checks the workspace that Modal reports for the member's token when the member uses it, and a member on another workspace sees that their Modal workspace is not allowed by their admin. Turning the **Allow members to connect to Modal** switch off hides the workspace list, which is kept and applies again when you turn Modal back on. Modal jobs run in Modal's cloud, not on the member's computer. There is no spend ceiling in Claude Science; to limit spend, use the controls in your Modal account (see [Modal's documentation](https://modal.com/docs/guide/budgets)). Members approve jobs on a card that shows the machine and the maximum billable time, per job or for a whole conversation or project, and a job keeps running and billing after the app closes. ### Scientific model endpoints Members can connect a scientific model server, such as NVIDIA BioNeMo NIM, that Claude calls directly from analyses (see [Scientific model endpoints](/docs/claude-science/compute-providers#scientific-model-endpoints)). The **Show scientific model endpoint providers on the Compute tab** switch decides whether members can connect the providers listed on the app's **Compute** tab. It's on by default for Team and Enterprise organizations, and off by default for organizations with HIPAA compliance enabled, which can turn it on. When the switch is off, members can't connect these providers or use the endpoints they set up earlier, and the app shows that scientific model endpoint setup is disabled by your admin; the settings they entered are kept. The switch governs third-party model endpoints only and has no effect on which Claude models members can use. While members manage their own network allowlist, an endpoint a member connected is reachable without being on that list. While you manage the [network allowlist](#network-allowlist), an endpoint at a public or internal host name works only if your network allowlist also includes that host, so add `health.api.nvidia.com` (NVIDIA's hosted endpoint) or your own server's name under **Custom domains** on the **Organization settings** > **Claude Science** page. Endpoints at a private IP address or on localhost aren't affected. ### Memory Memory lets Claude save short facts about a member, their projects, and their files across sessions, stored in the app's local database on the member's computer (see [Memory](/docs/claude-science/core-concepts#memory)). Each member chooses whether their own memory is on, during first-time setup or later in **Settings** > **Memory**. The **Turn on memory for your team** switch decides whether members can use memory at all. It's on by default for Team and Enterprise organizations, and off by default for organizations with HIPAA compliance enabled, which can turn it on. When the switch is off, memory is off for every member, whatever they chose in their own settings; Claude neither recalls nor saves facts, first-time setup skips its memory step, and the **Memory** setting shows that memory is disabled by your admin. Facts a member saved earlier stay on their computer, the member can still review and delete them, and Claude uses them again if you turn the switch back on. When Claude recalls saved facts for a session, those facts are sent to Anthropic as part of that session's conversation and handled like the rest of the conversation (see [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data)). The **Capabilities** > **Memory** setting in claude.ai **Organization settings** doesn't control memory in Claude Science. ## How other admin settings apply to Claude Science In the tables below, each setting is named by its page in claude.ai **Organization settings** and, where it has one, its label there (for example, **Capabilities** > **Web search**). Apart from the **Enable for your organization** toggle, the controls on the **Claude Science** page itself are described under [Organization settings](#organization-settings). The status column in each table shows one of four values: * **Supported in Claude Science**: you can govern this for Claude Science, through the claude.ai setting itself or through the named control on the **Claude Science** page. * **Partially supported in Claude Science**: you can govern only part of this for Claude Science through either place, and the note says which part. * **Not available in Claude Science**: the setting doesn't cover Claude Science, and Claude Science has no equivalent control. * **Not applicable in Claude Science**: Claude Science has nothing for the setting to govern. ### Identity and access | Setting in claude.ai | Status for Claude Science | Note | | ----------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Organization and access > Single sign-on (SSO) | Supported in Claude Science | Members sign in to Claude Science through claude.ai, so your SSO configuration and the **Require SSO for Claude** setting apply to the app. | | Organization and access > User provisioning (SCIM directory sync, Enterprise) | Supported in Claude Science | Provisioning and deprovisioning act on claude.ai membership, which Anthropic checks on every request the app makes, so a deprovisioned member's app stops working. | | Organization and access > Domains | Supported in Claude Science | Domain verification, and the **Migrate accounts using your domains** and **Restrict organization creation** settings that build on it, act on claude.ai accounts before anyone reaches the app, so they apply unchanged. | | Members | Supported in Claude Science | Adding or removing members controls who can sign in to Claude Science. | | Roles (built-in) | Supported in Claude Science | Every built-in role (User, Admin, Owner, and Primary Owner) can use Claude Science once it's turned on for the organization. | | Roles > Claude Science permission in custom roles (Enterprise) | Supported in Claude Science | Add the Claude Science permission to a custom role to give the app to that role's members. Members whose custom roles don't include it can't use the app. Team plans don't have custom roles, so everyone gets access when Claude Science is on. | | Groups (Enterprise) | Supported in Claude Science | Members get the Claude Science access of the roles their groups assign. | | IP allowlist (Enterprise) | Partially supported in Claude Science | The app's sign-in, its requests to Claude, and its Directory connector calls are checked against your allowlist (see [Restrict access to Claude with IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)). Traffic that doesn't go to Anthropic isn't checked, which covers code on the member's computer, SSH hosts, or Modal account, and custom connectors. You can turn SSH hosts, Modal, and custom connectors off under [Organization settings](#organization-settings). | | Organization and access > Shortened session length (Enterprise) | Partially supported in Claude Science | Applies to the browser sign-in a member completes to connect the app. It doesn't shorten the app's own sign-in after that, so members aren't asked to sign in again on your schedule. Turning Claude Science off for the organization or removing a member still stops their app within a few minutes. | ### Capability toggles | Setting in claude.ai | Status for Claude Science | Note | | -------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Science > Enable for your organization | Supported in Claude Science | Off by default for Team and Enterprise. An Owner or Primary Owner turns it on under **Organization settings** > **Claude Science** (see [Enable Claude Science](/docs/claude-science/enable-claude-science)). Assigning seats doesn't turn it on. | | Data and privacy > Rate chats | Supported in Claude Science | When you turn this off, the app hides its response rating buttons and feedback form, as claude.ai does. If your organization uses customer-managed encryption keys (CMEK), you can't turn this setting on and the app doesn't show these controls. | | Organization and access > Organization instructions | Supported in Claude Science | Anthropic adds your organization instructions to the app's requests to Claude, as it does for claude.ai chat, so members don't need to update the app for a change to apply. | | Skills > Organization skills and Policy | Supported in Claude Science | Skills you add under **Organization skills**, and members' own claude.ai skills, appear in Claude Science while **Skills** is on, and **User-created skills** decides whether a member can save a skill from the app to their own claude.ai account. The skills that come with the app and the skills members add in it are controlled on the **Claude Science** page: one switch per Featured skill, and **Allow custom skills** for skills members add themselves (see [Featured connectors and skills](#featured-connectors-and-skills) and [Custom skills](#custom-skills)). | | Capabilities > Web search | Not applicable in Claude Science | This setting governs claude.ai chat. Claude Science can search the web regardless of it, and the **Claude Science** page has no switch for web search. | | Capabilities > Code execution and file creation | Not applicable in Claude Science | This setting governs the code sandbox Anthropic hosts for claude.ai chat. Running code on the member's computer, or on compute the member connects, is the core of Claude Science and can't be turned off; you govern what that code can reach with the [network allowlist](#network-allowlist), [SSH hosts](#ssh-hosts), and [Modal](#modal) controls. | | Capabilities > Allow network egress and Domain allowlist | Supported in Claude Science | These settings govern the hosted sandbox for claude.ai chat. Claude Science's sandbox has its own allowlist: manage it for the whole organization with the **Manage network allowlist** switch on the **Claude Science** page (see [Network allowlist](#network-allowlist)), or leave it off and let members manage their own. Administrators can also extend a member's list per device with the sandbox network keys in the [configuration file reference](/docs/claude-science/configuration-file-reference). | | Data and privacy > Location metadata | Not applicable in Claude Science | Claude Science doesn't send location data with requests to Claude, so there is nothing for this setting to govern. | | Capabilities > Memory (Enable memory for your team) | Supported in Claude Science | This setting governs memory in claude.ai chat. Claude Science keeps a separate memory on each member's computer, which you turn on or off for everyone with the **Turn on memory for your team** switch on the **Claude Science** page (see [Memory](#memory)). | | Settings for claude.ai projects (Public projects, Retention period for projects) | Not applicable in Claude Science | Claude Science doesn't use claude.ai projects. Its projects are folders on the member's computer. | ### Connectors | Setting in claude.ai | Status for Claude Science | Note | | ---------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connectors > Directory connectors you publish | Supported in Claude Science | Directory connectors you publish on the **Connectors** page are available to members in the app, as in claude.ai. The app reaches them through Anthropic's hosted connector service with the member's own account. | | Roles > connector permissions in custom roles (Enterprise) | Partially supported in Claude Science | Apply to the connectors on your **Connectors** page, which the app reaches through Anthropic. They don't apply to Featured connectors or custom connectors added via the Claude Science app; the **Claude Science** page controls those for every member rather than per role (see [Organization settings](#organization-settings)). | | Plugins > plugins you add for the organization | Partially supported in Claude Science | Plugins you set to **Installed by default** or **Required** are synced to members' Claude Science app, which loads their skills and connectors. Plugins left as **Available to install** aren't offered in the app, and plugin commands don't apply there. Which Featured connectors and skills members can use, and whether they can add their own, are separate controls on the **Claude Science** page (see [Featured connectors and skills](#featured-connectors-and-skills), [Custom connectors](#custom-connectors), and [Custom skills](#custom-skills)). | | Connectors > Tunnels API (Enterprise) | Partially supported in Claude Science | A connector your organization serves through a tunnel works in the app the same way it does in claude.ai, because the app reaches Directory connectors through Anthropic's hosted connector service. Custom connectors a member adds in the Claude Science app connect directly from the member's computer and never use a tunnel (admins can restrict this in [Custom connectors](#custom-connectors)). | | Connectors > connectors members add themselves | Supported in Claude Science | In claude.ai, members use only the connectors on your **Connectors** page. In Claude Science, members can also add custom connectors (a server URL or a local command) while the **Allow custom connectors** switch is on, which it is by default for Team and not for Enterprise, and the **Connectors** page and its restrictions don't apply to those. Turn off the **Allow custom connectors** switch under **Organization settings** > **Claude Science** to limit members to Featured connectors and the Directory connectors you publish (see [Custom connectors](#custom-connectors)). | | Connectors > Desktop extension allowlist | Not applicable in Claude Science | Claude Science doesn't install desktop extensions, so there is nothing for this setting to govern. | ### Data and privacy | Setting in claude.ai | Status for Claude Science | Note | | -------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data and privacy > Encryption keys (customer-managed keys) | Supported in Claude Science | The content Anthropic stores from Claude Science (model-call logs, skills members publish, and, where the Compliance API is enabled, session transcripts) is encrypted under your key. Data stored on the member's computer isn't hosted by Anthropic, and work members send to their own SSH hosts, Modal account, or scientific model endpoints doesn't pass through Anthropic, so neither is under your key. In organizations that use customer-managed encryption keys, the app also hides its response rating buttons and feedback form, as claude.ai does. See [Customer-managed encryption keys](/docs/claude-science/how-claude-science-works-with-your-data#customer-managed-encryption-keys). | | Data and privacy > Data residency (US-only inference), or the regional processing terms in your contract | Supported in Claude Science | Governs where Anthropic processes Claude Science requests to Claude, as for your other Claude products. It doesn't cover code that runs on the member's computer, SSH hosts, or Modal account (the same boundary as Claude Code). | | Data and privacy > HIPAA Compliance | Not applicable in Claude Science | Organizations with HIPAA compliance enabled can turn Claude Science on, but its use isn't covered under your BAA and members must keep protected health information out of it. These organizations start from stricter defaults, listed under [Defaults by plan](#defaults-by-plan). | | Data and privacy > Retention period for chats and projects | Partially supported in Claude Science | The auto-delete window doesn't cover data on members' computers or the model-call logs Anthropic keeps for this product. For Enterprise organizations with the Compliance API enabled, the window does apply to the session transcripts it returns. | ### Audit and compliance | Setting in claude.ai | Status for Claude Science | Note | | ------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data and privacy > Export audit logs | Not available in Claude Science | Claude Science doesn't write events to the audit log. For Enterprise organizations with the Compliance API enabled, changes to your Claude Science organization settings are recorded in its Activity Feed instead. | | Data and privacy > Compliance API | Supported in Claude Science | Enterprise plans only. The [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) returns read-only transcripts of members' Claude Science sessions (this coverage is in beta) and records changes to your Claude Science organization settings in its Activity Feed. Sessions in organizations with HIPAA compliance enabled aren't captured. See [Compliance API coverage](/docs/claude-science/how-claude-science-works-with-your-data#compliance-api-coverage). | | Data and privacy > Export data | Not available in Claude Science | The organization export doesn't include Claude Science conversations and files, which are stored on members' computers (the same as Claude Code). | ### Usage, models, and billing | Setting in claude.ai | Status for Claude Science | Note | | ---------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Usage > Extra usage and Spend limits | Supported in Claude Science | Claude Science usage counts toward each member's 5-hour and weekly usage limits, in the same pool as Claude Code and Cowork. | | Billing | Supported in Claude Science | Claude Science uses the same seat as the rest of claude.ai, so there is nothing separate to purchase. | | Models > Model access and Default model (Enterprise) | Supported in Claude Science | Claude Science follows your **Models** page. Turning a model off, for the whole organization or for a custom role, removes it from those members' model picker in the app within a few minutes, and requests for that model are refused. Your **Default model** setting applies in the app as it does in claude.ai. Team plans don't have the **Models** page. | | Analytics (from the user menu) | Supported in Claude Science | Analytics has a **Claude Science** tab with adoption and session metrics, and the spend charts on the **Overview** tab can be filtered to Claude Science (see [Monitor usage](/docs/claude-science/monitor-usage)). | ### Offboarding and local data | Setting in claude.ai | Status for Claude Science | Note | | ------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Removing a member (local data) | Not available in Claude Science | Removing a member ends their access to Claude Science but doesn't delete data already on their computer. Use your device management software for that (see [Manage on devices](/docs/claude-science/manage-on-devices)). | | Deleting local data | Not available in Claude Science | When a member deletes Claude Science data on their computer, Anthropic isn't notified, so the matching server-side model-call logs keep their standard retention period. Compliance API session transcripts, where captured, remain until their retention period ends. | # Artifacts Source: https://claude.com/docs/claude-science/artifacts An artifact is a file Claude saves into the project: a figure, processed dataset, report, notebook, or other output. An artifact is a file Claude saves into the project: a figure, processed dataset, report, notebook, or other output. Artifacts are stored on your computer in the app's data folder and persist until you delete them. Other files Claude writes during a session are temporary and are cleared a few hours after the session ends; ask Claude to save a scratch file if you want to keep it. ## Working with artifacts Click a linked file in the conversation to open it in a tab beside the chat. HTML artifacts have zoom controls, including fit to width; images zoom up to their native resolution. Open **Files** in the sidebar for a searchable grid of every artifact in the project. From an artifact's menu you can: Open, Open beside session, **View in context**, **Provenance**, Versions, **Copy link**, **Star**, **Rename**, **Download**, or **Delete**. Renaming doesn't break links. **Delete** removes all versions permanently. Files you attach or drop into the composer are listed under **Your uploads**. To copy artifacts outside the app, use **Download** for a single file, or open the project's folder under \~/.claude-science and copy the files directly. ## Versions When Claude saves the same filename again in the same session, the artifact gains a new version. You can also edit text-based artifacts (Markdown, code, plain text) directly: click **Edit content**, make changes, and **Save** to create a new version. Images, PDFs, HTML, and tables can't be edited in place. When an artifact file is open, a version stepper and a diff toggle appear. In diff mode, you can choose which earlier version to compare against; the previous version is the default. Older versions are read-only; to restore one, ask Claude to save it again. Links Claude puts in the conversation point to the specific version that existed at the time. ## Provenance Every artifact version records how it was made. Open **Provenance** from an artifact's menu to see five tabs: * **Messages**: the conversation around the save. * **Code**: a reproducible script, downloadable as a script or notebook. * **Execution Log**: every command that ran. * **Environment**: the environment name, language version, and every installed package with its version. * **Review**: findings from [the reviewer](/docs/claude-science/the-reviewer). The **Execution Log** is the authoritative record of what ran. If the **Code** tab and the log disagree, trust the log. ## Deleting artifacts Deleting a session keeps its artifacts and their provenance. Deleting a project deletes all of its sessions, artifacts, and project-scoped memory. # Claude Science changelog Source: https://claude.com/docs/claude-science/changelog Release notes for Claude Science, including new features, improvements, and bug fixes by version. * On Windows, environment setup now handles user folders with accented or non-Latin names, tries again if Windows briefly refuses to start the environment installer, and no longer needs the Microsoft Visual C++ Redistributable * The app now warns you a few days before your sign-in expires and offers a "Sign in again" button * Various bug fixes and security improvements * Claude Science is now available for Windows: download it from [claude.com/product/claude-science](https://claude.com/product/claude-science), and see [Get started](/docs/claude-science/get-started) for setup * Various bug fixes and improvements * On Linux, commands, notebook cells, and local connectors work again on systems with bubblewrap's recent security update * Cloud storage in Settings (Amazon S3, S3-compatible services, and Google Cloud Storage with HMAC keys) now works behind a TLS-inspecting proxy such as Zscaler or Netskope, trusting the same corporate root certificate as sign-in and the Claude API * Various bug fixes and security improvements * Messages now show when they were sent: hover one of your messages to see the time, and Claude's replies show it next to their copy and feedback buttons * Reviewer findings now appear as cards directly under the message they refer to, instead of a single summary card; click a card to open the reviewer's reasoning * When a connector's sign-in expires mid-session, Claude now tells you which connector to reconnect, and Settings > Connectors shows "Sign-in expired" with a Reconnect button * Choosing a model whose safeguards block most life sciences research now shows a short warning first, with a one-click switch to an alternative model * Sessions on Claude Opus 5 now stay focused on what you asked for, with fewer unrequested analyses, figures, and sub-agents * On macOS behind a TLS-inspecting proxy (such as Zscaler or Netskope), Python, pip, curl, and git inside a session now trust the same corporate root certificate that environment builds already use * Tab-separated (.tsv) files open as tables, and the 3D structure viewer follows dark mode and opens small-molecule files (SDF, MOL2, XYZ, and similar) in stick view * First-time setup now includes a memory step, with memory on unless you switch it off there; existing installs keep their current setting (change it anytime under Settings > Memory) * Security hardening across the analysis sandbox and credential handling on macOS and Linux * Lots of other miscellaneous improvements and fixes * On macOS, installs that showed an environment setup error in their first session now repair themselves automatically after updating; the Featured connectors become available once the repair finishes, which can take a few minutes * Star a session from its menu to keep it in a Starred section at the top of your project's session list * Get notified when any of your sessions finishes or needs your input, even while you work in another project. In-app notifications are on by default; sound and desktop notifications are under Settings > General > Notifications * Set reasoning effort for a single session from the session options next to the message box; the value in Settings stays the default for new sessions * On Pro and Max plans, see your credit balance and monthly spend limit and turn usage credits on or off under Settings > Usage * When you ask for a plan, Claude now waits for your approval before running code or marking steps done * Lots of other miscellaneous improvements and fixes **New** * **Improved context preservation.** On Max, Team, and Enterprise plans, sessions go much further before older messages are summarized. * **Works on corporate networks.** Sign in and install packages on networks with corporate proxies, TLS inspection, or authenticated package mirrors. Mirror credentials go in Settings. No config files needed. * **Search your memories.** Find anything Claude remembers from the memory screen. Results are highlighted and jump to where they live. The screen also loads faster now. * **Archive projects.** Tidy your project list without deleting anything; archived projects keep all their data and can be brought back anytime. * **Password sign-in for SSH machines.** Adding a remote machine that asks for a password instead of a key is now supported. You're prompted when it's needed, and the password is never saved to disk. * **Compute monitor.** See every running kernel with its memory and CPU use from the new Compute tab. Kernels can be stopped if needed with optional feedback sent to the agent such as "redo this analysis using less memory". **Improvements and fixes** * **Richer artifact previews.** HTML files show rendered thumbnails, Word documents show text previews, large CSVs show their structure, and PDFs show their first page. * **Parquet files open as tables.** See a parquet file's columns and first rows right in the app, even for very large files. * **Memories stay in their project.** Notes from one project no longer surface in another. * **Annotations travel with your message.** Annotations you've added appear above the message box and carry over when you open a side chat. * **Less disk space for huge files.** When Claude saves the same very large file over and over, it can now keep just the latest version instead of every copy. * **The conversation view holds still.** Images no longer shove the page as they load, "View in context" lands on the right message, and mentioning a file always attaches the right one. * **Edit messages with attachments.** Editing an earlier message now supports file mentions, attachments, and uploads. * **Many other miscellaneous fixes and improvements.** **Features** * Sessions now pause and ask for your confirmation before spending extra usage. Billed usage credits are never drawn on a dismissible warning alone. * Claude can now monitor how much memory and processing power its computations are using, and plan its work accordingly. * Search from inside a project: the project view now has a search button that opens the same search as Cmd+K. * Download any artifact from any surface: every artifact menu now includes a download option. * Starred artifacts now pin to a new Starred section at the top of the Library, with a star badge. **Fixes** * Fixed a crash that could prevent very large sessions from loading. * Fixed several ways a running session could stall or stop early, including long thinking pauses being cut off mid-run and sessions resuming incorrectly after a crash. * Fixed the app sometimes becoming unresponsive after an automatic update. * Code blocks now switch correctly when your system switches between light and dark mode. * Lots of other miscellaneous improvements and fixes. * **Fixed a bug where idle sessions were consuming usage.** * Lots of other miscellaneous improvements and fixes. **Features** * Auto-review is now available on the Pro plan: turn it on from the session settings, and it stays off until you do. * Artifact previews: zoom HTML artifacts (including fit to width), zoom images to native resolution, and choose which version an artifact diff compares against * Import skills from private GitHub repositories using your own GitHub credentials * LaTeX previews now resolve cross-references — \ref, \eqref, and section numbering render the way your document intended * Dashboard upgrades: a project switcher with live per-project status, project names on the "Now" cards, a visible search button, and ⌘K search now matches project descriptions too * Annotate artifacts faster: drag image annotation pins to reposition them, and use @/# mentions in annotation comments **Fixes** * Pasted attachments no longer disappear before their first use, very large text and JSON previews no longer freeze the tab, and a stale usage-limit banner now clears itself once your usage limit resets * Cloning a repo or unpacking an archive no longer floods the chat with every image it contains * The Reviewer no longer gets stuck on "Reviewing…" or hides its findings tray * Flaky read-only connector tool calls now retry once automatically instead of failing your turn, and connector setup errors tell you what's actually wrong * A corrupt pasted image no longer breaks the transcript * Upgrading with a very large history database no longer fails partway through * Fixed a crash when the browser's auto-translate feature modified the page * Lots of other miscellaneous improvements and fixes * Corporate networks: environment builds now work behind TLS-inspecting proxies (such as Zscaler or Netskope). On macOS, corporate root CAs in your keychain are picked up automatically for conda/pip package downloads; on macOS or Linux you can also point at a CA-bundle file under Settings > Network > Package mirror. The mirror card's Check button now verifies TLS trust with the same bundle the builds use. (In-session `pip`/`curl` and the Desktop app's guest-VM builds are not covered) * Package mirrors: point conda and pip at your organization's internal mirror (Artifactory/Nexus) via Settings > Network > Package mirror. Setting a mirror also drops the public package hosts from the sandbox network allowlist * OpenAlex now requires a free API key for full-text access. Claude Science resolves access automatically or asks you in the session when a key is needed; you can also add and validate a key anytime under Settings > Credentials * New Context usage view: see how full a session's context window is and where tokens go, from the + menu in the composer * Lots of other miscellaneous improvements and fixes * Public launch of Claude Science # Cloud storage Source: https://claude.com/docs/claude-science/cloud-storage Connect Amazon S3, Google Cloud Storage, or Azure Blob Storage so Claude can read data and write results in place, with your permission. Connect Amazon S3, Google Cloud Storage, or Azure Blob Storage so Claude can read data and write results in place, with your permission. In **Settings > Credentials**, choose **AWS**, **Google Cloud**, or **Microsoft Azure**, then Connect. Provide the credential (access key, service-account JSON, HMAC key, service principal, or connection string) and list the bucket names (AWS, GCP) or **Blob containers** (Azure) this credential covers. S3-compatible stores use the AWS form with the **S3-compatible endpoint** field; you'll need to allowlist that endpoint host separately. Listing a bucket adds its address to the sandbox network allowlist so code can reach it without a per-call card. Access within the bucket is still limited to the credential's permissions. Credentials are encrypted on your computer and sent only to the provider they belong to. Claude reads and writes objects with ordinary code using the provider's Python library (`boto3`, Azure SDK). **Settings > Storage** lists connected credentials and lets you browse and import objects (up to 100 GB) or export artifacts. From code, reach Google Cloud Storage with an **HMAC key** via `boto3`, or use the import/export flow. `gsutil`, `gcloud storage`, and the google-cloud-storage Python library use path-style addresses that aren't reachable from the sandbox. Any code Claude writes can use credentials you add here. If a bucket should never be reachable from an analysis session, don't add its credential. # Command line settings Source: https://claude.com/docs/claude-science/command-line-settings Reference for the claude-science command: every subcommand, the serve flags, the single-use login link, and the environment variables Claude Science reads. Reference for the claude-science command: every subcommand, the serve flags, the single-use login link, and the environment variables Claude Science reads.\ claude-science serve starts Claude Science and opens the web app in your browser at a single-use login link. Everyday use is that one command. The others manage the running program: they mint login links, report status, follow logs, install updates, and merge data directories. On Windows, the installer adds the command to your PATH for new terminals. There the app window you open from the Start menu is the everyday way in, and the commands below manage the same running program. ## Commands | Command | What it does | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `claude-science serve` | Start the background program and open the web app in your browser at a single-use login link. One runs per data directory; Ctrl-C stops it. | | `claude-science open` | Mint a fresh login link from the running program and open it in your browser. | | `claude-science url` | Print a fresh login link alone on standard output and nothing else. | | `claude-science status` | Print whether the program is running, the version, and the port, as JSON. | | `claude-science logs` | Print the newest log file from the data directory. `--tail` follows it live. | | `claude-science stop` | Stop the program cleanly. | | `claude-science update` | Check for and install an update. `--check` only reports; --to `` installs a specific version, which is also how you roll back. Updates are signature-verified and replace the binary atomically. | | `claude-science import` `` | Merge another data directory, or its database file, into this one. | | `claude-science uninstall` | Windows only. Remove the app, its shortcuts, and its PATH entry while keeping your data; `--purge` also deletes the data directory. Quit Claude Science first. | | `claude-science --version` | Print the version. | | `claude-science` `` --help | Print help for any command. | `import` has no preview and no undo. Back up the data directory before you run it; running the same import a second time is safe. ## Global flags These two work on every command. On Windows, `~` in the defaults below is your user profile folder, `%USERPROFILE%`. | Flag | Default | What it does | | -------------------- | ------------------------------- | ------------------------------- | | `--data-dir` `` | `~/.claude-science` | The data directory to use. | | `--config` `` | `~/.claude-science/config.toml` | The configuration file to read. | ## The login link When serve starts, it prints a line of the form `Web UI -> http://localhost:/?nonce=...`. The nonce is a one-time password: it signs one browser tab in and then expires, about three minutes after it is printed. The signed-in tab stays signed in until you restart the program.\ You never need to keep a link. claude-science open mints a fresh one and opens it in your browser whenever you want to sign in again. For a machine you reach over SSH, claude-science url prints a fresh link alone on standard output: run it there, then open the printed link through your tunnel. The app listens on 127.0.0.1 unless you change --host, so it is reachable only from your own machine. ## Flags for serve | Flag | Default | What it does | | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--port` `` | `8000` | The port the web app is served on. 0 picks a free port. | | `--no-browser` | off | Do not open a browser. url prints a login link any time you want one. | | `--detached` | off | Run in the background. Implies --no-browser. | | `--no-auto-update` | off | Do not check for or install updates. For a pinned or centrally managed install. | | `--host` `
` | 127.0.0.1 | The address the app listens on. Anything else exposes the app to your network; prefer an SSH tunnel. | | `--base-path` `` | unset | Serve the app under a URL prefix behind a reverse proxy. | | `--allow-origin` `` | unset | An extra browser Origin allowed to connect; repeat the flag for more than one. It does not change which sites Claude can reach. | | `--sandbox-port` `` | port + 1 | The separate origin that previews of generated HTML are served from, so a previewed page cannot read your session. | | `--verbose` | off | Show startup and info log lines on the console; by default they go only to the log file. | ## Dangerous flags `--dangerously-no-sandbox` runs code with full read and write access to your home directory and an unrestricted network. `--dangerously-skip-approvals` approves every permission card automatically, for everything, until you restart without the flag; questions addressed to you still appear. Neither belongs in everyday use. ## Environment variables `DO_NOT_TRACK`, set to any value other than `0` or `false`, turns usage analytics and error reports off. It is the same switch as `disable_telemetry = true` in the configuration file. `GITHUB_TOKEN` is optional and is used only against `api.github.com`, to lift the rate limit when you install a skill from a GitHub repository. Claude Science also reads the standard proxy variables (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, and `ALL_PROXY`); see [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks#connect-through-an-outbound-proxy). The proxy address variables are the one case where the environment overrides the configuration file, and `NO_PROXY` is merged with the `no_proxy` key rather than replacing it. Every other setting belongs in the configuration file. ## See also Connect an SSH host and run jobs on it. # Comments Source: https://claude.com/docs/claude-science/comments Comments let you pin notes to specific parts of an artifact instead of describing a location in prose. Comments let you pin notes to specific parts of an artifact instead of describing a location in prose. Select text in a Markdown, plain-text, LaTeX, or code file; select text in a PDF; click a point on an image or figure; or turn on **Comment** and click an element in a rendered HTML report. You can also comment on session transcripts. You can't comment on tables or other artifact types. ## Leaving a comment * Select content in an artifact and click **Comment**. * Type your comment and press Enter (or click **Save**). Press Shift+Enter for a new line. * The comment appears as a highlighted badge (text) or numbered pin (images). Hover to read it; click to **Edit** or **Delete**. ## Sending comments to Claude Saving a comment doesn't send it. Pending comments appear above the message box and are sent with your next message. This lets you batch several comments and send them together, or send them one at a time. Claude receives each comment with its filename, the quoted selection (or marked image), and your note. Once sent, comments leave the artifact and appear as cards on the message. Comments don't have threads or a resolve state. To revise an artifact again after Claude updates it, comment on the new version. Limits: comment text is capped at 1,000 characters. Comments aren't included in downloads and don't appear in **Files**. # Compute providers Source: https://claude.com/docs/claude-science/compute-providers Claude Science can run jobs on an external cloud provider you control, and connect to model servers that serve scientific models over HTTP. Claude Science can run jobs on Modal using a Modal account you own and control. You connect your account, jobs run on it, and Modal bills you directly. Anthropic doesn't provide or bill compute and never sees a payment method. ## Connecting Modal In Settings > Compute > **Cloud providers**, click Connect on the Modal card. If you've signed in with the Modal CLI (`modal token new`), the app reads `~/.modal.toml` automatically; click Check again after the file exists. Alternatively, paste a **Token ID** and **Token secret** in Settings > Credentials, under Modal. Tokens are stored encrypted on your computer and never shown to Claude. ### Workspace restrictions set by your organization On Team and Enterprise plans, your organization's admin can limit Modal to specific workspaces. When Claude uses your Modal token, the app checks the workspace that Modal reports for that token, not the label in your `~/.modal.toml`. If that workspace isn't on your organization's list, the app tells you that this Modal workspace is not allowed by your admin, and Claude can't run jobs there until you connect a token from an allowed workspace. Your admin can also turn Modal off for the organization (see [Modal](/docs/claude-science/admin-controls#modal)). If your organization manages the network allowlist, set **Network restrictions** on the Modal page under **Settings** > **Compute** to **Allowlist** or **No network** before you run jobs. Jobs from a Modal setup with unrestricted network access are refused while your organization manages the list (see [Network allowlist](/docs/claude-science/admin-controls#network-allowlist)). ## Running cloud jobs When work needs a GPU or more memory than your machine has, Claude proposes a job and a **Start a Modal job?** card appears. The card shows the Modal profile, exact machine spec (for example, H100, 8 CPUs, 32 GiB), a note that billing is per-second, and the maximum billable time. It links to Modal's pricing page. Approve per job, or for the conversation or project. A separate card asks before Claude opens a Modal setup shell (capped at 30 minutes, no GPU). Input files are limited to 1 GiB per submit. For larger inputs, Claude can stage data to a Modal Volume and mount it into the job. Outputs written to `./out/` (up to 5 GiB) are returned with logs. Closing the app doesn't cancel a running Modal job; it continues billing until it finishes or times out. Cost controls: there's no spend ceiling. Each job is approved individually with its machine and time limit visible. **Concurrent jobs** (default 10, set on the Modal page under Settings > Compute) caps simultaneous containers that Claude Science on this machine can run. **Default container timeout** is 12 hours (maximum 23), enforced by Modal. Track spend on Modal's dashboard. On the Modal page under Settings > Compute you can set the Modal environment and the default application name used for containers. ## Container images Claude derives a container image from the environment a job needs and builds it once on Modal's build servers, then reuses that image for later jobs until the environment changes. Claude tracks built images in the Details document on the Modal page under Settings > Compute. ## Scientific model endpoints Claude Science can connect to a model server (hosted, or a container you run) that serves a scientific model over HTTP, and call it directly from analyses. On Team and Enterprise plans, your organization's admin can turn off scientific model endpoints for the organization. When your admin turns them off, you can't connect these providers or use endpoints you set up earlier, and the settings you entered are kept. Turning them off doesn't change which Claude models you can use (see [Scientific model endpoints](/docs/claude-science/admin-controls#scientific-model-endpoints)). If your organization manages the network allowlist, an endpoint at a public or internal host name works only while that list includes the host. ### NVIDIA BioNeMo NIM Model endpoints are available in Claude Science on macOS and Linux. In Settings > Compute, under Model endpoints, click Connect on NVIDIA BioNeMo NIM. Import the skills from the BioNeMo Agent Toolkit, add your NVIDIA NGC API credential, and connect to NVIDIA-hosted API endpoint, or choose to run the model as a local container (On a machine with an NVIDIA GPU). Once connected, ask Claude to start a local Docker NIM container or set up a remote connection for a specific NIM skill from the BioNeMo Agent Toolkit. # Configuration file reference Source: https://claude.com/docs/claude-science/configuration-file-reference Claude Science's config.toml file: where it lives, how its values interact with the Settings page, and the network-related keys for the outbound proxy, certificate bundles, package mirror, and sandbox network allowlist. Claude Science reads optional settings from a TOML file named `config.toml` in its default data folder, which is `~/.claude-science/config.toml` on macOS and Linux and `%USERPROFILE%\.claude-science\config.toml` on Windows. Every key has a default, so the app starts with no file present; administrators deploy the file with device management to set fleet policy. The file is read once at startup, so changes take effect after a restart. The `claude-science` command accepts `--config ` to read a different file for one run. On Windows, save the file as UTF-8 and write Windows paths inside it in single quotes (for example `'C:\ProgramData\corp\corporate-ca.pem'`) or with forward slashes, because a backslash inside a double-quoted TOML string is an escape sequence and a file that fails to parse prevents Claude Science from starting. ## Network configuration The network-related keys, grouped by the TOML table each belongs to. For the package-mirror keys (`[conda] channel_mirror`, `pip_index_url`, and `ca_bundle`) and the proxy key (`[network] proxy`), a value set in the file takes precedence over the matching Settings control, which then shows as managed by your organization so a member cannot override it. The `[sandbox.network]` lists are additive instead: they add to the member-managed lists under **Settings** > **Network** and lock nothing. On Team and Enterprise plans, two settings made for the whole organization under **Organization settings** > **Claude Science** sit above both the file and the Settings page. An [organization package mirror](/docs/claude-science/admin-controls#organization-package-mirror) takes precedence over the mirror keys, and while the organization manages the [network allowlist](/docs/claude-science/admin-controls#network-allowlist), the file's `allowed_domains` are set aside and its `denied_domains` still apply. The `[network] ca_bundle`, `no_proxy`, and `mcp_x509_strict` keys and `[conda] allow_insecure_mirror` have no in-app control. ### App connection keys The `[network]` table configures the app's own connections. | Key | Type | Default | Effect | | ----------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxy` | string (URL) | unset | The outbound proxy for the app's HTTP and HTTPS connections, for example `http://proxy.example.corp:8080`. Supply Basic-authentication credentials in the address. An `https://` (TLS-to-proxy) address applies to the app's own connections only; sandboxed package downloads connect directly when the proxy is `https://`, so prefer `http://`. A proxy variable in the app's environment (including `ALL_PROXY`) takes precedence over this key, which takes precedence over the Settings proxy field and the proxy detected from macOS or Windows system settings. | | `no_proxy` | string (comma-separated) | unset | Hosts that bypass the proxy, as exact hostnames or domain suffixes in one comma-separated string, for example `".example.corp,registry.example.corp"`. Combined with the `NO_PROXY` environment variable and, when the macOS or Windows system settings supply the proxy address, the system's bypass list. Loopback addresses always bypass the proxy. | | `ca_bundle` | string (absolute path) | unset | PEM file added to the app's default TLS trust for sign-in, the Claude API, Anthropic-hosted connectors, update checks, and [cloud storage](/docs/claude-science/cloud-storage) access from Settings (Amazon S3, S3-compatible stores, and Google Cloud Storage with an HMAC key); use it for a corporate root behind TLS inspection. It covers the app's own connections only, while package downloads use `[conda] ca_bundle`. The value must be an absolute path outside the app's data directory (`~/.claude-science`), temporary directories, and any directory you have granted Claude write access to; a system location such as `/etc/claude-science/corporate-ca.pem`, or a folder under `C:\ProgramData` on Windows, is recommended. The file must exist, parse as a PEM bundle, and contain no private key; a failing value is ignored with a warning. On Windows, when this key and `[conda] ca_bundle` are both unset, the roots in the computer's Trusted Root Certification Authorities store are trusted automatically instead. | | `mcp_x509_strict` | `"auto"`, `"relaxed"`, or `"strict"` | `"auto"` | How strictly local connectors check a corporate certificate's profile. With `"auto"`, Claude Science relaxes the strict check when it detects TLS inspection from a configured `[network] ca_bundle`. Connectors pick up a change at their next relaunch. | ### Package download keys The `[conda]` table configures where analysis environments fetch packages from and how those downloads verify certificates. | Key | Type | Default | Effect | | ----------------------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channel_mirror` | string (URL) | unset | Base URL of an internal conda mirror. Channel names resolve beneath it, so `/conda-forge/noarch/repodata.json` must return the conda-forge index. Setting it removes the public conda hosts from the sandbox allowlist and admits the mirror host, which environment builds contact directly from the workstation, not through an outbound proxy. Must be `https://` on port 443 or 8443 (an `http://` URL is accepted only when `allow_insecure_mirror` is set), by DNS name, with no embedded credentials. A deployed value these rules reject prevents the app from starting. An [organization package mirror](/docs/claude-science/admin-controls#organization-package-mirror) set under **Organization settings** > **Claude Science** takes precedence over this key. | | `pip_index_url` | string (URL) | unset | A PEP 503 simple index for Python packages, for example an Artifactory or Nexus PyPI remote ending in `/simple`. Setting it removes the public Python hosts from the sandbox allowlist. Same URL rules as `channel_mirror`, including the startup failure on an invalid value, and the same precedence of an organization package mirror. | | `ca_bundle` | string (absolute path) | unset | A complete PEM bundle (public roots plus your corporate roots) that package downloads verify against, replacing the default trust list; in this release the bundle alone may not be sufficient for pip, which verifies against the operating system's trust store. On macOS and Linux this key affects package downloads only, and it never fixes sign-in; behind TLS inspection, set `[network] ca_bundle` as well. When unset, Linux uses your distribution's system certificate bundle. On Windows, package downloads verify against the Windows certificate store and do not read this key; leave it unset there unless you need a custom bundle, because a file set on Windows becomes the complete certificate list that code inside sessions trusts and turns off the app's automatic use of the Windows certificate store. Same path rules as `[network] ca_bundle`. | | `allow_insecure_mirror` | boolean | `false` | Allows `http://` mirror URLs in this file (the Settings page accepts `https://` only). Off by default because a plaintext mirror lets an on-path attacker substitute packages. | | `ssl_no_revoke` | boolean | `true` | Windows only. When `true`, conda package downloads skip the certificate-revocation check, which networks that inspect TLS usually cannot answer. Set it to `false` to require the check, so that a revoked or uncheckable certificate is rejected. pip downloads and the app's own connections are unaffected. | ### Sandbox network keys The `[sandbox.network]` table adjusts the network allowlist the analysis sandbox enforces. Members see the same allowlist under **Settings** > **Network**. | Key | Type | Default | Effect | | ----------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | When `false`, code Claude runs has no network access: package installs and data fetches inside the analysis fail, while the app's own connections are unaffected. This is a no-network mode, not a way to skip the allowlist. | | `allowed_domains` | array of strings | `[]` | Domains added to the built-in allowlist, as exact hostnames or wildcards such as `*.example.org`. While the organization manages the [network allowlist](/docs/claude-science/admin-controls#network-allowlist) under **Organization settings** > **Claude Science**, these domains are set aside and the organization's list applies. | | `denied_domains` | array of strings | `[]` | Domains added to the built-in denylist. A denied domain is blocked even if it also appears on the allowlist, and the built-in denylist entries cannot be removed. | ## Related resources * [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks): how to apply these keys for a proxy, TLS inspection, or an internal mirror * [Network requirements](/docs/claude-science/network-requirements): the built-in allowlist and denylist these keys adjust * [Manage Claude Science on devices](/docs/claude-science/manage-on-devices): deploying `config.toml` with device management * [Command line settings](/docs/claude-science/command-line-settings): the `--config` and `--data-dir` flags # Connectors and skills Source: https://claude.com/docs/claude-science/connectors-and-skills Connectors give Claude access to external data sources during an analysis. Connectors give Claude access to external data sources during an analysis. Skills are written instructions Claude loads when relevant, covering how to run a method, which tools to use, and what to verify. Both are managed in Settings and apply across all projects. ## Featured connectors Claude Science includes Featured connectors to public life-sciences databases. They're on by default and can be turned off individually in **Settings > Connectors**. On Team and Enterprise plans, your organization can also turn individual Featured connectors off for everyone, and in organizations with HIPAA compliance enabled they start off until an admin turns them on. A connector your organization has off stays listed, grayed, and Claude can't use it (see [Featured connectors and skills](/docs/claude-science/admin-controls#featured-connectors-and-skills)). Featured connectors are read-only and don't require an account or key. Some underlying databases have non-commercial or attribution terms; review each source's license for your use case. | Connector | Sources | | ------------------------- | ---------------------------------------------------- | | Genomes | Ensembl (incl. VEP), UCSC | | Genes & Ontologies | MyGene, UniProt, GO, Reactome, OLS | | Variants | gnomAD, ClinVar, dbSNP | | Human Genetics | GWAS Catalog, eQTL Catalogue, FinnGen, BioBank Japan | | Clinical Genomics | ClinGen, CIViC, Open Targets | | Expression | GTEx | | Regulation | ENCODE, JASPAR, UniBind | | Protein Annotation | InterPro, Pfam, Human Protein Atlas, STRING | | Structures & Interactions | PDB, AlphaFold, EMDB, Complex Portal, IntAct | | RNA | Rfam | | Omics Archives | GEO, ArrayExpress, PRIDE, MGnify, MetaboLights | | Cancer Models | cBioPortal | | Chemistry | PubChem, ChEBI, Rhea, BindingDB | | Drug Regulatory | FDA drug data, openFDA | | Literature Graph | OpenAlex, arXiv | | Research Resources | Grants.gov, Antibody Registry | Additional Featured connectors: **BioMart**, **CellGuide** (CELLxGENE cell types), **ZINC** (purchasable chemical space), and **Ketcher Chemistry** (2D molecule sketcher). Four Directory connectors are available from the [connector directory](https://claude.com/connectors) and are accessible in Claude Science and other Claude products: **PubMed**, **Clinical Trials**, **ChEMBL**, and **bioRxiv**. On Team and Enterprise plans, directory connectors appear only after an admin adds them. By choosing to enable connectors, you authorize Claude to use the optional enabled resources on your behalf and confirm you have the necessary rights and licenses. These resources and content they reach may be subject to third-party terms (viewable in Settings), and you are solely responsible for compliance. On Team and Enterprise plans, an admin in your organization gives this authorization for the team when turning Claude Science on and choosing which connectors members can use, and you remain responsible for complying with those terms. ## Using connectors Name a source in your request, or describe what you need and Claude chooses from available connector tools. Connector queries appear in the conversation as expandable code steps. Featured connectors you've previously enabled run without a permission card. Connectors you add yourself prompt for approval per tool, with Once, This conversation, This project, or Global scope. The databases behind Featured connectors are on the network allowlist in groups under Settings > Network. Turning off a group disables the connectors that depend on it. ## Skills **Settings > Skills** lists the skills Claude can load. Featured science skills include literature review, indication dossier, and model-specific skills for AlphaFold2, Boltz-2, Chai-1, ESMFold2, OpenFold3, ProteinMPNN (with LigandMPNN and SolubleMPNN), DiffDock, ESM-2, Evo 2, Borzoi, scGPT, and scvi-tools. The AlphaFold2, Boltz-2, Chai-1, and OpenFold3 skills can build sequence alignments on the public ColabFold server (api.colabfold.com), and AlphaFold2 and Boltz-2 do so unless you supply your own alignment files. When a skill uses that server, the job sends your protein sequences to it directly from the computer or your own compute, not through Anthropic. Claude loads a skill automatically when the work calls for it. Type **/** in the composer to open the skill picker and insert one explicitly. On Team and Enterprise plans, your organization can turn individual Featured skills off; a skill it has off stays listed, grayed, and Claude doesn't load it. **Add skill** lets you create your own via **Chat with Claude**, **Write from scratch**, **Upload a skill**, or **Import from GitHub**. **Import from GitHub** works with private repositories too, once you add a GitHub token under **Settings > Credentials**. You can also ask Claude to distill a workflow from an existing session into a skill. On Team and Enterprise plans, adding skills of your own is available only if your organization allows custom skills; skills you added earlier keep working either way (see [Custom skills](/docs/claude-science/admin-controls#custom-skills)). Your admin can also add skills for everyone in your organization from claude.ai. See [Organization skills](/docs/claude-science/admin-controls#organization-skills). # Core concepts Source: https://claude.com/docs/claude-science/core-concepts A project groups related sessions and the artifacts they produce. ## Projects and sessions A project groups related sessions and the artifacts they produce. Projects also let you set up custom instructions for Claude to read at the start of every session. Folder permissions you grant persist across sessions within a project. A session is one conversation thread. Each session has its own workspace folder and multiple running kernels. ## Files stay on your computer Claude reads and writes files in place, in the folders you grant. Anthropic doesn't host or store your files; file content that Claude reads to answer a prompt is sent to Anthropic as part of the conversation, and Anthropic retains it as [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data) describes. If you sign in to Claude Science on a different computer, your files, artifacts, and conversation history don't follow you there. See [Use Claude Science on more than one computer](/docs/claude-science/multiple-computers) for what your account does carry between computers. The one exception to working in place is **Attach files** in the composer: attached files are copied into the application's local data folder so they stay with the conversation. Don't move, rename, or delete files inside \~/.claude-science directly. Doing so can break artifact links and version history. Manage artifacts through the app. ## Permission cards A permission card appears in the conversation each time Claude needs a new kind of access. The card names exactly what's being requested. You can allow or deny each one. | Action | Card title | Scope options | | ---------------------- | ----------------------------------------------------------- | ------------------------------------------------- | | Read or write a folder | Access `` on your computer? | Read-only or Read & write; persists until revoked | | Run code | Run Python code? / Run a shell command? / Install packages? | Once or Always | | Reach a network host | Connect to ``? | Persists until revoked | | Use a connector tool | Use ``? | Once, This conversation, This project, or Global | | Run a remote job | Run this job on ``? / Start a Modal job? | Once, This conversation, This project, or Global | All standing grants are listed in Settings > Permissions and can be revoked there. ## Plans Claude might choose to propose a plan before starting multi-step work. You approve the plan or iterate with Claude on refining it; plan text can't be edited directly. Approved plan steps appear in the conversation and are marked complete as work finishes. ## Sandbox All code Claude writes runs inside an operating-system sandbox on your computer. The sandbox can read and write only the workspace and the folders you've granted. Its network is deny-by-default: outbound connections go through a local proxy that allows only package managers, the scientific databases behind Featured connectors, and hosts you've approved. ## Delegation **Delegation** lets Claude split a request into independent tracks that run in parallel. Turn it on or off per session in the session settings menu; your last choice becomes the default for new sessions. When work splits, a marker appears in the conversation for each track with a status indicator. Click a marker to open that track's transcript. **Stop** ends the whole session; individual tracks can't be stopped separately. ## Memory Memory lets Claude save short facts about you, your projects, and your files across sessions. You choose whether memory is on during first-time setup, and you can change it anytime in Settings > Memory. Saved facts are stored in the app's local database on your computer; they aren't synced to Anthropic. The Memory settings page lists every saved fact. You can edit, delete, add, or clear facts there. A per-session toggle in the session settings menu turns memory off for that session only. Facts Claude recalls for a session are sent to Anthropic as part of that session's conversation, and Anthropic retains them as [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data) describes. On Team and Enterprise plans, your organization's admin can turn memory off for the organization. Memory is then off for you whatever you chose, and your saved facts stay on your computer, where you can still review and delete them (see [Memory](/docs/claude-science/admin-controls#memory) in the admin controls). ## Composer shortcuts * `@` inserts an artifact or uploaded file by name * `#` inserts a past session by title * `/` inserts a skill # Use Claude Science on a corporate network Source: https://claude.com/docs/claude-science/corporate-networks How to run Claude Science behind an outbound proxy, a TLS-inspecting proxy, an internal package mirror, and an egress firewall, with the settings your network team needs for each. Claude Science runs on each member's computer and connects out for sign-in, the Claude API, and package and research hosts, usually through controls your IT organization manages on a corporate network. This page shows the administrator who runs those controls how to point Claude Science at an internal package mirror, configure an outbound proxy and TLS inspection, and hand the firewall team the [network requirements](/docs/claude-science/network-requirements) it needs. Claude Science makes three kinds of outbound connections, each passing through a different part of your network policy: * The app's own connections (sign-in, the Claude API, Anthropic-hosted connectors, update checks) traverse your outbound proxy and TLS inspection. * The analysis sandbox's connections (package hosts and research databases, when Claude runs code) are filtered by the app's own network allowlist; package downloads can be redirected to your internal mirror. * Interactive previews load display libraries from public content-delivery networks in the browser, as ordinary browser traffic governed by your endpoint's web policy. ## Setup at a glance 1. Check the [support table](#what-works-on-a-corporate-network) for your operating systems and network shape. 2. Hand the [network requirements](/docs/claude-science/network-requirements) page to the team that manages your proxy or firewall allowlist. 3. [Point package installs at your internal mirror](#point-package-installs-at-an-internal-mirror) if the public package hosts are blocked, and deploy the mirror credential. 4. [Connect through an outbound proxy](#connect-through-an-outbound-proxy) if your network uses one. 5. If your proxy inspects TLS, [deploy your corporate root certificate](#work-behind-tls-inspection) as two bundles: one for the app, and a differently built one for package downloads. 6. [Deploy the settings with device management](/docs/claude-science/manage-on-devices#deploy-configuration-with-device-management) rather than by hand. 7. If sign-in or a first build fails, match the error against [Troubleshooting](#troubleshooting-corporate-network-errors). ## What works on a corporate network | Network shape | macOS | Windows | Linux | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Explicit outbound HTTP proxy (HTTP CONNECT) | Supported; detected automatically from the system settings | Supported; detected automatically from Windows proxy settings | Supported | | Proxy that requires Basic authentication | Supported, with credentials in the proxy address | Supported, with credentials in the proxy address | Supported, with credentials in the proxy address | | Proxy that requires NTLM, Negotiate, or Kerberos authentication | Not supported | Not supported | Not supported | | Network that only publishes a PAC or WPAD file | Not supported | Supported in the app window, which follows the proxy the script resolves (see [System proxy settings on macOS and Windows](#system-proxy-settings-on-macos-and-windows)) | Not supported | | SOCKS proxy | Not supported | Not supported | Not supported | | TLS inspection on the app's own connections (Zscaler, Netskope, and similar) | Supported with a CA bundle setting | Supported; a corporate root in the computer's certificate store is trusted automatically | Supported with a CA bundle setting | | TLS inspection on conda package downloads | Supported with a CA bundle setting | Supported automatically through the Windows certificate store | Supported with a CA bundle setting | | TLS inspection on pip package downloads | Supported, with the corporate root also installed in the operating system's trust store (see [Corporate root for package downloads](#corporate-root-for-package-downloads)) | Supported automatically through the Windows certificate store | Supported, with the corporate root also installed in the operating system's trust store (see [Corporate root for package downloads](#corporate-root-for-package-downloads)) | | Internal package mirror (Artifactory, Nexus) | Supported | Supported | Supported | | Internal package mirror reached only through the corporate proxy | Not supported | Not supported | Not supported | | Authenticated package mirror | Supported, with the credential saved in Settings | Supported, with the credential saved in Settings | Supported, with the credential saved in Settings | | Local connectors (the bundled research tools) behind TLS inspection | Not supported | Not supported | Not supported | ## Point package installs at an internal mirror When your network blocks the public package hosts (`conda.anaconda.org`, `repo.anaconda.com`, `pypi.org`), point Claude Science at your internal artifact repository instead, and every environment build fetches packages through it. You can set the mirror in three places: once for the whole organization under **Organization settings** > **Claude Science** > **Organization package mirror**, for a fleet with the `[conda] channel_mirror` and `pip_index_url` keys in a [deployed `config.toml`](/docs/claude-science/manage-on-devices#deploy-configuration-with-device-management), or for a single machine under **Settings** > **Network** > **Package mirror**, where the same two settings are called the conda channel mirror and the pip index URL. The steps below use the Settings page, the quickest way to test a mirror URL before you deploy it. The organization setting takes a conda channel URL and a Python package index (PyPI) URL, which apply to every member whether or not the organization manages the network allowlist. They take precedence over a mirror set in a member's configuration file or Settings; the member's values are kept but not used, and their Settings show the package mirror as controlled by their admin. The same URL rules apply as below, and an address that breaks those rules is ignored for that registry rather than stopping the app. Members still sign in to the mirror themselves, once for each mirror host (see [Mirror credentials](#mirror-credentials)), and the mirror removes the public hosts it replaces for every member. See [Organization package mirror](/docs/claude-science/admin-controls#organization-package-mirror). Set both a conda channel mirror and a pip index: analysis environments are built from conda packages, so a pip index alone leaves the first build stuck trying to reach the public conda host. Open **Settings** > **Network**, select **Configure** on the **Package mirror** row, and paste the base URL of your conda mirror. For JFrog Artifactory that is the conda API root or a virtual conda repository, for example `https://yourorg.jfrog.io/artifactory/api/conda/conda-all`. Paste your Python package index, including the `/simple` suffix that Artifactory and Nexus PyPI remotes use, for example `https://yourorg.jfrog.io/artifactory/api/pypi/pypi-remote/simple`. Select **Save**, then **Check**: a green result confirms the mirror answered, and a `401` or `403` on an authenticated mirror is expected until a credential is saved (see [Mirror credentials](#mirror-credentials)). The mirror takes effect for the next package operation without a restart. On a machine with an outbound proxy, confirm with a test environment build rather than the check alone (see [Mirror traffic and your other network controls](#mirror-traffic-and-your-other-network-controls)). The mirror must serve the standard conda channel layout, with one base URL, one directory per channel, and one per platform beneath it: ```text theme={null} / conda-forge/ noarch/repodata.json noarch/.conda linux-64/repodata.json osx-arm64/... win-64/... bioconda/ noarch/... ``` Your mirror must serve at least `conda-forge` (every environment uses it) and `bioconda` for R and bioinformatics work; other channels a member requests (for example `pytorch` or `nvidia`) resolve under the same mirror base, so serve those too if needed. Anaconda's commercial `defaults` channel is rejected while a mirror is configured, so members should use `conda-forge` instead. Do not point the conda mirror at a remote repository configured for a single channel (for example one whose upstream is `https://conda.anaconda.org/conda-forge`): it returns an empty index that the check reports green while every build then fails with `nothing provides `. Use a remote that proxies the conda host root (`…/artifactory/api/conda/conda-remote`), a virtual conda repository, or the conda API root with channel-named remote repositories beneath it. Mirror URLs must use `https://`, name a host by DNS name rather than IP address, and use port 443 or 8443, so an Artifactory instance on its stock port 8081 needs a 443 or 8443 listener or a reverse proxy in front of it. Credentials embedded in the URL are rejected at save time. The Settings page accepts `https://` mirrors only, while Claude Science also accepts an `http://` mirror from `config.toml` when `[conda] allow_insecure_mirror` is set. Validate mirror URLs before distributing a `config.toml`, since an invalid deployed value prevents the app from starting. ### Mirror credentials For a mirror that requires authentication, enter one username and access token under **Settings** > **Network** > **Package mirror** > **Mirror credentials**, using an account scoped to reading the mirror, then run the check so it signs in with the credential. The one credential is presented to both the conda-mirror host and the pip-index host, so if those need different accounts, keep one of them anonymous; the credential is sent only to `https://` mirror hosts. Claude Science stores the credential encrypted in its local database, using a key kept in a file only the member's account can read (on macOS, a copy of that key is in the keychain for recovery), and also writes the credential, automatically, to a plaintext `.netrc` at `~/.claude-science/conda/.netrc` that the conda and pip download tools read during environment builds. Code that runs while an environment builds (a package's `setup.py`, for example) can read that file, Claude's analysis code cannot read either location, and a `.netrc` in the member's home directory is not used for these downloads. For a macOS or Linux fleet that manages credentials centrally, deploy that `.netrc` file yourself instead (on Windows, save the credential in Settings), one `machine ` block per mirror host with `login` and `password` lines and no comments, and use either the file or Settings, not both: a credential saved in Settings rewrites the file from the saved value at the save and at every restart and environment build, while a file deployed with no credential saved in Settings is left alone. Environments a member registers from an existing project folder install their packages inside the analysis sandbox during a session, where the credential is hidden by design, so those environments need a mirror that allows anonymous reads. ### Mirror traffic and your other network controls Configuring a mirror removes the public package hosts from the sandbox's network allowlist and admits the mirror host in their place, so a misconfigured mirror fails with an error that names the mirror rather than falling back to the public hosts. To keep the public hosts reachable alongside the mirror, re-add them under **Settings** > **Network** (`pypi.org`, `*.pypi.org`, `files.pythonhosted.org` for pip, and `conda.anaconda.org`, `repo.anaconda.com`, `anaconda.org`, `*.anaconda.org` for conda). When the organization manages the network allowlist, **Network** settings are read-only, so a member can't re-add them, and the hosts a mirror replaces stay removed even if they are switched on in the organization's list. Environment builds connect to the mirror host directly, never through your outbound proxy: the workstation needs a direct route (typically your VPN or internal network), any workstation firewall must allow the mirror host as a direct destination, and a proxy allowlist entry alone does not reach it. A package failure that names the mirror on a proxy-only network therefore means the mirror is unreachable directly, and a SaaS repository such as `yourorg.jfrog.io` works only if the workstation can reach it directly, so on a proxy-only network host the mirror inside your network. On a proxy-configured machine the **Check** button and a real build can take different paths, so treat a test environment build as the authoritative signal (a known limitation). Mirrors that redirect package files to path-style object-storage URLs (such as `s3.us-west-2.amazonaws.com//...`) fail with `CONNECT tunnel failed, response 403`, because path-style object-storage hosts are on a built-in denylist that cannot be overridden; have the mirror serve the files itself, or redirect to bucket-qualified hostnames such as `.s3.us-west-2.amazonaws.com` and add that hostname under **Settings** > **Network** > **Allowed domains**. The check warns at save time when it sees a redirect to a denied host. The package manager that builds environments ships inside the app, so a first build on a locked-down network downloads no tooling from GitHub. ## Connect through an outbound proxy Claude Science reads its proxy configuration once at startup, so restart it after a change. The first source that sets a proxy address wins: 1. The standard proxy variables in its own process environment: `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` (lowercase spellings also work). `ALL_PROXY` fills in for either proxy variable that is unset, an empty variable counts as unset, and `NO_PROXY="*"` sends all traffic directly. 2. The `[network] proxy` key in `config.toml`, the form to [deploy with device management](/docs/claude-science/manage-on-devices#deploy-configuration-with-device-management). 3. The proxy field under **Settings** > **Network**, where a member can paste a proxy address by hand. It takes effect at the next restart, and when `config.toml` sets the proxy, the field shows as managed by your organization so members cannot override it. 4. On macOS and Windows, the proxy configured in the operating system's settings, which Claude Science detects automatically: an explicit web proxy in macOS network settings, or the proxy server in Windows proxy settings. Write the proxy as an `http://` URL; if it requires a username and password, embed them in the address and percent-encode special characters (for example, `@` in a password becomes `%40`): ```text theme={null} HTTPS_PROXY=http://username:password@proxy.example.corp:8080 HTTP_PROXY=http://username:password@proxy.example.corp:8080 NO_PROXY=.example.corp ``` An `https://` (TLS-to-proxy) address works for the app's own connections only. Sandboxed package downloads tunnel only through `http://` proxies, so with an `https://` address they skip the proxy and connect directly; an `http://` address keeps every connection on the proxy. Claude Science always bypasses the proxy for loopback addresses (`localhost`, `127.0.0.1`, and their IPv6 equivalents), whether or not they appear in `NO_PROXY`, so the app and its background service can always talk to each other. Add your internal domains to `NO_PROXY`; entries match a host exactly or as a domain suffix (`.example.corp` and `example.corp` behave the same), and CIDR ranges such as `10.0.0.0/8` are not matched. `NO_PROXY` entries from the environment, the configuration file, and (when the system settings supply the proxy address) the macOS or Windows bypass list are combined. ### Proxy settings in the configuration file For a fleet, set `[network] proxy` and `no_proxy` in `config.toml`; both keys and their formats are in the [configuration file reference](/docs/claude-science/configuration-file-reference#app-connection-keys). ### System proxy settings on macOS and Windows On macOS, Claude Science detects an explicit system web proxy automatically, so a machine whose proxy your MDM already sets needs no Claude Science configuration unless the proxy requires authentication. macOS keeps an authenticated proxy entry's credentials in the keychain, where Claude Science cannot read them, so connections through the detected proxy fail with HTTP 407 (see [the troubleshooting entry](#the-proxy-requires-its-own-sign-in-http-407)); set `[network] proxy` with the credentials in the address instead. When the network publishes only a PAC or WPAD file, Claude Science on macOS detects it and names the PAC URL in the sign-in error, but does not evaluate it. Set `[network] proxy` to the proxy the PAC file resolves to for Anthropic's hosts. On Windows, Claude Science reads the proxy server and bypass list from Windows proxy settings at startup, which covers a proxy set under **Settings** > **Network & internet** > **Proxy**, in Internet Options, or by Group Policy, so a PC whose proxy your device management already sets needs no Claude Science configuration unless the proxy requires authentication. Windows proxy settings carry no credentials either, so for a proxy that requires Basic authentication, set `[network] proxy` with the credentials in the address. Bypass entries other than host names and domain suffixes are not applied, including the **Don't use the proxy server for local (intranet) addresses** option and entries written as IP ranges, so list internal domains in `[network] no_proxy`. To restart Claude Science on Windows after a settings change, quit it from its notification-area icon and open it again, because closing the window leaves it running. When the network publishes only a PAC or WPAD file, the Claude Science app window follows the proxy that the script resolves for Anthropic's hosts and restarts the app's background service once to apply it. A script-resolved proxy that demands a sign-in of any kind, refuses the connection, or does not answer within a few seconds is not used, and Claude Science keeps connecting as it did before, which on such a network means directly. For a proxy that needs credentials, set `[network] proxy` with them in the address. Claude Science started from a terminal with `claude-science serve` does not evaluate PAC files, so set `[network] proxy` there too. ### How the environment variables reach the app How the variables reach the app depends on the operating system: * On macOS, the menu-bar app reads `~/.claude-science/env`, a file of `KEY=VALUE` lines (`export KEY=VALUE` also works), when it launches. Put the three variables there, then quit and reopen the app; an app started from the Dock or Finder does not see variables exported in a terminal. The file's `NO_PROXY` entries merge with the other sources rather than replacing them. * On Windows, the app reads the variables from the user's environment when it starts, so set them as user environment variables, then quit Claude Science from its notification-area icon and open it again; variables typed into an open Command Prompt or PowerShell window do not reach an app started from the Start menu. Because Claude Science already follows Windows proxy settings, most PCs need no variables, and `[network] proxy` in `config.toml` is the form to deploy. * On Linux, export the variables in the shell or service unit that starts `claude-science serve`. The `env` file is read only by the macOS app. Only Basic proxy authentication, supplied in the proxy address, is supported; NTLM, Negotiate, and Kerberos proxies are not. On macOS and Linux, networks whose only published proxy configuration is a PAC or WPAD file are not supported either, because Claude Science does not evaluate PAC files there. On Windows, the app window follows a PAC or WPAD file as described under [System proxy settings on macOS and Windows](#system-proxy-settings-on-macos-and-windows). For a proxy that only speaks NTLM or Kerberos, a local relay such as `cntlm` or `px` works: the relay runs on the workstation, authenticates to your corporate proxy with the user's credentials, and exposes a plain HTTP proxy on the loopback interface. Point `HTTPS_PROXY` and `HTTP_PROXY` at the relay (for example `http://127.0.0.1:3128`). The loopback bypass governs which destinations skip the proxy, not whether the proxy can be reached, so a loopback relay works as a proxy address. Environment builds reach a configured [package mirror](#point-package-installs-at-an-internal-mirror) directly, not through the proxy. Separately, the `claude-science update` terminal command is its own process: it honors proxy variables exported in that shell but not the macOS `env` file, so export the variables in the terminal first. The background updater inside the running app uses the app's proxy settings. ## Work behind TLS inspection A TLS-inspecting proxy such as Zscaler or Netskope re-signs every HTTPS connection with a certificate from your organization's own root certificate authority, which Claude Science's built-in list of public roots does not include, so until you give it that root, sign-in and package downloads fail certificate verification (the sign-in error is listed under [Troubleshooting](#troubleshooting-corporate-network-errors)). Two settings carry the corporate root and behave differently. Set the one that matches the traffic, and read the warning in [Corporate root for package downloads](#corporate-root-for-package-downloads) before reusing one file for both. ### Corporate root for app connections The `[network] ca_bundle` key in `config.toml` points at a PEM file whose certificates Claude Science adds to its default trust for sign-in, the Claude API, Anthropic-hosted connectors, update checks, and [cloud storage](/docs/claude-science/cloud-storage) access from Settings. For cloud storage, the corporate root applies to Amazon S3 and S3-compatible connections, and to Google Cloud Storage connections that use an HMAC key. The public roots stay in place, so the file holds only your corporate root. The path rules are in the [configuration file reference](/docs/claude-science/configuration-file-reference#app-connection-keys). A failing value is ignored with a warning rather than stopping the app, so a sign-in error behind inspection usually means the bundle did not load, and the app re-reads the bundle every few minutes (about every 30 minutes on Windows), so a corrected file takes effect without a restart. When you deploy a `config.toml`, deploy the bundle files alongside it. On Windows, when neither `[network] ca_bundle` nor `[conda] ca_bundle` (the **CA bundle path** field in **Settings**) is set, Claude Science automatically trusts the root certificates installed for the whole computer (the computer's **Trusted Root Certification Authorities** store, not the current user's) and rechecks that store about every 30 minutes, so a PC whose device management already installs your corporate root there needs no setting. Claude Science reads that store with Windows PowerShell, so on PCs where Windows PowerShell is blocked or restricted for users, set `[network] ca_bundle` for the app's own connections and `[conda] ca_bundle` for code inside sessions instead of relying on the store. If you do set `[network] ca_bundle` on Windows, the file is used instead of the store; write its path in single quotes, for example `'C:\ProgramData\corp\corporate-ca.pem'`, because a backslash inside double quotes is a TOML escape and a file that fails to parse stops Claude Science from starting. ### Corporate root for package downloads Conda package downloads for the analysis sandbox use their own setting, `[conda] ca_bundle`, the complete list of roots those downloads trust, so it must contain the public roots your packages come from as well as your corporate root. On Linux, when the key is not set, Claude Science uses your distribution's system certificate bundle (maintained by `update-ca-certificates` or `update-ca-trust`), so a Linux image that already trusts your corporate root needs no setting at all. On Windows, leave `[conda] ca_bundle` unset unless Windows PowerShell is blocked or restricted for users (covered under [Corporate root for app connections](#corporate-root-for-app-connections)): package downloads there verify certificates through the Windows certificate store and do not read the key, so a corporate root installed for the whole computer is trusted with no setting. A `[conda] ca_bundle` file that exists on a Windows PC becomes the complete certificate list that code inside sessions trusts, in place of the store, and the app's own connections then stop trusting the Windows certificate store automatically, so set `[network] ca_bundle` as well. On macOS and Linux, `[conda] ca_bundle` affects package downloads only, and it never fixes sign-in. The CA bundle path field on the Settings page sets this same `[conda]` key, so filling it in helps package downloads only, and on Windows leave the field empty. Behind TLS inspection you also need `[network] ca_bundle`, which has no Settings field and is set in `config.toml`. pip verifies package downloads against the operating system's trust store, and in this release setting `[conda] ca_bundle` alone may not be sufficient for pip, so also install the corporate root in that trust store: on Linux with `update-ca-certificates` or `update-ca-trust`, on macOS in the system keychain through your MDM, and on Windows in the computer's Trusted Root Certification Authorities store, which pip reads in environments on Python 3.10 or later, the default. ```toml theme={null} [conda] ca_bundle = "/etc/claude-science/complete-bundle.pem" ``` The same path rules apply as for `[network] ca_bundle`; the [configuration file reference](/docs/claude-science/configuration-file-reference#package-download-keys) lists them. Do not point `[conda] ca_bundle` at the single-root file you use for `[network] ca_bundle`: the package-download setting replaces the whole trust list, so a file containing only your corporate root breaks every package download (on Windows, every download made by code inside a session) on any network your proxy does not inspect, such as a laptop on home Wi-Fi. Build the `[conda]` bundle from your system's public roots plus the corporate root. ### What the certificate settings do not cover Code that Claude runs inside a session, such as a `pip install` typed into a cell or an R `install.packages()` call, is covered on macOS but not on Linux. On macOS, Python, pip, curl, git, and downloads from R in the session's environments trust the same certificates as environment builds: the `[conda] ca_bundle` file if you set one, otherwise the system's public roots plus the corporate root Claude Science finds in the macOS keychain (`[network] ca_bundle` alone does not reach in-session code). On Windows, Python, pip, and curl inside a session are pointed at an export of the root certificates installed for the whole computer (or the `[conda] ca_bundle` file if one is set). On Linux, neither bundle reaches code inside a session: curl and git there honor a root installed in the operating system's trust store, but the environment's Python, pip, and R see public roots only, so behind TLS inspection, have Claude install packages into an environment rather than in a cell. The local connectors (the bundled research tools) do not work behind TLS inspection in this release: they run in their own Python environment, and nothing delivers your corporate root to that environment, so their connections fail certificate verification. This is a known limitation. Claude Science does detect TLS inspection from your configured CA bundle and relax the connectors' strict certificate-profile check, which stops them from rejecting a corporate root whose Basic Constraints extension is not marked critical, but that relaxation adds no trust. The Anthropic-hosted connectors keep working once `[network] ca_bundle` is set. Connector installs that use `npm` also keep npm's own certificate configuration. Voice dictation's server-side speech recognition uses a WebSocket connection that is covered by neither the certificate settings nor the proxy settings, so it does not work behind TLS inspection or a mandatory proxy; in the browser, dictation falls back to the browser's own speech recognition. Certificate environment variables set in a shell, such as `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, or `PIP_CERT`, never reach package downloads, because those run in an isolated environment. Use the `ca_bundle` keys instead. ## Troubleshooting corporate network errors ### Token exchange failed: unable to get local issuer certificate Sign-in completes in the browser, then fails with this error when Claude Science's own connection to Anthropic hits TLS inspection without trusting your corporate root. The member sees a notice that the network inspects secure connections, with this error beneath it. Set `[network] ca_bundle` to a PEM file containing your corporate root (see [Corporate root for app connections](#corporate-root-for-app-connections)) and confirm the bundle warning is gone from the app log (`claude-science logs` prints it). ### The proxy requires its own sign-in (HTTP 407) Sign-in fails with this message when the proxy demands credentials the app is not sending, because the proxy address carries none or the proxy was detected from the macOS or Windows system settings, which never supply credentials. Include the Basic-authentication credentials in the proxy address (percent-encoding special characters) under **Settings** > **Network** > **Proxy address**, in `[network] proxy`, or in `HTTPS_PROXY`, then restart the app. Only Basic authentication works, so a proxy that requires NTLM, Negotiate, or Kerberos cannot be satisfied this way. During an environment build, a proxy authentication failure surfaces as a generic HTTP 502 error rather than a 407 message. ### Package downloads are being blocked by network policy An environment build reports this (often with HTTP 502) when it tries to reach the public package hosts on a network that blocks them and no mirror is configured. Configure the mirror under **Settings** > **Network** > **Package mirror**, with both the conda channel mirror and the pip index set. ### HTTP 401 or 403 during an environment build The mirror requires authentication and the build is not presenting a credential it accepts. Check that a credential is saved under **Settings** > **Network** > **Package mirror** > **Mirror credentials** (or, on a fleet that deploys the `.netrc` file directly, that the file has a block for the exact mirror hostname); a credential in `~/.netrc` in the home directory is ignored for these downloads. ### HTTP 401 on the mirror check With no saved credential, a `401` is expected because the check sends none; enter the credential under **Mirror credentials** and run the check again. When a credential is saved, the check signs in with it, so a `401` means the token is wrong or expired. On a proxy-configured machine the check and a build can also take different network paths (see [Mirror traffic and your other network controls](#mirror-traffic-and-your-other-network-controls)). ### Green check, then nothing provides the package The conda mirror URL points at an Artifactory remote repository configured for a single channel, which returns an empty index that the check accepts; see the note in [Point package installs at an internal mirror](#point-package-installs-at-an-internal-mirror) for the mirror URL forms that work. ### CONNECT tunnel failed, response 403, naming an amazonaws.com host The mirror redirects package files to path-style cloud object storage, which the sandbox blocks. Switch the mirror to serve the files itself or to use bucket-qualified storage URLs, as described in [Mirror traffic and your other network controls](#mirror-traffic-and-your-other-network-controls). ### https mirrors must use port 443 or 8443 The mirror is listening on a port the sandbox cannot tunnel to. Put a 443 or 8443 listener or a reverse proxy in front of it, then save the `https://` URL again. ### Local connectors fail with certificate errors behind inspection The local research connectors report certificate failures, while the Anthropic-hosted connectors keep working once `[network] ca_bundle` is set, because the corporate root does not reach the local connectors' own Python environment (see [What the certificate settings do not cover](#what-the-certificate-settings-do-not-cover)). This is a known limitation on TLS-inspected networks. # Custom connectors Source: https://claude.com/docs/claude-science/custom-connectors Add any Model Context Protocol (MCP) server as a Remote (HTTPS web server) or Local command (program on your computer). In **Settings > Connectors** > **Add connector**, choose **Remote** or **Local command** and enter a **Name** (lowercase letters, digits, hyphens). For **Remote**, enter the server URL; **Advanced settings** covers transport (**SSE** or **Streamable HTTP**), OAuth client settings, and the **Headers helper command**. For **Local command**, enter the command; **Advanced settings** covers arguments and environment variables. **Browse Connectors Directory** opens the public directory. Remote servers that need login take you through the provider's sign-in page. On Team and Enterprise plans, you can add and use custom connectors only if your organization allows them. When it doesn't, the **Remote** and **Local command** options under **Add connector** are grayed with a note that custom connectors are disabled by your admin. Custom connectors you added earlier stay listed and grayed, Claude can't use them, and they work again if your organization turns custom connectors back on. See [Custom connectors](/docs/claude-science/admin-controls#custom-connectors) in the admin controls. Every tool from a custom connector starts at **Ask each time**. On the connector's page, set individual tools to **Always allow** or **Block** under **Tools**, or turn on Skip approvals for the whole connector. Skip approvals disables the per-call card for every tool on that connector. Only use connectors from developers you trust. Local-command connectors run inside the sandbox with the same network limits as Claude's code and a per-connector writable directory. Environment variables for local connectors are saved unencrypted in a configuration file readable by your account only; don't put high-value secrets there. On Windows, a local-command connector starts with `npx`, `node`, `python`, or the full path of a program. Connectors launched through `npm` or a `.cmd`, `.bat`, or `.ps1` file aren't supported there. # Enable Claude Science Source: https://claude.com/docs/claude-science/enable-claude-science Claude Science is a desktop app for scientific research. Claude Science is a desktop app for scientific research. It's off by default for Team and Enterprise organizations. Turning it on in **Organization settings** > **Claude Science** opens a short dialog that covers who gets access and which connectors to turn on. You can change any of it later on the same page, which also holds the other [organization settings](/docs/claude-science/admin-controls#organization-settings) for Claude Science: which connectors, skills, compute, network access, and memory members can use. ## Availability Claude Science is in beta. | Plan | Claude Science app access | | ----------- | ----------------------------------------- | | Team | Off; turn on in **Organization settings** | | Enterprise | Off; turn on in **Organization settings** | | Pro and Max | On; no admin action needed | | Free | Not available | If your organization has HIPAA compliance enabled, Claude Science app access is also off by default. You can turn it on, but usage isn't covered under your Business Associate Agreement (BAA) and the app shouldn't be used with protected health information (PHI). These organizations also start with stricter organization settings (see [HIPAA organizations](#hipaa-organizations)). ## Turn on Claude Science Go to **Organization settings** > **Claude Science**.\ Turn on the **Enable for your organization** toggle. The **Turn on Claude Science** dialog opens.\ Complete each step of the dialog, described below, then select **Turn on Claude Science**. Nothing is saved until you do.\ Review the [organization settings](/docs/claude-science/admin-controls#organization-settings) below the toggle, which unlock once Claude Science is on.\ Members with access can [download Claude Science](https://claude.com/product/claude-science) and sign in with their claude.ai account. You need an Owner or Primary Owner role to turn Claude Science on or off. If you have the Admin role, you can add members and assign seats, but you can't turn on Claude Science. Ask an Owner or Primary Owner to turn it on. ### Review role access This step shows who gets access once Claude Science is on. On Team plans, everyone in your organization gets access automatically. On Enterprise plans, members in the built-in roles (User, Admin, Owner, and Primary Owner) get access automatically, and the step lists any custom roles that already include the **Claude Science** capability. To change which custom roles have access, select **Configure in role settings**, or continue and adjust roles later. ### Set up connectors Turn on the tools and data sources your team will use in Claude Science. You can change all of it later. Under **Featured connectors**, the **Claude Science local connectors** row covers the connectors that are built by Anthropic, ship with the app, and run on each member's computer. Expand it to turn individual connectors on or off for the whole organization; you can change this later under [Featured connectors and skills](/docs/claude-science/admin-controls#featured-connectors-and-skills), and members can also turn individual local connectors off for themselves in the app. The **PubMed**, **Clinical Trials**, **ChEMBL**, and **bioRxiv** rows are connectors Anthropic hosts. They start selected, and turning Claude Science on adds the selected ones to **Organization settings** > **Connectors** for your organization, which makes them available to members in Claude Science and in claude.ai. Under **From the Claude connector directory**, you can select additional life-sciences connectors, which are added to your organization the same way. The **PubMed**, **Clinical Trials**, **ChEMBL**, and **bioRxiv** rows and the directory list are read-only if your organization has HIPAA compliance enabled or your role can't add connectors for the organization; add those connectors from **Organization settings** > **Connectors** after enabling. The switches for the local connectors still work, and in an organization with HIPAA compliance enabled they start off so you can turn on the ones you have reviewed. By continuing, you authorize your team to let Claude use the optional enabled resources on their behalf. These resources and content they reach may be subject to third-party terms (viewable in Settings), and your users are solely responsible for compliance. ## Who gets access after you enable Turning on the **Enable for your organization** toggle controls whether Claude Science is accessible to your organization at all. Adding members or assigning seats doesn't turn it on. Once it's on, roles control which members can use it: Built-in roles include the Claude Science entitlement, so those members can download and sign in immediately.\ Custom roles (Enterprise plans only) need the **Claude Science** capability added. Members on a custom role without the capability see the app as unavailable even after you enable it for the organization.\ A custom role whose **Capability access** setting is **All capabilities** already includes Claude Science. The **All generally available** setting excludes beta capabilities such as Claude Science, so for those roles also select the **Claude Science** capability. This is the same pattern as other Claude apps you enable per organization. ## What members see Once Claude Science is enabled and a member's role includes the entitlement, they can download the app from claude.com/product/claude-science and sign in with their claude.ai account. If the **Enable for your organization** toggle is off, members are stopped at sign-in with a message such as "Your organization hasn't turned on Claude Science yet. Ask your admins for access." They can select **Request access** to send that request to the organization's admins, then sign in again once Claude Science is on. On Enterprise plans, members whose custom role doesn't include the capability are stopped the same way, with a message that Claude Science isn't available for their account yet, and can also request access. These requests appear under **Requests** in **Organization settings** > **Notifications**. Turning Claude Science on resolves them, and for a member whose custom role lacks the capability, you give the role access on the **Roles** page. Members who belong to more than one organization on claude.ai, such as a personal account alongside yours, need to choose your organization when claude.ai asks which one to connect. Before they select **Authorize**, they can also select **Switch organization** on the authorization screen to change that choice. A member who connects a Free personal account instead sees "Claude Science requires a Pro or Max subscription." and can select **Switch account** to sign in again and choose your organization. ## HIPAA organizations Organizations with HIPAA compliance enabled can turn on Claude Science during the beta, but usage isn't covered under your BAA, so keep protected health information out of it. The **Turn on Claude Science** dialog opens with a step that says so. In its connectors step the local connectors start off, and you can turn on the ones you have reviewed. The Anthropic-hosted and directory connectors in that step are read-only because the dialog's quick-enable path doesn't include the per-connector HIPAA attestation, so add those from **Organization settings** > **Connectors** instead, where the attestation is required. These organizations also start with stricter organization settings. Featured connectors and skills, SSH hosts, Modal, model endpoints, and memory are off until you turn them on (including for members who were already using them), custom connectors can't be turned on, and the organization always manages the network allowlist. See [Defaults by plan](/docs/claude-science/admin-controls#defaults-by-plan). ## Turn off Claude Science Go to **Organization settings** > **Claude Science** and turn off the **Enable for your organization** toggle. Members can no longer sign in to the app, and members who are already signed in lose access within a few minutes. The app stops accepting new messages and shows a notice that Claude Science isn't available for their account. The other settings on the page keep their values and apply again when you turn Claude Science back on. Data already on members' computers stays there; see [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data) for details. # Get started Source: https://claude.com/docs/claude-science/get-started Install Claude Science on macOS, Windows, or Linux, sign in with your Claude account, and run your first analysis. ## Install Download the installer from [claude.com/product/claude-science](https://claude.com/product/claude-science) and double-click to install. On first launch, the app sets up its runtime and starter Python and R environments, which takes a few minutes, then opens a new tab in your default browser. If no browser tab appears, choose Open from the menu bar icon. Download the installer from [claude.com/product/claude-science](https://claude.com/product/claude-science) and open it. It installs Claude Science for your user account, adds **Claude Science** to the Start menu and the desktop, and opens the app in its own window. The installer is signed by Anthropic, PBC. On first launch, Claude Science sets up the sandbox and downloads its app window engine (about 150 MB) from `downloads.claude.ai` before the window appears, so the first start takes longer than later ones, and a notice shows progress. The starter Python and R environments keep setting up in the background for several minutes after the window opens. **One-time Windows permission.** If Claude Science asks for one-time permission from Windows so that cells can run git and Command Prompt scripts and PowerShell can change folders, **Yes** lets Windows ask for approval (an administrator's password if you aren't one) and **No** leaves those features off. Python and R cells work either way, and the **Ask Windows now** button under **Settings** > **Permissions** grants the permission later. **Notification-area icon.** Closing the window leaves Claude Science running, with an icon in the notification area of the taskbar. Click the icon to reopen the window, or choose **Quit Claude Science** from the icon's menu to stop the app. **Updates.** Claude Science checks for updates in the background and shows **Update available** when one is ready; choose **Restart to update** to install it. Administrators who distribute the app themselves can turn the background check off with `[update] auto_update = false` (see [Manage Claude Science on devices](/docs/claude-science/manage-on-devices#deploy-configuration-with-device-management)). To update by hand instead, open a newer installer, which upgrades the installed copy in place and keeps your data. **Uninstall.** Quit Claude Science from its notification-area icon first, because the uninstaller refuses to run while the app is running. Then uninstall **Claude Science** from **Settings** > **Apps** > **Installed apps**, or run `claude-science uninstall` in a terminal. Either way your data is kept. To remove the data as well, run `claude-science uninstall --purge` in a terminal instead. **Corporate networks.** Claude Science follows the proxy configured in Windows proxy settings and trusts corporate root certificates installed for the whole computer, so most managed PCs need no Claude Science configuration. See [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks). **Differences on Windows:** * Claude runs shell commands with PowerShell. Command Prompt scripts, git inside cells, and folder changes in PowerShell need the one-time Windows permission. * Only folders on local NTFS or ReFS drives can be granted, not network shares, mapped network drives, FAT or exFAT drives (many USB sticks and memory cards), or a whole drive such as `D:\`. Copy such files to a local folder or attach them in the chat. * [Custom connectors](/docs/claude-science/custom-connectors) that run a local command start with `npx`, `node`, `python`, or the full path of a program. Connectors launched through `npm` or a `.cmd`, `.bat`, or `.ps1` file aren't supported. * The **Model endpoints** section of **Settings** > **Compute** (NVIDIA BioNeMo NIM) isn't available. **Linux version under WSL.** The Windows app itself doesn't need WSL. The Linux command-line version of Claude Science also runs under Windows Subsystem for Linux (WSL 2) with Ubuntu 24.04 or later. Inside the Ubuntu terminal, follow the install steps in the Linux tab, then start Claude Science with `claude-science serve --port 8765 --no-browser` instead, and open the printed link in a Windows browser. Install the sandbox dependencies, then run the installer. The sandbox needs bubblewrap 0.8.0 or later and socat, and installing them takes administrator (`sudo`) access; if you don't have it, ask your system administrator to install them. * Ubuntu or Debian: `sudo apt-get update && sudo apt-get install -y curl bubblewrap socat` * Fedora or RHEL: `sudo dnf install -y curl bubblewrap socat` * Arch: `sudo pacman -S curl bubblewrap socat` Ubuntu 24.04's repositories carry a new enough bubblewrap and Ubuntu 22.04's don't; on any distribution, confirm with `bwrap --version` that the installed version is 0.8.0 or later before you start Claude Science. ```bash theme={null} curl -fsSL https://claude.ai/install-claude-science.sh | bash ``` ```bash theme={null} claude-science serve ``` First launch prints a local URL right away, then continues setting up its starter Python and R environments. To run Claude Science on a remote server and use it from your computer, see [Run on a remote Linux server](/docs/claude-science/run-on-remote-linux-server). Claude Science is a local application, not a website, so there's no public URL to visit. On Windows it opens in its own window, and on macOS and Linux it opens in a browser tab. Open it from the application itself: the menu bar icon on macOS, the Start menu on Windows, or the `claude-science` command on Linux. On a remote server, the sign-in link reaches your browser through an SSH tunnel; see [Run on a remote Linux server](/docs/claude-science/run-on-remote-linux-server). ## Sign in and complete setup When the app opens, sign in with your Claude account. On Windows, click the **Sign in on the web** button and confirm with **Continue**; the app opens claude.ai in your default browser and continues in the app window once you approve the sign-in there. If the sign-in redirect can't return to the app (for example, through an SSH tunnel), use the **Paste code instead** option on the sign-in screen. No API key is required. After sign-in, a setup wizard walks you through enabling connectors and skills, setting which websites Claude can access, and choosing whether memory is on. You can change these at any time in Settings. Claude Science keeps your data in a single folder in your home directory: `~/.claude-science` on macOS and Linux, and `%USERPROFILE%\.claude-science` on Windows. On Linux, the `claude-science` command itself installs to `~/.local/bin`, and on Windows the app installs to `%LOCALAPPDATA%\Programs\ClaudeScience` and adds that folder to your user PATH. Beyond that, it doesn't modify your existing conda installation, R libraries, or shell configuration. Deleting the data folder removes all projects, artifacts, and conversation history. Deleting the folder and the application removes Claude Science entirely; on Windows, quit the app from its notification-area icon, then uninstall it from **Settings** > **Apps** > **Installed apps**. ## Run your first analysis * Open the Example project, or create a new one. * Start a conversation. Reference a folder on your computer by typing its path or using the @ picker in the composer. * Review the folder-access card when it appears and choose whether to allow it. * Review the code-execution card when Claude proposes running code and choose whether to allow it. * Results appear as artifacts in the Files panel. ## Troubleshooting first launch * macOS says the application isn't supported, or the app icon appears crossed out: the download page picked the build for the wrong processor. Return to the download page and choose Mac (Intel) or Mac (Apple Silicon) to match your Mac. To check which you have, open the Apple menu, choose About This Mac, and look at the Chip or Processor line. * No browser tab appeared on macOS or Linux: on macOS, choose Open from the menu bar icon. On Linux, copy the printed URL into a browser on the same machine, or run `claude-science url` to print a fresh one. * A Claude Science message on Windows says the app was not installed because the file could not be confirmed: the copy you opened still runs but isn't installed. Download the installer again from [claude.com/product/claude-science](https://claude.com/product/claude-science) and open the new file. If the message persists, the PC could not verify the publisher's signature, so ask your IT team. * The Windows app reports that it couldn't set up the app window engine: the first launch downloads that engine from `downloads.claude.ai`, and this usually means the app couldn't reach it. Check the internet connection, and on a corporate network ask IT to allow that domain (see [Network requirements](/docs/claude-science/network-requirements)). * Linux refuses to start: a sandbox dependency is missing (install bubblewrap and socat as shown in the Install section), too old, or blocked. Check your bubblewrap version with `bwrap --version`, then match the error message to its fix in the [Linux troubleshooting table](/docs/claude-science/run-on-remote-linux-server#troubleshooting). * Projects from another computer don't appear: by design, Claude Science keeps your work on the computer where it's installed, so each computer starts with its own projects. Your earlier projects are still on the other computer. See [Use Claude Science on more than one computer](/docs/claude-science/multiple-computers). * Sign-in stops at claude.ai: your account is on the Free plan (upgrade required), the redirect couldn't return (use Paste a code), or your Team or Enterprise organization hasn't [enabled Claude Science](/docs/claude-science/enable-claude-science) yet. # Glossary Source: https://claude.com/docs/claude-science/glossary One-sentence definitions for the terms you meet in Claude Science, from artifact to workspace. One-sentence definitions for the terms you meet in Claude Science, from artifact to workspace. **[Artifact](/docs/claude-science/artifacts)**: any file Claude makes and saves for you, listed in its session's Files view. **Cell**: one block of code Claude runs in a kernel; the cell, its output, and the environment it ran in are recorded in the session's Notebook. **Cloud provider**: your own account at a cloud service where Claude can start jobs; you pay that provider directly. **[Comment](/docs/claude-science/comments)**: a note you pin to part of an artifact by selecting it; Claude reads pending comments as instructions on its next turn. **Connector**: an outside data source or tool wired into Claude over MCP; Claude Science includes a featured set, you can access partner connectors from the Connectors Directory, and you can add your own under Settings > Connectors. **Data directory**: the `~/.claude-science` folder on your computer holding the database, artifacts, session workspaces, and logs. **[Environment](/docs/claude-science/tools-and-environments)**: a named set of installed packages (conda) that a kernel runs in, reused across sessions. **Execution log**: the slice of a session's Notebook cells that produced a given artifact version, shown as a tab in its Provenance pane. **Kernel**: the live Python or R process that runs a session's cells and keeps variables in memory between them. **Memory**: notes Claude keeps about you and your projects across sessions, which you can review and edit. **Model endpoint**: a scientific domain-specific model server you register under Settings > Compute, that runs locally or connects to a vendor's hosted solution, that Claude sends single prediction requests to. **Network allowlist**: the list of every outside host that sandboxed code may reach, kept under Settings or, on Team and Enterprise plans, managed by your organization. **Permission card**: the card that replaces the message box when Claude needs your permission for running code, running a job, accessing a network host, a folder, a connector tool, or re-configuring Claude Science; you allow or deny it. **Provenance (the artifact record)**: the panel behind every artifact version showing the code, cells, conversation, environment, and findings that produced it. **[Reviewer](/docs/claude-science/the-reviewer)**: the independent agent that re-examines Claude's claims and artifacts at checkpoints, recording each issue it raises as a finding on the artifact's Review tab; on some plans it runs in the background automatically. **Sandbox**: the isolated environment all of Claude's code runs in; reaching outside it needs your approval. **Scope**: how long an approval lasts (Once, This conversation, This project, or Global), with every standing grant listed and revocable under Settings > Permissions. **Session**: one conversation thread inside a project, with its own kernel and workspace. **Skill**: an installable package of instructions and helper code that teaches Claude a method or tool. **Specialist**: a named set of skills, connectors, and instructions that a session answers as. **SSH host**: a remote machine (server, cluster node, or a job submission host) added by its SSH name, that Claude can run jobs on, or dispatch jobs from. **Version**: one immutable save of an artifact; saving again adds a new version on top instead of overwriting. **Workspace**: the per-session folder on disk where Claude's code reads and writes files before they are saved as artifacts. # How Claude Science works with your data Source: https://claude.com/docs/claude-science/how-claude-science-works-with-your-data What Anthropic receives from Claude Science, what stays on members' computers, and what Enterprise organizations can retrieve through the Compliance API. Claude Science is a local-first application. Conversation history and artifacts are stored on the member's computer, and Anthropic doesn't sync them to the member's Claude account or to other devices. Anthropic does receive the prompts and responses the app exchanges with Claude, and handles them under its standard retention and Trust & Safety policies. For Enterprise organizations with the Compliance API enabled, Anthropic also retains those exchanges as session transcripts that the organization can retrieve; [Compliance API coverage](#compliance-api-coverage) explains what they contain. The following sections cover each of these, plus remote compute, connectors, and customer-managed encryption keys. ## What Anthropic receives Each time the app calls Claude, the prompt and Claude's response travel to Anthropic's servers and are logged under Anthropic's standard retention policy for model traffic (see How long do you store my organization's data in the Privacy Center), the same policy that applies to other Claude products. If your organization uses [customer-managed encryption keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek), these model-call logs are encrypted under your key (see [Customer-managed encryption keys](#customer-managed-encryption-keys) below). Your organization's Custom Data Retention setting doesn't change how long these model-call logs are kept. It does apply to the session transcripts that Anthropic keeps for Enterprise organizations with the Compliance API enabled, described in [Compliance API coverage](#compliance-api-coverage). The app also sends product-usage telemetry (event counts and timings, not conversation content) and, when it runs into an error, a redacted error report (the error type and its location in Claude Science's own code, not conversation content or research data). Both are turned off by the same [device configuration](/docs/claude-science/manage-on-devices#telemetry) setting. ## Compliance API coverage If your organization is on an Enterprise plan and has the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, your compliance team can retrieve transcripts of members' Claude Science sessions through it. Coverage of Claude Science sessions is in beta. Anthropic captures a session only while the Compliance API is enabled for your organization and the member is signed in with their Claude Enterprise account. Transcripts aren't available for sessions that ran before capture began for your organization, although such sessions can still appear in the session list with their content marked unavailable. Anthropic records each session on its servers as the app's requests reach the Claude API, without installing anything extra on the member's computer or capturing anything beyond the requests the app already sends to Claude. Sessions in organizations with [HIPAA compliance enabled](/docs/claude-science/enable-claude-science#hipaa-organizations) aren't captured, and [Retrieve session transcripts](https://platform.claude.com/docs/en/manage-claude/compliance-sessions) lists the other cases the Compliance API doesn't return. A transcript is reconstructed from what the app exchanged with Claude during the session: the member's prompts, Claude's responses, tool calls (including code and file content Claude wrote through them), and the text portions of tool results, including text from files that Claude read, subject to the size limits the Compliance API applies. Claude's extended thinking and the app's system prompt aren't included (a placeholder marks where the system prompt was), tool definitions and connector (MCP server) configuration are omitted, and images, PDFs, and other non-text content appear as placeholders. Content that never reached the Claude API, such as a local file the session never sent, isn't in the transcript. Anthropic keeps these transcripts for six years from capture by default. If your organization has set a Custom Data Retention period (in claude.ai under Organization settings > Data and privacy), that period applies to the transcripts instead, and when more than one retention period is set, the shortest applies. If your organization uses [customer-managed encryption keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek), the transcripts are encrypted under your key. The session endpoints are read-only, so transcripts can't be deleted through the API before they expire; see [Retention and deletion](https://platform.claude.com/docs/en/manage-claude/compliance-sessions#retention-and-deletion) for the current terms. The Compliance API's [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) also records changes to your Claude Science organization settings, such as turning the product on or off. The [Compliance API reference](https://platform.claude.com/docs/en/api/compliance/activities/list) describes these events. ## Remote compute When a member chooses to connect the app to remote compute (an owned server or cloud account they control), the app sends code and data directly to that destination. That traffic doesn't pass through Anthropic, and Anthropic doesn't store it. For organizations that use customer-managed encryption keys, see [Customer-managed encryption keys](#customer-managed-encryption-keys). You can turn SSH hosts, Modal, and scientific model endpoints off for the organization under **Organization settings** > **Claude Science** (see [SSH hosts](/docs/claude-science/admin-controls#ssh-hosts), [Modal](/docs/claude-science/admin-controls#modal), and [Scientific model endpoints](/docs/claude-science/admin-controls#scientific-model-endpoints)). For setup details, see [Remote compute clusters](/docs/claude-science/remote-compute-clusters) and [Compute providers](/docs/claude-science/compute-providers) in the user documentation. ## Connectors Directory connectors you publish as an admin are reached through Anthropic's hosted connector service, so your directory connector permissions and tunnels apply. Connectors a member adds locally (either running on their own computer or pointing at a custom URL) talk to their app directly, without routing through Anthropic. You can turn custom connectors off for the organization (see [Custom connectors](/docs/claude-science/admin-controls#custom-connectors)). ## Customer-managed encryption keys Organizations that use [customer-managed encryption keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek) can turn on Claude Science. The content Anthropic stores from the app is encrypted under your key, including the model-call logs of members' conversations with Claude, skills members publish, and, for Enterprise organizations with the Compliance API enabled, session transcripts. The app's conversation history, files, artifacts, and memory are stored on the member's computer and aren't hosted by Anthropic; of these, only what the app sends to Claude reaches Anthropic, where your key covers it as this section describes. Work members send to their own SSH hosts, Modal account, or scientific model endpoints goes directly there, not through Anthropic, and isn't under your key or any Anthropic-managed key, so review those providers' data handling. You can turn these connections off under **Organization settings** > **Claude Science**. In organizations with CMEK enabled, the app hides its response rating buttons and feedback form, as claude.ai does. ## What this means for you as an admin Because conversations and artifacts live on members' computers, Custom Data Retention and Org Data Export don't reach that local data. For Enterprise organizations with the Compliance API enabled, Anthropic also keeps session transcripts captured from the app's model calls, which include file text the app sent to Claude, and a record of settings changes (see [Compliance API coverage](#compliance-api-coverage)). Device management is the control you have for local data: your device management software (such as your MDM or EDR) governs the app's local folder the same way it governs any other local application data. Identity controls (SSO, SCIM, roles) apply because sign-in goes through claude.ai. See [Admin controls](/docs/claude-science/admin-controls) for the organization settings that govern what members can connect the app to, and for what IP allowlisting and session duration cover. # Legal and compliance Source: https://claude.com/docs/claude-science/legal-and-compliance Legal agreements, compliance certifications, and security information for Claude Science. Legal agreements, compliance certifications, and security information for Claude Science. ## Legal agreements ### License Your use of Claude Science is subject to:\ [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) - for Team and Enterprise users\ [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms) - for Pro and Max users ## Usage policy ### Acceptable use Claude Science usage is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Science. ### Authentication and credential use Claude Science authenticates with Anthropic's servers using OAuth tokens. OAuth authentication is intended exclusively for purchasers of Claude Pro, Max, Team, and Enterprise subscription plans and is designed to support ordinary use of Claude Science and other native Anthropic applications. More information about how users can authenticate with OAuth tokens can be found in [Logging in to your Claude account](https://support.claude.com/en/articles/13189465-logging-in-to-your-claude-account).\ Anthropic reserves the right to take measures to enforce these restrictions and may do so without prior notice.\ For questions about permitted authentication methods for your use case, please [contact sales](https://www.anthropic.com/contact-sales?utm_source=claude_science\&utm_medium=docs\&utm_content=legal_compliance_contact_sales). ## Security and trust ### Trust and safety You can find more information in the [Anthropic Trust Center](https://trust.anthropic.com) and [Transparency Hub](https://www.anthropic.com/transparency). ### Security vulnerability reporting Anthropic manages its security program through HackerOne. [Use this form to report vulnerabilities](https://hackerone.com/4f1f16ba-10d3-4d09-9ecc-c721aad90f24/embedded_submissions/new).\ © Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service. # Literature access Source: https://claude.com/docs/claude-science/literature-access Claude retrieves open-access full text without credentials; add publisher keys or a library proxy to reach paywalled text you're entitled to. Claude retrieves open-access full text without credentials. To reach paywalled text you're entitled to, add publisher keys or your library's proxy in the Claude Science app: select the gear icon and choose **Settings**, then select **Credentials**, then choose **Literature access (journals, etc.)** in the **Services** list. No key bypasses a paywall. These panels live in the Claude Science app's own **Settings**, separate from your claude.ai account and organization settings. If you've added custom credentials, the **Services** list appears below your **Custom** credentials. Given a DOI or title, Claude tries in order: an open-access copy (Unpaywall, Semantic Scholar, PubMed Central), CrossRef full-text links, publisher routes you hold keys for, your library proxy, then the publisher page. Retrieved files (PDF, XML, or text) are saved into the session. ## Available credentials Each credential in the **Literature access (journals, etc.)** form is optional and independent. | Credential | Effect | | ---------------------------------------------- | ------------------------------------------------------------- | | **Elsevier API key** + institutional token | Enables the Elsevier route (subscription still required) | | **Springer Nature API key** | Enables the Springer Nature route | | **Semantic Scholar API key** | Speeds the Semantic Scholar step | | **NCBI API key** | Raises the PubMed rate limit from 3 to 10 requests per second | | **CORE API key** | Gives skills access to the CORE open-access aggregator | | Institutional **EZproxy URL** + session cookie | Retries publisher links through your library | OpenAlex has its own entry in the same **Services** list: add a free **OpenAlex API key** there (create one on the [OpenAlex API settings page](https://openalex.org/settings/api)). OpenAlex requires a key on every request, so OpenAlex-backed literature search needs one configured. NCBI, EBI, and OurResearch (Unpaywall) ask callers to provide a contact email. The first time this applies, a **Share a contact email with research data services?** card appears. Sharing an email enables the Unpaywall step. You can also set this in the app's **Settings**, on the **General** tab, under **Contact email**. Claude paces requests to each provider at one per second, backs off when asked, and identifies itself in every request. Paywalled HTML isn't scraped. # Manage Claude Science on devices Source: https://claude.com/docs/claude-science/manage-on-devices Claude Science is a desktop application that stores member content locally. Claude Science is a desktop application that stores member content locally. This page covers what IT and endpoint teams need to know: where the app writes data, how to deploy configuration with device management, what telemetry is sent, and what members see when Anthropic requires an update. ## Where the app stores data The app writes to two locations on each member's computer: Configuration: config.toml in the app's default data folder (`~/.claude-science/config.toml` on macOS and Linux, `%USERPROFILE%\.claude-science\config.toml` on Windows) holds all app settings. Every key is optional; the app starts with no file present. This is the file to deploy through device management.\ Data: the app's data directory holds conversations, generated artifacts, delegation configurations, and workspace files in a per-organization subfolder (orgs/``/), stored as a local database plus files. Authentication tokens and the shared package environment live under the default data folder (`~/.claude-science/`, or `%USERPROFILE%\.claude-science\` on Windows) regardless of the data directory, so endpoint backup or wipe policies that target the data directory don't affect sign-in state. On Windows, the program itself installs per user to `%LOCALAPPDATA%\Programs\ClaudeScience` and registers under the signed-in user's **Settings** > **Apps** > **Installed apps** rather than machine-wide. The app also writes launch logs and state to `%LOCALAPPDATA%\ClaudeScience` and keeps a sandbox state folder under `%LOCALAPPDATA%`, and it unpacks components it runs, such as the app window engine and the sandbox launcher, under the data folder, so allow-listing by path needs both the program folder and the data folder. Uninstalling removes the program and sandbox state; `claude-science uninstall --purge` also removes the data and state folders. Your endpoint tooling governs these folders the same way it governs any other local application data. Anthropic doesn't host a copy of these folders, so Custom Data Retention and Org Data Export don't reach them. [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data) covers what Anthropic does receive from the app, including the session transcripts available to Enterprise organizations with the Compliance API enabled. ## Deploy configuration with device management To set configuration keys organization-wide, deploy the per-member config.toml (at the path given under [Where the app stores data](#where-the-app-stores-data)) through your MDM or endpoint tool. Claude Science doesn't read its settings from a system-level managed-preferences file or registry policy keys, so there's no native MDM configuration channel on any operating system. Deploying the per-member config.toml is the supported approach. The sandbox network allowlist and the package mirror can instead be set once for every member under **Organization settings** > **Claude Science** (see [Organization settings](/docs/claude-science/admin-controls#organization-settings)). The keys most relevant to admins are: | Key | Effect | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | disable\_telemetry = true | Stops the app from sending product-usage telemetry and error reports to Anthropic. | | data\_dir = "``" | Moves conversations, artifacts, and workspaces to a managed location (for example, a volume your backup tooling covers). | | \[update] auto\_update = false | Prevents the app from updating itself; pair with your own distribution channel. | | \[sandbox.network] enabled = false | Blocks network access from the app's local code-execution sandbox. The similarly named \[sandbox] network\_isolated key does not control this. | The [configuration file reference](/docs/claude-science/configuration-file-reference) documents the network-related keys and their defaults, and [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks) covers the proxy, TLS-inspection, and mirror settings. ## Telemetry The app sends product-usage telemetry (event counts and timings, not conversation content) to Anthropic. There's no in-app setting for this; consent is covered by your organization's acceptance of Anthropic's commercial terms. When the app runs into an error, it also sends an error report to the error-reporting service Anthropic uses that identifies the error type and where it occurred in Claude Science's own code. The report includes the app version, its runtime version, the operating system version, and the app's most recent telemetry events. The app redacts each report on the member's computer before sending it: error messages are removed, and code locations outside Claude Science's own code are blanked. Reports contain no conversation content, research data, file contents, or file paths, and no usernames, account identifiers, or organization identifiers. To turn telemetry and error reports off on managed devices, use either of: Set disable\_telemetry = true in config.toml (deployable through MDM).\ Set the DO\_NOT\_TRACK environment variable (for example to 1) on the device. Both are device-level settings. There's no per-member or per-organization telemetry toggle in Organization settings. ## Endpoint detection and response Claude Science runs analysis code inside a local sandbox on the member's computer. On macOS, sandboxed analysis processes run as ordinary child processes and are visible to host-level EDR tools. On Windows, they run under the member's account inside a Windows AppContainer, the operating system's built-in app isolation, started by a sandbox launcher that ships inside the app, without WSL or Hyper-V. Windows asks once, optionally, for administrator approval so that Command Prompt scripts and git can run inside cells and PowerShell cells can change folders, while Python and R cells work without it. If security software holds the sandbox launcher or quarantines files in an analysis environment, Claude Science names the affected folder in its error message so you can add an exclusion. On Linux, sandboxed processes run inside a separate PID namespace with an isolated process view, so host-level EDR won't see them as ordinary children of the app. ## Required updates Anthropic may set a minimum supported version of the app. When a member's installed version falls below that floor, the app shows a full-page notice that the installed version is no longer supported and blocks further use until the member updates. Admins don't configure this floor; it's set by Anthropic. If your organization distributes the app through its own channel with auto-update disabled, plan to push updates promptly when Anthropic raises the floor. # Monitor Claude Science usage Source: https://claude.com/docs/claude-science/monitor-usage Claude Science usage counts against each member's standard weekly quota and uses the same seat as the rest of claude.ai. Claude Science usage counts against each member's standard weekly quota and uses the same seat as the rest of claude.ai. You can track adoption in Analytics and through the Admin API. ## Analytics Open Analytics from the user menu and select the Claude Science tab to see adoption and session metrics for this product. To see spend, or to compare active members across products, select Claude Science in the product filter on the Overview tab. The Monitor usage link in Organization settings > Claude Science opens Analytics. ## Admin API The Claude Enterprise Admin API (Enterprise plans only) returns Claude Science usage alongside your other products. Per-member metrics (GET /v1/organizations/analytics/users, science\_metrics object): | Field | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------- | | distinct\_session\_count | Number of distinct Claude Science sessions. Null on aggregated rows where a distinct count can't be computed. | | message\_count | Number of messages sent in Claude Science sessions. | | delegation\_count | Number of delegations (handoffs to a specialized agent) in Claude Science sessions. | | remote\_compute\_job\_count | Number of remote compute jobs launched from Claude Science sessions. | | skills\_used\_count | Total number of skill invocations in Claude Science sessions. | See the Admin API reference for authentication and the full schema. # Use Claude Science on more than one computer Source: https://claude.com/docs/claude-science/multiple-computers What to expect when you sign in on another computer. Claude Science runs on your own computer by design, and your projects, artifacts, and conversation history live there with it, under your control rather than in your Claude account. Each computer you install it on keeps its own projects, so a new or different computer starts fresh when you sign in, and your earlier work stays on the first computer. ## Your work stays on your computer Anthropic doesn't sync your projects, artifacts, or conversation history to your Claude account, so there's no cloud copy for you to browse or sync from another computer. Claude reads and writes your files in place, in the folders you grant, and your work sits alongside them on your computer, where your own backup tools can cover it like any other application data. Your prompts, Claude's responses, and the file content Claude reads to answer them still go to Anthropic as part of each conversation, and Anthropic retains them as [How Claude Science works with your data](/docs/claude-science/how-claude-science-works-with-your-data) describes. You can install Claude Science on more than one computer and sign in to each with the same Claude account. Your account carries your plan and usage limits to every computer. Skills from your organization, along with any you published from the app, also reappear when you sign in on another computer (to the same organization, if your account belongs to more than one). Memory, settings, and the connectors you added in the app stay with each computer. Because the only copy is on your computer, include the app's data folder in your regular backups. In the app, **Settings > Storage > Data location** shows where the folder is. To take a single result to another computer, choose **Download** from the artifact's menu. A file saved with **Export session** is for technical support and troubleshooting, and can't be loaded into Claude Science on another computer. To reach the same projects from several computers instead, you can install Claude Science once on a Linux server you control and connect to it through an SSH tunnel from the browser on each computer. See [Run on a remote Linux server](/docs/claude-science/run-on-remote-linux-server). # Network requirements Source: https://claude.com/docs/claude-science/network-requirements The domains Claude Science connects to, grouped for a proxy or firewall allowlist: the app's connections to Anthropic, the analysis sandbox's package and research domains, the domains a package mirror adds and removes, and the built-in list of domains it always blocks. Claude Science connects to a small, fixed set of domains for sign-in, the Claude API, and the app's own literature search, and to a larger set of package and research domains when Claude runs analysis code, which members adjust on their own computers or your organization manages for every member. This page lists them for the team that manages your proxy or firewall allowlist. Connections are outbound-only and almost entirely HTTPS on TCP 443 (an internal package mirror may use 8443). The app's own domains are fixed, apart from open-access full-text downloads (covered below); the analysis-sandbox domains are a built-in allowlist that members adjust during onboarding or under **Settings** > **Network**, or that the organization manages for every member (see [Analysis sandbox domains](#analysis-sandbox-domains)). The domains fall into three groups: the app's own connections every member needs, the analysis sandbox's package and research domains, and the domains the member's browser loads. For the proxy and TLS-inspection settings, see [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks). ## App connections Every Claude Science install makes these connections, which travel through the member's outbound proxy and TLS inspection, so they need the proxy and corporate-certificate settings from the corporate networks page. All are outbound HTTPS on TCP 443. | Domain | Required when | Purpose | | --------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `claude.ai` | Always | Browser-based sign-in, usage analytics, feature configuration, and the catalog of available connectors | | `platform.claude.com` | Always | Completing sign-in (the OAuth token exchange) | | `api.anthropic.com` | Always | The Claude API for every request Claude makes, plus account and usage information | | `o1158394.ingest.us.sentry.io` | When telemetry is on (the default) | Crash and error reporting (the error type and where it happened in Claude Science's own code, never error messages, conversation content, or research data); blocking it degrades diagnostics only | | `*.mcp.claude.com` | When members use the Anthropic-hosted connectors | PubMed, ClinicalTrials.gov, ChEMBL, and bioRxiv connectors | | `storage.googleapis.com` | When automatic updates are on | Update manifests and installers | | `downloads.claude.ai` | On Windows, at first launch and when an update changes it | The app window engine, the component that displays the app window | | `api.github.com`, `codeload.github.com` | When members import skills from a GitHub repository | Fetching the skill repository's contents | Custom connectors and remote compute that members add reach whatever hosts they are configured with, so allow those case by case. Installs with telemetry turned off (see [Telemetry](/docs/claude-science/manage-on-devices#telemetry)) send no error reports, and blocking `o1158394.ingest.us.sentry.io` affects only error reporting, not the rest of the app. ### Full-text and literature retrieval When Claude searches the scientific literature or retrieves full text, the app itself contacts these hosts over its own connections, which pass through your outbound proxy and TLS inspection like the app connections above, so the proxy must allow them even though several are also on the sandbox allowlist. Full-text downloads come from wherever the open-access copy of an article is hosted, so on a network that allows only listed hosts, expect retrieval of some full-text copies to fail; the domains below keep literature search and PubMed retrieval working. | Domain | Required when | Purpose | | ------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- | | `api.unpaywall.org` | When Claude retrieves full text | Locating open-access copies of articles | | `doi.org` | When Claude resolves a DOI | DOI resolution | | `eutils.ncbi.nlm.nih.gov`, `www.ncbi.nlm.nih.gov` | When Claude searches PubMed | PubMed/PMC article records and full-text files | | `api.semanticscholar.org`, `api.crossref.org` | When Claude searches the literature | Scholarly search and citation metadata | | `api.openalex.org` | When a member adds an OpenAlex API key | Validating the stored key | | `api.elsevier.com`, `api.springernature.com` | Only when the member has stored those publishers' API keys | Publisher full-text APIs | ## Analysis sandbox domains When Claude runs code, its network access passes through a local filtering proxy that allows only the domains on the sandbox's built-in allowlist, grouped by purpose below. By default, each member manages the list on their own computer. Members can turn off any group except package management, during onboarding or under **Settings** > **Network**, and add allowed domains of their own in Settings. An administrator can also use the per-device configuration file, whose `[sandbox.network]` keys add allowed or denied domains, or disable sandbox networking entirely. An organization can instead manage the list for every member from **Organization settings** > **Claude Science**, with one switch per domain and custom domains of its own. Members then see their **Network** settings read-only, and the domains a member or a configuration file added are set aside while the organization manages the list. See [Network allowlist](/docs/claude-science/admin-controls#network-allowlist) for what the organization's list covers and how changes reach members. ### Package management domains These domains supply Python, R, and system packages when Claude builds an analysis environment. Members can't turn them off. An organization that manages the allowlist can turn the CRAN and Bioconductor, npm, and GitHub domains off, and the PyPI and conda domains off once an organization package mirror replaces them. | Domain | Purpose | | ----------------------------------------------------------------------------------------- | ----------------------------------------------- | | `pypi.org`, `*.pypi.org`, `files.pythonhosted.org` | Python packages from PyPI | | `conda.anaconda.org`, `repo.anaconda.com`, `anaconda.org`, `*.anaconda.org`, `*.conda.io` | conda packages | | `cran.r-project.org`, `cloud.r-project.org`, `bioconductor.org`, `www.bioconductor.org` | R packages from CRAN and Bioconductor | | `registry.npmjs.org` | npm packages for connectors that need them | | `github.com`, `*.github.com`, `*.githubusercontent.com` | Tools and packages published as GitHub releases | Claude Science itself does not require GitHub; the package manager ships inside the app. The GitHub domains are used only when a package Claude installs is published as a GitHub release or a member imports a skill from a GitHub repository, and blocking them fails only those operations. When you configure a conda channel mirror, Claude Science removes only the conda hosts (`conda.anaconda.org`, `repo.anaconda.com`, `anaconda.org`, `*.anaconda.org`) from the allowlist, and a Python index mirror removes only `pypi.org`, `*.pypi.org`, and `files.pythonhosted.org`. The `*.conda.io`, CRAN and Bioconductor, npm, and GitHub rows stay. A removed host is reachable again if a member re-adds it under **Settings** > **Network** or an administrator lists it in `[sandbox.network] allowed_domains`, which takes precedence over the removal. Environment builds contact the mirror host directly from the workstation, not through the outbound proxy, so it must be reachable directly (over your VPN or internal network if the mirror is internal, HTTPS on TCP 443 or 8443). A proxy allowlist entry alone does not make the mirror reachable for builds, and build-time mirror traffic will not appear in your proxy logs. See [Point package installs at an internal mirror](/docs/claude-science/corporate-networks#point-package-installs-at-an-internal-mirror). An organization package mirror set under **Organization settings** > **Claude Science** removes the same hosts for every member and is admitted the same way. When the organization manages the allowlist, the removed hosts stay unreachable even if they are switched on in the organization's list, and a member's own mirror host is reachable only if the organization's list includes it. ### Research database domains These groups are on by default. Members can turn them off during onboarding or anytime under **Settings** > **Network**. When the organization manages the allowlist, the organization's per-domain switches apply instead. | Group | Domains | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NCBI and NIH | `*.ncbi.nlm.nih.gov`, `*.nih.gov`, `cactus.nci.nih.gov` | | Genomics and biology | `rest.ensembl.org`, `grch37.rest.ensembl.org`, `*.ensembl.org`, `reactome.org`, `*.reactome.org`, `rest.kegg.jp`, `*.kegg.jp`, `cellguide.cellxgene.cziscience.com`, `gnomad.broadinstitute.org`, `gtexportal.org`, `jaspar.elixir.no`, `www.encodeproject.org`, `mygene.info`, `rfam.org`, `www.cbioportal.org`, `sparql.rhea-db.org`, `bindingdb.org`, `www.bindingdb.org`, `r12.finngen.fi`, `pheweb.jp`, `api.genome.ucsc.edu`, `unibind.uio.no` | | Proteomics | `rest.uniprot.org`, `*.uniprot.org`, `string-db.org`, `*.string-db.org`, `*.ebi.ac.uk`, `search.foldseek.com`, `rcsb.org`, `*.rcsb.org`, `*.proteinatlas.org` | | Literature and citations | `api.semanticscholar.org`, `api.biorxiv.org`, `www.biorxiv.org`, `api.crossref.org`, `doi.org`, `api.openalex.org`, `arxiv.org`, `*.arxiv.org` | | Clinical and pharma | `api.fda.gov`, `clinicaltrials.gov`, `*.clinicaltrials.gov`, `api.clinpgx.org`, `api.platform.opentargets.org`, `cancer.sanger.ac.uk`, `actionability.clinicalgenome.org`, `search.clinicalgenome.org`, `erepo.genome.network`, `civicdb.org`, `api.grants.gov`, `www.antibodyregistry.org`, `cartblanche22.docking.org`, `files.docking.org` | ### Optional compute integrations These domains matter only when a member turns on the matching integration. | Domain | Required when | Purpose | | --------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `health.api.nvidia.com` | When members enable NVIDIA-hosted BioNeMo inference | NVIDIA's hosted inference endpoint; a member can enter a different endpoint host when connecting BioNeMo under **Settings** > **Compute** | | `nvcr.io` | When members run NVIDIA NIM containers locally | Pulling NVIDIA container images | | `api.modal.com`, `*.w.modal.host` | When members connect a Modal account for remote compute | Modal's API and its dynamic worker hosts, reached from the member's machine | ### Domains the sandbox always blocks The sandbox blocks a built-in list of common destinations for moving data out of an organization (anonymous file-upload and paste services, chat and webhook endpoints that accept posted data without an account, reverse-tunnel services, and path-style cloud object storage addresses), and neither members nor configuration can remove entries from it. The blocklist is enforced only inside the analysis sandbox, so it does not affect the app's own connections, such as the update check to `storage.googleapis.com` listed under App connections above. For the path-style object-storage entries (`s3.amazonaws.com`, `s3..amazonaws.com`, `storage.googleapis.com`, `commondatastorage.googleapis.com`, and `r2.cloudflarestorage.com`), a bucket named in the URL path is blocked, while a bucket named in the hostname (for example `.s3.us-west-2.amazonaws.com` or `.storage.googleapis.com`) can be added to the allowlist under **Settings** > **Network**. If your package mirror or a cloud workflow stores data in object storage, address the bucket by hostname. ## Domains the member's browser loads Sign-in pages and interactive previews load in the member's web browser, so they are governed by your web-filtering policy rather than the outbound proxy or the sandbox allowlist. If your policy blocks these domains, sign-in pages fail to load or interactive previews render blank or broken. | Domain | Purpose | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `claude.ai` | The sign-in authorization page | | `console.anthropic.com` | The sign-in fallback page, which shows a one-time code the member pastes into the app when the browser cannot return to the app's local callback address | | `cdn.jsdelivr.net`, `esm.sh`, `unpkg.com`, `cdnjs.cloudflare.com` | JavaScript display libraries for interactive previews | | `3dmol.org`, `3dmol.csb.pitt.edu` | Molecular structure viewer | | `*.claudemcpcontent.com` | Isolated frames that display Claude's HTML previews and interactive connector output. A standard desktop install serves these frames from the app's own local address, so this entry matters mainly where members open Claude Science from a non-local address | ## Related resources * [Use Claude Science on a corporate network](/docs/claude-science/corporate-networks): proxy, TLS-inspection, and package-mirror settings * [Configuration file reference](/docs/claude-science/configuration-file-reference): the network keys in the configuration file * [Manage Claude Science on devices](/docs/claude-science/manage-on-devices): deploying the configuration file with device management # Claude Science Source: https://claude.com/docs/claude-science/overview Anthropic's AI workbench for rigorous science. Claude Science is a desktop application that pairs Claude with an analysis environment on your computer. Available in beta on macOS, Windows, and Linux. You describe a research task or analysis in plain language; Claude writes and runs Python, R, or shell code in a sandbox, reads the folders you grant it, pulls data from scientific databases through connectors, and saves results as versioned artifacts with a full provenance record. A background reviewer can check Claude's claims against the work that was actually run. Your files stay on your computer, and code runs in a sandbox. You approve each new folder, network host, and remote job before Claude can use it. Claude can make mistakes. The reviewer reduces, but doesn't eliminate, errors. It checks claims against the execution record and doesn't re-run analyses. Verify results before relying on them in research, publication, or downstream decisions. Claude Science is a research tool and isn't intended for clinical or diagnostic use. ## Requirements * A Claude account on a Pro, Max, Team, or Enterprise plan. On Team and Enterprise plans, an Owner must [enable Claude Science for the organization](/docs/claude-science/enable-claude-science) first. * macOS 13 or later (Apple silicon or Intel), Windows 11 (x64), or Linux x64 on a glibc-based distribution. * About 5 GB of free disk space for the runtime and starter environments. * On Linux: socat, bubblewrap 0.8.0 or later, and unprivileged user namespaces permitted by the kernel. # Remote compute clusters Source: https://claude.com/docs/claude-science/remote-compute-clusters Connect a machine you can reach over SSH (a lab workstation or an HPC login node) so Claude can run jobs on it. Connect a machine you can reach over SSH (a lab workstation or an HPC login node) so Claude can run jobs on it. Use it to connect to a remote workstation with a GPU, or your existing HPC cluster. Claude Science uses your existing `~/.ssh/config`, authenticates with your key or `ssh-agent`, and installs nothing on the host itself. On Team and Enterprise plans, your organization can turn SSH hosts off. When it has, **Add SSH host** isn't available, hosts you added earlier stay listed but refuse new commands and file transfers, and a job that's already running can still be stopped and its results collected (see [SSH hosts](/docs/claude-science/admin-controls#ssh-hosts) in the admin controls). ## Adding a host Go to **Settings > Compute** > **SSH hosts** > **Add SSH host**.\ Choose or type an alias from your `~/.ssh/config`. The address, user, port, and any `ProxyJump` come from that file.\ Optionally add notes about the host (partition, account code, module loads, whether software can be installed). Claude reads these before the first job.\ Optionally override **User**, **Port**, or **Identity file** under **Advanced**.\ Click **Add**. Adding a host runs a read-only probe that records CPUs, memory, GPUs, CUDA driver, presence of conda/modules/Apptainer, scratch directories, and whether `sbatch` exists. On SLURM clusters it reads partitions. Results are saved as editable notes on the host's detail page; re-run with **Probe**. ## Running jobs Workstations run jobs as detached processes. SLURM clusters receive jobs via `sbatch`. Jobs survive connection loss. On the host's detail page, set **Scratch directory** (must be on a shared filesystem for SLURM) and **Concurrent job limit** (default 100). When Claude proposes a remote job, a **Run this job on ``?** card shows the command and script. Approve with **Once**, **This conversation**, **This project**, or **Global** scope. On approval, the job script and inputs are copied to a job directory under the scratch directory. Remote jobs run outside the sandbox, as your user on the host, with access to everything your account can read and write there. Default job timeout is 30 minutes; tell Claude before submitting longer work. When a job finishes, outputs are pulled back into the session. Files over the size threshold (about 100 MB by default) stay on the host, and Claude records their paths. ## Host details Claude reads host-specific instructions from the Details document on the host's detail page. It holds notes that describe the host's setup and how to run jobs on it: how environments are activated, where data and packages live, and the cluster's scheduling conventions. Claude updates these as it works with the host, and you can edit them at any time. # Run on a remote Linux server Source: https://claude.com/docs/claude-science/run-on-remote-linux-server Install Claude Science on a cloud VM or lab server and use it from your own browser through an SSH tunnel. Claude Science runs on a remote Linux server (a cloud VM or a lab machine) the same way it runs on a workstation: the application and your data stay on the server, and you use the web app from your computer's browser through an SSH tunnel. Setup takes about five minutes, plus a few minutes of environment setup on first launch. This page covers running all of Claude Science on a remote machine. To keep Claude Science on your own computer and have it run jobs on a machine you reach over SSH, see [Remote compute clusters](/docs/claude-science/remote-compute-clusters). The server needs x64 Linux on a glibc-based distribution (arm64 and musl-based distributions such as Alpine aren't supported), about 5 GB of free disk space, and the system packages below. Your Claude account needs a Pro, Max, Team, or Enterprise plan; see [Requirements](/docs/claude-science/overview#requirements). ## Install dependencies Claude runs code inside a sandbox, and the sandbox needs two system packages: bubblewrap and socat. On Ubuntu or Debian: ```bash theme={null} sudo apt-get update && sudo apt-get install -y curl bubblewrap socat ``` The sandbox requires bubblewrap 0.8.0 or later; check with `bwrap --version`. Ubuntu 24.04 ships a new enough version, and Ubuntu 22.04 doesn't. The sandbox isn't optional: Claude Science refuses to start rather than run code unsandboxed. ## Install Claude Science ```bash theme={null} curl -fsSL https://claude.ai/install-claude-science.sh | bash ``` The installer downloads the current release, verifies its checksum, and installs the `claude-science` command in `~/.local/bin`. If it prints a PATH line at the end, add that line to your shell profile. Then confirm the command works: ```bash theme={null} . ~/.profile claude-science --version ``` ## Forward the ports from your computer Set up the tunnel before you start Claude Science: the sign-in link it prints is only valid for about three minutes. By default, the web app listens only on the server's localhost, so it isn't exposed to the network. An SSH tunnel makes it reachable from your computer. Claude Science uses two ports: one for the web app (8000) and a separate one for previews of generated HTML, served from its own origin so a previewed page can't read your session. The preview port is always the web app port plus one, so 8001 by default. Forward both. In a terminal on your computer: ```bash theme={null} ssh -L 8000:localhost:8000 -L 8001:localhost:8001 you@server.example.com ``` Leave that terminal open; the tunnel lasts as long as the SSH connection. If you work on the server through VS Code's Remote-SSH extension, it forwards ports automatically as the app uses them; check its Ports panel to confirm both ports are forwarded. ## Start Claude Science On the server: ```bash theme={null} claude-science serve --no-browser ``` First launch prints the sign-in link, of the form `http://localhost:8000/?nonce=...`, right away, and continues setting up its starter Python and R environments; the setup can take a few minutes and about 5 GB of disk. If port 8000 or 8001 is taken on either machine, pass a different port to serve (for example `--port 8765`; previews then use the next port up, 8766) and change the `ssh -L` forwards to match. To run it in the background instead, use `claude-science serve --no-browser --detached`. `claude-science status` reports whether it's running, and `claude-science stop` stops it. ## Sign in Open the printed link in your computer's browser. The link is single-use and expires about three minutes after it's printed; run `claude-science url` on the server to print a fresh one at any time. Restarting with `claude-science stop` then `claude-science serve --no-browser` also prints a fresh link. Sign in with your Claude account. If the sign-in redirect can't find its way back through the tunnel, choose **Paste code instead** on the sign-in screen. Then complete the setup wizard as described in [Get started](/docs/claude-science/get-started). ## Keep it up to date `claude-science update` checks for and installs updates. See [Command line settings](/docs/claude-science/command-line-settings) for the full command reference, including `logs` and the `serve` flags. ## Troubleshooting | Symptom | What it means | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command not found: claude-science` | `~/.local/bin` isn't on your PATH yet. Run `. ~/.profile` or open a new terminal. | | An error mentioning `bwrap too old` | The server's bubblewrap is older than 0.8.0. Upgrade it, or use a distribution that ships a newer version, such as Ubuntu 24.04 or later. | | An error mentioning `cannot create unprivileged user namespaces` | The kernel or an AppArmor profile blocks the sandbox from creating user namespaces; some Ubuntu 24.04 images restrict this. The error message names the exact setting to change for your distribution. | | The sign-in link shows an expired-link page | Links are single-use and valid for about three minutes. Run `claude-science url` on the server and open the fresh link; restarting with `claude-science stop` then `claude-science serve --no-browser` also prints one. | | Sign-in stops at claude.ai | The redirect couldn't return through the tunnel (choose **Paste code instead**), your account is on the Free plan (an upgrade is required), or your Team or Enterprise organization hasn't [enabled Claude Science](/docs/claude-science/enable-claude-science) yet. | | Interactive HTML previews render as static snapshots after a short delay (charts don't respond) | The tunnel isn't forwarding the preview port. Add the second `-L` forward; the preview port is the web app port plus one (8001 by default). | | The browser can't reach `localhost:8000` | The tunnel isn't up; rerun the `ssh -L` command. If the tunnel is up, confirm Claude Science is running on the server with `claude-science status`. | | The installer reports no binary for your platform | Claude Science on Linux needs x64 with glibc. arm64 servers and musl-based distributions such as Alpine aren't supported. | # The reviewer Source: https://claude.com/docs/claude-science/the-reviewer A built-in verification step that independently re-reads Claude's recent responses, the approved plan, saved artifacts, and the execution record, then checks whether its claims match what ran. The reviewer is a built-in verification step that independently re-reads Claude's recent responses, the approved plan, saved artifacts, and the execution record, then checks whether Claude's claims match what actually ran. It runs automatically after responses and periodically during long work, and you can trigger it any time with **Request review**. Automatic review is on by default on Max, Team, and Enterprise plans; on the Pro plan it starts off, and you can turn it on per session. ## Examples of what the reviewer checks * A result reported as computed when nothing ran. * A value in the response that contradicts the file it came from. * A citation that doesn't support the claim attributed to it. * A reference whose DOI resolves to a different article. * An approved plan step that wasn't completed. * A conclusion not supported by the method used. This isn't a complete list. The reviewer checks whether claims match the record; it doesn't re-run analyses. It can flag a conclusion that doesn't follow from the method that was run, but it doesn't judge whether that method was the right choice for your research question. Go to Settings > Specialists to customize the Reviewer or create your own specialist to perform additional reviews and judgments customized to the way you work. ## How Claude responds to findings If the reviewer finds something, each finding appears as a card directly under the message it refers to, showing what the reviewer found and the finding's status. A message with more than three findings shows the first three and a **Show all** control. Click a card to open the reviewer's full reasoning. Claude reads the findings and addresses them in its next message, either by correcting the work or by explaining why the finding doesn't apply. ## Adding your own review criteria In **Settings** > **Specialists**, open **Reviewer** and add checks in the **Instructions** field. Your criteria are added to every review; they can't remove or weaken built-in checks. ## Controls Auto-review is a per-session toggle in the session settings menu. It starts on for Max, Team, and Enterprise plans and off for the Pro plan. Reviews run against your plan's usage. # Tools and environments Source: https://claude.com/docs/claude-science/tools-and-environments Claude writes and runs Python, R, and shell commands. Claude writes and runs Python, R, and shell commands (PowerShell on Windows). Python and R run in a persistent kernel that keeps variables in memory across steps in a session. The kernel ends after about 30 minutes idle, when a package install restarts its environment, or when the session ends. ## Starter environments First launch creates two read-only conda environments in \~/.claude-science: * Python: numpy, pandas, scipy, matplotlib, seaborn, pillow * R: tidyverse, ggplot2, jsonlite ## Task environments When work needs packages the starters don't have, Claude reuses an existing named environment or proposes creating a new one (for example, single-cell or structural-biology). A permission card shows the environment name and initial packages. Environments are shared across all projects on the machine. To list or delete environments, ask Claude; there's no settings page for them. ## Installing packages Claude installs from these sources by default: * Conda: micromamba from the conda-forge, bioconda, defaults, and pytorch channels * Python: pip from PyPI * R: CRAN and Bioconductor A package installed into an environment is permanent and available in every session and project using that environment. A package installed inline in a code cell (`pip install` or `install.packages()`) lasts only until the kernel restarts. To keep a package, ask Claude to install it into the environment. For tools without a package, Claude downloads source, builds it in the sandbox with compilers from conda-forge, and saves the build as an artifact for reuse. The sandbox has no root access or system package manager. `apt` and `sudo` aren't available; Claude uses conda-forge or builds from source instead. Package sources can't be redirected to a different server. ## GPUs If your Linux machine has GPUs, the sandbox makes them available to code Claude runs, including on multi-GPU machines. You first need to turn GPU access on in the Settings > Compute pane. Allowing GPU access reduces the default sandboxing configuration applied by Claude Science. If your machine has no GPU, Claude notes this when a task needs one and can run the work on the remote compute you've connected. See Remote compute clusters and External compute providers. # Give Claude access to your tools Source: https://claude.com/docs/claude-tag/admins/add-connections An Access bundle bundles the credentials Claude Tag acts with. See how to create the dedicated service accounts, what to connect first, and how allowed websites limit reach. Claude starts delivering work before you connect anything. On Slack content alone, it can [catch a team up on a channel or thread](/docs/claude-tag/users/use-cases/catch-up), [triage a request channel](/docs/claude-tag/users/use-cases/triage-requests), [turn a discussion into a doc](/docs/claude-tag/users/use-cases/create-artifacts), and [track a project from channel history](/docs/claude-tag/users/use-cases/track-projects). Connections multiply what it can do from there; each one adds a system Claude can act in beyond Slack. ## Your first Access bundle An [Access bundle](/docs/claude-tag/concepts/glossary#access-bundle) is a named set of credentials, domain entries, repository grants, plugins, and instructions that Claude uses in the channels the bundle covers. A connection is one service credential inside a bundle, like a Datadog API key or a warehouse service account, that Claude uses to act in that service from any channel under the bundle's [scope](/docs/claude-tag/concepts/glossary#scope). If you're in [setup](/docs/claude-tag/admins/setup-overview), you add these connections there; skip to [Decide what to connect](#decide-what-to-connect). The steps below are for creating a bundle outside setup, on the admin page directly. Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Under **Claude Tag's access**, the **Slack** tab lists your scopes: **Default Slack** (organization-wide), then each workspace and any channels under them. Selecting **Default Slack** opens the **Default Slack access** panel. On the scope where you want the bundle to apply, click **+** next to **Access bundles** and choose **Create new bundle**. This creates the bundle and attaches it to that scope in one step; the bundle dialog opens. A bundle created on a workspace or channel scope is named after that scope, like **Acme bundle** for a workspace named Acme or **#engineering bundle** for that channel. A bundle created on **Default Slack** is named **Untitled access bundle** until you rename it. To rename a bundle, click the pencil next to the name (the console uses "profile" and "Access bundle" interchangeably). You can also create an unattached bundle by clicking **Create** on the **Access bundles** page in the left navigation, then attach it to scopes afterward. A bundle created there is named **Untitled access bundle** until you rename it. Connections belong to the [agent identity](/docs/claude-tag/concepts/agent-identity), not to any person. Personal claude.ai connectors apply in DMs. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use a member's own connectors in a channel for that member's own tasks, after the member allows it. Name a bundle after what it grants, since the name is what you'll read when deciding which bundles to bind to a channel: `data-readonly`, `github-write`, `monitoring`, `gtm-tools`. A capability name stays meaningful when the same bundle serves several teams; a team name (`devprod-team`) works when one team's full access is the unit you'll reuse. ### Why create more than one bundle Multiple bundles let you grant access by capability and compose it per channel. For example, with separate `data-readonly`, `github-write`, and `monitoring` bundles: `#platform-eng` gets all three, `#gtm-analytics` gets only `data-readonly`, and `#incidents` gets `monitoring` plus `github-write`. Each credential is defined once, so rotating a Datadog key means editing one bundle without touching the others. A bundle also has Domains, Plugins, and Instructions tabs alongside Credentials and Repositories. Use the bundle's Instructions for guidance that should travel with a credential; use [per-scope custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions) for guidance tied to a place. ## Decide what to connect Six categories cover most of the work teams hand to Claude. Any service with an HTTP API can be added; start with the categories that match what your teams already do. Read-only connections are most useful in combination: an answer that joins the ticket, the deploy, and the error rate needs all three systems connected. Connecting many systems read-only is a different decision from granting write access anywhere. | Connect | Examples | Recommended access | What it adds | | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Knowledge and docs | Google Drive, [Notion](/docs/claude-tag/admins/connections/notion), [Confluence](/docs/claude-tag/admins/connections/atlassian) | Read | Answers grounded in design docs, runbooks, and prior decisions | | Code | GitHub, [GitLab](/docs/claude-tag/admins/connections/gitlab) | Read and write | On GitHub, branches, pull requests, review, and CI follow-up through the [Claude GitHub App](/docs/claude-tag/admins/configure-github). On GitLab, issues, merge request comments, and pipeline checks through its API | | Data warehouse | BigQuery, [Snowflake](/docs/claude-tag/admins/connections/snowflake), Redshift | Read | Data questions answered with charts in the thread; recurring reports | | Monitoring | [Sentry](/docs/claude-tag/admins/connections/sentry), [Datadog](/docs/claude-tag/admins/connections/datadog), [PagerDuty](/docs/claude-tag/admins/connections/pagerduty) | Read | Logs, metrics, and errors for debugging and incident work | | Issue tracking | [Linear](/docs/claude-tag/admins/connections/linear), [Asana](/docs/claude-tag/admins/connections/asana), [Jira](/docs/claude-tag/admins/connections/atlassian) | Read and write | File tickets and post status updates where work lives | | Go-to-market | [HubSpot](/docs/claude-tag/admins/connections/hubspot), [Gong](/docs/claude-tag/admins/connections/gong), [Salesforce](/docs/claude-tag/admins/connections/salesforce) | Read | Pipeline and customer state for account questions | Per-service instructions, with the credential fields and allowed-websites values, are in the [connection guides](/docs/claude-tag/admins/connections/overview). ### Create a dedicated account per service The credential you connect is Claude's account in that tool, not yours. Anyone in a channel under the bundle's scope can use it through Claude, so connect a dedicated identity you control rather than your personal login. For each tool, create that identity specifically for the agent rather than reusing a shared bot key. The pattern depends on the service. | Service type | Recommended pattern | | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Google Workspace (Drive, Calendar, Docs) | Create a virtual user like `claude@yourcompany.example.com` and share the folders and calendars it needs. If using a GCP service-account key with domain-wide delegation, restrict the delegation to that single subject and the minimum OAuth scopes; DWD can otherwise impersonate any user in your domain. | | SaaS with native service accounts (Datadog, Snowflake, Sentry) | Create a service account in that tool's admin, scope it to the project or read-only role, and use its API key | | SaaS without service accounts (Linear, Asana) | Create a dedicated user seat for the agent and use a personal access token from that seat | | Cloud APIs (AWS, GCP) | Create a dedicated IAM principal with the narrowest policy that covers the work | A dedicated account keeps the agent's activity separately auditable in each tool's logs and lets you revoke its access without touching anyone else's. Grant read-only wherever the categories below say read; Claude can never exceed what the key allows. If the person who administers a service isn't you, send them this: ```text wrap theme={null} Please create a service account in [service] for our Claude agent, scoped to [read-only / the specific project], and send me the credential through [your secrets channel]. It will be used by an org-managed agent, with the credential injected at a network proxy; the agent itself never holds the key. Details: https://claude.com/docs/claude-tag/admins/add-connections ``` ### Limit access to specific resources A connection has no setting for which pages, folders, or projects Claude can reach inside a tool. The connection's reach is whatever the connected account can access in that tool. To narrow Claude to a subset, narrow the account: * **Confluence or another wiki:** give the service account read access to only the spaces or pages Claude should see * **Google Drive:** share only the relevant folders with the dedicated Google account; see [Google Workspace](/docs/claude-tag/admins/connections/google) * **Project or ticket trackers:** add the service account to only the projects it needs The host, path, and method restrictions on a connection control which API endpoints Claude can call, not which records those endpoints return. Use them alongside account-level scoping, not instead of it. For a shared or external channel, put the narrowed connection in its own bundle and [attach that bundle only to that channel](/docs/claude-tag/admins/attach-to-scope#attach-to-a-channel), so the credential is unavailable elsewhere. ## Connect a service that isn't in the list The services with **Connect** buttons on the Credentials tab are presets, not the full set Claude can connect to. Any app with an API can be connected: click **Connect** next to **Custom tool** at the bottom of the tab. See the [Custom connection guide](/docs/claude-tag/admins/connections/custom) for the form fields, credential types, and how to add a custom MCP server. You can also add connections from a channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). The option to add one appears there only for people who can manage Claude's setup for that channel or for the whole organization. [Channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) can manage setup for their assigned channels. Other channel members see the channel's connections on the Configure page but can't add one. ## Allow a host without a credential Claude does channel work in an isolated [sandbox](/docs/claude-tag/concepts/agent-identity#channel-sessions). A network request is traffic that sandbox sends to a host, such as an API call, a `curl` fetch, or a package install. Before Claude can make one from a channel, the destination host has to be allowed by one of three settings, the allow layers: * **A domain entry**: a hostname listed on this bundle's **Domains** tab. Requests to it pass with no credential attached; see [Add a domain](#add-a-domain). * **A [connection](#add-a-connection)**: a credential on this bundle's **Credentials** tab. Requests matching its [allowed websites](#set-allowed-websites) pass with that credential attached. * **The scope's [environment](/docs/claude-tag/concepts/glossary#environment)**: the compute configuration the scope's sessions run in, which carries its own network access setting, starting at the Trusted access level that covers common package registries. Requests to hosts it allows pass with no credential; see [Broad web access through the environment](#broad-web-access-through-the-environment). A host that none of these allows stays unreachable, and when more than one bundle is attached to a scope, the entries of all of them apply. Web search is governed by none of them, because searching happens on Anthropic's servers rather than in the sandbox; see [Web search vs. network requests](#web-search-vs-network-requests). ### Add a domain A domain entry allowlists one hostname for every channel this bundle covers. After you add it, requests from those channels' sandboxes to that host go through with no credential attached. To get there, open the bundle from the scope that covers the channel, under **Claude Tag's access** at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag); if the scope has no bundle yet, [create one](#your-first-access-bundle) first. On the bundle's **Domains** tab, fill in the form and click **Add domain**: * **Domain**: the hostname to allow; a wildcard is allowed as the leftmost label, like `*.example.com`, and covers subdomains at any depth but not `example.com` itself * **Ports**: needed only when the service listens on something other than 443 For example, to let Claude check a vendor's status page at `status.example.org`, enter `status.example.org` in the **Domain** field and leave the **Ports** field empty. You don't have to predict the full list up front. When a request is blocked, Claude says so in the thread and names the host, with wording like "blocked by the network egress proxy" (that is, by Agent Proxy); add that host here and retry. If the host is listed and Claude still reports it blocked, check these in order: * **The bundle is attached to the channel's scope.** Claude can use a Domains entry only in channels whose scope, or an ancestor scope, has this bundle attached; see [Attach bundles to scopes](/docs/claude-tag/admins/attach-to-scope). * **The entry matches the exact host.** A wildcard like `*.example.com` doesn't cover `example.com` itself, and `www.example.com` and `example.com` are different hosts. * **The request didn't move to another host.** If the page redirects, or loads from a CDN or a sign-in host, allow that host too; Claude names the host it was blocked on. * **The port is listed.** Needed only when the service listens on something other than 443. * **A minute has passed since you saved the entry.** Agent Proxy picks up a new entry within about a minute, in existing threads as well as new ones, so retry in the same thread after a short wait. * **The bundle was attached before the thread started.** A bundle you attach after a thread started isn't guaranteed to reach that thread, so start a fresh thread to use its entries. * **The request came from a channel, not a DM.** A bundle attached to a channel doesn't apply in DMs. Typical entries are hosts the work calls without a key, such as a docs site or a public API. Common package registries are usually already reachable through the [environment's Trusted access default](#broad-web-access-through-the-environment), and a host that needs a credential belongs in a [connection](#add-a-connection) instead. Entries appear below the form, and each one can be edited or removed from its row. [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) carries only HTTP and HTTPS. A protocol that isn't HTTP, such as SSH, can't cross the proxy, so listing a host here doesn't make it reachable over SSH. ### Broad web access through the environment Domain entries allow hosts one at a time. For a scope whose work needs more of the web, the environment setting grants broader access. An [environment](/docs/claude-tag/concepts/glossary#environment) is the sandboxed compute configuration the scope's sessions run in, and it carries its own network access setting. A new environment's network access level is Trusted access, which allows a [documented set of package registries and developer hosts](https://code.claude.com/docs/en/cloud-environments#default-allowed-domains). A channel can already reach hosts like `pypi.org` and `registry.npmjs.org` with no domain entry. To give a scope broader access, create an organization-shared environment with a more permissive level and set it on the scope, as described in [Configure the environment for a scope](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope). **Full access** allows any domain; see [Network access in the Claude Code docs](https://code.claude.com/docs/en/cloud-environments#network-access) for the other levels. ### Allow all hosts Allow-all egress is off by default; ask your Anthropic account team to enable it for your organization. Once enabled, you can enter `*` alone as the domain. A `*` entry needs ports assigned; it admits any host on those ports, with no credential attached. With `*` active: * Requests to hosts that no connection covers go through with no credential attached. * A `*` entry never carries a credential, and a connection's credential still travels only to its [allowed websites](#set-allowed-websites). * Private and internal network addresses and cloud metadata endpoints remain blocked. Without allow-all egress enabled, saving `*` fails with a generic "Couldn't add domain." error that doesn't name the cause. If the capability is later disabled, you can disable an existing `*` entry or narrow it to specific hosts, but you can't keep it active. ### Web search vs. network requests Web search needs no domain entry, connection, or environment setting. It's [Anthropic's built-in web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool), and the searching happens on Anthropic's servers rather than in the channel's sandbox, so no allow layer applies. Opening a page is not part of the search. A search returns content from the pages it matches, which Claude reads and cites; fetching a URL from the sandbox is a network request like any other, and the host needs an allow layer. Claude can answer from a page that search surfaced yet report that it can't open the same link. If the work needs Claude to open and read pages rather than answer from search results, allow those hosts through the settings above. [Web search vs. network requests](/docs/claude-tag/concepts/agent-identity#web-search-vs-network-requests) covers the session mechanics behind the split. ## Add a connection On the bundle's **Credentials** tab, click **Connect** next to a listed service, or next to **Custom tool** for a service not in the list. For a custom connection, choose the credential type: | Credential type | Use for | | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bearer | API keys and OAuth bearer tokens. Most SaaS REST APIs. | | Basic | HTTP Basic authentication. | | Body parameter | A token the API expects in the request body or query string instead of a header. | | AWS SigV4 | Signed requests to AWS service endpoints with an access key pair. | | GCP access token (with Service Account Key) | Google Cloud APIs via a service-account JSON key. Google Workspace services like Drive and Calendar also use this; see [the Google guide](/docs/claude-tag/admins/connections/google). | | GCP IAP (with Service Account Key) | Google Cloud services behind Identity-Aware Proxy. | | OAuth 2.0 JWT bearer | Server-to-server OAuth. | | OAuth 2.0 client credentials | Server-to-server OAuth. Salesforce uses this. | | MCP Connector | Sign in once as an admin; the agent acts as that account. | For GitHub repositories, use the GitHub connection at [Configure GitHub access](/docs/claude-tag/admins/configure-github) rather than a credential from this table. Credentials are injected at the network boundary by Agent Proxy; the model and the sandbox are not given the key. A request to a host you haven't allowed is blocked, not sent. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ### Send a setup link to another admin When someone else holds a service's secret, create a setup link instead of collecting the secret yourself. On the service's row in the **Credentials** tab, open the **Connect** button's menu and select **Copy link for another admin**. Whoever opens the link signs in to your Claude organization and submits the credential there. They don't need an admin role. The row tracks the link. It shows **Pending** until the credential is submitted, then **Approval needed**. Select **Review** to check the submission and approve or reject it. The credential becomes active only after you approve it. The row shows **Expired** for a link that went unused, and until the credential is submitted you can revoke the link from the row's **⋮** menu. Setup links are available for services that use the Bearer or Basic credential type. For other types, the **Connect** menu has no link option. ### Set allowed websites List the hosts a connection's credential may be sent to. A wildcard works only as the leftmost label, like `*.example.com`; it covers subdomains at any depth but not `example.com` itself. You can't enter `*` alone here; a credential is always limited to specific hosts. To let Claude reach any host without a credential, see [Allow all hosts](#allow-all-hosts). To change a connection's name or allowed websites after saving, open the **⋮** menu on that connection's row in the bundle's **Credentials** tab and choose **Edit**; the **Edit connection** dialog labels the field **Allowed hosts**. The same menu has **Rotate secret** (where the credential type supports it) and **Delete**. Check the host against your account's region before saving. Some presets fill a default host that may not match your account's region; a Datadog key, for example, only works against your account's Datadog site, like `api.datadoghq.com` or `api.datadoghq.eu`. ### Restrict by path or method After saving, you can narrow a connection. Select **Edit** on the connection's row in the bundle's **Credentials** tab. The **Edit connection** dialog lets you rename the connection and, where the connection has an allow rule, restrict it by HTTP method and path, for example to allow `GET` but not `DELETE`. Agent Proxy starts applying an edit to a connection or a Domains entry within about a minute after you save it, in existing threads as well as new ones. It evaluates connections and Domains entries from the most specific scope outward (channel, then workspace, then organization), and within a scope by priority; the first match decides. A request that matches no connection, no Domains entry, and nothing in the environment's network access is blocked. Private IP ranges and cloud metadata endpoints stay blocked regardless. ### Connections vs claude.ai connectors The connection gallery lists credential types the agent can hold, not the connectors your organization or its members have set up on claude.ai. A connection authenticates the agent, not a person; a connector on someone's personal claude.ai account doesn't appear here. For Google services, use a service-account key or the MCP Connector sign-in option, both of which give the agent one credential with access to the data the channel needs. Personal connectors keep working in [DMs](/docs/claude-tag/concepts/agent-identity#direct-message-channels). ## Attach plugins A connection grants access; a plugin teaches Claude how to use it well. A plugin is a packaged set of skills: reusable instructions for working with a specific tool or following a specific process. Attach a plugin to the same Access bundle or scope that carries the connection, so the credential arrives with directions for using it. A Datadog API key, for example, makes the API reachable, and a Datadog plugin tells Claude which endpoints answer which questions. Once you turn a plugin on for a bundle or add it to a scope, sessions in the channels that bundle or scope covers pick up the plugin automatically. Nobody in those channels has to turn that plugin on. A channel member can also add a plugin available to your organization, by asking Claude in the channel or from the channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel), unless an admin has [restricted editing to admins](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions). Anthropic provides plugins for common tools and processes, and you can add your own from a [skills repository](/docs/claude-tag/admins/skills-repo). To give Claude organization-wide skills, package them as a plugin. Admins and channel members turn plugins on in different places: * A plugin added directly on a scope (the plugin chips on the scope's panel) is enabled there as soon as you add it. * A bundle's **Plugins** tab lists the plugins available to your organization, each off until you toggle it on. * A channel member can ask Claude to add a plugin to their channel, unless an admin has [restricted editing to admins](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions). Claude proposes the change and adds the plugin only after someone in that channel selects **Confirm**. Adding a plugin for your whole organization makes it available, not active. The plugin takes effect only where a bundle enables it or a scope adds it directly. Adding or removing plugins and skills applies to new threads only. A thread already running keeps the set it began with; start a fresh thread to pick up changes. See [What survives between replies](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies). Claude can't publish a new skill version from inside a thread; that update happens in admin settings. ### Code review with the Security Guidance plugin Anthropic's **Security Guidance** [plugin](https://code.claude.com/docs/en/plugins) has Claude review the code it writes. With the plugin on in a channel, Claude is warned about risky patterns as it edits files, and the plugin reviews the code changes in the session's repository when Claude commits, pushes, or finishes a reply, checking for vulnerabilities such as injection, cross-site scripting, and hardcoded secrets. Claude addresses the findings or reports them in the thread. **Security Guidance** is off by default. Add it directly on a scope, or turn it on in a bundle's **Plugins** tab, and new threads in covered channels pick it up. The plugin flags problems and suggests fixes; it doesn't block a commit or a push. To require review before code merges, use your repository's branch protection and required checks. ## Verify the connection saved * Each connection is listed in the bundle with the host you set. * The [Access bundles page](https://claude.ai/admin-settings/claude-tag/access-bundles) shows a status for each connection when you expand the bundle. * **Active**: Claude can send the credential to its allowed hosts * **Not active**: the secret is stored but no allow rule uses it yet, so Claude can't send it. * **Approval needed**: another admin submitted the credential through a shared setup link. Select **Review** on its row, then **Approve**. * **Used** with a time, or **Never used**: when Claude last sent the credential; independent of the status * New threads pick up new connections on their own. An existing thread isn't told about a connection added after it started, but the connection works there; ask Claude to use the service by name. ## Related resources * [Set a spend limit](/docs/claude-tag/admins/set-spend-limit): fund usage so the connections you just added can run * [Configure GitHub access](/docs/claude-tag/admins/configure-github): repository access, managed through the Claude GitHub App * [How agent identity works](/docs/claude-tag/concepts/agent-identity#agent-proxy): how the credentials you just added reach Claude without entering its sandbox # Configure per-channel access Source: https://claude.com/docs/claude-tag/admins/attach-to-scope Choose which Slack channels and workspaces a set of Claude Tag credentials applies to. Covers inheritance, overlap rules, and adding channels after setup. This page covers adding access to more workspaces and channels, and how access stacks when several bundles apply to the same place. It assumes you have already [paired a workspace](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace) and [created an Access bundle](/docs/claude-tag/admins/add-connections). You must be an Owner in your Claude organization to attach bundles. A scope is where a bundle applies: **Default Slack access** (the organization-wide root), a workspace, or a single channel. Bundles inherit downward through those scopes, and when credentials overlap, the narrowest scope wins. ## How scopes inherit Bundles stack downward. A channel gets whatever is attached at Default Slack access, plus its workspace, plus anything attached to the channel itself. Nested boxes. The outermost box is the Default Slack access scope: a bundle attached here is the baseline every channel gets. Inside it, two examples. Outside the workspace box, a channel called another-team in a different workspace gets only the default bundle. Inside the workspace box, which adds an optional bundle for channels inside it, two channel boxes: a public channel called general, with no channel bundle, gets the default plus the workspace bundle; a private channel, marked with a lock, with its own channel bundle, gets all three, the default, workspace, and channel bundles. Nested boxes. The outermost box is the Default Slack access scope: a bundle attached here is the baseline every channel gets. Inside it, two examples. Outside the workspace box, a channel called another-team in a different workspace gets only the default bundle. Inside the workspace box, which adds an optional bundle for channels inside it, two channel boxes: a public channel called general, with no channel bundle, gets the default plus the workspace bundle; a private channel, marked with a lock, with its own channel bundle, gets all three, the default, workspace, and channel bundles. | Scope | What it covers | Access | | :------------------- | :---------------------------------------- | :---------------------------------------------------------------------- | | Default Slack access | Every Slack workspace and channel | The baseline set every channel gets | | Workspace | All channels in one Slack workspace | Inherits Default Slack access, plus workspace-level bundles | | Channel | A single Slack channel, public or private | Inherits Default Slack access and workspace, plus channel-level bundles | The same stacking applies in reverse. Detaching a bundle from a channel removes only that channel's additions, and bundles attached at the workspace or Default Slack access still apply there. Memory is also scoped, but differently: there is no organization-wide memory, public-channel entries are shared across the workspace, and a private channel reads workspace memory but writes only to its own store. See [What Claude Tag remembers](/docs/claude-tag/users/memory). DMs run under the user's own claude.ai account, so bundles attached here apply only in channels. See [how DMs work in this model](/docs/claude-tag/concepts/agent-identity#direct-message-channels). ## Attach the bundle Attaching binds the bundle to a workspace scope or to a single channel under it. The binding takes full effect in new threads only. A thread already running keeps the skills, plugins, and custom instructions it started with. A connection added after a thread started still works there if you ask Claude to use the service by name, but Claude doesn't announce it, so test with a new top-level thread after attaching a bundle. See [What survives between replies](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies). At the channel's top level, outside any thread, Claude works from a single long-lived channel session. After a configuration change, Claude replaces that session on the next channel message, so top-level replies pick up the change from then on. ### Attach to a workspace Each paired workspace already has a scope; bind a bundle in the scope's **Access bundles** section. On the **Access bundles** page in the left navigation, each bundle's card shows how many places it's used in. To see which scopes those are, open the bundle's **Manage** dialog and hover over the usage count in its footer. To add another workspace, [pair it](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace) first. ### Attach to a channel Channels Claude was added to appear on the **Slack** tab automatically, each as a scope under its workspace. To give one of these channels access beyond the workspace baseline, select its row and bind bundles in the scope's **Access bundles** section. A channel row shows the name an admin gave the scope, the channel's name in Slack, or the raw channel ID. To find a channel, use the **Search channels** field. It matches channel names and channel IDs (pasting a channel link copied from Slack also works), and searching a workspace's name shows that workspace's channels. To bind one bundle to several channels in one pass, open the bundle from a scope's **Access bundles** section on the **Slack** tab and select **Add to channels**. The dialog lists channel scopes grouped by workspace, with a search field and a checkbox per channel. Check the channels you want and select **Add**. The bundle binds to each checked channel, and channels it's already bound to directly are marked **Already added**. A channel that doesn't appear in the list yet needs a scope created for it: 1. On [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), find the workspace on the **Slack** tab under **Claude Tag's access** and select **Add channel**. 2. Pick the channel in the **Channel** field. Type a name to search public channels, or paste a channel ID or channel link copied from Slack. Private channels don't appear in the search results, so for a private channel, paste its ID from the channel's details in Slack. Channel IDs start with `C`, or with `G` for some older private channels. 3. Save, then bind bundles in the new scope's **Access bundles** section, the same as for a workspace. In a channel shared across more than one workspace in your Enterprise Grid, bundles bound to the channel or its workspace don't apply. See [Channels shared across workspaces in your Enterprise Grid](/docs/claude-tag/admins/restrict-access#channels-shared-across-workspaces-in-your-enterprise-grid) for what Claude does there instead. A bundle attached to a public channel grants its access to anyone who joins that channel. In most Slack workspaces, anyone can join a public channel, so the channel's join policy becomes the effective access control for whatever the bundle grants. Keep elevated credentials in private-channel scopes. ### Attach a single repository or connector To grant a single repository or connector without opening a bundle first, use the **Repositories** and **Connectors** sections on the scope's own panel and select the **+** button (**Add repo** or **Add connector**). When you save the repository or finish connecting, the item is attached to that scope. Each connector or repository row in these sections carries an origin line that says which scope or bundle gave the scope that item. | Origin line | What it means | | :------------------------- | :------------------------------------------------------------------------------------------------------------------ | | **Inherited from** *scope* | The row comes from a wider scope. When an admin-made bundle carries it, the line adds **via** and the bundle's name | | **Attached from** *bundle* | The row was added on this scope through that admin-made bundle | Select the scope name to open that scope, or the bundle name to open the bundle. An item you add with the **+** button is still stored in a bundle, chosen in this order: 1. The bundle that was created for that scope, if it exists 2. The scope's only bundle, if that bundle is bound nowhere else 3. A new bundle created for the scope When the receiving bundle is bound to other scopes too, the picker shows a note that the addition applies in every scope the bundle is bound to. ## Precedence when bundles overlap A channel sees the **union** of every bundle bound at the channel itself, its workspace, and Default Slack access. Narrower scopes don't replace wider ones; they add to them. When two bundles in the resolved set carry rules for the same host, the rule from the narrower scope wins. Within that union, fixed rules decide which credential and which instructions apply. ### Which credential wins When two bundles each carry a credential for the same host: * The credential from the **narrowest scope** is used: channel beats workspace, which beats Default Slack access. * Within the same scope, the order isn't admin-configurable. Avoid binding overlapping credentials at the same scope; if you can't predict which key acts, neither can a security review. * There is no fallback. If the winning credential gets a `401` or `403`, Claude does not retry with the next one. ### Repositories and plugins Repository grants and plugins from every bound bundle are combined as a union; a channel gets every repo and plugin from any bundle in its chain. To see what applies to a channel, select its scope on the **Slack** tab. The scope's panel lists everything that applies there in its **Connectors**, **Repositories**, and **Plugins** sections, inherited items included. Each row's origin line says **Inherited from** the wider scope or **Attached from** the bundle that carries it. Select the scope or bundle name in the origin line to open it. ### Custom instructions Per-scope custom instructions are **concatenated**, Default Slack access first, then workspace, then channel. A channel's instructions add to, rather than replace, what's set above it. ### Instruction layers Three kinds of standing instruction can apply in a channel, written by different people: | Layer | Who writes it | Where | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | | Custom instructions | Owner for any scope; channel members and [channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for the channel scope, unless members are [restricted](#restrict-who-can-set-channel-instructions) | The scope's panel in admin settings, or the **Configure** link in any reply footer for the channel scope | | Channel memory | Anyone in the channel | By telling Claude to remember | | Task prompt | The requester | The message itself | Channel members can shape how Claude responds in their channel through memory, but they can't change which credentials or repositories it has; that's bundle configuration. See [who controls what](/docs/claude-tag/admins/customize) for the full split. Custom instructions are read ahead of the conversation and take priority in practice, but they're guidance, not an enforced guardrail. Don't rely on them to block actions; use access controls for that. ### Add custom instructions Each scope can carry custom instructions, which are standing guidance Claude reads in every session there, like team conventions or where to file tickets. The **Custom instructions** field is on the scope's panel, shown when you select the scope on the **Slack** tab in admin settings. Channel members reach the same field for the channel scope through the **Configure** page, linked in the footer of any Claude reply in the channel, without going through admin settings. Both entry points write the same instructions, so a change from either place is visible in the other. The field is plain text, inserted as written; there is no include or template syntax, and `{{include:...}}` is passed through literally. To give Claude a repository's `CLAUDE.md`, [grant the repository](/docs/claude-tag/admins/configure-github#grant-repository-access) and name it in the request; its `CLAUDE.md` loads after the clone completes. What Claude reads in a channel is the concatenated custom instructions of its scope chain, plus the `CLAUDE.md` of any repository it clones. Projects in claude.ai don't apply here; Claude doesn't read a Project's instructions or knowledge in Slack, and a channel can't be pointed at a Project. A new instruction applies to sessions started after you save it. Claude reads it in every new thread right away, keeps the old text in a thread that's already running, and picks it up at the channel's top level on the next channel message, when it replaces the channel's session (see [Attach the bundle](#attach-the-bundle)). Claude doesn't read a channel's instructions in another channel or in a DM. To confirm what a session is reading, start a new thread and ask Claude to repeat its admin instructions. ### Restrict who can set channel instructions By default, anyone in a channel who is also a member of your Claude organization can edit that channel's instructions from the **Configure** link in Claude's reply footer. The **Channel member edits** setting in a scope's **Advanced** settings controls this. | Option | Effect | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Inherit** | Follow the parent scope's setting | | **Allow** | Members can edit channel instructions from the Configure link | | **Block** | The Configure page is read-only for members, with a note that only admins can change channel instructions. Claude also declines to make a model the channel default when anyone asks in a thread | A chain of scopes that all inherit resolves to **Allow**. Set **Block** at the workspace or Default Slack access scope to lock channel instructions across every channel beneath it. A [channel manager](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) can still edit instructions and the default model from the Configure page in a channel assigned to them when **Block** is set. ## Verify the bundle is live * The bundle card's usage count includes the new scope. To see it named, open the bundle's **Manage** dialog and hover over the count in its footer. * A test task in the pilot channel uses the bundle's connections, and the action appears in the connected service's audit log under your service account. Repeat the attach step for any additional scopes that need elevated access. ## Related resources * [Getting started for users](/docs/claude-tag/users/getting-started): what your team does once the bundle is live * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): narrow where it responds # Attribute costs to users Source: https://claude.com/docs/claude-tag/admins/attribute-costs Pull channel spend per Slack user from the Claude Enterprise Analytics API for showback or chargeback reporting, and see how Claude's work is attributed to people. You can pull Claude Tag channel spend broken out by the Slack user Claude did the work for. The [Claude Enterprise Analytics API](https://platform.claude.com/docs/en/manage-claude/analytics-api) reports your organization's spend over time, and grouping its [cost report](https://platform.claude.com/docs/en/api/admin/analytics/cost/list) by `claude_tag_user_id` returns one row per attributed Slack user. Use the rows to attribute spend to people or departments for showback and chargeback reporting. The Analytics API is available to organizations on a Claude Enterprise plan. To call it, you need an API key with the `read:analytics` scope. Only your organization's primary owner can create that key, at [`claude.ai/admin-settings/api-access`](https://claude.ai/admin-settings/api-access). See [Get access to the Claude Enterprise Analytics API](https://platform.claude.com/docs/en/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api) for the steps. On the [analytics page](https://claude.ai/analytics/claude-tag) in claude.ai you see spend by channel and by kind of work, not by user. For spend by user, use the cost report. ## Get spend per user Call the cost report with `claude_tag_user_id` in `group_by[]`. This example requests one week of channel spend, one row per user per day: ```bash theme={null} curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost_report?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ group_by[]=claude_tag_user_id&\ products[]=claude-tag" \ --header "anthropic-version: 2023-06-01" \ --header "x-api-key: $ANALYTICS_API_KEY" ``` `products[]=claude-tag` limits the report to Claude's work in Slack channels, which bills to your organization's usage balance. DMs with Claude bill to the sender's own seat and aren't reported under `claude-tag`, so this filter leaves them out. Each row's `claude_tag_user_id` is a Slack user ID such as `U0123ABCDEF`, not a claude.ai user ID. A row with a null `claude_tag_user_id` is channel spend with no attributed user, and [How costs map to users](#how-costs-map-to-users) lists those cases. For the full parameters, response schema, and data freshness, see the [cost report reference](https://platform.claude.com/docs/en/api/admin/analytics/cost/list), which also covers grouping by `slack_channel_id` and `claude_tag_category`. ## How costs map to users Channel spend is attributed to at most one Slack user at a time, by these rules: * **Work someone asked for goes to the person who asked.** Spend for each of Claude's replies goes to the member whose message Claude was responding to, so when several people address Claude in one thread, the spend is split across them. * **Work Claude picks up on its own goes to a person in the thread where it did the work.** That person is the member whose message Claude acted on, if there is one. Otherwise it is whoever mentioned Claude into the thread, or, if no one did, the person who started the thread. * **Scheduled routines go to the person who set the routine up.** * **The null row collects spend with no attributable person.** Examples are work Claude started on its own in a thread that another app or bot posted, and a routine whose creator can't be identified. Monitoring, meaning Claude reading a channel it was asked to watch, is never attributed to a user. Per-user rows therefore sum to less than your total channel spend. Per-user attribution doesn't change billing. Channel work still bills to your organization's usage balance, not to any user's seat. See [Set a spend limit](/docs/claude-tag/admins/set-spend-limit) for the billing split. ## Related resources * [Get cost over time](https://platform.claude.com/docs/en/api/admin/analytics/cost/list): the cost report's parameters, response schema, and limits * [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api): key setup, data freshness, and pagination * [Set a spend limit](/docs/claude-tag/admins/set-spend-limit): what bills to the organization's balance versus a user's seat # Review what Claude Tag has done Source: https://claude.com/docs/claude-tag/admins/audit Claude Tag actions appear under its own service accounts in each connected tool's audit log. See what the Audit page covers, how to trace an action to its source, and where each connected tool keeps logs. Use this page to review what Claude Tag is doing across your organization: which routines are scheduled, what memory it has saved, and where to find a record of each action it took. The Audit page opens for Owners in your Claude organization; the other trails on this page are visible to anyone with access to the underlying surface. Claude Tag activity is auditable in four places: * **[The Audit page](#what-the-audit-view-lists)** in admin settings, with tabs for scheduled work, memory, and network events * **Memory files on each scope** (select the scope in the **Claude Tag's access** section, then choose **View memory files** from its **⋯** menu), where you can review what Claude has saved * **[Attribution on each action](#trace-an-action-to-its-source)** Claude takes in a connected tool * **[The audit logs of each connected service](#trace-an-action-to-its-source)**, where its actions appear under the service account you provisioned ## What the Audit view lists The Audit page, labeled **Activity** in the admin console's left nav and page heading, at [`claude.ai/admin-settings/claude-tag/audit`](https://claude.ai/admin-settings/claude-tag/audit) has these tabs: | Tab | What it shows | | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Scheduled work** | Every routine across your organization, with a **Scope** filter and a per-row **⋮** menu (View details, Pause/Resume, Delete) | | **Memory** | Each scope's memory files, where you can read what Claude has saved for that workspace or channel. Owners can also edit or delete entries there. | | **Network events** | An hourly JSON export of outbound calls Claude made through Agent Proxy. Git and MCP traffic are not included in this export. Select a date and hour to download. | Each routine on the **Scheduled work** tab shows **Created by** (the member who set it up) in its **View details** dialog. There is no per-action log of every task and who asked; for that, use the trails below. ## Trace an action to its source In channels, Claude acts as itself, so each action there carries the service-account identity: * **In Slack**, it posts as the Claude app, and its work happens in threads anyone in the channel can read. * **On code**, commits and pull requests show the Claude GitHub App as the author, and each one links back to the Slack thread it came from. * **In every other connected service**, actions appear under the service account you created for the connection. That last one is the general-purpose trail: because you provisioned the credential, the connected service's audit log shows everything Claude did there, under an account your security team already monitors. [Verify your setup](/docs/claude-tag/admins/setup-overview#verify-your-setup) uses this check to validate a new connection. ## See what's scheduled in a channel Anyone in the channel can see its standing work. Ask in the channel: ```text wrap theme={null} @Claude what triggers do you have set up in this channel? ``` Claude lists the channel's scheduled jobs and watches, and anyone there can ask it to disable one. Routines run with the channel's credentials, so the channel listing is also the permission picture. See [proactivity](/docs/claude-tag/users/proactivity#manage-standing-work). ## Related resources * [How agent identity works](/docs/claude-tag/concepts/agent-identity): how attribution differs in channels and DMs * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): the controls when an audit turns something up * [Security and data handling](/docs/claude-tag/concepts/security-and-data): the model behind the trails # Configure GitHub access Source: https://claude.com/docs/claude-tag/admins/configure-github Claude Tag gives Claude its own GitHub identity, so it opens pull requests as Claude. See how to link your GitHub organization, grant repositories to a bundle, what loads when a repository is cloned into a session, how to get project dependencies installed, and what Claude can do with GitHub Actions. Using GitLab instead of GitHub? See [Configure GitLab access](/docs/claude-tag/admins/configure-gitlab). GitLab uses a service-account token rather than an installed app. Claude Tag gives Claude its own GitHub identity, the Claude GitHub App, so pull requests it opens from a channel or a DM are authored by Claude rather than by a person. You only need GitHub access if a team will hand Claude code work: branches, pull requests, review, or CI follow-up. You link GitHub once for your Claude organization, then grant repositories per Access bundle. If you link your GitHub organization before running [setup](/docs/claude-tag/admins/setup-overview), setup includes a step for granting repository access inline, so you don't need to return to the Repositories tab afterward. ## Link your GitHub organization The person who completes the link must be both an **owner of the GitHub organization** and an **Owner in your Claude organization**. If you aren't a GitHub organization owner, use **Copy message** under **Not a GitHub account owner?** on the GitHub settings page to send the link to someone who is. Open [`claude.ai/admin-settings/github`](https://claude.ai/admin-settings/github). This page is shared with Claude Code; one connection serves both products. Click **Connect Claude to GitHub** (**Connect**, once any account is already linked) and complete the GitHub authorization. After authorizing, the **Connected GitHub accounts** table lists the GitHub accounts the Claude GitHub App is installed on. The **Type** column reads **Organization** or **Personal**. An account already linked to your Claude organization shows **Connected**, and one that still needs linking shows **Not linked**. Claude Tag uses **Organization** accounts only; a **Personal** row is someone's own GitHub account and can't be used for your repositories. If your organization's row reads **Not linked**, select the **Link** button next to it. If it isn't listed at all, click **Install on another organization** and complete the install on github.com; you're returned to this page with the organization under **Connected GitHub accounts** as **Connected**. An organization can also be missing from the table because single sign-on (SSO) on GitHub hides it. A note under the table counts the organizations hidden that way. To make them appear, authorize the Claude app for those organizations on GitHub. * A disabled **Link** button means you can't link that account yet; the button's tooltip names the reason, such as not being an owner of that GitHub organization * A **Needs permissions** status means the installation has a pending request; **Review permissions** takes you to github.com to approve it * An **Authorize SSO** button in place of **Link** means your GitHub token isn't authorized for that organization's SSO; the button opens github.com to authorize it, and you link after returning ## Grant repository access The remaining steps are in the Claude Tag admin page, not GitHub's settings. Repository grants live on the Access bundle; editing a bundle's Repositories tab requires the **Owner** role in your Claude organization. A [channel manager](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) can also add repositories to their own channel, limited to repositories their GitHub account is an admin of. Open an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle) and go to its **Repositories** tab. Before any GitHub organization is linked, this tab shows a **Get started with GitHub** button that opens [`claude.ai/admin-settings/github`](https://claude.ai/admin-settings/github). Choose the repositories Claude can read from and open pull requests against. Access is per listed repository, or choose **Connect all** for the organization. ## Verify GitHub access * The GitHub organization shows as **Connected** under **Connected GitHub accounts** at [`claude.ai/admin-settings/github`](https://claude.ai/admin-settings/github). * The granted repositories are listed in the bundle's **Repositories** tab. * For the end-to-end check, open a draft PR from a test channel; see [Verify the bundle is live](/docs/claude-tag/admins/attach-to-scope#verify-the-bundle-is-live). ### If Claude can't reach a repository When Claude replies "That environment or repo isn't configured for Claude Code", or reports that GitHub returned a 403, check the two levels in order. | Check | Where | | :---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The GitHub organization that owns the repository shows **Connected** under **Connected GitHub accounts** | [`claude.ai/admin-settings/github`](https://claude.ai/admin-settings/github). An installation still waiting on a GitHub organization owner shows **Needs permissions**; **Review permissions** opens the approval on github.com. | | The repository is listed on the bundle's **Repositories** tab, and that bundle is attached to the channel's scope | [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Access bundles** → the bundle → **Repositories**. A repository granted in one bundle isn't reachable from a channel under a different bundle. | Repository grants apply to new threads. After changing the **Repositories** tab, start a fresh thread in the channel and name the repository in the first message. A `403` that names a GitHub Actions operation, such as "repository\_dispatch is not permitted for this session type.", is a different error. It says nothing about repository access; see [What Claude can do with GitHub Actions](#what-claude-can-do-with-github-actions). ## How granted repositories reach a session Granting a repository in a bundle makes it *available* to Claude in any channel under that bundle's scope. It doesn't clone the code into a session on its own. A session starts with no repositories checked out; Claude clones one when the request names it, or when someone in the thread tells it which repository to add. Tell your team to name the repository in the first message of a code task. ### What loads from a repository When Claude clones a granted repository into a session, its Claude Code configuration loads on the next turn after the clone completes, so project context arrives without further prompting: * `CLAUDE.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md` load as project context * Skills in `.claude/skills/` load, so Claude can use them in the session [Hooks](https://code.claude.com/docs/en/hooks) in a repository's `.claude/settings.json` don't run in the session. A repository's `.mcp.json` is never loaded, and connections come only from the Access bundle. Repository skills apply only in sessions that have the repository. To give a skill to every channel under a scope, add it through a [skills repository](/docs/claude-tag/admins/skills-repo). ### Install project dependencies Every session runs in an isolated sandbox with a standard set of preinstalled tools. There are two places to add what a project needs beyond that set, such as a specific language runtime or a database client: * **For every session in a channel**, an admin adds the install commands to the setup script of the environment the channel's sessions run on. See [Configure the environment for a scope](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope). * **For one repository**, add the install commands to the repository's `CLAUDE.md`. Claude follows `CLAUDE.md` as guidance when it starts work that needs it, not as an unconditional setup step. Write each install as a precondition of the work it supports, for example "install the SDK before building or running tests", so Claude runs it when a task touches that code. The sandbox is fresh for every session, so the installs repeat each time Claude works in the repository. Prefer the standard package manager and its default registry over a vendor install script or a third-party package source. Package managers such as `apt`, `pip`, `npm`, and `dotnet` reach their default registries from the sandbox; downloads from other hosts can be blocked at the sandbox's [egress boundary](/docs/claude-tag/concepts/security-and-data#network-egress). An Owner can allow an additional host on the bundle's Domains tab; see [Allow a host without a credential](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential). ## What Claude can do with GitHub Actions In a channel, Claude acts on GitHub as the Claude GitHub App, and that identity carries a fixed set of GitHub Actions permissions. No admin setting changes it, and adding `api.github.com` as a [custom connection](/docs/claude-tag/admins/connections/custom) with your own token doesn't change it either; Claude's GitHub requests always act as the Claude GitHub App. Claude can: * Read workflow runs, jobs, logs, and artifacts, so it follows a pull request's CI and reports the result * Re-run a workflow run or its failed jobs, cancel a run in progress, and dispatch a `workflow_dispatch` workflow * Delete runs, logs, or artifacts, and enable or disable a workflow * Trigger `push` and `pull_request` workflows by pushing a branch or opening a pull request, the same way any other author does * Edit files under `.github/workflows/` and open a pull request with the change, like any other file Claude can't: * Send a `repository_dispatch` event * Approve a workflow run that's waiting on approval, or its pending deployments A request for either is refused with a `403`; a `repository_dispatch` request returns "repository\_dispatch is not permitted for this session type." Approving a held run or a pending deployment releases a checkpoint GitHub inserted for a person, so do it from the repository's **Actions** tab on github.com. ## Require a second approval on Claude's pull requests Claude is the author of the pull requests it opens, from a channel or a DM, so GitHub's rule against approving your own pull request applies to Claude and not to the person who asked for the change. On a branch that requires one approving review, the person who asked Claude for a change can approve and merge it alone. If you want a second person to look at Claude's work before it merges, require the second review in GitHub. GitHub gives you two ways, both set in a branch protection rule or ruleset on each branch Claude opens pull requests against. * **Require two approving reviews.** GitHub's built-in setting. It applies to pull requests from people too. * **Require a status check that only Claude's pull requests must pass.** A check you build and maintain, for example a GitHub Actions workflow that fails on pull requests authored by `claude[bot]` (or by your own app's `[bot]` login on [GitHub Enterprise Server](#github-enterprise-server)) until two people have approved, and passes on pull requests people open. With either, also turn on dismissing stale approvals when new commits are pushed, so an approval doesn't carry over to a later push. See [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) and [About status checks](https://docs.github.com/en/pull-requests/reference/status-checks) in GitHub's documentation. ## Scheduled work uses the same connection Scheduled jobs use the same GitHub connection as interactive work, with nothing extra to configure. A recurring job that can't reach its repository skips that run and retries on its next schedule; after three consecutive failed runs spanning at least an hour, it disables itself. A one-time job that can't reach its repository is disabled on the first failure; the routine's page shows why. ## GitHub Enterprise ### GitHub Enterprise Cloud with data residency Organizations on `*.ghe.com` (Enterprise Cloud with Data Residency) are registered the same way as a GitHub Enterprise Server host below. ### GitHub Enterprise Server GitHub Enterprise Server instances are supported when reachable from the public internet. A GHES host on a private network without a public address can't be connected. On GHES, you create the GitHub App on your own instance instead of installing Anthropic's. The setup is shared with Claude Code; follow the [Claude Code GitHub Enterprise Server guide](https://code.claude.com/docs/en/github-enterprise-server) to create and register the app. After registering the GHE host, a host picker appears on the bundle's **Repositories** tab; select your host there to grant its repositories. Registering a GHE host with your Claude organization isn't fully self-serve. Raise it with your account team if the guide doesn't get you all the way through. ## Related resources * [Configure per-channel access](/docs/claude-tag/admins/attach-to-scope): bind the bundle to the workspaces and channels that need it * [Set up routines](/docs/claude-tag/users/proactivity): the scheduled jobs that use this connection # Configure GitLab access Source: https://claude.com/docs/claude-tag/admins/configure-gitlab Give Claude its own GitLab identity so it can read projects, manage issues, review merge requests, and check pipelines as a service account. Covers creating the account, scoping its access, generating a token, and adding it to a bundle. Connecting GitLab lets Claude read repository contents, manage issues, review and comment on merge requests, and check pipeline status from any channel under a bundle's scope, all through the GitLab API. Unlike GitHub, there is no Claude app to install in GitLab. Instead, you give Claude its own GitLab user and add that user's personal access token to an Access bundle. The connection is API-only. The token authenticates GitLab API requests, not git, so Claude gets a 401 error when it tries to clone a private project or push to any project over HTTPS, even with the connection in place. To clone a repository into the session workspace, connect it through [GitHub](/docs/claude-tag/admins/configure-github) instead. A dedicated service account keeps Claude's GitLab activity attributed to a single identity you control. You decide which groups and projects it can reach by granting that account membership the same way you would for a person, and you can revoke or rescope it at any time without touching anyone else's access. ## Prerequisites * The **Owner** role in your Claude organization to create an Access bundle. * Permission in GitLab to create a user (or a [service account](https://docs.gitlab.com/user/profile/service_accounts/) on tiers that offer it) and to add that user to the groups or projects Claude should reach. * An [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle) to hold the credential. Create one first if you haven't already. ## Create a dedicated GitLab account for Claude Create a GitLab user that exists only for Claude, for example `claude@yourcompany.example.com`. On GitLab Premium or Ultimate, a [service account](https://docs.gitlab.com/user/profile/service_accounts/) is the cleanest fit because it is clearly non-human. On other tiers, a regular user works the same way; treat it as a bot seat. Set the account's display name and avatar to whatever you want teammates to see on Claude's comments and issue activity. ## Grant the account access to your groups and projects Add the service account as a member of each GitLab group or project Claude should work in. Granting at the group level is usually simpler than adding it to projects one at a time, and it means new projects in that group are reachable without another grant. The role you grant determines which API calls succeed. Grant the lowest role that covers what you want Claude to do: reading code and browsing issues and merge requests needs less than creating issues, posting review comments, or acting on pipelines. See GitLab's [permissions reference](https://docs.gitlab.com/user/permissions/) for what each role allows. ## Generate a personal access token Create a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) for the account. For a GitLab.com service account, create the token from the group's service account settings or through the API; for a regular bot user, sign in as it and create the token from its profile. The token starts with `glpat-`. | Scope | When to grant it | | :--------- | :------------------------------------------------------------------------------------------------------ | | `api` | Read and write. Required for Claude to create and update issues, post comments, and act on pipelines. | | `read_api` | Read-only. Use this instead of `api` if you want Claude to browse and answer questions but never write. | Set an expiry that matches your rotation policy, and store the token somewhere you can retrieve it once; GitLab shows it only at creation. Group access tokens and project access tokens also work in the same field. The service-account approach is recommended because one token covers every group you add the account to, and the identity on comments and issues is yours to name. A group or project token is scoped to that single group or project and appears under a GitLab-generated bot name. ## Add the token to an Access bundle At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles**, click into the bundle, and go to **Credentials**. Click **Connect** next to **GitLab** and paste the token into **Personal access token**. If your organization's plugin marketplace includes a GitLab plugin, add it on the bundle's **Plugins** tab so Claude knows how to call the GitLab API. See [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). The connection works without the plugin, which adds ready-made workflows. The token is held by [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) and injected on every API request to your GitLab host. The model and the session sandbox never see it. ## Self-managed GitLab Self-managed GitLab instances are supported when reachable from the public internet. In the **Connect GitLab** form, open the **Advanced** tab and add your instance's hostname under **Allowed websites**; `gitlab.com` is preset for GitLab SaaS. An instance on a private network without a public address can't be connected. ## Verify GitLab access * GitLab is listed under the bundle's **Credentials** tab. * In a channel under the bundle's scope, `@Claude what can you access from this channel?` returns GitLab. * In that same channel, ask Claude to list the open issues in one of your GitLab projects. Claude returns them without prompting for credentials. ## Related resources * [Connect GitLab](/docs/claude-tag/admins/connections/gitlab): the credential field reference and how GitLab differs from GitHub * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential and bundle reference * [Configure GitHub access](/docs/claude-tag/admins/configure-github): the GitHub App path, which is different # Connect Asana Source: https://claude.com/docs/claude-tag/admins/connections/asana Connect Asana to Claude Tag so it can file tasks and read project status. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Asana lets Claude file tasks and pull project status from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Asana plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Asana On every Asana plan, create the personal access token from a dedicated Asana seat for Claude, and give that seat access to only the projects and teams Claude needs. Per Asana's guidance, avoid service account tokens, which carry organization-wide access. Asana's own guide for creating the credential is at [developers.asana.com](https://developers.asana.com/docs/personal-access-token). ## Add the connection to a bundle In the bundle, click **Connect** next to **Asana**. | Field | Value | | :----------------------------- | :----------------------------------- | | Claude's personal access token | The personal access token from Asana | | Allowed websites | `app.asana.com` | The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Asana appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/track-projects): the issue tracking use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Jira and Confluence Source: https://claude.com/docs/claude-tag/admins/connections/atlassian Connect Atlassian Cloud to Claude Tag so it can read and update Jira issues and search Confluence pages. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Atlassian Cloud lets Claude read and search Confluence pages and read, comment on, and update Jira issues from any channel under the bundle's scope. One credential covers both products on the same Atlassian site. This is an HTTP API connection, not an MCP server or a personal claude.ai connector. Pair it with a plugin that covers Jira and Confluence so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). ## Create the credential in Atlassian Create a dedicated Atlassian account for Claude (for example `claude@yourcompany.example.com`) and add it to the Jira projects and Confluence spaces it should reach. The connection can read whatever this account can read, so a dedicated account keeps Claude's reach to exactly what you grant it. Sign in as that account and create an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Atlassian shows the token once; store it somewhere you can retrieve it. Atlassian API tokens expire, with a maximum lifetime of one year, so plan to create a new token and update the connection before the old one lapses. Create the API token without scopes. Atlassian accepts tokens with scopes, including service account tokens, only at its `api.atlassian.com` gateway, not at your site's hostname, so the preset can't use them. If your organization requires tokens with scopes, connect through the gateway instead of the preset. Add a [custom connection](/docs/claude-tag/admins/connections/custom) with the **Basic** credential type, the dedicated account's email and token, and `api.atlassian.com` under **Allowed websites**. Then [restrict the connection](/docs/claude-tag/admins/add-connections#restrict-by-path-or-method) to the path prefixes `/ex/jira//` and `/ex/confluence//`, because the cloud ID in a gateway request's path chooses which Atlassian site the request reaches. Atlassian documents [tokens with scopes](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/), [service account tokens](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/), and [how to find your site's cloud ID](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/). ## Add the connection to a bundle On the bundle's **Credentials** tab, click **Connect** next to **Jira & Confluence**. The form asks for the dedicated account's email address and the API token from Atlassian. In the host field, replace the prefilled `*.atlassian.net` with your own site's hostname, such as `your-domain.atlassian.net`. The form rejects the wildcard because it would let the credential reach any Atlassian site, not just yours. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). Atlassian Data Center (self-hosted) isn't covered by the preset because it authenticates with a personal access token sent as a Bearer header. Add a Data Center instance as a [custom connection](/docs/claude-tag/admins/connections/custom) with the **Bearer** credential type and your instance's hostname under **Allowed websites**. The instance must be reachable from the public internet. ## Verify the connection In a channel under the bundle's scope, in a new thread, ask Claude to fetch one issue or page by key or URL. The call lands under the dedicated account in Atlassian's audit log. ```text wrap theme={null} @Claude can you read PROJ-123 from Jira? ``` New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [Custom connection](/docs/claude-tag/admins/connections/custom): for a setup the preset doesn't cover, such as a self-hosted Data Center instance * [Give Claude access](/docs/claude-tag/admins/add-connections): the full connection model and how to scope a dedicated account # Connect BigQuery Source: https://claude.com/docs/claude-tag/admins/connections/bigquery Connect BigQuery to Claude Tag so it can run read-only queries on your datasets. BigQuery has no preset, so it is added as a custom credential with a GCP service-account key. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting BigQuery lets Claude run queries against your datasets from any channel under the bundle's scope. Add it as a custom credential with **Custom tool**; BigQuery has no preset button in the picker. This is an HTTP API connection, not a personal claude.ai connector. Pair it with a plugin that covers BigQuery so Claude knows how to form and run queries; without one, Claude can reach the API but has to work out the request shape on its own. See [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). ## Create the credential in Google Cloud Create a dedicated service account for the agent in the Google Cloud project that holds your BigQuery data, then create a JSON key for it. Google's guides cover [creating a service account](https://cloud.google.com/iam/docs/service-accounts-create) and [creating a service account key](https://cloud.google.com/iam/docs/keys-create-delete). ## Grant access to specific datasets You scope what Claude can read on the Google Cloud side, through the service account's role grants. The connection itself has no dataset setting. Grant the service account two roles: * **BigQuery Data Viewer** (`roles/bigquery.dataViewer`) on each dataset Claude should query. Grant it on the specific datasets, not on the project, so Claude can read only those datasets. * **BigQuery Job User** (`roles/bigquery.jobUser`) on the project, so the service account can run query jobs. Together the two grants let Claude run read-only queries against those datasets. To widen or narrow access later, edit the dataset grants in Google Cloud; the connection needs no change. ## Add the connection to a bundle In the bundle, click **Connect** next to **Custom tool** and choose **GCP access token (with Service Account Key)**. | Field | Value | | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Credential type | **GCP access token (with Service Account Key)** | | GCP service account key (JSON) | The JSON key file from Google Cloud Console | | Scopes (optional) | `https://www.googleapis.com/auth/bigquery`. The field is labeled optional, but leave it empty and the token defaults to a broader scope. BigQuery's query endpoints don't accept a read-only scope; the dataset roles in the section above are what keep the connection read-only. | | Allowed websites | `bigquery.googleapis.com` | Agent Proxy exchanges the service-account key for an access token and injects it at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` BigQuery appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. Then confirm a query runs against a dataset you granted: ```text wrap theme={null} @Claude how many rows are in .? ``` ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/answer-data-questions): warehouse questions answered with charts in the thread * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect a service that isn't in the list Source: https://claude.com/docs/claude-tag/admins/connections/custom Connect a tool that has no built-in preset to Claude Tag. Covers credential types, what each form field means, and how to add a custom MCP server. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. For a service that doesn't have a preset Connect button, use **Custom tool** on the bundle's Credentials tab. This works for any service with an HTTP API. The [BigQuery](/docs/claude-tag/admins/connections/bigquery) guide is a worked example. ## Add a custom HTTP API ### What you need from the service * A service-account credential (an API key, token, or OAuth client), not your personal login * The API host (for example `api.example.com`) * How the API authenticates (which header or flow it expects) See [Create a dedicated account per service](/docs/claude-tag/admins/add-connections#create-a-dedicated-account-per-service) for the service-account patterns. ### Fill out the Custom tool form | Field | What to enter | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | A label for this connection (for example "Internal billing API") | | **Credential type** | Pick the type that matches how the API authenticates; see [Credential types](#credential-types) | | **Allowed websites** | The API's host (for example `api.example.com`). A wildcard is allowed as the leftmost label. You can't enter `*` alone here; a credential is always limited to specific hosts (see [Allow all hosts](/docs/claude-tag/admins/add-connections#allow-all-hosts)). The credential is sent only to hosts you list here. | | **Path prefixes** (optional) | Restrict the credential to specific URL paths under the host. Shown only for the MCP Connector type, and only when the provider you pick doesn't fix its own hosts and paths. | | **Custom headers** | Any extra headers the API requires beyond the credential. Shown only for the Bearer credential type. | After saving, where the credential has an allow rule, you can narrow it by HTTP method and path from its **Edit connection** dialog; see [Restrict by path or method](/docs/claude-tag/admins/add-connections#restrict-by-path-or-method). ### Credential types | Type | Use for | | :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------- | | **Bearer** | An API key or token sent as `Authorization: Bearer `. Most SaaS REST APIs. | | **Basic** | HTTP Basic authentication (`Authorization: Basic `) | | **Body parameter** | A token the API expects in the request body or query string instead of a header | | **AWS SigV4** | AWS service APIs on `amazonaws.com` endpoints that require Signature Version 4 signing | | **GCP access token (with Service Account Key)** | Google Cloud APIs; the proxy exchanges the SA key for an access token | | **GCP IAP (with Service Account Key)** | Google Cloud services behind Identity-Aware Proxy | | **OAuth 2.0 JWT bearer** | APIs that accept a JWT signed with your private key in exchange for an access token (DocuSign, for example) | | **OAuth 2.0 client credentials** | Machine-to-machine OAuth with a client ID and secret | | **MCP Connector** | OAuth sign-in. Sign in once as an admin; the agent acts as that account. | For GitHub repositories, use the GitHub connection at [Configure GitHub access](/docs/claude-tag/admins/configure-github) rather than a credential from this table. If you're unsure which type, check the service's API authentication docs for which header or flow it expects. ### AWS SigV4 Use the **AWS SigV4** credential type for AWS service APIs such as S3, Lambda, and DynamoDB. Agent Proxy reads the AWS service and signing region from the hostname and signs each outbound request with the credential at the boundary, so neither the model nor the sandbox holds the keys. Agent Proxy signs requests to hostnames in these forms: * `service.region.amazonaws.com` * S3 virtual-hosted-style endpoints, for example `my-bucket.s3.us-east-1.amazonaws.com` * Service hostnames with extra parts before the service name, as long as the region is the last part before `amazonaws.com`, for example the Amazon ECR API host `api.ecr.us-east-1.amazonaws.com` or the host of an API Gateway invoke URL, `abc123.execute-api.us-east-1.amazonaws.com` * The regionless hosts of IAM, STS, S3, Route 53, CloudFront, Organizations, and Global Accelerator, for example `iam.amazonaws.com`, which Agent Proxy signs for `us-east-1` Requests to other hostnames fail before reaching AWS. Agent Proxy can't sign a request to a hostname with no region for any other service, such as `ec2.amazonaws.com`, or to a hostname with the region before the service name, such as an OpenSearch domain endpoint (`my-domain.us-east-1.es.amazonaws.com`). It also can't sign requests to an API Gateway custom domain or to a non-AWS API that uses Signature Version 4. | Field | Value | | :---------------- | :---------------------------------------------------------------------------------------------------------- | | Access key ID | The IAM user or role access key, for example `AKIAIOSFODNN7EXAMPLE` | | Secret access key | The matching secret access key | | Session token | Optional. Only needed for temporary credentials from AWS STS. | | Allowed websites | The AWS service endpoint host, for example `s3.us-east-1.amazonaws.com` or `lambda.us-east-1.amazonaws.com` | Use long-lived credentials from a dedicated IAM user where you can. Temporary STS credentials work but expire on their own schedule, and the connection stops working when they do; you re-enter all three values to rotate. Claude can call the endpoint with `curl`, an AWS SDK, or the AWS CLI. The sandbox holds no real AWS credentials, so a CLI or SDK signs the request with placeholder values; Agent Proxy strips that signature and re-signs with the stored credential before the request leaves for AWS. Agent Proxy can't sign an S3 upload sent in chunks with a checksum trailer, which the AWS CLI and the AWS SDKs send when they compute upload checksums by default. That upload fails with HTTP 502 and the reason `injection failed ("")`. Have Claude add `request_checksum_calculation = WHEN_REQUIRED` to the profile in `~/.aws/config` and retry. The federated-access troubleshooting entry [An AWS request fails after a successful sign-in](/docs/claude-tag/admins/federated-access/troubleshooting#an-aws-request-fails-after-a-successful-sign-in) gives the same fix, the environment-variable form, and how to apply the setting in every thread. #### When AWS returns `SignatureDoesNotMatch` A `SignatureDoesNotMatch` response from AWS means the request AWS received doesn't match the one Agent Proxy signed. | Check | What to do | | :---------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The access key ID and secret access key belong to the same IAM identity | Re-enter the access key ID, secret access key, and session token together. The form is write-only, so a partial update can leave them mismatched. | | No proxy or gateway of your own sits between Anthropic and AWS | A second proxy that adds, strips, or reorders headers, or that re-signs the request, invalidates the signature Agent Proxy attached. Point **Allowed websites** at the AWS endpoint directly. | A dropped or expired session token is a different failure: AWS rejects it with a token error such as `InvalidClientTokenId`, not `SignatureDoesNotMatch`. Rotate all three fields. ### OAuth 2.0 JWT bearer Use the **OAuth 2.0 JWT bearer** credential type for APIs that exchange a JWT signed with your private key for an access token. The [Salesforce guide](/docs/claude-tag/admins/connections/salesforce) is a worked example. The **Private key (PEM)** field takes a PEM-encoded RSA private key without a passphrase, the format that begins with `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----`. Identity providers such as Okta export the key as a JWK (a JSON object) by default; convert a JWK to PEM before pasting it. The form doesn't check the key's format, so a key in the wrong format fails only when you save. #### When saving fails with "Failed to create egress credential" Saving the form can return the error "Failed to create egress credential. Check your inputs and try again." The most likely cause is a private key that isn't PEM-encoded, for example a JWK pasted as-is into the **Private key (PEM)** field. Convert the key to PEM and save again. Saving also fails when a PEM-encoded key isn't an RSA key or has a passphrase. Once the key is in the right format, re-check each field against the values from your service. ## Add a custom MCP server The server must be a remote endpoint that Claude can reach at a URL over the internet. An MCP server that runs on a person's machine over stdio, including one packaged as a [desktop extension](/docs/connectors/custom/desktop-extensions), can't be connected, because [sessions](/docs/claude-tag/concepts/glossary#session) run in a cloud sandbox that Anthropic hosts, not on anyone's machine. Host the server as a remote endpoint first, then follow the steps below. To give Claude an MCP server (one you run, or a vendor's hosted MCP endpoint), the pattern is a plugin plus a credential: In the bundle's **Plugins** tab (or via your [skills repository](/docs/claude-tag/admins/skills-repo)), add a plugin whose `.mcp.json` points at the server URL. The plugin tells Claude the server exists and how to call it. On the **Credentials** tab, click **Connect** next to **Custom tool** and add a credential for the MCP server's host (for example, a Bearer token with **Allowed websites** set to `your-mcp-host.example.com`). This lets the call leave the sandbox with auth attached. The plugin's `.mcp.json` is loaded because it's part of an attached plugin; an `.mcp.json` checked into a repository Claude clones is not loaded. ## Verify the connection In a channel under the bundle's scope, in a new thread, ask Claude to make a small read against the API: ```text wrap theme={null} @Claude can you reach api.example.com? Try a GET on /health. ``` Check the service's own audit log to confirm the call landed under your service account. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. If Claude reports that it can't use the credential, check its status on the [Access bundles page](https://claude.ai/admin-settings/claude-tag/access-bundles). **Not active** means no allow rule uses the credential yet. **Approval needed** means another admin submitted it through a shared setup link; select **Review**, then **Approve**. See [Verify the connection saved](/docs/claude-tag/admins/add-connections#verify-the-connection-saved). ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the full connection model * [Allow a host without a credential](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential): for public APIs that need no auth * [Allow all hosts](/docs/claude-tag/admins/add-connections#allow-all-hosts): the egress option that lets Claude reach any public host without a credential # Connect Datadog Source: https://claude.com/docs/claude-tag/admins/connections/datadog Connect Datadog to Claude Tag so it can query metrics, logs, and monitors. Covers the dedicated account to create, the API key fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Datadog lets Claude query metrics, logs, and monitors during debugging from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Datadog plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Datadog Create an API key under a service account in Datadog. Also create an Application key under the same service account. The Application key carries the read scopes, so restrict it to read-only roles. The form doesn't require the Application key, but reading metrics, monitors, and dashboards does. Datadog's own guide for creating the credential is at [docs.datadoghq.com](https://docs.datadoghq.com/account_management/api-app-keys/). ## Add the connection to a bundle In the bundle, click **Connect** next to Datadog. The picker has three Datadog entries, one per site. Pick the one that matches your Datadog account's site. | Picker entry | Site | | :---------------- | :------------------------------------------ | | **Datadog** | US1 (`api.datadoghq.com`), the default site | | **Datadog (US5)** | US5 (`api.us5.datadoghq.com`) | | **Datadog (EU)** | EU (`api.datadoghq.eu`) | The form asks for the same fields in all three. | Field | Value | | :----------------------- | :------------------------------------------------------------------------------------------------------------------ | | Claude's API key | The API key from Datadog | | Claude's application key | The Application key from Datadog. Optional in the form; add it so Claude can read metrics, monitors, and dashboards | | Allowed websites | Prefilled by the preset; override for other sites (see below) | Datadog has a separate API host per site, and a key only works against its own. If your account is on a site without a picker entry, pick any Datadog entry and override Allowed websites with your site's API host: `api.us3.datadoghq.com`, `api.ap1.datadoghq.com`, or `api.ddog-gov.com`. To change the host later, open the **⋮** menu on this connection in the bundle's Credentials tab and choose **Edit**. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Datadog appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/watch-monitors): the monitoring use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect GitLab Source: https://claude.com/docs/claude-tag/admins/connections/gitlab Connect GitLab to Claude Tag so it can read code, manage issues, comment on merge requests, and check pipelines through the GitLab API. Covers token permissions, self-managed hostnames, and how it differs from GitHub. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting GitLab lets Claude read and search projects, manage issues, comment on merge requests, and check pipeline status, all through the GitLab REST API. The connection is a single access token added to a bundle. This page is the credential field reference. The full setup walkthrough, including creating a dedicated GitLab service account for Claude and scoping its group access, is at [Configure GitLab access](/docs/claude-tag/admins/configure-gitlab). If your plugin marketplace includes a GitLab plugin, pair it with this connection so Claude knows how to call the API. See [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). The connection works without it. ## Add the connection A personal access token from a [dedicated service account](/docs/claude-tag/admins/configure-gitlab#create-a-dedicated-gitlab-account-for-claude) is recommended, so one identity covers every group you add it to. Project and group access tokens also work if you only need a single project or group. Grant the `api` scope for read and write, or `read_api` for read-only. The token starts with `glpat-`. On the bundle's **Credentials** tab, click **Connect** next to **GitLab** and paste the token. For self-managed GitLab, switch to the form's **Advanced** tab and add your instance's hostname under **Allowed websites**. **You'll see:** GitLab listed in the bundle's connections, and `@Claude what can you access from this channel?` returns it in a new thread under the bundle's scope. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. | Field | Value | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | Personal access token | The token from GitLab, starting with `glpat-`. Project and group access tokens work here too; the label is the field name, not a token-type constraint. | | Allowed websites | `gitlab.com` (preset). For self-managed GitLab, open the **Advanced** tab and add your instance's hostname here. | GitLab's own guide for creating tokens is at [docs.gitlab.com](https://docs.gitlab.com/api/rest/authentication/). ## How GitLab differs from GitHub | | GitLab | GitHub | | :-------------------------------- | :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- | | Auth | A service account's personal access token | The Claude GitHub App, [installed separately](/docs/claude-tag/admins/configure-github) | | Referencing a project in a thread | Give Claude the full project URL; it reads it through the API | Typing `owner/repo` in the message auto-attaches it | | Self-managed | Your hostname under **Advanced → Allowed websites** | [GitHub Enterprise setup](/docs/claude-tag/admins/configure-github#github-enterprise) | | Handing back changes | Manages issues and comments on merge requests through the API | [Draft pull requests](/docs/claude-tag/users/use-cases/work-with-github) authored by the Claude GitHub App | The connection is API-only. The token authenticates GitLab API requests, not git, so Claude gets a 401 error when it tries to clone a private project or push to any project over HTTPS, even with the connection in place. To clone a repository into the session workspace, connect it through [GitHub](/docs/claude-tag/admins/configure-github) instead. The token is auto-injected on every API request to your GitLab host. The model and the sandbox are not given the key; see [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Related resources * [Configure GitHub access](/docs/claude-tag/admins/configure-github): the GitHub App path, which is different * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Gong Source: https://claude.com/docs/claude-tag/admins/connections/gong Connect Gong to Claude Tag so it can pull call summaries and deal context. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Gong lets Claude pull call summaries and deal context from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Gong plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Gong A Gong technical admin generates the access key and secret; the key is tied to the admin who created it, so use a dedicated admin account where possible. The credential type is HTTP Basic; both the access key and the access key secret are required. Gong's own guide for creating the credential is at [help.gong.io](https://help.gong.io/docs/receive-access-to-the-api). ## Add the connection to a bundle In the bundle, click **Connect** next to **Gong**. | Field | Value | | :------------------------- | :------------------------------ | | Claude's access key | The access key from Gong | | Claude's access key secret | The access key secret from Gong | | Allowed websites | `api.gong.io` (preset) | Gong assigns each company its own API base URL, like `us-46459.api.gong.io`. Copy yours from **Company Settings** → **Ecosystem** → **API** in Gong, then switch to the connection form's **Advanced** tab and enter it under **Allowed websites**. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Gong appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/pull-deal-state): the go-to-market use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Google Drive, Calendar, and Gmail Source: https://claude.com/docs/claude-tag/admins/connections/google Connect Google Drive, Calendar, and Gmail to Claude Tag so it can read docs, sheets, events, and email. Covers OAuth setup, the service-account option, and what each grants. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Google Drive, Calendar, and Gmail lets Claude read documents, spreadsheets, calendar events, and email from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. This is an HTTP API connection, not a personal claude.ai connector. A member's own Google connector applies in DMs. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use it in a channel for that member's own tasks, after the member allows it. ## Choose OAuth or a service account The connection picker offers two routes: | Route | When to use | | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | | **OAuth (Connect button)** | Fastest path. An admin signs in with a Google account that has access to the content Claude needs. | | **GCP service-account key** | When you want a dedicated non-human identity in Google with auditable access, or need domain-wide delegation across your Workspace. | Both routes create a credential and an allowed-websites rule for the Google hosts the connection uses. ## Add the connection with OAuth Use a dedicated Google account for this connection (for example, `claude@yourcompany.example.com`), not your own. The connection is shared: anyone in a channel under the bundle's scope can ask Claude to read whatever this account can see in Drive, Calendar, and Gmail. A dedicated account starts with no access until you share the specific folders and calendars Claude needs, and keeps its activity under a separate identity in Google's audit log. In the bundle, click **Connect** next to **Google Drive**, **Google Calendar**, or **Gmail**. The dialog lists the Google hosts the connection can reach; there are no scopes to choose. Click **Sign in with Google Drive** (or **Sign in with Google Calendar**, or **Sign in with Gmail**), approve the Google consent screen, and the credential is saved. The connection's reach is whatever the signed-in Google account can see. Share the relevant folders and calendars with that account in Google before testing. ## Add the connection with a service account In the bundle, click **Connect** next to **Custom tool** and choose **GCP access token (with Service Account Key)**. | Field | Value | | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GCP service account key (JSON) | The JSON key file from Google Cloud Console | | Scopes (optional) | The Google API scopes to request (for example `https://www.googleapis.com/auth/drive.readonly`). The field is labeled optional, but Drive and Calendar calls fail without the matching scope listed here. | | Subject (optional) | A user email to impersonate via domain-wide delegation. Set this for Workspace data (Drive, Calendar, Gmail, Docs). | | Allowed websites | `*.googleapis.com` | For Google Workspace data (Drive, Calendar, Gmail, Docs), the service account needs domain-wide delegation configured in your Google Admin console with the matching API scopes. Google's guide is at [developers.google.com/identity/protocols/oauth2/service-account](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority). The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Google Drive, Calendar, or Gmail appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. The credential row in the bundle shows **Never used** until Claude first uses the connection. The label tracks usage, not health, so a working connection stays on **Never used** until someone exercises it. To confirm the connection works, ask Claude in the same thread to read something from the service, such as today's calendar events or a named document. The label updates after that first read. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/find-answers): grounding answers in your team's documents * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect HubSpot Source: https://claude.com/docs/claude-tag/admins/connections/hubspot Connect HubSpot to Claude Tag so it can read pipeline, deal, and contact data. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting HubSpot lets Claude pull pipeline, deal, and contact state from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the HubSpot plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in HubSpot Create a private app and select the read scopes you need (typically `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read`). The private app acts as its own identity in HubSpot's audit log. HubSpot's own guide for creating the credential is at [developers.hubspot.com](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview). ## Add the connection to a bundle In the bundle, click **Connect** next to **HubSpot**. | Field | Value | | :------------------------- | :---------------------------------------------------------------------------- | | Claude's private app token | The private app token from HubSpot | | Allowed websites | `api.hubapi.com` (preset). To add a different host, use the **Advanced** tab. | The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` HubSpot appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/pull-deal-state): the go-to-market use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Linear Source: https://claude.com/docs/claude-tag/admins/connections/linear Connect Linear to Claude Tag so it can file tickets and post status updates. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Linear lets Claude file tickets and post status updates from a thread from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Linear plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Linear Create a personal API key from a dedicated Linear seat for Claude, not your own account, so its activity shows under that seat in Linear's audit log. Scope the key to specific Linear teams when you create it; the only place to limit which projects Claude can write to is in Linear itself. The key starts with `lin_api_`. Linear's own guide for creating the credential is at [linear.app](https://linear.app/developers/graphql#personal-api-keys). ## Add the connection to a bundle In the bundle, click **Connect** next to **Linear**. | Field | Value | | :--------------- | :---------------------- | | Claude's API key | The API key from Linear | | Allowed websites | `api.linear.app` | The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Linear appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/create-artifacts): the issue tracking use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Notion Source: https://claude.com/docs/claude-tag/admins/connections/notion Connect Notion to Claude Tag so it can read and search your Notion workspace. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Notion lets Claude ground answers in your Notion workspace from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Notion plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Notion Create an internal integration in Notion and share the specific pages or databases Claude should read with that integration. Nothing is reachable until shared. Notion's own guide for creating the credential is at [developers.notion.com](https://developers.notion.com/docs/create-a-notion-integration). ## Add the connection to a bundle In the bundle, click **Connect** next to **Notion**. | Field | Value | | :-------------------------- | :------------------------------------------ | | Claude's integration secret | The internal integration secret from Notion | | Allowed websites | `api.notion.com` | The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Notion appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/find-answers): the knowledge and docs use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Per-service connection guides Source: https://claude.com/docs/claude-tag/admins/connections/overview Step-by-step setup for each tool Claude Tag can connect to. Each guide covers the dedicated account to create, the credential to enter, and the URL to allow. Each guide covers one service: how to create the credential as a dedicated identity, what to paste into the Access bundle, and the Allowed websites value. For the model behind connections (credential types, Agent Proxy, allowed websites), see [Give Claude access](/docs/claude-tag/admins/add-connections). Always connect a dedicated account for Claude (for example, `claude@yourcompany.example.com`), not your personal login. Anyone in a channel under the bundle's [scope](/docs/claude-tag/admins/attach-to-scope) can use the connection through Claude, so whatever this account can reach is available to every member of those channels. See [Create a dedicated account per service](/docs/claude-tag/admins/add-connections#create-a-dedicated-account-per-service). | Service | Category | Guide | | :------------------------------ | :----------------- | :--------------------------------------------------------------------------- | | Datadog | Monitoring | [Connect Datadog](/docs/claude-tag/admins/connections/datadog) | | Sentry | Monitoring | [Connect Sentry](/docs/claude-tag/admins/connections/sentry) | | PagerDuty | Monitoring | [Connect PagerDuty](/docs/claude-tag/admins/connections/pagerduty) | | Linear | Issue tracking | [Connect Linear](/docs/claude-tag/admins/connections/linear) | | Asana | Issue tracking | [Connect Asana](/docs/claude-tag/admins/connections/asana) | | Jira and Confluence | Issue tracking | [Connect Jira and Confluence](/docs/claude-tag/admins/connections/atlassian) | | Notion | Knowledge and docs | [Connect Notion](/docs/claude-tag/admins/connections/notion) | | Google (Drive, Calendar, Gmail) | Knowledge and docs | [Connect Google](/docs/claude-tag/admins/connections/google) | | HubSpot | Go-to-market | [Connect HubSpot](/docs/claude-tag/admins/connections/hubspot) | | Salesforce | Go-to-market | [Connect Salesforce](/docs/claude-tag/admins/connections/salesforce) | | Gong | Go-to-market | [Connect Gong](/docs/claude-tag/admins/connections/gong) | | GitLab | Code | [Connect GitLab](/docs/claude-tag/admins/connections/gitlab) | | BigQuery (custom) | Data warehouse | [Connect BigQuery](/docs/claude-tag/admins/connections/bigquery) | | Snowflake | Data warehouse | [Connect Snowflake](/docs/claude-tag/admins/connections/snowflake) | | Stripe | Billing | [Connect Stripe](/docs/claude-tag/admins/connections/stripe) | | Vercel | Deployments | [Connect Vercel](/docs/claude-tag/admins/connections/vercel) | GitHub is managed through the Claude GitHub App rather than a connection in this list; see [Configure GitHub access](/docs/claude-tag/admins/configure-github). Services marked (custom) have no preset button. Add them with **Custom tool** following their guide. The presets and guides cover common services, not the full set Claude can connect to. Any app with an API can be added as a custom connection or a custom MCP server. See [Connect a custom service](/docs/claude-tag/admins/connections/custom) for the credential types and form fields. ## When a connection fails after setup If Claude says it can't reach a service you connected, start with the checks at the top of [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting). Confirm the connection is in a bundle [attached to the channel's scope](/docs/claude-tag/admins/attach-to-scope), and rerun the test in a new thread, since a session loads its connections when it starts. Two entries on the troubleshooting page cover connection failures directly: * [A connection works in one channel but not another](/docs/claude-tag/admins/troubleshooting#a-connection-works-in-one-channel-but-not-another): bundles attach per scope, so the failing channel's scope is likely missing the bundle * [I hit an authentication error and couldn't finish this turn](/docs/claude-tag/admins/troubleshooting#i-hit-an-authentication-error-and-couldn%E2%80%99t-finish-this-turn): Claude posts that message when its own request fails an authentication check. A connected service's failing credential surfaces as a tool error inside Claude's reply instead # Connect PagerDuty Source: https://claude.com/docs/claude-tag/admins/connections/pagerduty Connect PagerDuty to Claude Tag so it can read incidents and on-call schedules. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting PagerDuty lets Claude read incidents and on-call schedules during incident work from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the PagerDuty plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in PagerDuty Generate a general-access read-only API key. A read-write key lets Claude acknowledge and resolve incidents; grant that only on a private incident-channel scope. Creating a general-access key requires the PagerDuty Admin or Account Owner role; non-admins only see User Token keys, which also work but inherit that user's permissions. PagerDuty's own guide for creating the credential is at [support.pagerduty.com](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key). ## Add the connection to a bundle In the bundle, click **Connect** next to **PagerDuty**. | Field | Value | | :--------------- | :------------------------- | | Claude's API key | The api key from PagerDuty | | Allowed websites | `api.pagerduty.com` | PagerDuty accounts on the EU service region use `api.eu.pagerduty.com` instead. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` PagerDuty appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/watch-monitors): the monitoring use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Salesforce Source: https://claude.com/docs/claude-tag/admins/connections/salesforce Connect Salesforce to Claude Tag so it can read and update CRM records. Covers the connected app to create, the client credential fields, and the host to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Salesforce lets Claude read accounts, contacts, opportunities, and cases (and write, if you grant it) from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. The connection uses the OAuth 2.0 client credentials flow. ## Create the credential in Salesforce Create a connected app (or External Client App) with the client credentials flow enabled, and set a dedicated integration user as the app's run-as user. Salesforce's guide is [Configure a Connected App for the OAuth 2.0 Client Credentials Flow](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_client_credentials_flow.htm\&type=5). You'll need from Salesforce: * The app's **Consumer Key** (the client ID), from its **Settings** tab * The app's **Consumer Secret** (the client secret) * Your org's My Domain host (for example `yourcompany.my.salesforce.com`) Assign the integration user a Permission Set scoped to the objects and fields Claude should reach. Read-only is the recommended starting point. ## Add the connection to a bundle In the bundle, click **Connect** next to **Salesforce**. | Field | Value | | :---------------- | :--------------------------------------------------------------------------------------- | | Client ID | The app's Consumer Key | | Client secret | The app's Consumer Secret | | Token URL | Your org's token endpoint, `https://yourcompany.my.salesforce.com/services/oauth2/token` | | Scopes (optional) | Leave empty unless your app requires specific scopes | | Allowed websites | Your org's host, for example `yourcompany.my.salesforce.com` | The preset prefills Allowed websites with an example host that cannot resolve. Replace it with your org's host before saving, or every request fails. To change the host later, open the **⋮** menu on this connection in the bundle's Credentials tab and choose **Edit**. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude list the five most recently modified Opportunities in Salesforce. ``` Check the integration user's login history in Salesforce Setup to confirm the call landed under that user. ## Related resources * [Pull deal and account state](/docs/claude-tag/users/use-cases/pull-deal-state): what this connection adds # Connect Sentry Source: https://claude.com/docs/claude-tag/admins/connections/sentry Connect Sentry to Claude Tag so it can pull errors and stack traces into threads. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Sentry lets Claude pull errors and stack traces into incident threads from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Sentry plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Sentry Create an internal-integration token in Sentry (Settings → Developer Settings → Internal Integrations) rather than a user auth token; scope it to the projects Claude should read. The token starts with `sntrys_`. Prefer an internal-integration token over a user auth token so access is not tied to a person. Sentry's own guide for creating the credential is at [docs.sentry.io](https://docs.sentry.io/integrations/integration-platform/internal-integration/). ## Add the connection to a bundle In the bundle, click **Connect** next to **Sentry**. | Field | Value | | :------------------ | :---------------------- | | Claude's auth token | The api key from Sentry | | Allowed websites | `sentry.io` | Self-hosted Sentry uses your own hostname instead of `sentry.io`. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Sentry appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/watch-monitors): the monitoring use cases * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Snowflake Source: https://claude.com/docs/claude-tag/admins/connections/snowflake Connect Snowflake to Claude Tag so it can run read-only queries on your warehouse. Covers the dedicated user to create, the access token field, and the host to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Snowflake lets Claude run queries against your warehouse from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. This is an HTTP API connection, not a personal claude.ai connector. ## Create the credential in Snowflake Create a dedicated Snowflake user for the agent with a read-only role scoped to the databases and schemas Claude should query. In Snowsight (Snowflake's web interface), under **Governance & security** and then **Users & roles**, generate a programmatic access token for that user. Tokens expire after 15 days by default, so plan to rotate the credential. Snowflake's guide for programmatic access tokens is at [docs.snowflake.com](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens). The connection authenticates with this token; key-pair authentication is not currently supported. ## Add the connection to a bundle In the bundle, click **Connect** next to **Snowflake**. | Field | Value | | :--------------------------------- | :---------------------------------------------------------------------------- | | Claude's programmatic access token | The programmatic access token from Snowflake | | Allowed websites | Your account's host, for example `yourorg-youraccount.snowflakecomputing.com` | The preset prefills Allowed websites with an example host that cannot resolve. Replace it with your account's host before saving, or every request fails. To change the host later, open the **⋮** menu on this connection in the bundle's Credentials tab and choose **Edit**. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Snowflake appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [What this connection adds](/docs/claude-tag/users/use-cases/answer-data-questions): warehouse questions answered with charts in the thread * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Stripe Source: https://claude.com/docs/claude-tag/admins/connections/stripe Connect Stripe to Claude Tag so it can answer billing and subscription questions. Covers the dedicated account to create, the key fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Stripe lets Claude answer billing and subscription questions from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Stripe plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Stripe Use a restricted key with read-only resource permissions, not your account's full secret key. Consider connecting test mode first. Stripe's own guide for creating the credential is at [docs.stripe.com](https://docs.stripe.com/keys). ## Add the connection to a bundle In the bundle, click **Connect** next to **Stripe**. | Field | Value | | :------------------ | :---------------------------------------------------------------------------- | | Claude's secret key | The secret key from Stripe | | Allowed websites | `api.stripe.com` (preset). To add a different host, use the **Advanced** tab. | The field labeled Claude's secret key accepts a restricted key; the label is the field name, not a key-type constraint. The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Stripe appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Connect Vercel Source: https://claude.com/docs/claude-tag/admins/connections/vercel Connect Vercel to Claude Tag so it can check deployment status and logs. Covers the dedicated account to create, the token fields, and the URL to allow. Connections are added inside an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle). At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open **Access bundles** in the left navigation, click into a bundle (or **Create** one), and go to its **Credentials** tab. Connecting Vercel lets Claude check deployment status and logs from any channel under the bundle's scope. You add it as a connection inside an [Access bundle](/docs/claude-tag/admins/add-connections); the credential belongs to the agent, not to any person. Pair this connection with the Vercel plugin from Anthropic's plugin marketplace so Claude knows how to call the API; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). This is an HTTP API connection, not an MCP server or a personal claude.ai connector. ## Create the credential in Vercel Create the token from a dedicated team member seat, scoped to the team rather than your personal account. Vercel's own guide for creating the credential is at [vercel.com](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token). ## Add the connection to a bundle In the bundle, click **Connect** next to **Vercel**. | Field | Value | | :-------------------- | :--------------------------- | | Claude's access token | The access token from Vercel | | Allowed websites | `api.vercel.com` | The Agent Proxy injects the credential at the network boundary; the model and the sandbox are not given the key. See [how Agent Proxy works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Verify the connection In a channel under the bundle's scope, in a new thread: ```text wrap theme={null} @Claude what can you access from this channel? ``` Vercel appears in the list once the connection is live. New threads pick up the connection on their own; in an existing thread, ask Claude to use the service by name. ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the full credential-type and allowed-hosts reference # Customize Claude Tag Source: https://claude.com/docs/claude-tag/admins/customize Claude Tag is customized per channel and workspace (a scope), not per user. See what admins set in claude.ai, what anyone can change from the channel, and what stays fixed. Claude Tag's behavior is shaped by four layers, each set in a different place: | Layer | What it is | Who sets it | Where | | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Connections** | Credentials for the systems Claude can reach (GitHub, Drive, Datadog, your APIs) | Owner; a [channel manager](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for their assigned channels | [Access bundles](/docs/claude-tag/admins/add-connections), or the channel's Configure page for a channel manager | | **Plugins and skills** | Instructions that teach Claude how to use a tool or follow a process. A plugin bundles one or more [skills](https://code.claude.com/docs/en/skills). | Owner; channel members can add plugins to their channel unless an admin restricts editing | [Bundle Plugins tab](/docs/claude-tag/admins/add-connections#attach-plugins), a [skills repository](/docs/claude-tag/admins/skills-repo), or the channel's Configure page | | **Custom instructions** | Standing guidance read in every session at a scope (team conventions, output formats). Outranks channel memory. | Owner for any scope; channel members for the channel scope, from the [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel) | [Per-scope instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions) | | **Channel memory** | Facts Claude saves while working in a channel | Anyone in the channel | By [telling Claude](/docs/claude-tag/users/memory) | Connections and plugins decide what Claude *can do*; instructions and memory shape *how it does it*. ## Settings admins control Access and organization-wide behavior are set at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), per scope (a scope is a channel, a workspace, or your whole organization), so the same agent can work differently in different channels. Most controls below are Owner-only. | Setting | What it does | More | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | | Custom instructions | Standing guidance read in every session on a scope, like team conventions. Outranks channel memory. | [Add custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions) | | Respond automatically | Whether Claude replies to a channel's messages without an @-mention. **Respond automatically** exists only on channels, not on workspaces or your whole organization. Channel members can change it too, from Slack or the channel's Configure page. | [Turn automatic replies on or off](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off) | | Plugins | Bundles of skills that teach Claude how to use a specific tool | [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins) | | Connections | Which systems it can reach from each channel | [Add connections](/docs/claude-tag/admins/add-connections) | | Default model | Which Claude model handles sessions in a scope | [Choose the model for a scope](#choose-the-model-for-a-scope) | | Auto mode allow rules | Actions pre-approved in a scope's sessions that Claude's permission checker would otherwise flag or stop | [Auto mode allow rules](#auto-mode-allow-rules) | | Environment | Which cloud environment a scope's sessions run in | [Configure the environment for a scope](#configure-the-environment-for-a-scope) | | Claude Tag version | Which generation answers (New, Legacy, or Off) in a scope. On the Team plan, a single [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) replaces it. | [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope) | ### Channel connections are separate from personal connectors An Owner configures Claude's connections, plugins, and skills, and they apply per scope. They are separate from the connectors, skills, or MCP servers an individual user has set up in their own claude.ai or Claude Desktop account. A user's personal connectors are not part of a channel's configuration, and the channel's connections are not listed among that user's personal connectors in claude.ai. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can use a user's personal connectors in a channel for that user's own tasks, after the user allows it. That work runs with the user's permissions and is recorded under their name. Projects in claude.ai are separate too. Claude doesn't read a Project's instructions or knowledge in Slack, and a channel can't be pointed at a Project. Put standing guidance for a channel in its [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions). To give Claude access to a tool that is not in the built-in connection list, including a custom MCP server, see [add a custom connection](/docs/claude-tag/admins/connections/custom). ## Change behavior from the channel Everything in the table below is open to channel members, with no admin involved. | To change | Say something like | More | | :----------------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------ | | How Claude formats output | "remember for this channel: post reports as a table" | [Memory](/docs/claude-tag/users/memory) | | How chatty Claude is | "ask before posting anything longer than a screen" | [Memory](/docs/claude-tag/users/memory) | | When Claude follows a thread | "stay quiet in this thread unless someone tags you" | [Control when Claude Tag responds](/docs/claude-tag/users/when-claude-responds) | | What Claude does on a schedule | "every morning at 9, post a digest of open threads" | [Set up routines](/docs/claude-tag/users/proactivity) | | What Claude remembers | "what do you remember about this channel?" then correct it | [Memory](/docs/claude-tag/users/memory) | Changes in the table above are saved to channel memory; verify one stuck by asking what it remembers. Members can also tailor how Claude works in the channel from its Configure page on claude.ai. The **Configure** link in the footer of any Claude reply in the channel opens it, and if a member sends [`@Claude !configure`](/docs/claude-tag/users/commands#get-the-link-to-configure-a-channel) in the channel, Claude replies with a link to it. Anyone in the channel who is also a member of your Claude organization can edit settings for that channel there, unless an admin has [restricted editing to admins](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions). The **Channel instructions** field on that page holds standing guidance that outranks memory. See [configure Claude for a channel](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). The Configure page also shows the channel's resolved access. Its **Tools and access** tab lists the channel's resolved connections and any allowed domains. Members can see those lists but not change them there. The same tab's **Plugins** card lists the plugins available to Claude in the channel; members can add plugins there unless an admin has [restricted editing to admins](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions). The card groups plugins **Added by your admin**, which members can't remove, separately from plugins **Added by members**, which members can remove. The Configure page's **Routines** tab lists the channel's [routines](/docs/claude-tag/users/proactivity) with each one's schedule, status, and last run. On the Enterprise plan, an Owner can name [channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for a channel. They set the channel's default model, repositories, connections, and plugins from the same page. ## Choose the model for a scope Each scope carries a **Default model** setting in its **Advanced** section, alongside the [environment](/docs/claude-tag/concepts/glossary#environment) and guest controls. It sets the model new channel sessions in that scope start on; the options are drawn from the models available to your organization, such as Opus and Sonnet models. A scope without its own setting inherits from its parent, and a channel's setting overrides its workspace's. The **Inherit** option shows which model the scope resolves to. To keep sessions on a model you chose, set a specific model at the organization scope rather than leaving the setting unset; every scope without an override then follows it. The setting applies to new sessions; threads already underway keep the model they started with. The footer of each Claude reply in Slack names the model that handled it, so you can confirm what a scope is running. Channel members can also change the model from Slack. Asking Claude in a thread switches that thread, and asking it to make a model the channel default changes what new threads in the channel start on, unless the scope's [Channel member edits](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) setting is **Block**. See [choose the model Claude Tag uses](/docs/claude-tag/users/models). ### Models your organization allows Claude Tag's model lists come from the models your organization makes available for Claude Code, set in the Claude admin console, leaving out any that Claude Tag doesn't support. A model you see in Claude Code can be absent in Slack for that reason. The allowed list applies in two places. * **Model lists in Slack.** The models Claude offers when someone asks it to switch, and the model selector for direct messages, show only allowed models. Claude declines a request to switch to a model outside the list. * **Configured defaults.** If your organization also enforces the policy on defaults and a workspace or channel's **Default model** isn't allowed by your organization's Claude Code model policy, Claude declines to start the session and posts a notice in the thread asking the requester to contact an admin. A model excluded by your organization's plan entitlements works differently. Claude starts the session on a fallback model the plan includes, and declines only when the plan excludes every fallback. The footer of the first reply names the model that served it, so check there to see which model the session started on. A change to the allowed list applies to new sessions, like a change to the **Default model**; a thread already underway keeps its model until someone in it asks Claude to switch. ## Configure the environment for a scope Claude runs every channel session in a sandbox that starts with a standard set of tools. When a channel's work needs something that sandbox doesn't have, such as a language runtime, a database client, a set of environment variables, or broader web access, give the channel an environment. An environment is an [organization-shared cloud environment](https://code.claude.com/docs/en/cloud-environments#organization-shared-environments): you create it once, then choose it on a scope, meaning a channel, a workspace, or **Default Slack access**. Both steps take an Owner; a [channel manager](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) can't change a channel's environment. ### Decide what goes in the environment An environment carries a setup script, environment variables, and a network access level. Not everything a channel needs belongs there, so match each need to its place before you create one: | What the channel needs | Where to put it | | :------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A tool installed before Claude starts, such as a runtime or a database client | The environment's setup script, a Bash script whose installs are on disk before Claude starts work | | A value every session should see, such as a deployment target or a feature flag | The environment's environment variables, as `KEY=value` pairs, one per line | | Web access without a credential | The environment's network access level; see [broad web access through the environment](/docs/claude-tag/admins/add-connections#broad-web-access-through-the-environment) | | An API key, token, or other credential | A [connection](/docs/claude-tag/admins/add-connections), never an environment variable | | Setup for one repository, such as installing its dependencies | That repository's `CLAUDE.md`; see [install project dependencies](/docs/claude-tag/admins/configure-github#install-project-dependencies) | Keep credentials out of environment variables because every session on the environment reads them and Claude can print them. There is no separate secrets store. A connection stores the credential outside the sandbox and attaches it to matching requests at the network layer, so Claude uses the service without holding the raw value. [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) describes how. A connection also travels with the access bundle, so you choose channel by channel which sessions can use it. Repository-specific setup goes in `CLAUDE.md` so the people who maintain the repository keep it current. Claude reads it when it starts work in that repository. ### Create the environment and choose it on a scope Creating the environment and choosing it on a scope happen on two different admin pages. Choose it on a channel to change only that channel's sessions, on a workspace to cover every channel in the workspace where you haven't chosen one, or on **Default Slack access** to cover every workspace. From the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings), add an [organization-shared environment](https://code.claude.com/docs/en/cloud-environments#organization-shared-environments) and fill in its setup script, environment variables, and network access level. The picker is at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) > **Claude Tag's access** > **Slack** > the scope (**Default Slack** is the organization-wide scope) > **Advanced** > **Environment**. Pick the environment there. Start a fresh thread in the channel and ask Claude to use what you added, such as running the tool your setup script installed. Threads already underway keep the environment they started on, so an existing thread won't show the change. ### Which environment a channel's sessions use When a session starts, Claude uses the first environment it finds, in this order: 1. The channel's **Environment** setting 2. The workspace's **Environment** setting 3. The **Environment** setting on **Default Slack access** 4. The [organization's default environment](https://code.claude.com/docs/en/cloud-environments#the-default-environment), which an Owner chooses under **Cloud sessions** at [`claude.ai/admin-settings/claude-code`](https://claude.ai/admin-settings/claude-code) If you haven't chosen an environment on a scope, its picker shows **Organization default**, but sessions there may still run on an environment you chose on the workspace or on **Default Slack access**. In a channel where Claude runs with [channel-only access](/docs/claude-tag/admins/restrict-access#how-channel-only-works) because a guest is present, sessions run on the standard environment regardless of these settings. If a channel's sessions aren't on the environment you expect, see [channel sessions use the wrong environment](/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one). ## Auto mode allow rules Sessions run in [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode), where Claude's permission checker reviews each action Claude is about to take and can flag or stop it. When you add an auto mode allow rule to a scope, you pre-approve one action in that scope's sessions, so Claude runs it there without the checker stopping it. The checker keeps reviewing every other action. A rule is a plain sentence that describes work you approve in the scope, such as "Deploying to our staging cluster from a session in this channel is a normal, approved workflow." To add one: 1. On [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), open the **Slack** tab under **Claude Tag's access** and find the scope you want to change (the organization-wide **Default Slack** row, a workspace, or a channel). The **Default Slack** row opens as **Default Slack access**. 2. Open the scope's **Advanced** section and find **Auto mode allow rules**, below the [**Default model**](#choose-the-model-for-a-scope) setting. 3. Select **Add rule** and write the rule as one plain sentence. The rules list has three properties: * **Limits:** a scope holds up to 50 rules, and each rule can be up to 1,024 characters * **Inheritance:** rules you set on a workspace or on [Default Slack access](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit) (the organization-wide root) carry down to the channels beneath, the way [custom instructions](/docs/claude-tag/admins/attach-to-scope#custom-instructions) stack. A channel's own rules add to those and never replace them, so put a rule on a single channel's scope to pre-approve an action there without changing any other channel. * **Access:** you edit the list with the same admin access as the scope's other **Advanced** settings Once you add an allow rule, Claude runs the actions it names in every channel the scope covers without anyone approving them in the moment. Keep each rule narrow: name the tool, the action, and the environment it allows, and put rules that unlock sensitive systems on the narrowest scope that needs them. ## Settings no one can change * The Claude app's name, @-handle, and avatar in Slack are the same in every workspace; there is no rename or rebrand setting. ## Related resources * [Settings map](/docs/claude-tag/concepts/settings-map): every settings surface, including spend limits and personal connectors * [What Claude Tag remembers](/docs/claude-tag/users/memory): how channel instructions are stored, shared, and corrected * [Good habits for working with Claude Tag](/docs/claude-tag/users/good-habits): phrasings that make recurring output consistent * [How agent identity works](/docs/claude-tag/concepts/agent-identity): why access is set per channel # Connect an authorization server Source: https://claude.com/docs/claude-tag/admins/federated-access/authorization-server Let Claude exchange a short-lived identity token for an access token from an OAuth 2.0 authorization server you run, then call your APIs with it. Covers what your token endpoint receives and must check, what it returns, and how to register it in the console. Authorization servers are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Authorization servers** section. Connecting a server needs an organization Owner, or an admin with full Claude Tag management permission. With an authorization server connection, Claude presents a short-lived identity token to an OAuth 2.0 authorization server you run, receives one of your access tokens in return, and calls your APIs with it. No long-lived credential for your systems is stored in Claude, and [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) holds each access token only until it expires. The identity token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your server decides whether to issue a token for it. Choose this when you run an authorization server that issues tokens for your APIs. If your own service will verify the identity token on every request instead, [connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway). If a vendor's API gave you a private key to sign assertions with (Salesforce, for example), use the [OAuth 2.0 JWT bearer](/docs/claude-tag/admins/connections/custom#oauth-2-0-jwt-bearer) credential type instead; the console labels this page's connection **Authorization server**. Two terms recur on this page. The **subject check** is what your server does to every identity token, confirming it belongs to your organization. The **connection check** is the probe the console runs when a gateway is connected; it doesn't run for token endpoints. ## Before you begin * You're an organization Owner, or an admin with full Claude Tag management permission. * Your authorization server's token endpoint is reachable from the internet over HTTPS at an address with a domain name, such as `https://auth.example.com/oauth2/token`. The console accepts an address that: * is at most 256 characters * may have a path, with no spaces or special characters in it * has no port number (the console drops `:443`), query, fragment, or sign-in details * isn't an IP address, a private-network name, an Anthropic-owned host, or a cloud token-exchange host * The token endpoint is on a different host from the APIs Claude will call with the returned token, for example `auth.example.com` and `api.example.com`. * Your server can reach `https://identity.anthropic.com` to fetch Anthropic's signing keys. * An organization can register up to 5 [gateways](/docs/claude-tag/admins/federated-access/connect-a-gateway), and a token endpoint counts as one. ## Copy the values from the console In **Authorization servers**, click **Connect an authorization server**, enter your token endpoint in the **Token endpoint** field, enter your authorization server's issuer identifier in the **Issuer URL** field (or leave it empty if your server requires the token endpoint URL as the audience), and copy the **Issuer**, **JWKS URL**, **Audience**, and **Subject prefix** rows from the **Set your authorization server to accept these values** card. Then click **Cancel**; you register the endpoint after configuring the server. | Value | What to configure | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer | `https://identity.anthropic.com/agents`, matched exactly. The OpenID Connect (OIDC) discovery document is at `https://identity.anthropic.com/agents/.well-known/openid-configuration`. | | JWKS URL | The JSON Web Key Set (JWKS) named by `jwks_uri` in the discovery document, `https://identity.anthropic.com/agents/jwks.json`. Accept ES256 only. Select the key by `kid`, and refetch the JWKS on an unknown `kid` before rejecting the token. | | Audience | Your authorization server's issuer identifier, as you enter it in the **Issuer URL** field when you connect the server, for example `https://auth.example.com`. It must be an HTTPS URL on the same host as the token endpoint. If your server requires the token endpoint URL as the audience instead, leave **Issuer URL** empty and the audience is the token endpoint address as the console stores it (the host lowercased, a bare trailing slash dropped, the rest kept as entered). Either way, copy the **Audience** row into your verifier rather than typing it. The `aud` claim is a JSON array with one element. Accept only this exact value, not any address on your host. | | Subject prefix | `wimse://identity.anthropic.com/org//agent/`. Every token's `sub` claim starts with this prefix and ends with one agent's ID; see the [subject](/docs/claude-tag/admins/federated-access/token-reference#subject) format. Agent IDs aren't shown in the console; your server learns them from the tokens it receives, and they change, for example when a Slack channel is deleted and recreated. | | Tenant | Your organization ID, the value between `/org/` and `/agent/` in the **Subject prefix**, carried in every token as the `tenant` claim. | | Expiry | Tokens expire 10 minutes after they're issued. Check `exp`, allowing up to 60 seconds of clock skew. | ## Configure the authorization server Claude sends a standard JWT bearer grant ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)) to the token endpoint as an HTTPS `POST` with `Content-Type: application/x-www-form-urlencoded` and `Accept: application/json`. The form body contains these fields: ```text wrap theme={null} grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=[&resource=][&scope=] ``` The `resource` ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)) and `scope` fields are present only if you set them when connecting the server. No `client_id` or `client_secret` is sent. Register one client for Anthropic's issuer that accepts this grant without client authentication; the subject check is what keeps other organizations out. The request doesn't follow redirects, and the exchange must complete within about 10 seconds. Your server must: * Verify the token with a standard JWT or OIDC library configured with the issuer, JWKS URL, audience, and expiry from [Copy the values from the console](#copy-the-values-from-the-console). * Check the subject. Where your use case allows, accept only the full subjects of your own agents, and update that list when a Slack channel is deleted and recreated. At minimum, reject every token whose `sub` doesn't start with your **Subject prefix**, or equivalently pin `iss` and reject every token whose `tenant` isn't your organization ID. This check is required because every organization's tokens come from the same issuer; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). The console's connection check doesn't run for token endpoints, so nothing tests this check for you. * Decide what the agent may do, for example from the agent ID at the end of `sub`, and issue an access token for it. Tokens may carry additional opaque claims; ignore claims you don't recognize. * Return `200` with a JSON body: `access_token`, `token_type` (`Bearer`, compared without regard to case, and may be omitted), and `expires_in` in seconds. Each grant carries a fresh token with a new `jti`, so your server may reject a repeated `jti`. Claude caches the access token when `expires_in` is between 5 minutes and 1 day, inclusive, and reuses it until about 5 minutes before it expires (for tokens shorter than 10 minutes, until half their lifetime has passed). The cache is per channel, so one channel's token is never used for another, and your server may still see more than one grant per channel within a token's lifetime. An `expires_in` outside that range, or none, makes Claude exchange a new token on every request to your APIs. To refuse a grant, return a standard OAuth 2.0 error response, such as `400` with `{"error": "invalid_grant"}`. Any non-`2xx` status is a refusal. Claude reads only the `error` code and never shows `error_description` to anyone, so log the reason on your side. After a refusal, or any other failed exchange, the agent's request fails with an error, and Claude doesn't try the exchange again for a few seconds; your token endpoint's `Retry-After` header on a `429` or `503` response extends that wait. If one of your APIs answers `401`, or `403` with a `WWW-Authenticate: Bearer` challenge whose error is `invalid_token`, Claude drops the cached token (unless it was just issued) and exchanges a new one on the next request. A plain `403` doesn't trigger this. ## Register the endpoint and connect the server In **Authorization servers**, click **Connect an authorization server**. In the **Token endpoint** field, enter the full address starting with `https://`, for example `https://auth.example.com/oauth2/token`. In the **Issuer URL** field, enter your authorization server's issuer identifier, the `iss` value it uses, for example `https://auth.example.com`. That value is the token's audience, and it must be an HTTPS URL on the same host as the token endpoint. Leave the field empty only if your server requires the token endpoint URL as the audience. Then the **Token endpoint** address is the audience. The **Audience** row of the card shows which one will be sent. Select the checkbox labeled **This authorization server checks that each token's subject belongs to your organization**. The **Register server** button stays disabled until you do. The checkbox is your confirmation that the server makes the subject check described under [Configure the authorization server](#configure-the-authorization-server), and a server that doesn't must not be connected. Then click **Register server**. The dialog notes that the automatic connection check doesn't run for token endpoints. The endpoint is registered as a gateway with the check marked **Skipped**, and the dialog moves to the second step. If you close the dialog at that point, the endpoint stays registered and counts toward the limit. To continue later, click **Connect an authorization server** again, enter the same address, and select the checkbox again, which returns you to the second step. Don't use **Add to bundle** on the endpoint's row in the **Gateways** table; that would connect the address as a gateway, after which the server can't be connected. Optionally enter a **Resource**, the API the returned token should be scoped to as an absolute URI (for example `https://api.example.com`), and a **Scope**, space-separated scopes to request. In **Allowed API hosts**, add the hosts Claude may call with the returned token, for example `api.example.com`. A wildcard as the leftmost label matches any subdomain; an entry or wildcard that covers the token endpoint's host is rejected. Then choose a bundle from the **Access bundle** list (or click **New bundle**, enter a **Bundle name**, and click **Create bundle**) and click **Connect server**. This creates a [connection](/docs/claude-tag/admins/add-connections) in that bundle, labeled **Authorization server** on its **Credentials** tab, with the API hosts under **Allowed hosts**. Agent Proxy attaches the access token as an `Authorization: Bearer` header to every request Claude makes to those hosts. A token endpoint can be connected once in your organization, in one bundle; to use it in several scopes (workspaces or channels), attach that bundle to each. The **Authorization servers** table lists each server by its **Token endpoint**, with its **Access bundle**, its **Allowed hosts**, when it was **Added**, and a **Remove** action. The endpoint also appears in the **Gateways** table with its check marked **Skipped** and a note that a connected authorization server uses it. ## Let agents use the APIs Claude uses the connection in channels whose scope has the bundle attached. [Attach the bundle to a workspace or channel](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) if it isn't attached already. Claude also needs to know what the APIs are for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions): ```text wrap theme={null} The internal orders API is at https://api.example.com; see GET /openapi.json for what it offers. Authentication is already set up. ``` The exchange happens in Agent Proxy, outside Claude's sandbox, so neither the identity token nor your access token is visible to Claude, and Claude can't perform the exchange itself. New threads pick up the connection on their own. In a thread already running, ask Claude to use the API and name its host. If Claude still can't, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) at the channel's top level (not inside a thread) to start a fresh session with your organization's current configuration. ## Verify the connection In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to make a small read: ```text wrap theme={null} @Claude call GET /openapi.json on https://api.example.com and tell me what the API offers. ``` Then check your authorization server's logs for a JWT bearer grant whose token has your **Subject prefix**, and your API's logs for a request carrying the access token it issued. If the grant was refused, your server's own error is the reason; Claude sees only that the request failed. See [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows. ## Remove the server In the **Authorization servers** table, click **Remove** in the server's row, then **Remove server** in the confirmation. Claude stops using the connection within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. An access token your server already issued stays valid with your server until it expires, and Agent Proxy discards it with the connection. The endpoint stays registered as a gateway, so to free its place in the limit, also click **Remove** in its row of the **Gateways** table. To change the address, do both removals, then connect the server again with the new address. ## Common errors Five messages come up while connecting: * **"The issuer URL must be an https URL on the same host as the token endpoint. Leave it empty to use the token endpoint as the audience."**: the **Issuer URL** value is not an HTTPS URL on the token endpoint's host. Enter the issuer identifier your server uses there, or clear the field. * **"This token endpoint is already connected in the bundle"**: the server already has its one connection. [Attach that bundle to the scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. * **"This organization has reached its limit of 5 registered gateways, which includes token endpoints"**: remove an unused row from the **Gateways** table first. * **"The allowed hosts can't include the token endpoint's host"**: an **Allowed API hosts** entry, or a wildcard in it, covers the token endpoint's host. Put the token endpoint on a different host from the APIs. * **"That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first."**: the token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your Access bundles. Enter the server's own addresses, or delete that gateway's connection from its bundle first. For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting). ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model * [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a connection applies * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation * [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): the alternative where your own service verifies the token on every request * [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type # Connect an AWS role Source: https://claude.com/docs/claude-tag/admins/federated-access/aws Let Claude sign in to an IAM role in your AWS account with a short-lived identity token instead of stored access keys. Covers the identity provider and trust policy to create in AWS, how to connect the role in the console, and how to verify the connection in CloudTrail. AWS roles are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Cloud roles** section. Connecting a role needs an organization Owner, or an admin with full Claude Tag management permission. With an AWS role connection, Claude signs in to an IAM role in your AWS account with a short-lived identity token and calls AWS with the role's permissions. No access key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your role's trust policy decides which tokens to accept. If someone else manages your AWS account, give them the values from the console and the trust policy below; the console steps need a Claude Tag admin. ## Before you begin * You're an organization Owner, or an admin with full Claude Tag management permission. * You can create an IAM identity provider and an IAM role in an AWS account in the standard AWS partition. Roles in AWS GovCloud (US) and AWS China can't be connected. * You know which AWS service hosts Claude will call, for example `s3.us-west-2.amazonaws.com` and `*.s3.us-west-2.amazonaws.com` for S3 in one region. ## Copy the values from the console In **Cloud roles**, click **Connect an AWS role** and copy the **Issuer**, **Audience**, and **Subject prefix** rows from the **Set the role's trust policy to accept these values** card. Then click **Cancel**; you connect the role after creating it in AWS. | Value | What it is | | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer | `https://identity.anthropic.com/agents`. The URL of the identity provider you create in AWS, including the `/agents` path. | | Audience | `sts.amazonaws.com`. The same for every organization, so it can't identify yours. | | Subject prefix | `wimse://identity.anthropic.com/org//agent/`. Every token's subject starts with this prefix and ends with one agent's ID. The trust policy must require at least this prefix. | ## Create the identity provider and role in AWS In the AWS account that owns the role, create an IAM OpenID Connect (OIDC) identity provider with the provider URL `https://identity.anthropic.com/agents` and the audience `sts.amazonaws.com`. Include the `/agents` path. A provider created with the bare hostname, or with any other path, makes every sign-in fail later with an invalid-token or provider error from AWS. You don't need to supply a certificate thumbprint, because AWS verifies the provider's certificate itself. To confirm the provider, run `aws iam get-open-id-connect-provider --open-id-connect-provider-arn ` and check that `Url` is `identity.anthropic.com/agents` (AWS stores the URL without `https://`) and `ClientIDList` contains `sts.amazonaws.com`. Create an IAM role with the trust policy below. Replace the account ID with yours (the rest of the provider ARN is the same for every account), and replace the `sub` value with your **Subject prefix** followed by `*`. ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/identity.anthropic.com/agents" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "identity.anthropic.com/agents:aud": "sts.amazonaws.com" }, "StringLike": { "identity.anthropic.com/agents:sub": "wimse://identity.anthropic.com/org/org_01Hx7rQkPzT9sN3mVbJw2eYd/agent/*" } } } ] } ``` Keep both conditions. Because every organization's tokens come from the same issuer with the same audience, the `sub` condition is the only thing that limits the role to your organization; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). The wildcard replaces only the agent ID at the end. Never put a wildcard before `/agent/`. `StringEquals` on the prefix never matches, so keep the prefix condition under `StringLike`. Both condition keys start with `identity.anthropic.com/agents:` (the issuer without `https://`). The prefix condition is the minimum, and it admits every agent in your organization. Where your use case allows, pin the role to specific agents instead, which is the strongest form: use `StringEquals` on `identity.anthropic.com/agents:sub` with one full subject, or a JSON array of full subjects. The console doesn't show agent IDs, so you learn a subject from CloudTrail after a first sign-in under the prefix condition. Agent IDs change when a Slack channel is deleted and recreated, so update the policy when that happens. Attach a least-privilege permissions policy to the role for the work Claude will do. The check under [Verify the connection](#verify-the-connection) needs no permissions. Each sign-in gives Claude temporary credentials that last 1 hour, the AWS default. Claude doesn't ask for a different length, and the role's maximum session duration setting doesn't change this. To cut off access before they expire, use the role's **Revoke active sessions** option in IAM or change its permissions. ## Connect the role in the console In **Cloud roles**, click **Connect an AWS role**. In the **Role ARN** field, enter the role's ARN, for example `arn:aws:iam::123456789012:role/ClaudeTag`. The role's name is used as the connection's name. The **Allowed AWS hosts** field starts with `*.amazonaws.com`, which lets Claude use the role with any AWS service. Keep that entry for the first verification, then narrow the list to the hosts Claude needs from the connection's [**Edit connection** dialog](/docs/claude-tag/admins/add-connections#set-allowed-websites) on the bundle's **Credentials** tab. A wildcard covers subdomains only: `*.s3.us-west-2.amazonaws.com` matches `example-reports.s3.us-west-2.amazonaws.com` but not `s3.us-west-2.amazonaws.com`. The AWS CLI and SDKs use both forms for S3, so list both the plain host and the wildcard for each region, and for `us-east-1` also `*.s3.amazonaws.com`, the older global S3 address some tools still use there. Every host must end in `.amazonaws.com`. The sign-in itself goes to the AWS Security Token Service (STS) from Anthropic's side and doesn't need an entry here. Select the checkbox labeled **The role's trust policy requires the subject prefix shown above**. The **Connect role** button stays disabled until you do. Select it only if the trust policy pins `sub` to one or more full subjects under your **Subject prefix**, or to your prefix followed by `*` under `StringLike`, as described under [Create the identity provider and role in AWS](#create-the-identity-provider-and-role-in-aws). Choose a bundle from the **Access bundle** list, or click **New bundle**, enter a **Bundle name**, and click **Create bundle**. Then click **Connect role**. This creates a [connection](/docs/claude-tag/admins/add-connections) in that bundle, labeled **AWS role** on its **Credentials** tab, with the hosts you entered under **Allowed hosts**. A role can be connected in one bundle only; to use it in several scopes (workspaces or channels), attach that bundle to each. The **Cloud roles** table has **Role**, **Access bundle**, **Allowed hosts**, **Added**, and **Actions** columns. Each connection's name appears under **Role** with the role's ARN and an **AWS role** chip beneath it, and **Remove** is under **Actions**. ## Let agents use the role Claude uses the role in channels whose scope has the bundle attached. [Attach the bundle to a workspace or channel](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) if it isn't attached already. Claude also needs to know what the role is for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions): ```text wrap theme={null} Use the AWS CLI to read the S3 bucket example-reports in us-west-2. AWS access is already set up. ``` Claude calls AWS with `curl`, an AWS SDK, or the AWS CLI, as with an [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom#aws-sigv4). [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) signs each request at the network boundary with the role's temporary credentials, so the sandbox never holds them. New threads pick up the connection on their own. In a thread already running, ask Claude to use AWS. If Claude still can't, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) at the channel's top level (not inside a thread) to start a fresh session with your organization's current configuration. ## Verify the connection In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to run a connectivity check. The check is Claude's own request to `sts.amazonaws.com`, so keep `*.amazonaws.com` under the connection's **Allowed hosts** for this check, or add `sts.amazonaws.com` if you already narrowed the list. The sign-in itself needs no entry there. After the check passes, remove `sts.amazonaws.com` again if you added it, or narrow the wildcard. While it is listed, Claude can send any STS request signed with the role's credentials. If the role is allowed to assume another role, the credentials AWS returns are readable in Claude's sandbox. The call needs no permissions policy on the role. Send Claude this prompt: ```text wrap theme={null} @Claude Connectivity check for this channel's AWS connection. Please run exactly: curl -sS -o /tmp/resp.txt -w '%{http_code}' 'https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15' and tell me the HTTP status code it prints and, only if it is not 200, the first 200 characters of /tmp/resp.txt. ``` A status of 200 means the sign-in worked. Then check CloudTrail in the AWS account for an `AssumeRoleWithWebIdentity` event on your role whose identity provider names `identity.anthropic.com/agents`. Claude signs in at the global STS endpoint, `sts.amazonaws.com`, so the event is recorded in the US East (N. Virginia) region; look there or in a multi-region trail, and allow a few minutes for it to appear. The role session name is an opaque ID for the Claude session that signed in. Claude may reuse one sign-in's credentials for most of the hour across threads in the same channel, so not every request produces a sign-in event. After AWS denies a request, Claude signs in again on the next one. If Claude reports that the request was refused, CloudTrail usually shows why. * No sign-in event at all means the request never reached AWS, most often because the host isn't in the connection's **Allowed AWS hosts**. * An invalid-token or provider error on the sign-in usually means the identity provider's URL doesn't exactly match the issuer, `https://identity.anthropic.com/agents`. * `AccessDenied` on the sign-in means the trust policy didn't accept the token. Check the `sub` condition and the condition-key prefix. * A denied action after a successful sign-in means AWS denied the action. Check the role's permissions policy first, then any bucket policy, permissions boundary, or service control policy. See [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows. To disconnect a role, click **Remove** in the role's row of the **Cloud roles** table, then **Remove role** in the confirmation. Claude stops using the role within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. Credentials from an earlier sign-in stay valid in AWS until they expire, within 1 hour; they're held only by Agent Proxy, never by Claude's sandbox. ## Common errors Two messages come up while connecting: * **"This role is already connected in the bundle"**: the role already has its one connection. [Attach that bundle to the scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. * **"Enter a role ARN like `arn:aws:iam::123456789012:role/ClaudeTag`"**: the **Role ARN** field rejected the value, most often because the ARN is in the AWS GovCloud (US) or AWS China partition, which can't be connected. For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting). ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model * [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a role connection applies * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation * [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type * [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom#aws-sigv4): the stored-key alternative, and how Claude signs AWS requests # Connect a gateway Source: https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway Connect a gateway you run so Claude Tag can call your internal services with a short-lived identity token instead of a stored credential. Covers what the gateway must check, how to register it in the console, and how to verify the connection. Gateways are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Gateways** section. Connecting a gateway needs an organization Owner, or an admin with full Claude Tag management permission. A gateway is a service you run between Claude and your internal systems. Every request Claude sends it carries a signed identity token naming your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel). The gateway checks the token, decides what that agent may do, and forwards the request with your own credentials. No long-lived credential for your systems is stored in Claude. Two terms recur on this page. The **subject check** is what your gateway does to every token, confirming it belongs to your organization. The **connection check** is what the console does once, when you connect the gateway, confirming that your gateway performs the subject check. ## Before you begin * You're an organization Owner, or an admin with full Claude Tag management permission. * The gateway has a public HTTPS address with a domain name, such as `https://gateway.example.com`, on the standard HTTPS port. The console rejects a path, port, trailing slash, IP address, private-network name, Anthropic-owned host, or cloud token-exchange host. * The gateway can reach `https://identity.anthropic.com` to fetch Anthropic's signing keys. * If you start from Anthropic's [sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample) (Python, Apache 2.0), terminate TLS in front of it, because it listens on plain HTTP, and set its `audience` to the public address you register. * An organization can register up to 5 addresses, counting gateways and authorization-server token endpoints together. ## Copy the values and deploy the gateway In **Gateways**, click **Connect a gateway** and copy the **Issuer**, **JWKS URL**, **Subject prefix**, and **Control subject** rows from the **Set your gateway to accept these values** card, which appears as soon as the dialog opens and doesn't depend on the address. Then click **Cancel**; you register the gateway after deploying it. Claude authenticates with a JSON Web Token (JWT) in the `Authorization: Bearer` header of every request. It reuses one token for a session's requests for about five minutes, or until your gateway answers 401, and then requests a new one, so don't treat a repeated `jti` as a replay. Verify it with a standard JWT or OpenID Connect (OIDC) library configured with these values. | Value | What to configure | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer | `https://identity.anthropic.com/agents`, matched exactly. The OIDC discovery document is at `https://identity.anthropic.com/agents/.well-known/openid-configuration`. | | Signing keys | The JSON Web Key Set (JWKS) named by `jwks_uri` in the discovery document, `https://identity.anthropic.com/agents/jwks.json`. Accept ES256 only. On an unknown key ID, refetch the key set before rejecting the token. | | Audience | Your gateway address as the console stores it (the console converts the host to lowercase), for example `https://gateway.example.com`. The `aud` claim is a JSON array with one element, so use the library's audience option. | | Subject prefix | `wimse://identity.anthropic.com/org//agent/`, copied from the dialog. Every token's `sub` claim names one agent in one organization. | | Tenant | Your organization ID, the value between `/org/` and `/agent/` in the **Subject prefix**, carried in every token as the `tenant` claim. | | Control subject | A reserved test identity in your organization, copied from the dialog. Anthropic uses it only for the connection check. | | Expiry | Tokens expire 10 minutes after they're issued. Check `exp`, allowing up to 60 seconds of clock skew. | The subject check is yours to implement, and it's required, because every organization's tokens come from the same issuer; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). Implement the check in one of two forms, strongest first: * Accept only an explicit list of your own agents' full subjects, when your use case allows it. The sample gateway does this by default and offers the prefix form below as an opt-in setting. Agent IDs change when a Slack channel is deleted and recreated, so you update the list when that happens. * Otherwise, reject every token whose `sub` doesn't start with your **Subject prefix**, or pin `iss` and `tenant` together. The `tenant` claim is your organization ID, the same value the subject carries between `/org/` and `/agent/`, so checking it is the subject check in claim form. This is the minimum. For the connection check, the gateway also needs a route at the address itself, with no path, that answers an empty `POST` by verifying the token and reporting whether the subject is accepted (2xx if it is, 401 or 403 if not) and does nothing else. Agents normally call a path; the root route exists for the connection check, and an agent that calls it gets the same accept-or-reject answer. The sample gateway calls this its readiness route. The check sends it two requests, and any other status from either one fails the check: * A token valid in every other way (your audience, Anthropic's issuer and signature, unexpired) whose subject isn't your organization. The gateway must answer 401 or 403. Only the `tenant` or subject check can reject it. * A token for the **Control subject**. The gateway must answer 2xx. A gateway that lists exact subjects must include the control subject in its list, and a prefix or `tenant` check accepts it on its own, because it belongs to your organization. Either way, map it to no service. With the sample gateway, set `audience` in `config.yaml` to your registered address and add a `principals` entry for the **Control subject** with `allowed_services: []` (the example config ships with a placeholder organization ID). By default the sample accepts only the subjects listed under `principals`; an agent that isn't listed gets 403, and the sample logs its full subject so you can add it. To accept every agent in your organization instead, add an `organization_principals` entry keyed by your **Subject prefix**. The control subject still needs its exact `principals` entry either way. Never forward the Claude Tag token downstream; replace the `Authorization` header with your own credential. ## Register the gateway in the console In **Gateways**, click **Connect a gateway**. In the **Gateway address** field, enter the host only, in lowercase, starting with `https://`, for example `https://gateway.example.com`. This address is the token's audience. Select the **This gateway checks that each token's subject belongs to your organization** checkbox. The **Run check and connect** button stays disabled until you do. Select it only if the gateway rejects every subject outside your organization, by explicit list, by prefix, or by the `tenant` claim. Leave the **Run the check** option selected and click **Run check and connect**. The check can take up to a minute. If it fails, nothing is registered; see [Common errors](#common-errors). If the gateway can't be reached from the internet yet, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**. The reason is shown in the **Gateways** table. Entering an address that is already registered runs the check again (unless you skip it) without changing the stored result, then moves to the bundle step. Choose a bundle from the **Access bundle** list, or click **New bundle**, enter a **Bundle name**, and click **Create bundle**. Then click **Add to bundle**. This creates a connection in that bundle, labeled **Gateway** on its **Credentials** tab, with the gateway's host as its allowed website. A gateway can be in one bundle only; to use it in several scopes, attach that bundle to each. Click **Not now** to finish without a bundle. The **Gateways** table lists each gateway with its **Connection check** result (**Passed**, or **Skipped** with your reason), when it was added, and **Add to bundle** and **Remove** actions. For a gateway that is already registered, skip the dialog's first step: click **Add to bundle** in the gateway's row of the **Gateways** table, which opens the dialog at the bundle step. Entering the address again in **Connect a gateway** also reaches the bundle step, but unless you skip the check it runs again first, and that run counts toward the check limit. ## Let agents reach the gateway Claude uses the gateway in channels whose scope has the bundle attached. [Attach the bundle to a workspace or channel](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) if it isn't attached already. Claude also needs to know the gateway exists. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions): ```text wrap theme={null} Internal APIs are behind https://gateway.example.com. Call GET /list-services there to see what is available. ``` The sample gateway serves `GET /list-services` for this; an OpenAPI document named in the instructions works as well. New threads pick up the connection on their own. In a thread already running, ask Claude to use the gateway and include its address. If Claude still can't see the gateway, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) at the channel's top level to start a fresh session with your organization's current configuration. ## Verify the connection In a channel under the bundle's scope, start a new thread and ask Claude to make a small read through the gateway: ```text wrap theme={null} @Claude call GET /list-services on https://gateway.example.com and tell me what it returns. ``` If your gateway logs subjects and decisions, confirm the request arrived with a token that passed every check and a subject starting with your **Subject prefix**. [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) attaches the token at the network boundary; the model and the sandbox are not given it. To disconnect a gateway, click **Remove** in the gateway's row of the **Gateways** table. Claude stops using the gateway at once. A token issued before the removal stays valid until it expires, within 10 minutes. ## Common errors Two messages come up while connecting: * **"The check didn't pass"**: the gateway isn't reachable from the internet over HTTPS, its root route doesn't answer an empty `POST` directly, or the subject check is missing or rejects the **Control subject**. See [The check didn't pass](/docs/claude-tag/admins/federated-access/troubleshooting#the-check-didn%E2%80%99t-pass). * **A bundle-step message that the gateway is already in a bundle**: a gateway can be in one bundle only. [Attach that bundle to the scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting). ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model * [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a gateway connection applies * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation * [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type * [Sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample): a reference gateway with offline tests # Connect a Google Cloud identity Source: https://claude.com/docs/claude-tag/admins/federated-access/gcp Let Claude call Google Cloud through workload identity federation with a short-lived identity token instead of a service account key. Covers the pool, provider, and IAM grants to create, with or without a service account, and how to connect the identity in the console. Google Cloud identities are connected at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation and use the **Cloud roles** section. Connecting an identity needs an organization Owner, or an admin with full Claude Tag management permission. With a Google Cloud identity connection, Claude exchanges a short-lived identity token at a workload identity pool you create and calls Google Cloud APIs with the result. No service account key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your pool's attribute condition decides which tokens to accept. If someone else manages your Google Cloud project, give them the values from Claude's admin settings and the settings below; the console steps need a Claude Tag admin. Before you start, decide whether Claude acts as the federated identity itself, with roles granted to it directly, or as a service account you create. Both forms are covered below. ## Before you begin * You're an organization Owner, or an admin with full Claude Tag management permission. * You can create a workload identity pool and provider in a Google Cloud project (any project; it doesn't have to own the resources) and grant IAM roles on the resources Claude will use. Use a workload identity pool; workforce identity pools aren't supported. * If an organization policy restricts which issuers your workload identity pools may trust, allow `https://identity.anthropic.com/agents` first. * You know which Google API hosts Claude will call, for example `storage.googleapis.com`. ## Copy the values from the console In **Cloud roles**, click **Connect a Google Cloud identity** and copy the **Issuer** and **Subject prefix** rows from the **Set the workload identity provider to accept these values** card (the **JWKS URL** row isn't needed, because Google reads the keys from the issuer). Then click **Cancel**; you connect the identity after setting up Google Cloud. | Value | What it is | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer | `https://identity.anthropic.com/agents`. The issuer URL of the provider you create in the pool. | | Subject prefix | `wimse://identity.anthropic.com/org//agent/`. Every token's subject starts with this prefix and ends with one agent's ID. The organization ID between `/org/` and `/agent/` is also the value of the token's `tenant` claim. | ## Create the pool and provider in Google Cloud Create a workload identity pool and an OpenID Connect (OIDC) provider in it with these settings. Replace `` with the ID from your **Subject prefix**. | Setting | Value | | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer URL | `https://identity.anthropic.com/agents` | | Allowed audiences | Leave at Google's default, the provider's own resource name, which Google accepts with or without a leading `https:`. Claude sends the name exactly as you enter it in Claude's admin settings, so if you pin allowed audiences instead, pin that same spelling. | | Attribute mapping | `google.subject` = `assertion.sub`. You can also map `attribute.org` = `assertion.tenant`, which lets you grant roles to all of your organization's agents as one principal set in [Grant access](#grant-access). | | Attribute condition | `assertion.sub == ""` for one agent. To allow several agents, join one comparison per agent with CEL's or operator. To admit every agent in your organization instead, `assertion.sub.startsWith("wimse://identity.anthropic.com/org//agent/")`. | Google doesn't require an attribute condition, and nothing checks it for you. Without one, agents of every other Claude Tag organization can authenticate to your pool, because every organization's tokens come from the same issuer; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). The condition on `assertion.sub` is the subject check every connection type needs. The exact form accepts only the agents you list, and the prefix form accepts every agent in your organization, because every subject carries your organization ID between `/org/` and `/agent/`. Listing exact subjects is the strongest form. The prefix form is the minimum, and it admits every agent in your organization to the pool. With the prefix form, you can still grant IAM roles only to individual agents' `principal://` members, as shown under [Grant access](#grant-access). Claude's admin settings don't show agent IDs, so you learn a subject from Cloud Audit Logs after a first exchange, and you update the condition or the grants when a Slack channel is deleted and recreated, because the new channel's agent has a new ID. Mapping `attribute.org` from `assertion.tenant` is optional. The `tenant` claim carries the same organization ID as the subject, so the condition `attribute.org == ""` is the prefix check in claim form. The mapping is standard Google attribute mapping. ## Grant access Choose one of the two forms. The console step "Name the service account, or leave the field empty" depends on your choice. ### Without a service account Grant IAM roles on each resource directly to the federated identity. To grant a role to one channel's agent, use the agent's full subject, unescaped, for example `principal://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/claude/subject/wimse://identity.anthropic.com/org//agent/`. To grant a role to all of your organization's agents at once, map `attribute.org` from `assertion.tenant` as described under [Create the pool and provider in Google Cloud](#create-the-pool-and-provider-in-google-cloud), and use the principal set ```text wrap theme={null} principalSet://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/claude/attribute.org/ ``` with your project number, pool ID, and organization ID. Grant only what Claude needs, and grant nothing to the pool-wide principal set (`principalSet://…/workloadIdentityPools/claude/*`). In this form, don't grant the federated identity any permission that mints credentials, such as `iam.serviceAccounts.getAccessToken`, `iam.serviceAccounts.signJwt`, or service account key creation, because Claude could then obtain a Google credential that works outside Claude. (The form with a service account grants one such permission on purpose, on one service account.) ### With a service account Create a dedicated service account in any project and grant it the roles Claude needs. The console accepts only addresses of the form `@.iam.gserviceaccount.com`, so the default Compute Engine and App Engine service accounts can't be used. Enable the IAM Service Account Credentials API in the service account's project. Then grant the **Workload Identity User** role (`roles/iam.workloadIdentityUser`) to the same `principalSet://` or `principal://` member as in [Without a service account](#without-a-service-account), on the service account's own IAM policy rather than on the project. Don't grant the service account any permission to mint further credentials or create keys. ## Connect the identity in the console In **Cloud roles**, click **Connect a Google Cloud identity**. In the **Workload identity provider** field, enter `//iam.googleapis.com/` followed by the provider's full name as Google reports it, for example `//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/claude/providers/agents`. Use the project number, not the project ID (find it on the project's dashboard in the Google Cloud console). The value is stored as you type it and is the token's audience. In the **Service account to act as (optional)** field, enter the service account's email, for example `claude@my-project.iam.gserviceaccount.com`, if you chose the form with a service account. Leave the field empty to have Claude act as the federated identity itself. The connection is named after the service account, or after the provider's ID (the last part of its resource name) when there is none. The **Block requests that mint new credentials** checkbox is selected by default. With it selected: * Claude can't use this identity to call Google endpoints that create keys, tokens, or other credentials, even if IAM would allow the call. * Requests to a list of services that deal in credentials are refused entirely. See [what the credential-minting block refuses](/docs/claude-tag/admins/federated-access/limits#what-the-credential-minting-block-refuses) on the limits page. * gRPC calls are refused, so tell Claude in the custom instructions to use the REST transport of client libraries such as Spanner, Bigtable, Firestore, and Pub/Sub. If Claude needs one of the refused services, clear the checkbox and rely on your IAM grants alone. The token exchange itself, including acting as the service account, happens inside Agent Proxy and isn't affected by this checkbox or by the allowed hosts. Replace the prefilled `*.googleapis.com` entry in the **Allowed Google hosts** field with the hosts Claude needs, for example `storage.googleapis.com`. A wildcard as the leftmost label, such as `*.storage.googleapis.com`, matches any subdomain but not the name itself. Every host must be `googleapis.com`, a subdomain of it, or a subdomain of `clients6.google.com`. You can change the list later from the connection's [**Edit connection** dialog](/docs/claude-tag/admins/add-connections#set-allowed-websites) on the bundle's **Credentials** tab. Select the checkbox labeled **The provider's attribute condition requires the subject prefix shown above**. The **Connect identity** button stays disabled until you do. Select the checkbox only if the provider's attribute condition pins `assertion.sub` to one or more full subjects under your **Subject prefix**, or at minimum pins `assertion.sub` to your **Subject prefix** (or, if you mapped it, `attribute.org` to your organization ID), as described under [Create the pool and provider in Google Cloud](#create-the-pool-and-provider-in-google-cloud). Choose a bundle from the **Access bundle** list, or click **New bundle**, enter a **Bundle name**, and click **Create bundle**. Then click **Connect identity**. This creates a [connection](/docs/claude-tag/admins/add-connections) in that bundle, labeled **Google Cloud identity** on its **Credentials** tab, with the hosts you entered under **Allowed hosts**. The same provider can be connected more than once, for example once with a service account and once without, as long as no two Google Cloud connections in one bundle share a host under **Allowed hosts**. To use a connection in several scopes (workspaces or channels), attach its bundle to each. The **Cloud roles** table has **Role**, **Access bundle**, **Allowed hosts**, **Added**, and **Actions** columns. Each connection's name appears under **Role** with the provider and a **Google Cloud** chip beneath it, which also names the service account when the connection acts as one, and **Remove** is under **Actions**. ## Let agents use the identity Claude uses the identity in channels whose scope has the bundle attached. [Attach the bundle to a workspace or channel](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) if it isn't attached already. Claude also needs to know what the identity is for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions): ```text wrap theme={null} Use the Cloud Storage JSON API at storage.googleapis.com to read the bucket example-reports. Google Cloud access is already set up. ``` [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) exchanges the token and attaches the resulting Google credential to each request at the network boundary, so the sandbox never holds it. New threads pick up the connection on their own. In a thread already running, ask Claude to use Google Cloud. If Claude still can't, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) at the channel's top level (not inside a thread) to start a fresh session with your organization's current configuration. ## Verify the connection In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to run a connectivity check. The check reads a bucket's metadata, so the identity needs the `storage.buckets.get` permission on the bucket, and `storage.googleapis.com` must be under the connection's **Allowed hosts**. Send Claude this prompt, replacing `example-reports` with a bucket the identity can read: ```text wrap theme={null} @Claude Connectivity check for this channel's Google Cloud connection. Please run exactly: curl -sS -o /tmp/resp.txt -w '%{http_code}' https://storage.googleapis.com/storage/v1/b/example-reports and tell me the HTTP status code it prints, then paste the contents of /tmp/resp.txt. ``` A status of 200 with a JSON body whose `kind` is `storage#bucket` means the token exchange and the API call both worked. For log evidence, enable Data Access audit logs beforehand for the Security Token Service API, for Cloud Storage, and, with a service account, for the IAM Service Account Credentials API, because Google keeps them off by default. The Security Token Service entry records each token exchange, with Google's reason when it refuses one, which Claude's own error doesn't show. The Cloud Storage entry shows the caller as the service account, or as the federated identity with the agent's full subject. If Claude reports that the request was refused, the two most common causes are these: * A token refused by your provider usually means the attribute condition didn't accept it. Check the organization ID in the condition, then the issuer URL and the allowed audience. * A permission error on the API call means the role grant is missing or too narrow. See [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows and the other causes. To disconnect an identity, click **Remove** in the identity's row of the **Cloud roles** table, then **Remove role** in the confirmation. Claude stops using the identity within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. A Google credential from an earlier exchange stays valid with Google until it expires, held only by Agent Proxy, never by Claude's sandbox. To end the trust on the Google side as well, delete the provider or remove the IAM bindings. ## Common errors Two messages come up while connecting: * **A message that a connection "already covers" a host "in this bundle"**: another Google Cloud connection in the bundle you chose already has that host under **Allowed hosts**, so Claude would never use the new connection for it. Remove the shared host or choose another bundle. * **A rejected Workload identity provider or Service account to act as value**: the value doesn't match the form the field describes, usually because the resource name carries the project ID instead of the project number, or the service account is a default one. For other dialog messages, see [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting). ## Related resources * [Give Claude access](/docs/claude-tag/admins/add-connections): the Access bundle and connection model * [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where an identity connection applies * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation * [Limits](/docs/claude-tag/admins/federated-access/limits): what the credential-minting block refuses, and the other limits for Google Cloud identities * [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type * [BigQuery](/docs/claude-tag/admins/connections/bigquery): the stored-key alternative for one Google service # Limits for federated cloud access Source: https://claude.com/docs/claude-tag/admins/federated-access/limits Counts, lengths, lifetimes, and unsupported configurations for Claude Tag's federated cloud access: gateways, AWS roles, Google Cloud identities, and authorization servers. This page collects the fixed limits of Federated cloud access in one place. ## Where federated connections work Federated connections are available to Claude in Slack channels, where it acts under your organization's [agent identity](/docs/claude-tag/concepts/agent-identity). They aren't available in direct messages, which run on the individual's own claude.ai account, and they need an Anthropic-hosted environment; Claude can't use them in a [self-hosted environment](/docs/claude-tag/concepts/security-and-data). ## Identity token | Limit | Value | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Token lifetime | 10 minutes. Tokens can't be revoked before they expire. When you remove a gateway, Claude stops using it at once; when you remove a cloud role or authorization server, within about a minute (current behavior, may change). A token issued before the removal stays valid until it expires. | | Signing algorithm | ES256 only. | | Claims | See the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference#claims); verifiers must ignore claims they don't recognize. | ## Gateways | Limit | Value | | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Registered addresses per organization | 5, counting gateways and authorization-server token endpoints together. | | Token reuse | Claude reuses one token for a session's requests to the same gateway for about five minutes, half the token's lifetime, or until the gateway answers 401, and then requests a new one (current behavior, may change). A gateway sees the same `jti` on many requests. | | Gateway address | An HTTPS host name only, with no path, port, query, or trailing slash. The host name needs a domain, like `gateway.example.com`, uses only letters, numbers, hyphens, and dots, and has at most 253 characters (current behavior, may change). The console rejects an IP address, a private-network name, an Anthropic-owned host, or a host cloud providers use for token exchange, and names the reason. The connection check also refuses a host name that resolves to a private address. | | One connection per gateway | A gateway connected in one Access bundle can't be connected again in another. Attach that bundle to each scope that needs the gateway. | | [Allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) on the gateway's connection | Exactly the gateway's host, the only host Claude sends the token to. It can't be widened or given a wildcard. | | Connection check | Runs only against an HTTPS host with no path. The console sends two `POST` requests to the address, each with an empty body and a test token, doesn't follow redirects, and can take up to a minute. [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway) lists the expected responses. The console refuses a check that runs many times in quick succession and says how long to wait. | | Same address twice in one organization | Entering an address that is already registered runs the connection check again (unless you skip it) without changing the stored result, then moves to the bundle step. The run counts toward the check limit. | ## AWS roles | Limit | Value | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Role ARN** | A commercial-partition IAM role, `arn:aws:iam:::role/`. AWS GovCloud and AWS China roles aren't supported. | | **Allowed AWS hosts** | Hosts ending in `.amazonaws.com` only, for example `s3.us-east-1.amazonaws.com` or `*.amazonaws.com`. | | Role session | 1 hour. The exchange doesn't ask for a longer session, so raising the role's maximum session duration has no effect. Claude reuses one session's credentials for the same agent until shortly before they expire, or until AWS answers a request with 403 (current behavior, may change). | | Token audience | `sts.amazonaws.com`, the same for every organization. Condition the trust policy on the `sub` claim as well as the audience; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). | | One connection per role | A role can be connected once in your organization. | ## Google Cloud identities | Limit | Value | | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Workload identity provider** | The full resource name of a provider in a workload identity pool under a numeric project, `//iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/`. Workforce identity pools aren't supported. | | **Service account to act as** | Optional. A service account, `@.iam.gserviceaccount.com`. Default compute and App Engine service accounts aren't accepted. Leave it empty to call Google Cloud as the federated identity itself. | | **Allowed Google hosts** | `googleapis.com`, a subdomain of it, or a subdomain of `clients6.google.com`. | | OAuth scope | `https://www.googleapis.com/auth/cloud-platform`, always. Effective permissions come from IAM. | | **Block requests that mint new credentials** | On by default. When on, requests to Google's credential-minting and credential-delivering endpoints are refused, including over gRPC; see [What the credential-minting block refuses](#what-the-credential-minting-block-refuses). The block is best effort and doesn't replace least-privilege IAM. | | Google Cloud connections in one bundle | No two Google Cloud connections in the same Access bundle can cover the same host under **Allowed hosts**, whatever their providers or service accounts. A wildcard such as `*.googleapis.com` covers every subdomain but not `googleapis.com` itself. The same provider can be connected again with different hosts, or in another bundle. | ### What the credential-minting block refuses With **Block requests that mint new credentials** on, Agent Proxy refuses these requests before they reach Google, whatever IAM would allow (current behavior, may change): * Every request to these services, whether the service is named in the host or in the path: Security Token Service, IAM, IAM Service Account Credentials, API Keys, Firebase Authentication (Identity Toolkit and Secure Token), Cloud Workstations, Cloud SQL Admin, AlloyDB, Connect Gateway, GKE Hub, Certificate Authority Service, Identity-Aware Proxy, Apigee, Secret Manager, Parameter Manager, OS Login, Cloud Shell, Cloud Identity, the Google Workspace Admin SDK, Cloud KMS, Cloud Tasks, Cloud Scheduler, Eventarc, Workflows and Workflow Executions, API Gateway, Application Integration, Deployment Manager, Cloud Build, Cloud Composer, Dataform, AI Platform Training and Prediction, Google Kubernetes Engine, Dataproc, OS Config, Dialogflow, Storage Transfer Service, BigQuery Data Transfer Service, and Vertex AI Workbench. * On every other Google service, methods whose response carries a credential or signature, matched by method name. For example `generate`, `refresh`, or `exchange` methods ending in `Token`, `Cert`, `Certificate`, `Credential`, `Credentials`, `Url`, `Secret`, `Password`, or `Key`, and `exchangeAppAttestAssertion` and `exchangeAppAttestAttestation` (Bigtable's `generateConsistencyToken`, which returns no credential, passes). * Signing methods: `sign`, `signJwt`, `signBlob`, `signSshPublicKey`, and their `asymmetric`, `mac`, and `raw` forms. * `show`, `reset`, or `retrieve` methods ending in `Credential`, `Credentials`, `Password`, `Secret`, or `SecretKey`, plus `add` or `import` methods ending in `PublicKey`, and methods starting with `signUp` or `signIn`. * `setIamPolicy` on any resource, and Compute Engine `setMetadata`, `setCommonInstanceMetadata`, `updatePerInstanceConfigs`, `patchPerInstanceConfigs`, instance updates, and instance settings writes. * Cloud Storage IAM and ACL writes, and HMAC key creation. * IAM service account key creation and upload; API Keys `keyString` and Memorystore `authString` reads. * Pub/Sub subscription creation, update, and `modifyPushConfig`, and Cloud Monitoring uptime check creation and changes. * Google's OAuth 2.0 token endpoint (`oauth2.googleapis.com/token`), HTTP batch requests (a path that starts with `/batch`), and any request framed as gRPC, gRPC-Web, or `$rpc`. On services not listed above, reads such as `getIamPolicy`, `testIamPermissions`, and `tokeninfo` pass. If Claude needs one of the refused services, clear the checkbox on that connection and rely on IAM alone. ## Authorization servers | Limit | Value | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Token endpoint** | A full HTTPS URL of at most 256 characters (current behavior, may change), with an optional path and no port, query, fragment, user name, password, spaces, or special characters. The same host rules as a gateway address apply, and a trailing slash is dropped. | | Token audience | Your authorization server's issuer identifier as you entered it (an HTTPS URL on the same host as the token endpoint, with the same address rules), or the token endpoint URL exactly when you left the issuer identifier empty. It can't be changed after the server is connected. | | **Resource** | Optional. An absolute URI with no fragment, at most 256 characters with no spaces (current behavior, may change). | | **Scope** | Optional. Space-separated scope words with no quotes or backslashes, at most 256 characters in total (current behavior, may change). | | **Allowed API hosts** | Must not include the token endpoint's host. | | Token exchange | A form-encoded `POST` that doesn't follow redirects and must complete within about 10 seconds (current behavior, may change). | | Access token reuse | Reused until about five minutes before it expires (for tokens shorter than 10 minutes, until half their lifetime has passed) when `expires_in` is between 5 minutes and 1 day. When `expires_in` is missing or shorter, the token is used for one request. When it is longer than a day, the token isn't cached either, so every request goes to the token endpoint. (Current behavior, may change.) | | Subject check | Your authorization server performs it; the console has no connection check for token endpoints. The server must accept only your own agents' full subjects, or at minimum check that each token's subject starts with your organization's **Subject prefix**. | | Endpoint reuse | A registered address can be connected as a gateway or as an authorization server, not both. A token endpoint stays listed in the **Gateways** table after you remove its authorization server, and frees its place among the 5 registered addresses only when you remove it there too. | ## Testing The console's connection check is the only way to have Anthropic send a token to your gateway before Claude does. There is no way to request a test token for your own use. To test end to end, follow the Verify step on each connection page. ## Related resources * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): claims, issuer, keys, and rotation * [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway) * [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws) * [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp) * [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server) * [Network requirements](/docs/claude-tag/admins/network-requirements): Anthropic's egress range and internet reachability # Federated cloud access Source: https://claude.com/docs/claude-tag/admins/federated-access/overview Claude Tag proves its identity to your systems with a short-lived signed token instead of a credential stored in Claude. Learn how the token works and which of the four connection types to use. Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation. Connecting a gateway, cloud role, or authorization server needs an organization Owner, or an admin with full Claude Tag management permission. In Slack channels, Claude Tag acts under its own [agent identity](/docs/claude-tag/concepts/agent-identity) rather than as any person. Federated cloud access lets that identity prove itself to your systems with a short-lived, signed identity token instead of a credential you store in Claude. Federated cloud access is in public beta. In the console, you connect your gateway, AWS role, Google Cloud identity, or authorization server under **Federated cloud access** and add it to an [Access bundle](/docs/claude-tag/admins/add-connections) attached to the channels where Claude should use it. Your cloud or gateway administrator configures that system to trust Anthropic's issuer and to check that each token's subject belongs to your organization, and the system then decides what the agent may do. To confirm the connection works, ask Claude in one of those channels to make a small request, then check its reply and your system's logs. Federated cloud access goes one way: Claude proves who it is to your systems. For your workloads proving who they are to the Claude API, see [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) on the Claude Developer Platform. Your systems can accept the token in one of four ways. The table below says which to choose; the rest of the page explains what the token is and what to have ready. ## Choose a connection type | Connection type | Who accepts the token | Choose it when | | :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Gateway** | A service you run. It verifies the token, maps the agent to permissions, and forwards the request to your internal systems with credentials you hold. | You want one entry point in front of internal APIs. The [sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample) is a starting point. | | **AWS role** | AWS, through an IAM OIDC identity provider. AWS issues temporary credentials for a role whose trust policy names Anthropic's issuer and your organization. | Claude should call AWS APIs under a role you govern with IAM. | | **Google Cloud identity** | Google Cloud, through a workload identity pool. Google issues an access token for the federated identity, acting as a service account if you name one. | Claude should call Google Cloud APIs under an identity you govern with IAM. | | **Authorization server** | Your OAuth 2.0 authorization server. It accepts the token as a JWT bearer grant (RFC 7523) and returns an access token for your APIs. | Your APIs are already protected by your own OAuth server and you'd rather issue its tokens than run a gateway. | In every case the system on your side decides what the agent may do in your systems. Each connection type has its own setup page: [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway), [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws), [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp), and [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server). ## How it works 1. When a request from Claude's sandbox needs one of your systems, [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) matches it by destination to a federated connection in one of the channel's Access bundles. Until an admin connects a system in **Federated cloud access** and adds it to a bundle attached to the channel, nothing matches and no token is issued for Claude's requests. 2. Anthropic issues an identity token. The token is a JSON Web Token (JWT) signed by Anthropic and valid for 10 minutes. Its subject names your organization and the agent, in the form `wimse://identity.anthropic.com/org//agent/`, and its audience names the destination. Claude reuses one token for a session's requests to the same gateway for about five minutes, or until the gateway answers 401, and then requests a new one. The other connection types use a token once, in an exchange. 3. Your side accepts the token. A gateway verifies it directly. AWS or Google Cloud exchanges it for a short-lived cloud credential. Your authorization server exchanges it for an access token. Agent Proxy attaches the result to Claude's request, or signs the request with it for AWS, and forwards the request. The model and the sandbox are never given the token or the credential that comes back. Whichever system accepts the token checks five things: * **Signature**, against the public keys Anthropic publishes, and **issuer**. Together these prove Anthropic issued the token. * **Audience**. This proves the token was issued for the destination it's presented to: your gateway, your authorization server, your Google Cloud provider, or AWS. * **Expiry**. This proves the token is fresh. * **Subject**. This is what names your organization. Every Claude Tag organization's tokens come from the same issuer, and every organization's AWS tokens share the same audience, so the first four checks can pass for a token that belongs to someone else. Every connection type therefore requires a subject check. The strongest form accepts only the exact subjects of your own agents. The minimum form requires the subject to start with your **Subject prefix**, `wimse://identity.anthropic.com/org//agent/`, including the `/agent/`; a gateway, authorization server, or Google Cloud attribute condition can pin `iss` and `tenant` instead, since `tenant` carries the same organization ID. The console shows the issuer, the signing-key location, and your **Subject prefix** with copy buttons, and each setup page says where they go. The [identity token reference](/docs/claude-tag/admins/federated-access/token-reference) lists every value and claim and [compares the two forms of the subject check](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). Anthropic stores no long-lived credential for your systems, and each call carries a short-lived signed token, so there is no key of yours to rotate or leak. Anthropic rotates its own signing keys, and the [token reference](/docs/claude-tag/admins/federated-access/token-reference#key-rotation) says how a verifier follows them. To cut off access, remove the connection in the console. These lifetimes then apply: | What | How long it lasts | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | A removed connection | Claude stops using a removed gateway at once, and a removed cloud role or authorization server within about a minute | | An identity token already issued | 10 minutes from when it was issued | | AWS credentials already exchanged | 1 hour, the role session length | | A Google Cloud credential already exchanged | As long as Google Cloud issued it for | | An access token from your authorization server | The `expires_in` your server returned | Anthropic doesn't review your gateway, trust policy, or authorization server. When you connect a gateway, the console offers a connection check that confirms the gateway rejects a token whose subject isn't your organization. The other connection types have no check in the console, so you verify them yourself with the steps on each setup page. ## Before you begin * **Federated cloud access** appears in the console's left navigation. It's missing for organizations whose compliance configuration excludes federated cloud access. * An organization Owner, or an admin with full Claude Tag management permission, makes the connection in the console. * Your cloud or gateway administrator configures the system on your side: the gateway operator, your AWS or Google Cloud IAM administrator, or your authorization server's operator. Each setup page lists the values they configure. * An [Access bundle](/docs/claude-tag/admins/add-connections) is attached to the [scope](/docs/claude-tag/concepts/glossary#scope) of the channels where Claude should use the connection. A connection can be in only one bundle, so to use a connection in several places, attach that bundle to each scope. Federated connections work in Slack channels, where Claude acts under your organization's agent identity. They don't work in direct messages, which run under [the individual's own account](/docs/claude-tag/concepts/agent-identity#direct-message-channels). ## Related resources * [How agent identity works](/docs/claude-tag/concepts/agent-identity): the identity these tokens represent, and how Agent Proxy attaches credentials * [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): verify the token at a service you run * [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws): the IAM OIDC provider and trust policy * [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp): the workload identity pool, provider, and attribute condition * [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server): accept the token as a JWT bearer grant * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim, the lifetime, and key rotation * [Limits](/docs/claude-tag/admins/federated-access/limits): counts, lengths, lifetimes, and unsupported configurations * [Troubleshoot federated cloud access](/docs/claude-tag/admins/federated-access/troubleshooting): console messages, blocked requests, and rejections in your logs # Identity token reference Source: https://claude.com/docs/claude-tag/admins/federated-access/token-reference The claims, issuer, signing keys, lifetime, and subject format of the identity token Claude Tag presents to a gateway, cloud provider, or authorization server. When Claude calls a system you connected through Federated cloud access, it proves who it is with a signed identity token instead of a stored credential. The token is a JSON Web Token (JWT) that names your organization and the agent making the request. A gateway you run receives it in the `Authorization: Bearer` header and verifies it directly. AWS, Google Cloud, or your authorization server receives it in a token exchange and returns one of its own credentials. This page lists what the token contains so the engineer who configures the verifying side can pin the right values. For setup steps, see [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway), [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws), [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp), or [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server). ## Issuer and signing keys | Item | Value | | :----------------------------------------- | :------------------------------------------------------------------------------------------------ | | Issuer (`iss`) | `https://identity.anthropic.com/agents`. Match it exactly, including the `/agents` path. | | OpenID Connect (OIDC) discovery document | `https://identity.anthropic.com/agents/.well-known/openid-configuration` | | Signing keys, as a JSON Web Key Set (JWKS) | `https://identity.anthropic.com/agents/jwks.json`, the `jwks_uri` named in the discovery document | | Signing algorithm | ES256 only. Reject any other `alg`, including `none`. | Both documents are public and need no authentication to fetch. One issuer serves every Claude Tag organization, so the issuer and signature prove only that Anthropic issued the token. The [subject](#subject), or the `tenant` claim, is what ties a token to your organization. ### Key rotation Signing keys rotate. If you run the verifier yourself, select the key by the token's `kid` header and refetch the JWKS when you see a `kid` you don't know, before rejecting the token. Most JWKS libraries do this by default. Don't pin a single key. AWS and Google Cloud manage their own key caches. ## Lifetime | Claim | Value | | :---- | :---------------------------------------------------------------------------------------- | | `iat` | When the token was issued, in seconds since the Unix epoch | | `nbf` | 15 seconds before `iat` (current behavior, may change). Libraries check it automatically. | | `exp` | 10 minutes (600 seconds) after `iat` | | `jti` | A unique ID for this token | Allow up to 60 seconds of clock skew when you check `exp`, and treat `exp` as the earliest moment a token may stop working rather than an exact cutoff; cloud providers apply their own grace. Tokens can't be revoked before they expire. There is no revocation list or introspection endpoint. When you remove a gateway in the console, Claude stops using it at once, and a token issued before the removal stays valid until it expires, within 10 minutes. When you remove a cloud role or authorization server, Claude stops using it within about a minute, and a credential from an earlier exchange stays valid with AWS, Google Cloud, or your server until it expires, held only by Agent Proxy, never by Claude's sandbox. Claude reuses one token for a session's requests to the same gateway for about five minutes, half the token's lifetime, or until the gateway answers 401, and then requests a new one (current behavior, may change). A gateway therefore sees the same `jti` on many requests, so don't treat a repeated `jti` as a replay. AWS, Google Cloud, and an authorization server each see a token once per exchange. ## Subject The `sub` claim names one agent in one organization: ```text theme={null} wimse://identity.anthropic.com/org//agent/ ``` * The organization ID starts with `org_` and the agent ID with `cagt_`. Both use only letters, digits, `_`, and `-`, so neither can contain `/` or `:`. * The **Connect a gateway**, **Connect an AWS role**, **Connect a Google Cloud identity**, and **Connect an authorization server** dialogs show your organization's **Subject prefix**, `wimse://identity.anthropic.com/org//agent/`. Every one of your agents' subjects starts with this prefix. * An agent belongs to one Slack channel. Deleting and recreating a channel creates a new agent with a new ID. The console doesn't show agent IDs; a verifier learns full subjects from the tokens it receives or from your cloud provider's logs. * The console's connection check for a gateway presents a token for a reserved test agent in your organization, shown in the **Connect a gateway** dialog as the **Control subject**. Your gateway must answer that token with a 2xx status so the check can pass, and must grant that subject no access. See [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway). The `wimse://` form follows the IETF WIMSE working group's workload identifier specification. ### Authorize on the subject A token with a valid signature, issuer, audience, and expiry can still belong to another organization, because one issuer serves every Claude Tag organization and every organization's AWS tokens share one audience. Only the subject, or the `tenant` claim, says which organization a token belongs to, so every verifier, trust policy, and attribute condition must check it. Write the check in one of two forms, strongest first: * **Pin the exact subjects.** Accept only the full subjects of your own agents. This is the strongest form, so use it whenever your use case allows. You update the rule when a Slack channel is deleted and recreated, because the new channel's agent has a new ID, and a gateway's list must also include the **Control subject**. * **Require your organization.** If keeping a list of exact subjects isn't practical, require that `sub` start with your **Subject prefix**, including the `/agent/`, or pin `iss` together with `tenant`, which carries the same organization ID. This is the minimum, and it accepts every agent in your organization, including agents in channels created later. ## Audience The `aud` claim is a JSON array with one element. Use your library's audience option rather than comparing the raw claim text; some libraries print a one-element array as a bare string. | Where the token goes | `aud` | | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A gateway you connected | The HTTPS address you registered, which the console accepts only as a bare host on the standard port and stores in lowercase, for example `https://gateway.example.com` | | AWS | `sts.amazonaws.com` | | Google Cloud | Your workload identity provider's full resource name, for example `//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/claude/providers/agents` | | An authorization server | Your server's issuer identifier as you entered it when connecting the server (an HTTPS URL on the token endpoint's host), for example `https://auth.example.com`, or the token endpoint URL exactly as registered, for example `https://auth.example.com/oauth2/token`, if you left the issuer identifier empty | The audience identifies the destination, not your organization; every organization's AWS tokens share `sts.amazonaws.com`. Always check the [subject](#subject) too. ## Claims These are the claims a token carries. | Claim | Value | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `iss` | `https://identity.anthropic.com/agents` | | `sub` | The agent's subject; see [Subject](#subject) | | `aud` | One-element array; see [Audience](#audience) | | `iat`, `nbf`, `exp` | Issued-at, not-before, and expiry times; see [Lifetime](#lifetime) | | `jti` | Unique token ID | | `tenant` | Your Claude organization ID, the same value as the subject's `org/` segment. Together with `iss`, this is the pair a relying party pins to trust tokens from one organization. Not your cloud or identity provider's tenant ID. | | `agent_id` | The agent ID, the same value as the subject's `agent/` segment | | `profile_id` | The ID of the Access bundle the connection belongs to, starting with `capp_`. Informational. | | `platform` | `slack` when the request came from Slack. Present whenever `slack_workspace_id` is. | | `slack_workspace_id` | The ID of the Slack workspace Claude is acting in. Present when the request came from a Slack workspace your organization owns. | | `slack_channel_id` | The ID of the Slack channel Claude is acting in. Present whenever `slack_workspace_id` is and Claude is acting in one channel rather than a whole workspace. | Tokens may carry additional claims Anthropic uses internally for audit; ignore any claim not listed here and never base an authorization decision on it. Three claim names are reserved and absent from every token: `platform_user_id`, `actor_sub`, and `account_id`. Don't write a rule that depends on them. An absent claim is omitted from the token, never sent empty. Anthropic sends the token only to the destinations you connect in **Federated cloud access**. When the request comes from Slack, the `slack_workspace_id` and `slack_channel_id` claims carry your Slack workspace and channel IDs to that destination along with your organization and agent IDs. Authorize on `sub`, as described under [Authorize on the subject](#authorize-on-the-subject). A gateway or authorization server, which can read every claim, can use `tenant` and `agent_id` instead, because they repeat the subject's two parts. An AWS trust policy matches on `sub` and `aud` only; a Google Cloud attribute condition can read `sub` or `tenant`. The token carries no claim that names the person behind the request, and no `groups`, `roles`, or `scope` claims. A rule that needs `slack_workspace_id` or `slack_channel_id` should refuse a token that lacks them. Anthropic may add claims to the token. A verifier must ignore claims it doesn't recognize and must never depend on a claim not listed here being present. ### Example payload The decoded payload of a token sent to a gateway registered as `https://gateway.example.com`, for a request from a Slack channel, with made-up IDs. Opaque claims are left out. ```json theme={null} { "iss": "https://identity.anthropic.com/agents", "sub": "wimse://identity.anthropic.com/org/org_01Hx7rQkPzT9sN3mVbJw2eYd/agent/cagt_01Mz4kVnXr8TqWb2pLsJ7hYe", "aud": ["https://gateway.example.com"], "iat": 1756600000, "nbf": 1756599985, "exp": 1756600600, "jti": "MX4KT2R7WBH5QZ3NDJ6PVA25FC", "tenant": "org_01Hx7rQkPzT9sN3mVbJw2eYd", "agent_id": "cagt_01Mz4kVnXr8TqWb2pLsJ7hYe", "profile_id": "capp_01Qw9tHnKj5Rz3mXb7PvL2cY", "platform": "slack", "slack_workspace_id": "T01HX7RQKPZT", "slack_channel_id": "C01MZ4KVNXRT" } ``` ## Verify a token Use a maintained JWT or OIDC library for your language and confirm it performs all five checks. Most libraries check issuer and audience only when configured to. 1. **Signature**: verified against a key from the JWKS, ES256 only. 2. **Issuer**: exactly `https://identity.anthropic.com/agents`. 3. **Audience**: the value registered for your gateway, cloud provider, or authorization server. 4. **Expiry**: `exp` is in the future, allowing up to 60 seconds of clock skew. 5. **Subject**: `sub` is one of your own agents' full subjects, or at minimum starts with your organization's **Subject prefix** (or `tenant` is your organization ID). Libraries don't do this one for you. Reject the token if any check fails, and answer with a generic 401 that doesn't echo the token. To read a captured token's claims while debugging, decode its middle segment. JWT payloads are base64url-encoded, so a plain `base64 -d` often fails: ```bash theme={null} python3 -c 'import base64,json,sys; p=sys.argv[1].split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4))), indent=2))' "$TOKEN" ``` Decoding doesn't verify anything. Log the subject and your decision, never the token itself. ## Related resources * [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): verify the token yourself at a service you run * [Connect an AWS role](/docs/claude-tag/admins/federated-access/aws): the trust policy that pins these values * [Connect a Google Cloud identity](/docs/claude-tag/admins/federated-access/gcp): the attribute condition that pins these values * [Connect an authorization server](/docs/claude-tag/admins/federated-access/authorization-server): accept the token as a JWT bearer grant * [Limits](/docs/claude-tag/admins/federated-access/limits): lengths, counts, and lifetimes in one place * [Sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample): a Python gateway that verifies the token and pins subjects exactly or by organization, with offline tests # Troubleshoot federated cloud access Source: https://claude.com/docs/claude-tag/admins/federated-access/troubleshooting Errors from Claude Tag's federated cloud access and what fixes each: console dialog messages, requests Claude reports as blocked or failed, and rejections your gateway, AWS, Google Cloud, or authorization server records. Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation. Changing them needs an organization Owner, or an admin with full Claude Tag management permission. This page covers what goes wrong after you connect a gateway, AWS role, Google Cloud identity, or authorization server through **Federated cloud access**. It's organized by where the problem shows up: a message in a console dialog, an error Claude reports in the thread, or a rejection in your own logs. The token terms used below are explained on the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference). First confirm two things that have nothing to do with federation: * The connection is in an [Access bundle attached to the channel's scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle). For a gateway, the scope's custom instructions also [name the gateway's address](/docs/claude-tag/admins/federated-access/connect-a-gateway#let-agents-reach-the-gateway), so Claude knows the gateway exists. * You tested in a new thread. A thread already running isn't told about a connection added after it started; ask Claude for the service by name, or send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) at the channel's top level. If Claude reports that a host isn't allowed before any request is sent, see [Claude says a host isn't allowed](/docs/claude-tag/admins/troubleshooting#claude-says-a-host-isn%E2%80%99t-allowed-or-it-can%E2%80%99t-reach-the-internet). ## Messages in the console Most dialog messages say what to do. The table adds what the message doesn't. The one message that needs more, "The check didn't pass", has its own entry below the table, followed by what removing and reconnecting a gateway does. | Message | What it means | Do this | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "The check can't run right now. Try again later, or skip the check and record why." | Anthropic couldn't produce the test tokens for the connection check. The problem is on Anthropic's side, not your gateway's. | Wait a few minutes and click **Run check and connect** again. If the message persists, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**; remove and reconnect the gateway later to record a passed check. | | "Too many checks in a short time." followed by how long to wait | Your organization ran the connection check too many times in quick succession. The limit counts every admin in the organization. Entering an address that is already registered runs the check again and counts too, unless the **Skip the check** option is selected. | Wait the time the message names. To add an existing gateway to a bundle, click **Add to bundle** in its row of the **Gateways** table instead of entering its address again. | | "Too many attempts in a short time." in the **Connect an authorization server** dialog | A general request limit, not the connection check; registering a token endpoint never runs the check. | Wait the time the message names and try again. | | "Connecting a gateway needs full Claude Tag management permission. Ask an organization owner." or "This needs full Claude Tag management permission. Ask an organization owner." | Your account can't change federated connections. Channel managers, and admins whose Claude Tag permission covers specific channels only, can't connect a gateway, cloud role, or authorization server. | Ask an organization Owner, or an admin with full Claude Tag management permission, to make the connection from their own account. | | A dialog message containing "isn't enabled for your organization yet", or **Federated cloud access** is missing from the left navigation | Federated cloud access isn't available to organizations whose compliance configuration excludes it. The navigation item is also hidden from channel managers and from admins whose Claude Tag permission covers specific channels only, because connecting a system needs full Claude Tag management permission. | Ask an organization Owner, or an admin with full Claude Tag management permission, to open the page. If it's missing for them too, your organization's compliance configuration excludes the feature. | | "This organization has reached its limit of 5 gateways. Remove one to connect another." or, in the **Connect an authorization server** dialog, "…limit of 5 registered gateways, which includes token endpoints." | An organization can register 5 addresses. A token endpoint is registered the same way as a gateway, so it counts toward the same 5 and appears in the **Gateways** table marked "Used by a connected authorization server. Manage it from the Authorization servers section." An address is either a gateway or a token endpoint in your organization, not both. | In the **Gateways** table, click **Remove** in the row of a gateway you no longer use. To free a token endpoint's row, click **Remove** in the server's row of the **Authorization servers** table first, then remove the endpoint from the **Gateways** table. See [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). | | "This gateway is already registered. Close this dialog and pick it from the list to add it to a bundle." | The address is already registered in your organization, and the dialog couldn't load its row to continue. This message is rare: entering a registered address normally runs the connection check again without changing the stored result, then moves on to the bundle step. | Click **Cancel**, then click **Add to bundle** in the gateway's row of the **Gateways** table. | | "`
` is already in the bundle ``. Assign that bundle to a channel to use the gateway there.", "This role is already connected in the bundle ``.", or "This token endpoint is already connected in the bundle ``." | A gateway, AWS role, or token endpoint can be connected in only one Access bundle, and this one already is. | To use the connection in more channels, [attach that bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. To move it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. Then add it to the new bundle: **Add to bundle** in the gateway's row of the **Gateways** table, or the connect dialog again for the other types. | | "`` already covers `` in this bundle, so Claude would never use this connection for the hosts they share. Change the hosts or choose another bundle." in the **Connect a Google Cloud identity** dialog | Another Google Cloud connection in the bundle you chose already has that host under **Allowed hosts**, whatever its provider or service account. Claude uses the first connection in a bundle whose hosts match a request, so the new connection would never be used for the shared host. A wildcard such as `*.googleapis.com` covers every subdomain but not `googleapis.com` itself. The dialog won't connect until the overlap is gone. | Remove the shared host from the new connection's **Allowed Google hosts**, or choose another bundle. To give the host to the new connection instead, first narrow the existing one: in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, choose **Edit**, and change **Allowed hosts**. | | "Couldn't connect the gateway. Try again.", "Couldn't add the gateway to the bundle.", "Couldn't connect the role. Try again.", "Couldn't connect the identity. Try again.", "Couldn't register the authorization server. Try again.", or "Couldn't connect the authorization server. Try again." | The request failed for a reason the dialog doesn't name, most often a temporary one. | Try once more. If the message persists, contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). | | "The issuer URL must be an https URL on the same host as the token endpoint. Leave it empty to use the token endpoint as the audience." in the **Connect an authorization server** dialog | The **Issuer URL** value must be an HTTPS URL on the same host as the token endpoint, or empty. The token is only ever presented to that server, so its audience must name that server. | Enter the issuer identifier your authorization server uses, on the token endpoint's host, or clear the field to use the token endpoint as the audience. | | "This token endpoint is already connected. Manage it from the Authorization servers section." in the **Connect an authorization server** dialog | An authorization server with this token endpoint is already connected in one of your organization's Access bundles, and a server can be connected only once. The dialog checks this before it registers anything. | To use the server in more channels, [attach its bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle). To connect it again, remove it first: in the **Authorization servers** table, click **Remove** in the server's row. | | "That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first." in the **Connect an authorization server** dialog | The token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your organization's Access bundles. One address can't be both, because a token sent to the gateway could be replayed to the server as a grant. | Enter the token endpoint and issuer identifier your authorization server publishes. To use that address for the server instead, remove the gateway first: in **Access bundles**, open the bundle that holds the gateway, open its **Credentials** tab, open the **⋮** menu on the gateway's row, and choose **Delete**. Then, in the **Gateways** table under **Federated cloud access**, click **Remove** in the gateway's row. | | "That address is registered by a connected authorization server. Enter your gateway's address, or remove the server first." in the **Connect a gateway** dialog | The address you entered is a connected authorization server's token endpoint or audience, for example a server whose **Issuer URL** is the bare host `https://auth.example.com`. One address can't be both, because a token sent to the gateway could be replayed to that server as a grant. | Enter the host your gateway answers on. To use that address for a gateway instead, remove the server first: in the **Authorization servers** table, click **Remove** in the server's row. | | "That address is already a connected authorization server's audience. Enter this server's own issuer URL." in the **Connect an authorization server** dialog | The **Issuer URL** value (or the token endpoint, when **Issuer URL** is empty) is already another connected authorization server's audience or token endpoint. Two servers can't share an audience, because a token minted for one would be valid at the other. | In the **Issuer URL** field, enter the issuer identifier this server publishes. If the other server holds this identifier by mistake, remove that server first: in the **Authorization servers** table, click **Remove** in its row, then connect it again with its own issuer URL. | | "The address is too long. Issuer URLs have at most 256 characters." under the **Issuer URL** field of the **Connect an authorization server** dialog | The **Issuer URL** field accepts at most 256 characters, the same limit as the **Token endpoint** field. | Check that the field holds only the issuer identifier, for example `https://auth.example.com`, and not a longer value pasted by mistake. | | "Couldn't check the addresses against your gateways and servers. Close this dialog and try again." in the **Connect an authorization server** dialog, or "Couldn't check the address against your authorization servers. Close this dialog and try again." in the **Connect a gateway** dialog | Before it registers an address, each dialog loads your organization's existing connections to check that the address doesn't clash with a connected gateway or authorization server. That list didn't load, and the dialog doesn't register an address it couldn't check. | Close the dialog and open it again. If the message persists, reload the page, then contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). | | An address-field message such as "Enter only the host, like [https://gateway.example.com](https://gateway.example.com), with no path, port or trailing slash.", "Enter a host name, not an IP address.", "That is an Anthropic address. Enter your own gateway's host name.", "That host name only works inside a private network. Enter a host name that is reachable from the internet.", or "That host is reserved for cloud token exchange. Enter your own gateway's host name." | A gateway address is an HTTPS host only, with a domain name of at least two labels. A token endpoint may have a path, but no port, query, fragment, or sign-in details. Neither can be an IP address, a private-network name, an Anthropic-owned host, or a host cloud providers use for token exchange. | Enter the public address the service answers on, for example `https://gateway.example.com` or `https://auth.example.com/oauth2/token`. The console can't register a private address even with the check skipped. | ### The check didn't pass **What you see** The **Connect a gateway** dialog shows "The check didn't pass. Claude couldn't reach the gateway, or the gateway didn't reject a token whose subject isn't your organization while accepting one that is. Fix the gateway and run the check again, or skip the check and record why." **What it means** The connection check sent two requests to your gateway and didn't get the two answers it needs. The gateway must reject a token whose subject isn't your organization, and it must accept a token for your **Control subject**. The console shows this one message for every failed check, so it doesn't say which request failed. If this was a new address, nothing was registered. **How to resolve** The check sends an empty `POST` to the address itself, with nothing added after the host, twice. Work through the causes in order. | Check | What to do | | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude can reach the address from the internet over HTTPS | Confirm the host resolves publicly, the TLS certificate is valid, and the gateway isn't behind a VPN. | | An empty `POST` to the address itself is answered directly | The check doesn't follow redirects, and any status other than the two expected ones fails it, including a 503 from a gateway that couldn't fetch the signing keys. | | The token whose subject isn't your organization gets 401 or 403 | If the gateway answered 2xx, the subject check is missing or wrong. | | The token for the **Control subject** gets 2xx | A gateway that rejects every token is usually missing the control subject, or has a wrong issuer, audience, or key setting. With the sample gateway, add the **Control subject** as a `principals` entry with `allowed_services: []` in `config.yaml`. | A 503 from the gateway usually means it can't reach `https://identity.anthropic.com` to fetch the keys. For a gateway that rejects every token, [Your gateway rejects every token](#your-gateway-rejects-every-token) lists each setting to compare. If you deployed [Anthropic's sample gateway](https://github.com/anthropics/claude-tag-wif-gateway-sample), its `config.yaml` must carry your real organization ID in the control-subject entry. If the gateway can't be fixed right away, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**. To run the check later, remove the gateway and connect it again; see [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). ### Removing and reconnecting a gateway In the **Gateways** table, click **Remove** in the gateway's row. Claude stops using the gateway at once. A connection that used the gateway stays in its Access bundle but stops working, and Claude reports [request blocked: this credential's audience isn't registered as a gateway for this organization](#request-blocked-this-credential%E2%80%99s-audience-isn%E2%80%99t-registered-as-a-gateway-for-this-organization) until the gateway is registered again. To reconnect, click **Connect a gateway** in the **Gateways** section and enter the same address. Registering the address restores the existing connection, which is still in the bundle, so don't add it to the bundle again; the dialog refuses if you try. ## Errors Claude reports in the thread When a request from a channel can't be sent with a federated credential, it fails with an HTTP status and a one-line reason, which Claude usually quotes. Reasons with HTTP 403 and 502 end with the connection's name in parentheses, for example `("gateway.example.com")`. The two 503 reasons don't name the connection. Messages that begin "request blocked" come with HTTP 403. The request was refused on purpose, and retrying won't help. A 503 is temporary. A 502 usually means AWS, Google Cloud, or your authorization server refused the token exchange. A response from your gateway or from the cloud API itself reaches Claude as is, so those show as whatever status the other side returned. ### request blocked: this credential only works in channel sessions, not personal ones **What you see** Claude's request got HTTP 403 with this reason. **What it means** Federated connections work only in Slack channels, where Claude acts under your organization's [agent identity](/docs/claude-tag/concepts/agent-identity). The request came from a direct message, or from another session running under a person's own account, which has no agent identity for the token to name. **How to resolve** Use the connection from a channel whose scope has the bundle attached. No setting enables it in direct messages. ### request blocked: this credential's audience isn't registered as a gateway for this organization **What you see** Claude's request got HTTP 403 with this reason. **What it means** The gateway was removed from the **Gateways** table, but its connection is still in an Access bundle. Claude can't get a token for an address that isn't registered. **How to resolve** To keep the gateway, register the same address again; see [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). To drop it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. ### Claude says Google credentials are not enabled for this organization **What you see** Claude's request got HTTP 403 with the reason "request blocked: Google (gcp) credentials aren't enabled for this organization". **What it means** A Google Cloud identity is connected in a bundle, but Google Cloud federation is off for your organization. **How to resolve** Contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). ### Claude says a Google credential-minting endpoint was refused **What you see** Claude's request got HTTP 403 with the reason "request blocked: this credential has restrict\_credential\_minting set, so Google's credential-minting endpoints are refused". **What it means** The Google Cloud identity was connected with **Block requests that mint new credentials** selected, and Claude tried to call a Google endpoint that creates keys, tokens, or other credentials. The block worked as intended. **How to resolve** Usually nothing: the block worked. If Claude needs that call, review the identity's IAM permissions first, because the block is a safeguard on top of IAM and not a replacement for it. The setting is chosen when the identity is connected, so in the **Cloud roles** table, click **Remove** in the identity's row, and connect the identity again with the **Block requests that mint new credentials** checkbox cleared. ### request blocked: this Google credential only works for requests to Google API hosts **What you see** Claude's request got HTTP 403 with this reason. **What it means** Claude tried to send a Google Cloud credential to a host Google doesn't serve. The credential is attached only to `googleapis.com`, its subdomains, and subdomains of `clients6.google.com`. **How to resolve** If the target is a Google API, check the host Claude used. If it isn't, the request needs a different connection. ### request blocked: this credential's allowed hosts include its own token endpoint **What you see** Claude's request got HTTP 403 with the reason "request blocked: this credential's allowed hosts include its own token endpoint; an admin must remove the token endpoint's host from the allowed hosts". **What it means** The authorization server connection's allowed hosts cover the token endpoint's own host, for example through a wildcard such as `*.example.com` that covers `auth.example.com`. The connect dialog refuses this when the connection is created, and so does every later edit of its allowed hosts, so the message isn't expected; the same rule is checked again on every request. The access token your server returns must never be sent back to the server that issued it, so every request with this connection is refused until an admin fixes it. **How to resolve** In **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, choose **Edit**, and in the **Edit connection** dialog set **Allowed hosts** to only the APIs Claude calls with the returned token, for example `api.example.com`, with no wildcard that covers the token endpoint's host. If the API and the token endpoint share a host, use a different host for one of them. ### credential injection temporarily unavailable; retry the request **What you see** Claude's request got HTTP 503 with this reason, or with "injection capacity exceeded; retry the request". **What it means** Something was briefly unavailable. Anthropic's identity service, your cloud provider's token exchange, or your authorization server answered with a server error (5xx) or 429, or timed out, or a failure moments earlier is still being backed off. **How to resolve** Ask Claude to retry. If one connection keeps failing this way, check that your authorization server or cloud provider is reachable and healthy, then contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). ### injection failed **What you see** Claude's request got HTTP 502 with the reason `injection failed ("")`. **What it means** Most often, the system Claude's identity token was presented to refused the exchange. AWS refused `AssumeRoleWithWebIdentity`, Google Cloud's token exchange refused the token, or your authorization server answered the grant with an error. Claude's reply doesn't say why; for a refused exchange, your own logs do. **How to resolve** Look up the refusal where it happened and fix the configuration it names. | Connection | Where to look | Entry | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS role | CloudTrail, the `AssumeRoleWithWebIdentity` event for the role | [AWS refuses AssumeRoleWithWebIdentity](#aws-refuses-assumerolewithwebidentity) if the event failed. [An AWS request fails after a successful sign-in](#an-aws-request-fails-after-a-successful-sign-in) if the event succeeded, or there is no new event. | | Google Cloud identity | Cloud Audit Logs, the Security Token Service API entry for the token exchange and, if you named a service account, the IAM Service Account Credentials API entry | [Google Cloud refuses the token exchange](#google-cloud-refuses-the-token-exchange) | | Authorization server | Your server's log for the `POST` to the token endpoint | [Your authorization server rejects the grant](#your-authorization-server-rejects-the-grant) | Allow for log delivery delay before concluding there was no attempt. For an AWS role, no new event can also mean Claude reused credentials from an earlier sign-in. See [An AWS request fails after a successful sign-in](#an-aws-request-fails-after-a-successful-sign-in). Otherwise, if your logs show no attempt at the time of the request, the token wasn't issued. [Contact Anthropic](#contact-anthropic) with the details listed there. A gateway connection doesn't produce this error. Your gateway's own response reaches Claude, so Claude reports the status your gateway returned, usually 401 or 403; see [Your gateway rejects every token](#your-gateway-rejects-every-token). ### An AWS request fails after a successful sign-in **What you see** Claude's request to an AWS service got HTTP 502 with the reason `injection failed ("")`. CloudTrail shows that the role's `AssumeRoleWithWebIdentity` event succeeded, or shows no new event because Claude was reusing credentials from an earlier sign-in. Other kinds of request with the same connection may still work. The failure repeats for one kind of request, for example every call to one host or every upload to S3. **What it means** The sign-in worked, but [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) couldn't sign the request with the role's credentials, so it never left for AWS. Claude's reply doesn't say which of these applies: * **A hostname with no usable region.** Agent Proxy reads the AWS service and signing region from the hostname, so the region must be the last label before `amazonaws.com`, as in `service.region.amazonaws.com`, `my-bucket.s3.us-east-1.amazonaws.com`, or `api.ecr.us-east-1.amazonaws.com`. Agent Proxy refuses a hostname with no region, such as `ec2.amazonaws.com`, unless the service is IAM, STS, S3, Route 53, CloudFront, Organizations, or Global Accelerator, which it signs for `us-east-1`. It also refuses a hostname that puts the region before the service name, such as an OpenSearch domain endpoint (`my-domain.us-east-1.es.amazonaws.com`). * **A large request to a service other than S3 with no content hash.** When a request has no `x-amz-content-sha256` header, Agent Proxy hashes the body before signing and refuses a body over 1 MB (1,048,576 bytes). The AWS CLI and SDKs add that header for S3 but usually not for other services. * **An S3 upload sent in chunks.** The AWS CLI (2.23.0 and later) and the AWS SDKs that compute upload checksums by default can send S3 uploads in chunks with a checksum trailer. Agent Proxy can't sign a request in that format. The fix is to have the AWS CLI or SDK send the body in one piece. **How to resolve** | Cause | Do this | | :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hostname with no usable region | Use the service's regional endpoint, `service.region.amazonaws.com` (for S3, also `bucket.s3.region.amazonaws.com`), and make sure that host is in the connection's **Allowed hosts**. A host that exists only with the region before the service name, such as an OpenSearch domain endpoint, can't be reached through a federated connection. [Contact Anthropic](#contact-anthropic) with the hostname. | | Large request to a service other than S3 | Keep the body under 1 MB, or have Claude send the request with an `x-amz-content-sha256` header set to the hex SHA-256 of the body, for example with `curl`. For large data, upload to S3 and pass a reference instead. | | S3 upload sent in chunks | Have Claude set the environment variable `AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED` before running the AWS CLI or a script that uses an AWS SDK, or add `request_checksum_calculation = WHEN_REQUIRED` to the profile in `~/.aws/config`, then retry. To apply it in every thread, add a line to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions), for example "Before using the AWS CLI or an AWS SDK, add `request_checksum_calculation = WHEN_REQUIRED` to the default profile in `~/.aws/config`." S3 still computes and stores a checksum for the object. If the upload still fails, [contact Anthropic](#contact-anthropic). | ### The cloud API answers 403 after a successful exchange **What you see** Claude reports a 403 from an AWS or Google Cloud API, with the provider's own error body rather than a reason beginning "request blocked". **What it means** The token exchange worked and Claude called the API with the exchanged credential, but the role or identity lacks permission for that action. For Google Cloud, the exchange always requests the `cloud-platform` scope, so IAM alone decides what the credential can do. **How to resolve** Grant the IAM permission to the AWS role, the Google Cloud service account, or the federated identity when no service account is named. For AWS, a 403 also makes Claude assume the role again on the next request, so a fix takes effect on the next try. ## Rejections in your own logs ### Your gateway rejects every token **What you see** Every request from Claude gets 401 or 403 from your gateway, including the connection check's token for the **Control subject**. **What it means** One of the standard checks is configured with the wrong value. Your gateway's log of the failing check is the fastest route; if it logs nothing, work down the list. The values to compare against are shown in the **Connect a gateway** dialog before you enter an address, as described on [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway#copy-the-values-and-deploy-the-gateway). **How to resolve** | Check | What to confirm | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Audience | The `aud` claim is a JSON array with one element, your gateway address exactly as the console stored it: `https://` plus the lowercase host, no path or trailing slash. Use your library's audience option rather than comparing the raw claim to a string. | | Issuer | Exactly `https://identity.anthropic.com/agents`, including the path. A verifier configured with any other issuer value, such as the bare host, a different path, or a trailing slash, rejects every token, including the connection check's token. | | Signing keys | Fetched from the JSON Web Key Set (JWKS) named in `https://identity.anthropic.com/agents/.well-known/openid-configuration`. Accept ES256 only. Select the key by `kid`, and refetch the JWKS on an unknown `kid` before rejecting. | | Time | The token expires 10 minutes after issue (`exp`) and is valid from 15 seconds before issue (`nbf`). Check `exp`, allowing up to 60 seconds of clock skew, and make sure your gateway's clock is right. | | Subject | The subject check accepts your listed agents' full subjects and the **Control subject**, or at minimum every subject starting with your **Subject prefix**, `wimse://identity.anthropic.com/org//agent/`, including the `/agent/`. A list that omits the **Control subject** fails the connection check, and a list that omits an agent rejects that agent's requests. | ### Your gateway sees the same token ID on many requests **What you see** Requests within a few minutes of each other carry a token with the same `jti`. A gateway that treats a repeated `jti` as a replay rejects almost everything. **What it means** This is normal. Claude reuses one token for a session's requests to the same gateway for about five minutes, or until your gateway answers 401, and then requests a new one. A plain 403 from your gateway doesn't refresh the token. Exchanges are different: AWS, Google Cloud, and an authorization server each see a token once per exchange. **How to resolve** Don't do per-request replay detection at a gateway. Rely on the signature, audience, expiry, and subject checks. ### Your gateway, trust policy, or IAM binding pins a full agent subject **What you see** One of two things. The connection check passed, but Claude's requests from a channel get 403 from your gateway. Or a gateway mapping, AWS trust policy condition, or Google Cloud IAM binding that matched a full subject ending in `/agent/cagt_...` stopped matching after the Slack channel was deleted and recreated. **What it means** Your rule accepts only specific agents. The connection check's **Control subject** is a reserved agent, so a rule listing it passes the check while rejecting real agents. And each channel's agent has its own ID: deleting and recreating a channel creates a new agent, so a pinned subject no longer appears in any token. By default the sample gateway accepts only the subjects listed in its configuration, and it logs the verified subject of each agent it rejects. **How to resolve** If you pin exact subjects, keep the list current. Log the verified subject of each rejected request, add each new agent's full subject to your rule (and, for a gateway, the **Control subject** with no access), and update the rule whenever a channel is deleted and recreated. The console doesn't display agent IDs, so your own logs are where you learn them. If keeping the list current isn't practical, accept every subject that starts with your **Subject prefix**, `wimse://identity.anthropic.com/org//agent/`, instead, which is the minimum form of the subject check. In the sample gateway, that is an `organization_principals` entry in `config.yaml`. ### AWS refuses AssumeRoleWithWebIdentity **What you see** Claude reports `injection failed` with HTTP 502, and CloudTrail shows an `AssumeRoleWithWebIdentity` event for the role with an error code. **What it means** STS refused to issue credentials for Claude's token. The trust relationship between your role and Anthropic's issuer isn't right. **How to resolve** | CloudTrail error | What to confirm | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `InvalidIdentityToken` | The IAM OIDC identity provider's URL is exactly `https://identity.anthropic.com/agents`, with the `/agents` path (AWS displays it without `https://`), and its audience list includes `sts.amazonaws.com`. | | `AccessDenied` | The trust policy's condition keys start with `identity.anthropic.com/agents:`; the `aud` condition is `StringEquals` on `sts.amazonaws.com`; the `sub` condition matches the token's subject, either `StringEquals` on this agent's full subject or `StringLike` on `wimse://identity.anthropic.com/org//agent/*`. `AccessDenied` also appears when the role was deleted or renamed. | | Any other code | AWS's STS documentation describes it. If the two rows above check out, the token itself is fine. | AWS credentials are reused for up to an hour for the same agent, so several threads' requests can appear under one CloudTrail session, and a trust policy change takes effect only when those credentials expire or AWS answers a request with 403. ### Google Cloud refuses the token exchange **What you see** Claude reports `injection failed ("")` with HTTP 502. Google's token exchange rejected the token, or the service account impersonation that follows it was refused. Claude shows this one message for every refusal from Google, so the message doesn't say which check failed. **What it means** The workload identity pool's provider or attribute condition doesn't accept the token, or the federated identity can't act as the service account you named. **How to resolve** Google records the reason in your Cloud Audit Logs. The Security Token Service API entry covers the token exchange, and, if you named a service account, the IAM Service Account Credentials API entry covers the impersonation. Both are Data Access audit logs, which Google keeps off by default, as described under [Verify the connection](/docs/claude-tag/admins/federated-access/gcp#verify-the-connection). If the logs were on and show no entry at the time of the request, the token wasn't issued; see [injection failed](#injection-failed). Otherwise, work through the checks in order. | Check | What to confirm | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Attribute condition | The provider's attribute condition accepts this token. A condition that lists full subjects must include this agent's subject. A condition on your **Subject prefix**, `assertion.sub.startsWith("wimse://identity.anthropic.com/org//agent/")`, accepts every agent in your organization, as does `attribute.org == ""` if you mapped `attribute.org` from `assertion.tenant`. Comparing the subject to the prefix with `==`, as in `assertion.sub == "wimse://identity.anthropic.com/org//agent/"`, never matches, because every subject continues past the prefix with an agent's ID. Use `startsWith` on the prefix, or `==` on a full subject. | | Issuer, attribute mapping, and audience | The provider's issuer is `https://identity.anthropic.com/agents`, its attribute mapping sets `google.subject` to `assertion.sub` (and `attribute.org` to `assertion.tenant` if your condition or grants use it), and the **Workload identity provider** you entered in the console is the provider's full resource name, which is the token's audience. | | Service account grant | If you named a service account, the federated identity holds a role on it that allows `iam.serviceAccounts.getAccessToken`, such as `roles/iam.workloadIdentityUser`. | ### Your authorization server rejects the grant **What you see** Claude reports `injection failed` with HTTP 502, and your authorization server's log shows a `POST` to the token endpoint answered with a 4xx, typically `{"error":"invalid_grant"}`. **What it means** Your server didn't accept Claude's identity token as a JWT bearer assertion. **How to resolve** | Check | What to confirm | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Grant shape | The token endpoint accepts `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` with the token in `assertion`, plus `resource` and `scope` if you set them, as a form-encoded `POST` with `Accept: application/json`. No `client_id` or client secret is sent, so the endpoint must accept the grant without client authentication. | | Audience | The token's `aud` is your authorization server's issuer identifier exactly as you entered it when connecting the server, or the token endpoint URL exactly as registered if you left the issuer identifier empty, as a one-element array. The **Audience** row of the **Connect an authorization server** dialog shows the value. | | Issuer and keys | As for a gateway: issuer `https://identity.anthropic.com/agents`, keys from its discovery document, ES256 only. | | Subject | Your server must accept only your own agents' full subjects, or at minimum require the **Subject prefix** shown in the **Connect an authorization server** dialog (or pin `iss` and `tenant`, which is the same check). The console's connection check doesn't run for token endpoints, so nothing tests this check for you. | | Response | A JSON body with `access_token`, `expires_in`, and, if `token_type` is present, the value `Bearer`. An `expires_in` under 5 minutes or over 1 day, or a missing one, makes Claude exchange a fresh token on every request, which shows in your log as one grant per request. | Claude doesn't read `error_description`, so put the detail in your server's log rather than in the response. ## Contact Anthropic If no entry resolves the problem, contact your Anthropic account team and include: * Your organization name and the channel where it happened * The time of the failing request, with the time zone * The error text Claude reported, including the HTTP status and the connection's name where the error shows one * For a gateway, the line from your gateway's log; for AWS, the CloudTrail event; for Google Cloud, the audit log entry; for an authorization server, the request and response your server logged Never send a token itself. Anthropic's logs record why a token was refused or not issued, and the time and connection name are enough to find the entry. ## Related resources * [Federated cloud access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use * [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): the setup steps and the connection check in full * [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim, the lifetime, and key rotation * [Limits](/docs/claude-tag/admins/federated-access/limits): counts, lengths, and lifetimes * [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting): errors outside federated cloud access # What the Claude Slack app can access Source: https://claude.com/docs/claude-tag/admins/for-slack-admins What the Claude app reads and posts in Slack, the OAuth scopes it requests, and what installing it does not grant. Written for the Slack admin approving the install. You're approving the Claude app install for someone who's setting up Claude Tag. This page covers what the app can do in your Slack workspace. The rest of setup happens on their side, in the Claude console; you don't need a Claude account. ## Where Claude reads and posts Claude reads and posts only in channels it has been added to, and in direct messages. Any workspace member who opens a direct message with Claude receives its welcome message, whether or not they've linked a Claude account. Installing the app does not add it to any channel. A member can add Claude to a channel in one of two ways: * Invite it with `/invite @Claude` in the channel * Select **Add to channel** on a channel Claude suggests in a direct message. Claude's welcome message, the introduction it posts when a member first opens a direct message with it, suggests public channels this way. A Claude organization admin can also set [auto-join channel patterns](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name), so Claude joins a public channel whose name matches when the channel is created or renamed. When a member selects **Add to channel** or an auto-join pattern matches, Claude adds itself to that channel using its `channels:join` scope. Slack's audit log records the join as the Claude app, with no inviter shown; neither the member's selection nor the matched pattern is visible in Slack's log. If you see a join in the audit log that no one can explain, a member selected one of these buttons or an auto-join pattern matched. Outside those two paths, Claude does not join channels on its own. Reading a channel's full history requires being added there. Workspace search can surface public-channel content, the same as any app with the search scope. Slack Connect channels (shared with another company) are always excluded, regardless of configuration. ## Requested scopes The app requests bot scopes for reading and posting in channels it's a member of, reactions, files, canvases, user lookup, and public-channel search. Slack's install consent screen shows the full current list; treat that as the canonical reference, since the set can change between releases. Two scopes a Slack admin commonly asks about: * `channels:join` lets Claude add itself to a public channel when a member selects one of its suggested-channel buttons, or when the channel's name matches an [auto-join channel pattern](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name) an admin set. It cannot join private channels this way. * `users:read.email` lets Claude read a member's profile email. Claude uses it for checks such as the email domain when a member connects their Claude account. It does not connect accounts; a member still runs the Connect step in Slack. ## What installing does not grant Credentials for GitHub, Google Drive, a data warehouse, or anything else are provisioned separately by a Claude organization Owner and live on Anthropic's side rather than in Slack. It responds when @-mentioned, and may respond to other messages it judges warrant a reply. ## After you install Post `@Claude connect` in any channel with no other text, or send `connect` on its own in a direct message with Claude, and give the code it returns to whoever asked you to install. That code is what pairs your workspace to their Claude organization; it expires after 15 minutes. Pick a channel that belongs to just your workspace. Claude can decline to reply in [guest and shared channels](/docs/claude-tag/admins/troubleshooting#guest-and-shared-channels). ## If you uninstall the app Uninstalling the Claude app from your workspace removes it from Slack and deletes the workspace's Claude data on Anthropic's side, the same way [disconnecting the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing) from the Claude console does. What Claude posted in Slack, such as messages, canvases, and files, stays in Slack under your workspace's own retention settings. On Enterprise Grid, this applies when the app was installed on an individual workspace and you uninstall it there. Removing an org-wide installation, from the whole grid or from one of its workspaces, doesn't delete data on its own; to delete it, ask the Claude organization Owner to disconnect the grid in their Claude settings. ## Related resources * [Security and data handling](/docs/claude-tag/concepts/security-and-data): where credentials are stored and what leaves your workspace * [Pair your Slack workspace](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace): what the Claude Owner does with the code you send # Use Claude Tag at a healthcare organization Source: https://claude.com/docs/claude-tag/admins/healthcare Claude Tag is not covered by Anthropic's Business Associate Agreement. Configure it so protected health information never reaches a channel, direct message, or tool Claude can read: limit Claude to approved channels, turn off direct messages, and connect only PHI-free tools. Also covers what to do if PHI is posted where Claude can read it. Claude Tag, the Claude app that works in your Slack channels, is not covered by Anthropic's Business Associate Agreement (BAA). A healthcare organization can use it for work that doesn't involve protected health information (PHI) by configuring it so that PHI never enters a channel, direct message, or connected tool that Claude can read. This page is for the Claude organization Owner and the compliance lead deciding where Claude works. It describes how to configure Claude Tag so PHI stays out of Claude's reach. It is not legal advice. Review your setup with your legal and compliance teams before you turn Claude on. ## What Claude can read in Slack Claude reads Slack with the same visibility a member of your workspace has. In a Slack workspace connected to your Claude organization, Claude can: * Read and post in the channels it has been added to * Search every public channel by keyword, including public channels it hasn't been added to. [No admin setting turns this search off](/docs/claude-tag/admins/restrict-access#controls-that-aren%E2%80%99t-available) * Read a private channel only after someone in that channel invites it Claude never searches private channels, and it doesn't operate in Slack Connect channels shared with another company. For a healthcare organization, the rule that follows is to keep PHI out of every public channel in the connected workspace, not only the channels where Claude responds, because Claude's keyword search reaches all of them. Keep PHI out of any private channel Claude has been invited to as well. For how Claude's work in each thread is isolated, how connection credentials are held, and where network traffic can go, see [Security and data handling](/docs/claude-tag/concepts/security-and-data). ## Plan and organization requirements Keeping PHI out of Claude's reach needs two things beyond the [general prerequisites for Claude Tag](/docs/claude-tag/admins/setup-overview): * **An Enterprise plan.** Limiting Claude to a list of approved channels uses the **Claude Tag version** setting, which you set separately for the whole workspace and for each channel. Each of those is a [scope](/docs/claude-tag/admins/attach-to-scope). Per-scope version settings are available on the Enterprise plan. * **A Claude organization without Zero Data Retention (ZDR) or customer-managed encryption keys.** Claude Tag stores session transcripts and channel memory, so it [isn't available to an organization with either policy](/docs/claude-tag/concepts/security-and-data). If your organization needs ZDR or customer-managed keys for other Claude products, ask your account team about creating a separate Claude organization without those policies and connecting your Slack workspace to that organization instead. ## Limit Claude to PHI-free channels An Owner turns Claude off everywhere by default, turns it on only in channels approved as PHI-free, turns off direct messages, and blocks channel names that signal PHI. Every setting in these steps is at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Go to **Claude Tag's access** → **Slack** → **Default Slack** → **Advanced** → **Claude Tag version** and set it to **Off**. [Limit Claude Tag to specific channels](/docs/claude-tag/admins/restrict-access#limit-claude-tag-to-specific-channels) has the full procedure. A workspace or channel entry's own **Claude Tag version** setting takes precedence over **Default Slack**, so an entry left on **New** or **Legacy** from an earlier pilot keeps Claude active there. Under **Claude Tag's access** → **Slack**, open each workspace and channel entry whose **Claude Tag version** is **New** or **Legacy** and set it to **Inherit**. Go to **Claude Tag's access** → **Slack**, select the entry for the approved channel, then go to **Advanced** → **Claude Tag version** and set it to **New**. **New** turns Claude on in that channel. If the channel isn't listed under **Slack**, [add the channel with **Add channel**](/docs/claude-tag/admins/attach-to-scope#attach-to-a-channel) first. On the same [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) page, turn off the [**Allow direct messages** toggle](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages). Claude is then reachable only in channels. Go to **Claude Tag's access** → **Slack** → **Default Slack** → **Advanced** → **Blocked channel patterns** and add the naming patterns your workspace uses for clinical or patient channels, for example `*-patient-*`. Claude won't read or respond in a matching channel even if someone invites it. See [Block or auto-join channels by name](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name). Any member of the workspace can still invite `@Claude` to a channel that isn't approved. Claude stays silent there, and an @-mention gets a notice that Claude is disabled in that channel instead of a reply. Only an Owner of your Claude organization can change a **Claude Tag version** setting or the **Allow direct messages** toggle. ## Connect only PHI-free tools In a channel, Claude signs in to tools outside Slack only through the connections an Owner adds, and each connection is attached to specific channels through an [access bundle](/docs/claude-tag/admins/attach-to-scope). For a healthcare organization, apply these rules when deciding what to connect: * Connect only tools that never hold PHI, such as your code host, issue tracker, and internal documentation * Leave electronic health record systems, clinical systems, and patient communication tools unconnected * Treat email and calendar as PHI-bearing unless your compliance team has confirmed otherwise, and leave them unconnected until then * Attach each bundle to the approved channels that need it, not to **Default Slack** (the entry whose settings apply to every channel in every connected workspace), so a connection never reaches a channel it wasn't reviewed for Members' own claude.ai connectors, such as their email or calendar, are a separate path to tools outside Slack. In a direct message, Claude works on the member's own Claude account and can use those connectors, so keep the **Allow direct messages** toggle off as described in [Limit Claude to PHI-free channels](#limit-claude-to-phi-free-channels). In channels, [personal connector use](/docs/claude-tag/concepts/personal-connectors) is available to a limited number of organizations. Ask your account team whether it is enabled for yours before you turn Claude on, and if it is, include members' claude.ai connectors in the tools that must stay PHI-free. ## Train your workspace and monitor approved channels Settings keep Claude out of unapproved channels and tools. They don't stop a person from typing PHI where Claude can read it. Train everyone in the workspace that patient information never goes in a public channel, in a channel Claude has been added to, or in a tool Claude is connected to. Run your data loss prevention tooling on the approved channels to catch mistakes. ## What Claude Tag stores Anthropic stores two things for the conversations Claude works in. The first is a transcript of each conversation, which includes everything Claude read while working. The second is the memory notes Claude keeps for each channel. Memory from public channels goes into one store for the whole workspace, so something Claude noted in one public channel can inform its replies in another channel. Memory from a private channel stays in that channel's own store and isn't read anywhere else. Anyone in a channel can ask Claude what it remembers there and tell it to correct or delete a note. An Owner can view, edit, and delete the memory notes of a channel or of the workspace at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the channel's or workspace's entry → options menu → **View memory files**. By default, your Slack conversations with Claude aren't used to train Anthropic's models. Anthropic's [model training policy](https://privacy.anthropic.com/en/articles/7996885-how-do-you-use-personal-data-in-model-training) describes when data is used. Claude Tag data is kept until one of the admin actions in [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle) deletes it, and during the beta you can't set a shorter retention period. For the full list of what is stored and what each admin action deletes, see [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle) and [What Claude Tag remembers](/docs/claude-tag/users/memory). ## If PHI is posted where Claude can read it Anthropic keeps a transcript of each conversation Claude works in, including the messages Claude read. Deleting a message in Slack doesn't remove it from a transcript that already includes it. If PHI is posted in a channel where Claude is turned on, in any public channel of the connected workspace, or in a private channel Claude has been invited to: 1. Report it to your organization's HIPAA privacy officer and follow your incident process. 2. Delete the message in Slack. 3. If the message was posted in a channel where Claude is turned on, have an Owner delete that channel's transcripts and memory immediately by [removing the channel's entry](/docs/claude-tag/concepts/data-lifecycle#delete-data-or-request-deletion) under **Claude Tag's access** → **Slack**. 4. If that channel is public, have an Owner also check workspace memory, because notes Claude saved from a public channel are stored with the workspace and aren't deleted with the channel's entry. Go to **Claude Tag's access** → **Slack** → your workspace's entry → options menu → **View memory files**, and delete any note that contains the information. Deleting a note removes it from what Claude reads in every channel right away. 5. Email [privacy@anthropic.com](mailto:privacy@anthropic.com) to request deletion of the data Claude Tag retained that the admin controls in steps 3 and 4 don't delete, including the workspace's stored memory and any transcript in another channel whose session found the message through search. Include the workspace, the channel, and the time of the message. Removing a channel's entry also turns Claude off in that channel, because the channel then inherits the **Off** you set on **Default Slack**. To turn Claude back on later, add the channel again under **Claude Tag's access** → **Slack** and set its **Claude Tag version** to **New**. ## Related resources * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): every control that narrows where Claude responds and who can use it * [Security and data handling](/docs/claude-tag/concepts/security-and-data): sandbox isolation, credential handling, and network egress * [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle): what Anthropic stores and how to delete it # Migrate from the earlier Claude in Slack Source: https://claude.com/docs/claude-tag/admins/migrate-from-earlier Claude Tag replaces the earlier per-user Claude in Slack app in place. See what changes, what stays, how the version is chosen per channel, and what existing users notice. If your organization already used the earlier Claude in Slack, including [Claude Code in Slack](https://code.claude.com/docs/en/slack), Claude Tag replaces it. Your existing Slack app and `@Claude` handle stay, and no data migrates. What changes is who Claude acts as and who sets it up. On the Team plan, a single [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) replaces the **Claude Tag version** controls described on this page, and there is nothing to migrate; the switch appears only while no scope routes to the earlier app. ## Switch your workspace to Claude Tag Open [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). If your workspace isn't paired, run [setup](/docs/claude-tag/admins/setup-overview); otherwise you're already on Claude Tag. Once paired, channels and linked-user DMs answer with the New version by default; no per-channel action is needed. Under **Claude Tag's access** → **Slack**, open each scope's **Advanced** section. Pairing defaults every scope's **Claude Tag version** to **New**, so this is usually quick. Set any showing **Legacy** to **New**. The New version starts with no access of its own. GitHub repositories and other connections do not carry over from individual users' linked accounts, so code requests in a switched channel have nothing to clone until you configure them. Follow the [setup overview](/docs/claude-tag/admins/setup-overview) to add connections, and [GitHub access](/docs/claude-tag/admins/configure-github) for code work specifically. If your teams keep custom skills in a repository's `.claude/skills/` folder, those skills apply only in threads that have the repository. Grant the repository in an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle) and have users name it in the first message. To give skills to every channel under a scope, add them through a [skills repository](/docs/claude-tag/admins/skills-repo). Send them [Get started](/docs/claude-tag/users/getting-started). The visible change is that work now belongs to the channel; see [What existing users notice after the switch](#what-existing-users-notice-after-the-switch) below. **You'll see:** the workspace appears under **Where Claude Tag works**, and the **Claude Tag version** on each scope shows **New**. ### If `@Claude` doesn't respond at all On Enterprise Grid, an earlier install can lose its connection and stop responding in every workspace. See [Claude is silent everywhere on Enterprise Grid](/docs/claude-tag/admins/troubleshooting#claude-is-silent-everywhere-on-enterprise-grid) for the reinstall that refreshes it without uninstalling, then send `@Claude connect` again in a channel of that workspace and [pair the workspace](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace) with the new code. The earlier Claude in Slack app, shown as **Legacy** in admin settings, is being deprecated; check with your account team for the cutover date. After that date, channels still set to Legacy stop responding until the scope's Claude Tag version is set to New. ## What stays the same * The Slack app and the `@Claude` handle. Your existing Claude in Slack settings (allowed users, verified-domain restriction) carry over. If your earlier install predates a permission Claude now uses, `@Claude connect` says so when you pair; a Slack admin clicks the install link in that reply and approves the consent screen, which installs over the existing app. Otherwise no app-side action is needed. * Direct messages still run on the user's own claude.ai account, the same way they did before. The shift to a shared identity applies to channels. * Users who already linked their claude.ai account keep that connection. It is what powers their DMs. ## How Claude Tag differs from the earlier app The earlier app linked each user's own claude.ai account, so it answered as that person and used their connectors. Claude Tag has one identity for the team, provisioned by an admin who also sets what it can reach in each channel. | | Legacy (the earlier Claude in Slack) | New (Claude Tag) | | :------------- | :------------------------------------------ | :--------------------------------------------------------- | | Identity | Each user links their own claude.ai account | One agent identity with org-level service credentials | | Sessions | Spawned per request | One persistent session per thread, shared with the channel | | Memory | None | Shared workspace memory plus private-channel memory | | Standing work | None | Routines and channel watching | | Who sets it up | Each user, individually | An Owner, once | The **Claude Tag version** setting on each scope chooses whether the New or Legacy version answers there, or neither. Access bundles only apply where the New version answers. See [Set the version for a scope](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope) for the four values and where to set them. ## Two versions of the same Slack app The earlier Claude in Slack and Claude Tag are two versions of the same `@Claude` Slack app, not two apps, so there is nothing to uninstall. You choose which version answers per scope with the **Claude Tag version** setting (**Off**, **Legacy**, **New**, or **Inherit**), so one workspace can run both during a phased switch. Setting a scope to **Off** turns off both versions there; to keep the earlier behavior in a scope, set it to **Legacy**. To tell which version answered in a channel, look at who authored the work. The New version authors code as the Claude GitHub App and keeps work in the channel's thread; if `@Claude` still opens pull requests under the asker's name, that channel is answering with the Legacy version. ## What existing users notice after the switch In channels, the visible difference is that work belongs to the channel, not to whoever asked. Anyone can reply in a thread to steer it, and the result stays where the team can see and pick it up. Code work is authored by the Claude GitHub App rather than as the requesting user. A user who never linked a claude.ai account can now hand Claude work in channels, by default. Whether that stays open or narrows to organization members is the admin's [access restriction](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude) setting. ## Related resources * [Glossary: the earlier Claude in Slack](/docs/claude-tag/concepts/glossary#the-earlier-claude-in-slack): what each term meant in the old app versus now * [Set up Claude Tag](/docs/claude-tag/admins/setup-overview): the new admin-side setup, since per-user setup no longer applies * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): keep specific channels on the old version during a phased switch # Network requirements Source: https://claude.com/docs/claude-tag/admins/network-requirements Claude Tag reaches your services from a published egress range, over HTTP and HTTPS only. See the IP block to allowlist and how the allowlist relates to the allowed-websites setting on a connection. If a service you want to connect (a data warehouse, an internal API, a GitHub organization with an IP allow list) restricts access by source IP, add Anthropic's egress range to its allowlist. Hand this page to the team that manages it. ## Add Anthropic's egress range to your allowlist Requests from Claude to your services originate from Anthropic's network. To let them through, add Anthropic's published egress range to the service's allowlist: ```text wrap theme={null} 160.79.104.0/21 ``` The authoritative list is [Anthropic's published IP addresses](https://platform.claude.com/docs/en/api/ip-addresses); check it when you create the rule. The range is shared across Anthropic services, and dedicated per-organization egress addresses aren't available, so the allowlist entry admits Anthropic's infrastructure as a whole. Your credential's [allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) are what scope which of *your* systems Claude can call. Allowlist changes on enterprise systems can take days to take effect, which is why the [prerequisites for setup](/docs/claude-tag/admins/setup-overview) send you here before you start setup. ## Internet reachability A connected service must accept traffic from the internet (restricted by IP allowlist if you like). A service reachable only inside your private network can't be connected; private networking such as PrivateLink or VPC peering is not supported. In an Anthropic-hosted environment, every request from a channel's sandbox to your service passes through [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy), which carries HTTP and HTTPS only. A service reachable only over another protocol, such as SSH or a database's native wire protocol, can't be connected; put an HTTP API in front of it instead. ## IP allowlist vs. allowed websites The IP allowlist on your service and the [allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) on a connection are opposite sides of the same boundary: | | IP allowlist | Allowed websites | | :-------------------- | :----------------------------------- | :-------------------------------------- | | **Who configures it** | Your team, on your service | You, on the connection in Claude | | **What it decides** | Which networks may reach the service | Which hosts a credential may be sent to | ## Events and webhooks Events from connected services, like GitHub activity, are delivered directly to Anthropic, so there is no inbound listener to configure on your side. ## Related resources * [Add connections](/docs/claude-tag/admins/add-connections#set-allowed-websites): the allowed-websites setting (the other direction: what Claude is allowed to reach) * [Allow a host without a credential](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential): how hosts become reachable from a channel, including [allow-all egress](/docs/claude-tag/admins/add-connections#allow-all-hosts) * [How agent identity works](/docs/claude-tag/concepts/agent-identity): how credentials are injected at the network boundary * [Setup overview](/docs/claude-tag/admins/setup-overview): back to the console flow once the allowlist is in place # Restrict where Claude Tag operates Source: https://claude.com/docs/claude-tag/admins/restrict-access Claude Tag responds only where it has been added and addressed. See who can invoke it, guest and externally shared channel limits, the per-scope version setting, how to limit it to chosen channels, how to delegate a channel's setup, and how to quiet or remove it. In channels, Claude Tag responds only where it's been added and addressed, and the controls on this page narrow that further. DMs are a separate surface that runs on the user's own account; see [how DMs differ from channels](/docs/claude-tag/concepts/agent-identity#direct-message-channels). Most controls on this page require the Owner role in your Claude organization; the [permissions table](#permissions-by-role) below lists which actions a channel manager or a channel member can take. ## Control who can invoke Claude Tag In channels where the app has been added, an @-mention guarantees a response; Claude may also respond to a message that doesn't mention it when it judges a reply is warranted, and once a thread is active it follows replies in that thread. By default, anyone in such a channel can address it. A single toggle narrows that to people in your Claude organization. ### Restrict who can use Claude At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), under **Where Claude Tag works**, click **Manage** next to **Member access**. The **Claude Tag in Slack** dialog lists your connected workspaces and shows a toggle that controls who in your Slack workspace can use Claude at all; its label depends on your plan. You must be an Owner of your Claude organization to change it. | Plan | Toggle | Off (default) | On | | :--------- | :------------------------------------------- | :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------- | | Enterprise | **Restrict to roles with Claude Tag access** | Anyone in the connected Slack workspace can use Claude, even without a Claude account | Only members whose role grants the **Claude Tag in Slack** capability can use Claude | | Team | **Restrict to your organization** | Anyone in the connected Slack workspace can use Claude, even without a Claude account | Only Slack users with a Claude account in your organization can use Claude | The toggle applies to channels and DMs alike. You may see the earlier three-option **Members** dropdown instead of the toggle. The dialog keeps the dropdown while your organization's stored choice matches neither toggle state. That happens for an Enterprise organization that previously chose **Open to any organization member** (now marked deprecated), and for a Team organization still restricted by role from an earlier Enterprise plan. Switch to one of the toggle's two states. The dropdown is then replaced by the toggle, and the deprecated option is no longer offered. #### Restrict by role on Enterprise Role restriction requires an Enterprise plan. Team plans don't have role-level control; turning on **Restrict to your organization** is the only restriction available there. Restricting by role spans three console pages. 1. On [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), turn on **Restrict to roles with Claude Tag access**. 2. On [`claude.ai/admin-settings/groups`](https://claude.ai/admin-settings/groups), create groups and add the relevant members. 3. On [`claude.ai/admin-settings/roles`](https://claude.ai/admin-settings/roles), create a custom role with the **Claude Tag in Slack** capability turned on or off, and choose which groups hold the role in the role editor. Three rules govern how role restrictions resolve. * **The toggle gates the capability.** The **Claude Tag in Slack** capability on a role has no effect until **Restrict to roles with Claude Tag access** is on. While the toggle is off, every member can use Claude regardless of what their role grants. * **Built-in roles always grant access.** Every built-in role, including User, Owner, and Primary owner, grants **Claude Tag in Slack** automatically, so the restriction only blocks members on a custom role that doesn't grant it. * **Any grant wins.** A member in more than one group keeps access if any of their roles grants it. A member whose roles don't grant the capability is excluded everywhere Claude works, in three ways: * **@-mentions and DMs get a private notice.** Claude doesn't act on the request. The member sees a notice only they can see, saying their role doesn't allow Claude Tag and to ask their admin for access. * **Automatic replies skip them.** In channels where Claude responds without being tagged, a restricted member's messages never trigger a response. * **Their thread replies aren't read.** In a thread an allowed member started, a restricted member's replies don't reach Claude as content. Claude sees that a message arrived, but the message body is withheld. On a Slack Enterprise Grid whose workspaces are paired to different Claude organizations, one organization's access settings govern the entire grid, so your restrictions may not be enforced in your own workspaces. ### Restrict who can link a Claude account by email domain On Enterprise plans, if your organization belongs to a parent enterprise organization, you see one more toggle in the same **Manage** dialog, **Restrict to your verified domains**. It needs an Owner to change and is disabled while Claude Tag is off for the organization. The check uses the enterprise's verified domains, which every organization under the enterprise shares. When the toggle is on, a Slack user whose profile email isn't on one of the enterprise's verified domains can't link a Claude account to this organization; the sign-in is refused. Turning this on in any one organization also stops Slack users on a verified domain from linking a Claude account to any organization outside the enterprise. ## Control where Claude Tag operates The restriction toggle decides who can use Claude. The controls in this section decide where it works at all, from one channel up to a workspace, and which generation answers in each scope (a scope is a channel, a workspace, or your whole organization). On the Team plan, a single [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) replaces the per-scope version controls. The other controls in this section work the same way on both plans. ### Quiet or remove Claude Tag Six ways to stop Claude Tag from responding, ordered from quietest to most complete: 1. **Ask it to stay quiet.** Saying "stay quiet in this thread unless tagged" stops Claude following an active thread. 2. **Remove it from the channel.** Run `/remove @Claude`. It can no longer read or post there. 3. **Set the scope's Claude Tag version to Off.** Claude stops responding in that scope even if someone invites it back; an @-mention gets a disabled notice instead of a reply. Only an Owner can change it, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the scope → **Advanced** → **Claude Tag version**. If you have the [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) instead, turn it off at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag**. Claude then stops responding in every connected workspace, not in one scope. 4. **Remove the channel's scope.** Choose **Remove this scope** from the scope's options menu. Claude keeps answering in the channel with the access it inherits from its workspace, and deletes the channel's sessions, memory, routines, and published artifacts; see [what each action deletes](/docs/claude-tag/concepts/data-lifecycle#actions-in-claude). To stop it answering as well, run `/remove @Claude` or set the scope's version to **Off** first. 5. **Delete the bundle.** This revokes its credentials everywhere it was attached (the credentials are removed; memory, routines, and transcripts are not). Running sessions may keep a revoked credential for a short window before the change propagates. 6. **Uninstall the app.** This removes Claude from the workspace and deletes the workspace's Claude data the same way [disconnecting the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing) does. To keep Claude out of channels by name ahead of time, add a [blocked channel pattern](#block-or-auto-join-channels-by-name) instead. Steps 1–3 do not delete any data. Removing Claude from a channel stops it responding there; the channel's memory and routines stay on record, and re-adding Claude restores them. Steps 4 through 6, and disconnecting the workspace, each delete something different: * **Remove the channel's scope (step 4):** deletes the channel's sessions, memory, routines, and published artifacts. Claude keeps answering in the channel with the access it inherits from its workspace; see [what each action deletes](/docs/claude-tag/concepts/data-lifecycle#actions-in-claude). * **Delete the bundle (step 5):** removes the credentials in that bundle. Memory, routines, and session transcripts stay. * **Uninstall the app (step 6):** Anthropic deletes the workspace's Claude data, the same set as disconnecting the workspace, plus the app's installation credential; see [what each action deletes](/docs/claude-tag/concepts/data-lifecycle#actions-in-slack). * **[Disconnect the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing)** at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): Anthropic deletes the workspace's sessions and transcripts, memory, routines and artifacts, scopes, and members' account links, and the app stays installed so a workspace admin can pair again; see [what each action deletes](/docs/claude-tag/concepts/data-lifecycle#actions-in-claude). Access bundles belong to your organization, not to a workspace, so uninstalling or disconnecting keeps them; only their bindings to that workspace's scopes go. To delete one channel's data while Claude stays in the workspace, remove that channel's scope (step 4) rather than uninstalling. ### Limit Claude Tag to specific channels To let Claude respond only in channels you choose, for example during a pilot confined to one channel, turn the [version setting](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope) **Off** everywhere and switch the chosen channels back to **New**. Both changes happen in the **Claude Tag's access** section at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). DMs, guest channels, and shared channels need more than the version setting; each gets its own treatment after the steps. These steps need the per-scope version controls. If you have the [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) instead, you can't limit Claude this way. Use [blocked channel patterns](#block-or-auto-join-channels-by-name) to keep it out of specific channels. **Off** silences the earlier Claude in Slack too. If you're in the middle of migrating from the earlier app, decide which scopes stay on **Legacy** before you start; the earlier app keeps answering in those channels. The control is at [**Default Slack access**](/docs/claude-tag/admins/attach-to-scope) > **Advanced** > **Claude Tag version**. Set it to **Off**. Open each workspace or channel scope set to **New**, and each one set to **Legacy** that you aren't keeping on the earlier app, and set its **Claude Tag version** to **Inherit**. Find the channel with **Search channels**; channels Claude was added to are already listed. If it isn't listed, create a scope for it with **Add channel** as described in [Attach to a channel](/docs/claude-tag/admins/attach-to-scope#attach-to-a-channel). The control is at the channel's scope > **Advanced** > **Claude Tag version**. Set it to **New**. A channel's own setting wins over the **Off** above it, so Claude responds in the chosen channels and nowhere else. If someone invites the app into another channel afterward, Claude stays silent there. Mentioning `@Claude` in that channel gets a notice that Claude is disabled in the channel, not a reply. DMs, guest channels, and shared channels sit outside the version setting: * **DMs.** The version setting doesn't cover them. To close those off too, turn off the [**Allow direct messages**](#allow-or-disable-direct-messages) toggle. * **Guest channels.** By default Claude is off in any channel that includes a Slack guest. If a chosen channel has guests, also set [Allow Claude to work in channels with guests](#restrict-guest-channels) to **Allow** or **Channel only** on its scope. * **Shared channels.** A [channel shared across workspaces in your Enterprise Grid](#channels-shared-across-workspaces-in-your-enterprise-grid) takes its settings from **Default Slack access** only, and Claude [doesn't operate in Slack Connect channels](#externally-shared-channels) at all; neither can serve as a chosen channel. To control who can use Claude in the allowed channels, turn on the [restriction toggle](#restrict-who-can-use-claude); to cap what a channel spends, [set a per-channel spend limit](#set-spend-limits). ### Block or auto-join channels by name **Channel name rules** steer where Claude works by channel name instead of channel by channel. The rules sit in the **Advanced** section of the **Default Slack access** panel and of each workspace scope's panel at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), as two pattern lists: * **Blocked channel patterns**: Claude won't read or respond in a channel whose name matches, even if someone invites it there. When it's added to such a channel or @-mentioned in one, it posts a notice that an admin has blocked it there, and otherwise stays silent. * **Auto-join channel patterns**: Claude joins a public channel whose name matches when the channel is created or renamed. Private channels still need an invite. To add Claude to an existing channel, invite it as usual. A pattern is written in lowercase, like Slack channel names, plus two wildcards: `*` matches any run of characters and `?` matches exactly one. `inc-*` matches every channel whose name starts with `inc-`, and `*-confidential-*` matches any name containing `-confidential-`. Each list holds up to 50 patterns of up to 80 characters. A channel that matches a blocked pattern stays off-limits even when it also matches an auto-join pattern. Patterns on **Default Slack access** apply in every connected workspace. A workspace scope can add its own patterns but can't remove the organization's. ### Restrict guest channels By default, Claude is disabled in any channel that includes a Slack guest. You can change this default per scope with the **Allow Claude to work in channels with guests** setting, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the scope → the collapsed **Advanced** section. The setting has three values: | Value | What Claude does in a channel that includes a guest | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Restrict** (default) | Doesn't reply. When someone mentions it, Claude posts a short notice that it doesn't respond in channels that include guests, with a link to this setting. | | **Channel only** | Replies, but while a guest is present it runs with [channel-only access](#how-channel-only-works). The channel's own instructions and any access bundle attached directly to the channel still apply. | | **Allow** | Replies with the full access the scope gives it. Bundles, connections, and instructions from the workspace and from **Default Slack access** apply, along with repositories, memory, and skills. | A channel without its own value shows **Inherit** and takes the value from its workspace, or from **Default Slack access**. Only an organization Owner can choose **Allow** or set a scope back to **Inherit**. The setting applies to every guest channel the scope covers. To open one channel rather than a whole workspace, set it on the channel's own scope. Under every value, guests in the channel can read what Claude posts there. In any channel that includes a guest, even under **Allow**, Claude won't search the workspace, look up people or channels, or read channels other than the one it's in. The results could include content the guests can't see in Slack, which is also why Claude doesn't search private channels. To have Claude search, look someone up, or read another channel, ask from a channel without guests. #### How Channel only works Use **Channel only** to keep Claude available in a channel shared with contractors, clients, or agency partners without exposing the rest of the organization's setup to that conversation. While a guest is in the channel, Claude has: * No [access bundles](/docs/claude-tag/admins/attach-to-scope) from the workspace or from **Default Slack access**. A bundle attached directly to this channel's scope still applies, with its connections, instructions, and plugins. Attach to a guest channel only what you're comfortable with Claude using in a conversation guests can read. * No connections set directly on the channel. * No repositories, including any in a bundle attached to the channel. * No instructions set on the workspace or the organization. Instructions set on the channel itself still apply. * No memory, including this channel's own, and no skills. * No [environment set on the scope](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope). The session runs on the standard environment, so the setup script, environment variables, and network access level of the environment you chose don't apply while a guest is present. Claude decides which access applies when a conversation starts. When no guest is in the channel, new conversations get full access, as under **Allow**. A conversation that was underway before the first guest joined doesn't keep its full access. The next message from a workspace member in that thread starts the conversation over with channel-only access. A guest who writes there before a member does gets the same notice as under **Restrict**. While a guest is present, Claude replies only to mentions and to threads it's already part of. It doesn't act on other messages in the channel on its own, even where [**Respond automatically**](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off) is on. A guest can talk to Claude by mentioning `@Claude` or by replying in a thread Claude is part of, and Claude answers them. A guest can't approve a tool or permission request, and can't restart, mute, fork, or stop the session. If a guest clicks approve, nothing is granted. Treat a channel's instructions, and the instructions in any bundle attached to the channel, as visible to everyone in that channel, including guests. Under **Channel only**, Claude follows them in replies that guests can read and respond to. **Channel only** takes effect where the **New** [Claude Tag version](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope) answers. On a scope where **Legacy** answers, a channel that includes a guest is treated as **Restrict**. ### Externally shared channels Claude doesn't operate in Slack Connect channels, the ones shared with another company. It's off in those channels regardless of scope or bundle, and this isn't configurable. ### Channels shared across workspaces in your Enterprise Grid What happens in a channel shared across more than one workspace inside your Enterprise Grid depends on whether every workspace in it is connected to the same Claude organization. When the workspaces all belong to your one Claude organization, Claude replies in the channel, but only with the access and settings on your organization's [Default Slack access](/docs/claude-tag/admins/attach-to-scope) scope. Bundles, instructions, and memory set on a workspace or on that channel don't reach it. Claude posts a notice in the thread explaining this, about once a month per channel at most rather than on every reply. Where guest access is at its default **Restrict**, the [guest check](#restrict-guest-channels) still runs first and can refuse the reply. When the workspaces belong to different Claude organizations, each with its own settings and plan, Claude won't reply and posts a refusal message instead. There is no per-channel override for either case. ### Migrate from the earlier Claude in Slack If your organization used the earlier Claude in Slack app, the **Claude Tag version** setting on each scope chooses which generation answers `@Claude` there. Access bundles only apply where the New version answers. See [Set the version for a scope](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope) for the values and [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/migrate-from-earlier) for the switch. ### Allow or disable direct messages The **Allow direct messages** toggle controls whether members can message Claude directly. When it's off, Claude is reachable only in channels. The default is on, and you must be an Owner of your Claude organization to change it. On [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), the toggle appears in one of two places: directly on the Claude Tag settings page, or in the **Manage** dialog on the Slack entry under **Where Claude Tag works**. It's the same setting in both places, so change it wherever it appears for your organization. ### Set spend limits Spend limits live at [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag), a different page than the main Claude Tag settings; see [when the usage page is available](/docs/claude-tag/admins/set-spend-limit#set-the-spend-limit). Spend trends and per-channel reports live on a separate analytics page; see [Usage analytics](#usage-analytics) below. A spend limit is a cap on how much of your organization's usage balance Claude Tag can draw each billing period. Setting a limit doesn't fund the balance; on a Team plan, [fund the usage balance first](/docs/claude-tag/admins/set-spend-limit) or Claude won't respond in channels regardless of the limit. * **Organization-wide limit.** Caps total Claude Tag spend across every channel. * **Default spend limit.** A default limit applied to each channel that doesn't have its own. * **Per-channel limits.** Set on any channel from its row in the per-channel spend table, in addition to the organization limit. A channel doesn't need its own scope to take a limit. * **Per-channel spend.** How much each channel has spent against its limit in the current billing period, at list price, on the same page. Usage covered by a promotional credit isn't counted here and shows as \$0.00. The **Spend by channel** table at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag) shows list-price spend including covered usage. Work that would exceed a limit is declined rather than silently truncated. A user blocked by a limit can request more usage from their admin in Slack, and the admin notification names whether the usage balance or the limit caused the block. ### Usage analytics Spend trends live at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag), the Claude Tag section of the Analytics dashboard, refreshed once a day. It shows total and projected month-end spend for the period you pick, spend by channel with a CSV export, DM versus channel spend, [spend by kind of work](/docs/claude-tag/admins/set-spend-limit#see-spend-by-kind-of-work), and any promotional credit. Billed figures are shown after your discount. Anyone with permission to view your organization's Analytics dashboard can open it; it has no controls, so use the usage page to change a limit. The two pages link to each other. When the period you pick falls within the current month, the **Spend by channel** table shows a **Billed** column and a **List price** column. Usage covered by a promotional credit shows as \$0.00 under **Billed** and at its list price under **List price**. ## Delegate channel setup to channel managers A channel manager is a member of your Claude organization who can set up Claude in specific channels without the Owner role. Channel managers are available on the Enterprise plan, and you must be an Owner to add or remove them. You name channel managers one channel at a time. For that channel, a channel manager sets the default model, adds repositories, manages credentials and plugins in the channel's bundle, and edits channel instructions. Every other setting at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) stays with Owners. ### What a channel manager can do on the Configure page A channel manager has to be a member of the channel in Slack. The channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel), reached from the **Configure** link in any Claude reply, is split into tabs. In a channel you assigned to them, a channel manager sees the **Default model** card on the **General** tab and the repository and access bundle cards on the **Tools and access** tab. Members without the role don't see those cards. Owners and Admins also see an **Admin** tab, whose **Channel settings** card holds some of the channel scope's settings from admin settings. | Setting | What a channel manager can do | | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Default model** | Choose the model new threads in the channel start on, from the models your organization allows. **Inherit** keeps the workspace or organization default | | **Repositories** | Add repositories beyond the ones your bundles already grant the channel. They can add only repositories their own GitHub account is an admin of | | **Access bundles** | Add, rotate, test, and remove credentials, and turn [plugins](/docs/claude-tag/admins/add-connections#attach-plugins) on or off, in the bundle Claude created for the channel and in any bundle they created for it. If the channel has no bundle yet, they can create one. They can't edit a bundle you created or a bundle that other channels share | When a channel manager adds a credential, Claude also allows the host that credential uses. Channel managers can't change the bundle's domains or rules in any other way. Credentials that use Claude's own identity (mutual TLS, AWS or GCP service identity, and IAP) stay Owner-only: a channel manager can't add, change, or rotate one, but can delete one from the channel's bundle, including one an Owner added. If that happens, Claude loses access to that service until an Owner adds the credential back. If you detach the channel's own bundle from the channel, its channel managers can't save settings for the channel; they see an error saying the channel's configuration was suspended by an administrator. They don't get a new bundle. Attach the bundle again to restore their access. A channel manager can edit channel instructions even when the scope's [Channel member edits](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) setting is **Block**. Channel managers see their assigned channels at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag); organization and workspace settings are read-only for them. Tell them when you add them. ### Add a channel manager Channel managers are built on [custom roles](https://claude.ai/admin-settings/roles). When you add the first manager to a channel, you create a custom role for it, named **Channel managers** plus the channel's name and ID, with the **Claude Tag channel setup** permission. A custom role works only for members on the **Custom roles** access level, so the last step below checks each manager's level. At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), select the channel's row on the **Slack** tab under **Claude Tag's access**. The channel must be a public or private channel. If it isn't listed, [add Claude to the channel](/docs/claude-tag/users/getting-started#add-claude-to-a-channel) in Slack first. In the panel's header, select the people-icon button labeled **Add channel managers who can add connections and repos to this channel**. In the popup, select **Add users** to add people, which also creates a group named after the channel, or **Add groups** to add a group from [`claude.ai/admin-settings/groups`](https://claude.ai/admin-settings/groups). The same group can manage several channels. When you add a member on the User or Claude Code user level, you move them to the **Custom roles** level in the same step; if they already hold other custom roles, you confirm the move first. For a member on any other level, you see **Not in effect** until you change their level on the Members page. Adding a group changes nobody's level; group members who aren't on the **Custom roles** level show **Not in effect** too. If your identity provider manages access levels, you can't change a level on the Members page, and the move doesn't happen. Put the channel managers in an identity provider group and map that group to the **Custom roles** level instead. If you turn on identity provider management after adding channel managers, the next sync sets every member's level from your group mappings, so managers you moved by hand show **Not in effect** until a mapped group covers them. The role and its group are kept; you don't need to add the managers again. Owners and Admins can already configure every channel, so you see them as **Already has full access** and can't add them. Leave the role as it was created: assigned to its channel, with **Claude Tag channel setup** as its only permission. If the role's permissions are changed on the Roles page, the channel's channel-managers popup stops recognizing the role and refuses to add or remove any, with a notice that points you to the Roles page. To recover, set the role's permissions back to exactly **Claude Tag channel setup**; the group and its members are kept. To give channel managers any other permission, create a separate role for it. ### Remove a channel manager To remove a channel manager, open the same popup from the people-icon button on the channel's panel. The current managers are listed under **Channel managers**. Remove a member you added directly, or detach a group you added. The member keeps their access level and any other custom roles. The manager cards on the channel's Configure page disappear for them. ### Verify a channel manager's access The popup behind the people-icon button on the channel's panel shows each manager's status under **Channel managers**. A member whose access level doesn't support the role appears as **Not in effect**; the role works only on the **Custom roles** access level, so change the member's level on the Members page to put it into effect. An active manager sees the **Default model**, repository, and access bundle cards on the channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel), so asking them to open that page confirms the setup. ### Audit channel manager activity Channel manager activity is recorded in your organization's audit log, which you read through the [Compliance API](https://platform.claude.com/docs/en/api/compliance). The log records: * **Role channel assignments.** When a channel is assigned to a channel manager role or removed from it, with the role and the number of channels before and after. * **Credential changes.** Each credential a channel manager creates, updates, rotates, or deletes, with the Slack workspace and channel it was for and the roles that granted the permission, so you can tell a channel manager's change from an Owner's. Secrets are never included. * **Configure page changes.** Which settings a channel manager saved from the Configure page, such as the default model, repositories, or channel instructions. The log records which fields changed, not the values entered. The [Audit page](/docs/claude-tag/admins/audit) at [`claude.ai/admin-settings/claude-tag/audit`](https://claude.ai/admin-settings/claude-tag/audit) doesn't list these events; it covers scheduled work, memory, and network events. ## Permissions by role Creating bundles, binding them to scopes, and pairing workspaces need an Owner. A [channel manager](#delegate-channel-setup-to-channel-managers) configures only the channels assigned to them. Everything else happens inside the channel and is open to its members. The table lists each action and who can take it. | Action | Owner | Channel manager | Channel member | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------ | :-------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | Pair a workspace | Yes | No | No | | Create, rename, delete, or bind an Access bundle | Yes | Only to create a bundle for an assigned channel | No | | Edit a bundle's Repositories, Domains, or Instructions tab | Yes | No | No | | Edit a bundle's Credentials or Plugins tab | Yes | Yes, in a bundle created for an assigned channel | No | | Add a channel manager | Yes | No | No | | Set a channel's default model or repositories from the Configure page | Yes | Yes, in assigned channels | No | | Set a channel's default model by asking Claude in a thread, unless the scope's [Channel member edits](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) setting is **Block** | Yes | Yes | Yes | | Write channel memory | Yes, in the channel | Yes, in the channel | Yes | | Set channel instructions from the Configure link | Yes | Yes, in assigned channels | Yes, unless the scope's [Channel member edits](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) setting blocks it | | Create, list, or disable a scheduled job in the channel | Yes, in the channel | Yes, in the channel | Yes | | Remove Claude from a channel | Yes | Yes, with `/remove`, unless your Slack admin restricts it | Yes, with `/remove`, unless your Slack admin restricts it | Scheduled jobs run with the channel's credentials, so a member creating one can't reach anything the channel itself can't. ## Controls that aren't available These are controls an admin might look for that Claude Tag doesn't have. * **Third-party deployment.** Claude Tag runs on Anthropic's first-party service; it isn't available through third-party deployments. * **Renaming or rebranding the app.** The Claude app's name, @-handle, and avatar in Slack are fixed; there is no per-workspace rename setting. * **Per-user spend caps on channel work.** Spend limits apply at the organization and channel level. There's no way to cap what one member can spend in channels; DM usage bills to that member's own seat and follows the seat's usual limits. * **Per-channel responder allowlist.** The restriction toggle governs who can invoke Claude across the workspace; you can't narrow it to a list of people for one channel only. * **An open-internet switch in Claude Tag settings.** A channel sandbox reaches only allowed hosts. To let Claude reach a public site or API, an Owner adds that hostname on a [bundle's Domains tab](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential); for broad web access, they pin an [environment](/docs/claude-tag/concepts/glossary#environment) whose network access level is Full access on the scope. [Allow-all egress](/docs/claude-tag/admins/add-connections#allow-all-hosts), a `*` entry on the Domains tab, is off by default and enabled per organization by Anthropic. * **A web search toggle for channels.** No setting turns web search off for channel sessions; the web search capability setting in claude.ai admin settings governs claude.ai chat, not channels. Web search runs on Anthropic's servers rather than from the channel sandbox, so Domains entries and egress settings don't govern it, and a search opens no new path out of the sandbox; search requests travel to Anthropic the same way the session's model traffic already does. See [Web search vs. network requests](/docs/claude-tag/concepts/agent-identity#web-search-vs-network-requests). * **Read-scope confinement.** Claude can search public channels by keyword the same way any Slack user can; it can't read a channel's full history unless it's been added there. There's no setting to disable workspace search, and no setting to enable it in [channels that include guests](#restrict-guest-channels), where search is unavailable. * **Session length enforcement.** Your organization's Slack session-length policy is not enforced on this surface. ## Related resources * [Configure per-channel access](/docs/claude-tag/admins/attach-to-scope): change the scopes these controls apply to * [How agent identity works](/docs/claude-tag/concepts/agent-identity): the model these controls operate on * [Security and data handling](/docs/claude-tag/concepts/security-and-data): what these controls don't cover (data flow, retention, where credentials are stored) * [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle): which of these controls delete data and which only stop Claude responding # Set a spend limit Source: https://claude.com/docs/claude-tag/admins/set-spend-limit Claude Tag draws from your organization's usage balance, not individual seats. See whether you need to fund usage, how to set the spend limit, and what happens when it's reached. Work Claude does in channels bills to your **organization's usage balance**, not to individual seats. The **spend limit** is a cap you set on how much of that balance Claude Tag can use each month. | Work | Bills to | Capped by | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------- | :------------------------------------------------------------------------------------------------------- | | Channel work | Your organization's usage balance | The spend limit, plus any [per-channel limits](/docs/claude-tag/admins/restrict-access#set-spend-limits) | | Reading a channel, [deciding whether to reply](/docs/claude-tag/users/when-claude-responds#what-claude-does-with-a-channel-message), and short replies from what Claude already knows | Nothing | Not counted toward any limit. A working session Claude starts from the channel is channel work, above | | A DM with Claude | The sender's own seat | The seat's usual limits, not the spend limit | ## Whether this step is required depends on your plan | Your plan | What you need to do here | | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Team** | **Required, before anything runs.** A Team plan has no usage balance until it's funded, and Claude won't respond in channels until it is. A [launch usage credit](https://support.claude.com/en/articles/15575654-claude-tag-launch-promo-for-claude-team-and-enterprise) counts as a funded balance, so check for one before buying credits. Then set a spend limit. | | **Enterprise (invoiced)** | **Recommended.** Usage bills to your invoice with no upper bound until you set a spend limit. Set one to cap exposure during the pilot. | ## Set the spend limit Not every organization sees this page. A trial organization that hasn't enabled usage billing, a single-seat Team plan, an organization with a hybrid desktop deployment, or an admin whose role can't view billing is redirected to personal usage settings instead. If your organization bills through a reseller, the page is not available and these steps don't apply; your organization's usage is funded through the reseller instead. Go to [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag). Enter an amount in your organization's billing currency. The spend limit resets at the start of each month and applies across every paired workspace. You can change it any time. There's no published per-task cost guidance. For a pilot, set a spend limit you're comfortable with for the first month, then watch the per-channel usage breakdown on the same page and adjust. If a promotional credit covers the pilot's usage, that breakdown shows \$0.00. In that case, watch the **List price** column of the **Spend by channel** table at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag) instead. ## What happens when the spend limit is reached When usage reaches the spend limit, Claude stops and tells the requester in the thread that it couldn't finish. The requester can ask an admin to raise the limit. The spend limit counts usage at list price. If your organization has a negotiated discount, that discount applies at invoice time, not to the cap. ### Rate limits versus the spend limit The spend limit caps how much your organization is charged. It doesn't change how fast Claude can work. Claude Tag also applies its own throughput limits on how quickly threads can be started and messages delivered, and an organization with many busy channels can hit one while the spend limit still has plenty of room. When that happens, Claude tells the requester in the thread that it hit a rate limit and names a short wait, usually a few seconds. Re-send the message after the wait. Raising the spend limit doesn't clear a rate limit, and a rate-limited request doesn't spend anything. | Claude says | Limit reached | What to do | | :--------------------------------------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------- | | The spend limit is reached | Spend limit | Raise it on the usage page above | | It hit the session rate limit, or is rate limited delivering a message | Throughput limit | Wait the few seconds the reply names, then re-send. If your organization hits this often, contact your account team. | ## Per-channel limits Per-channel limits and the per-channel spend breakdown are on the same usage page. See [Set spend limits](/docs/claude-tag/admins/restrict-access#set-spend-limits) for the full set of controls. ## Attribute costs by channel In claude.ai you see spend per channel, not per user. Channel work bills to your organization's usage balance, not to any user's seat. The usage page at [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag) shows spend broken down by channel, at list price. Usage covered by a promotional credit isn't counted there and shows as \$0.00. To see each channel's list-price spend for the current month including covered usage, use the **List price** column of the **Spend by channel** table at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag). To attribute spend to teams or departments for showback or chargeback reporting, structure channels so each maps to one team or department, and give those channels [their own scopes](/docs/claude-tag/admins/attach-to-scope). The per-channel breakdown then reads as your per-team report, and per-channel spend limits act as team-level budgets. Organizations on a Claude Enterprise plan can also pull channel spend per Slack user from the Analytics API, which attributes Claude's channel work to individual Slack users. See [Attribute costs to users](/docs/claude-tag/admins/attribute-costs). DMs are separate. A DM bills to the sender's own seat, not to the organization's usage balance. ## See spend by kind of work On the analytics page at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag), you see channel spend split into four categories. The page refreshes once a day, so today's activity appears tomorrow and a new month is empty until its first complete day. The split shows which kind of work is driving spend. For each billed category you see its share of channel spend over the period you pick; Monitoring shows as not billed. The shares are approximate; for exact amounts, use your invoice. * **Engaged**: threads where someone @-mentioned Claude, replied to Claude, or asked it for a reminder * **Proactive**: work Claude picked up or started on its own, before anyone addressed it * **Scheduled**: recurring scheduled work * **Monitoring**: Claude reading the channels it belongs to, which isn't billed Reading a channel Claude belongs to, whether or not anyone tags it, doesn't draw from the usage balance. When Claude starts a working session on its own, that session bills to the balance under Proactive. To stop Claude from starting work on its own in a channel, turn off the channel's [Respond automatically](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off) setting. DMs aren't included, because they bill to the sender's seat. ## Related resources * [Verify your setup](/docs/claude-tag/admins/setup-overview#verify-your-setup): run a first task in a channel * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access#set-spend-limits): per-channel limits and the usage page in full # Set up Claude Tag Source: https://claude.com/docs/claude-tag/admins/setup-overview Set up Claude Tag for your organization: pair your Slack workspace, choose and connect Claude's tools, set a spending limit, launch, and test that it works. Every step on one page. Claude Tag is Claude working in your team's Slack channels. It can also act in your other tools, like your issue tracker or data warehouse, through accounts you create for it during setup. Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) and click **Start setup** (**Resume setup** if you started earlier). The setup page walks you through these steps in order. This page covers each one in the same order, and each section says what to have ready before the step and what each choice means. 1. [Pair your Slack workspace](#pair-your-slack-workspace): install the Slack app and redeem a pairing code 2. [Choose Claude's first tools](#choose-claude%E2%80%99s-first-tools): select at least two tools 3. [Connect GitHub](#connect-github): install the Claude GitHub App and grant repositories 4. [Create accounts for Claude's other tools](#create-accounts-for-claude%E2%80%99s-other-tools): one account and API key per tool 5. [Launch Claude Tag](#launch-claude-tag): set the monthly spend limit and turn Claude Tag on The console saves your progress, so you can leave and come back to where you stopped. When you've launched, [verify your setup](#verify-your-setup). | Prerequisite | Why you need it | If you don't have it | | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A **Team or Enterprise plan** on claude.ai | Claude Tag is available on Team and Enterprise plans, on Anthropic's first-party service. It isn't available on individual plans (Free, Pro, or Max), or for third-party deployments. | Start a Team or Enterprise plan at [claude.com/pricing](https://claude.com/pricing) | | A Claude organization **without Zero Data Retention (ZDR) or customer-managed encryption (CMEK)** | Claude Tag stores channel memory and session transcripts, which ZDR doesn't permit. A CMEK policy doesn't allow Claude Tag either. | Claude Tag isn't available to organizations with a ZDR or CMEK policy | | **Routines** enabled for your Claude organization | Until it is, Claude answers every mention and DM with a reply that it's unavailable and does no work. | An admin enables Routines at [`claude.ai/admin-settings/claude-code`](https://claude.ai/admin-settings/claude-code) | | **Owner** role in the Claude organization you're setting up | Pairing a workspace and creating Access bundles are Owner-only writes. Roles are per organization, so being an Owner elsewhere doesn't carry over. | Ask an Owner to run setup, or have one promote you at [`claude.ai/admin-settings/members`](https://claude.ai/admin-settings/members) | | A **Slack workspace admin** | Running `@Claude connect` requires a Slack workspace admin; installing the app usually does too. | If that's someone else, [send them the install request](#if-you-re-not-the-slack-workspace-admin) early (app approval can take time), and plan to be online together when you pair; pairing codes expire 15 minutes after they're issued | | **Usage credits** (Team plans) | Channel work draws from your organization's usage balance; on a Team plan nothing runs until credits are loaded. | Check whether your organization has a [launch usage credit](https://support.claude.com/en/articles/15575654-claude-tag-launch-promo-for-claude-team-and-enterprise) before buying; otherwise, buy credits at [`claude.ai/admin-settings/usage`](https://claude.ai/admin-settings/usage) | | *(Optional)* The **Claude GitHub App** linked to your Claude organization | Linking GitHub first turns setup's GitHub step into repository selection instead of an app install. | [Link your GitHub organization](/docs/claude-tag/admins/configure-github#link-your-github-organization) first, or grant repository access after setup | | *(Optional)* A **channel to test in** | You'll invite Claude to a channel to [verify your setup](#verify-your-setup). | Create a private Slack channel for the pilot, or pick any existing one | If any of your services restrict traffic by IP, file the [network requirements](/docs/claude-tag/admins/network-requirements) request with your network team early; in many organizations, IP allowlist changes take days to approve. If you see **View setup guide** and **Go to chat** buttons instead of **Start setup**, your signed-in account can't run setup. See [Common setup issues](#common-setup-issues). If your team already uses the earlier Claude in Slack, the same steps apply and your existing app stays; see [Migrate from the earlier app](/docs/claude-tag/admins/migrate-from-earlier) for what changes. ## Pair your Slack workspace Install the Claude app in Slack, get a pairing code from Slack, and paste it on the setup page. **Where:** the Slack Marketplace, at [claude.com/claude-for-slack](https://claude.com/claude-for-slack). Click **Add the Claude app** on the setup page to open the listing, then click **Add to Slack** and approve the permissions. If the app is already installed, click **Add to Slack** anyway: you reinstall over the existing app with its current permissions and keep your settings. **Where:** Slack, in the workspace you just installed the app in. Open any channel and add Claude to it with `/invite @Claude`. Claude posts a short welcome message when it joins. Then send `@Claude connect` as a new message with no other text. Claude replies in the channel with a message only you can see, containing the pairing code: > Connect **this workspace** (Acme) to your Claude organization for billing: have a Claude **organization admin** redeem this code in Claude admin settings. The code works once and expires in 15 minutes. > `workspace_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6` > *Once connected, Claude usage in this workspace is billed to that organization.* Only a Slack workspace admin (or Grid org admin) can run this command; anyone else gets a message naming who to ask. If you skip the invite, Slack shows you a notice that Claude isn't in the channel, with an **Add Them** button. Click it, then send `@Claude connect` again. **Where:** the Claude Tag setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Paste the pairing code Claude sent into the **Paste the pairing code** field. **Connected to** followed by your workspace name appears under it when the code is accepted. Select **Entire workspace (recommended)** or **Specific channel**. If you select **Specific channel**, enter each channel's ID in the **Channel IDs** field, separated by commas, like `C0B1SLDGBPG, C0ARH08HQCA`. To find a channel's ID in Slack, right-click the channel, choose **Copy**, then **Copy link**; the ID is the part after the last slash. For a private channel, invite `@Claude` to it in Slack first. If you aren't asked where Claude can reply, Claude replies across the whole workspace once you [launch](#launch-claude-tag). You see a confirmation that the pairing worked. Select **Next: Choose Claude’s tools**. Claude doesn't answer mentions in Slack until you finish [Launch Claude Tag](#launch-claude-tag); a mention before then gets "Claude is disabled in this channel." Only a Slack workspace admin can run `@Claude connect`, and in most workspaces only an admin can install the app. If that's not you, send the Slack admin the message below and have them return the pairing code: ```text wrap theme={null} Please install the Claude app (https://claude.com/claude-for-slack) in [workspace]. When that's done, let me know a time that works for the next part: in any channel, run /invite @Claude, then post "@Claude connect" with no other text and send me the code it returns. Pick a channel that belongs to just [workspace]. The code expires 15 minutes after Claude posts it, so I'll redeem it right away. What it can access: https://claude.com/docs/claude-tag/admins/for-slack-admins ``` When a Grid org admin sends `@Claude connect`, the reply includes two codes: a `workspace_` code that pairs only that workspace, and an `enterprise_` code that pairs every workspace in the Grid that doesn't already have its own pairing. Paste the `enterprise_` code if Claude should work across the Grid; DMs for users homed in other Grid workspaces only work with a Grid-wide pairing. See [Pair an Enterprise Grid](/docs/claude-tag/admins/workspaces#pair-an-enterprise-grid). ## Choose Claude's first tools **Where:** the Claude Tag setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Select at least two tools your team uses, then click **Next: Connect GitHub**. Selecting a tool here doesn't connect it. In [Create accounts for Claude's other tools](#create-accounts-for-claude%E2%80%99s-other-tools), you create an account for Claude in each tool you selected and paste that account's API key on the setup page. The list shows widely used tools; use **Search all tools** for one that isn't shown. GitHub isn't in the list; you set it up in [Connect GitHub](#connect-github). You can add more tools any time after setup. See [Give Claude access](/docs/claude-tag/admins/add-connections) for which services to connect first. ## Connect GitHub **Where:** the Claude Tag setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). If the app isn't installed yet, select **Start setup** on the step to open your [Claude GitHub settings](/docs/claude-tag/admins/configure-github), where you sign in with GitHub, authorize your organization, and install the app. Claude reaches GitHub through the [Claude GitHub App](/docs/claude-tag/admins/configure-github) rather than an account and credential, so GitHub has its own step. The setup page shows one of three things, depending on where the Claude GitHub App is installed: * **Connect GitHub**, when the app isn't linked to your Claude organization yet. Only an owner of your GitHub organization can install the app. If that's you, follow the steps shown. If not, send the message the step shows to a GitHub organization owner, skip this step, and continue with setup. After they install the app, [grant repositories](/docs/claude-tag/admins/configure-github#grant-repository-access) from the admin page. * **Choose your GitHub repos**, when the app is already linked. Grant every repository or pick specific ones. * **The Claude app is installed on \[username], a personal account**, when the app was installed on someone's personal GitHub account rather than an organization. Claude Tag connects to a GitHub organization only. A GitHub organization owner installs the app on the organization that owns your repositories (see [Link your GitHub organization](/docs/claude-tag/admins/configure-github#link-your-github-organization)). You can skip the step and continue with setup while that happens, then [grant repositories](/docs/claude-tag/admins/configure-github#grant-repository-access) from the admin page afterward. The repositories you grant apply to every channel Claude is in. If your team won't hand Claude code work, skip this step. ## Create accounts for Claude's other tools **Where:** your company's email admin console and each tool you selected, then the Claude Tag setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Treat Claude like a new hire. You give it an email address, add it to each tool as a member, and then, signed in as Claude, create an API key in that tool. The setup page asks you for those keys, one per tool. Claude's own account in each tool is what lets you see exactly what it did in that tool's logs and cut off its access without touching anyone else's. [How agent identity works](/docs/claude-tag/concepts/agent-identity) has the full model. Work through one tool end to end before starting the next. In your company's email admin console, create a new user for Claude, for example `claude@yourcompany.example.com`, the same way you'd create a mailbox for a new hire. Every tool invitation and verification email for Claude lands in that inbox. Any address works; the setup page shows `claude@` followed by your domain only as an example, and Claude Tag never stores the address itself. In the tool's member or user settings, invite `claude@yourcompany.example.com` the way you'd add a new teammate. Open the invitation from Claude's inbox and finish creating the account, including a password. Give the account the narrowest role that covers the work; read-only where the tool offers it. For a tool that offers service accounts, create one in the tool's admin settings instead of inviting the email address, scoped read-only or to the specific project. Sign in to the tool as Claude and create the credential that tool's [connection guide](/docs/claude-tag/admins/connections/overview) names, usually an API key or personal access token from the tool's settings. Copy it; it belongs to Claude's account, so Claude's actions show up in the tool's audit log under Claude's name. Back on the setup page, each tool you selected is listed. Click **Connect** next to the tool and paste the key you just created. Then repeat the last three steps for the next tool you selected: add Claude as a member, create an API key in Claude's account, and paste it here. Claude keeps the one email address for every tool. To finish this step later, select **Skip** and confirm past the warning that Claude won't be able to act in the unconnected tools. Claude still works from what's in Slack: it can catch a team up on a channel, turn a thread into a doc, and search the web. It can't act in a tool until that tool is connected. See [Give Claude access](/docs/claude-tag/admins/add-connections) for what access to give each account, and the [per-service connection guides](/docs/claude-tag/admins/connections/overview) for the credential fields per tool. ## Launch Claude Tag **Where:** the Claude Tag setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Channel work draws from your organization's usage balance, not from individual seats; the spend limit caps how much of that balance Claude Tag can use each month. DMs run on the user's own claude.ai account and aren't capped by this limit. If your organization has a [launch usage credit](https://support.claude.com/en/articles/15575654-claude-tag-launch-promo-for-claude-team-and-enterprise), the launch screen shows the amount and the date it runs through, and after launch the admin page shows it under **Included usage** with how much is used. You're billed for usage beyond it, up to the spend limit. If the setup page shows a **Buy usage credits** step before Launch, buy credits on that step to continue. The launch screen then doesn't include **Set monthly spend limits**, so set a limit after launch at [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag). Choose from `$500`, `$1,000`, `$2,500`, `$5,000`, **Unlimited**, or **Custom** (a US-dollar amount up to `$1,000,000`). Usage bills against your organization's balance up to that amount each month. See [Set a spend limit](/docs/claude-tag/admins/set-spend-limit) for what counts toward the cap, per-channel limits, and what users see when it's reached. The toggle is on by default: after launch, Claude DMs each member of the workspace to help them get started. Those DMs don't count toward your usage. Turn the toggle off to skip them. The admin page has a matching row, **Let people know they can talk to Claude**. To send the DMs from the admin page, select **Notify members now** on that row and confirm. The row reads **Members notified** once the DMs have gone out. Claude Tag turns on and you return to the Claude Tag admin page, which now shows your workspace under **Where Claude Tag works**. Claude answers mentions in the workspace you paired from here on. If you skipped connecting tools, a **Finish setting up Claude Tag** card sits at the top of the admin page; its **Finish setup** button reopens the steps you skipped. To leave setup without turning Claude Tag on, select **Finish later**. Everything you've set is saved, and the admin page shows a resume card that brings you back here. Until you launch, the Claude app is in your Slack workspace but every mention gets "Claude is disabled in this channel." ## Verify your setup **Where:** Slack, in any channel of the workspace you paired. Run the first check, then the ones that match what you connected. ### Check that Claude responds Add Claude to the channel, then mention it: ```text wrap theme={null} /invite @Claude ``` ```text wrap theme={null} @Claude summarize what this channel decided this week and list any open questions ``` **Passed when:** Claude replies in a thread under your message. The reply ends with a footer naming the model and a **Configure** link. **If not:** "Claude is disabled in this channel" means you haven't finished [Launch Claude Tag](#launch-claude-tag). No reply at all means the channel isn't covered; check that the workspace appears under **Claude Tag's access** on the **Slack** tab in admin settings, then see [Nothing responds](/docs/claude-tag/admins/troubleshooting#nothing-responds). ### Check a tool you connected Skip this check if you skipped [Create accounts for Claude's other tools](#create-accounts-for-claude%E2%80%99s-other-tools). Otherwise, in a new thread, ask what the channel can reach: ```text wrap theme={null} @Claude what can you access from this channel? ``` Then ask one tool for something small that a read-only account can do. If you connected an issue tracker: ```text wrap theme={null} @Claude pull the five most recent issues from our issue tracker and post them here ``` For a data warehouse, ask for a row count from one table. For a support tool, ask for the newest open tickets. For a document store, ask it to find a file by name. **Passed when:** the first reply lists the tools you connected, the second comes back with data, and the request appears in that tool's audit log under Claude's account. **If not:** a tool missing from the list means its connection didn't save; open the Access bundle in admin settings and [connect it again](/docs/claude-tag/admins/add-connections#add-a-connection). "I can't reach…" in a thread you started before connecting means Claude wasn't told about the new connection; start a fresh thread. Anything else, see [Access and connections](/docs/claude-tag/admins/troubleshooting#access-and-connections). ### Check GitHub Skip this check if you skipped [Connect GitHub](#connect-github). Otherwise, ask about a repository you granted: ```text wrap theme={null} @Claude list the open pull requests in your-org/your-repo and who each one is waiting on ``` **Passed when:** Claude lists the pull requests. **If not:** see [GitHub doesn't work in this channel](/docs/claude-tag/admins/troubleshooting#github-doesn%E2%80%99t-work-in-this-channel). For more tasks to hand Claude once the checks pass, see the [use case library](/docs/claude-tag/users/use-cases). ## After setup After launch, you change anything about Claude Tag from the admin page: 1. Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). 2. Under **Claude Tag's access**, open the **Slack** tab. 3. In the list on the left, select **Default Slack** to change how Claude works everywhere, or select a workspace or channel to change it in that one place. What you connected during setup is attached to the workspace you paired, or to each channel you listed if you chose **Specific channel**. **Default Slack** is the layer above that: anything you add there applies in every workspace and channel, and each entry below it adds to that for one place. Every entry has the same sections: **Connectors**, **Repositories**, **Plugins**, **Custom instructions**, **Access bundles**, and, under **Advanced**, the **Default model**. An [Access bundle](/docs/claude-tag/concepts/glossary#access-bundle) is a named set of connections, repositories, plugins, and instructions that you can attach to more than one place. Setup created one on your workspace's entry, named after the workspace (for example, **Tag Test default**), holding the tools you connected. | To do this | Go to | Learn more | | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | | Change the model Claude replies with | The entry's **Advanced** section, **Default model**. Set it on **Default Slack** to change it everywhere, or on one channel. | [Choose the model for a scope](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope) | | Give Claude standing instructions | The **Custom instructions** field on **Default Slack** for every channel, or on one channel's entry for that channel only. | [Customize](/docs/claude-tag/admins/customize) | | Connect another tool, or one you skipped | **Connectors** on the entry, or the bundle named after your workspace under **Access bundles**. | [Give Claude access](/docs/claude-tag/admins/add-connections) | | Let Claude reach a site or API that has no credential | The **Domains** list of the Access bundle, under **Access bundles**. | [Allow a host without a credential](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential) | | Grant more repositories | **Repositories** on the entry. | [Configure GitHub access](/docs/claude-tag/admins/configure-github) | | Give one channel more than the default | Select the channel and add to it. | [Configure per-channel access](/docs/claude-tag/admins/attach-to-scope) | | Limit where Claude works or who can use it | | [Restrict where Claude operates](/docs/claude-tag/admins/restrict-access) | | Pair another workspace, or disconnect one | The Slack row's **⋮** menu under **Where Claude Tag works**. Disconnecting permanently deletes the workspace's Claude data. See [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle). | [Manage workspaces](/docs/claude-tag/admins/workspaces) | | Change the spend limit | [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag). | [Set a spend limit](/docs/claude-tag/admins/set-spend-limit) | | Turn Claude Tag off | The **Enable Claude Tag for your organization** toggle at the top of the admin page. | | | Bring in the first users | | [Getting started for users](/docs/claude-tag/users/getting-started) | ## Common setup issues Every message setup can show instead of the next step, matched to its fix, is in [Setup errors](/docs/claude-tag/admins/troubleshooting#setup-errors) on the troubleshooting page. ## Related resources * [How Claude Tag works](/docs/claude-tag/concepts/how-it-works): what happens between a mention and a reply * [How agent identity works](/docs/claude-tag/concepts/agent-identity): why Claude gets its own accounts, and what that means for audit logs and access * [Configure per-channel access](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit): how Default Slack, workspaces, and channels inherit Access bundles * [Claude Tag settings map](/docs/claude-tag/concepts/settings-map): every setting, and whether admins, channel members, or users control it * [Glossary](/docs/claude-tag/concepts/glossary): Access bundle, scope, session, and the other terms on this page * [Network requirements](/docs/claude-tag/admins/network-requirements): what your services must allowlist so Claude can reach them * [Claude Tag in production at Anthropic](https://claude.com/blog/ai-ci-cd-on-call): how Anthropic runs Claude Tag as its first responder for CI/CD failures # Set up a skills repository Claude can update Source: https://claude.com/docs/claude-tag/admins/skills-repo Put your org's Claude Tag skills in a git repository with auto-sync, grant Claude write access, and Claude can open pull requests to improve its own skills from what it learns in channels. A **skill** is a set of instructions that teaches Claude how to use a specific tool or follow a specific process (for example, which Datadog endpoints answer which questions, or your org's incident-response runbook). Claude Tag uses the same [skills format as Claude Code](https://code.claude.com/docs/en/skills). A **plugin** bundles one or more skills together. You can upload skills one at a time in the console, but putting them in a git repository means Claude can open pull requests to improve them from what it learns working in your channels. You review the PR; once merged, every channel picks up the update. ## Set up the skills repository A private or internal GitHub repository, laid out as a [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces): a `.claude-plugin/marketplace.json` file at the root that lists each plugin, and one folder per plugin. Each plugin bundles one or more skills. A public repository can't be selected in the next step; fork it into a private one first. For a github.com repository, the GitHub connector must be enabled for your organization. On the **Plugins** page at [`claude.ai/admin-settings/plugins`](https://claude.ai/admin-settings/plugins), click **Add plugins** and choose **Sync from GitHub**. Select the repository, leave **Sync automatically** on (the default), and click **Create**. When you click **Create**, and on every sync after that, the whole repository is downloaded as one archive, and the archive can't be larger than 512 MiB. A repository over that size, such as a large monorepo, is rejected with `Download too large (>536.9MB)` even when the plugins in it are small. Put the plugins in a smaller dedicated repository, or [upload the plugin as a zip file](#upload-a-plugin-as-a-zip-file) instead. Open an [Access bundle](/docs/claude-tag/admins/add-connections#your-first-access-bundle), go to its **Repositories** tab, and add the repository. The Claude GitHub App must already be linked to your GitHub organization; see [Configure GitHub access](/docs/claude-tag/admins/configure-github). In the same bundle's **Plugins** tab, toggle on the plugins from your new marketplace; each is off until you enable it. See [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). **You'll see:** the repository appears in the bundle's Repositories list, and the marketplace's plugins appear in the bundle's Plugins tab, each labeled with the marketplace name. ## How updates propagate Once the repository is set up, Claude can propose changes and they reach channels automatically after you merge: | Stage | What happens | | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | | Claude works in a channel | Using the skills currently attached to that scope | | Claude proposes an update | Opens a pull request against the skills repository, under the Claude GitHub App identity, linked back to the thread that prompted it | | You review and merge | The PR is yours to approve, edit, or close, like any contributor's | | The marketplace syncs | On push to the default branch, the updated plugin syncs to your organization automatically | | New threads pick it up | The next thread in any covered channel uses the updated skill | Every skill change reaches channels only after a human approves the merge; Claude opens the PR, you merge it. ## Prompt Claude to propose updates Claude won't open skill PRs unprompted. Ask in the channel when something it learned should stick: ```text wrap theme={null} @Claude that worked. Open a PR to the skills repo so the Datadog skill includes that query pattern. ``` Or set a routine that sweeps a channel's corrections into proposed updates: ```text wrap theme={null} @Claude every Friday, review what you got wrong in this channel this week and open one PR to the skills repo with the fixes. ``` ## Why a repository instead of uploading skills You can also upload individual skills in the console without a repository. The repository pattern is worth the setup because Claude can propose changes to it, every change goes through version control and code review, and you can attach the same skills to multiple bundles without uploading them again. ## Upload a plugin as a zip file To upload instead, on the **Plugins** page at [`claude.ai/admin-settings/plugins`](https://claude.ai/admin-settings/plugins), click **Add plugins**, choose **Upload a file**, and upload a `.zip` or `.plugin` archive of up to 200 MB. The archive has to be a [Claude Code plugin](https://code.claude.com/docs/en/plugins), laid out in one of these ways: * A `.claude-plugin/plugin.json` manifest at the archive root, with each skill in its own folder at `skills//SKILL.md` * The same layout inside a single top-level folder * For a single skill, a `SKILL.md` at the top level whose frontmatter declares the plugin's components An archive with no manifest, with more than one `plugin.json`, or with the manifest anywhere else is rejected at upload. After upload, the plugin is in your organization's catalog but not attached anywhere. To make it available in channels, toggle it on in a bundle's **Plugins** tab or add it directly on a scope; see [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). ## Repository context files and MCP servers A granted repository's `CLAUDE.md` and `.claude/rules/*.md` load when Claude clones it, in the same format as Claude Code; see [What loads from a repository](/docs/claude-tag/admins/configure-github#what-loads-from-a-repository) and the [Claude Code memory docs](https://code.claude.com/docs/en/memory). A repository's `.mcp.json` is not loaded. To give Claude an MCP server, put the `.mcp.json` in a plugin, next to its `.claude-plugin/plugin.json`, and attach the plugin; the [Claude Code plugin docs](https://code.claude.com/docs/en/plugins) cover the `.mcp.json` format, and [Add a custom MCP server](/docs/claude-tag/admins/connections/custom#add-a-custom-mcp-server) covers the credential the server needs. ## What belongs in the repository | Put in the skills repo | Put in channel memory instead | | :------------------------------------------------------------ | :------------------------------------- | | How to call a specific API correctly | This channel's preferred output format | | A runbook that any team would reuse | A one-off decision this channel made | | Tool-specific gotchas (auth headers, pagination, rate limits) | Who owns what in this team | Skills in the repository reach every channel under the scope. ## Related resources * [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins): how plugins and skills load into a scope * [Configure GitHub access](/docs/claude-tag/admins/configure-github): granting Claude write access to a repository * [What Claude Tag remembers](/docs/claude-tag/users/memory): when channel memory is the right place instead # Troubleshoot Claude Tag setup Source: https://claude.com/docs/claude-tag/admins/troubleshooting Error messages from Claude Tag setup and what fixes each. Covers permission mismatches, GitHub access gaps, session start failures, and account errors. This page covers errors you might hit setting up and administering Claude Tag: Slack app permissions, guest and shared channels, console errors, channels and threads where nothing responds, access and connections, and session starts. Each entry has the same three parts: what you see, what it means, and how to resolve it. For problems people can resolve on their own in a channel, like a missing reply or a thread that lost its work, see [Troubleshoot Claude Tag in channels and DMs](/docs/claude-tag/users/troubleshooting). If someone reports that Claude can't reach a service you connected, check two things before anything else: * The connection reaches that channel through an attached bundle. To check, go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) > **Claude Tag's access** > **Slack** > the channel's scope (or its workspace's scope, if the channel isn't listed) > **Access summary**, which includes access [inherited from wider scopes](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit). If there's no **Access summary** section, or the connection isn't in it, [attach the bundle](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) to the channel's scope; if the channel has no scope yet, select **Add channel** on its workspace to [create the scope](/docs/claude-tag/admins/attach-to-scope#attach-to-a-channel) first. * The test ran in a new thread; an existing thread isn't told about a connection added after it started, though the connection works there if the request names the service. ## Setup errors What you expected to see while running [setup](/docs/claude-tag/admins/setup-overview), what appeared instead, and what to do. | You expected | But got | Do this | | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The setup page at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) | A page titled **Set up Claude Tag** with **View setup guide** and **Go to chat** buttons | Your signed-in account can't run setup, and **View setup guide** leads back to this guide. On a personal account (Free, Pro, or Max), [start a Team or Enterprise plan](https://claude.com/pricing) first. In a Team or Enterprise organization, ask an Owner to run setup. When the page shows a workspace switcher, your account also belongs to another Team or Enterprise organization; switch to it and retry. | | A pairing code from `@Claude connect` | “Only Slack workspace admins (or Enterprise Grid org admins) can link this workspace to a Claude organization…” | The person who sent `@Claude connect` isn't a Slack workspace admin or Grid org admin. See [Only Slack workspace admins or Grid org admins can link this workspace](#only-slack-workspace-admins-or-grid-org-admins-can-link-this-workspace). | | A pairing code | “…installation is out of date” | A Slack admin approves the update or reinstalls the app, then sends `@Claude connect` again. See [This workspace's Claude app installation is out of date](#this-workspace%E2%80%99s-claude-app-installation-is-out-of-date). | | A pairing code | A message about guests, or about the channel being shared across workspaces | Send `@Claude connect` again in a channel with no guests that belongs to a single workspace. Match the exact message in [Guest and shared channels](#guest-and-shared-channels) for the fix that fits it. | | The console to accept your pairing code | "Claim code is invalid, expired, or already used" | Codes are single-use and last 15 minutes. Send `@Claude connect` again and paste the fresh code right away. See [Claim code is invalid, expired, or already used](#claim-code-invalid). | | The console to accept your pairing code | "Already connected to a different organization" | The workspace is paired to another Claude organization, often a trial org. See [Already connected to a different organization](#already-connected-to-a-different-organization). | | The spend limit picker on the **Launch Claude Tag** step | A **Buy usage credits** step | Your organization pays by card in US dollars and has no credits loaded. Load credits, or select **Skip** to continue without; nothing runs in channels until the balance is funded. Invoiced organizations and those billing in other currencies see the spend limit picker regardless of balance. | | A reply from Claude while you're still in setup | "Claude is disabled in this channel. Your admin can re-enable it here." | Claude Tag isn't turned on until you finish [Launch Claude Tag](/docs/claude-tag/admins/setup-overview#launch-claude-tag). Finish setup, then mention `@Claude` again. If the message persists after launch, see [Claude is disabled in this channel](#claude-is-disabled-in-this-channel). | | The **Connect GitHub** step to list your organization's repositories | "The Claude app is installed on \[username], a personal account. Claude Tag connects to a GitHub organization. Install it on your organization instead." | The Claude GitHub App is on a personal GitHub account. Have a GitHub organization owner [install it on the organization](/docs/claude-tag/admins/configure-github#link-your-github-organization) that owns your repositories. You can skip the step and [grant repositories](/docs/claude-tag/admins/configure-github#grant-repository-access) after setup. | | A connected tool to work in your test | “I can't reach…” | Claude isn't told about a connection added after the thread started. Ask it to use the service by name, or start a fresh thread. | | The **Where Claude Tag works** section with a **+ Connect** button | Only the legacy Claude in Slack toggles | Your organization isn't enabled for Claude Tag. Contact your account team. | | Claude to respond in Slack | "Claude Tag has been turned off for your Claude organization…" | The **Enable Claude Tag for your organization** toggle is off. An Owner turns it on at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). See [the troubleshooting entry](#claude-tag-is-turned-off-for-your-organization). | | Claude to respond in Slack | "Claude Tag is unavailable because Routines aren't enabled for your organization…" | Routines isn't enabled for your Claude organization, which Claude Tag requires. An admin enables Routines at [`claude.ai/admin-settings/claude-code`](https://claude.ai/admin-settings/claude-code), then anyone can mention `@Claude` again. See [the troubleshooting entry](#claude-tag-is-unavailable-because-routines-are-not-enabled). | | Claude to respond in Slack | "Claude in Slack is not available for your organization" or "Claude isn't available for organizations with restricted compliance settings." | The paired Claude organization has a restricted compliance configuration, such as Zero Data Retention (ZDR), that Claude Tag can't run under. No setting lifts the restriction; contact your account team. See [the troubleshooting entry](#restricted-compliance-settings-block-claude-tag). | | The **Slack** tab to list your scopes | "Couldn't load Slack scopes. Reload the page to try again." | Reload the page. See [Couldn't load Slack scopes](#couldn%E2%80%99t-load-slack-scopes). | | A reply in your test channel | "Couldn't check this channel just now" | Mention `@Claude` again. See [Couldn't check this channel just now](#couldn%E2%80%99t-check-this-channel-just-now). | | A reply in your test channel | "Something went wrong starting a session" | Retry first. If it persists, see [the session-start entries](#something-went-wrong-starting-a-session). | ## Slack app permissions Most errors in this section appear when Claude needs a Slack permission that wasn't part of the app when your workspace approved it. For those, the fix is a Slack workspace admin re-approving the Claude app from [Claude for Slack](https://claude.com/claude-for-slack), which grants the current permission set. Nothing else changes, and existing settings carry over. ### This workspace's Claude app installation is out of date **What you see** Claude replies to `@Claude connect`: > This workspace's Claude app installation is out of date — it hasn't granted the \[permission name] permission(s). I can't create a link code until a Slack admin reinstalls the Claude app or approves its updated permissions. Once that's done, ask me to link again. Two phrases in the message are links: * **reinstalls the Claude app** opens the reinstall flow. The fix below starts from this link. * **approves its updated permissions** opens Slack's Manage apps page for the workspace. On Enterprise Grid the message names "this Slack organization's Claude app installation" and asks a Slack organization admin to reinstall the org-wide app. The org-wide reinstall works from inside one of the Grid's workspaces with **Install to entire organization**, following the steps in [Claude is silent everywhere on Enterprise Grid](#claude-is-silent-everywhere-on-enterprise-grid). Sometimes the reply issues a code anyway, with a footnote that the install "is out of date". The reinstall steps below clear the footnote too. **What it means** Claude needs a Slack permission that wasn't part of the app when your workspace approved it, so the app was never granted it. Claude can't issue a link code until the updated permission set is approved. **How to resolve** A Slack workspace admin runs these three steps: 1. Click the **reinstalls the Claude app** link in the reply, or open [Claude for Slack](https://claude.com/claude-for-slack) and click **Add to Slack**. Don't uninstall first; this installs over the existing app, so your settings carry over. 2. Approve the consent screen Slack shows; it lists each permission being added. If Slack shows **Unapproved permissions requested** instead of completing, see [Unapproved permissions requested](#unapproved-permissions-requested). 3. Run `@Claude connect` again. If the reinstall worked, the reply contains a pairing code (the link code the original message said it couldn't create) instead of this message. Send that pairing code to whoever runs Claude setup in the console; it expires after 15 minutes. Slack's **Manage apps** page lists the permissions the app requests, not the permissions your workspace has granted, so seeing the missing permission listed there doesn't mean it's approved. The grant happens on the consent screen. For the app's permissions in one place, see [What the Claude Slack app can access](/docs/claude-tag/admins/for-slack-admins). ### Unapproved permissions requested **What you see** **Unapproved permissions requested** is a message from Slack, not a Claude reply. It appears in either of two places: * On the consent screen after **Add to Slack**, including for a workspace admin who approved the app before * As the pending status on the Claude entry under **Settings & administration** → **Manage apps** → **App requests**, in workspaces that require admin approval for apps **What it means** The permissions the Claude app requests have changed since your workspace approved it, and Slack requires a fresh approval for the additions. The consent screen lists each permission being added, so you can review exactly what you're granting before approving; approval applies only to the Claude app already installed in your workspace. **How to resolve** A Slack workspace admin approves the Claude app's updated permissions in either place: * In Slack, go to **Settings & administration** → **Manage apps** → **App requests** and approve the Claude request. * Or open [Claude for Slack](https://claude.com/claude-for-slack), click **Add to Slack**, and approve the consent screen. Both paths grant the same permissions, and neither requires uninstalling first. If the approval worked, `@Claude connect` returns a pairing code without mentioning the installation again. ### Only Slack workspace admins or Grid org admins can link this workspace **What you see** Claude replies to `@Claude connect`: > Only Slack workspace admins (or Enterprise Grid org admins) can link this workspace to a Claude organization. Please ask a workspace admin to mention me with `@Claude connect`. **What it means** Slack reports that the person who ran `@Claude connect` doesn't hold the workspace admin role, so no pairing code was issued. This reply is itself the signal, and there's nothing else to check. The Claude Owner role doesn't satisfy the check; it's the Slack-side role that matters. **How to resolve** Have a Slack workspace admin run `@Claude connect` instead. On Enterprise Grid, a Grid organization admin works too. If the fix worked, their reply contains a pairing code. ### Missing the required Slack permission (users:read) **What you see** Claude replies in the channel: > Claude can't check this channel for guests because it's missing the required Slack permission (users:read). A workspace admin needs to reinstall Claude to grant it. If the failure happens while Claude is posting a message rather than replying, there's no fixed message; Claude describes the problem in its own words, and the underlying error it relays reads "message not delivered: Claude can't check this channel for guests because the Slack app is missing a permission (users:read); a workspace admin must reinstall Claude to grant it." **What it means** **Allow Claude to work in channels with guests** is set to **Restrict** or **Channel only** for this channel's [scope](/docs/claude-tag/concepts/glossary#scope), so Claude checks the channel for guests before replying, and this install predates the `users:read` permission that check needs. **How to resolve** Re-approve the app from [Claude for Slack](https://claude.com/claude-for-slack). Don't uninstall first; the re-approval installs over the existing app. If the fix worked, a mention in the affected channel gets a reply instead of the permission message. ### The audit log shows Claude joining channels no one invited it to **What you see** Slack's audit log shows Claude joining a channel with no inviter recorded, and no one in the workspace remembers adding it. **What it means** Either a member selected **Add to channel** on a channel Claude suggested in a direct message, or the channel's name matches an [auto-join channel pattern](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name) an admin set, and Claude joined the public channel when it was created or renamed. Claude's welcome message, the introduction it posts when a member first opens a direct message with it, suggests a few public channels, each with an **Add to channel** button. Selecting one directs Claude to add itself to that channel. Claude performs that join with its own `channels:join` permission, so Slack's audit log records the join as the Claude app and shows no inviter; the member's selection is not visible in Slack's log. Outside those two paths, Claude never joins a channel unprompted. [What the Claude Slack app can access](/docs/claude-tag/admins/for-slack-admins) covers how members add it. **How to resolve** Nothing is misconfigured. If an auto-join pattern brought Claude in, review the patterns in the scope's **Advanced** section. If Claude shouldn't be in the channel, remove it with `/remove @Claude`, or [set the scope's Claude Tag version to Off](/docs/claude-tag/admins/restrict-access#quiet-or-remove-claude-tag) so it stops responding there even if it's added again. If you have the [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) instead of per-scope version settings, remove Claude and add a [blocked channel pattern](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name) for the channel's name. If you want every join in the audit log attributed to a person, ask members to add Claude with `/invite @Claude` rather than the buttons; Slack records an invite as the inviting member's action. ## Guest and shared channels Claude checks a channel for guests and for sharing across workspaces before it replies there. The messages those checks post look alike, but most are refusals and one is a notice on a reply Claude goes on to give. Match the exact message text before changing anything; each message has a different cause and a different fix. A channel created at the Enterprise Grid organization level rather than inside a single workspace counts as shared across workspaces even when it appears in only one workspace's sidebar, so a channel can hit the shared-channel messages below despite looking like an ordinary single-workspace channel. ### Claude doesn't respond in channels that include guests **What you see** Claude replies in the channel: > Claude doesn't respond in channels that include guests. You can remove the guests from this channel (Channel details -> Members -> filter by "guests"), or a claude.ai organization owner can allow it in Claude Tag settings under Advanced -> "Allow Claude to work in channels with guests". In the message, "Claude Tag settings" is a link to the admin page where the guest setting described below lives. The role it names is a claude.ai organization owner, not a Slack admin. **What it means** The channel includes at least one Slack guest account, and **Allow Claude to work in channels with guests** is set to **Restrict** for this channel's scope. **Restrict** is the default. **How to resolve** Either fix works: * Remove the guests from the channel, or move the conversation to a channel with no guests; this changes no settings, so no other channel is affected. * Change **Allow Claude to work in channels with guests** for the scope covering this channel, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the scope → the collapsed **Advanced** section. **Channel only** restores replies with [channel-only access](/docs/claude-tag/admins/restrict-access#how-channel-only-works). **Allow** restores replies with the scope's full access, and only an organization Owner can choose it. See [restrict guest channels](/docs/claude-tag/admins/restrict-access#restrict-guest-channels) for what each value exposes. Either value applies to every guest channel that scope covers. To limit the change to one channel, set the value on the channel's own scope. Either value restores replies, not workspace search. Claude can't search the workspace from a channel that includes guests, even under **Allow**. Removing the guests restores search as well. If the fix worked, a mention in the channel gets a reply. ### Couldn't check this channel just now **What you see** Claude replies in the channel: > Couldn't check this channel just now. Please try again in a moment. **What it means** Claude couldn't complete its check for guests in this channel; either the guest-policy lookup or the Slack membership check briefly failed, so Claude declined this reply rather than risk posting where a guest might see it. This isn't a configuration error. **How to resolve** 1. Mention Claude again; the retry usually clears it. 2. If one channel hits this repeatedly, the membership check may be failing on an unusually large channel. Setting **Allow Claude to work in channels with guests** to **Allow** on the channel's scope removes the guest check for every channel that scope covers, which usually stops the message from recurring; weigh [what Allow exposes](#claude-doesn%E2%80%99t-respond-in-channels-that-include-guests) first. ### This channel is shared across multiple workspaces **What you see** Claude replies in the channel: > This channel is shared across multiple workspaces, and Claude can't verify whether it includes guests, so Claude can't respond here. The same check also refuses requests made from another conversation, such as asking Claude to post a message in the channel, with a message ending "shared across multiple workspaces and Claude can't verify whether it includes guests". **What it means** This message comes from the guest check, not from workspace sharing. **Allow Claude to work in channels with guests** is set to **Restrict** for this channel's scope, and the channel's membership can't be verified, most often because the channel is shared across an Enterprise Grid organization, so Claude declines. **How to resolve** Use a channel that belongs to a single workspace. Setting the scope's guest setting to **Allow** removes the guest check that posts this message, but a Grid-shared channel still doesn't behave like a single-workspace one. When its workspaces connect to different Claude organizations, Claude posts the refusal in [This channel is shared among several Claude workspaces](#this-channel-is-shared-among-several-claude-workspaces) instead of replying. When they all share your one Claude organization, Claude replies with only your organization's default access and settings, described in [This channel is shared across several Slack workspaces](#this-channel-is-shared-across-several-slack-workspaces). ### This channel is shared among several Claude workspaces **What you see** Claude replies in the channel: > This channel is shared among several Claude workspaces, so Claude cannot respond here. The reply appears only when someone mentions Claude directly, or addresses it in a thread it already joined. Other messages in the channel get no reply at all. **What it means** The channel is shared across more than one Slack workspace in your Enterprise Grid, and those workspaces are paired to different Claude organizations. No single organization's settings cover the channel, so Claude declines regardless of the guest policy or any scope setting. Claude also declines when it can't confirm that the workspaces share one Claude organization. Two similar messages come from different situations. [This channel is shared across multiple workspaces](#this-channel-is-shared-across-multiple-workspaces) is the guest case, and [This channel is shared across several Slack workspaces](#this-channel-is-shared-across-several-slack-workspaces) is the case where every workspace belongs to your one Claude organization, so Claude replies. **How to resolve** Move the conversation to a channel that belongs to a single workspace, or to a DM. ### This channel is shared across several Slack workspaces **What you see** Claude posts a notice in the thread, then answers the request: > This channel is shared across several Slack workspaces, so Claude is using only your organization's default Slack access and settings here — not any workspace- or channel-specific repos, instructions, or memory you've configured. **What it means** The channel is shared across more than one Slack workspace, and every one of those workspaces belongs to your Claude organization. Claude works there, but only with the access and settings on your [**Default Slack access**](/docs/claude-tag/admins/attach-to-scope) scope. Bundles, instructions, and memory attached to a workspace or to this channel don't apply. The notice posts at most about once a month per channel, so replies in this channel run under the same defaults even when no notice accompanies them. **How to resolve** Nothing is broken. To use a channel's own repositories, connections, or instructions, work in a channel that belongs to a single workspace, or add what the channel needs to the **Default Slack access** scope. In a single-workspace channel, requests use that channel's own configuration and the notice doesn't appear. ### Claude isn't available in channels shared across your Enterprise Grid **What you see** You ask Claude to do something that involves a channel shared across your Enterprise Grid, and the refusal names the request it declined and ends: > Claude isn't available in channels shared across your Enterprise Grid **What it means** The request needed Claude to act in a channel that's shared across more than one workspace in your Enterprise Grid. The message appears in whichever conversation you made the request; the entries above cover the replies Claude posts in the shared channel itself. This refusal covers both sharing cases. Even when the shared channel's workspaces all belong to your one Claude organization and Claude answers direct mentions there, Claude still declines requests made from another conversation. **How to resolve** Point the request at a channel that belongs to a single workspace, or move the conversation to one. ### This channel is now shared across multiple workspaces **What you see** Claude posts in the thread: > This channel is now shared across multiple workspaces, so this thread's earlier session can't continue here. Please @-mention me in a new thread. **What it means** The channel became shared after this thread's session started, so the session is still bound to one workspace's configuration and can't continue in front of every workspace that now sees the channel. **How to resolve** Mention Claude in a new thread; new threads start under the channel's current sharing. ## Console errors ### Couldn't load Slack scopes **What you see** A banner at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), on the **Slack** tab under **Claude Tag's access**, reads: > Couldn't load Slack scopes. Reload the page to try again. **What it means** The request that loads your scope list from Claude's backend failed; it isn't a Slack permissions problem, and your configuration is intact. The page shows the error instead of an empty list so that a failed load doesn't look like an unconfigured workspace. **How to resolve** 1. Reload the page. If the reload worked, the scope list renders. That's the usual outcome. 2. If the banner persists across reloads, check [`status.anthropic.com`](https://status.anthropic.com) for an active incident and try again in a few minutes. 3. If it continues with no incident posted, contact [Anthropic support](https://support.claude.com) with the time it occurred. ### The page shows your plan as Free **What you see** You open the admin console expecting your organization's settings and land on your personal account settings instead, showing the **Free plan** and no Claude Tag section anywhere. **What it means** You're signed into a personal claude.ai account, which is a separate workspace from your organization. claude.ai sends a personal account to its own settings page rather than to the admin console, so the **Free** you see is your personal account's plan, not a broken admin page. **How to resolve** Use the workspace switcher in claude.ai to switch to your organization, then reopen [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). If the switch worked, the page shows your organization's plan and the Claude Tag settings. ### Already connected to a different organization **What you see** You paste a pairing code on the setup page and the console rejects it, saying the workspace is already connected to a different organization. **What it means** A Slack workspace can pair with only one Claude organization at a time, and this one is already paired elsewhere. If your company has more than one Claude organization, the existing pairing is often in a test or trial org. **How to resolve** 1. Find the Claude organization that holds the pairing. Check any other organizations your company has. 2. Have an Owner in that organization [disconnect the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing) from their **Connected workspaces** list. 3. Send `@Claude connect` again for a fresh code and redeem it here. Disconnecting deletes the workspace's Claude data, including its memory, channel configurations, sessions, and the routines set up in its channels. The deletion can't be undone. See [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle) for the full list of what's deleted. ### Claim code is invalid, expired, or already used **What you see** You paste a pairing code on the setup page and the console says the claim code is invalid, expired, or already used. **What it means** Pairing codes are single-use and expire 15 minutes after Claude posts them. The code was redeemed already, timed out, or came from a different workspace. On Enterprise Grid, a Grid org admin's reply includes two codes: a workspace code (starting with `workspace_`) and a Grid-wide code (starting with `enterprise_`). **How to resolve** Ask the Slack admin to send `@Claude connect` again and paste the fresh code right away. Reinstalling the app is not required. ## Nothing responds Most of the silence problems in this section span a whole workspace or channel and come down to configuration. If Claude stays silent in one thread but answers everywhere else, a setting isn't the cause. Either Claude's session for that thread is stuck, or the thread is muted. See [Claude went silent in one thread, but responds elsewhere](#claude-went-silent-in-one-thread-but-responds-elsewhere). ### Claude went silent in one thread, but responds elsewhere **What you see** In one thread, an "is thinking…" line appeared under a request and no reply followed, while Claude kept answering normally in other channels and threads. **What it means** First check the thread for a notice from Claude that begins `:mute: Claude is muted in this thread`. If that notice is there, the thread is muted and the session isn't stuck. A 👎 reaction on one of Claude's replies mutes the thread and posts that notice. If Claude's session for the thread was partway through a reply, the reaction also stops that reply. To bring Claude back to a muted thread, send `@Claude !unmute` in the thread or @-mention Claude there, as [Thumbs-down reactions and muting](/docs/claude-tag/users/commands#thumbs-down-reactions-and-muting) describes. Without that notice, the session behind that thread is stuck: it hasn't replied and hasn't posted an error. Because Claude responds everywhere else, the problem is confined to that one session, and none of the configuration fixes in the entries below apply. **How to resolve** Have someone in the thread send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session). The command archives the stuck session and starts a fresh one that rereads the thread, so a follow-up message in the same thread gets an answer. Starting a new thread and restating the request also works. Restarting abandons whatever the session was midway through, and there's no way to resume it. A silent session may still be working through a long task, so treat `!restart` as a last resort. If the same request stalls again on the fresh session, send [feedback](/docs/claude-tag/users/commands#send-feedback) from that thread so Anthropic can investigate. ### Claude is silent everywhere on Enterprise Grid **What you see** Mentions get no reaction and no reply in every channel and DM across the Grid, and nothing was changed on the Claude side. **What it means** On Enterprise Grid, the Claude app's organization-level authorization can be revoked on Slack's side without anything changing in Claude. When it is, Claude never receives the mentions at all. **How to resolve** Reinstall over the existing app. Don't uninstall first; installing over the top is what carries your existing settings over. 1. As a Slack org owner or org admin, sign into one of the Grid's workspaces, not the organization-level admin page. The install option only appears from inside a workspace. 2. Open [Claude for Slack](https://claude.com/claude-for-slack), select **Add to Slack**, and choose **Install to entire organization**. 3. Mention `@Claude` anywhere. If the reinstall worked, the mention gets a reaction and a reply. The pairing survives the reinstall, so a normal reply means you're done. A reply that says the workspace isn't set up means the pairing needs to be redone; see [This workspace isn't set up for Claude Tag yet](#this-workspace-isn%E2%80%99t-set-up-for-claude-tag-yet). ### DMs never respond on Enterprise Grid **What you see** Channels in the paired workspace work normally, but some users' direct messages with Claude answer with a redirect to setup instructions, even after their account connects. **What it means** On Enterprise Grid, direct messages follow each user's home workspace, not the workspace you paired. A user homed in a Grid workspace the pairing doesn't cover gets the setup redirect in DMs. **How to resolve** Pair the whole Grid rather than one workspace. When a Grid Org Owner or Org Admin sends `@Claude connect`, the reply includes two codes; redeem the one starting with `enterprise_` (not the `workspace_` one) in the pairing step. See [Pair on Enterprise Grid](/docs/claude-tag/admins/workspaces#pair-an-enterprise-grid). ### This workspace isn't set up for Claude Tag yet **What you see** Claude replies to a mention: > This workspace isn't set up for Claude Tag yet. A workspace admin can run `@Claude connect`, or set it up here. The reply varies with the sender: someone who isn't a Slack workspace admin is told to ask their Claude workspace owner to run `@Claude connect`, without the settings link. **What it means** The Slack workspace hasn't been paired with a Claude organization. **How to resolve** Run [the pairing flow](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace). If the fix worked, a mention in the workspace gets a reply. ### Using the legacy Claude in Slack bot. Ask your Claude workspace owner to enable Claude Tag. **What you see** Claude posts "Using the legacy Claude in Slack bot. Ask your Claude workspace owner to enable Claude Tag." as a short notice in the thread just before its first reply. **What it means** The earlier per-user Claude in Slack app answered the message instead of the new version. That happens when the Slack workspace isn't paired with a Claude organization that has Claude Tag turned on, or when the channel's or workspace's **Claude Tag version** is set to **Legacy**. Turning Claude Tag on needs an Owner of your Claude organization, not a Slack workspace owner. **How to resolve** The fix is in claude.ai admin settings, not in Slack. An Owner turns Claude Tag on at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) and [pairs the workspace](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace). If the workspace is already paired, check the **Claude Tag version** on the channel's scope, then on its workspace's, and set it to **New** or **Inherit**; see [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/migrate-from-earlier). Once Claude Tag is on and the workspace is paired, the notice stops appearing. ### Claude Tag is turned off for your organization **What you see** Claude replies to a mention: > Claude Tag has been turned off for your Claude organization (the one this Slack workspace is connected to). A Claude admin for that organization can turn it back on in Claude admin settings. The same reply appears on every surface: channel mentions, DMs, and `@Claude connect`. In a DM, the parenthetical instead names the organization your connected claude.ai account belongs to, because that's the organization whose setting failed the check. **What it means** The **Enable Claude Tag for your organization** toggle is off in admin settings, or your organization isn't enabled for Claude Tag. The toggle that matters is the one in the Claude organization the reply's parenthetical points to. **How to resolve** 1. An Owner switches the toggle on at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). If the toggle was the problem, a mention in Slack now gets a normal reply. 2. If the message persists, check which Claude organization the workspace is paired to. If your company has more than one (a trial organization alongside the main one, for example), an Owner in the wrong organization can [revoke the pairing](/docs/claude-tag/admins/workspaces#revoke-a-pairing) so you can pair the workspace to the right one. 3. If the right organization has the toggle on and the message persists, contact your account team to confirm Claude Tag is enabled for it. Revoking the pairing deletes the workspace's Claude data, including its memory, channel configurations, sessions, and the routines set up in its channels. The deletion can't be undone. See [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle) for the full list of what's deleted. ### Claude Tag is unavailable because Routines are not enabled **What you see** Claude replies to a mention or a DM: > Claude Tag is unavailable because Routines aren't enabled for your organization. Admins can manage Routines at claude.ai → Admin settings → Claude Code. In the message, "claude.ai → Admin settings → Claude Code" is a link to that settings page. When Claude can't check the setting in the moment, the reply reads "Couldn't verify your organization's settings right now. Please try again in a moment." instead. **What it means** Your organization doesn't have Routines enabled, which Claude Tag requires. Anyone who mentions Claude in a channel or DMs it gets this reply, and Claude does no work. The "Couldn't verify" reply means the check couldn't complete rather than that Routines is off. **How to resolve** An admin enables Routines from the Claude Code page in admin settings, at [`claude.ai/admin-settings/claude-code`](https://claude.ai/admin-settings/claude-code). Once Routines is enabled for your organization, mention Claude again; a normal reply means the setting took effect. For the "Couldn't verify" reply, wait a moment and mention Claude again. ### Restricted compliance settings block Claude Tag **What you see** Claude replies to a mention in a channel: > Claude isn't available for organizations with restricted compliance settings. In a DM with Claude, on the Claude app's **Home** tab, and in Slack's assistant panel, the message reads instead: > Claude in Slack is not available for your organization In a DM and in the assistant panel, that message is shown only to you and isn't kept in the conversation, while the **Home** tab continues to show it. Other Claude Tag actions in the same organization return similar messages that end with "not available for organizations with restricted compliance settings." **What it means** Your Claude organization has a restricted compliance configuration, such as Zero Data Retention (ZDR). Claude Tag retains channel memory and session transcripts, so it isn't available to organizations under that configuration; see [what Claude Tag retains](/docs/claude-tag/concepts/security-and-data). **How to resolve** 1. In a channel, the message is about the organization the workspace is paired to. Check which Claude organization that is. If your company has more than one, such as a trial organization alongside the main one, the workspace may be paired to the wrong one; an Owner in that organization can [revoke the pairing](/docs/claude-tag/admins/workspaces#revoke-a-pairing) so you can pair the workspace to the right one. 2. In a DM or on Claude's Home tab, the message is about the organization your own Claude account is connected to. If you also belong to a Claude organization without ZDR, click **Disconnect** on Claude's Home tab, then reconnect with that organization active. 3. If the organization in question is the intended one, no setting lifts the restriction; Claude Tag isn't available to organizations under it. Contact your account team with questions about your organization's compliance configuration. ### Claude is disabled in this channel **What you see** Claude replies in the channel: > Claude is disabled in this channel. Your admin can re-enable it here. Only the first sentence is fixed. A sender who isn't a Slack workspace admin is told to ask their Claude workspace owner to re-enable it, with a link to the Claude Tag product page instead of admin settings. **What it means** This channel's scope has **Claude Tag version** set to **Off**. If you have the [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) instead of per-scope version settings, the same notice means the switch is off, or the channel's workspace is set to **Off** on its own. **How to resolve** An Owner turns the scope back on: 1. Open [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). 2. Under **Claude Tag's access**, open the **Slack** tab and select the channel's scope. 3. Expand **Advanced**. 4. Set **Claude Tag version** to **New**. If you have the [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) instead of per-scope version settings, check that the switch is on at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag**. If the fix worked, a mention in the channel gets a reply. ## Access and connections Access and connection errors usually mean Claude responded but couldn't reach a connected service, a repository, or a capability the sender's seat doesn't include. A scope left on **Legacy** only looks like an access problem; there, the earlier Claude in Slack answers instead of Claude Tag, so bundles and connections never apply. ### Claude says a host isn't allowed or it can't reach the internet **What you see** Claude in a channel says a host isn't allowed, a network request was blocked, or it can't fetch a page, even though the request was ordinary HTTP. **What it means** A channel session's outbound network access is deny-by-default. A host is reachable when a bundle's connection or [Domains list](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential) allows it, or when the network access setting of the environment the scope's sessions run on allows it; anything else is blocked. Web search is separate and works regardless, so Claude can answer from search while being unable to fetch the same page; enabling web search in claude.ai admin settings doesn't open network access for channels. See [Web search vs. network requests](/docs/claude-tag/concepts/agent-identity#web-search-vs-network-requests). **How to resolve** * For specific hosts, add them to the bundle's [Domains list](/docs/claude-tag/admins/add-connections#add-a-domain); if the channel's scope has no bundle attached, [attach one](/docs/claude-tag/admins/attach-to-scope) first. A credential-bearing service belongs in a connection instead. * For broad access, pin an organization-scoped environment whose network access level is Full access on the scope; see [the environment entry below](#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one). Test in a new thread. If the fix worked, the fetch that failed succeeds there. ### A connection works in one channel but not another **What you see** Claude uses a connected service without trouble in one channel, and in another channel says it has no access to the same service. **What it means** Bundles attach per scope. The working channel's scope has the bundle; the failing one likely doesn't. **How to resolve** Attach the bundle to the failing channel's scope, or move the work to a channel under a covered scope. Test in a new thread, or ask Claude to use the service by name in the existing one. If the fix worked, asking `@Claude what can you access from this channel?` in a new thread lists the service. ### GitHub doesn't work in this channel **What you see** In the channel, Claude says it has no GitHub access, can't find a repository, or opens pull requests under the asker's name instead of its own. **What it means** The most likely cause is a channel whose scope still has **Claude Tag version** set to **Legacy**, so the earlier Claude in Slack answers instead of Claude Tag. The other causes are a missing bundle attachment, a stale thread, an ungranted repository, or a repository the GitHub App installation doesn't cover. **How to resolve** Go through these checks in order; the same checks, in the same order, apply when GitHub worked in a channel and then stopped. 1. **Which version answers the channel**: if `@Claude` opens pull requests under the asker's name, the channel is on **Legacy**, and bundles only apply where Claude Tag answers. Switch the scope's **Claude Tag version** setting per [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/restrict-access#migrate-from-the-earlier-claude-in-slack). You're on the right version when pull requests open under the Claude GitHub App. 2. **A bundle with GitHub access on this channel's scope**: bundles attach per scope, so the bundle that carries GitHub access must be attached to a scope that covers this channel; [Attach the bundle to a scope](/docs/claude-tag/admins/attach-to-scope) covers attachment and inheritance. If the bundle is attached, asking `@Claude what can you access from this channel?` in a new thread lists GitHub. 3. **A fresh thread**: a new thread picks up every configuration change, so test in one before checking anything further. 4. **The repository granted in the bundle**: the repository must be listed in the bundle's **Repositories** tab, per [Grant repository access](/docs/claude-tag/admins/configure-github#grant-repository-access). If the repository is granted, asking Claude to read a file from it works in a new thread. Granting makes the repository available to clone, but the code doesn't enter a session until a request names it. 5. **The GitHub App installation covers the repository**: if Claude reports a repository isn't available, isn't configured, or returned a 403, check the installation, since the app's repository selection is upstream of the bundle grant. At [`claude.ai/admin-settings/github`](https://claude.ai/admin-settings/github), the organization that owns the repository should show **Connected** under **Connected GitHub accounts**. If its row shows a **Needs permissions** status instead, the install is waiting on a GitHub organization owner. Click **Review permissions** to approve it on github.com. If you aren't a GitHub organization owner, use **Copy message** under **Not a GitHub account owner?** on that settings page to send the request to someone who is. If the organization isn't listed at all, install the app with **Install on another organization**; [Link your GitHub organization](/docs/claude-tag/admins/configure-github#link-your-github-organization) covers both. For GitHub Enterprise Server repositories, confirm [the GHE host is registered](/docs/claude-tag/admins/configure-github#github-enterprise-server) instead. The github.com App install doesn't cover them. ### I hit an authentication error and couldn't finish this turn **What you see** Claude posts in the thread: > I hit an authentication error and couldn't finish this turn. This can be temporary (for example a GitHub rate limit) — mention me to retry in a few minutes. If it keeps happening, this session may lack access to a repository it needs, or its credentials or integration may need to be reconnected. **What it means** Claude's own request failed an authentication check partway through the turn, so it stopped, keeping the work done so far. The cause is usually temporary, such as a GitHub rate limit on the session's requests, and a retry a few minutes later clears it. When the message repeats, the session likely can't reach a repository it needs. This message doesn't point at a service you connected. When a connected service's credential fails, Claude reports that as a tool error inside its reply, not with this notice. A DM sender whose seat doesn't include Claude Code gets [Your Claude account is connected, but it doesn't have access in this organization](#your-claude-account-is-connected-but-it-doesn%E2%80%99t-have-access-in-this-organization) instead. **How to resolve** Have the requester mention Claude in the same thread after a few minutes; the session picks up where it stopped. If the message repeats on every retry, check the repository access for that channel with the steps in [GitHub doesn't work in this channel](#github-doesn%E2%80%99t-work-in-this-channel), then start a new thread. If access checks out and the message still recurs, contact [Anthropic support](https://support.claude.com) with the channel and the time it happened. ### Your Claude account is connected, but it doesn't have access in this organization **What you see** Claude replies in the DM: > Your Claude account is connected, but it doesn't have access in this organization yet, usually because it needs a seat that includes Claude Code. A Claude admin can add one in your organization's settings. Once they do, mention me here and I'll pick this back up. **What it means** DMs run on the user's own claude.ai account and need a seat that includes Claude Code; this user's seat doesn't include it. Mentioning `@Claude` in a channel doesn't depend on the sender's seat. **How to resolve** Assign the user a seat that includes Claude Code on the **Members** page at [`claude.ai/admin-settings/members`](https://claude.ai/admin-settings/members), then have them mention Claude in the same DM thread. If the fix worked, the DM gets a reply instead of this message. ## Session start errors Session start errors appear before any work begins. Some are transient and clear on retry; the rest point to capacity or environment configuration. ### Still waiting for available capacity **What you see** Claude posts in the thread: > Still waiting for available capacity — your request is queued and will start automatically. Replies in this thread are picked up automatically. **What it means** The session was created and is still waiting for compute to run it. Why it waits differs between Anthropic-hosted and self-hosted [environments](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope). On an Anthropic-hosted environment, capacity is temporarily busy or the session is taking longer than usual to start, and the session normally starts on its own. If it never starts, Claude posts the [Session failed to start](#session-failed-to-start-the-session-container-never-connected) message instead. On a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments), no runner has claimed the session yet. The session waits in the environment's queue until a runner claims it. **How to resolve** On an Anthropic-hosted environment, wait; no action is needed. On a self-hosted environment, use [Troubleshooting](https://code.claude.com/docs/en/self-hosted-environments-deploy#troubleshooting) in the self-hosted environments guide to find out why no runner is claiming the session. The queued session starts once a runner claims it. Either way, users should reply in the same thread if they have more to add, since starting a new thread only queues a second session behind the first. ### Session failed to start: the session container never connected **What you see** Claude posts in the thread: > Session failed to start: the session container never connected — please try again **What it means** The session's compute container didn't come up in time. This is transient. **How to resolve** Mention Claude in the same thread to retry. If the retry worked, the session starts and Claude begins the task. ### Something went wrong starting a session **What you see** Claude posts in the thread: > Something went wrong starting a session. Try again in a moment. When Claude can name the cause, it posts one of these instead: | Message | Cause | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Hit the session rate limit — try again in a few seconds." (or "in about Ns" when Claude knows the wait) | Too many sessions started at once; wait, then mention Claude again | | A message naming a specific repository that isn't available or isn't configured | The repository isn't granted for this channel; see [GitHub doesn't work in this channel](#github-doesn%E2%80%99t-work-in-this-channel) | | "That environment or repo isn't configured for Claude Code. Check claude.ai/code and try again." | The scope's pinned environment isn't set up; see [Channel sessions use the wrong environment](#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one) | | "Claude is having trouble starting sessions right now. Try again in a minute." | The service that runs sessions is briefly unavailable; retry | | "You don't have permission to start a session here." | A permission check refused to start the session; when Claude knows which check failed, the message names it | **What it means** This is the catch-all for session-start failures that don't map to a more specific message, so the cause varies. It's usually transient. **How to resolve** Mention Claude again in the same thread before changing any configuration; the retry usually clears it. If a specific message from the table above appears instead, follow its row. ### Channel sessions use the wrong environment, or can't find one **What you see** Sessions in a channel start on an environment you didn't expect, or session starts fail with the environment message from the table above. **What it means** Sessions run on the environment or runner pool set on the nearest scope above them, or on the organization's default environment when none is set; [Configure the environment for a scope](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope) covers the picker. The picker only lists environments scoped to the organization; an environment created under an individual account doesn't appear, because channel sessions run with no user account attached. **How to resolve** If the environment you want isn't in the picker, create it as an [organization-shared environment](https://code.claude.com/docs/en/cloud-environments#organization-shared-environments) from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings), then pin it on the scope. Don't create it at [`claude.ai/code`](https://claude.ai/code): environments you create there belong to your individual account, so they never appear in the picker. If the fix worked, a new thread's session runs on the pinned environment. See the [glossary entry on environments](/docs/claude-tag/concepts/glossary#environment). ## Related resources * [Setup overview](/docs/claude-tag/admins/setup-overview): re-walk the setup steps if the failure points to one you skipped * [User troubleshooting](/docs/claude-tag/users/troubleshooting): for problems people hit in channels * [Give feedback](https://support.claude.com): when it's a bug, not a configuration issue # Manage workspaces and versions Source: https://claude.com/docs/claude-tag/admins/workspaces Connect more Slack workspaces or an Enterprise Grid to Claude Tag, choose which Claude version each channel uses, and disconnect a workspace. This page covers managing Slack workspace pairings after initial setup: adding more workspaces, choosing which Claude Tag version each one runs, turning Claude on or off on the Team plan, and disconnecting one. A workspace pairing links one Slack workspace (or Enterprise Grid) to your Claude organization so `@Claude` can run there. Your first pairing was created during [setup](/docs/claude-tag/admins/setup-overview). To add more, you must be an Owner in your Claude organization, and a Workspace Admin (or Grid Org Admin) in the Slack workspace you're adding. ## Pair another workspace You can connect multiple Slack workspaces to one Claude organization. After the first pairing, the page no longer opens on setup, and the Slack row appears under **Where Claude Tag works**. The reverse doesn't hold. A Slack workspace or Enterprise Grid pairs with one Claude organization at a time. To move a pairing to a different Claude organization, an Owner in the organization that currently holds it must [disconnect it](#revoke-a-pairing) first. Until then, the console refuses the new pairing as [already connected to a different organization](/docs/claude-tag/admins/troubleshooting#already-connected-to-a-different-organization). Once the pairing moves, changes the previous organization's admins make in their settings no longer reach that workspace. If your company has more than one Claude organization (a subsidiary with its own, for example), agree on which one holds the pairing before connecting. At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), under **Where Claude Tag works**, either select **+ Connect** at the top right, or open the **⋮** menu on the Slack row and select **+ Add workspace**. In any channel of the new workspace, send `@Claude connect` with no other text, as a new top-level message or in a thread where Claude isn't already working, then paste the code Claude sends you into the dialog. Pick a channel that belongs to just the new workspace. Claude can decline to reply in [guest and shared channels](/docs/claude-tag/admins/troubleshooting#guest-and-shared-channels). If your organization used the earlier Claude in Slack app, the dialog header reads **Switch to Claude Tag** instead of **Set up Claude Tag for your workspace**. The steps are the same, and the new workspace is added alongside your existing one, not in place of it. **You'll see:** the new workspace in the Slack row's connected list and as a scope in the **Claude Tag's access** section. ### Pair an Enterprise Grid When a Grid Org Owner or Org Admin sends `@Claude connect`, the reply includes two codes. The `workspace_` code pairs only the workspace it was sent from. The `enterprise_` code pairs every workspace in the grid at once; redeem it when Claude should work across the grid. The choice matters for direct messages. On Enterprise Grid, DMs follow each user's home workspace rather than the workspace you paired, so pairing a single workspace leaves DMs unanswered for users homed in the grid's other workspaces. The `enterprise_` code covers them all. ## Set the version for a scope Every scope routes to one of four versions. On the Team plan, a single [**Enable Claude Tag** switch](#turn-claude-tag-on-or-off-on-the-team-plan) replaces the control this section describes. The control is at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the scope → **Advanced** → **Claude Tag version**. Channels Claude was added to appear under **Slack** automatically, and the **Search channels** field finds a channel's scope by name or ID. | Label | Effect | | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **New** | Claude Tag. Access bundles, skills, and custom instructions apply | | **Legacy** | The earlier per-user Claude in Slack. Bundles and skills do not apply. Being deprecated; see [Migrate from the earlier app](/docs/claude-tag/admins/migrate-from-earlier) | | **Off** | Neither version responds to channel mentions in this scope. Direct messages are unaffected | | **Inherit** | Use the parent scope's value. Not shown at **Default Slack access** | Both versions answer through the same @Claude app, so **Off** turns off the Legacy version too. To opt out of Claude Tag while keeping the earlier behavior, set the scope to **Legacy**, not **Off**. Per-scope version changes (workspace and channel) are reversible; see [Migrate from the earlier app](/docs/claude-tag/admins/migrate-from-earlier). ## Turn Claude Tag on or off on the Team plan On the [Team plan](https://claude.com/pricing), you turn Claude on or off in every connected Slack workspace with one switch, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag**. The switch doesn't override a workspace set to **Off** on its own. On the Enterprise plan, and in a Team organization whose Slack configuration can't be expressed as one on-or-off choice (a scope set to **Legacy**, a workspace or channel set to **New**, a channel set to **Off**, an access bundle attached to a channel, or a migration from the earlier Claude in Slack still in progress), the workspace and channel entries under **Slack** show a **Claude Tag version** setting instead of the switch; use [Set the version for a scope](#set-the-version-for-a-scope). ### Turn Claude off in channels Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag** and turn the switch off. An @-mention in any channel gets "Claude is disabled in this channel" while the switch is off. Direct messages keep working. To stop those too, turn off the [**Allow direct messages**](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages) toggle. ### Turn Claude back on Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag** and turn the switch on. Everything you set on each scope, such as [access bundles](/docs/claude-tag/admins/attach-to-scope) and [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions), applies again. A workspace set to **Off** on its own stays off, along with its channels; the switch doesn't override a workspace's own **Off** setting. ### Turn Claude off for the whole organization Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) and turn off the **Enable Claude Tag for your organization** toggle at the top of the page, above **Claude Tag's access**. That toggle turns off direct messages too. ### Keep Claude out of specific channels The switch has no per-channel setting. Add [blocked channel patterns](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name) for the channels instead. ### Notices that settings aren't applied When a workspace or channel entry shows a notice that its settings aren't applied, nothing you set there is lost. | Notice | What to do | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "These settings aren't applied while Claude Tag is disabled. They're saved and will take effect once it's enabled." | Go to [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → **Default Slack** → **Enable Claude Tag** and turn the switch on | | "These settings aren't applied while Claude Tag is turned off for this workspace or channel; the org-wide Enable Claude Tag setting doesn't override that. They're saved and will take effect once it's turned back on." | The workspace, or the channel's workspace, is set to **Off** on its own, and the switch doesn't override it. While you have the switch, the admin page has no control for that setting | | "These settings aren’t applied while Claude Tag setup is incomplete for this workspace or channel." | Select the **Resume** *workspace* **setup** button beside the notice and finish that workspace's setup. On a channel's entry, the button's label names the channel's workspace | ## Revoke a pairing In the **Connected workspaces** list, select **Disconnect** on the workspace's row, then confirm in the dialog. Claude stops responding in that workspace's channels immediately, and your organization is no longer billed for Claude usage there. Direct messages run on each member's own Claude account, so they keep working until the deletion below removes the member's account link. A member who reconnects their account afterward can use direct messages again while the app stays installed. When you disconnect a workspace, Anthropic deletes its Claude data: * The workspace's sessions and their transcripts, including members' direct-message conversations with Claude in that workspace * Its channel, workspace, and direct-message memory * The routines set up in its channels, and the artifacts published from them * Its scopes, with their instructions and bundle bindings * The links between members' Slack and Claude accounts Deletion starts as soon as you confirm and runs to completion in the background. This can't be undone. Routines a person set up in a direct message with Claude belong to that person's account and keep running; an Owner can delete them from the [**Scheduled work** tab](/docs/claude-tag/admins/audit). Access bundles belong to your organization, not to a workspace, so they stay available to attach to other scopes; only their bindings to the deleted scopes go. After you disconnect, the Slack row under **Where Claude Tag works** shows **Disconnected** with the workspace's name, and offers a **Reconnect** action, as a button on that row and in the row's **⋮** menu. **Reconnect** reopens the pairing dialog, where you redeem a fresh code from `@Claude connect`. The Slack app stays installed, so a workspace admin can pair the workspace again by sending `@Claude connect` in it, to the same Claude organization or a different one. If you intend the data to be deleted, wait a few minutes before pairing the workspace to the same organization again, because a new pairing that arrives while the deletion is still starting can cancel it. Once the deletion has run, the new pairing starts without the deleted data. Uninstalling the app from the workspace in Slack deletes the same data, whether or not you disconnected first; see [Quiet or remove Claude Tag](/docs/claude-tag/admins/restrict-access#quiet-or-remove-claude-tag). ## Related resources * [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle): what disconnecting deletes, what it keeps, and what other actions do to Claude-side data * [Migrate from the earlier app](/docs/claude-tag/admins/migrate-from-earlier): the upgrade path and what changes for existing users * [Pair your Slack workspace](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace): the first pairing, with the Slack-admin handoff # How agent identity works Source: https://claude.com/docs/claude-tag/concepts/agent-identity Claude Tag acts under its own service accounts in Slack channels, not as you. See how channel access is bounded, how credentials reach it, how Claude uses your personal connectors for your own tasks in a channel, and why DMs differ. Claude Tag's identity depends on where you message it. In Slack channels, Claude acts with its own service accounts, rather than as a specific user. An organization Owner [provisions this identity during setup](/docs/claude-tag/admins/setup-overview), so it arrives with its own account in each system it works in: the Claude app in Slack, the Claude GitHub App on GitHub, and a service account in every other connected tool. Actions it takes are attributed to those accounts; for example, posts come from the Claude app and pull requests show the Claude GitHub App as the author. In organizations where personal connectors in channels is available, Claude can also use your own claude.ai connectors for a task you hand it in a channel, after you allow it. See [Personal connectors in a channel](#personal-connectors-in-a-channel). In direct messages (DMs) between a user and `@Claude`, the provisioned identity does not apply. DMs are one-to-one only; group DMs aren't supported. A DM has no channel to scope it to, so a DM session runs on [the individual's own claude.ai account](#direct-message-channels) instead, with their personal connectors. GitHub is the exception in attribution: a pull request opened from a DM is authored by the Claude GitHub App, the same as in channels, though the session can only work with repositories connected on that user's own account. Owners can disable DMs organization-wide; see [Allow or disable direct messages](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages). How Claude behaves in channels (its standing instructions, plugins, and channel memory) is configured separately from its identity; see [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions), [plugins](/docs/claude-tag/admins/add-connections#attach-plugins), and [memory](/docs/claude-tag/users/memory) for more information. ## Channel sessions When Claude works on a channel task, the request moves through three places: * The ask happens in your Slack workspace, when a user tags Claude to do something or a scheduled task starts. * The work Claude does runs in a sandbox, an isolated working environment built for the thread. * The agent's credentials for any additional connections, such as GitHub or a data warehouse, reach those systems to pull the required information. An organization Owner sets up those credentials as part of [provisioning the identity](/docs/claude-tag/admins/setup-overview#create-accounts-for-claude%E2%80%99s-other-tools). The diagram below traces one request through this process. Diagram showing the request path across three zones, labeled your Slack workspace, Anthropic's infrastructure, and your systems. A task mentioned in the Slack workspace runs in a session sandbox in the middle zone, one sandbox per thread, holding no credentials. Outbound requests pass to Agent Proxy, which injects the credential drawn from the credential store; a request that no rule, domain entry, or environment network access setting allows is blocked. Credentialed requests reach your systems, like GitHub, a data warehouse, monitoring, or any HTTP API. A dashed return path shows results posting back in the thread, as Claude. Diagram showing the request path across three zones, labeled your Slack workspace, Anthropic's infrastructure, and your systems. A task mentioned in the Slack workspace runs in a session sandbox in the middle zone, one sandbox per thread, holding no credentials. Outbound requests pass to Agent Proxy, which injects the credential drawn from the credential store; a request that no rule, domain entry, or environment network access setting allows is blocked. Credentialed requests reach your systems, like GitHub, a data warehouse, monitoring, or any HTTP API. A dashed return path shows results posting back in the thread, as Claude. A user asks Claude to chart last week's signups or fix a deploy test. The task gets a session in a thread under the message. Claude does the work in an isolated environment built for this thread, reading files, writing documents, and running code. The credentials you provision are not placed in the sandbox; they stay in the credential store and are injected at the proxy. When the work needs something outside the sandbox, like calling the GitHub API or querying a warehouse, the request crosses Agent Proxy, the network boundary between the sandbox and everything else. Agent Proxy checks it against the rules an admin configured, and decides whether it proceeds and what credential, if any, travels with it. A matching credential comes from the credential store, where an admin's [connections](/docs/claude-tag/admins/add-connections) are kept. Once saved, a credential is never displayed again; Agent Proxy retrieves it only at the moment of injection and attaches it to the request at the boundary, so the model and the sandbox itself are not given the key. The credentialed request reaches your system, like GitHub or the warehouse, and the result returns to the thread. ### Agent Proxy For each outbound request from the sandbox, Agent Proxy checks the destination against three allow layers. A request goes through if any one of them allows it; a host that none of them allows is blocked. | When the destination | Result | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | Matches a connection's rule, its [allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) | The proxy attaches that connection's credential and forwards the request. The credential stays at the proxy; the model and sandbox are not given it. | | Is on the [bundle](/docs/claude-tag/concepts/glossary#access-bundle)'s [Domains list](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential) but matches no connection | The proxy forwards the request without a credential. | | Is allowed by the network access setting of the [environment](/docs/claude-tag/concepts/glossary#environment) the [scope](/docs/claude-tag/concepts/glossary#scope)'s sessions run on | The proxy forwards the request without a credential. | | Matches none of these | The proxy blocks the request. | A new environment's network access level defaults to Trusted access, so a fresh setup can reach a documented set of package registries and developer hosts before an admin has configured anything. The [cloud environments documentation](https://code.claude.com/docs/en/cloud-environments#default-allowed-domains) lists the covered hosts. To narrow that default, pin an environment with a stricter level, such as No access. The same rules apply to code Claude runs in the sandbox, like `curl` or a `fetch` call: a request is blocked unless its host is allowed by one of the layers above. Agent Proxy carries HTTP and HTTPS only. A protocol that isn't HTTP, such as SSH or a database's native wire protocol, can't cross the proxy even to an allowed host. For the endpoints and addresses your network team may need to allowlist, see [Network requirements](/docs/claude-tag/admins/network-requirements). ### How a host gets allowed A host that none of the three layers above allows is blocked, and Claude names the blocked host in the thread so an admin can add it; see [Give Claude access to your tools](/docs/claude-tag/admins/add-connections). ### Web search vs. network requests Claude can search the web from a channel without any Domains entry. Web search is [Anthropic's built-in web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool), which runs on Anthropic's servers, not code running in the channel's sandbox. The sandbox sends nothing new for a search. Search requests travel to Anthropic the same way the session's model traffic already does, and the searching happens server-side. The [Agent Proxy](#agent-proxy) rules don't apply to web search; fetching a page or calling a service from the sandbox is an outbound network request and follows them. Searching and opening a page are different actions. A search returns content from the pages it matches, which Claude reads and cites, so it can answer from a page that search surfaced. Opening a URL, whether one you pasted or one a search returned, is a fetch from the sandbox, and the host needs an allow layer. That is why Claude can quote a page it found through search and still report that it can't open the same link. The web search capability setting in your organization's claude.ai admin settings governs claude.ai chat; it doesn't govern Claude Tag sessions, in channels or DMs. If Claude reports that it can't reach a host from a channel, the fix is a [domain entry](/docs/claude-tag/admins/add-connections#add-a-domain) or the scope's [environment](/docs/claude-tag/concepts/glossary#environment), not that setting. ### Agent access What Claude can reach in a channel comes from the [Access bundles](/docs/claude-tag/admins/add-connections) an admin attached to that channel's scope. Anyone in the channel gets the same capability, and the same request can do more in `#platform-eng` than in a general channel. This design has four consequences. * **Configure once.** Everyone in the scope can use it immediately. * **Predictability.** What Claude can do never changes based on who asked. * **Personal connectors are separate.** A shared channel session uses only the service-account connections an admin attached. Where [personal connectors in channels](#personal-connectors-in-a-channel) is available, Claude uses the connectors on your own claude.ai account only for your own tasks, after you allow it. * **Clean audit.** Actions the channel session takes in connected tools show up under a service account your security team already knows how to reason about. That service-account identity is also how Claude appears wherever it acts. In Slack, it posts as the Claude app. On GitHub, commits and pull requests show the Claude GitHub App, and pull requests link back to the Slack thread they came from. In every other connected service, actions appear under the service account an admin provisioned, in that service's audit log. ### Personal connectors in a channel A channel session works with the channel's Access bundles, so the [connectors on your own claude.ai account](/docs/connectors/overview) are not part of it. Personal connectors in channels is available to a limited number of organizations. Where it is available and a task you hand Claude needs something only your connectors can reach, Claude can use your connector for that part of the work, and it asks you before it starts. The work runs with your permissions and is recorded under your name. Requests other people make to Claude in the task's thread run with the channel's own access, not with your connectors. Claude is designed to take direction from you, treating what other people post in the thread as information for the task rather than as instructions. [Personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) covers how you approve connector use, when Claude holds a result for your review before posting, what other people in the channel see, and how to stop a task. ## Direct message channels A DM with Claude works differently from a channel. There is no scope to attach an identity to, so a DM session runs with your own claude.ai account instead, the same way a Claude Code session on the web does, using your own connectors and credentials, with results attributed to you (pull requests excepted; the Claude GitHub App authors those from DMs too). The diagram contrasts with the channel path above; the sandbox is the same engine, but everything around it is yours. Diagram showing how a DM session reaches your systems. A message to Claude in a direct message runs in a session sandbox, in a zone labeled Anthropic's infrastructure, the same engine as a channel session, but it runs with your identity. From there it reaches your systems through your own connectors and accounts, like GitHub or Drive, using your own credentials. A dashed return path shows results posting back in the DM, as you. Diagram showing how a DM session reaches your systems. A message to Claude in a direct message runs in a session sandbox, in a zone labeled Anthropic's infrastructure, the same engine as a channel session, but it runs with your identity. From there it reaches your systems through your own connectors and accounts, like GitHub or Drive, using your own credentials. A dashed return path shows results posting back in the DM, as you. The table lines up the two paths on the four dimensions that differ. | | In a channel | In a DM | | :---------- | :--------------------------------------------- | :------------------------------------------------------------------- | | Acts as | Its own service accounts | You | | Access | The channel's Access bundles | Your personal connectors | | Attribution | The agent's accounts, in each tool's audit log | Your name, except pull requests, which the Claude GitHub App authors | | Billing | The organization | Your seat | Three of those differences are worth spelling out. * **Connectors.** The [connectors on your account](/docs/connectors/overview) are available, including MCP servers you've added. * **Billing.** Usage bills to your seat rather than the organization's service key. * **Channel-side configuration.** It doesn't follow you in; the agent's connections and repository grants don't apply in DMs. DM work runs under your credentials, so most of it is attributed to you and can reach only what your own accounts can. Pull requests are the exception: Claude authors them as the Claude GitHub App from DMs too, so a repository's history shows the same author either way, while the repositories it can reach are still only the ones connected on your own account. Use channels for shared work and DMs for personal tasks, or for data you'd rather access under your own authenticated identity than a shared channel credential. ### Claude Tag versus Claude Code in Slack A DM with Claude Tag runs under your own account, which is also how [Claude Code in Slack](https://code.claude.com/docs/en/slack) works, routing a coding @-mention to a Claude Code session on the web under the requester's own account. The two can look identical. The table shows how to tell them apart. | | Claude Tag in a channel | Claude Code in Slack | | :------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------ | | **Runs under** | The agent identity an admin provisioned | Your own Claude account, linked in the Claude app | | **GitHub** | The Claude GitHub App; pull requests belong to the app | Your GitHub connection on claude.ai/code; pull requests open under your account | | **Access** | The Access bundles an admin attached to the channel | Your personal connectors | | **Billing** | The organization | Your seat | If `@Claude` in your workspace opens pull requests as you, you're seeing Claude Code in Slack, not a Claude Tag session. ## Related resources * [Security and data handling](/docs/claude-tag/concepts/security-and-data): where credentials are stored, what leaves your tenant, and what runs unattended * [Give Claude access](/docs/claude-tag/admins/add-connections): provision the access this page describes * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): narrow where this agent identity is allowed to act # Data lifecycle and deletion Source: https://claude.com/docs/claude-tag/concepts/data-lifecycle What Claude Tag stores on Anthropic's side, how long session transcripts and memory are kept, and what disconnecting a workspace, uninstalling the app, deleting a Slack channel, removing a scope, or leaving the organization does to that data. Claude Tag keeps a record of its work on Anthropic's side, separate from the messages in your Slack workspace. This page is for the Owner or security reviewer who needs to know what that record contains, how long Anthropic keeps it, and which actions in Slack or in your Claude admin settings delete it. For each action, the tables below say what is deleted and whether Claude keeps responding, because the two don't always go together. ## What Anthropic stores There are two copies of the work Claude does in Slack. The messages, canvases, files, bookmarks, and pins in Slack stay in Slack under your workspace's own retention settings. Anthropic doesn't remove them when Claude-side data is deleted, and can't once the app is uninstalled, so delete those in Slack. On Anthropic's side, Claude Tag stores the following for each paired workspace. | What | What it contains | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Session transcripts | The record of one thread's, channel's, or direct message's work. A transcript holds the messages Claude was shown in the conversation and who sent them, files attached there, earlier versions of messages that were later edited, what Claude retrieved while working (Slack search results, messages it read in channels it's in, and data from connected tools), and everything Claude said and did | | Memory | The notes Claude saves for each channel, the workspace-shared notes from public channels, and separate notes for each direct-message conversation. See [What Claude Tag remembers](/docs/claude-tag/users/memory) | | Routines | The scheduled and run-once tasks set up in channels or in direct messages, with their instructions and run history | | Scopes and their settings | Each workspace and channel [scope](/docs/claude-tag/concepts/glossary#scope), with its custom instructions, version setting, and Access bundle bindings | | Access bundles | The connections and credentials an Owner provisions. Bundles belong to your organization, not to a workspace | | Account links | The link between each member's Slack account and their Claude account, and the tokens that link uses | | Published artifacts | Pages a session published to claude.ai. See [Artifact visibility](/docs/claude-tag/concepts/security-and-data#artifact-visibility) | | The app's installation credential | The token the Claude app uses to read and post in your Slack workspace | Deleting or editing a message or file in Slack doesn't remove it from a transcript that already includes it. Messages from other people in the conversation, including guests, become part of the transcript the same way and are held as your organization's data. ## How long data is kept During the beta there is no automatic retention period for Claude Tag data. Session transcripts, memory, routines, scopes, and account links are kept until one of the actions on this page deletes them. Your organization's custom data retention setting doesn't apply to Claude Tag transcripts or memory. It does apply to artifacts a session published, which follow the same retention rules as your organization's other shared artifacts. Sessions Claude stops using are archived, not deleted. That includes a thread's session after someone sends [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session), a session that closed because the thread's first message was deleted before anyone replied, and the channel-level sessions Claude replaces after about an hour of quiet or a day of age. An archived session keeps its full transcript until the channel's or workspace's data is deleted. Letting a plan lapse, turning Claude Tag off, or no longer using it doesn't delete anything on its own. To delete a workspace's data when you stop using Claude Tag, [disconnect the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing) or uninstall the app. When an action below deletes data, deletion starts right away and completes in the background. Copies can remain in routine backups for a limited period after that before they age out. ## What each action does to Claude-side data The first table covers actions taken in Slack, and the second covers actions taken in Claude. "Claude-side data" means the items listed under [What Anthropic stores](#what-anthropic-stores). ### Actions in Slack | Action | Claude-side data | Does Claude keep responding? | | :------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- | | A Slack admin uninstalls the Claude app from a workspace | Deleted, the same as [disconnecting the workspace](#actions-in-claude), plus the app's installation credential for that workspace. Access bundles, and routines members set up in direct messages, stay | No. The app is removed from the workspace | | On Enterprise Grid, a Grid admin removes an org-wide installation of the app, from the whole grid or from one of its workspaces | Nothing is deleted. To delete the data, an Owner disconnects the grid, or a workspace that has its own pairing, in your Claude admin settings | No | | A channel is deleted in Slack | Deleted: that channel's sessions and transcripts, including earlier sessions Claude had archived there, its channel memory, and its scope with the routines and artifacts that belong to it. Notes Claude saved to workspace memory from a public channel aren't tied to the channel and stay until you delete them or disconnect the workspace, as does anything created under the workspace scope rather than the channel's own | Not applicable | | A channel is archived in Slack | Nothing is deleted. Unarchiving the channel picks its memory, routines, and sessions back up | Not while the channel is archived | | A public channel is made private | Nothing is deleted. Claude archives the channel's earlier sessions, and new sessions save to the channel's own memory store. Notes Claude saved to workspace memory while the channel was public stay there, readable from the workspace's other channels; see [Workspace memory](/docs/claude-tag/users/memory#workspace-memory) | Yes | | Someone removes Claude from a channel with `/remove @Claude` | Nothing is deleted. The channel's memory, routines, and past sessions stay on record, and re-adding Claude picks them back up. The channel's routines keep firing while Claude is out of the channel but can't post there | No | | Someone edits a message Claude read | Claude receives the edit as a note, and the transcript keeps both the earlier and the edited text | Yes | | Someone deletes a reply, or deletes a thread's first message after others have replied | Nothing is removed from the transcript, and Claude isn't notified | Yes | | Someone deletes a thread's first message before anyone has replied | The session closes and is archived with its transcript, including the deleted message | No. The thread is gone | | Someone deletes a file they attached in a thread Claude worked in | The copy Claude took into the session stays with the session and its transcript | Yes | | A member's Slack account is deactivated | Nothing is deleted. Their account link, direct-message conversations and notes, and their messages in channel transcripts stay. Channel routines they created keep running, and routines they set up in direct messages keep running until they're removed from your Claude organization | Not to that member | ### Actions in Claude | Action | Claude-side data | Does Claude keep responding? | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | An Owner [disconnects a workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing) | Deleted: the workspace's sessions and transcripts, including members' direct-message conversations there; its channel, workspace, and direct-message memory; the routines set up in its channels and the artifacts published from them; its scopes with their instructions and bundle bindings; and members' account links. The Slack app and its installation credential stay so a workspace admin can pair again, and Access bundles, routines members set up in direct messages, and what Claude posted in Slack stay too. Pairing the same workspace to the same organization again within a few minutes can cancel the deletion | Stops in channels immediately. Direct messages keep working on each member's own Claude account until the deletion removes that member's account link | | An Owner disconnects an Enterprise Grid | The same as disconnecting a workspace, for every workspace in the grid that doesn't have its own workspace pairing, plus the app's installation credentials for those workspaces. Workspaces you paired individually stay connected and keep their data until you disconnect them | Stops in the affected workspaces | | An Owner removes a channel's scope with **Remove this scope** in the **Claude Tag's access** section | Deleted: the channel's sessions and transcripts recorded up to that moment, including threads still in progress, its memory, its routines, and the artifacts published from it. The Slack channel itself is unchanged | Yes. Claude stays in the channel and, when tagged again, starts fresh under the access it inherits from the workspace. To stop it as well, run `/remove @Claude` or set the scope's version to **Off** first | | An Owner sets a scope's version to **Off**, turns off Claude in Slack for the organization, or turns off [direct messages](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages) | Nothing is deleted. Turning the setting back on resumes with the existing memory, routines, and sessions | No, in the affected scope | | An Owner detaches a bundle from a scope, or deletes an Access bundle | Detaching removes the binding, and deleting a bundle removes its credentials everywhere it was attached. Memory, routines, and transcripts are unaffected | Yes, without that access | | An Owner deletes entries from a scope's memory files, or someone in the channel tells Claude to forget an entry | The entry is removed from what Claude reads and from the memory files view. Earlier versions of the scope's memory remain stored with the scope until the scope's data is deleted | Yes | | An Owner deletes a routine from the [**Scheduled work** tab](/docs/claude-tag/admins/audit#what-the-audit-view-lists), or someone asks Claude to delete it in the channel or direct message where it was set up | The routine and the sessions it ran are deleted. Pausing a routine there, or disabling it from the channel, keeps it on record | Yes | | A member selects **Disconnect** in the Claude app's **Home** tab in Slack | Removes the link between their Slack and Claude accounts and revokes the tokens Claude Tag held for them. Their earlier direct-message conversations and notes, and channel work they started, aren't deleted; those go with the workspace | In channels, yes. Direct messages and personal connectors stop working for that member until they reconnect | | A member is removed from your Claude organization | Nothing is deleted. They lose access within minutes, and routines they set up in direct messages are turned off. Their account link, direct-message conversations, and notes stay until the workspace is disconnected | Not to that member | | A member deletes their own Claude account | On Team and Enterprise plans, deleting an individual account doesn't remove the Claude Tag data your organization holds about that member, including their direct-message conversations and notes and their account link. A member who wants the link and its tokens removed can select **Disconnect** in Slack before deleting their account | Not to that member | | Your Claude organization is deleted | All Claude Tag data for every paired workspace is deleted as part of the organization deletion. The Slack app isn't uninstalled by this, and its installation credential remains until the app is uninstalled, so uninstall it from each workspace in Slack as well | No | | Your organization adopts Zero Data Retention or another restricted compliance configuration after pairing | Nothing already stored is deleted. Disconnect each workspace to delete its data | No. Claude stops responding in Slack and new pairings are refused; see [Restricted compliance settings block Claude Tag](/docs/claude-tag/admins/troubleshooting#restricted-compliance-settings-block-claude-tag) | ## Direct messages A direct-message conversation with Claude is stored the same way a channel thread is, as a session with a transcript, together with the notes Claude keeps for that conversation. Both are deleted with the workspace the member messaged Claude from, when that workspace is disconnected or the app is uninstalled from it, and when your Claude organization is deleted. They aren't deleted when the member selects **Disconnect** in Slack, when the member's Claude account is deleted on a Team or Enterprise plan, or when an Owner turns off direct messages. Routines a member set up in a direct message belong to that member's Claude account. An Owner can delete them from the **Scheduled work** tab, or the member can ask Claude in the direct message to delete one. They are turned off when the member is removed from your Claude organization, and disconnecting the workspace doesn't delete them. When a member first opens a direct message with Claude, the welcome Claude writes, which suggests channels based on the member's recent public-channel activity, runs as a short session that is stored like any other. ## Delete data or request deletion The controls that delete Claude Tag data, from largest to smallest: * **Disconnect a workspace or an Enterprise Grid** at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), or uninstall the app from the workspace in Slack. Deletes all of that workspace's data. See [Revoke a pairing](/docs/claude-tag/admins/workspaces#revoke-a-pairing) * **Remove a channel's scope** in the **Claude Tag's access** section. Deletes that channel's data recorded so far * **Delete a scope's memory files**: select **View memory files** in the scope's options menu, choose a file, then select **Delete**. You can also tell Claude in the channel to forget an entry. See [Check and correct what Claude Tag remembers](/docs/claude-tag/users/memory#check-and-correct-what-claude-tag-remembers) * **Delete a routine** from the **Scheduled work** tab, or ask Claude to delete it in the channel or direct message where it was set up. See [Audit Claude Tag activity](/docs/claude-tag/admins/audit) There is no control in Slack or in your Claude admin settings that deletes a single thread's transcript on its own. During the beta, Claude Tag session transcripts and memory aren't included in your organization's data exports, and the Compliance API doesn't list or delete Claude Tag sessions. For a deletion request these controls don't cover, contact your account team or [privacy@anthropic.com](mailto:privacy@anthropic.com). ## Audit records for deletions Disconnecting a workspace or an Enterprise Grid, and removing a channel's scope, are recorded in your organization's audit log, which you read through the [Compliance API](https://platform.claude.com/docs/en/api/compliance). Deletions that start in Slack, such as deleting a channel or uninstalling the app, aren't recorded there, and neither is a member's **Disconnect** in the **Home** tab. ## Related resources * [Security and data handling](/docs/claude-tag/concepts/security-and-data): sandbox isolation, credential storage, and artifact visibility * [Manage workspaces and versions](/docs/claude-tag/admins/workspaces#revoke-a-pairing): the Disconnect control and what it deletes * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access#quiet-or-remove-claude-tag): the ways to quiet or remove Claude, and which keep data * [What Claude Tag remembers](/docs/claude-tag/users/memory): reading, correcting, and deleting memory * [Audit Claude Tag activity](/docs/claude-tag/admins/audit): scheduled work, memory files, and network events # Claude Tag for Claude Code users Source: https://claude.com/docs/claude-tag/concepts/for-claude-code-users Which parts of a Claude Code setup carry into Claude Tag, which move to admin settings, and how Slack threads map to sessions. Claude Tag runs the same engine as Claude Code. When you tag `@Claude` in Slack with a task, a session starts in a sandbox that your organization configures, not on your machine. That sandbox is the same infrastructure that runs [Claude Code on the web](https://code.claude.com/docs/en/web-quickstart), described in [Compute and the sandbox](/docs/claude-tag/concepts/security-and-data#compute-and-the-sandbox). If you use Claude Code on the web, a session works the way a web session does, from a fresh clone of your repository rather than from files on your machine. The `CLAUDE.md` files and skills you checked into that repository apply in the session as they do in a web session. If you run Claude Code in your terminal, the settings on your own machine don't reach a session, because the session runs in the sandbox and can't read your machine. For most of those settings, an admin sets a channel-wide counterpart instead, and a few have no counterpart at all. This page shows what happens when a session starts, which admin settings replace your local ones, and how Slack threads map to sessions. ## What happens when a session starts A session begins with a fresh sandbox and no repository checked out. Your repository's Claude Code configuration takes effect only after Claude clones the repository, which happens when your message names a repository that an admin has [granted to the channel](/docs/claude-tag/admins/configure-github#grant-repository-access). | Step | What applies | | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You tag `@Claude` with a task | Your message is the task, and Claude starts work in a sandbox with no repository | | Your message names a granted repository | Claude clones it into the sandbox | | The clone completes | `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, and the skills in `.claude/skills/` [load into the session](/docs/claude-tag/admins/configure-github#what-loads-from-a-repository) | [Hooks](https://code.claude.com/docs/en/hooks) in the repository's `.claude/settings.json` don't run in the session. ## Local settings versus admin settings A session reads configuration from your repository, not from your machine. The `CLAUDE.md` files and skills you checked into the repository load when Claude clones it, as described in [What happens when a session starts](#what-happens-when-a-session-starts). The settings on your machine never load into a session, because a session runs in the sandbox and can't read your machine. That includes your `~/.claude` directory, your personal `settings.json`, your shell environment, and the MCP servers you configured locally. They still apply when you run Claude Code in your terminal. ### Admin counterparts for local settings The table shows what takes the place of each setting from your machine. Where a counterpart exists, an admin sets it for the whole channel. | Claude Code setting on your machine | In Claude Tag | | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/model` | An admin sets the [default model per channel](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope), and you can [switch models in a thread](/docs/claude-tag/users/models) | | Effort level | Not configurable. Sessions run at the model's default effort. | | MCP servers in `.mcp.json` | Not loaded, even when `.mcp.json` is checked into the repository. A session reaches external services only through the [connections an admin set for the channel](/docs/claude-tag/admins/add-connections), and each connection holds that service's credentials. | | Secrets and API keys in your environment | An admin provisions them as channel connections. The raw key never enters the sandbox. It is [added to requests at the network layer](/docs/claude-tag/concepts/agent-identity#agent-proxy). | | Environment variables | An admin sets them on the [environment the channel's sessions run on](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope), and every session in the channel reads them. There is no per-person environment to customize. The values are readable in every session on the environment, so ask an admin to add secrets as connections instead. | | A personal `settings.json` | Not loaded. | | A setup script for your workspace | An admin sets a setup script on the [environment the channel's sessions run on](/docs/claude-tag/admins/customize#configure-the-environment-for-a-scope), and what it installs is in place when each session in the channel starts. For setup that belongs to one repository, use `CLAUDE.md` [install steps](/docs/claude-tag/admins/configure-github#install-project-dependencies) instead. | | Permission prompts | Sessions run in auto mode, where Claude's permission checker reviews each action and can stop it. An admin pre-approves routine actions with [auto mode allow rules](/docs/claude-tag/admins/customize#auto-mode-allow-rules) instead of you approving in the moment. | To change what a session can reach, ask an admin to [add a connection](/docs/claude-tag/admins/add-connections). The change applies to every session in the channel. ## How Slack threads map to sessions You start a session by tagging `@Claude` in a thread with a task, and that session gets its own sandbox. Each reply in the same thread continues the session, so there is no `--continue` or `/resume` to run, and a session stays attached to the thread it started in. See [the lifecycle of a request](/docs/claude-tag/concepts/how-it-works#lifecycle-of-a-request) for what happens between replies. Each thread is its own session with its own sandbox, so run parallel tasks in separate threads the way you would in separate terminal tabs. The sandbox is released after a quiet period, but the conversation stays in the thread, and a later reply continues the session. See [what survives between replies](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies). ## Whose credentials a session uses Claude Code acts with your credentials. What a session acts with depends on whether you tag Claude in a channel or in a direct message. ### In a channel In a channel, Claude acts with credentials of its own, service accounts that [an admin provisions](/docs/claude-tag/concepts/agent-identity#channel-sessions). A pull request comes from the Claude GitHub App rather than from you, and a query against a connected service runs with the channel's credentials no matter who asked. Access is set per channel, not per person. ### In a direct message A [direct message](/docs/claude-tag/concepts/agent-identity#direct-message-channels) runs on your own claude.ai account, with the connectors you added to that account rather than the connections an admin set for the channel, so a DM is the closest match to a Claude Code session on your own credentials. ## Steer a session in the thread Where you would interrupt Claude Code and edit a file or reprompt, [reply in the thread](/docs/claude-tag/concepts/how-it-works#reply-in-the-thread-to-steer). Corrections and added constraints land as messages, and Claude folds them into the running task. ### Keep instructions in channel memory For instructions that should persist beyond one thread, use channel memory, the instructions Claude keeps for one channel and reads in every session there. Keep repository conventions in `CLAUDE.md`. Put channel conventions in memory by telling Claude to remember them: ```text theme={null} @Claude remember for this channel: reports go out as tables ``` See [What Claude remembers](/docs/claude-tag/users/memory) for how memory is scoped and how to correct it. ## Claude Tag versus a bot you build on the API A Slack bot you build on the Claude API is software your team writes and hosts. It calls the API with your key, holds its own Slack tokens, and has the tools and memory you code into it. Claude Tag is Anthropic's hosted Slack app. It takes care of the parts you would otherwise build. * **Hosting.** Each thread gets a Claude Code session in a sandbox Anthropic runs, or in the [environment](/docs/claude-tag/concepts/glossary#environment) your organization pins, under an [agent identity](/docs/claude-tag/concepts/agent-identity) of its own. * **Credentials.** An admin gives Claude [connections](/docs/claude-tag/admins/add-connections) to your tools, and [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) attaches the credentials at the network boundary, outside the sandbox. * **Customization.** [Custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions), [channel memory](/docs/claude-tag/users/memory), and [routines](/docs/claude-tag/users/proactivity) are built in. * **Governance and billing.** [Access controls](/docs/claude-tag/admins/restrict-access) and spend limits are set in claude.ai admin settings, and usage is [billed to the organization's usage balance](/docs/claude-tag/overview#billing-and-spend-limits). ## Related resources * [How Claude Tag works](/docs/claude-tag/concepts/how-it-works): the session model this page maps your setup onto * [How agent identity works](/docs/claude-tag/concepts/agent-identity): why a channel uses the agent's access and a DM uses yours * [Claude Tag settings map](/docs/claude-tag/concepts/settings-map): where each setting your organization owns is set * [Configure GitHub access](/docs/claude-tag/admins/configure-github): what loads from a repository and how installs work in the sandbox # Glossary Source: https://claude.com/docs/claude-tag/concepts/glossary Claude Tag terms defined in one place. See agent identity, Access bundle, channel manager, connection, scope, Agent Proxy, routine, channel memory, environment, and session. ## Access bundle A named set of connections, [domain entries](/docs/claude-tag/admins/add-connections#add-a-domain), repository access, and rules that an Owner creates for Claude to use. Bundles attach to scopes, and one bundle can serve many scopes. See [Give Claude access](/docs/claude-tag/admins/add-connections). ## Agent identity The service accounts Claude acts with: the Claude app in Slack, the Claude GitHub App on code, and the credentials an admin provisions for every other tool. See [How agent identity works](/docs/claude-tag/concepts/agent-identity). ## Agent Proxy The network layer that injects credentials into Claude's outbound requests. The model and the sandbox are not given the key; Agent Proxy adds the credential at the network boundary when a request matches the rules an admin set. See [How agent identity works](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Channel manager A member of your Claude organization whom an Owner has named to set up specific channels. For each channel assigned to them, a channel manager sets the default model, adds repositories their own GitHub account is an admin of, and manages credentials and plugins in the channel's own bundle, without holding the Owner role. See [Delegate channel setup to channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers). ## Channel memory Facts Claude retains while working in a channel, including facts you told it to remember and notes it writes itself. Entries from public channels are shared across the workspace; entries from private channels are saved to that channel's own store. See [What Claude Tag remembers](/docs/claude-tag/users/memory). ## The earlier Claude in Slack Claude Tag is the second generation of the Claude app in Slack: | | Legacy (the earlier Claude in Slack) | New (Claude Tag) | | :------------- | :------------------------------------------ | :---------------------------------------------------- | | Identity | Each user links their own claude.ai account | One agent identity with org-level service credentials | | Sessions | Spawned per request | One persistent session per thread, shared | | Memory | None | Shared workspace memory plus private-channel memory | | Proactive work | None | Routines and channel watching | Your admin chooses which generation answers `@Claude` in a given channel, so two channels in the same workspace can work differently. See [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/workspaces#set-the-version-for-a-scope). ## Connection A credential for one external service that Claude uses on the channel's behalf, like a Datadog API key or a GitHub App installation. Connections belong to the agent identity, not to any user, and are grouped into [Access bundles](#access-bundle) by an admin. A connection is not a connector. A connector belongs to your personal claude.ai account. A channel session uses the channel's connections. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use your connectors there for your own tasks, after you allow it. A DM uses your own account instead, as [how DMs work in this model](/docs/claude-tag/concepts/agent-identity#direct-message-channels) describes. ## Connector A tool you add to your own claude.ai account, like Gmail, Google Drive, or a custom MCP server, listed under [Customize > Connectors](https://claude.ai/customize/connectors). Connectors are personal. In Slack they apply in DMs. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use them in a channel for your own tasks, after you allow it. For the agent-side equivalent that works in channels, see [Connection](#connection). ## Environment The sandboxed compute configuration a session runs in, including its network access setting. Environments used here must be scoped to the organization, not to an individual account, because channel sessions run with no user account attached. ## Plugin A bundle of skills an Owner attaches to an Access bundle or scope, teaching Claude how to use a specific tool or follow a specific process. Anthropic provides plugins for common tools; you can add your own. See [Attach plugins](/docs/claude-tag/admins/add-connections#attach-plugins). ## Routine A scheduled or run-once task Claude runs on its own, such as a daily digest or a channel watch. Anyone in a channel can ask Claude to set one up, list what's scheduled, or disable one. Routines run with the channel's connections, not the creator's. Claude Code also has a feature named routines. Those run under an individual user's account; Claude Tag routines run under the agent identity. ## Rule The match conditions Agent Proxy checks against each outbound request. A connection pairs one credential with the rule that decides when to inject it, and a request that matches the rule gets the credential attached at the boundary. A request that nothing allows (no rule, no domain entry, no [environment](#environment) network access setting) is blocked. See [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy). ## Scope One of three levels Claude's settings can target: Default Slack access (the organization-wide root), one Slack workspace, or one channel (public or private). Scopes inherit downward, so a channel gets its workspace's settings plus any of its own. An Owner attaches [Access bundles](#access-bundle) and instructions at a scope. See [Attach the bundle to a scope](/docs/claude-tag/admins/attach-to-scope). ## Session The unit of work behind one conversation. Each Slack thread binds to one persistent session, and anyone in the channel can continue it by replying in the thread. A channel where Claude works at the top level, outside threads, also carries one session for the channel itself, separate from every thread's. See [How Claude Tag works](/docs/claude-tag/concepts/how-it-works) and [Restart a stuck or wrong-context session](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session). ## Related resources * [How Claude Tag works](/docs/claude-tag/concepts/how-it-works): the scope, channel, and thread model in action * [How agent identity works](/docs/claude-tag/concepts/agent-identity): how connection, scope, and Agent Proxy fit together when Claude runs a task * [Set up Claude Tag](/docs/claude-tag/admins/setup-overview): where bundles, scopes, and connections get created in the console # How Claude Tag works Source: https://claude.com/docs/claude-tag/concepts/how-it-works Each Claude Tag thread in Slack runs a working session in a sandbox. See how progress shows in the thread, how to steer mid-task, what survives between turns, and how memory is scoped. Claude Tag is Claude, working inside your team's Slack channels. An organization Owner gives it its own accounts to the tools your team uses, so it arrives already able to act, and anyone in a channel can tag it into a problem without setting anything up. When someone tags Claude in at a channel's top level, the channel's own [session](/docs/claude-tag/concepts/glossary#session) picks the message up. A task that needs investigation, tools, or a longer exchange gets a working session in a thread under the message, and that thread binds to its own session from then on. Claude works through the task and posts the result back into the conversation. The work runs in an ephemeral cloud sandbox, not on your local machine. This page covers: * [Walk through a session](#walk-through-a-claude-tag-session): an annotated example thread showing one task end to end * [Starting a session](#start-a-session), [tracking progress](#track-claude%E2%80%99s-progress), and [steering mid-thread](#reply-in-the-thread-to-steer): what to type, what to watch, and who can redirect * [Team channels and personal DMs](#team-channels-and-personal-dms): which surface to use, and how access differs between them * [Key concepts](#key-concepts): agent identity, scheduling, and memory defined * [Lifecycle of a request](#lifecycle-of-a-request): the five-step loop, [the checklist](#how-the-checklist-updates), [per-channel access](#channel-access), and [scheduled tasks](#one-off-and-scheduled-tasks) * [Session context and memory](#session-context-and-memory): what Claude reads, what survives idle, and what carries across channels ## Walk through a Claude Tag session The thread below is one task end to end in Slack: Jordan tags @Claude into `#launch-week` with a question, a colleague steers mid-thread, and the answer lands in the channel.
# launch-week 19 members
J
Jordan9:02 AM

@Claude where are we on launch prep? Pull together what's still open from this channel.

ClaudeAPP9:02 AM

On it. I'll go through this channel's open threads and the launch plan.

Done: Read 14 open threads Done: Cross-checked the launch plan in Drive Done: Listed who each item is waiting on Done: Drafted the status summary
S
Sam9:06 AM

fold in the vendor quotes from last week's thread too

ClaudeAPP9:08 AM

Done. Full status below: eight items closed, three open. The venue contract is the oldest, waiting on legal since the 2nd.

Each of the five moments in that thread shows a piece of how Claude Tag works: 1. **Jordan handed Claude a problem, not a prompt.** Typing `@Claude` in a message that asks for something is what starts a working session. 2. **Claude acknowledged, then went quiet.** The "is thinking…" line and the checklist are the progress surface; the silence between 9:02 and 9:06 was the work happening. [How the checklist updates](#how-the-checklist-updates) 3. **Sam steered Claude without `@`-mentioning it again.** Once a session is active in a thread, it belongs to everyone there. [Reply in the thread to steer](#reply-in-the-thread-to-steer) 4. **The work ran somewhere real, with the channel's tools.** Reading fourteen threads happened in a sandbox built for this thread, and the launch plan came through this channel's Drive connection. What a session can reach is set per channel. [Channel access](#channel-access) 5. **The result is in the thread.** The whole channel can see it, use it, and build on it. [What survives between replies](#what-survives-between-replies) The rest of this page takes each piece apart. ### Start a session To start a session, type `@Claude` in a Slack message and say what you need in that same message (a question to answer, a task to run, a problem to dig into). Jordan's "`@Claude` where are we on launch prep?" is the whole move. Anyone in the channel can do it. ### Track Claude's progress Once your message sends, an "is thinking…" line at the bottom of the thread means Claude picked it up. What happens next depends on the size of the ask. Questions and one-off requests get a direct reply. A longer task, like Jordan's, gets a checklist instead. [How the checklist updates](#how-the-checklist-updates) covers how it works and how to read one while it runs. While a session runs, check in by replying in the same thread. Asking "how's it going?" in the thread is enough; it reads new replies as it works. ### Reply in the thread to steer Anyone in the channel can steer a running session by replying in its thread, not just the person who started it. That is what Sam did in the walkthrough. Without re-mentioning `@Claude` or starting over, he replied in Jordan's thread, and the session folded his instruction into work already in progress. Add context, redirect the approach, or pick up the result later; a colleague's thread is yours to continue. Editing or deleting an earlier message doesn't steer the session the way a reply does: * **Editing a message**: Claude receives a note each time you edit, showing what the message said before the edit and what it says now. Both versions become part of the session's transcript, so editing a message doesn't remove the earlier text from what Anthropic stores. An edit doesn't start a new task or re-address Claude, even if you add `@Claude` to it. * **Deleting a reply**: Claude gets no notification and keeps the version it already read. Deleting the reply in Slack doesn't remove it from the session's transcript. * **Deleting the thread's first message**: if the thread already has replies, Claude keeps working and the session stays open. If you delete it before anyone has replied, the session closes. Anything Claude already pushed or posted persists, per [what survives between replies](#what-survives-between-replies), and you start a new thread to pick the task back up. Closing the session archives it rather than deleting it, so its transcript, including the message you deleted, stays with the channel's Claude data until that data is [deleted](/docs/claude-tag/admins/workspaces#revoke-a-pairing). * **Correcting course**: Claude responds to replies; edits reach it only as notes, and a deleted reply not at all. Say the change in a new reply; the reply is also how you walk back a message it already read. ## Team channels and personal DMs Where you message Claude determines whose tools and accounts it uses. In a channel, it acts with the connections an organization admin set for that channel, and the work is attributed to its own accounts. In a DM, the same engine runs with your own claude.ai connectors, and the work is attributed to you, except pull requests, which the Claude GitHub App authors from DMs as well. | Working in… | Access | Attribution | Best for | | :---------- | :----------------------------------------- | :----------------------- | :--------------------------------- | | A channel | The channel's connections, set by an admin | The agent's own accounts | Shared work the team should see | | A DM | Your own claude.ai connectors | You | Personal tasks using your own data | The Access column is about external systems. A channel session reaches what the channel was granted, and a DM session reaches what your own account is connected to. Everything below describes channel sessions, where most of the model lives. For the DM side, see [direct message channels](/docs/claude-tag/concepts/agent-identity#direct-message-channels), and for choosing between the two, see [pick the right surface](/docs/claude-tag/users/good-habits#pick-the-right-surface). ## How Claude Tag differs from Cowork and Claude Code Anthropic offers several ways to work with Claude on real tasks; they reach the same kinds of systems but through different mechanisms. | | Claude Tag | Cowork | Claude Code | | :---------------- | :---------------------------------------------------------------- | :------------------------------------ | :------------------------------------------- | | Where | Slack channels | claude.ai chat | Your terminal or IDE | | Whose access | The team's: service-account credentials an admin sets per channel | Yours: your personal OAuth connectors | Yours: your local credentials and filesystem | | Who sees the work | Everyone in the channel | Just you | Just you | | Best for | Shared work the team should see and steer | Personal research and drafting | Hands-on coding in your own checkout | The short version: **team work → Claude Tag; personal work → Cowork or Claude Code.** Claude Tag's connections authenticate the agent itself with service accounts, not any person. Personal connectors apply in a Claude Tag DM, which runs on your own claude.ai account, the same way Cowork does. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use your personal connectors in a channel for your own tasks, after you allow it. ## Key concepts Three ideas recur across this page and the rest of these docs. * **Agent identity**: in channels, Claude acts under its own service accounts that an admin provisions, not as the person who asked. What it can reach is set per channel, so everyone in a channel works with the same access. See [How agent identity works](/docs/claude-tag/concepts/agent-identity). * **Scheduling and long-running work**: a task can run on a schedule, follow a pull request and act when it changes, or keep going across many turns in one thread. The same channel access applies whether a person or a schedule started it. See [Set up routines](/docs/claude-tag/users/proactivity). * **Memory**: what Claude learns in public channels is saved as workspace memory that any channel can use; private channels keep their own. See [What Claude remembers](/docs/claude-tag/users/memory). ## Lifecycle of a request Every session, in any channel, follows the same five-step loop. 1. **The session starts.** Someone tags `@Claude` with a task that needs a working session, or a [scheduled routine](/docs/claude-tag/users/proactivity) runs. At a channel's top level, the channel's own session picks the message up and starts the thread's session. 2. **A sandbox builds.** Each thread gets its own isolated working environment. 3. **The working loop runs.** Claude works through the task with the channel's access, editing its checklist in place. 4. **The result lands in the thread.** An answer, a doc, a chart, or a pull request. 5. **A quiet period follows.** The sandbox is released while the thread persists; a new reply rebuilds it and starts the loop again. Flow diagram of one session in five numbered steps. Step 1, tag Claude in with an @Claude message carrying a task. Steps 2 and 3 happen inside the sandbox. Step 2, a sandbox builds, one per thread; step 3, the working loop runs through the task's steps using the channel's access. Step 4, Claude posts the result in the thread as an answer, a doc, a chart, or a pull request. Step 5, a dashed quiet period follows, where the sandbox is released while the thread persists. A dashed return arrow from the quiet period back up into the sandbox shows that a new reply rebuilds it and the loop continues. Flow diagram of one session in five numbered steps. Step 1, tag Claude in with an @Claude message carrying a task. Steps 2 and 3 happen inside the sandbox. Step 2, a sandbox builds, one per thread; step 3, the working loop runs through the task's steps using the channel's access. Step 4, Claude posts the result in the thread as an answer, a doc, a chart, or a pull request. Step 5, a dashed quiet period follows, where the sandbox is released while the thread persists. A dashed return arrow from the quiet period back up into the sandbox shows that a new reply rebuilds it and the loop continues. Steps 1 and 2 are [starting a session](#start-a-session): a message tags Claude in, and a sandbox builds for that thread. Step 3, the working loop, is [the checklist](#how-the-checklist-updates) below. Steps 4 and 5, the result and the quiet period that follows, are covered in [What survives between replies](#what-survives-between-replies). Every session runs in an ephemeral sandbox, a real working environment where Claude can read documents, run code, build charts, and open pull requests. Claude clones your GitHub repositories into the sandbox, edits them there, and pushes changes back to GitHub as a branch or pull request. The sandbox runs the same engine that powers Claude Code on the web, Anthropic's agent for writing and running code, which is why the results are working artifacts rather than chat. Two threads in the same channel are two separate sessions with separate sandboxes; sessions don't share state directly. A channel where Claude works at the top level, outside threads, also carries one session for the channel itself, separate from every thread's. That session reads the channel's top-level messages and handles top-level @-mentions, so context carries across separate top-level asks in the same channel; [What survives between replies](#what-survives-between-replies) covers how long it lives. For a task that needs investigation, tools, or a longer exchange, it starts a dedicated session in a thread under the message. At the channel's top level, [`!restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) replaces the channel's session. Even with nothing connected, every session starts from the same baseline. * It reads its own thread and the channel's history, including pinned items * It searches the workspace's content * It writes and runs code inside the sandbox, which is how a chart comes out of a posted CSV, or a doc out of a long thread, with nothing wired up ### What Claude posts back Claude posts each session's result in the thread you asked in, choosing the form that fits the work. | Form | What it is | When you see it | | :------------------ | :------------------------------------------------------ | :--------------------------------- | | A reply | An answer, list, or summary as a Slack message | Questions and short results | | A file or chart | Attached to the thread the way anyone shares a file | Data, images, generated documents | | A page kept current | Any of the above, edited in place over time | Digests, indexes, standing reports | | A hosted page | A web page published on claude.ai, linked in the thread | Dashboards, prototypes, reports | A hosted page stays available after the session ends, and Claude updates it when you ask in the thread. Anyone with access to the channel can open it; [artifact visibility](/docs/claude-tag/concepts/security-and-data#artifact-visibility) covers the access model. These are the same artifacts [Claude Code publishes](https://code.claude.com/docs/en/artifacts), with channel-based access in place of owner-controlled sharing. For code work, the result is usually a draft pull request opened under the Claude GitHub App, with the link posted in the thread. ### How the checklist updates For a longer task, Claude's first reply is a checklist, a live task list that it edits in place as it goes. Slack does not send notifications when a message is edited, so the thread can look frozen while the list is still moving. A quiet thread usually means Claude is mid-task, not stuck. Open the thread. Checklist items checked off since you last looked mean the work is moving. In the walkthrough, nothing new arrived in anyone's notifications between 9:02 and 9:06, while the checklist ticked through fourteen threads of reading. If the work hits a wall, Claude usually says so in a reply rather than going silent. When a thread stays silent well past what the task should need, treat it as a stuck session; see [Claude reacted or started thinking, then never replied](/docs/claude-tag/users/troubleshooting#claude-reacted-or-started-thinking-then-never-replied). ### Channel access Connections extend a session's reach into your own systems. An organization admin attaches access to a scope (the organization, a workspace, or a single channel), so the same request can do more in one channel than in another, and everyone in a given channel works with the same capability. A thread locks in its skills, plugins, and custom instructions when it starts, and a running thread keeps that set. Connections and domain rules are enforced on each request, so one an admin adds mid-thread works in a running thread. Claude doesn't announce a new connection in an existing thread; ask it to use the service by name. A new thread picks up every kind of change, so after a configuration change, start a new top-level thread. #### How to identify access Because access is set per channel rather than per person, the way to find out what a session can reach is to ask it, not to guess from your own permissions. * **Ask what Claude can reach.** In any channel, `@Claude what can you access from this channel?` lists its current reach. * **If Claude cannot reach something, the channel was not granted access.** Another channel may have the access, and an organization Owner can add it. [How agent identity works](/docs/claude-tag/concepts/agent-identity) covers the model. * **Personal connectors are separate from channel connections.** A connection an admin attaches to a channel is separate from a connector on your personal claude.ai account. Your own connectors work in your DMs. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use them in a channel for your own tasks, after you allow it. ### One-off and scheduled tasks A session starts the same way whether a person triggers it or a schedule does. A tagged task runs in its thread's session, and the sandbox is released once the work finishes. A routine runs the same loop on a schedule, a channel watch, or a repository event, with the channel's connections, so a recurring digest or watcher gets the same access a typed request would. See [set up routines](/docs/claude-tag/users/proactivity). ## Session context and memory Every session runs the same lifecycle; what varies by place and thread is [what it can see](#conversation-context), [what survives idle](#what-survives-between-replies), and [what it remembers](#channel-and-workspace-memory). ### Conversation context A session reads its own thread and its channel. Mentioning `@Claude` partway into an existing thread gives it a window of the thread's messages, not the whole thread, with other bots' replies filtered out. In long threads, restate anything critical. Claude works in channels it has been added to, but workspace search can still find messages by keyword from public channels it's not a member of (the same search any Slack user has). Workspace search is unavailable in [channels that include guests](/docs/claude-tag/admins/restrict-access#restrict-guest-channels). Finding something is broader than being able to act somewhere; to have it participate in a channel directly, invite it with `/invite @Claude`. ### What survives between replies A thread is durable, but the sandbox behind it is not. Durable means the thread stays in Slack, and everything Claude read and said in it is kept in the session's transcript on Anthropic's side, so the session can pick up where it left off whenever someone replies. Deleting messages or the thread in Slack doesn't remove them from that transcript. The sandbox is the computer where Claude runs commands and keeps working files for a task. A few minutes after a session finishes its turn, its sandbox is released, and the same session resumes in a fresh one when the next message arrives. A thread's session keeps resuming this way for as long as people use the thread. Claude replaces it with a new session in two cases. | When | What Claude does | | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | | Someone sends [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) | Archives the session right away and starts a fresh one that rereads the thread | | The session [gets stuck and fails](/docs/claude-tag/users/troubleshooting#claude-reacted-or-started-thinking-then-never-replied) | Starts the replacement when the next message arrives in the thread | Timeline with two lanes. The Slack thread lane is one continuous bar that persists from the moment a task starts. The sandbox lane below it is segmented, built when the task starts, released while the thread goes quiet, and rebuilt fresh when someone replies. Timeline with two lanes. The Slack thread lane is one continuous bar that persists from the moment a task starts. The sandbox lane below it is segmented, built when the task starts, released while the thread goes quiet, and rebuilt fresh when someone replies. | | Survives idle periods | | :------------------------------------- | :---------------------------------- | | The conversation and its context | Yes | | Channel memory | Yes | | Work pushed, posted, or opened as a PR | Yes, in the external system | | Files that exist only in the sandbox | No. Claude recreates them if asked. | For long tasks, ask it to push branches and post drafts as it goes, so deliverables are saved somewhere durable while the work is still running. See [Good habits](/docs/claude-tag/users/good-habits#give-every-task-a-definition-of-done). A running thread isn't told about configuration changes an admin makes after it started, such as a new connection, plugin, skill, repository grant, or custom instruction. A new thread starts from the scope's current configuration, so after changing a scope, start a fresh thread to see the change. The channel's own session, the one that handles top-level messages outside any thread, lives longer than a thread's. Claude replaces it with a fresh one when a top-level message arrives after about an hour with no top-level activity, when the session is about a day old, or when the channel's configuration has changed since the session started. Channel memory and the channel's history are unaffected, so the only visible effect is that Claude no longer carries what the previous session had been working on. Claude also stops reading a channel's top-level messages once about 100 of them have arrived since it last posted or replied there. An `@Claude` mention in the channel starts it reading again; see [When Claude stops reading a channel](/docs/claude-tag/users/when-claude-responds#when-claude-stops-reading-a-channel). These thresholds are defaults and can change, so treat the numbers as approximate. ### Channel and workspace memory Memory follows places the same way access does, and it accumulates for the team rather than for any individual. Memory from public channels is shared across the workspace, so a decision recorded while working in #launch-week is available when someone asks in #gtm-west. When Claude cites something from a channel you have never used it in, it is reading workspace memory shared from that channel, not a profile of you. Private channels read workspace memory while working, and what they save is written to that channel's own store rather than the workspace store. To see what it holds, ask `@Claude what do you remember about this channel?`. Anyone in the channel can correct or remove entries. [What Claude Tag remembers](/docs/claude-tag/users/memory) covers reading, correcting, and adding to memory. The whole model so far fits in one picture, with access set at the scope, memory shared from public channels, work in progress per thread, and DMs outside all of it. Diagram showing three nested levels. A scope container holds two channels, #platform-eng and #gtm-west, and each channel holds its own threads, like 'fix checkout latency' or 'pull deal state'. The private channel is marked with a lock. Callouts mark what lives at each level (identity and access at the scope; memory, shared from public channels across the workspace while private channels keep their own; and work in progress at the thread). A DM with Claude sits below, outside every scope, and runs on your own account. Diagram showing three nested levels. A scope container holds two channels, #platform-eng and #gtm-west, and each channel holds its own threads, like 'fix checkout latency' or 'pull deal state'. The private channel is marked with a lock. Callouts mark what lives at each level (identity and access at the scope; memory, shared from public channels across the workspace while private channels keep their own; and work in progress at the thread). A DM with Claude sits below, outside every scope, and runs on your own account. DMs are outside this picture; they run on your own account, as covered in [Team channels and personal DMs](#team-channels-and-personal-dms) above. Owners can disable DMs organization-wide; see [Allow or disable direct messages](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages). ## Related resources * [Getting started](/docs/claude-tag/users/getting-started): hand Claude your first task * [How agent identity works](/docs/claude-tag/concepts/agent-identity): why an admin sets access per channel, and how credentials stay out of the sandbox * [Good habits](/docs/claude-tag/users/good-habits): write tasks that survive the sandbox lifecycle # Personal connectors in channels Source: https://claude.com/docs/claude-tag/concepts/personal-connectors Claude can use your own claude.ai connectors, called personal connectors, for your tasks in a Slack channel. See how you approve connector use, when Claude asks you to review a result before posting it, and what other people in the channel can reach. Personal connectors are the tools you add to your own claude.ai account, like your calendar or your email. When a task you ask for in a Slack channel needs one of your own tools, Claude can offer to use your connector for it. Connector use in channels is available to a limited number of organizations. If Claude never offers to use your connectors in a channel, connector use in channels may not be available to your organization, and the channel works with admin-attached connections as described in [how agent identity works](/docs/claude-tag/concepts/agent-identity). ## Where your connectors apply In a channel, an admin decides the shared access. The channel uses the connections an admin attached to it, and everyone who asks there gets the same access. In organizations where connector use in channels is available, Claude can also use the connectors on your own claude.ai account in that channel. When you ask Claude there for something that needs one of your own tools, it can use your connector for your task. In a direct message (DM), your connectors apply on their own, because a DM runs on [your own claude.ai account](/docs/claude-tag/concepts/agent-identity#direct-message-channels). [Routines](/docs/claude-tag/users/proactivity) and other work Claude starts on its own in a channel use the channel's connections, never your connectors. Claude uses your connectors only while working on a request you made yourself. Your connectors serve only you. When someone else in the channel asks Claude for something, their request doesn't control or use your connectors, even in a shared channel. Claude works with your permissions, reaches only what your account can reach, and records what it does under your name. To add or remove connectors on your account, open the **Customize > Connectors** page on claude.ai; see [connectors on claude.ai](/docs/connectors/overview) for setup. ## Control connector use ### Approve connector use By design, Claude asks before it starts using your connectors in a channel. The first time a task calls for one of your connectors, Claude shows you a prompt in the thread that only you can see, with three choices: * **Allow** starts the work in auto mode. Claude uses your connectors as the task needs them and checks with you before posting anything that looks sensitive. * **Allow with review** starts the work and shows you every result to approve before it posts to the channel. * **Don't allow** declines this request, and Claude doesn't use your connectors. A later request can prompt you again. To save **Allow** or **Allow with review** for future tasks in every channel, select the **Use this choice for future requests** checkbox on the prompt before you choose. Once you've saved a choice, Claude starts a task you @-mention it for without showing the prompt. To change a saved answer, open the Claude app in Slack and select its **Home** tab. The **Home** tab offers **Auto mode**, **Ask every time**, and **Allow with review**. **Ask every time** is the setting before you save a choice. ### Review results before posting Claude can hold a result and show it to you before anything posts to the channel. When you chose **Allow with review**, Claude holds every result. When you chose **Allow**, Claude holds a result when the content looks sensitive and posts the rest directly. Once you approve a held result, Claude posts it in the thread where you asked. On the Enterprise plan, an Owner can set the review rule for a scope with the **Delegated task results** setting, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag) → **Claude Tag's access** → **Slack** → the scope → **Advanced** → **Delegated task results**. **Require review** removes **Allow** from the prompt and **Auto mode** from the **Home** tab, so Claude holds every result for your review. **Share without review** removes **Allow with review** from both. ### Stop connector use To stop a task that's using your connectors, select **Stop** under the message in the task's thread where Claude says it's going to use your connectors. Only you can see the **Stop** button. ## What other people in the channel see Results stay visible in the channel. What Claude posts back to a channel thread is readable by everyone there, like any other work Claude does in a channel. Claude's detailed work on a task you approved lives in a session only you can open. The work runs with your permissions and is recorded under your name. Other people can't use your connectors. Requests other people make to Claude in your task's thread run with the channel's own access, not with yours. While Claude works on your connector task, it is designed to take direction from you and to treat what other people post in the thread as information for the task rather than as instructions. ## Related resources * [How agent identity works](/docs/claude-tag/concepts/agent-identity): whose identity and access Claude uses in channels and DMs * [Connectors](/docs/connectors/overview): set up and manage connectors on your claude.ai account * [Get started](/docs/claude-tag/users/getting-started): hand Claude your first task in a channel # Security and data handling Source: https://claude.com/docs/claude-tag/concepts/security-and-data How Claude Tag keeps credentials out of the sandbox, limits where a channel session's requests can go, and controls who can see artifacts and invoke Claude. In channels, Claude acts under its own service accounts that an Owner provisions. By default it can read and post in Slack channels it's been added to and search public channels by keyword; it has no access to your external systems until an Owner adds connections. Each connection is scoped to specific channels and workspaces, and the actions Claude takes in connected tools are attributable to its own service accounts. Every channel request, whether a person typed it or a schedule triggered it, follows the same path: it runs in an isolated sandbox that holds no credentials. In an Anthropic-hosted environment, requests leave that sandbox only through Agent Proxy and reach your systems under the agent's own accounts. Sessions in a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) run on runners inside your network, and Claude can't use Access bundles in those sessions yet. DMs run on the user's own claude.ai account instead and are covered separately on [How agent identity works](/docs/claude-tag/concepts/agent-identity#direct-message-channels). ## How a request travels Each Slack thread runs in its own sandbox. In an Anthropic-hosted environment, every outbound call from that sandbox passes through the same checkpoints. Diagram showing the request path across three zones, labeled your Slack workspace, Anthropic's infrastructure, and your systems. A task mentioned in the Slack workspace runs in a session sandbox in the middle zone, one sandbox per thread, holding no credentials. Outbound requests pass to Agent Proxy, which injects the credential drawn from the credential store; a request that no rule, domain entry, or environment network access setting allows is blocked. Credentialed requests reach your systems, like GitHub, a data warehouse, monitoring, or any HTTP API. A dashed return path shows results posting back in the thread, as Claude. Diagram showing the request path across three zones, labeled your Slack workspace, Anthropic's infrastructure, and your systems. A task mentioned in the Slack workspace runs in a session sandbox in the middle zone, one sandbox per thread, holding no credentials. Outbound requests pass to Agent Proxy, which injects the credential drawn from the credential store; a request that no rule, domain entry, or environment network access setting allows is blocked. Credentialed requests reach your systems, like GitHub, a data warehouse, monitoring, or any HTTP API. A dashed return path shows results posting back in the thread, as Claude. | Checkpoint | The guarantee | | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The sandbox | Holds no credentials | | Agent Proxy | Injects credentials from the credential store at request time, and blocks a request that no [connection](/docs/claude-tag/admins/add-connections#set-allowed-websites), [**Domains** entry](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential), or [environment network access level](/docs/claude-tag/admins/add-connections#broad-web-access-through-the-environment) allows | | Your systems | See the agent's own accounts, so its actions there are attributable | ### Compute and the sandbox Sessions run in ephemeral sandboxes, the same infrastructure that runs [Claude Code on the web](https://code.claude.com/docs/en/web-quickstart). Each Slack thread gets its own sandbox. When a thread goes quiet, its sandbox is released; replying in the thread builds a fresh one. What persists across that release and rebuild: * **Persists:** The thread, its visible work, and anything pushed to a branch, opened as a pull request, or posted into Slack. * **Does not persist:** Files that existed only inside the sandbox. To keep generated files, ask Claude to push them to a branch or post them in the thread. Claude Tag retains channel memory and session transcripts. Because of that retention, Claude Tag isn't available to organizations with Zero Data Retention (ZDR) enabled. Claude Tag also isn't available to organizations with a customer-managed encryption (CMEK) policy. ### Credential storage Credentials you provision are kept in a separate credential store, not in the proxy itself. When an outbound request matches a rule, [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy), the network layer between the sandbox and any external host, retrieves the credential from that store and injects it at the boundary, so the model and the sandbox are not given the key. This means: * **A saved credential is not displayed again.** The setup screens are write-only. * **The credential travels only to the hosts you named** when you added the connection. * **You can narrow the credential further**, to one host, one path prefix, or read-only methods, in [Add connections](/docs/claude-tag/admins/add-connections). ### Network egress In an Anthropic-hosted environment, outbound traffic from a channel session's sandbox is default-deny. Requests go only to hosts an allow layer covers, and the layers are a [connection's Allowed websites](/docs/claude-tag/admins/connections/custom#fill-out-the-custom-tool-form), the [bundle's Domains tab](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential), and the network access setting of the [environment](/docs/claude-tag/concepts/glossary#environment) the scope's sessions run on. A new environment's default level, Trusted access, already covers a [documented set of package registries and developer hosts](https://code.claude.com/docs/en/cloud-environments#default-allowed-domains). See [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) for what happens to a request under each layer. Flow diagram across two zones, labeled Anthropic's infrastructure and your systems. In the first zone, a session sandbox that holds no credentials sends every outbound request to Agent Proxy, which matches it against admin rules. Three outcomes branch toward your systems: on a rule match, the credential is attached at the boundary and the request proceeds; on an allowlist-only match, from the bundle's Domains list or the environment's network access setting, the request is sent without credentials; on no match, the request is blocked entirely (the default-deny outcome) and the host is unreachable. Flow diagram across two zones, labeled Anthropic's infrastructure and your systems. In the first zone, a session sandbox that holds no credentials sends every outbound request to Agent Proxy, which matches it against admin rules. Three outcomes branch toward your systems: on a rule match, the credential is attached at the boundary and the request proceeds; on an allowlist-only match, from the bundle's Domains list or the environment's network access setting, the request is sent without credentials; on no match, the request is blocked entirely (the default-deny outcome) and the host is unreachable. Because requests to any other host are blocked, data can only leave the sandbox to hosts an allow layer covers. An admin sets the Allowed websites list on each connection and the Domains tab on each bundle. An admin sets the environment's network access level, which defaults to Trusted access, from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings). See [Set allowed websites](/docs/claude-tag/admins/add-connections#set-allowed-websites) and [Allow a host without a credential](/docs/claude-tag/admins/add-connections#allow-a-host-without-a-credential). Organizations can opt in to allow-all egress, where a `*` entry on a bundle's Domains tab admits requests to any host on the ports that entry lists, still without credentials. Private and internal network addresses and cloud metadata endpoints remain blocked. Allow-all egress is off by default and enabled per organization by Anthropic; see [Allow all hosts](/docs/claude-tag/admins/add-connections#allow-all-hosts). ### Service accounts In channels, Claude acts under service credentials of its own, not under the account of the person who tagged it. The Slack surface is the Claude app, code work goes through the Claude GitHub App, and every other connected tool uses a service account an Owner provisions in an Access bundle. See [How agent identity works](/docs/claude-tag/concepts/agent-identity) for the full model. A connection belongs to that agent identity and is shared by everyone the bundle's scope covers. Anyone in a channel under that scope can ask Claude to act with the credential, so whatever the connected account can read or write is available to every member of those channels. Connect a dedicated identity you control for each service, such as a `claude@yourcompany.example.com` seat or a native service account, rather than a personal login. A dedicated account keeps the agent's actions separately auditable in each tool's logs and lets you revoke its access without affecting a person; see [Create a dedicated account per service](/docs/claude-tag/admins/add-connections#create-a-dedicated-account-per-service). DMs with `@Claude` run on the user's own claude.ai account instead, with that user's personal connectors, and work there is attributed to them, except pull requests, which the Claude GitHub App authors from DMs as well. Owners can disable DMs organization-wide; see [Allow or disable direct messages](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages). Personal connectors in channels is available to a limited number of organizations. Where it is available, Claude uses a user's personal connectors in a channel only for that user's own tasks, after the user allows it. The work runs with that user's permissions and is recorded under their name. Requests other people make to Claude in the task's thread run with the channel's own access, not with that user's connectors. Claude is designed to take direction from the connector's owner, treating what other people post in the thread as information for the task rather than as instructions, and the owner can tell Claude in the task's thread to stop. See [Personal connectors in channels](/docs/claude-tag/concepts/personal-connectors). ### Isolate credentials between channels A channel session can use only the [Access bundles](/docs/claude-tag/admins/add-connections) attached in one of three places: * **The channel itself.** A bundle you attach here applies in that channel only. * **The channel's workspace.** A bundle you attach here applies in every channel of that workspace. * **[Default Slack access](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit).** The organization-wide root; a bundle you attach here applies in every channel of every paired workspace. A bundle attached anywhere else in your organization is invisible to the session, and no request from the session's sandbox can carry a credential from a bundle outside those three scopes. For example, if you attach a bundle holding finance credentials to one private channel, sessions in every other channel run as if that credential doesn't exist. If you attach the same bundle to a workspace or to Default Slack access instead, every channel beneath it gets that access, so isolation comes from where you attach the bundle, not from the bundle itself. Confine a credential to one channel in three steps: 1. Attach its bundle to that channel and nowhere broader. 2. Keep the channel private. A bundle on a public channel [grants its access to anyone who joins](/docs/claude-tag/admins/attach-to-scope#attach-to-a-channel). 3. Check the channel's **Connectors**, **Repositories**, and **Plugins** sections on the [Slack tab in admin settings](/docs/claude-tag/admins/attach-to-scope). They list the access the channel gets, including rows inherited from the workspace or from Default Slack access, each with an origin line naming where it comes from. Claude [doesn't operate in externally shared channels](/docs/claude-tag/admins/restrict-access#externally-shared-channels), so a channel shared with another company never has a session to isolate. Isolating a credential doesn't isolate what Claude knows. What it learns in a public channel becomes [workspace memory](/docs/claude-tag/users/memory) that sessions in the workspace's other channels can read, and it can [search public channels by keyword](/docs/claude-tag/admins/restrict-access#controls-that-aren%E2%80%99t-available) without being added to them, the same way any workspace member can. ## Artifact visibility A session can publish an artifact, a web page hosted on claude.ai with the link posted in the thread, and the page stays available after the sandbox is released. Anyone with access to the source Slack channel can open it, which in a public channel covers everyone in the workspace. Someone who opens the link without that access sees a request-access prompt rather than the page. There is no share setting for anyone to change. Updates go through Claude: ask in the Slack thread, or [send Claude a comment on the page](/docs/claude-tag/users/use-cases/create-artifacts#comment-on-the-page-to-ask-for-changes), which anyone who can post in the channel can do. Artifacts you publish from your own Claude Code sessions work differently: they belong to you, and you control who can open them, with sharing options that depend on your plan and organization settings. See the [Claude Code artifacts documentation](https://code.claude.com/docs/en/artifacts). ## Member access By default, anyone in a connected Slack workspace can invoke Claude in channels, with or without a Claude account. An Owner can turn on a restriction toggle to narrow that: on Team plans it limits Claude to people with a Claude account in your organization, and on Enterprise plans it limits Claude to members whose role grants the **Claude Tag in Slack** capability. See [Restrict who can use Claude](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude). The toggle governs DMs as well as channels. ## Related resources * [How agent identity works](/docs/claude-tag/concepts/agent-identity): the identity model in full, including DM attribution * [Data lifecycle and deletion](/docs/claude-tag/concepts/data-lifecycle): what Anthropic stores, how long it's kept, and what each action deletes * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): the controls that exist and the ones that don't * [Audit Claude Tag activity](/docs/claude-tag/admins/audit): the trails for tracing what it did # Claude Tag settings map Source: https://claude.com/docs/claude-tag/concepts/settings-map Claude Tag settings map: the admin page for access and behavior, the usage page for spend limits, the in-Slack Configure link for channel instructions, and personal connectors for DMs and your own tasks in channels. Claude Managed Agents is configured separately on the Claude Platform. Claude Tag's settings live on claude.ai, split across a few pages that each own a different kind of setting. Which page you need depends on what you're changing. The table maps each surface to what it controls. | Surface | Who changes it | What it controls | | :--------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Claude Tag admin page](https://claude.ai/admin-settings/claude-tag) | An Owner in your Claude organization | Access, behavior, and restrictions for channels, per [scope](/docs/claude-tag/concepts/glossary#scope) | | [Usage page](https://claude.ai/admin-settings/usage/claude-tag) | An admin | Spend limits and each channel's spend against them | | [Analytics page](https://claude.ai/analytics/claude-tag) | Anyone who can view the Analytics dashboard | Spend trends, projections, and per-channel reports; read-only | | The **Configure** link in the footer of any Claude reply in a channel | Channel members (unless an admin restricts editing) and [channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for their assigned channels | One channel's instructions and whether Claude replies there without an @-mention. Channel managers also set the channel's default model, repositories, connections, and plugins | | [Customize > Connectors](https://claude.ai/customize/connectors) on your own claude.ai account | You | Which of your personal tools apply in [DMs](/docs/claude-tag/concepts/agent-identity#direct-message-channels) and, where available, for [your own tasks in a channel](/docs/claude-tag/concepts/personal-connectors) | Channel memory and routines aren't in the table because you change them by talking to Claude in the channel; see [what anyone can change from the channel](/docs/claude-tag/admins/customize#change-behavior-from-the-channel). Owners can review both, as each scope's memory files and scheduled work, from [the Audit page](/docs/claude-tag/admins/audit), labeled **Activity** in the console. ## The Claude Tag admin page Everything an Owner configures for channels lives at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag). Settings there apply per scope (a channel, a workspace, or the whole organization). A scope without its own setting inherits from its parent, and a channel's setting overrides its workspace's, so two channels can run with different connections, models, and instructions. Most controls are Owner-only; the [permissions table](/docs/claude-tag/admins/restrict-access#permissions-by-role) lists each action and who can take it. * **Access bundles**: the connections, domain entries, repository grants, and plugins Claude uses in the channels a bundle covers. See [Give Claude access](/docs/claude-tag/admins/add-connections). * **Custom instructions**: standing guidance Claude reads in every session on a scope. See [Add custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions). * **Default model**: the model new sessions in a scope start on. The picker shows the models your organization allows for Claude Code, leaving out any that Claude Tag doesn't support, so it can be missing models you see in Claude Code itself. See [Choose the model for a scope](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope). * **Auto mode allow rules**: plain sentences that pre-approve actions Claude's permission checker would otherwise flag or stop in a scope's sessions. See [Auto mode allow rules](/docs/claude-tag/admins/customize#auto-mode-allow-rules). * **Workspace pairing and restrictions**: which Slack workspaces are paired, whether DMs are allowed, guest-channel behavior, who can invoke Claude, and which generation of the app answers in each scope (on the Team plan, a single [**Enable Claude Tag** switch](/docs/claude-tag/admins/workspaces#turn-claude-tag-on-or-off-on-the-team-plan) replaces the per-scope setting). See [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access). * **Channel name rules**: channel-name patterns that keep Claude out of matching channels or join it automatically to new public ones. See [Block or auto-join channels by name](/docs/claude-tag/admins/restrict-access#block-or-auto-join-channels-by-name). ## Spend limits and usage Spend limits live at [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag), a different page than the Claude Tag admin page. It holds the organization-wide spend limit, the default spend limit for channels, per-channel limits, and each channel's spend against its limit. If your organization bills through a reseller, this page is not available. See [Set a spend limit](/docs/claude-tag/admins/set-spend-limit) for funding the usage balance and what users see when a limit is reached. Usage covered by a promotional credit isn't counted on the usage page and shows as \$0.00 there. To see each channel's list-price spend for the current month including covered usage, use the **List price** column of the **Spend by channel** table at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag). Spend trends live at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag), the Claude Tag section of the Analytics dashboard. It shows total and projected spend, spend by channel, and [spend by kind of work](/docs/claude-tag/admins/set-spend-limit#see-spend-by-kind-of-work) for the period you pick, and anyone with permission to view the Analytics dashboard can open it. It has no controls; see [Usage analytics](/docs/claude-tag/admins/restrict-access#usage-analytics). ## The Configure page Every Claude reply in a channel ends with a footer, and its **Configure** link opens a claude.ai page for that channel; replies in DMs have no Configure link. You can also send [`@Claude !configure`](/docs/claude-tag/users/commands#get-the-link-to-configure-a-channel) in the channel, and Claude replies with a link to the same page. Anyone in the channel who is also a member of your Claude organization can edit the **Channel instructions** field on that page, unless an admin has [restricted editing to admins](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions). The page's **Respond automatically** toggle controls whether Claude replies in the channel without an @-mention; see [Turn automatic replies on or off](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off). The page's **Tools and access** tab shows the channel's resolved connections and any allowed domains. Members can see those lists but not change them there. The same tab's **Plugins** card lists the channel's plugins, and members can add plugins there unless an admin has restricted editing to admins. A **Routines** tab lists the channel's routines with each one's schedule, status, and last run. The Configure page and the **Custom instructions** field on the scope's panel in admin settings write the same instructions, so a change from either place is visible in the other. See [Configure Claude for a channel](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). On the Enterprise plan, an Owner can name [channel managers](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for a channel. For them, the same page adds editable cards: the channel's default model on the **General** tab, and its repositories and access bundles on the **Tools and access** tab. ## Personal connectors on claude.ai Connectors you add to your own claude.ai account, under **Customize > Connectors**, apply in DMs with Claude, because [a DM runs on your own account](/docs/claude-tag/concepts/agent-identity#direct-message-channels). A channel session uses the connections an admin attached to it. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use your personal connectors there for your own tasks, after you allow it. Slack has no connector settings of its own. See [connectors on claude.ai](/docs/connectors/overview) for setting one up, and [the troubleshooting entry](/docs/claude-tag/users/troubleshooting#a-connector-works-on-claude-ai-but-not-in-slack) if a connector you use on claude.ai is missing in Slack. ## Claude Tag versus Claude Managed Agents [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) is a separate product for developers, a pre-built agent harness that runs in managed infrastructure. You configure it on the Claude Platform through the Managed Agents API, and access requires a Claude API key. An agent there is defined by its model, system prompt, tools, MCP servers, and skills. Environments choose where its sessions run (a cloud sandbox, or a self-hosted sandbox on your own infrastructure), and scheduled deployments run it on a cron schedule. The two products don't share settings. Nothing on the Claude Tag admin page configures a Managed Agent, and an agent defined on the Claude Platform doesn't change how Claude behaves in Slack. ## Related resources * [Customize Claude Tag](/docs/claude-tag/admins/customize): the layers that shape Claude's behavior in a channel and who sets each one * [How agent identity works](/docs/claude-tag/concepts/agent-identity): why channels and DMs use different access * [Set up Claude Tag](/docs/claude-tag/admins/setup-overview): where each setting is first created during setup # Work with Claude Tag Source: https://claude.com/docs/claude-tag/overview Claude Tag puts Claude in your Slack channels with admin-governed access. See what to hand it, how setup works, and where to start as an admin or end user.
Public Beta

Tag @Claude in. Get results back in the thread.

Anyone in a channel can tag Claude into a problem and hand it work: reproduce a bug and open a pull request, turn a decision thread into a doc, assemble the state of a project. It posts a checklist in the thread as it goes, and the whole exchange stays visible to the channel.

# platform-eng 38 members
D
Dana2:14 PM

checkout has felt slow all morning — anyone else seeing it?

L
Leo2:15 PM

same. @Claude can you investigate? Compare latency against this morning's deploy and find what's causing it.

ClaudeAPP2:15 PM

On it. I'll compare latency before and after the deploy, track down the cause, and report back here.

Done: Pulled p99 latency from Datadog Done: Diffed deploy 4f2c1 against main Done: Reproduced the slow query locally In progress: Opening a pull request with the fix…
## Plans that include Claude Tag Claude Tag is available on Team and Enterprise plans, on Anthropic's first-party service. It isn't available on individual plans (Free, Pro, or Max), or for third-party deployments. To use it, your organization pairs its Slack workspace with its Claude organization; see [the setup overview](/docs/claude-tag/admins/setup-overview) for the full prerequisites. If you're choosing between Claude products for Slack-shaped work, [how Claude Tag differs from Cowork and Claude Code](/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code) compares them directly: team work in shared channels is Claude Tag; personal work on your own files is Cowork or Claude Code. ## Where Claude Tag runs Claude Tag works in Slack. You interact with it by writing in a Slack channel, thread, or direct message, and it replies there. Mention `@Claude` in a channel to guarantee it picks the message up. When Claude works on a task, it runs in an ephemeral sandbox, not on your computer. The sandbox is created when a conversation starts, holds any code or files Claude is working with, and is discarded when the conversation goes idle. See [how Claude Tag works](/docs/claude-tag/concepts/how-it-works) for the full lifecycle. You extend what Claude can reach, like your repositories, ticketing systems, data warehouses, and custom tools, through [connections](/docs/claude-tag/admins/add-connections), [plugins, and skills](/docs/claude-tag/admins/customize). An Owner configures these per scope (a channel, a workspace, or the whole organization), separately from any connectors an individual user has set up in their own claude.ai account.
## Billing and spend limits Adding Claude to Slack doesn't add a per-seat charge. Channel and thread work is billed by usage instead: it draws from a **usage balance**, an amount in your organization's billing currency that an Owner funds. A [spend limit](/docs/claude-tag/admins/set-spend-limit) caps how much of that balance Claude Tag can use each billing period. Direct messages don't draw from this balance. A DM runs on the sender's own claude.ai account and follows that seat's usual usage limits, so the organization spend limit doesn't apply to it. To learn what your team's usage costs, run a pilot with a spend limit set and watch the per-channel breakdown on the [usage page in your admin settings](https://claude.ai/admin-settings/usage/claude-tag). Your organization may already have a [launch usage credit](https://support.claude.com/en/articles/15575654-claude-tag-launch-promo-for-claude-team-and-enterprise) to run that pilot against before it funds the balance itself. The usage page doesn't count usage that a credit covers, so that usage shows as \$0.00 there. While the credit covers your pilot, watch the **List price** column of the **Spend by channel** table at [`claude.ai/analytics/claude-tag`](https://claude.ai/analytics/claude-tag) instead. That column shows each channel's list-price spend for the current month, including covered usage. [Set a spend limit](/docs/claude-tag/admins/set-spend-limit) covers how to fund the balance on each plan, set the limit, and what happens when usage reaches it.
For end users
## Put Claude Tag to work If Claude Tag is in your channel, you can use it now. (If it isn't there yet, an Owner in your Claude organization runs setup: see [Set up Claude Tag](/docs/claude-tag/admins/setup-overview).) Anyone in the channel can hand it work, and channel work bills to the organization, not to you. What it can reach depends on the channel you're in, not on who you are. The fastest way to find out is to ask it: `@Claude what can you access from this channel?` Or, if you're signed in to your Claude organization, click **Configure** in the footer of a Claude reply in the channel to see its [connections](/docs/claude-tag/concepts/glossary#connection), the external services an admin has connected for that channel. Replies in org-shared channels have no Configure link. The one exception is a DM, where it runs on your own claude.ai account instead of the channel's setup. Owners can disable DMs organization-wide; see [Allow or disable direct messages](/docs/claude-tag/admins/restrict-access#allow-or-disable-direct-messages). ### Common uses The list below covers common ways teams use Claude Tag. Each link opens a guide with the prompts to paste and the connections the task needs. * [Watch monitors and alerts](/docs/claude-tag/users/use-cases/watch-monitors): scheduled dashboard checks, and alerts investigated as they arrive. Needs a monitoring connection like Datadog, Sentry, or PagerDuty. * [Triage requests](/docs/claude-tag/users/use-cases/triage-requests): an intake channel where Claude answers what it can, flags duplicates, and routes the rest. Works on Slack content alone. * [Find answers in your docs](/docs/claude-tag/users/use-cases/find-answers): policy and runbook questions answered with the source. Needs a docs connection like Google Drive, Notion, or Confluence. * [Answer data questions](/docs/claude-tag/users/use-cases/answer-data-questions): a plain-language question becomes a warehouse query and a chart. Needs a data warehouse connection. * [Track projects and chase approvals](/docs/claude-tag/users/use-cases/track-projects): standing status digests and follow-ups that run until an approval lands * [Turn threads into docs and tickets](/docs/claude-tag/users/use-cases/create-artifacts): a settled discussion becomes the decision doc, the customer reply, or the filed tickets * [Fix bugs](/docs/claude-tag/users/use-cases/fix-bugs): a bug reported in the channel comes back as a draft pull request. Needs GitHub. * [Work from your own channel](/docs/claude-tag/users/use-cases/your-own-channel): scratch questions, digests of channels you don't follow, and follow-ups on what you said you'd do [Get started](/docs/claude-tag/users/getting-started) covers your first message, what you see while Claude works, and how to shape Claude's behavior in your channel.
For administrators
## Set Claude Tag up once for everyone You set up Claude Tag once, at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), and you must be an Owner in your Claude organization to do it. The setup page at that URL walks you through it: * **Pair your Slack workspace**: send `@Claude connect` in Slack to get a pairing code, then enter it on the setup page. * **Connect the services Claude will work in**: for each one, such as your issue tracker or data warehouse, create an account for Claude and enter its credential. * **Grant repositories**: choose which repositories the Claude GitHub App can reach. * **Set a monthly spend limit and launch**. Claude Tag starts with no access to your external systems. The services you connect during setup form an [Access bundle](/docs/claude-tag/concepts/glossary#access-bundle), the set of tools Claude can reach, attached to the workspace or channels you paired. Once you launch, everyone in a channel Claude is in can use Claude Tag immediately, with no per-user setup. [Set up Claude Tag](/docs/claude-tag/admins/setup-overview) walks through those steps with what to have ready, what each choice means, and how to verify Claude Tag works once you launch.

Security review

Security and data handling

The security model, what admins can and can't restrict, audit trails, and network requirements.

## Where to start with Claude Tag Admins: pair your Slack workspace, connect the services Claude will work in, and launch It's already in your channel: send your first message The session model, what it can read, and how memory follows places Prompts to paste, by team and connection # Commands Claude Tag understands Source: https://claude.com/docs/claude-tag/users/commands A few exact, bang-prefixed words after an @-mention run a fixed action instead of starting a normal turn: see the command list, get the link to a channel's settings page, restart a stuck or wrong-context session, check whether Claude is still working in a thread or channel, mute or unmute a thread, send feedback, list a channel's routines, and fork a thread's conversation into a new thread, here or in another channel. A command is `@Claude` followed immediately by one of a few exact words starting with `!`. Claude matches the message against that word and runs a fixed action instead of starting a normal turn. `!help`, `!configure`, `!restart`, `!status`, `!mute`, and `!unmute` must stand alone: adding extra words, as in `!restart` with words tacked on, makes the message an ordinary prompt instead. `!feedback`, `!routines`, and `!fork` accept text after the command, covered below. ## See the commands available to you ```text wrap theme={null} @Claude !help ``` Claude replies with the commands it understands in your workspace. The list can differ by workspace, since a command can be enabled for some workspaces and not others. ## Get the link to configure a channel ```text wrap theme={null} @Claude !configure ``` Run `!configure` in a channel, and Claude replies in the thread with a link to that channel's Configure page on claude.ai. On that page you [tailor how Claude works in the channel](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel), for example by editing its channel instructions, and it's the same page the **Configure** link in the footer of any Claude reply opens. In a DM with Claude there are no per-channel settings, so Claude replies there with a link to the [Claude Tag admin page](https://claude.ai/admin-settings/claude-tag) instead. ## Restart a stuck or wrong-context session ```text wrap theme={null} @Claude !restart ``` Use this when a session is stuck, or when it's carrying context you don't want the next reply to build on. Claude archives the current session and starts a fresh one in its place. Every thread Claude takes part in runs a session of its own, holding that one conversation. Some channels have one more session on top of the per-thread ones. That session belongs to the channel itself, and it's the session Claude works from at the channel's top level, outside any thread. When Claude [replies to a top-level message no one mentioned it in](/docs/claude-tag/users/when-claude-responds), the channel's session is the one replying. Where you run `!restart` picks which session gets replaced: * **In a thread**, `!restart` replaces that thread's session. The fresh session rereads the thread, so it keeps what's in the messages and drops everything else the old one was carrying. * **At a channel's top level**, `!restart` replaces the channel's session. The fresh session picks up from where the old one left off. Claude confirms once the replacement session is ready. If the restart can't complete, Claude tells you and you can run `!restart` again. You need the same access to run `!restart` that you'd need to message the session directly; someone who can only observe a thread can't restart it. ## Check whether Claude is still working ```text wrap theme={null} @Claude !status ``` Use this when Claude has gone quiet and you want to know whether it's still on the task before you follow up or [restart the session](#restart-a-stuck-or-wrong-context-session). Claude answers with a short note only you can see, and never posts that answer for others in the conversation. Checking doesn't interrupt work in progress or count as a new request. The note doesn't quote the conversation or say what Claude is working on. The note opens with a heading that says whether it covers this thread, this channel, or this DM, then gives Claude's status there: ```text wrap theme={null} Claude in this thread I'm still working in this thread (started 6m ago). • Muted: no (mute with `!mute`) ``` ## Mute or unmute a thread ```text wrap theme={null} @Claude !mute ``` Run `!mute` in a thread Claude is part of, and Claude stops replying there. Muting is per thread by design. Other threads, the channel's top level, [routine](/docs/claude-tag/users/proactivity) posts, and service notices are unaffected. There's no channel-level mute. If you run `!mute` at a channel's top level, Claude posts this hint: ```text wrap theme={null} :mute: Muting works per thread — reply `@Claude !mute` (or `!unmute`) inside the thread you mean. ``` To quiet unprompted replies across a whole channel, turn the channel's [**Respond automatically** setting](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off) off. Unmute the same way: ```text wrap theme={null} @Claude !unmute ``` A muted thread also unmutes when you @-mention Claude there with a request, so you don't need `!unmute` before asking something new. Checking on Claude with [`!status`](#check-whether-claude-is-still-working) leaves the thread muted. You need the same access to mute or unmute a thread that you'd need to message Claude there. ### Thumbs-down reactions and muting When someone reacts 👎 to one of Claude's replies in a thread, Claude mutes that thread and stops posting there. If Claude's [working session](/docs/claude-tag/concepts/how-it-works) in that thread is partway through writing another reply, Claude abandons that unfinished reply. Claude then posts this notice in the thread: ```text wrap theme={null} :mute: Claude is muted in this thread and won't post here again. `@Claude !unmute` (or any @-mention) brings it back; `@Claude !mute` mutes it again anytime. ``` To bring Claude back, send `@Claude !unmute` in the thread, or @-mention Claude there with your next request. A 👎 reaction doesn't tell Claude what was wrong with the answer. To get a corrected answer, @-mention Claude in the thread and say what was wrong. The mention also unmutes the thread. ## Send feedback ```text wrap theme={null} @Claude !feedback ``` Opens a form in Slack for sending feedback on Claude Tag to the team that builds it, along with a note on what the report includes. Add words after `!feedback` and Claude carries them into the form as a starting draft, which you can still edit before submitting: ```text wrap theme={null} @Claude !feedback the channel summary skipped the pinned thread ``` ## List the routines in a channel ```text wrap theme={null} @Claude !routines ``` Claude replies in the thread with the [routines](/docs/claude-tag/users/proactivity) set up in the channel: the scheduled jobs, watched channels, and other standing work it runs there. The list covers only that channel's routines. * **For the current channel**, run `!routines` in that channel. * **For another channel**, add the channel mention or its ID, as in `@Claude !routines #other-channel`. You need to be a member of that channel, and it must belong to your organization. Claude sends the list in a reply only you can see, so that channel's routines aren't posted for everyone in the channel where you asked. If the single word after `!routines` isn't a channel mention or ID, Claude replies with how to use the command. Adding two or more words makes the message an ordinary prompt that starts a normal turn instead. ## Fork a thread ```text wrap theme={null} @Claude !fork @Claude !fork #channel ``` Run `!fork` from inside a thread Claude is part of, and Claude continues that conversation in a new thread. Leave the channel out to start the new thread in the same channel, or name a channel to continue the conversation there. Use it when a discussion outgrows its thread: a bug report that turns out to belong in the owning team's channel, a request that another team should pick up, or a side question that deserves its own thread. The fork starts a new thread in Slack and links the two threads together: * **In the new thread's channel**, Claude posts a new top-level message that links back to the original thread and carries your prompt, then continues in the replies under it. The new conversation starts with the original thread as background, so nobody has to re-explain. * **Back in the original thread**, Claude replies with a link to the new thread, so anyone following along can see where the conversation continued. The prompt is required, and it kicks off the new thread: Claude starts working on it there right away. To fork into another channel, pick it from Slack's `#` autocomplete so it arrives as a channel mention. The channel must be public, and both you and Claude must be members of it; invite Claude with `/invite @Claude` first if it isn't there yet. On Enterprise Grid, a public channel in another workspace of your grid also works when that workspace is paired to the same Claude organization, but a channel shared across workspaces doesn't. `!fork` works from threads in public channels only. Threads in private channels, DMs, and group DMs can't be forked, since forking would carry the conversation to a different audience. If the fork can't be set up, Claude replies with a note only you can see, and nothing is posted in either channel. ## Related resources * [Set up routines](/docs/claude-tag/users/proactivity): the standing work `!routines` lists, and how to create, edit, or disable it * [Control when Claude Tag responds](/docs/claude-tag/users/when-claude-responds): what makes Claude reply without any command or mention at all * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): the admin controls that decide who can message Claude at all, including its commands # Get started Source: https://claude.com/docs/claude-tag/users/getting-started Claude Tag works in your Slack channels. See how to check it's on, send your first message, what it can read, and why DMs work differently. Claude Tag is Claude working in your Slack workspace. You hand it work by writing a message where Claude is, and Claude carries it out in that thread. An `@Claude` mention guarantees a response in a channel, but it isn't required everywhere. DMs and threads Claude is already in reach it without one. There's nothing for you to install or configure; if `@Claude` is in your channel, you can use it (unless your admin has [restricted who can invoke Claude](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude)). ## When to tag Claude in a channel versus a DM Where you tag Claude decides whose tools it uses and who sees the result. * **Channel** for shared team work. The work happens in the open, so anything Claude does in the thread, including its checklist and results, is visible to everyone in the channel, and anyone can reply to steer the work. An admin sets what Claude can reach in each channel, and everyone who asks there gets the same access. By default you don't need a Claude account to tag Claude in a channel; the work bills to the organization. An admin can [restrict who can invoke Claude](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude). * Example: `@Claude where are we on the launch checklist? Pull what's still open from this channel and #design-review.` * **DM** for personal tasks. A DM runs on your own claude.ai account with [your own connectors](/docs/connectors/overview). Every DM message reaches Claude without an @-mention. You can also DM Claude questions about getting started, like how to word a task or what to try first. DMs are one-to-one only; group DMs aren't supported. * Example: `Pull my afternoon meetings from my calendar and draft a one-line prep note for each.` See [team channels and personal DMs](/docs/claude-tag/concepts/how-it-works#team-channels-and-personal-dms) for the full comparison. If your workspace previously used the earlier Claude in Slack app, see [how Claude Tag differs](/docs/claude-tag/admins/migrate-from-earlier) for what has changed. ## Add Claude to a channel Claude only works in channels it's been added to. To add it, run: ```text wrap theme={null} /invite @Claude ``` Run the command in the channel's message box. Slack rejects `/invite` sent from inside a thread. Or mention `@Claude` in a message; Slack will prompt you to add it. If Slack says "You don't have permission to invite people to this channel", the channel or workspace limits who can add people. In Slack, open **Channel details** → **Agents & apps** (called **Integrations** in some Slack versions), select **Add**, and pick **Claude**. Or ask someone who can add people to the channel to add Claude. ## Check that Claude is working Mention `@Claude` in any channel where it's been added. In the Slack message box, send: ```text wrap theme={null} @Claude what can you access from this channel? ``` A reply means it's running there, and the answer tells you what it can reach. ### What you see when Claude first joins a channel When a person first invites Claude to a channel, it posts a short intro on its own: it reads the channel's history and suggests a few tasks it could pick up. The intro doesn't post when a bot adds Claude, in org-shared channels, or in channels that already have memory. The footer under each reply names the model that handled it. You can [choose a different model](/docs/claude-tag/users/models) yourself, and admins [set the default model for each channel](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope). In a channel, the footer also has a **Configure** link; open it to [tailor how Claude works in this channel](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). Replies in DMs and in org-shared channels have no Configure link. | If you see | It means | Do this | | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Typing `@Claude` doesn't show **Claude** with an **APP** badge in the suggestion list | The Claude app isn't installed in your workspace | Ask your Slack admin to install the Claude app, and send them [the installation guide](/docs/claude-tag/admins/setup-overview#pair-your-slack-workspace) | | The mention sends but Claude doesn't reply | Setup isn't finished for this channel | Ask your Claude organization admin to enable Claude Tag for this channel, and send them [the setup guide](/docs/claude-tag/admins/setup-overview) with the channel name | | Claude replies "I couldn't find a Claude Code environment for your account" | Claude couldn't resolve an environment for this DM; DMs run on your account rather than the organization's | Mention Claude again. If it keeps happening, see [I get an environment error in a DM](/docs/claude-tag/users/troubleshooting#i-get-an-environment-error-in-a-dm) | ## Hand Claude a task Every interaction has the same shape. You mention `@Claude` with a task, Claude works on it in the thread, and Claude posts the result there. ```text wrap theme={null} @Claude learn what you can about my role from this workspace, then tell me three tasks you could take off my plate this week. ``` An "is thinking…" line appears at the bottom of the thread when Claude picks the task up, and it replies with results; a multi-step task also gets a checklist it updates as it works. A quiet thread after the "is thinking…" line means Claude is working, not stuck; long tasks can take a minute or more before the first reply. Once Claude is in a thread, you don't need to @-mention it again; it reads every reply in that thread. Read Claude's work before you use it, in proportion to what's at stake. A summary you can skim; something going to a customer or changing a system gets a careful read. If a result needs checking, ask it to show its work in the same thread. Tasks run in the cloud, so Claude keeps working after you close Slack. Replies in the thread reach Claude without re-mentioning. If the thread looks idle, Claude is usually still working; see [how to read its progress](/docs/claude-tag/concepts/how-it-works#track-claude%E2%80%99s-progress). ## What Claude can see After you've handed Claude a task, the first question is what it has to work with. The short version: it reads the thread you tagged it in, it can search your workspace's public channels, and anything beyond Slack depends on what your admin connected. | What you give Claude | Can Claude read it? | | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Messages in this thread | Yes. Mentioning it mid-thread also gives it the thread's earlier messages | | A file you attach (image, screenshot, PDF, or another type) | Yes, up to a size limit that depends on the file type. See [Files you attach](#files-you-attach) | | Other public channels in your workspace | By searching only, the same way a person searches Slack; Claude can find a message by keyword but can't read a channel's full history unless it's been added there | | Private channels and DMs | Only from inside them. Adding Claude to a private channel lets it work there, but the channel stays unreadable from any other channel or DM. | | A link you paste, like a Google Doc or a webpage | Only if your admin allowed that site for this channel. If not, Claude tells you it can't reach it. For files in your personal Drive or Google account, DM Claude instead; [a DM uses your own connectors](/docs/claude-tag/concepts/agent-identity#direct-message-channels) | | A Slack canvas | No | | A message you edited after sending | Yes. Each edit sends Claude a note showing the text before and after the edit. An edit never starts a new task on its own, so to be sure a correction is picked up, say it in a new reply. Deleting a reply doesn't notify Claude, and deleting the thread's first message before anyone replies closes the session; see [Reply in the thread to steer](/docs/claude-tag/concepts/how-it-works#reply-in-the-thread-to-steer) | The fastest way to find out for your channel is to ask: `@Claude can you read the doc I just linked?` gets you a yes or a "that site isn't allowed here." ### Files you attach Claude reads images and PDFs directly. It puts any other file type in its working files and opens it from there when the task needs it. Claude accepts files within these limits. * **Images**: up to about 3.75 MB each * **PDFs**: up to 5 MB each * **Other files** (spreadsheets, code, archives, documents): up to 100 MB each * **Number of files**: up to 5 per message. Claude ignores any beyond the fifth. Claude can't read an image or PDF over its limit and answers from the rest of your message. To hand Claude a larger image or PDF, resize the image, split the PDF, or paste the text. Slack doesn't expose personal account settings (your sidebar, notification preferences, channel membership, or DMs between you and other people) to apps. If you want help organizing channels, paste or screenshot the list and Claude can propose a scheme you apply yourself. ### Which messages Claude reads * An @-mention guarantees a response. Claude may also respond to a message that doesn't mention it when it judges a reply is warranted; include the mention to guarantee one. It receives the thread's root message and earlier replies for context when you mention it mid-thread; for details on the window, refer to [what Claude sees when you mention it](/docs/claude-tag/concepts/how-it-works#conversation-context). * Once mentioned in a thread, Claude follows the rest of that thread and may reply without another mention. * While working on a task, Claude can search the workspace's public channels by keyword, the same way a person searches Slack. It can't read a channel's full history unless it's been added there. To quiet Claude in a thread or remove it from a channel, see [Control when Claude Tag responds](/docs/claude-tag/users/when-claude-responds). ## Give Claude standing instructions Set instructions for a channel by telling Claude there, the way you'd ask anyone on the team: ```text wrap theme={null} @Claude remember for this channel: keep replies short, and always include a link to the source. ``` The instruction saves to channel memory and applies to everyone's threads. Public-channel memory is also [shared across your workspace](/docs/claude-tag/users/memory). Verify with "what do you remember about this channel?" ## Related resources * [Use case library](/docs/claude-tag/users/use-cases): every shape of work, each with the prompts to paste * [Good habits](/docs/claude-tag/users/good-habits): how to write tasks that finish * [Set up routines](/docs/claude-tag/users/proactivity): once a task works, have Claude run it on its own schedule * [Commands](/docs/claude-tag/users/commands): exact words starting with `!` that run a fixed action, like `!restart` for a stuck session * [Personal connectors in channels](/docs/claude-tag/concepts/personal-connectors): how Claude can use your own claude.ai connectors for a task you hand it in a channel # Good habits for working with Claude Tag Source: https://claude.com/docs/claude-tag/users/good-habits Name the outcome, give every task a definition of done, and pick the right channel. See how to write tasks Claude can finish and how to keep many threads reviewable. Tasks should have a verifiable end state. Claude runs each one in its own thread, and a thread closes when someone can confirm the work is done. A task without that end state produces an open-ended report, and the thread stays open while you decide what to do with it. The habits here are for anyone who tags Claude in from Slack. ## Work in the open Claude is most useful when the work is somewhere the team can see, steer, and build on. A few mindsets make that the default rather than something you remember to do. * **Work in public.** Assume everyone in the channel can read the thread, including its checklist and results. Anything your team writes down, like decisions, conventions, and postmortems, is context Claude can use. Knowledge that lives in DMs or was only said aloud is invisible to it. Put anything personal in a DM instead. * **Share control.** Replying in a thread someone else started is how work moves. Redirect the approach, add what the requester didn't know, or pick up the result and run with it. * **Grant broad access.** A channel with more connections (the tools an admin linked for this channel, like GitHub or Drive) produces more useful results, because Claude can join more sources together. The connections are scoped to the agent's identity, so granting them to a channel does not expose anyone's personal data. * **Give Claude the destination, not the route.** State the outcome you want and let Claude work out the steps; the [definition of done](#give-every-task-a-definition-of-done) below makes that concrete. * **Tolerate the mess.** A first draft posted in the thread is more useful than a polished one in a DM. The thread is the workspace, not the deliverable. ### Mentioning people who aren't in the channel Claude can't add anyone to a channel, and it doesn't decide whether a mentioned person is notified. Slack's prompt to invite or notify someone who isn't in the channel appears only for messages you type yourself; it never applies to messages Claude posts. Slack delivers Claude's mention the way it delivers any app-posted message. In a public channel, the person is notified in their Activity view even though they haven't joined. In a private channel, they aren't notified and can't see the message until someone invites them. If you want someone to follow a thread Claude is working in, invite them yourself. ## Write tasks that close The phrasing of a task determines whether it has a verifiable end state, what form the result takes, and how Claude responds while working on it. ### Name the outcome, not the activity A task like "post the project status and tag me when it's up" has an end state Claude can verify; "look at this" does not, and invites an open-ended report. Put the verifiable outcome in the first sentence of the task. ### How much detail to give Claude [reads the thread you tag it in, can search the workspace's public channels, and works with the channel's connections](/docs/claude-tag/users/getting-started#what-claude-can-see). If the background for your task is already in a thread, channel, or connected tool, link to it and state the outcome you want in one sentence. You don't need to restate the background. ```text wrap theme={null} @Claude take over the bug in the thread linked above. Fix it and open a draft PR. ``` When a mistake would be costly to undo, give Claude more detail. Write the detail as constraints: name the rules the change must respect, the checks that count as verification, and what the work must not touch. ```text wrap theme={null} @Claude migrate the export config to the new schema. Hard rules: no behavior change, don't touch the billing module, and every old config key keeps working as an alias. Done means the full test suite passes, not only the export tests. ``` Constraints in a task steer Claude but don't restrict Claude from performing a specific action. Anything you type to Claude goes into its working context, where it can be forgotten or overridden. If there are actions Claude must not take, enforce them outside the conversation, with controls like repository permissions, branch protection rules, and required checks. ### Give every task a definition of done Starting a thread costs one sentence. Closing it costs your attention, because you read the output, decide whether it's right, and reply. Without a stated end condition, Claude can't declare the thread finished and you can't stop checking it. The end condition you write determines who can close the thread, and the table matches each kind of condition to who closes it. | End condition | Who closes it | Example | | :----------------------------- | :----------------- | :---------------------------------------------------- | | An objective check passes | Claude, on its own | "Done when CI is green" | | You approve a prepared result | You, one click | "Draft the status memo and post it here for approval" | | You choose between options | You, one word | "Research approaches A and B and recommend one" | | No verifiable condition exists | No one | Reframe it as a question instead of a task | Two refinements make the table work in practice: * **The condition must be observable by Claude.** "Done when CI is green" requires access to CI. If the proof lives in a system the channel isn't connected to, change the condition to one you close yourself. * **Spell out everything the condition includes.** "Babysit this PR until it merges" can produce a merge the moment approvals arrive, before open review comments are addressed. If the full condition is approvals present, comments resolved, and your final go-ahead, write all three into the task. For tasks Claude closes itself, ask it to attach proof, such as the source link, the chart, the test output, or the diff. You read the proof, not the transcript. For long-running work, make getting the deliverable somewhere durable part of the definition. Post the file to the thread, push the branch, or open the draft pull request as it goes. See [what survives between replies](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies). Calibrate over time. Check everything it produces in a new channel at first, and widen what it closes on its own as its output holds up under review. ### Say which decisions come back to you Tell Claude which decisions it can make on its own and which ones it must bring to you before acting. If you don't, Claude judges each case itself. It may make a change you wanted to see first, or stop to ask so often that it spends most of the task waiting for your replies. ```text wrap theme={null} @Claude update the retry logic the way this thread decided. Handle test failures and lint yourself. Come back to me before changing any public interface, and for anything you're not sure is in scope. ``` These instructions steer Claude but don't restrict Claude from deciding on its own. A decision that must come back to you needs an enforced control too, such as branch protection for merges. Once you've seen and verified Claude's output over several tasks, you can let it make more decisions without checking in, the same way you widen [what it closes on its own](#give-every-task-a-definition-of-done). ### Specify the output format for anything recurring A monitor or digest that posts on a schedule posts to the channel repeatedly, so spell out the shape you want each post to take. Say how long each item should be, give it the status legend to use, and tell it what to leave out, so the channel can read every post at a glance. ```text wrap theme={null} @Claude every 6 hours, check #alerts and post one line per item: 🔴 needs a person, 🟡 watch, 🟢 fine. Skip 🟢 unless something changed. ``` Once a post matches the format you want, you can also point at it directly: "use the format from your 9am post going forward." ### Steer Claude Tag explicitly Claude adapts to instructions, but it won't guess that you want it to. Tell it how to behave in this channel and ask it to remember. That works in both directions, whether you want more structure or less noise: ```text wrap theme={null} @Claude remember for this channel: always format reports as a table, and ask before posting anything longer than a screen. ``` ```text wrap theme={null} @Claude remember for this channel: keep replies to three sentences unless someone asks for detail. ``` Verify what stuck by asking what it remembers about the channel. See [What Claude Tag remembers](/docs/claude-tag/users/memory). ## Work in the right place Where you start a thread determines what Claude can reach, who else can pick the work up, and which standing conventions apply. ### Start a new thread for a new task Each thread runs its own session, and the session carries the whole conversation into every reply. Keep follow-ups on the same task in the same thread, where Claude already has the context. Start a new thread for each new task. The fresh session begins with full room for the work, picks up any configuration changes made since the old thread began, and keeps each piece of work reviewable on its own. A thread that accumulates many tasks eventually [grows past what one session can hold](/docs/claude-tag/users/troubleshooting#this-conversation-is-too-long-for-me-to-process). ### Pick the right surface Channel access belongs to the channel, and DM access belongs to you. A channel can also be yours alone. Create one with just you and Claude in it, and it works the same way a team channel does. The table compares the three surfaces. | | A team channel | Your own channel | A DM | | :---------------- | :----------------------------------------- | :---------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | | Access | The channel's connections, set by an admin | The channel's connections, set by an admin | Your own claude.ai connectors | | Memory | Channel memory the team builds | Channel memory you build | Outside channel and workspace memory | | Who sees the work | Everyone in the channel | You, plus anyone you invite | You | | Billing | The organization | The organization | Your seat | | Best for | Shared work the team should see and steer | Your own questions, digests, and follow-ups, kept where a teammate can pick them up | Personal tasks on your own connections, or data that shouldn't run through a shared channel connection | [Routines](/docs/claude-tag/users/proactivity) belong to a channel too. You set standing work up in the channel where it should post, and it runs with that channel's connections. [Work from your own channel](/docs/claude-tag/users/use-cases/your-own-channel) shows what a channel of your own is good for. A DM can still answer questions about a public channel when the answer should stay private. Name the channel in the DM, as in `summarize the last week of #product-feedback`. Claude's Slack search covers public channels in this workspace from a DM the same as from a channel, so the DM advantage is privacy of the answer, not broader reach. Workspace search is unavailable in [channels that include guests](/docs/claude-tag/admins/restrict-access#restrict-guest-channels), so ask from a DM or from a channel without guests. Reading a public channel's full history, rather than what search finds, needs Claude to be a member of that channel. If it says it can't read a public channel, `/invite @Claude` from inside that channel adds it. A private channel is readable only from inside it. Inviting Claude lets it work in that channel, but Claude can't read the private channel's messages from any other channel or DM. To ask about a private channel, ask in that channel. Channels in a different workspace and Slack Connect channels stay out of reach. When more than one surface would work, prefer a channel. Work that happens there compounds, because Claude can draw on it in later threads and teammates can find it, redirect it, or build on it. If Claude says it can't reach something in a channel, the channel likely wasn't granted that access. See [How agent identity works](/docs/claude-tag/concepts/agent-identity). ### Teach Claude something that sticks When Claude gets something wrong, or learns something worth keeping, where you put the fix decides who else benefits and whether you can do it yourself. | You want Claude to know | Put it in | Who can write it | Reaches | | :---------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | | How this channel should behave: format, tone, when to respond | [**Channel memory**](/docs/claude-tag/users/memory) (say it and ask Claude to remember) | Anyone in the channel | This channel (or workspace, from a public channel) | | Conventions and setup for one repository: file layout, PR labels, dependencies to install | **`CLAUDE.md`** at the repo root ([loaded when the repo is](/docs/claude-tag/admins/configure-github#what-loads-from-a-repository)) | Anyone with repo write | Any session that works in that repo, from any channel | | Standing rules for this channel that outrank memory | The [**Configure** page](#configure-claude-for-a-channel), in the **Channel instructions** field | Channel members, unless an admin has [restricted it](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) | This channel | | How to use a tool correctly, or follow a specific process, org-wide | [**A skill**](/docs/claude-tag/admins/skills-repo) in your org's plugin marketplace | An organization Owner adds it; anyone can ask Claude to open a PR proposing the change | Every channel under the scope it's attached to | | Standing rules across many channels | [**Custom instructions**](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions) on a workspace or organization scope | An organization Owner, in the console | Every session in that scope | The first three are yours to write. Skills and wider-scope custom instructions are attached by an Owner, but you can still ask Claude to draft a skill change as a pull request for an admin to review: ```text wrap theme={null} @Claude that worked. Open a PR to the skills repo so this query pattern is part of the Datadog skill. ``` See [the admin guide to a skills repository](/docs/claude-tag/admins/skills-repo) for what that setup gives you. A `CLAUDE.md` carries setup as well as conventions. Sessions run in a sandbox with a standard set of preinstalled tools. If the repository needs more, such as a language runtime or a database client, put the install commands in `CLAUDE.md`, and Claude [runs them when its work needs them](/docs/claude-tag/admins/configure-github#install-project-dependencies). A `CLAUDE.md` is guidance; a required status check is a gate. If a pull request must carry a label or pass a check, make that a repository rule rather than a memory note or a skill. The same goes for review: to require an approval from someone other than the person who asked Claude for the change, see [Require a second approval on Claude's pull requests](/docs/claude-tag/admins/configure-github#require-a-second-approval-on-claude%E2%80%99s-pull-requests). ### Configure Claude for a channel The **Configure** link in the footer of any Claude reply in a channel opens a page where you tailor how Claude behaves in that channel. You can also send [`@Claude !configure`](/docs/claude-tag/users/commands#get-the-link-to-configure-a-channel) in the channel, and Claude replies with a link to the same page. The page is on claude.ai, so you need to be signed in to your Claude organization to edit it, and an admin can [restrict editing](/docs/claude-tag/admins/attach-to-scope#restrict-who-can-set-channel-instructions) so the page is read-only for members. The **Respond automatically** toggle on that page controls whether Claude replies in the channel without an @-mention. See [Turn automatic replies on or off](/docs/claude-tag/users/when-claude-responds#turn-automatic-replies-on-or-off) for what the setting does and the other places you can change it. Use the **Channel instructions** field on that page to write standing guidance Claude reads in every new session in the channel: the channel's purpose, its conventions, the tone replies should take, and anything Claude should do or avoid there. Channel instructions outrank channel memory and sit alongside any instructions an admin has set for the workspace or organization. Save the field and the change applies to new sessions started in the channel. The page's **Tools and access** tab shows **Connections**, the services Claude can reach from this channel, along with any allowed domains. You can see those lists but not change them on this page. The same tab's **Plugins** card lists the channel's plugins, and you can add plugins there unless an admin has restricted editing to admins. If an Owner has made you a [channel manager](/docs/claude-tag/admins/restrict-access#delegate-channel-setup-to-channel-managers) for the channel, the tab also has access bundle and repository cards you can edit. ## Keep thread count and review rate matched Claude runs as many threads as you start. Your capacity to review them doesn't scale the same way, because every thread that needs your judgment routes through you serially. Three conventions keep the queue manageable: * **One channel per project.** Threads and the project's working context stay in one place, and a glance at the channel shows the project's state. * **Batch your reviews.** Several threads in one sitting costs less than the same number spread across the day, because each return is a context reload. * **Mark closed threads.** React ✅ to anything you consider done, and tell your digest routine to skip them. ## Related resources * [Use case library](/docs/claude-tag/users/use-cases): the full setups these habits make reliable * [What Claude Tag remembers](/docs/claude-tag/users/memory): make corrections stick # What Claude Tag remembers Source: https://claude.com/docs/claude-tag/users/memory Claude Tag memory belongs to the channel, not to you. See how public channels share workspace memory, why private channels stay isolated, and how to check or correct it. Claude keeps memory by channel. Memory from public channels is shared across the workspace. What it learns working in a private channel is saved to that channel's own store, and channel memory isn't organized by person. In a direct message, Claude keeps separate notes for its conversation with you; see [Workspace memory](#workspace-memory). Memory accumulates three ways: * **You tell Claude.** Say "remember for this channel: reports go out as tables" and it saves the instruction. * **Claude saves facts on its own.** While working it keeps notes like decisions the channel made. * **Claude can read past sessions.** Ask it to look back and it lists earlier sessions in the channel and reads their transcripts; it can't full-text search across them, so name a timeframe or topic. ## Workspace memory Memory generated in public channels is shared across the workspace automatically. A decision recorded in #data-eng is available when you ask in #analytics. You can still point it at a specific channel, like "check what #data-eng knows about this." Reading and saving follow different rules depending on where Claude is working: | Where Claude is working | Reads from | Saves to | | :---------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------ | | Public channel | Workspace memory | This channel's notes or workspace-shared, both inside the workspace store | | Private channel | That channel's memory, plus workspace memory (read-only) | That channel's own store | Other workspaces stay separate. Direct messages stay separate too. Claude keeps notes for each direct-message conversation, stored with the workspace rather than with your Claude account. Those notes are deleted when an Owner [disconnects the workspace](/docs/claude-tag/admins/workspaces#revoke-a-pairing), not when you disconnect your own Claude account in Slack. If a private channel is later made public, its accumulated memory does not move with it: new sessions there read and write the workspace store, and the memory it saved while private is no longer read by new sessions. If a public channel is later made private, what Claude saved to workspace memory while the channel was public stays in workspace memory, where sessions in the workspace's other channels can still read it, and new sessions in the now-private channel save to the channel's own store. If those earlier entries shouldn't stay shared, ask an Owner to delete them from the workspace scope's memory files. ## Manage what Claude Tag remembers Anyone in the channel can save, read, and correct memory by talking to Claude directly in the channel. ### Make an instruction stick Memory is a curated note, not a transcript. To make something permanent, say so explicitly: ```text wrap theme={null} @Claude remember for this channel: changes go to acme/data-pipeline, never acme/website, and run the lint check before opening any pull request. ``` Keep saved instructions short. Long entries crowd out everything else; memory works best holding stable facts, not a running log of events. For longer playbooks, put them in a repository Claude can read. The documents that onboard a person to your team work as context the same way. Link the runbook, style guide, or review checklist in the channel, or store them where it can read them, instead of re-describing their contents in memory. ### Check and correct what Claude Tag remembers Ask Claude in the channel to list everything it has saved to memory. ```text wrap theme={null} @Claude what do you remember about this channel? ``` If something is wrong or stale, tell it to update or forget the entry. Anyone in the channel can read and change channel memory. Two habits keep memory useful over time: * **After correcting an entry, have Claude record the fix.** "Update your memory for this channel so this doesn't happen again" turns a one-time fix into a standing one. * **Prune what your work has outgrown.** Entries written weeks ago can describe a repository, owner, or convention that no longer exists. Ask Claude in the channel to review its memory and drop the entries that no longer apply. For ongoing upkeep, set up a [routine](/docs/claude-tag/users/proactivity) that repeats the review on a schedule; weekly works well. An Owner in your Claude organization can view, edit, or delete a scope's memory files at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), under the scope's options menu. ## Related resources * [How Claude Tag works](/docs/claude-tag/concepts/how-it-works): the scope, channel, and thread model behind memory * [Good habits](/docs/claude-tag/users/good-habits): habits that keep memory accurate # Choose the model Claude Tag uses Source: https://claude.com/docs/claude-tag/users/models Ask Claude to switch models in a Slack thread, set a channel's default model, or pick the model for your direct messages. See which models you can use and how to confirm which one replied. Every Claude Tag reply in Slack comes from one Claude model, and you choose which one by asking Claude for it in plain language, the same way you hand it any other task. The footer of each reply names the model that handled it, so you can confirm a switch took effect. Model choice is part of Claude Tag, which is available on Team and Enterprise plans. It isn't available on individual plans (Free, Pro, or Max) or for third-party deployments. Which models you can ask for depends on your organization; see [which models you can use](#which-models-you-can-use). ## Switch the model in a thread Tell Claude which model you want, in your own words, in the thread. ```text wrap theme={null} @Claude switch to Claude Opus 4.8 for the rest of this thread. ``` To confirm the switch, check the reply footers. The reply that acknowledges the switch still names the previous model, because Claude writes it before the switch takes effect; the new model appears in the footer of the reply after it. Asking in a thread changes the model for that thread only. To change what new threads in the channel start on, set a [default model for the channel](#set-a-default-model-for-the-channel) instead. The same request works in a direct message, where it applies to that conversation only. ## Set a default model for the channel To change what new threads in a channel start on, ask for the channel, not just the thread. ```text wrap theme={null} @Claude use Sonnet for this thread, and make it the default model for this channel. ``` Claude sets the channel's default model, which applies to new threads in that channel. Threads already underway keep the model they started with until someone in them asks Claude to switch. If an admin has set the scope's **Channel member edits** setting to **Block**, Claude declines to set the channel default; ask for the thread alone instead. Admins set the same default from claude.ai, per workspace or channel; see [choose the model for a scope](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope). ## Choose the model for your direct messages Open the Claude app's **Home** tab in Slack. When model selection is enabled for your organization, the tab includes a model selector for direct messages. New direct message conversations you start with Claude use the model you pick there. The selector offers only the models your organization allows. The selector doesn't change a conversation already underway. To change one of those, ask Claude to switch in that conversation. ## Which models you can use Anthropic manages the list of models on offer, and your organization's settings narrow it. The options include Opus and Sonnet models, drawn from what's available to your organization. Every list you see in Slack, the direct message selector and the models Claude offers to switch to, is already filtered to that set. To see the current list, ask in the thread. ```text wrap theme={null} @Claude what models can I use here? ``` If you ask for a model that isn't on the list, Claude tells you it isn't available, and the thread stays on the model it was already using. ## Related resources * [Get started](/docs/claude-tag/users/getting-started): what else the reply footer links to * [Customize Claude Tag](/docs/claude-tag/admins/customize#choose-the-model-for-a-scope): how admins set a default model per workspace or channel, and how the organization's model policy applies # Set up routines Source: https://claude.com/docs/claude-tag/users/proactivity Claude Tag runs routines you set up from the channel. See scheduled jobs, channel watching, pull request subscriptions, paste-ready routine recipes, and how to list or pause standing work. You can give Claude standing work from any channel it's in. This standing work is called a routine: a job that runs on a schedule, such as watching a channel, following a pull request, or posting status updates. You set a routine up in the channel where it should run, and it uses that channel's connections with the same permissions as a typed request. ## Set up standing work ### Scheduled jobs Describe the schedule you want and the work Claude should do in one message: ```text wrap theme={null} @Claude every weekday at 9am, read the open threads in this channel, check the tickets and pull requests linked in them, and post a one-line status per item. Skip anything with a ✅ reaction. ``` Name the output format in the job so recurring posts stay scannable. ### Watch channels Ask Claude to watch named channels and post here when something matches a topic: ```text wrap theme={null} @Claude watch #product-announce, #eng-announce, and #design-announce. Once a day, post here if anything is relevant to user education. Skip days with nothing. ``` Naming both the channels and the topic is what keeps a watch useful. The watch can cover this channel too ("keep an eye on this channel and post a morning summary"). ### Follow a pull request Claude can subscribe to a single pull request and react when it updates. A subscription is the one way Claude reacts to GitHub events; it wakes on activity on that pull request, such as a comment, a failed check, or a merge. You can't set up a routine from Slack that fires on other repository events, such as every new pull request. ```text wrap theme={null} @Claude subscribe to PR #482 in acme/data-pipeline. When CI finishes or a review lands, post here, and tag me if anything failed. ``` ## Routine recipes Each recipe below sets up a complete routine with one message. Adapt the channel names, repositories, and times to your own, and name the timezone in each message, since schedules run in UTC. ### Daily standup summary Claude posts a morning rollup of open threads and anything waiting on someone, before the team starts the day. ```text wrap theme={null} @Claude every weekday at 9am Pacific, post a summary of open threads in this channel and anything that looks like it's waiting on someone. ``` "Waiting on someone" makes the rollup surface actions, not just a recap; [Catch up](/docs/claude-tag/users/use-cases/catch-up) has the one-off version. ### Weekly channel digest Claude posts one recap at the end of each week, so the channel has a single place to see what happened. ```text wrap theme={null} @Claude every Friday at 3pm Eastern, post a digest of this week in this channel: what got decided, what's still open, and anything waiting on someone. ``` For an intake channel, the [Triage requests](/docs/claude-tag/users/use-cases/triage-requests) version of this rollup also sweeps posts that never tagged Claude. ### Watch a pull request until it merges Claude subscribes to a single pull request and posts as it moves through CI, review, and merge. ```text wrap theme={null} @Claude subscribe to PR #482 in acme/data-pipeline. Post here when CI finishes, a review lands, or it merges, and tag me if anything failed. ``` [Follow a pull request](#follow-a-pull-request) explains what the subscription reacts to. ### Alert investigation when a monitor fires Claude checks the alerting dashboard on a schedule and posts a first pass at diagnosis for anything new, so the investigation is underway before anyone asks. This recipe needs a monitoring connection such as Datadog or PagerDuty; [Watch monitors and alerts](/docs/claude-tag/users/use-cases/watch-monitors) has the full setup. ```text wrap theme={null} @Claude every two hours, check the alerting dashboard against its last state. For anything new, post when it started, what changed around then, and what to look at first. ``` The routine posts only when something changed, not on every check. ### Automatic triage for new requests Claude answers, deduplicates, and routes requests as they arrive. This recipe is a standing role rather than a schedule; "remember for this channel" saves it to [channel memory](/docs/claude-tag/users/memory), so it applies to everyone's threads. ```text wrap theme={null} @Claude remember for this channel: when someone tags you on a request, check whether it duplicates something already reported, answer it directly if the answer exists, and otherwise route it to the right owner with a one-line summary. ``` Pair it with a weekly rollup so untagged posts are still swept; [Triage requests](/docs/claude-tag/users/use-cases/triage-requests) has both messages. ## Manage standing work Anyone in the channel can list, edit, or disable its standing work: * **List.** Ask "what routines do you have set up in this channel?", or send [`@Claude !routines`](/docs/claude-tag/users/commands#list-the-routines-in-a-channel). Add a channel mention or its ID, as in `@Claude !routines #other-channel`, to list another channel's routines; pick the channel from Slack's autocomplete so it lands as a real mention, since a typed name on its own isn't accepted. * **Edit.** Describe the change and it updates the job * **Disable.** Name the job to stop, as in "disable the Friday rollup" Standing work is visible to the channel: jobs post into the channel they belong to, or into another public channel you name that Claude has been added to. A channel's routines keep running if their creator leaves the channel, is removed from your Claude organization, or has their Slack account deactivated, and anyone still in the channel can disable them. Routines a person set up in a direct message with Claude belong to that person's account and are turned off when the person is removed from your Claude organization. A few boundaries apply: * A job runs with the channel's connections, the same as an interactive request. * Claude can post a job's output into another public channel in the same workspace only if the job's own channel is public and Claude has been added to the target channel. It labels the message with the channel it came from. * Claude doesn't post job output to private channels, DMs, group DMs, or externally shared channels, and doesn't message people directly. The one exception is the completion or failure notice it sends to whoever set up the routine, and only when that person's Slack account is connected to their Claude account. * Schedules run in UTC. Name the timezone when you set a schedule, as in "every weekday at 9am Pacific". With no timezone in your message, Claude uses the one on your Slack profile. To confirm the time Claude set, send [`@Claude !routines`](/docs/claude-tag/users/commands#list-the-routines-in-a-channel), which lists schedules in UTC. * A routine runs at a fixed UTC time, so each daylight saving change shifts its local time by an hour, in the same direction the clocks move. A routine running at 9am Pacific moves to 10am after the clocks go forward, or to 8am after they go back. Ask Claude to reschedule the routine to the local time you want. * A scheduled job that touches a github.com repository uses the same GitHub connection your admin set up for interactive work. See [Configure GitHub access](/docs/claude-tag/admins/configure-github#scheduled-work-uses-the-same-connection). ## Related resources * [Use case library](/docs/claude-tag/users/use-cases): every entry has a proactive form to copy * [Prompt library](/docs/claude-tag/users/prompt-library#manage-routines): prompts to create, audit, and stop routines * [Good habits](/docs/claude-tag/users/good-habits): write schedules that keep working # Prompt library Source: https://claude.com/docs/claude-tag/users/prompt-library Copy-paste prompts for Claude Tag in Slack, each with why it works. See first messages, forwarded-message handoffs, channel rules, memory checks, routines, and mid-thread steering. These prompts are ready to copy, paste, and adapt: swap in your own channel names, services, and repositories. Each comes with the reason it works, so you can keep the mechanism when you change the words. ## First messages in a new channel Ask what Claude can access from this channel: ```text wrap theme={null} @Claude what can you access from this channel? ``` **Why it works**: what Claude can do differs per channel, and without this grounding Claude may suggest tasks it can't do here. Get a personalized starting point: ```text wrap theme={null} @Claude learn what you can about my role from this workspace, then tell me three tasks you could take off my plate this week. ``` **Why it works**: it's a discovery task with a bounded output. By asking for three tasks, you get a list you can judge in ten seconds and reuse as a menu of next tasks. Start with a low-stakes task: ```text wrap theme={null} @Claude catch me up on this channel since Monday. ``` **Why it works**: you bound the task with "since Monday", and you can grade the result yourself because you were there. ## Forward a message as a task To turn an existing Slack message into a task, for example a bug report or a request someone posted, forward it to a channel Claude is in. In the message you attach when forwarding, name the deliverable and say what Claude should do if it isn't possible. Claude reads the forwarded message, so you don't need to retype its contents. ```text wrap theme={null} @Claude investigate this. If it's something we can fix, open a draft PR; if not, post who owns it and why it's theirs. ``` **Why it works**: by giving Claude both branches, you get a useful result whether or not a fix is possible. To hand over a discussion too long to forward, paste the thread's link instead: ```text wrap theme={null} @Claude read the thread linked below and take over the fix it describes. Post your plan here before changing anything. ``` **Why it works**: Claude works in the thread where you pasted the link, not in the thread you linked, so it uses this channel's connections and this channel can see the result. By asking Claude to post its plan first, you can redirect it before it starts. To read a linked thread in a public channel, Claude must be a member of that channel, and it can read a private channel's threads [only from inside that channel](/docs/claude-tag/users/good-habits#pick-the-right-surface). If Claude says it can't read the link, `/invite @Claude` in the linked public channel, or forward the messages instead. ## Shape how the channel works Use the prompts below to set channel-wide behavior that applies to every thread, not just yours. ```text wrap theme={null} @Claude remember for this channel: keep replies short, and always include a link to the source. ``` **Why it works**: you're explicitly telling Claude to save the rule. Claude usually doesn't keep preferences you mention in passing. ```text wrap theme={null} @Claude stay quiet in this channel unless tagged. ``` **Why it works**: you're stating standing channel behavior, so Claude applies it beyond the current conversation. ```text wrap theme={null} @Claude remember for this channel: treat every top-level post as a task and pick it up without waiting for a mention. ``` **Why it works**: Claude already [picks up untagged posts when it judges a reply is warranted](/docs/claude-tag/users/when-claude-responds), and it weighs this channel-memory rule in that judgment, so teammates don't have to remember to tag Claude on posts with a concrete ask. If you don't specify a need, or if a teammate has already claimed the task, Claude may not respond to the message. In [a channel Claude has stopped reading](/docs/claude-tag/users/when-claude-responds#when-claude-stops-reading-a-channel), mention `@Claude` so that it replies and starts reading the channel again. ## Check and correct memory ```text wrap theme={null} @Claude what do you remember about this channel? ``` **Why it works**: memory is a curated note and Claude decides what's worth keeping, so you have to ask to know what stuck. ```text wrap theme={null} @Claude that's outdated — forget the entry about the old project name. ``` **Why it works**: you name the specific entry, so Claude doesn't have to guess what's stale the way it does with "clean up your memory". ```text wrap theme={null} @Claude update your memory for this channel so this doesn't happen again. ``` **Why it works**: when you correct Claude in a thread, you fix that thread only. With this message, Claude saves the correction and applies it in everyone's future threads. ## Manage routines Create, audit, and stop the scheduled jobs Claude runs in this channel. For paste-ready schedules by scenario, like a daily standup summary or a weekly digest, see [Routine recipes](/docs/claude-tag/users/proactivity#routine-recipes). ```text wrap theme={null} @Claude every Friday at 3pm, post a summary of this week's requests: how many, top themes, and anything still unrouted. ``` **Why it works**: you name the schedule and the post's contents, so every week Claude posts the same shape and you can compare to last week. By asking for anything still unrouted, you get a sweep for dropped requests, not just a recap. ```text wrap theme={null} @Claude what routines do you have set up in this channel? ``` **Why it works**: schedules are channel state, and someone else may have set them up. Check what exists before you create a duplicate digest. ```text wrap theme={null} @Claude disable the daily digest job. ``` **Why it works**: you name which job. Any channel member can disable a scheduled job; you don't need to find an admin to stop a noisy routine. ## Steer work mid-thread Reply in the same thread; once Claude is working there, you don't need to @-mention it again. ```text wrap theme={null} Status check — what's done and what's left? ``` **Why it works**: you're replying into the session that's running the task, with full context. If you ask in a new thread instead, Claude starts a second session that knows nothing about the first. ```text wrap theme={null} Change of plan: target the staging config instead, and post the diff here before applying anything. ``` **Why it works**: when you redirect in the thread, Claude keeps everything the session has already learned. By asking for the diff first, you and the channel can review the change before Claude applies it. ```text wrap theme={null} Post the draft to the thread, or commit and push what you have, then keep going. ``` **Why it works**: the thread is durable but [the isolated workspace behind it isn't](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies). Anything Claude posts to the thread or pushes to a branch survives idle recycling; files that exist only in that workspace don't. ## Task starters, by shape Each entry in the use case library gets one starter here; the linked page has the full setup and the reasoning behind its prompts. | To do this | Paste this | | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Triage requests](/docs/claude-tag/users/use-cases/triage-requests) | "remember for this channel: when someone tags you on a request, check whether it duplicates something already reported, answer it directly if the answer exists, and otherwise route it to the right owner with a one-line summary. Track recurring themes." | | [Catch up](/docs/claude-tag/users/use-cases/catch-up) | "what got decided in this thread, and what's still open?" | | [Create an artifact](/docs/claude-tag/users/use-cases/create-artifacts) | "turn this thread into a one-page decision doc" | | [Track a project](/docs/claude-tag/users/use-cases/track-projects) | "where are we on the migration? What's blocked and on whom?" | | [Answer a data question](/docs/claude-tag/users/use-cases/answer-data-questions) | "show signup growth by week, and explain the dips discussed above" | | [Find an answer in the docs](/docs/claude-tag/users/use-cases/find-answers) | "what's our policy on data retention, and which doc says so?" | | [Pull deal state](/docs/claude-tag/users/use-cases/pull-deal-state) | "what's the state of the Acme renewal?" | | [Watch monitors](/docs/claude-tag/users/use-cases/watch-monitors) | "every morning at 7, check the dashboards and post one line per service" | | [Fix a bug](/docs/claude-tag/users/use-cases/fix-bugs) | "in acme/data-pipeline, reproduce the bug in this thread, fix it, and open a draft PR" | ## Related resources * [Use case library](/docs/claude-tag/users/use-cases): the full setup behind each starter * [Good habits](/docs/claude-tag/users/good-habits): the habits these prompts are built from * [Getting started](/docs/claude-tag/users/getting-started): the basics, if you haven't sent a first message yet # Troubleshoot Claude Tag in channels and DMs Source: https://claude.com/docs/claude-tag/users/troubleshooting Fixes for common Claude Tag problems in Slack. See no reply after a reaction, queued or failed sessions, lost work, missing connections, blocked links and websites, and DM or account errors. When something goes wrong mid-conversation, the cause is usually one of a small set. Each entry below has the same three parts: what you see, what it means, and how to resolve it. For setup and credential errors, see the [admin troubleshooting page](/docs/claude-tag/admins/troubleshooting). Many fixes end with something to send your admin. On this page that means whoever manages your organization's Claude account at claude.ai, and it's often not the same person as your Slack administrator. If you don't know who that is, ask whoever set Claude up in your workspace. ## No response or silence ### Mentioning @Claude does nothing at all **What you see** `@Claude` gets no reaction and no reply. **What it means** Total silence has several possible causes, from the app not being installed to the channel being turned off, and the checks below separate them. **How to resolve** Work through these in order. Each step says what success looks like and where to go if it fails. 1. **Is the Claude app installed in this workspace?** Start typing `@Claude` in any channel. **Works**: Slack autocompletes to a Claude app with an app badge; if more than one Claude app appears, check with your admin which one to use. **Fails**: nothing autocompletes, or only a person named Claude appears. The app isn't installed; this needs your admin (send them the [setup overview](/docs/claude-tag/admins/setup-overview)). 2. **Is Claude in this channel?** Type `/invite @Claude` in the channel's message box, not in a thread reply. Slack rejects `/invite` inside threads ("/invite is not supported in threads. Sorry!"). **Works**: Slack posts "Claude was added to #channel" (or "is already in this channel"). Mention it again. **Fails**: Slack says you can't add apps to this channel (a Slack Connect or guest-restricted channel); try an internal channel instead. If Slack says "You don't have permission to invite people to this channel", the channel or workspace limits who can add people. In Slack, open **Channel details** → **Agents & apps** (called **Integrations** in some Slack versions), select **Add**, and pick **Claude**. Or ask someone who can add people to the channel to add Claude. 3. **Is Claude Tag turned on for this channel?** Mention it again now that it's invited. **Works**: it reacts and replies. **Fails**: it replies "Claude is disabled in this channel" (Claude Tag is turned off for the channel, its workspace, or the organization), or it replies but behaves like the earlier Claude in Slack, with no channel memory and pull requests opening under your name rather than Claude's (the channel is set to **Legacy**). Either way this needs your admin (send them [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/restrict-access#migrate-from-the-earlier-claude-in-slack)). If `@Claude` still gets no reaction and no reply after all three, send your admin [the admin entries for a silent workspace](/docs/claude-tag/admins/troubleshooting#nothing-responds). If the silence covers every channel across an Enterprise Grid, the fix needs a Slack organization admin rather than your Claude admin, so send the link to them. ### Claude replies to me but not to a teammate **What you see** Claude answers your mentions in a channel, and a teammate's mentions in the same channel get silence or a refusal. **What it means** Mentioning Claude in a channel doesn't require the sender to have a Claude account or seat, so by default anyone in the workspace can use it. Your organization can restrict that with the [member access setting](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude), in which case members outside the restriction are declined. **How to resolve** Have the teammate mention `@Claude` themselves and report the exact text of any reply; the reply is the diagnosis. * No reaction and no reply at all: unusual when it works for you in the same channel; send your admin the exact channel and person. * A message about guests: see [the guest entry below](#claude-doesn%E2%80%99t-respond-in-channels-that-include-guests). * A message about permissions or access: your organization restricts who can use Claude; send your admin [the member access setting](/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude). ### Claude reacted or started thinking, then never replied **What you see** Claude added a reaction to your message, or an "is thinking…" line appeared under it, but no reply arrived. **What it means** A reaction or an "is thinking…" line without a reply usually means Claude is still working, not that your message was dropped. **How to resolve** 1. Send [`@Claude !status`](/docs/claude-tag/users/commands#check-whether-claude-is-still-working) in the same thread. Claude tells you, in a note only you can see, whether it's still working and for how long, without interrupting the work. If the note says Claude got disconnected, @-mention Claude in the thread and it picks up where it left off, with no restart needed. 2. If the silence has stretched well past what the task should need, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in the thread; it archives the session and starts a fresh one that still reads the thread. Starting a new thread and restating the request also works. Restarting abandons whatever the session was midway through, and there's no way to resume it. A silent session may still be working through a long task, so treat `!restart` as a last resort. ### Claude says my session is queued or failed to start **What you see** Claude posts in the thread: > Still waiting for available capacity — your request is queued and will start automatically. Replies in this thread are picked up automatically. Or, if the session never started: > Session failed to start: the session container never connected — please try again **What it means** The first message means the session was created and is waiting for capacity to run it. The session normally starts on its own within a few minutes. If your organization runs Claude's sessions on its own infrastructure, the wait lasts until that infrastructure starts the session. The second message means the session didn't start at all. The failure is usually temporary. **How to resolve** * For the capacity message, wait a few minutes. To add context while waiting, @-mention Claude in the same thread rather than starting a new one. A new thread only queues a second session behind the first. If Claude still hasn't started after several more minutes, send your admin [Still waiting for available capacity](/docs/claude-tag/admins/troubleshooting#still-waiting-for-available-capacity). * For the failed-start message, mention Claude in the same thread to retry. If the session fails to start again, ask an admin. ### Claude didn't react to a message I edited **What you see** You edited a sent message to add `@Claude`, and nothing happened. **What it means** Editing a sent message to add a mention doesn't trigger a response; Claude only picks up mentions from new messages. **How to resolve** Send a new message with the mention included. ### Claude never responds in a channel shared with another company **What you see** Mentions in a channel shared with another company get no answer, and usually no notice. **What it means** Claude doesn't operate in Slack Connect channels, the ones shared with another company. This holds regardless of admin settings. Messages there get no reply. See [externally shared channels](/docs/claude-tag/admins/restrict-access#externally-shared-channels). A channel shared across workspaces inside your Enterprise Grid isn't silent; what happens there depends on how those workspaces connect to Claude. When every workspace in the channel belongs to your one Claude organization, Claude answers, but with only your organization's default access and settings, so a repository or an instruction set up for that channel doesn't apply. A notice in the thread points this out from time to time. When the workspaces are connected to different Claude organizations, you see "This channel is shared among several Claude workspaces, so Claude cannot respond here" instead of an answer. Where guest access is restricted, you may first see "This channel is shared across multiple workspaces, and Claude can't verify whether it includes guests, so Claude can't respond here." If you ask Claude from another conversation to act in one of these channels, such as posting a message there, you see a reply that ends "Claude isn't available in channels shared across your Enterprise Grid". Each of these messages means the channel spans more than one workspace. The [admin entries on these messages](/docs/claude-tag/admins/troubleshooting#this-channel-is-shared-across-multiple-workspaces) explain what causes each one and what an admin can change. **How to resolve** Move the conversation to an internal channel that belongs to a single workspace, or to a DM, and mention Claude there. ### Couldn't check this channel just now **What you see** Claude replies in the channel: > Couldn't check this channel just now. Please try again in a moment. **What it means** When your organization restricts Claude in channels that include guests (the default), Claude checks each channel for guests before replying. That check briefly failed, so Claude declined this reply rather than guess. **How to resolve** Mention Claude again; the check usually passes on retry. If the same channel hits this repeatedly, send your admin [the admin entry on this message](/docs/claude-tag/admins/troubleshooting#couldn%E2%80%99t-check-this-channel-just-now). ### Claude doesn't respond in channels that include guests **What you see** Claude replies in the channel: > Claude doesn't respond in channels that include guests. You can remove the guests from this channel (Channel details -> Members -> filter by "guests"), or a claude.ai organization owner can allow it in Claude Tag settings under Advanced -> "Allow Claude to work in channels with guests". **What it means** The channel includes at least one Slack guest account, and your organization restricts Claude in channels that include guests (the default). **How to resolve** Any of these fixes works: * Remove the guests from the channel. In Slack, open **Channel details** → **Members** and filter by "guests"; guests show a **guest** badge on their Slack profile. * Move the conversation to a channel with no guests. * Ask a claude.ai organization owner to change the guest setting for this channel, and send them [the guest access setting](/docs/claude-tag/admins/restrict-access#restrict-guest-channels). They can let Claude reply with only the channel's own setup, or with full access. If you don't know who your organization's owners are, ask whoever set Claude up in your workspace. The guest access setting restores replies, not workspace search. Claude can't search the workspace from a channel that includes guests, even when it's allowed to respond there. Removing the guests or moving the conversation to a channel with no guests restores search as well. If the fix worked, a mention in the channel gets a reply. ## Too many or wrong responses ### Claude gave me a confident but wrong answer **What you see** Claude answered with certainty, and the answer is wrong or incomplete. **What it means** Claude can be wrong, including when it sounds certain. The most common wrong answer in Slack is an incomplete one, where Claude queried one source or one date range and reported the result as if it were the whole picture. **How to resolve** Before you share or act on a result, check the source links it posted, and ask it to show its work ("which channels did you search?" or "show me the query you ran"). If the answer is wrong, say so in the same thread with the correct answer; correcting it there is also how you steer the next attempt. For numbers and facts that matter, the [definition-of-done habit](/docs/claude-tag/users/good-habits#give-every-task-a-definition-of-done) helps. Make "include the source for every figure" or "show me the query" part of the ask. ### Claude replies to every message in a thread **What you see** Claude answers messages in the thread that weren't addressed to it. **What it means** Once Claude is mentioned in a thread, it follows the whole conversation there and may reply to messages that weren't addressed to it. **How to resolve** Reply in the thread with an instruction such as "only respond when I @-mention you"; Claude follows that instruction for the rest of the thread. ### I want to take back something I sent **What you see** You edited or deleted a message, and Claude still acts on the original. **What it means** Claude has already read the original. An edit reaches it as a new update in the thread, so it may or may not act on the change, and it never undoes work already in progress. A deleted reply doesn't reach Claude at all. **How to resolve** Say so in a new reply ("ignore that, do X instead"), or start a fresh thread for a clean session. ### This conversation is too long for me to process **What you see** Claude posts in the thread: > This conversation is too long for me to process and I couldn't finish this turn — please start a new thread to continue. In a DM it ends with "Click *New Chat* in the top right to start a fresh session" instead. **What it means** The thread has grown past what one session can hold, and it stays too long forever; retrying there can't work. **How to resolve** Start a new thread. You can paste a summary of where the previous one left off. ## Claude stopped mid-task The messages in this section mean a session started and then stopped partway through. For most of them the work is still there, and the same thread picks up where it stopped. For a disconnect, work that existed only on the machine running the session can be lost. Each entry says whether anything needs redoing. ### I hit repeated API server errors **What you see** Claude posts in the thread: > I hit repeated API server errors. I'll retry automatically in about 2 minutes — no need to do anything. Mention me to retry sooner. The related messages that start "Claude is over capacity right now" and "I hit API rate limits" behave the same way. The wait Claude names grows with each retry. If the retries run out, or the session isn't a thread session, the message ends "and stopped after retrying. Mention me to continue." instead. "The API request timed out and I stopped after retrying. Mention me to continue." and "An API server error cut my last response short, so it may be incomplete. Mention me to continue." always take that form. **What it means** The API serving the session returned repeated errors. The work isn't lost. When the message says Claude will retry automatically, the same conversation wakes again on its own, up to three times; a newer message from you in the thread cancels the pending retry. **How to resolve** Nothing, when the message says Claude will retry automatically; wait for it. Mention Claude in the same thread to retry sooner, or when the message asks you to. ### I hit API rate limits **What you see** Claude posts in the thread: > I hit API rate limits. I'll retry automatically in about 2 minutes — no need to do anything. Mention me to retry sooner. When the retries run out, the message is "I hit API rate limits and stopped after retrying. Wait a moment, then mention me to continue." **What it means** The Claude API rate-limited your organization's traffic partway through the turn. The work isn't lost. Rate limits are about momentary request rate, not accumulated usage: a single task makes many API requests in short bursts, so this can appear on an organization's very first request. It isn't the channel spend limit, and it doesn't mean anything is misconfigured. **How to resolve** Wait for the automatic retry, or wait a moment and mention Claude in the same thread; it picks up where it stopped. If it recurs constantly across channels, the organization's sustained traffic is above its rate limits; an admin can stagger heavy use or contact their account team about limits. If your message mentions a spend limit instead, that's a different problem; see [You've reached a Claude Tag spend limit](#you%E2%80%99ve-reached-a-claude-tag-spend-limit). ### This request needs usage credits that aren't available **What you see** Claude posts in the thread: > This request needs usage credits that aren't available and I couldn't finish this turn. Enable or purchase usage credits in claude.ai, then mention me to retry. **What it means** Your organization's usage credit balance can't cover the request, so the turn stopped. The session is still there. **How to resolve** An admin enables or purchases usage credits in claude.ai for your organization. Once that's done, mention Claude in the same thread to retry (adding credits doesn't restart the work on its own). The retry continues with the thread's conversation and context. [What survives between replies](/docs/claude-tag/concepts/how-it-works#what-survives-between-replies) covers what else carries over. ### Claude couldn't clone a repository for this session **What you see** Claude posts in the thread: > Claude couldn't clone a repository for this session. This can be temporary (for example a GitHub rate limit) — mention Claude in this thread to retry in a few minutes. If it keeps happening, this session may lack access to a repository it needs, or its credentials or integration may need to be reconnected. **What it means** The clone failed when the session started. A one-off failure is transient; the same repository failing every time usually means it isn't granted for this channel, or the connection it depends on needs to be reconnected. **How to resolve** Wait a few minutes, then mention Claude in the same thread to retry. If the same repository fails every time, send your admin [the GitHub access entry](/docs/claude-tag/admins/troubleshooting#github-doesn%E2%80%99t-work-in-this-channel). ### I got disconnected partway through **What you see** In the thread, Claude posts a message that begins "I got disconnected partway through and may not have finished" or "I lost my connection". The rest of the message either says that Claude is recovering on its own and how long to wait before mentioning it, or asks you to mention it so it can start again. A disconnect message appears in a thread where you're working with Claude, including a direct-message thread; Claude doesn't post one in a channel it's only watching or from a routine. If the machine running the session comes back, Claude removes the disconnect message from the thread, and there's nothing for you to do. If Claude restarts on a fresh machine instead, it edits the disconnect message to: > I've restarted on a fresh machine. Uncommitted changes from before the restart may not have carried over, so I'll re-check my work before continuing. No need to mention me. **What it means** The machine running this thread's session, the sandbox Claude works in, stopped partway through a turn, so the step Claude was on may not have finished. The thread's conversation is intact, and so is work Claude pushed to a branch, opened as a pull request, or posted into the thread. Files and drafts that existed only on the machine that stopped may not carry over to a fresh one. The entry [Claude lost work it created earlier](#claude-lost-work-it-created-earlier) describes the same kind of loss. **How to resolve** If the message says how long to wait, wait that long. If Claude hasn't posted in the thread by then, or if the message asks you to mention Claude, mention `@Claude` in the same thread. Claude runs the interrupted step again, so check the files and drafts from before the disconnect and ask Claude to redo anything that's missing. If the message says there's no need to mention Claude, wait for Claude to post in the thread. Claude re-checks its earlier work, then continues. If a disconnect message comes back after you mention Claude, the problem hasn't cleared yet. Wait a few minutes, then mention Claude in the thread again. ### Something went wrong and I couldn't finish this turn **What you see** Claude posts in the thread: > Something went wrong and I couldn't finish this turn. Mention me to retry. The related message "The API rejected the request as invalid, so I couldn't finish this turn. Mention me to retry." behaves the same way. **What it means** This is the catch-all for a turn that stopped mid-task. The error didn't match any of the more specific messages in this section, so the cause varies. If the message says "Something went wrong starting a session. Try again in a moment." instead, the session never started; the retry is the same either way. **How to resolve** Mention Claude in the same thread to retry; it picks up where it stopped. If the message repeats on every retry, [give feedback](https://support.claude.com) from the thread where it happened. ## Lost or stale work ### Claude lost work it created earlier **What you see** Claude can't find files or drafts it made earlier in the thread. **What it means** The isolated workspace where Claude works on a thread is recycled after a period of inactivity. Work that was pushed to a branch, opened as a pull request, or posted into the thread survives. Files that existed only inside that workspace don't, and Claude will need to recreate them. **How to resolve** Ask Claude to recreate the file, and for long-running work, ask it to commit and push early, or to post drafts into the thread as it goes, so nothing lives only in that workspace. The [definition-of-done habit](/docs/claude-tag/users/good-habits#give-every-task-a-definition-of-done) helps here. Make "push the branch" or "post the file" part of the task. ### My old thread stopped working, but new threads are fine **What you see** A thread created a while ago fails the same way on every retry, while new threads work. **What it means** A thread keeps the skills, plugins, and custom instructions it started with, so a thread created weeks ago can fall out of step with your organization's current setup, even though new threads work. Retrying in the same thread will usually keep failing the same way. **How to resolve** Send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in the thread. It archives the stuck session and starts a fresh one with your organization's current configuration, and the fresh session still reads the thread. Starting a new thread and restating your request also works; paste a link to the old thread so Claude picks up the context. ### Claude picked the wrong repository **What you see** Claude started working in a repository you didn't mean. **What it means** The request didn't name a repository, so Claude picked one from the channel's grants. **How to resolve** Start a new thread with the right one named in your first message, for example "in `acme/data-pipeline`, fix the failing import." Naming the repository up front is also how you prevent this. If you need another repository mid-thread, ask Claude to add it ("add acme/data-pipeline") and confirm with the **Confirm** button it posts; if the repository isn't allowed for this channel, Claude tells you after you confirm. ### Claude forgot instructions I gave it before **What you see** Something you told Claude earlier doesn't stick in later threads. **What it means** Channel memory is a small, curated note, not a transcript, and Claude decides what's worth saving, so passing details usually aren't kept. **How to resolve** To make an instruction stick, say so explicitly, as in `remember for this channel: always post reports as a table`. Keep saved instructions short; the per-channel memory budget is limited, and long entries crowd out everything else. For longer playbooks, store them in a repository Claude can read. Verify what stuck by asking what it remembers about the channel. See [What Claude Tag remembers](/docs/claude-tag/users/memory). ### A session link Claude posted shows a not-found page **What you see** You open a link to a session on claude.ai that Claude posted in Slack, such as the "open the session" link in a routine's completion message, and claude.ai shows a not-found page instead of the session. **What it means** A session Claude ran from a channel belongs to Claude's own identity rather than to the person who asked, so claude.ai shows it only to accounts in the Claude organization paired with the workspace, and then only to people who could see the conversation in Slack. Any workspace member can open a session from a public channel; a session from a private channel opens only for members of that channel and the person who started it. Anyone else sees not-found rather than a permission error. **How to resolve** Sign in to claude.ai with the account that belongs to the organization paired with your workspace. claude.ai matches you to your Slack identity through a connected Slack account or, failing that, through the email address on your Claude account, so if your Claude email differs from your Slack email, connect your Slack account first; DM `@Claude` and it prompts you. If the session came from a private channel, ask to be added to the channel. ## Access and connections ### A connection my admin added isn't showing up **What you see** Your admin added a connection, and Claude in your thread says it doesn't have it. **What it means** Claude isn't told about a connection added after its session started, so it doesn't list or offer the new service, even though the connection is usable. **How to resolve** Ask Claude to use the service by name; the connection works even though Claude didn't announce it. Or start a new thread, which picks up the connection on its own. For a scheduled job that's missing a connection, edit or recreate the schedule. If the fix worked, asking `@Claude what can you access from this channel?` in a new thread lists the connection. ### Claude says it can't access a channel it read before **What you see** One reply surfaces findings from a channel, and a later one says "I can't access that channel." Or Claude says it can't read a private channel it's a member of when you ask from another channel. **What it means** This usually doesn't mean access changed. For a public channel, Claude can search it without being a member, but it can't read the channel directly without being invited, so search results and direct reads come and go differently. For a private channel, membership isn't the issue. A private channel is readable only from inside it. Even when Claude is a member, it can't read that channel from any other channel or DM. **How to resolve** For a public channel Claude needs to read directly, invite it with `/invite @Claude` in that channel, then ask again in a new thread. For a private channel, ask in that channel itself, inviting Claude there first if it isn't a member. An invite lets Claude work inside the private channel, but doesn't make the channel readable from anywhere else. ### Claude says it can't reach a tool or service **What you see** Claude says it has no connection for a service you expected it to reach. **What it means** The channel likely hasn't been given a connection for that service; see [what each connection adds](/docs/claude-tag/admins/add-connections). **How to resolve** Ask your admin to add one for this channel and send them [the connection scope entry](/docs/claude-tag/admins/troubleshooting#a-connection-works-in-one-channel-but-not-another). Once they have, ask Claude to use the service by name, or start a new thread, which picks up the connection on its own. If the fix worked, asking `@Claude what can you access from this channel?` in a new thread lists the service. ### A connector works on claude.ai but not in Slack **What you see** A connector you use on claude.ai is missing when you work with Claude in Slack, or Claude says it has no access to that service. **What it means** Where you message Claude determines which connectors apply. A channel session uses the connections an admin attached to it. In organizations where [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available, Claude can also use your personal connectors there for your own tasks, after you allow it. A DM runs on your own claude.ai account and uses that account's connectors. You set up and authenticate connectors on claude.ai under **Customize > Connectors**; Slack has no connector settings of its own. The [settings map](/docs/claude-tag/concepts/settings-map) covers every settings surface. **How to resolve** For a channel, ask your admin to [add a connection](/docs/claude-tag/admins/add-connections) for the service. If [personal connectors in channels](/docs/claude-tag/concepts/personal-connectors) is available to your organization, Claude can also use your personal connectors for your own tasks, after you allow it. For a DM, work through these in order: 1. Check that your Claude account is connected. DM `@Claude` and it prompts you to connect if it isn't. 2. Check that the connector shows as connected under **Customize > Connectors** on claude.ai. 3. For a custom connector on a Team or Enterprise plan, an Owner adds it to the organization before you can connect it; see [third party connectors with remote MCP](/docs/connectors/custom/remote-mcp). 4. After connecting or reconnecting the connector on claude.ai, send Claude a new top-level direct message. A session loads its connectors when it starts, so your existing DM threads keep the set they started with and don't pick up the change. ### Claude says it has no internet access or can't open a link **What you see** You paste a URL or ask Claude to read a page, and it says the website isn't allowed, the request was blocked, or it lacks internet access. It may find the same page with web search and still not open the link. **What it means** Searching and opening a page take different paths. Web search runs on Anthropic's servers and needs no setup, and a search brings back content from the pages it matches, so Claude can often answer from what the search returned. Opening a URL happens from the channel's sandbox, the isolated workspace where Claude runs, and the sandbox reaches only websites your organization's setup allows; the web search setting has no effect on that. **How to resolve** Send your admin the link you tried to open along with [the blocked host entry](/docs/claude-tag/admins/troubleshooting#claude-says-a-host-isn%E2%80%99t-allowed-or-it-can%E2%80%99t-reach-the-internet). While you wait, ask Claude to search for the page instead; a search often brings back enough of the content to answer. Once your admin has allowed the website, retry; if it's still blocked, start a fresh thread. ### Claude can't connect over SSH **What you see** Claude reports it can't reach a host over SSH, or a database's native protocol times out. **What it means** Every request Claude makes from a channel passes through [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy), which carries HTTP and HTTPS only. A protocol that isn't HTTP, such as SSH or a database's native wire protocol, can't cross the proxy to any host, so this isn't a connection your admin can add. **How to resolve** If the service exposes an HTTP API, ask your admin to [add a connection](/docs/claude-tag/admins/add-connections) for that instead. ### You've reached a Claude Tag spend limit **What you see** Claude posts in the thread: > You've reached a Claude Tag spend limit. A Claude.ai organization owner can raise it in Claude.ai admin settings. Once the limit is raised, mention me to retry. You may also see a heads-up before you hit the limit. It starts "Heads up — your organization has used *N%* of its monthly Claude Tag spend limit." for the organization limit, or "Heads up — this channel has used *N%* of its monthly Claude Tag spend limit." for a channel limit. **What it means** Usage hit a cap an admin set, either for the whole organization or for this channel. A rate limit looks similar but is a different problem, and raising the spend limit doesn't clear it. If your message says "Hit the session rate limit — try again in a few seconds." (or "in about Ns" when Claude knows the wait), too many sessions started at once. Wait a moment, then mention Claude again. **How to resolve** Ask your admin to raise the limit; they do so at [`claude.ai/admin-settings/usage/claude-tag`](https://claude.ai/admin-settings/usage/claude-tag). Your admin here is whoever manages your organization's Claude account at claude.ai, not necessarily your Slack administrator. Once the limit is raised, mention Claude in the same thread to retry. ## DMs aren't working DMs run on your own Claude account rather than the organization's agent. They need a seat that includes Claude Code, and they use your personal connectors rather than the channel connections. If channels work but DMs don't, first check that your Claude account is connected; DM `@Claude` and it prompts you to connect if it isn't. ### I get an environment error in a DM **What you see** Claude replies in the DM: > I couldn't find a Claude Code environment for your account. Set one up at claude.ai/code and try again. **What it means** DMs run on your own claude.ai account rather than the organization's setup, which is why this appears there and not in channels. It's usually a brief lookup failure rather than a missing environment. **How to resolve** 1. Mention Claude again; the retry usually clears it. 2. If it keeps happening, the environment your account is set to use may no longer be available; check it at [`claude.ai/code`](https://claude.ai/code). If a channel (not a DM) shows session-start failures that mention an environment, send your admin [the environment scope entry](/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one). ### Your Claude account is connected, but it doesn't have access in this organization **What you see** Claude replies in the DM: > Your Claude account is connected, but it doesn't have access in this organization yet, usually because it needs a seat that includes Claude Code. A Claude admin can add one in your organization's settings. Once they do, mention me here and I'll pick this back up. The Claude app's **Messages** tab and Slack's assistant panel both count as DMs even though neither looks like one, so this message can appear when you thought you were using a channel. **What it means** Your seat type doesn't include the Claude Code engine that powers DMs. Mentioning `@Claude` in a real channel doesn't depend on your seat type and keeps working. **How to resolve** Channels keep working while you wait, so mention `@Claude` there if you need an answer now. Then ask your admin (whoever manages your organization's Claude account at claude.ai) about your seat assignment; the [admin entry on this message](/docs/claude-tag/admins/troubleshooting#your-claude-account-is-connected-but-it-doesn%E2%80%99t-have-access-in-this-organization) covers the fix. ### Your Claude admin has disabled sending direct messages to Claude **What you see** Claude replies when you DM it: > Your Claude admin has disabled sending direct messages to Claude. **What it means** DMs are turned off organization-wide. **How to resolve** Use a channel instead, or ask your admin about enabling DMs. ### Group DMs aren't supported **What you see** Claude replies in the group DM: > Group DMs aren't supported yet. Try a channel or a 1:1 DM instead. **What it means** Claude works in channels and one-to-one DMs only. **How to resolve** Start a private channel with the same members instead. ## Related resources * [How Claude Tag works](/docs/claude-tag/concepts/how-it-works): why behavior differs by channel and thread * [Give feedback](https://support.claude.com): report a bug from the thread where it happened # Use case library Source: https://claude.com/docs/claude-tag/users/use-cases Shapes of work teams hand Claude Tag in Slack, each with prompts to paste. See triage, catch-up, docs and tickets, project tracking, data, deals, monitoring, and bug fixes. Each use case below links to a page with prompts to paste, what it needs connected, and how to set it up to [run on a schedule or watch the channel](/docs/claude-tag/users/proactivity) instead of asking each time. If typing `@Claude` doesn't show **Claude** with an **APP** badge, the Claude app isn't installed in your Slack workspace; ask your Slack admin to install it. If the mention sends but Claude doesn't reply, ask your Claude organization admin to enable Claude Tag for the channel and send them the [setup guide](/docs/claude-tag/admins/setup-overview). ## All use cases | Use case | Who it's for | What Claude does | Connections needed | | :---------------------------------------------------------------------------------------- | :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | | [Catch up](/docs/claude-tag/users/use-cases/catch-up) | Anyone | Summarizes a thread, a channel, or what's waiting on you | Nothing | | [Work from your own channel](/docs/claude-tag/users/use-cases/your-own-channel) | Anyone | Answers scratch questions, digests channels you don't follow, and chases what you said you'd do | Nothing (issue tracker or GitHub optional) | | [Triage requests](/docs/claude-tag/users/use-cases/triage-requests) | Support, ops, IT, any intake channel | Answers what it can, flags duplicates, routes the rest, rolls up themes | Nothing (issue tracker optional for filing) | | [Turn threads into docs and tickets](/docs/claude-tag/users/use-cases/create-artifacts) | Anyone | Produces a decision doc, status memo, ticket, send-ready reply, or hosted web page from a discussion | Nothing (Drive or issue tracker optional) | | [Track projects and chase approvals](/docs/claude-tag/users/use-cases/track-projects) | PMs, leads, anyone running a project channel | Posts standing status digests; follows up on stalled sign-offs | Nothing (issue tracker optional) | | [Find answers in your docs](/docs/claude-tag/users/use-cases/find-answers) | Anyone | Looks up policies, runbooks, prior decisions; replies with the source | Google Drive, Notion, or Confluence | | [Review documents against a checklist](/docs/claude-tag/users/use-cases/review-documents) | Ops, compliance, anyone reviewing against criteria | Checks documents in a connected tool against a checklist or policy; posts findings per item | Google Drive, Notion, or Confluence | | [Answer data questions](/docs/claude-tag/users/use-cases/answer-data-questions) | Analysts, data-adjacent teams | Runs warehouse queries, returns charts; or charts from Slack history alone | BigQuery, Snowflake, or Redshift (charts from Slack need none) | | [Fix bugs](/docs/claude-tag/users/use-cases/fix-bugs) | Engineering | Reproduces the bug, opens a draft PR, follows CI to green | GitHub (Datadog, Sentry optional) | | [Work with GitHub](/docs/claude-tag/users/use-cases/work-with-github) | Engineering, anyone with repository questions | Answers repository questions in-thread, watches pull requests for you, turns postponed chores into draft PRs | GitHub | | [Watch monitors and alerts](/docs/claude-tag/users/use-cases/watch-monitors) | On-call, SRE | Checks dashboards on a schedule; investigates alerts before anyone asks | Datadog, Sentry, or PagerDuty | | [Pull deal and account state](/docs/claude-tag/users/use-cases/pull-deal-state) | Sales, customer success | Answers account questions in-thread; pre-call briefs; weekly pipeline digest | Salesforce, HubSpot, or Gong | | [Claude Tag for marketing teams](/docs/claude-tag/users/use-cases/marketing-team) | Marketing | Answers policy questions from team docs, drafts from campaign threads, checks lead state, posts a weekly metrics digest | HubSpot or Salesforce, plus Google Drive, Notion, or Confluence; BigQuery or Snowflake for the metrics digest (varies by recipe) | ## Use cases by connection A connection is a tool an admin linked for the channel. Each one adds a category of work; ask `@Claude what can you access from this channel?` to see which your channel has. | Connection | Examples | What it adds | | :----------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | Knowledge and docs | Google Drive, Notion, Confluence | [Find answers in your docs](/docs/claude-tag/users/use-cases/find-answers) | | Issue tracking | Linear, Jira, Asana | [Turn threads into tickets](/docs/claude-tag/users/use-cases/create-artifacts), [track projects](/docs/claude-tag/users/use-cases/track-projects) | | Data warehouse | BigQuery, Snowflake | [Answer data questions](/docs/claude-tag/users/use-cases/answer-data-questions) with charts | | Go-to-market | Salesforce, HubSpot, Gong | [Pull deal and account state](/docs/claude-tag/users/use-cases/pull-deal-state) | | Monitoring | Datadog, Sentry, PagerDuty | [Watch monitors and alerts](/docs/claude-tag/users/use-cases/watch-monitors) | | Code | GitHub | [Fix bugs](/docs/claude-tag/users/use-cases/fix-bugs), open pull requests, follow CI | If a connection your work needs is missing, an admin can [add it](/docs/claude-tag/admins/add-connections). ## Related resources * [Prompt library](/docs/claude-tag/users/prompt-library): the prompts from every entry, plus the operational ones, on one page * [Good habits](/docs/claude-tag/users/good-habits): make any of these reliable * [Set up routines](/docs/claude-tag/users/proactivity): turn any entry into a scheduled job # Answer data questions Source: https://claude.com/docs/claude-tag/users/use-cases/answer-data-questions Claude Tag answers data questions in the Slack thread. See warehouse queries with charts, scheduled metric reports, and charts built from channel history alone. ## How data-question prompts work This page is for teams who answer questions from a data warehouse (the database where your analytics tables live, like BigQuery or Snowflake). These prompts turn a question asked in Slack into a query and a chart. Each prompt below is a Slack message. You paste it in the channel where the metrics get discussed, Claude queries the warehouse or reads the channel history and posts progress in that thread, and the result lands there too. The result is a chart with a short answer, returned once or on a schedule depending on the prompt. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :------------- | :------------------ | :------------------------------------------- | | Data warehouse | BigQuery, Snowflake | Required. Runs the queries behind each chart | ## Prompts to paste ### Chart a metric on demand The thread is debating something a number would settle. Ask in the channel where the metrics get discussed. ```text wrap theme={null} @Claude show signup growth by week for the last quarter, and explain the two dips people were debating above. ``` ### Schedule a recurring metrics report When the team checks the same numbers every morning, schedule the post. One message sets up the recurring report. ```text wrap theme={null} @Claude every morning at 8, post yesterday's key metrics as a chart with a two-line summary of anything unusual. ``` Naming the format, here a chart plus two lines, keeps a recurring post scannable instead of letting it grow each day. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Chart from Slack alone Charts don't require a connection, because channel history is data. It can chart request volume in a triage channel, or how long requests waited for a first reply. ```text wrap theme={null} @Claude chart the volume of requests in this channel by week, and how long each waited for a first reply. ``` Anyone in the thread can ask for a different cut of the same data. ## Related resources When the question is about systems, not metrics Recurring reports How Anthropic answers ad-hoc data questions in Slack with Claude # Catch up Source: https://claude.com/docs/claude-tag/users/use-cases/catch-up Claude Tag summarizes Slack threads and channels on demand. See one-off recaps, a scheduled morning rollup of open threads, and what's waiting on you. ## How catch-up prompts work Each prompt below is a Slack message. You paste it in any channel Claude is in, Claude reads the channel or thread history and posts progress in that thread, and the recap lands there too. The result is always a summary of what was said, returned once or every morning depending on the prompt. ## Check the channel's connections This use case needs no connections; it works on Slack history alone. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. ## Prompts to paste ### Get a one-off recap A thread ran to forty replies overnight, or you skipped a channel for a week. Ask for the catch-up you need. ```text wrap theme={null} @Claude catch me up on this channel since Monday. ``` ```text wrap theme={null} @Claude what got decided in this thread, and what's still open? ``` ```text wrap theme={null} @Claude summarize what I missed last week, grouped by topic. ``` Each of these bounds the work with a time window, one thread, or a grouping, so the summary comes back in a shape you can check. ### Schedule a daily recap If the first stretch of every morning goes to re-reading channels, schedule the recap instead. One message sets up a rollup that posts before you start the day. ```text wrap theme={null} @Claude every weekday at 9am, post a summary of open threads in this channel and anything that looks like it's waiting on someone. ``` "Waiting on someone" makes the rollup surface actions, not just a recap of yesterday. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ## Related resources When the catch-up should become an artifact Scheduling and triggers # Turn threads into docs and tickets Source: https://claude.com/docs/claude-tag/users/use-cases/create-artifacts Claude Tag turns a Slack discussion into the artifact you name. See replies you can send, decision docs, status memos, filed tickets, hosted web pages, page comments that reach Claude, and a capture-channel pattern. ## How artifact prompts work An artifact here is a generated document, page, chart, or file Claude posts or links in the thread for the team to use, as opposed to a chat reply. Each prompt below is a Slack message. You paste it in the thread or channel you want turned into something, Claude reads the discussion and posts progress in that thread, and the draft lands there too. What the draft is depends on the prompt, and each one below names the artifact it returns, like a decision doc, a customer reply, a filed ticket, a planning outline, or a hosted web page. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :------------- | :------------------ | :------------------------------------- | | None | — | Works on Slack content alone | | Issue tracking | Linear, Jira, Asana | Optional. Files tickets from the draft | ## Prompts to paste ### Draft from one thread The thread settled the question, and what's missing is the doc, the customer reply, or the ticket. Name the artifact in the thread where the discussion happened. ```text wrap theme={null} @Claude turn this thread into a one-page decision doc: what we decided, the options we rejected, and why. ``` ```text wrap theme={null} @Claude draft a reply I can send to the customer based on this discussion. Keep it under 150 words. ``` ```text wrap theme={null} @Claude file this thread as a ticket, assign it to the owner we discussed above, and post the link here. ``` Name the format and the length; "a doc" gets you a guess, "a one-pager with a decision section" gets you the artifact. ### Ask for a hosted page When the deliverable is a page people open, like a dashboard or a status page, ask for one. Claude publishes it as a web page hosted on claude.ai, posts the link in the thread, and updates it when you ask in the same thread. ```text wrap theme={null} @Claude build a status page from the open items in this channel and post the link here. ``` Anyone with access to this channel can open the page; [artifact visibility](/docs/claude-tag/concepts/security-and-data#artifact-visibility) covers the access model. ### Comment on the page to ask for changes After Claude publishes a page from a channel or a thread, it keeps watching that page for comments. Open the page, start a comment on the part you want changed, and send the comment with **Send to Claude** or mention `@claude` in it. The comment reaches the Claude session behind the Slack thread that published the page, even if that thread has been quiet for a while. Claude answers in the comment thread on the page, in the Slack thread, or both, and when the comment asks for a change, it edits the page and publishes the update to the same link, so everyone with the page open sees it. ```text wrap theme={null} @claude the churn figure in the summary table is from July. Pull the August number and update the chart to match. ``` Anyone who can open the page can comment on it, and anyone who can post in the source Slack channel can send a comment to Claude. To stop comments on a page from reaching Claude, ask Claude in the Slack thread to stop watching that page. Comments reach Claude on pages it published from a channel or from a thread in a channel. For a page Claude published in a direct message, or an artifact you published from your own Claude Code session and linked in Slack, ask for changes in the conversation where the page was made. If a comment you sent goes unanswered, ask in the Slack thread. A message there reaches Claude whether or not it is still watching the page, and Claude can pick the page back up from the link it posted. ### Keep a capture channel Planning inputs arrive over a month, not in one sitting. Forward messages and ideas to one channel as you find them, then ask for a synthesis when you need the artifact. ```text wrap theme={null} @Claude go through everything posted in this channel this month and synthesize it into an outline for the planning doc. ``` ## Related resources When you need the summary, not the artifact How to specify outputs that come back right # Find answers in your docs Source: https://claude.com/docs/claude-tag/users/use-cases/find-answers Claude Tag finds answers in connected docs and replies in the thread. See policy lookups, runbook checks, prior decisions, and answers from the Slack channel alone. ## How answer-finding prompts work Each prompt below is a Slack message. You paste it in the channel where the question came up, Claude searches the connected docs or the channel history and posts progress in that thread, and the answer lands there too. The result is always an answer with the source it came from, so you can open what it read. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :----------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------------- | | Knowledge and docs | Google Drive, Notion, Confluence | Required to search those sources; channel-history-only answers need none. Searches the docs the answers live in | ## Prompts to paste ### Look up a policy A customer asks about data retention and you need the policy, not a recollection. Ask where the question comes up. ```text wrap theme={null} @Claude what's our policy on data retention, and which doc says so? ``` Asking for the doc keeps the answer checkable, since you can open what it read. ### Check a named document Launch is close and you need to know whether the plan covers the EU rollout, without re-reading it. Point it at the document and the question. ```text wrap theme={null} @Claude does the launch plan cover the EU rollout? Quote the relevant section if it's there. ``` "Quote the relevant section" turns a yes/no into evidence. ### Find the latest version The pricing deck gets recreated every quarter, and the link you saved is two versions old. Ask for the current one. ```text wrap theme={null} @Claude find the latest pricing deck and post where it lives. ``` ### Answer from the channel alone Without any connection, Claude can still answer from the channel's own history. ```text wrap theme={null} @Claude what did this channel decide about the retention policy, and when? ``` Answers come from this channel's history and [memory](/docs/claude-tag/users/memory). ## Related resources The same mechanism pointed at "what did I miss" How channel knowledge accumulates # Fix bugs Source: https://claude.com/docs/claude-tag/users/use-cases/fix-bugs Claude Tag takes a bug report from Slack to a draft pull request. See reproducing the issue, watching a bug channel, root-cause digs, and following CI to green. ## How bug-fix prompts work This page is for engineering teams. A pull request is a proposed code change opened for review; Claude opens them under its own GitHub identity, so they appear in your review queue like any other pull request. Each prompt below is a Slack message. You paste it in the channel or thread where the bug lives, Claude works on it in an isolated workspace and posts progress in that thread, and the result lands there too. What the result is depends on the prompt, and each one below says what it returns, like a draft pull request, a root-cause writeup, or a standing watch that triages new reports as they arrive. Anything it opens on GitHub is authored by the Claude GitHub App. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :--------- | :------- | :----------------------------------------------------- | | Code | GitHub | Required. Reads the repo and opens draft pull requests | ## Prompts to paste ### Fix a reported bug A bug report arrives with reproduction steps and nobody free to take it. This gets you a draft pull request with the fix, linked back to the thread. Name the repository in the prompt so it's cloned before work starts. ```text wrap theme={null} @Claude in acme/data-pipeline, reproduce the bug in this thread, fix it, and open a draft PR. Done means CI is green and the PR links back here. ``` The done definition, CI green and the PR linking back, gives the session a finish line it can check itself against. The pull request appears under the Claude GitHub App and links back to the Slack thread it came from. See [how agent identity works](/docs/claude-tag/concepts/agent-identity#agent-access). ### Move a bug report to the owning team's channel A report that landed in a general channel belongs with the team that owns the code. Fork the thread into their channel and put the fix prompt in the fork, so the owners see the work as it happens and the original thread gets a link to follow. ```text wrap theme={null} @Claude !fork #data-platform in acme/data-pipeline, reproduce the bug described in the linked thread, fix it, and open a draft PR. Done means CI is green and the PR links back here. ``` Both channels must be public, and you and Claude must both be in the target. See [Fork a thread](/docs/claude-tag/users/commands#fork-a-thread). ### Watch a bug channel Reports arrive faster than the team triages them. The standing form watches the channel and opens drafts for anything reproducible. ```text wrap theme={null} @Claude when a bug report lands in this channel, try to reproduce it. If you can, open a draft PR and tag the area owner; if you can't, reply with what you tried. ``` With the if/can't branch, every report gets a reply, either a draft or a list of what was tried. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Diagnose a failure without a fix Not every failure needs a pull request. Ask for the diagnosis alone, and the decision about what to do with it stays with the team. ```text wrap theme={null} @Claude why is this failing? Trace it to a cause and post what you find — diagnosis only, no fix. ``` Naming the deliverable, a cause rather than a patch, keeps the session from jumping ahead to code changes nobody asked for. ### See a pull request through CI Once a pull request exists, one Claude opened or one a person did, Claude can watch it instead of you refreshing the page. It subscribes to that pull request and posts when CI status changes. ```text wrap theme={null} @Claude watch PR #482 in acme/data-pipeline. When CI finishes, post the result here, and tag me if anything failed. ``` "Tag me if anything failed" is the filter. Green runs land quietly in the thread, and only a failure interrupts you. For repository conventions that should hold across every session that touches the code, like where files go or what a pull request must include, see [Make repo conventions stick](/docs/claude-tag/users/good-habits#teach-claude-something-that-sticks). ## Related resources Catching the problem before the bug report Definitions of done for code tasks # Claude Tag for marketing teams Source: https://claude.com/docs/claude-tag/users/use-cases/marketing-team Claude Tag recipes for marketing teams in Slack. See policy answers in an intake channel, campaign channel recaps and send-ready drafts, lead and campaign state from the CRM, a weekly metrics digest, and brand voice rules saved to channel memory. ## How marketing prompts work This page is for marketing teams. The recipes below run in the channels where marketing work already happens, like an intake channel where other teams post requests, a campaign channel during a launch, and the channel where lead numbers get discussed. Each prompt below is a Slack message. You paste it in the channel where that work lives, Claude posts progress in that thread, and the result lands there too. What you get depends on the prompt, and each recipe names it, like an answer with the doc it came from, a channel recap, a send-ready draft, a list of CRM records, or a scheduled digest. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. Each recipe below names the connection it uses. | Connection | Examples | Why it matters here | | :----------------- | :------------------------------- | :----------------------------------------------------------------------- | | None | — | Recaps, drafts, and brand voice rules work on Slack content alone | | Knowledge and docs | Google Drive, Notion, Confluence | Answers policy and process questions from the docs where they're written | | Go-to-market | HubSpot, Salesforce | Reads CRM records, like contacts, leads, and deals | | Data warehouse | BigQuery, Snowflake | Runs the queries behind the metrics digest | ## Prompts to paste ### Answer policy questions in an intake channel Other teams bring marketing their process questions, like whether the company can sponsor an event, who approves a use of the logo, and who owns customer stories. When the answers are written in the team's connected docs, Claude can answer each request in the thread where it was asked. ```text wrap theme={null} @Claude a vendor asked us to sponsor their conference. What's our sponsorship policy, and which doc says so? ``` Asking for the doc keeps the answer checkable, since you can open what it read. To answer requests as they arrive instead of prompting each time, give the channel a standing role: ```text wrap theme={null} @Claude remember for this channel: when someone tags you on a request, answer it from the brand guidelines and the marketing process docs, name the doc you used, and route anything the docs don't cover to the right owner with a one-line summary. ``` "Remember for this channel" saves the role to [channel memory](/docs/claude-tag/users/memory), so it applies to everyone's threads, not just yours. [Triage requests](/docs/claude-tag/users/use-cases/triage-requests) adds a weekly rollup that also sweeps posts that never tagged Claude. Some questions have no doc to cite, and a person on the team answers in the thread. When that answer will come up again, tell Claude to save it: ```text wrap theme={null} @Claude remember for this channel: conference sponsorships are capped at $5,000, and the events lead approves each one. ``` The next person who asks gets the answer from channel memory instead of waiting for the team. When the policy changes, ask `@Claude what do you remember about this channel?` and tell it to update the entry. ### Recap a campaign channel and draft from it During a launch, a campaign channel fills with decisions, status updates, and copy changes faster than anyone can read them all. Ask for a recap bounded by a time window, and when a thread settles what an announcement should say, ask for the draft in that thread. ```text wrap theme={null} @Claude catch me up on this channel since Monday: what got decided, what's still open, and anything waiting on marketing. ``` The time window bounds the recap, so it comes back in a shape you can check. ```text wrap theme={null} @Claude turn this thread into an announcement draft I can send to the customer list. Keep it under 200 words and match the messaging doc linked above. ``` Name the format, the length, and the source the draft should match. The same prompt shape produces a decision doc or a status memo; [Turn threads into docs and tickets](/docs/claude-tag/users/use-cases/create-artifacts) lists the variants. ### Check lead and campaign state in the CRM A lead is a prospect record in a CRM like HubSpot or Salesforce, created when someone responds to a campaign. When the channel is debating whether a campaign's leads are moving, ask the question against those records. ```text wrap theme={null} @Claude which leads from last month's webinar campaign still have no owner, and how long has each been waiting? ``` Asking how long each has waited tells you which lead to chase first. ```text wrap theme={null} @Claude compare the leads the June campaign created against the ones that reached a queue, and post which ones stalled and at what stage. ``` The reply lists the stalled records and the stage where each stopped. The [HubSpot connection](/docs/claude-tag/admins/connections/hubspot) is created with read scopes, so prompts in this channel pull records and don't change them. For account questions, pre-call briefs, and a pipeline digest, see [Pull deal and account state](/docs/claude-tag/users/use-cases/pull-deal-state). ### Schedule a weekly campaign metrics digest When the team checks the same campaign numbers at the start of every week, schedule the post instead of asking each time. One message sets up the recurring report, and it needs a data warehouse connection to run the queries. ```text wrap theme={null} @Claude every Monday at 9am Eastern, post last week's campaign metrics as a chart: signups by campaign, week-over-week change, and a two-line note on anything unusual. ``` Name the timezone in the message, since schedules run in UTC. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Save brand voice rules to channel memory Claude follows the tone and terminology rules saved to a channel's memory, so a rule saved once applies to every later draft in that channel. ```text wrap theme={null} @Claude remember for this channel: headlines use sentence case, "sign up" is the verb and "signup" is the noun, and the product is never called a platform. ``` Keep saved entries short, since long entries crowd out everything else. For a full style guide, link the document in the channel or store it in a connected tool Claude can read, instead of re-describing its contents in memory. [What Claude Tag remembers](/docs/claude-tag/users/memory) covers how to check and correct what's saved. ## Related resources The full set of go-to-market prompts How the scheduled digest runs, and more recipes # Pull deal and account state Source: https://claude.com/docs/claude-tag/users/use-cases/pull-deal-state Claude Tag pulls account and deal state into the Slack channel. See in-thread account answers, pre-call briefs, and a scheduled weekly pipeline digest. ## How deal-state prompts work This page is for sales and customer-success teams. A deal (also called an opportunity) is a sales prospect tracked in a CRM like Salesforce or HubSpot; an account is a customer record. These prompts pull that state into the Slack channel where the team discusses it. Each prompt below is a Slack message. You paste it in the account or deal channel, Claude pulls from the connected CRM and the channel discussion and posts progress in that thread, and the result is posted in that thread. What you get depends on the prompt, and each one below names it, like one account's state, a pre-call brief, or a scheduled pipeline digest. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :----------- | :------------------------ | :--------------------------------------- | | Go-to-market | Salesforce, HubSpot, Gong | Required. Pulls account and deal records | ## Prompts to paste ### Check one account's state The reply lists last activity, open items, and who owns the next step for the named account. ```text wrap theme={null} @Claude what's the state of the Acme renewal? Last activity, open items, and who owns the next step. ``` ### Find stalled deals The reply lists deals stuck at the named stage and how long each has been there. ```text wrap theme={null} @Claude which deals are stuck in stage 3, and how long has each been there? ``` "How long has each been there" is the actionable half. Aging tells you which deal to work first. ### Get a pre-call brief The brief pairs what's in the system with what was discussed in the channel. ```text wrap theme={null} @Claude brief me on Initech before my 2pm: account history, recent activity, and anything discussed in this channel lately. ``` ### Schedule a weekly digest One message sets up a standing digest posted to the team channel every Monday. ```text wrap theme={null} @Claude every Monday at 9am, post a pipeline digest: deals that moved stage last week, deals stalled more than two weeks, and renewals due in the next 30 days. ``` The three lines cover what moved, what's stuck, and what's coming due, so the digest reads the same way every Monday. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ## Related resources When the question is metrics, not accounts Scheduled digests # Review documents against a checklist Source: https://claude.com/docs/claude-tag/users/use-cases/review-documents Claude Tag reviews documents in a connected tool against a checklist or policy and posts findings in the thread. See single-document checks, batch reviews, filing lists, comparisons with past reviews, and a scheduled weekly sweep. ## How document-review prompts work Each prompt below is a Slack message. You paste it in the channel where the review belongs, Claude reads the documents and the criteria from the connected tool and posts progress in that thread, and the findings land there too. The criteria can be whatever your team already uses, like a checklist, a policy document, or a filing list. Read the findings before you act on them, in proportion to what's at stake. If a finding needs checking, ask Claude to show its work in the same thread. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :----------------- | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | | Knowledge and docs | Google Drive, Notion, Confluence | Required. Claude reads the documents under review, and the checklist or policy they're checked against, from these tools | Claude can reach only what the connected account can see in that tool. If a document is missing from a review, ask an admin to [share it with the connected account](/docs/claude-tag/admins/add-connections#limit-access-to-specific-resources). ## Prompts to paste ### Review one document against a checklist A draft is ready to go out, and it has to pass the team's checklist first. Name the document and the checklist in the channel where the review is happening. ```text wrap theme={null} @Claude review the launch announcement doc against the review checklist, and post one finding per item: met, not met, or unclear, plus the section you based each call on. ``` Asking for the section keeps each finding checkable, since you can open what it read. ### Review a batch against a policy A quarter's worth of vendor documents landed in one folder, and each needs the same check. Name the folder and the policy. ```text wrap theme={null} @Claude go through each document in the vendor-docs folder and check it against the data-handling policy. Post a table with one row per document: what it covers, what's missing, and anything unclear. ``` One row per document bounds the work, so the review comes back in a shape you can check. ### Work through a filing list Your team keeps a list of filings to check, and each item needs a verdict by the end of the week. Point Claude at the list and where the filings live. ```text wrap theme={null} @Claude work through this week's filing list in the shared folder. For each item, find the matching filing, check it against the list's criteria, and post its status and what's missing. ``` Naming both the list and the folder scopes the search to the documents that matter. ### Compare with the last review A revised draft is in, and you need to know whether it fixes what the last review flagged. ```text wrap theme={null} @Claude review the updated vendor agreement against the checklist, then compare with what the review in this channel found last month and post what changed. ``` Naming the timeframe matters, since Claude looks back by listing this channel's earlier sessions and reading them. ### Schedule a recurring review New documents arrive every week, and the same check applies to each. Schedule the review instead of asking each time. ```text wrap theme={null} @Claude every Monday at 9am Pacific, check the shared folder for documents added in the past week, review each against the review checklist, and post the findings here. ``` Include the timezone in the message, since schedules run in UTC. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). Keep the checklist as a document Claude can read, in the connected tool or linked in the channel, rather than re-describing its contents in [channel memory](/docs/claude-tag/users/memory). ## Related resources The same connections pointed at a single question How the recurring review runs on a schedule # Track projects and chase approvals Source: https://claude.com/docs/claude-tag/users/use-cases/track-projects Claude Tag posts project digests no one has to compile. See standing status updates and follow-ups on contracts, design reviews, and pull requests until they close. ## How project-tracking prompts work This page is for anyone running a project from a Slack channel: pulling status, chasing approvals, and posting digests so the team doesn't have to ask. Each prompt below is a Slack message. You paste it in the project channel, Claude reads channel history and any connected trackers and posts progress and the result in that thread. What you get depends on the prompt, and each one below names it, like a one-time status digest, a scheduled daily digest, or a follow-up that runs until an approval lands. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :------------- | :------------------ | :------------------------------------------------------------------------------------------ | | Issue tracking | Linear, Jira, Asana | Optional. Adds tracker state to digests; without it, digests draw from channel history only | | Code | GitHub | Optional. Checks PR and review state | ## Prompts to paste ### Get a one-time status update The reply pulls status spread across days of channel scroll into one digest. Ask in the project channel. ```text wrap theme={null} @Claude where are we on the migration? What's blocked and on whom? ``` The digest comes back in the thread with what moved, what's blocked, and on whom, built from channel history plus any connected trackers. ### Schedule a daily project digest One message sets up a digest that posts every weekday. ```text wrap theme={null} @Claude every weekday at 5pm, post a project digest: what moved today, what's blocked, and what hasn't been touched in three days. ``` Name the format in the prompt, like the three sections here, so every digest comes back in the same readable shape. "Hasn't been touched in three days" is a number, so stalled work surfaces itself instead of depending on someone's sense of what counts as stale. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Chase an approval A contract sits with legal, a design review has no comments, a pull request waits on a reviewer. Claude can follow any of them until they close. It nudges when the review stalls and posts when the state changes. ```text wrap theme={null} @Claude every weekday, check the design review discussed in this thread. If it's gone two weekdays with no reviewer reply, nudge them here; when an approval lands, post that it's done. Done means approved, not just commented on. ``` Define what "done" includes; see [the babysit caution](/docs/claude-tag/users/good-habits#give-every-task-a-definition-of-done). Code approvals need the code connection. Scheduled follow-ups on repositories use that same GitHub connection, with nothing extra to set up. ## Related resources Schedules and event triggers Definitions of done that close threads # Triage requests Source: https://claude.com/docs/claude-tag/users/use-cases/triage-requests Claude Tag triages a Slack request channel with two setup messages. See in-thread answers, duplicate flags, owner routing, weekly theme rollups, optional ticket filing, and runbooks of standing answers. ## How triage prompts work This page is for any team with an intake channel, like #ask-it, #design-requests, or #legal-help, where people post questions and someone has to route or answer each one. The two prompts below are Slack messages you paste in the request channel, in order. Together they set up a standing role: when someone tags `@Claude` on their request, it replies in-thread, answering what it can, flagging duplicates, and routing the rest. The weekly rollup lands as a top-level post in the same channel and sweeps anything that wasn't tagged. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :----------------- | :------------------- | :---------------------------------------------------------------------------------------------------------------- | | None | — | Works on Slack content alone | | Knowledge and docs | Google Drive, Notion | Optional. Reads a [runbook](#give-claude-a-runbook-of-standing-answers) or past decisions the team keeps in a doc | | Issue tracking | Linear, Jira | Optional. Files routed items as tickets | ## Prompts to paste Add Claude to the channel with `/invite @Claude` if it isn't there, then two messages set it up. ```text wrap theme={null} @Claude remember for this channel: when someone tags you on a request, check whether it duplicates something already reported, answer it directly if the answer exists, and otherwise route it to the right owner with a one-line summary. Track recurring themes. ``` "Remember for this channel" saves the role to [channel memory](/docs/claude-tag/users/memory), so it applies to everyone's threads, not just yours. Tell requesters to include `@Claude` when they post; pin the convention or add it to the channel topic. ```text wrap theme={null} @Claude every Friday at 3pm, post a summary of this week's requests: how many, top themes, and anything still unrouted, including posts that didn't tag you. ``` "Including posts that didn't tag you" turns the recap into a sweep, so requests that arrived without a mention are still caught. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). Answers draw on what the channel has already settled, meaning its [memory](/docs/claude-tag/users/memory) and its own past threads, and routing gets more accurate as corrections land in channel memory. ## Hand a request to the team that owns it When a request belongs to another team, fork its thread into that team's channel from inside the thread. Claude starts a new thread there with the request as background and leaves a link in the original thread, so the requester can follow the work without being re-asked for details. ```text wrap theme={null} @Claude !fork #payments-eng take this request: the reporter needs refunds on partial orders, and their screenshots and the duplicate check are in the linked thread. ``` The channel you name must be public, with both you and Claude in it. See [Fork a thread](/docs/claude-tag/users/commands#fork-a-thread) for the other rules. ## Give Claude a runbook of standing answers When people keep posting the same questions in a channel, give Claude the team's settled answers instead of leaving it to derive an answer from the channel's history each time. A runbook is the team's own document of those answers, kept in whatever form the team already uses, such as a Google Doc. It can say which requests have a standard answer, which route to an owner, and which the team answers itself. To have Claude answer from the runbook, put the standing guidance in the **Channel instructions** field on the channel's [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). The field needs no connection, and a short runbook can go in it whole. Claude [reads a channel's untagged messages and replies to some of them on its own](/docs/claude-tag/users/when-claude-responds), so name the cases to leave alone as explicitly as the answers. For a runbook kept as a document, Claude can read it when an admin has [connected the app that holds it](/docs/claude-tag/admins/add-connections) and the connection's account can see the document. The instruction then points at the document: ```text wrap theme={null} Answer requests in this channel from the team's triage runbook: . Read it before answering. If a request isn't covered there, mention so they can pick it up. ``` The team keeps editing the document where it already lives, and the instruction reaches every new session in the channel. A team that wants each change reviewed as a pull request can keep its runbook as a skill in a [skills repository](/docs/claude-tag/admins/skills-repo), a git repository an Owner registers and attaches to the channel; a merged pull request syncs the update to your organization automatically, and anyone in the channel can ask Claude to draft that pull request. When an answer changes, update the runbook where it lives. Edit the document, edit and save the **Channel instructions** field, or merge a pull request in the repository. However you ship the update, check the changed answer in a fresh thread. A thread already underway keeps the instructions and skills it started with. ## Related resources How the weekly rollup runs on a schedule How the standing role persists and improves # Watch monitors and alerts Source: https://claude.com/docs/claude-tag/users/use-cases/watch-monitors Claude Tag watches dashboards and alert channels so you see one line per issue. See scheduled checks, alert investigation before anyone asks, and the prompts to set both up. ## How monitor-watch prompts work This page is for operations and on-call teams. A monitor is an automated check in a tool like Datadog or PagerDuty that fires an alert when a metric crosses a threshold. These prompts have Claude check those dashboards or investigate alerts as they arrive. Each prompt below is a Slack message. You paste it in the channel that receives the alerts, Claude checks the connected dashboards or investigates the alert and posts progress in that thread, and the findings land there too. What comes back depends on the prompt, and each one below names it, like a scheduled one-line-per-service check, a single alert's diagnosis, or a standing watch that posts only changes. ## Check the channel's connections Check that the channel has the connections below. Ask `@Claude what can you access from this channel?` to check; an admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :--------- | :------------------------- | :----------------------------------------- | | Monitoring | Datadog, Sentry, PagerDuty | Required. Reads dashboards and alert state | ## Prompts to paste ### Schedule a recurring dashboard check One message sets up a standing check that posts every morning, one line per service. ```text wrap theme={null} @Claude every morning at 7, check the service dashboards and post one line per service: green, or what's off and since when. ``` Name the output format in the schedule, like "one line per service" above, so every post reads the same way. To list or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Investigate a single alert Reply in the thread the alert landed in for a first pass at diagnosis. The prompt names what diagnosis means here and where to put the result. ```text wrap theme={null} @Claude investigate this alert: when it started, what changed around then, and what you'd look at first. Post findings here. ``` "When it started, what changed around then" points the work at diagnosis, and "post findings here" keeps the trail in the thread for whoever picks it up. ### Start the diagnosis before anyone asks Set this up as a routine to get both: a scheduled check against the last known state, and an investigation kicked off for any change. The routine posts only when something changed, not on every check. ```text wrap theme={null} @Claude every two hours, check the alerting dashboard against its last state. For anything new, post when it started, what changed around then, and what to look at first. ``` ## Related resources When the investigation should end in a pull request Schedules and event triggers How Anthropic runs Claude as first responder for CI/CD failures Reference playbooks, templates, and guided setup for an on-call channel # Work with your GitHub repositories Source: https://claude.com/docs/claude-tag/users/use-cases/work-with-github Claude Tag works with your GitHub repositories from Slack: answer questions in-thread, subscribe to pull requests, and hand back chores as draft pull requests. ## How GitHub prompts work This page is for engineers and anyone else with questions a repository can answer. Claude works with the GitHub repositories an admin granted for the channel. It reads the code to answer questions, watches pull requests you name, and hands back changes as draft pull requests. Each prompt below is a Slack message. Paste it in the channel or thread where the question lives. Claude clones the repository into an isolated workspace, posts progress in that thread, and delivers the result there too. Name the repository in the first message. A session starts with no repositories checked out and clones one when the request names it. Anything Claude opens on GitHub is authored by the Claude GitHub App, so it appears in your review queue like any other pull request. An admin [grants a repository to the channels that need it](/docs/claude-tag/admins/attach-to-scope), and questions about the code work only in those channels. By default anyone in those channels can ask, and an admin can [restrict who can use Claude](/docs/claude-tag/admins/restrict-access#control-who-can-invoke-claude-tag). ## Check the channel's connections Check that the channel has the connection below. Ask `@Claude what can you access from this channel?` and the reply also lists which repositories the channel can reach. An admin can [add a connection](/docs/claude-tag/admins/add-connections) the channel is missing. | Connection | Examples | Why it matters here | | :--------- | :------- | :----------------------------------------------------------------- | | Code | GitHub | Required. Reads granted repositories and opens draft pull requests | The GitHub connection is what lets Claude clone a repository. For GitLab, an admin [connects it with an access token](/docs/claude-tag/admins/connections/gitlab), and Claude reads projects, manages issues, and comments on merge requests through the GitLab API. If Claude replies that a repository isn't configured, the repository wasn't granted for this channel. An admin can [verify GitHub access](/docs/claude-tag/admins/configure-github#verify-github-access). After the grant changes, start a fresh thread and name the repository in the first message. ## Prompts to paste ### Answer a repository question without interrupting the author A question about how the code behaves arrives in the channel, and the person who wrote it is away. Claude clones the repository, reads the code, and posts the answer in the thread. ```text wrap theme={null} @Claude in acme/data-pipeline, how does the export retry logic decide when to give up? Name the files involved. ``` Asking for the files involved attaches proof to the answer, so anyone in the thread can open them and check. Investigation questions work the same way: when a behavior last changed, in which commit, and who to ask about it. ```text wrap theme={null} @Claude in acme/data-pipeline, did the export retry behavior change recently? Find the commit that changed it, when it landed, and who wrote it. ``` The clone carries the repository's full commit history, so history questions get answered from the same checkout as code questions. If the repository keeps a `CODEOWNERS` file, questions about who owns a path read from it too. ### Stop refreshing a pull request Your work is blocked on a pull request a teammate opened, and the only way to know it moved is to keep checking the page. Claude subscribes to the pull request and posts in the thread when it updates, whether Claude opened it or a person did. ```text wrap theme={null} @Claude subscribe to PR #519 in acme/data-pipeline, the schema migration. When CI finishes or a review arrives, post here, and tag me if anything failed. ``` Claude reads the pull request's workflow runs and logs, so the post says whether checks passed or failed. To list or cancel a subscription later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). Because the prompt asks for a tag only on failure, passing runs post to the thread without notifying you. ### Hand off the change you keep postponing Small, well-understood changes sit on the list for weeks because they never become urgent. Docs drift from the code, a config key keeps its old name, a dependency stays a version behind. Describe one in a message, and it comes back as a draft pull request linked to the thread. ```text wrap theme={null} @Claude in acme/data-pipeline, the CSV export docs still describe the old date format. Update them to match the code and open a draft PR. Done means CI is green and the PR links back here. ``` Writing a [definition of done](/docs/claude-tag/users/good-habits#give-every-task-a-definition-of-done) into the task lets the session check its own work. The change comes back as a draft pull request in your review queue, opened under Claude's own GitHub identity. ### Triage a suspected bug where the report arrives A report arrives in the feedback channel, and nobody knows yet whether it's a bug. Claude investigates the repository and either explains the behavior or opens a draft fix. ```text wrap theme={null} @Claude a user reports that exports drop rows with empty dates. In acme/data-pipeline, is that a bug or intended behavior? If it's a bug, open a draft PR with a fix; if it's intended, explain here what the code does. ``` For the full arc from a bug report to green CI, including a standing watch that triages a bug channel, see [Fix bugs](/docs/claude-tag/users/use-cases/fix-bugs). Because the prompt asks for either a fix or an explanation, the thread gets an answer even when the behavior turns out to be intended. ### Hand off a change and follow its pull request in one message You can combine the earlier recipes in a single message. The prompt below hands off a change, sets the definition of done, and asks Claude to subscribe to the pull request it opens. ```text wrap theme={null} @Claude in acme/data-pipeline, the deprecation warnings in the export module still reference the removed legacy-dates option. Remove the stale warnings and open a draft PR. Done means CI is green and the PR links back here. Then subscribe to your own PR, and when CI finishes or a review arrives, post here and tag me if anything failed. ``` Claude opens the draft and then follows it the way it follows any pull request, because subscriptions work the same whether Claude opened the pull request or a person did. CI results and review activity arrive as posts in the thread, so you open GitHub only to review the finished change. ### Act on review comments and CI failures Claude can watch a pull request and address CI failures, review comments, and change requests as they come in, until the pull request is ready to merge. You approve and merge. ```text wrap theme={null} @Claude watch your PR #562 in acme/data-pipeline. When CI fails, fix it and push. When a review comment arrives, address it and push. Post here after each push saying what changed and why. Done means CI is green and every comment is addressed. I do the approving and merging. ``` If you don't want Claude to merge pull requests, turn on branch protection rules that restrict who can merge. These rules apply to Claude too. Claude can't approve a pull request it opened, but the person who asked for it can; to require a second approver, see [Require a second approval on Claude's pull requests](/docs/claude-tag/admins/configure-github#require-a-second-approval-on-claude%E2%80%99s-pull-requests). Also write "I do the approving and merging" into the task, as the example does. The task wording states your intent, but it's an instruction Claude can lose track of, not a control. The branch protection rule is what enforces it. Ask for a post after each push so you can follow the pull request from the thread instead of opening GitHub. ## Repository instructions in CLAUDE.md If your repository has conventions Claude should follow, such as file layout, pull request labels, or dependencies to install, add them to a `CLAUDE.md` file at the repository root. When Claude clones the repository into a session, its `CLAUDE.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md` files load on the next turn, so the guidance arrives without further prompting. Skills in the repository's `.claude/skills/` folder also load, so Claude can use them in sessions that have the repository. Anyone with repository write access can edit these files, and they reach every session that works in that repository, from any channel. Each session runs in an isolated sandbox with a standard set of preinstalled tools. Two threads are two sessions with two separate sandboxes. If the repository needs a tool that the standard set doesn't include, such as a language runtime or a database client, add the install commands to `CLAUDE.md`, and Claude [runs them when its work needs them](/docs/claude-tag/admins/configure-github#install-project-dependencies). A `CLAUDE.md` is guidance rather than a gate. If a pull request must carry a label or pass a check, make that a repository rule. For where `CLAUDE.md` sits among channel memory, channel instructions, and skills, see [Teach Claude something that sticks](/docs/claude-tag/users/good-habits#teach-claude-something-that-sticks). ## Related resources The full arc from a bug report to a draft pull request and green CI Pull request subscriptions and other standing work # Work from your own channel Source: https://claude.com/docs/claude-tag/users/use-cases/your-own-channel Create a Slack channel for you and Claude Tag alone and run your work from it. See scratch questions, digests of channels you don't follow, a weekly status digest, follow-ups chased until they close, and a handoff that covers your time away. A channel with just you and Claude in it works the same way any other channel does. This page is for anyone who wants a place for work that doesn't belong in any specific team's channel, like half-formed questions, personal digests, and the things you said you'd do. ## Your own channel versus a DM A DM is the other place to work alone with Claude, and the two surfaces run on different accounts. A DM session runs with your own claude.ai connectors, the work is attributed to you (pull requests excepted; the Claude GitHub App authors those), and usage bills to your seat. What Claude does there sits outside channel and workspace memory. Your own channel runs with the connections an admin set for it, usage bills to the organization, and what Claude learns there accumulates as [channel memory](/docs/claude-tag/users/memory) that later threads build on. [Routines](/docs/claude-tag/users/proactivity) can post there on a schedule. When scratch work turns into a team task, the thread is ready to [hand to a teammate](#hand-a-thread-to-a-teammate). Pick a DM for personal tasks on your own connections, or for data that shouldn't run through a shared channel connection. Pick your own channel for standing work, and for anything you might later hand off or show someone. [Pick the right surface](/docs/claude-tag/users/good-habits#pick-the-right-surface) compares both against a team channel. ## Set up the channel 1. Create a Slack channel and add Claude with `/invite @Claude`. Make the channel public unless the work needs to be private, since [memory](/docs/claude-tag/users/memory) from a public channel is shared across the workspace and teammates can find and join the work. A private channel works too, and keeps its memory in its own store. 2. Ask `@Claude what can you access from this channel?`. None of the prompts below require a connection, and an admin can [add a connection](/docs/claude-tag/admins/add-connections) your work needs, like the issue tracker or GitHub. 3. Tell Claude how the channel should behave and ask it to remember, as in `@Claude remember for this channel: keep replies short, and format digests as tables`. Later sessions in the channel start from what you saved. ## Prompts to paste Each prompt below is a Slack message. You paste it in your channel, Claude works with the channel's history and connections, and the result lands in that thread. ### Ask scratch questions A question is half-formed, or the answer only matters to you. Ask it here instead of in a team channel. ```text wrap theme={null} @Claude summarize the last week of #product-feedback and pull out anything about the export flow. ``` Naming a public channel works from here, since Claude's Slack search covers public channels in this workspace. For a channel's full history rather than what search finds, Claude needs to be a member of that channel too. The answers stay in your channel, where later sessions read them. ### Get a digest of channels you don't follow Some channels matter to your work a few times a month, not daily. Have Claude watch them and post here when something is relevant. ```text wrap theme={null} @Claude watch #product-announce, #eng-announce, and #design-announce. Once a day, post here anything relevant to the billing migration. Skip days with nothing. ``` Naming both the channels and the topic keeps the watch useful, and skipping empty days keeps this channel readable. Instead of skimming three announcement channels yourself, you read at most one post a day here. ### Track your week Open threads pile up here the way they do in any project channel. A scheduled digest posts a weekly summary of where they all stand. ```text wrap theme={null} @Claude every Friday at 3pm Pacific, post a digest of this channel: what closed this week, what's still open, and what hasn't moved in five days. Skip anything with a ✅ reaction. ``` Give the digest a concrete threshold, like five days without movement, and stalled work shows up without you asking for it. React ✅ to anything you consider done, and the digest drops it. Include the timezone in the message, since schedules run in UTC. To list, edit, or cancel scheduled work later, see [Manage standing work](/docs/claude-tag/users/proactivity#manage-standing-work). ### Hand a thread to a teammate Scratch work sometimes turns into a team task. Suppose a thread in this channel started as a half-formed question about the export flow, grew into a reproducible bug, and the fix now belongs to your teammate Marta. That thread is ready to share as it stands, because anyone in the channel can steer a session by replying in it. Invite Marta to the channel (for a public channel, sharing the thread link works too) and ask for a handoff summary in the thread. ```text wrap theme={null} @Claude summarize this thread for Marta: what's been tried, what's decided, and what's still open. ``` The summary gives Marta the state of the work in one message, with the full history above it. From there the thread is hers to continue, without re-mentioning @Claude or starting over. If the work belongs in a team channel rather than yours, fork the thread there instead of inviting Marta in. Claude starts a new thread in the channel you name with your thread as background, and leaves a link in your channel so you can follow along. ```text wrap theme={null} @Claude !fork #export-team summarize the export-flow bug for the team: what's been tried, what's decided, and what's still open. ``` The target must be a public channel that both you and Claude are in, and your own channel must be public for the fork to run. See [Fork a thread](/docs/claude-tag/users/commands#fork-a-thread). ### Chase your open follow-ups Claude can track the work you've committed to but might have forgotten about. When you agree to do something in another channel, forward that message to this channel, or post a short note here describing the commitment. When the work is somewhere Claude can check through this channel's connections, like a pull request review you owe, include the link. Then schedule a weekly sweep. ```text wrap theme={null} @Claude every Monday at 9am Pacific, read this channel and post one line per thing I said I'd do that isn't done yet, with how long it's been open. Check anything linked before calling it done. Keep listing each item until I mark it with a ✅. ``` Monday's post lists each commitment in this channel that isn't done yet. React ✅ when you finish one and it drops off the list, and everything else comes back the next Monday. ## Cover your time away Your channel can cover for you while you're out. Before you leave, post one handoff message here and pin it. Say who's covering, where each piece of work stands, what to point people at, and what holds until you're back. Then tell Claude to answer from it and to pause the channel's standing work. ```text wrap theme={null} @Claude I'm out next week and Marta is covering. Where things stand: the billing migration is waiting on legal, the dashboard rebuild is paused until the design review closes, and the onboarding runbook is pinned in this channel. Leave the pricing config alone until I'm back. While I'm out, when anyone asks here, answer from this message and the channel's history. Pause this channel's scheduled posts until I say I'm back. ``` While you're out, a teammate who needs to know where a piece of work stands, or who owns it, tags `@Claude` in your channel and gets the answer from the pinned handoff message, the channel's history, and [channel memory](/docs/claude-tag/users/memory). If you set a Slack status or an out-of-office reply, point people to this channel in it. The pause covers this channel's own routines, like the Friday digest and the Monday sweep this page sets up, so scheduled posts stop piling up unread. Anyone in the channel can [list, edit, or disable its standing work](/docs/claude-tag/users/proactivity#manage-standing-work), so a teammate can turn a routine back on early if the coverage needs it. On your first morning back, ask Claude to catch you up. ```text wrap theme={null} @Claude I'm back. Turn this channel's scheduled posts back on, and post one list of what needs me first, in priority order, built from what happened here while I was away. ``` The reply is one list of everything that happened here while you were away, ordered by what needs your attention first. ## Related resources List, edit, or disable the standing work this page sets up Pick the right surface and write tasks that close # Control when Claude Tag responds Source: https://claude.com/docs/claude-tag/users/when-claude-responds What Claude Tag does with a channel message nobody tagged it in, and how to turn unprompted replies off for a thread or a channel. Read this if Claude is replying too much, or went quiet. Claude replies without an @-mention in DMs, in any thread it's already part of, and to channel messages it judges warrant a reply. In a channel, Claude reads the messages and replies to some of them on its own, so an @-mention is how you guarantee a reply, not a requirement for one. This page covers how Claude decides whether to reply to a message nobody tagged it in, how to turn those replies off for a thread or a whole channel, and which messages never get a reply. Work Claude does on a schedule rather than in reply to a message is a [routine](/docs/claude-tag/users/proactivity), which has its own controls. ## What triggers a response Whether Claude replies to a message without an @-mention depends on where you send it. | Where you write | Replies without an @-mention? | | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A DM with Claude | Always. Every message is addressed to Claude already | | A thread Claude is already in | Yes, unless you've [quieted the thread](#quiet-one-conversation). Once Claude has joined, every reply there reaches it without another mention | | A channel, top-level | Sometimes. [What Claude does with a channel message](#what-claude-does-with-a-channel-message) describes how it decides. Include `@Claude` to guarantee a reply, or [turn unprompted replies off](#quiet-the-whole-channel) | | A message another app or bot posted | No guaranteed reply. Claude reads it as context. `@Claude` in a bot's message doesn't wake a quiet channel; in an active channel Claude may pick it up. See [Messages from other apps and bots](#messages-from-other-apps-and-bots) | When you @-mention Claude in a channel, it reacts to your message with an emoji within a few seconds to show that it picked the message up. The message goes to the channel's own [session](/docs/claude-tag/concepts/glossary#session), the session Claude works from at the channel's top level. It then answers in a thread under your message, or starts a [working session](/docs/claude-tag/concepts/how-it-works) in that thread when the request needs investigation, tools, or a longer exchange. Once a working session starts, Claude shows an "is thinking…" line under your message. A reaction with no line under it means Claude picked your message up and is either still deciding or answering directly in the thread, not that it missed you. You can change how much Claude replies on its own. You can [quiet a single thread](#quiet-one-conversation), [turn unprompted replies off for a whole channel](#turn-automatic-replies-on-or-off), or [tell Claude which kinds of untagged messages to answer](#what-claude-does-with-a-channel-message). ## What Claude does with a channel message Claude reads every top-level message in a channel it belongs to, and the replies in the channel's threads, whether or not anyone tagged it. For each message, it decides what to do from the channel's recent messages, the channel's [memory](/docs/claude-tag/users/memory), and any instructions your admin has set or a channel member has asked it to remember, and does one of four things. * **Nothing.** This is the usual outcome. In a channel where nobody has told Claude which kinds of messages to answer, Claude leaves untagged messages alone. The one exception is a message in which someone states a concrete need Claude can meet; Claude may then reply once, in a thread, offering to do it. * **A short reply in a thread under the message.** Claude replies on its own only when it already has the answer, from the channel's history or its memory, and the answer fits in one message. Replies of this kind carry the plain name **Claude**; see [The name on a reply](#the-name-on-a-reply). * **A working session in the message's thread.** When a message needs investigation, tools, or a longer exchange, Claude starts a working session there and posts the work in that thread. For an untagged message, Claude does this only when someone in the channel has told it to pick up that kind of work, as described below the list. * **A hand-off to work already in progress.** When a message adds to something Claude is already working on in another thread, for example a new detail about a bug it's investigating, Claude passes the message to that working session instead of replying. Claude posts nothing in the channel when it does this; anything the new information changes, it reports in the thread where the work is happening. To have Claude answer more kinds of untagged messages in a channel, tell it which kinds, in the channel, and ask it to remember. For example, `@Claude remember for this channel: answer questions about the deploy process without waiting to be tagged` saves the instruction to channel memory, and Claude applies it to everyone's messages there. Claude also records in channel memory whether people in the channel act on its unprompted replies or ignore them, and replies less in a channel that ignores them. [What Claude Tag remembers](/docs/claude-tag/users/memory) covers how to see and change what it saved. ## Turn automatic replies on or off The **Respond automatically** setting controls whether Claude replies to a channel's messages without an @-mention. When it's on, Claude may reply to a message it judges warrants one, as [What Claude does with a channel message](#what-claude-does-with-a-channel-message) describes. When it's off, Claude replies in that channel only when someone @-mentions it. The setting is on by default, so a channel Claude was just added to replies without @-mentions from the start. Each channel has its own copy of the setting, and there is no workspace- or organization-wide version. To make Claude mention-only across many channels, turn it off in each one. All three places below change the same setting, so a change you make in one appears in the others. | Where | How | | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | In Slack | Ask Claude in the channel, for example "@Claude only respond in this channel when someone @-mentions you" or "@Claude respond to messages here even when nobody mentions you." Claude confirms the change. | | The channel's Configure page | Open the **Configure** link in the footer of any Claude reply in the channel and switch the **Respond automatically** toggle. See [Configure Claude for a channel](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). | | The Claude Tag admin page (admins only) | At [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag), on the **Slack** tab under **Claude Tag's access**, open the channel's scope and switch **Respond automatically** in its **Advanced** settings. | The setting covers the channel's messages, not DMs. To quiet a single thread instead of the whole channel, [ask Claude in that thread](#quiet-one-conversation). Until Claude has joined a channel, you see "@-mention Claude in this channel to activate" in place of the toggle on the Configure page and the admin page. You see the same line in a channel shared across workspaces that all belong to your Claude organization, because Claude runs there with your organization's default settings only. [Messages that never get a reply](#messages-that-never-get-a-reply) covers shared channels in more detail. ## Messages from other apps and bots Claude reads a message that another Slack app or bot posted as channel context, but a bot's message never gets the guaranteed reply that a person's @-mention gets. If the channel's [Respond automatically](#turn-automatic-replies-on-or-off) setting is off, or Claude has [stopped reading the channel](#when-claude-stops-reading-a-channel), a bot's `@Claude` doesn't wake it. In a channel where Claude is active, a bot's `@Claude` reaches Claude as a hand-off it may pick up or leave, and it may answer in a thread. Claude treats alerts an integration posts, messages a Slack workflow posts, and messages from any other bot the same way. Because Claude reads those messages, when a person asks about an alert a bot posted, Claude can answer from it. To have Claude act on what an integration posts, mention it in the channel or in the message's thread. For example, reply to a bot-posted alert with `@Claude triage this`. To have Claude check the channel on a schedule and post what needs attention, set up a [routine](/docs/claude-tag/users/proactivity). ## The name on a reply Claude doesn't post every reply under the same display name. The name shows which kind of work produced the reply, in two forms: * **Claude**, the name alone: the reply comes from Claude's ambient presence in the channel, including unprompted replies * **Claude** followed by a short description of the task in square brackets: the reply comes from a [working session](/docs/claude-tag/concepts/how-it-works) handling that task in its thread. The description changes with every task, so a channel might show something like `Claude [reviewing the launch checklist]`, `Claude [debugging a failing deploy]`, or `Claude [summarizing customer feedback]`. ## Make a channel quieter If Claude is replying to messages that weren't meant for it, turn that down from inside the channel. ### Quiet one conversation Tell Claude in the thread to respond only when mentioned. ```text wrap theme={null} @Claude only respond when I @-mention you ``` Claude stops following that thread, and the rest of the channel is unaffected. This is the fix when one busy thread is the noise. The [`!mute` command](/docs/claude-tag/users/commands#mute-or-unmute-a-thread) goes further and silences the thread entirely; `@Claude !unmute`, or an @-mention that carries a request, turns it back on. A 👎 reaction on one of Claude's replies also mutes the thread, as [Thumbs-down reactions and muting](/docs/claude-tag/users/commands#thumbs-down-reactions-and-muting) describes. ### Quiet the whole channel Turn the channel's [**Respond automatically**](#turn-automatic-replies-on-or-off) setting off, so Claude replies there only when @-mentioned. From Slack, ask Claude directly. ```text wrap theme={null} @Claude only respond in this channel when someone @-mentions you directly. ``` Claude confirms the change, which is channel-wide, not just for you. You can make the same change with the toggle on the channel's Configure page, and an admin can make it from the Claude Tag admin page. Threads Claude already joined keep forwarding replies, so quiet those individually with the in-thread line above. The [`!mute` command](/docs/claude-tag/users/commands#mute-or-unmute-a-thread) quiets one thread at a time and does nothing at a channel's top level. ### Remove Claude Tag from the channel When quieting isn't enough, end Claude's presence in the channel. ```text wrap theme={null} /remove @Claude ``` Claude can no longer read or post in that channel. Any member can run this unless your Slack admin restricts the command. Admins have further options, through full removal from the workspace, on [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access). ## When Claude stops reading a channel Claude counts the messages posted in a channel since it last posted there itself. When the count gets high enough, Claude stops reading that channel's messages, and unprompted replies stop with it. Claude doesn't announce this. To start Claude reading again, mention `@Claude` in the channel. A mention from a person reaches Claude even while Claude isn't reading the channel, and once Claude posts its reply, it reads the channel's messages again. If unprompted replies don't come back after Claude answers a mention, the channel's [**Respond automatically**](#turn-automatic-replies-on-or-off) setting is off. Answering a mention doesn't turn the setting on, and Claude changes the setting only when a channel member asks it to, so turn it back on in any of the three places listed in that section. ## Messages that never get a reply A few cases produce silence even when the message includes a mention: * **Editing a message to add the mention.** An edit doesn't trigger a response. Delete the message and send a new one with `@Claude` included. * **Channels with guest accounts.** By default, Claude is off in channels that include guests; your admin can turn it on per scope. Ask whoever runs your Claude plan, or send them [the guest access setting](/docs/claude-tag/admins/restrict-access#restrict-guest-channels). * **Channels shared across workspaces connected to different Claude organizations.** Every workspace where Claude runs is connected to a Claude organization, the account a company sets up for Claude. When a channel is shared across workspaces connected to different Claude organizations, Claude won't reply there and posts a refusal message instead. You can't tell from Slack how a workspace is connected; the refusal message itself is the signal. Use a channel that belongs to one workspace, or send Claude a DM. * **Slack Connect channels.** Channels shared with another company are always off. When the workspaces sharing a channel all belong to one Claude organization, Claude replies there, but with only your organization's default access and settings. The repositories, instructions, and memory set up for that channel or its workspaces don't apply, and Claude posts a notice in the thread explaining this from time to time. The guest check above still applies first where guest access is restricted. To confirm a channel's setting, check the **Respond automatically** toggle on its [Configure page](/docs/claude-tag/users/good-habits#configure-claude-for-a-channel). To confirm an instruction Claude saved, ask `@Claude what do you remember about responding in this channel?`, and see [What Claude Tag remembers](/docs/claude-tag/users/memory) for where instructions are stored and how to change them. ## Related resources * [Customize Claude Tag](/docs/claude-tag/admins/customize): the settings only an admin can change, if channel memory isn't enough * [Restrict where Claude Tag operates](/docs/claude-tag/admins/restrict-access): the admin-side controls, from guest channels to full removal # Manage your listing after publishing Source: https://claude.com/docs/connectors/building/after-publishing Update your MCP server, plugin, and directory listing after publication ## Update your MCP server An MCP server is a live API. To add, change, or remove tools, deploy the change to your server—no resubmission to Anthropic is required, and there is no scheduled re-review. Claude picks up the new tool surface on the next connection. ## Update your plugin Plugin updates are pushed via your GitHub repo. CI mirrors changes to the public marketplace and runs automated screening on each update. ## Update your listing Edit your description, categories, icon, and other listing metadata from the submissions dashboard at [Organization settings > Directory](https://claude.ai/admin-settings/directory/submissions) in Claude.ai. See [Managing your listing](/docs/connectors/building/managing-your-listing) for what you can edit directly and which changes require review. ## Slugs are permanent Your directory slug is fixed after publication. It determines your connector's permanent listing URL: ```text theme={null} https://claude.ai/directory/connectors/SLUG ``` Share this URL from your own documentation or a "Connect to Claude" button to send users directly to your listing. Display names can change via the dashboard; the URL slug cannot. ## Delist your connector To voluntarily remove your connector from the directory, email `mcp-review@anthropic.com`. # Authentication for connectors Source: https://claude.com/docs/connectors/building/authentication OAuth and authentication options for MCP servers in Claude Authentication is the most common source of partner questions. Claude's auth support differs in a few places from the generic MCP specification, so read this page even if you're already familiar with MCP auth. ## Supported authentication types Claude supports the following authentication types for remote MCP servers. The same infrastructure backs Claude.ai, Claude Desktop, Claude mobile, Claude Code, and Cowork. | Type | Description | Availability | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `oauth_dcr` | OAuth 2.0 with Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) | Supported out of the box | | `oauth_cimd` | OAuth 2.0 with [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents) | Supported out of the box | | `oauth_anthropic_creds` | OAuth 2.0 with [Anthropic-held client credentials](#anthropic-held-client-credentials) | Contact `mcp-review@anthropic.com` | | `custom_connection` | Custom URL or OAuth client credentials [entered at connection time](#credentials-entered-at-connection-time) | Contact `mcp-review@anthropic.com` | | `static_headers` | Fixed credential (API key or bearer token) entered by an organization administrator as a request header when adding the connector | Beta | | `none` | No authentication (authless server) | Supported. An optional partial-auth mode is experimental. | If your server URL varies per customer, read [Servers with per-customer URLs](#servers-with-per-customer-urls) before you pick a type. Static bearer tokens and API keys are supported in beta through request headers (`static_headers`). An organization administrator enters the credential once when adding the connector, and Claude sends it on every request. The credential is shared by the organization rather than pasted per user. Standard header names such as `authorization` and `x-api-key` work for every connector; Anthropic reviews and approves any other header name before administrators can save the connector. See [Authenticating with request headers](/docs/connectors/custom/remote-mcp#authenticating-with-request-headers) for what administrators see and how to document the expected header for them. Tokens or API keys passed in the connector URL (for example, `?token=`, `?apiKey=`, or `?userToken=` query parameters) are **not recommended**. A credential in a URL is a security vulnerability: URLs are routinely recorded in server logs, proxies, and browsing history, so a query-string credential is easy to leak. The MCP authorization specification explicitly [prohibits access tokens in the URI query string](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-requirements). Use OAuth or [request headers](/docs/connectors/custom/remote-mcp#authenticating-with-request-headers) instead. ## Servers with per-customer URLs The submission portal's **Connection** step asks how users reach your server. There are three choices: * **Universal URL**: every user connects to the same URL. * **Multiple URLs**: you list a fixed set of labeled URLs, such as one per region. Users pick one when they connect. * **URL pattern**: you give an anchored regular expression that every customer's URL must match, such as `^https://[a-z0-9-]+\.mcp\.example\.com/mcp$`. Each user enters their own URL when they connect, and Claude accepts it only if it matches. Keep the host part of a URL pattern lowercase, because Claude lowercases the host of the URL the user enters before checking it. Listings with **Multiple URLs** or a **URL pattern** take longer to review. You choose the URL option and the authentication type separately, but the URL option limits which authentication types work. Request headers (`static_headers`) are set up by the organization administrator who adds the connector and aren't covered by this table. | Type | Universal URL | Multiple URLs | URL pattern | | ----------------------- | ------------- | ------------- | ----------- | | `oauth_dcr` | Yes | Yes | Yes | | `oauth_cimd` | Yes | Yes | Yes | | `oauth_anthropic_creds` | Yes | Yes | No | | `custom_connection` | Yes | No | Yes | | `none` | Yes | Yes | Yes | Anthropic-held client credentials are tied to exact server URLs, and a URL pattern matches URLs Anthropic doesn't know in advance. Credentials entered at connection time can't be combined with **Multiple URLs**. For a URL pattern, use these in order of preference: 1. Client ID Metadata Document (CIMD). Every customer's authorization server must advertise both CIMD values listed in [DCR and CIMD details](#dcr-and-cimd-details). 2. [Dynamic Client Registration](#dcr-and-cimd-details) (DCR). Every customer's authorization server must expose a `registration_endpoint`. 3. [Credentials entered at connection time](#credentials-entered-at-connection-time), if your customers' authorization servers support neither. Each customer then has to create an OAuth client for Claude themselves. ## Anthropic-held client credentials A pure machine-to-machine `client_credentials` grant—where a server-to-server token is issued with no user in the loop—is **not supported**. Every connection requires user consent. `oauth_anthropic_creds` is the consent-gated alternative. The flow works like this: 1. You create an OAuth `client_id` and `client_secret` in your own authorization server and send them to Anthropic. 2. Anthropic stores those credentials securely and associates them with your directory entry. 3. When a user connects your server, they go through a standard OAuth consent screen. 4. After consent, Anthropic uses the stored client credentials to complete the token exchange on the user's behalf. This gives you a stable, registered OAuth client without requiring DCR or CIMD on your end, while keeping the user-consent step. Anthropic stores your credentials securely and uses them only for token exchange on behalf of consenting users; they are shared across the hosted Claude surfaces (Claude.ai web, Desktop, mobile, and Cowork). Claude Code runs its own OAuth flow on the user's machine and identifies itself with its own [Client ID Metadata Document](#callback-urls), so it does not use Anthropic-held credentials. Claude Managed Agents uses a separate credential set. Anthropic-held credentials are bound to the authorization server that issued them. If you migrate to a new authorization server, email `mcp-review@anthropic.com` with the new `client_id` and `client_secret` before cutting over. CIMD-based connectors don't have this constraint — a CIMD `client_id` is a self-hosted URL, so it works against any authorization server that fetches it. Anthropic-held credentials are also tied to exact server URLs. They can't be used with a URL pattern, where each customer enters their own server URL. See [Servers with per-customer URLs](#servers-with-per-customer-urls) for the alternatives. To use this flow, email `mcp-review@anthropic.com` with your `client_id` and secret. ## Credentials entered at connection time `custom_connection` (**Custom URL or credentials at connection time** in the submission portal) asks each customer for the OAuth client that Claude should use, instead of Claude registering one or Anthropic holding one. Each customer must be able to create an OAuth client in your product, which usually means an administrator sets up the connector for their organization. If your customers can't create OAuth clients, use CIMD or DCR instead. When a user adds your connector, Claude shows a form with these fields: * **Server URL**, if your listing uses a URL pattern. Claude accepts the URL only if it matches the pattern. * **OAuth client ID** and **OAuth client secret**. You choose which of the two to ask for, and whether each is required or optional. The form links to pages you supply: one for where the customer finds their server URL, and one for how they get the credentials. The credentials page must explain how a customer creates an OAuth client for Claude in your product and registers the redirect URI `https://claude.ai/api/mcp/auth_callback`. If a user leaves an optional client secret blank, Claude uses the client ID as a public client. If a user leaves an optional client ID blank, Claude falls back to the same order as any other listing: Anthropic-held credentials for that URL if Anthropic holds any, then CIMD, then DCR. See [DCR and CIMD details](#dcr-and-cimd-details). If you later stop asking for credentials, connections already made with user-entered credentials keep using them. An organization gets the new behavior only once no one in it still has the connector. The next person to add it starts fresh. To use this flow, email `mcp-review@anthropic.com` with which fields you need, whether each is required, and the page each one should link to. ## DCR and CIMD details If your authorization server does **not** expose a `registration_endpoint` (i.e., does not support DCR), you have several options: * Expose a `registration_endpoint` * Support CIMD instead. Claude selects CIMD only when your authorization server metadata advertises **both** `"client_id_metadata_document_supported": true` **and** `"none"` in `token_endpoint_auth_methods_supported` — the second is required because Claude's CIMD client authenticates as a public client at your token endpoint. If either is missing, Claude falls back to DCR. See [lazy authentication](/docs/connectors/building/lazy-authentication#identify-the-client-with-cimd) for a worked CIMD example. * Switch to `oauth_anthropic_creds`, if your listing doesn't use a URL pattern If your server URL varies per customer and DCR isn't available, CIMD is the recommended path. Every customer's authorization server must advertise both values above. Otherwise Claude falls back to DCR for that customer, which needs a `registration_endpoint`. For servers expecting high traffic from the directory, prefer **CIMD or `oauth_anthropic_creds` over DCR**. DCR causes Claude to register a new client on every fresh connection, which can result in very large numbers of registered clients on your authorization server. CIMD and Anthropic-held credentials avoid the registration call entirely. Claude includes a [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) `code_challenge` with `code_challenge_method=S256` on every authorization request, regardless of which registration mechanism it uses. Your authorization server must support S256 PKCE, and the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-code-protection) requires it to advertise `"code_challenge_methods_supported": ["S256"]` in its metadata so spec-compliant clients can verify support before starting the flow. To control which scopes Claude requests, include a `scope` parameter in the `WWW-Authenticate` header on your `401` response. If you don't, Claude requests the scopes your protected resource metadata advertises in `scopes_supported`. Claude also appends `offline_access` when your authorization server metadata lists it in `scopes_supported`, to obtain a refresh token. See [lazy authentication](/docs/connectors/building/lazy-authentication#return-401-not-a-tool-error) for the canonical `401` shape. ## Cross-host authorization servers A cross-host authorization server doesn't need anything special on its own. The `authorization_servers` field in your [protected resource metadata](https://www.rfc-editor.org/rfc/rfc9728) tells Claude where the authorization server is, and Claude resolves it regardless of which host it points at. The thing to get right is making sure Claude can find the protected resource metadata in the first place. **Always return a `401` with a `WWW-Authenticate` header** whose `resource_metadata` parameter points at your protected resource metadata document — the same handshake described in [Return 401, not a tool error](/docs/connectors/building/lazy-authentication#return-401-not-a-tool-error): ```http theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource" ``` The `401` status is required — Claude does not honor a `WWW-Authenticate` header on a `200` response — and the `resource_metadata` URL doesn't have to be on the MCP server's origin; it can be any HTTPS location that serves the JSON document. That's what makes this the most reliable path for hosting platforms that can't serve `/.well-known/*` at the root, such as Supabase Edge Functions, Cloudflare Workers without a `/.well-known/*` route, and Lambda function URLs that only route a path prefix. If your `401` doesn't include a `resource_metadata` pointer, Claude can still infer the metadata location by probing your MCP server's origin: `/.well-known/oauth-protected-resource/` first, then `/.well-known/oauth-protected-resource`. Treat this as a fallback — it only works when your platform serves `/.well-known/*` paths, and it adds round-trips to every connection. Whichever way Claude finds the document: * The protected resource metadata document's `resource` field must match your MCP server URL exactly as the user enters it in Claude, including any path component. * The metadata's `authorization_servers` field must list your authorization server's issuer URL. If you list more than one, Claude uses the first entry and does not fall back to later entries — list your primary issuer first. * Your authorization server must serve its own discovery metadata — [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) authorization server metadata or [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) — at its `/.well-known/` paths, and that host must also be reachable from Anthropic's [published egress range](https://platform.claude.com/docs/en/api/ip-addresses). Discovery requests to the authorization server come from the same IP range as requests to your MCP server, so a WAF in front of your identity provider can break the flow even when your MCP server is reachable. If your authorization server is Microsoft Entra ID, you must also register the MCP server URL as an Application ID URI on your Entra app registration, or the token request fails with `AADSTS9010010`. By default, Entra accepts that URL as an Application ID URI only when it's on a domain your tenant has verified (see [Microsoft's identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions)), so an MCP server on a platform hostname such as `*.azurewebsites.net` needs a custom domain first. See [the troubleshooting entry](/docs/connectors/building/troubleshooting#microsoft-entra-id-rejects-the-resource-value) for the fix. If you control both hosts, an alternative is to serve the MCP endpoint and the authorization server behind a single custom domain that can route both `/.well-known/*` and your MCP path. A common symptom of a discovery failure is that your MCP server receives the initial request but your authorization server sees no traffic at all. That happens when neither path works: there's no `WWW-Authenticate: Bearer resource_metadata=…` header on your `401`, and the well-known paths on your MCP server's origin return `404`. With no metadata to read, Claude never learns where your authorization server is, and the connection fails with "Couldn't reach the MCP server." See [troubleshooting](/docs/connectors/building/troubleshooting) for the full diagnostic flow. ## Callback URLs For the hosted Claude surfaces (Claude.ai web, Desktop, mobile, and Cowork), register the following redirect URI: ``` https://claude.ai/api/mcp/auth_callback ``` **Claude Code** is a native client and uses an RFC 8252 loopback redirect on an ephemeral port — for example: ``` http://localhost:3118/callback ``` The port varies per session. Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback` in its [Client ID Metadata Document](https://claude.ai/oauth/claude-code-client-metadata), so your authorization server must accept both with the port component ignored. [RFC 8252 section 7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) requires this for the IP-literal form (`127.0.0.1`); apply the same port-agnostic match to `localhost` so Claude Code works, even though RFC 8252 section 8.3 discourages `localhost`. See [lazy authentication](/docs/connectors/building/lazy-authentication) for implementation details. A Client ID Metadata Document can't prevent loopback impersonation on its own — any local process can bind a port and claim to be the legitimate client. The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#localhost-redirect-uri-risks) requires authorization servers to display the redirect URI hostname clearly on the consent screen and recommends an extra warning when the only registered redirect URIs are loopback addresses. ## Token refresh Claude refreshes tokens **reactively on a 401 response**, with a proactive refresh up to five minutes before the stored expiry. To avoid refresh failures: * Return RFC 6749-compliant error codes (`invalid_grant`, not `invalid_request` or a custom code) when a refresh token is no longer valid * Rotate refresh tokens for public-client connections. DCR and CIMD register Claude as a public client, and the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-theft) adopts OAuth 2.1's requirement to rotate or sender-constrain refresh tokens for public clients. If you rotate, return the new refresh token in the same response that invalidates the old one. Your `/token` endpoint must accept `Content-Type: application/x-www-form-urlencoded` per [RFC 6749 section 4.1.3](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3). Claude sends both the initial token exchange and refresh requests with this content type. Some web frameworks default to JSON-only body parsing—if your endpoint returns `415 Unsupported Media Type`, register a form-urlencoded body parser. Dynamic client registration (`/register`) uses `application/json` per [RFC 7591 section 3.1](https://www.rfc-editor.org/rfc/rfc7591#section-3.1), so don't assume the same parser works for both. ## Enterprise authentication Organizations using SSO can also connect their users to your server without an interactive OAuth consent step, using an identity assertion signed by their identity provider. See [Enterprise Managed Auth](./enterprise-managed-auth) for what your authorization server needs to support. Most directory connectors use a **single shared OAuth application per connector**. Enterprise customers connect to the same OAuth app as everyone else, and access is scoped by the user's own permissions on your service. For a listing that asks for [credentials entered at connection time](#credentials-entered-at-connection-time), each customer supplies its own OAuth client instead. Custom connectors are different: an admin can supply their own OAuth client credentials when adding the connector, which scopes the OAuth client to that organization. See [custom connectors](#custom-connectors). ## Custom connectors When a user adds a custom connector by URL, the OAuth Client Secret field is **optional**. Supply it only if your authorization server requires confidential-client authentication. Supplying your own pre-registered client ID (and secret, if your server requires one) as static client credentials is a good option when you want a stable OAuth client per organization: it avoids dynamic client registration entirely, and the credentials are scoped to the organization that entered them. For servers that authenticate with a fixed API key or token rather than OAuth, request header authentication (`static_headers`) is available in beta. See [Supported authentication types](#supported-authentication-types) above and [Authenticating with request headers](/docs/connectors/custom/remote-mcp#authenticating-with-request-headers) for what administrators see. ## Endpoint latency Claude waits up to **10 seconds** for a response from your OAuth discovery, registration, and token endpoints, and up to **30 seconds** for refresh token requests. If no response arrives within that window the flow is treated as a failure, even if your server eventually completes the request. Aim well under these limits; a token endpoint that takes several seconds to respond will produce intermittent connection failures for users. If your token endpoint depends on slow downstream calls, return the HTTP response headers and body without buffering behind upstream work, and check that any reverse proxy, API gateway, or WAF in front of the endpoint isn't holding the response. ## Network reference Anthropic's outbound traffic to your server originates from `160.79.104.0/21`. See the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses) if you need to allowlist Anthropic for conditional access or firewall rules. # Directory connectors vs custom connectors Source: https://claude.com/docs/connectors/building/directory-vs-custom Understand the difference between directory-listed and custom connectors Directory connectors and custom connectors run on the **same MCP infrastructure**. The runtime, transport, authentication, and tool-calling code paths are identical. The difference is review, discoverability, and distribution. | | Directory connector | Custom connector | | ----------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- | | **Runtime** | Same | Same | | **Anthropic review** | Yes | No | | **In-product discovery** | Browse, search, Suggested Connectors | None | | **Distribution** | [Directory link](#share-an-install-link) | [Install link](#share-an-install-link) or manual URL entry | | **Anthropic-held client credentials** | Available | Not available | | **[External link](/docs/connectors/building/mcp-apps/external-links) confirmation** | Can allowlist destinations to skip the modal | Always shows the modal | | **Appears as** | Named card with logo | "Custom" | For what directory and custom connectors look like to a Claude user, including the Verified and Community labels, see [connector verification](/docs/connectors/verification). ## Share an install link Both directory and custom connectors have a URL you can share from your own documentation, a "Connect to Claude" button, or an onboarding email. ### Directory connectors After publication, your connector has a permanent listing URL based on its slug: ```text theme={null} https://claude.ai/directory/connectors/SLUG ``` For example, `https://claude.ai/directory/connectors/dovetail` opens the Dovetail listing with its description, screenshots, and a **Connect** button. You receive your slug when your submission is approved, and it [cannot change afterward](/docs/connectors/building/after-publishing#slugs-are-permanent). ### Custom connectors For a connector that is not in the directory, link to the **Add custom connector** dialog with the name and URL prefilled: ```text theme={null} https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=NAME&connectorUrl=ENCODED_URL ``` | Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------------------- | | `modal` | Must be `add-custom-connector`. | | `connectorName` | Display name shown to the user. | | `connectorUrl` | Your MCP server URL, [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). | For example, an install link for a server at `https://mcp.example.com/` looks like this: ```text theme={null} https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Example&connectorUrl=https%3A%2F%2Fmcp.example.com%2F ``` When a user follows the link, claude.ai opens the dialog with the name and URL prefilled and shows a notice that the values came from an external link. The user reviews the values and confirms before anything is added. If the user is signed out, they are prompted to sign in first and then land on the prefilled dialog. Install links only prefill the form. They do not bypass review by the user, and they do not grant your server any permissions the user has not confirmed. Organization administrators can use the same parameters on the admin path to prefill the org-wide connector dialog: ```text theme={null} https://claude.ai/admin-settings/connectors?modal=add-custom-connector&connectorName=NAME&connectorUrl=ENCODED_URL ``` ## Suggested Connectors Directory connectors are eligible for **Suggested Connectors**—Claude can recommend your connector in-chat when it's relevant to the user's task. Custom connectors are never suggested. Every directory entry is automatically eligible; there is no separate opt-in. ## Use both: directory plus elevated custom A supported pattern is to list a connector in the directory with safe, broadly-applicable defaults, **and** provide enterprise customers a separate URL to add as a custom connector with elevated permissions or tenant-specific configuration. Document both paths in your own product docs. ## Per-tenant URLs If your server URL varies per tenant (for example, `{tenant}.mcp.example.com`), submit one directory listing with a URL pattern. Each user enters their own URL when they connect. See [Servers with per-customer URLs](/docs/connectors/building/authentication#servers-with-per-customer-urls) for how this choice limits your authentication options. ## What the directory is not The Anthropic Directory is independent of the open [MCP Registry](https://registry.modelcontextprotocol.io) and the `modelcontextprotocol/servers` GitHub repository. Publishing to those does **not** surface your server in Claude. Submit through the [directory submission form](/docs/connectors/building/submission) to appear in Claude products. # Enterprise Managed Auth for connectors Source: https://claude.com/docs/connectors/building/enterprise-managed-auth Accept identity assertions from enterprise SSO so users connect to your MCP server without a separate OAuth consent step. Enterprise Managed Auth is available on Claude Team and Enterprise plans. MCP server developers and identity provider vendors can [register interest](https://docs.google.com/forms/d/e/1FAIpQLSf1goHGNDVFK7rncYuh6wnRpWSy7eGOcgL1i8uw3oyKFO9UUA/viewform) in supporting this flow. Enterprise Managed Auth (EMA) lets a user connect to your MCP server silently, using the single sign-on session they already have with their organization. Instead of showing each user an OAuth consent screen, Claude presents your authorization server with an **identity assertion**: a signed JSON Web Token (JWT), issued by the customer's identity provider, that vouches for the user's identity. Your authorization server validates the assertion and returns an access token in a single back-channel request. There is no browser redirect and no per-connector consent page. From the user's point of view, the connector is simply available as soon as their administrator enables it. This flow is defined by the [MCP enterprise managed authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) and is built on the standard [JWT bearer authorization grant (RFC 7523)](https://datatracker.ietf.org/doc/html/rfc7523). The assertion profile follows the [Identity Assertion JWT Authorization Grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/). This page is for connector developers who need their authorization server to accept Enterprise Managed Auth. Identity provider setup and Claude admin console configuration are handled by the customer's administrator. ## How it works When a user whose organization has Enterprise Managed Auth configured invokes your connector, Claude obtains a signed identity assertion for that user and exchanges it directly at your token endpoint for an access token. The user never sees a browser redirect or a consent screen, and your MCP server receives the same kind of bearer token it would after the interactive OAuth flow. ```mermaid theme={null} sequenceDiagram autonumber participant Claude participant AS as Your authorization server participant MCP as Your MCP server Note over Claude: User is signed in to Claude through their organization's SSO Claude->>AS: POST /token (grant_type=jwt-bearer, assertion=signed JWT) AS->>AS: Fetch issuer JWKS and verify signature AS->>AS: Validate iss, aud, exp, sub, and client_id AS-->>Claude: access_token Claude->>MCP: Tool call with Bearer access_token MCP-->>Claude: Tool result ``` Two parties are involved in this exchange: the customer's identity provider signs the assertion, and your authorization server verifies it and issues the access token. Both roles are often served by commercial identity platforms, so the distinction here is about which tenant plays which role rather than about product type. The identity provider publishes its signing keys as a JSON Web Key Set, and your authorization server fetches that key set to verify each assertion. ## With lazy authentication Enterprise Managed Auth also works with [lazy authentication](./lazy-authentication). When your server returns `401 Unauthorized` for a protected tool call, Claude normally shows the inline **Connect** card and runs the interactive OAuth flow. If the user's organization has Enterprise Managed Auth configured for your connector, Claude runs the silent JWT bearer exchange instead and retries the tool call without showing a prompt. Your MCP server returns the same `401` with a `WWW-Authenticate` header as described in the [lazy authentication guide](./lazy-authentication#return-401-not-a-tool-error). Your authorization server must still meet the [requirements below](#authorization-server-requirements). A fully authless server never returns `401`, so there is no point at which Claude can exchange an assertion. Enterprise Managed Auth does not apply to authless servers. ## Prerequisites Before adding Enterprise Managed Auth, make sure the following are already in place. * Your MCP server implements [MCP authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization), including Protected Resource Metadata (PRM) discovery, and follows the [MCP security best practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices). See our [authentication guide](./authentication) for Claude-specific requirements. * Your authorization server registers Claude using either [Anthropic-held client credentials](./authentication#anthropic-held-client-credentials) or a [Client ID Metadata Document](./authentication#dcr-and-cimd-details). Dynamic Client Registration (DCR) is not supported with Enterprise Managed Auth. The identity provider stamps a fixed `client_id` into every assertion it issues, so your authorization server must already recognize that client before the first assertion arrives. A client created on the fly through DCR cannot satisfy this requirement because its identifier will never match the value in the assertion. ## Authorization server requirements This section is for the authorization server operator. If your MCP server relies on a hosted identity platform, there is typically no code to write. Confirm that the platform supports the JWT bearer authorization grant and enable it for your tenant. If you run your own authorization server, the steps below describe what it needs to support. Support for this flow varies by product. The underlying capability is the JWT bearer authorization grant ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)), which lets an authorization server exchange a signed JWT for an access token. Some commercial authorization servers and identity platforms support it today and others do not yet, so the first step is to confirm that yours does and that the customer's identity provider can be registered as a trusted issuer. Your authorization server must accept `urn:ietf:params:oauth:grant-type:jwt-bearer` at its token endpoint and advertise it in the `grant_types_supported` array of its [authorization server metadata (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414): ```json theme={null} { "issuer": "https://auth.example.com", "token_endpoint": "https://auth.example.com/token", "grant_types_supported": [ "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer" ] } ``` Claude reads this metadata to discover whether your server supports Enterprise Managed Auth. The grant type must be listed here for the feature to be offered to the customer, even if your token endpoint would already accept it silently. For each customer, your authorization server needs to trust that customer's identity provider as a JWT issuer. Your authorization server fetches the identity provider's JSON Web Key Set and uses it to verify the signature on every incoming assertion. Your authorization server is responsible for maintaining an explicit allowlist of trusted issuer URLs per tenant rather than accepting any well-formed JWT. An assertion whose `iss` is not on the tenant's allowlist must be rejected with `invalid_grant`, even if the signature is valid. Never accept an identity assertion without full validation. As with all OAuth token handling, your authorization server must verify the signature, issuer, audience, expiry, and subject on every request. Use the JWT validation built into your authorization server product. If you need to inspect assertions in your own code, use the validation library or token introspection endpoint provided by your authorization server vendor rather than writing custom verification logic. Claude sends a form-encoded `POST` to your authorization server's token endpoint: ```http theme={null} POST /token HTTP/1.1 Host: auth.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer &assertion=eyJhbGciOi... &client_id=your-registered-client-id &scope=openid profile &resource=https://mcp.example.com ``` The `assertion` parameter carries the signed JWT. The `client_id` is the value Claude is registered under at your authorization server. Claude also includes the `resource` parameter ([Resource Indicators, RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)) set to your MCP server URL whenever the customer's identity provider supports forwarding it. Some identity provider configurations cannot pass a resource indicator through, so your authorization server should accept the request whether or not `resource` is present and use it for audience binding when it is. Your authorization server validates the assertion according to the [JWT bearer token processing rules (RFC 7523 section 3)](https://datatracker.ietf.org/doc/html/rfc7523#section-3) and returns a standard OAuth token response. Claude then presents the returned access token as a `Bearer` credential on calls to your MCP server, exactly as it does after the interactive flow. The access token lifetime is set by your authorization server, and the assertion lifetime is set by the customer's identity provider. Anthropic does not control either value. ## Access token lifetime Issue access tokens with whatever lifetime your security policy calls for. A short lifetime, such as one hour, does not force users to repeat single sign-on each time a token expires. When a user signs in to Claude through their organization's SSO, Claude obtains a long-lived refresh token from the identity provider. Claude uses that refresh token to request a fresh identity assertion from the identity provider whenever it needs one, without any user interaction. Claude then exchanges the new assertion at your token endpoint for a new access token. From the user's point of view, the connection stays active for as long as the identity provider's refresh token remains valid. The refresh token is issued by the customer's identity provider. Treat it as long-lived today. Identity provider administrators will be able to apply their own lifetime policy in the future. ## Testing your implementation End-to-end testing requires a Claude organization with Enterprise Managed Auth enabled and an identity provider tenant configured to issue assertions for your authorization server's audience. If your identity provider is Okta, refer to Okta's [Cross App Access participation guide](https://support.okta.com/help/s/article/claude-enterprise-managed-auth-with-okta-cross-app-access-xaa-beta-participation-guide?language=en_US) and configure your organization to be able to test your MCP's XAA implementation. ### Testing with the cross-app access playground [Okta's cross-app access playground](https://xaa.dev) lets you exercise the flow without a Claude organization. This is useful while you develop, and when your organization's single sign-on is not on a supported identity provider. On the playground you can: * Walk the full four-step flow end to end against a sandbox IdP, with every token shown decoded * Point it at your own MCP server or REST API to check resource metadata discovery, the `WWW-Authenticate` hint on `401` responses, and token validation * Point it at your own authorization server to check that it accepts an identity assertion over the JWT bearer grant, mints a scoped access token, and serves its metadata for discovery * Bring your own OIDC or SAML identity provider in place of the sandbox one * Re-run a single failed step and inspect service configurations, discovery documents, and a live event log ## Admin settings in your product In your product's admin settings, give each customer's administrator a control that turns Enterprise Managed Auth on or off for their organization and a field for their identity provider's issuer URL. When the administrator saves, add that URL to the organization's allowlist of trusted issuers, as described in [Authorization server requirements](#authorization-server-requirements). ## Provide setup documentation You can publish documentation that walks an enterprise administrator through enabling Enterprise Managed Auth for your product and add its URL to [your directory listing](./managing-your-listing). Claude shows the link in the Claude admin console when an administrator sets up Enterprise Managed Auth for your connector. ## Okta Integration Network apps If your product has an app in the Okta Integration Network, work with Okta to enable Cross App Access (XAA) for that app. Until that app supports Cross App Access, customers who use Okta need to create a custom app in Okta for your product before they can set up Enterprise Managed Auth. ## Related resources Baseline OAuth requirements your server must already meet. Defer OAuth until a protected tool is actually invoked. Verify your connector works end to end in Claude. Diagnose common authentication and connection issues. # Building custom connectors Source: https://claude.com/docs/connectors/building/index Build your own MCP servers to connect Claude to your tools and data ## Getting started **Authentication is the most common stumbling block.** Before you build, read the [authentication reference](/docs/connectors/building/authentication)—Claude's auth support differs from the generic MCP spec in a few important ways. Not sure whether to build an MCP server, a plugin, or both? See [what to build](/docs/connectors/building/what-to-build). **Build with Claude.** Install the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) in Claude Code—it walks you through building, testing, and packaging an MCP server interactively, using these docs as its reference. ### Key resources * **SDK Examples**: [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) and [Python](https://github.com/modelcontextprotocol/python-sdk) SDKs contain server implementation examples * **Protocol Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io) * **Hosting Solutions**: Platforms like Cloudflare offer remote MCP server hosting with autoscaling and OAuth management * **Auth Specifications**: Review the [authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization) with emphasis on third-party service flows ## Transport & authentication ### Supported transports Claude supports both Streamable HTTP and the legacy HTTP+SSE transport. The legacy HTTP+SSE transport is being deprecated in favor of Streamable HTTP. ### Authentication features * Supports the [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization), [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), and [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) auth specifications * Dynamic Client Registration (DCR) enabled * OAuth callback: `https://claude.ai/api/mcp/auth_callback` (hosted surfaces); loopback redirect for Claude Code — see [callback URLs](/docs/connectors/building/authentication#callback-urls) * Token refresh and expiry support * Custom credentials for non-DCR servers ## Protocol features ### Supported * [Tools](https://modelcontextprotocol.io/specification/latest/server/tools), [prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), and [resources](https://modelcontextprotocol.io/specification/latest/server/resources) * [Text](https://modelcontextprotocol.io/specification/latest/schema#textcontent) and [image-based](https://modelcontextprotocol.io/specification/latest/server/tools#image-content) tool results * [Text](https://modelcontextprotocol.io/specification/latest/schema#textresourcecontents) and [binary](https://modelcontextprotocol.io/specification/latest/schema#blobresourcecontents) resources ### Not yet supported * Resource subscriptions * Sampling * Advanced/draft capabilities ## Technical specifications | Constraint | Limit | | -------------------------------------- | -------------------------------------------------------- | | Claude.ai/Desktop max tool result size | \~150,000 characters | | Claude Code max tool result size | 25,000 tokens (configurable via `MAX_MCP_OUTPUT_TOKENS`) | | Claude Code timeout | Configurable via `MCP_TOOL_TIMEOUT` | | Claude.ai/Desktop tool call timeout | 240 seconds (4 minutes) per tool call | | Transport protocol | Streamable HTTP (legacy HTTP+SSE being deprecated) | ## Testing your server 1. Add directly to Claude via **Customize > Connectors** 2. Use the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector) to validate auth flows 3. Add to Claude Code with `claude mcp add` and check `/mcp` for status. See the [Claude Code MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart). ## Related topics Understanding the Model Context Protocol. Review requirements and submit your connector. Connect and debug your server with the Claude Code CLI. # Lazy authentication for MCP servers Source: https://claude.com/docs/connectors/building/lazy-authentication Let users call public tools immediately and defer OAuth until a protected tool is actually invoked. Not every tool on an MCP server needs the user's identity. A product catalog can be browsed anonymously; an order history cannot. **Lazy authentication** (sometimes called *mixed auth*) lets a single server expose both: unauthenticated clients can connect, list tools, and call public ones, and the server only challenges for credentials when a protected tool is invoked. The challenge follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization). In Claude, the challenge surfaces as an inline **Connect** card in the conversation. The user authenticates in a popup, Claude retries the same tool call automatically with the new token, and the turn continues — no context is lost. If the user's organization has [Enterprise Managed Auth](/docs/connectors/building/enterprise-managed-auth) configured for your connector, the `401` triggers a silent token exchange instead of the **Connect** card. The tool call is retried automatically and the user sees no prompt. The examples below are drawn from a single-file Express app using `@modelcontextprotocol/sdk` over Streamable HTTP. ## Return 401, not a tool error The only detail that matters is **how** the server refuses an unauthenticated call to a protected tool. It must fail the **HTTP request** with `401 Unauthorized` and a [`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc6750#section-3) header: ```http theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp", scope="orders:read" {"error":"invalid_token","error_description":"Authentication required for this tool"} ``` The body is advisory; the `401` status and `WWW-Authenticate` header carry the protocol signal. The optional `scope` parameter tells Claude which scopes to request during authorization — include the minimum your protected tools need. If you omit it, Claude requests the scopes your protected resource metadata advertises in `scopes_supported` (plus `offline_access` if your authorization server metadata lists it), which can produce an over-broad consent prompt. It must **not** return a successful HTTP response wrapping a tool error: ```http theme={null} HTTP/1.1 200 OK {"jsonrpc":"2.0","result":{"isError":true,"content":[{"type":"text","text":"Please sign in"}]},"id":1} ``` A `200` with `isError: true` is an application-level tool failure. Claude passes the error text to the model as the tool result and moves on — there is no auth prompt. Only a transport-level `401` causes Claude to pause the call, run the OAuth flow, and retry. A `403` triggers re-authentication only when accompanied by `WWW-Authenticate: Bearer error="insufficient_scope"` for scope step-up; any other `403` is surfaced as a terminal error. If users are seeing "please sign in" text in the chat instead of a **Connect** button, the server is returning the wrong one. The `resource_metadata` parameter in the `WWW-Authenticate` header points at the server's [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource Metadata (PRM), which in turn names the authorization server. That chain is how Claude discovers where to send the user without any of it being hard-coded in the client. ## Gate at the HTTP layer Because the refusal must be an HTTP status, the check has to happen **before** the JSON-RPC message reaches the MCP SDK. Once a tool handler is running, its return value is already destined to be wrapped in a `200` response. The sample inspects the parsed JSON-RPC body in the Express handler and short-circuits if the request is a `tools/call` for a protected tool and no valid bearer is present: ```ts src/index.ts theme={null} const PROTECTED_TOOLS = new Set(["get_my_orders"]); function callsProtectedTool(body: unknown): boolean { const messages = Array.isArray(body) ? body : [body]; for (const msg of messages) { if ( msg && typeof msg === "object" && (msg as { method?: unknown }).method === "tools/call" ) { const name = (msg as { params?: { name?: unknown } }).params?.name; if (typeof name === "string" && PROTECTED_TOOLS.has(name)) { return true; } } } return false; } const WWW_AUTHENTICATE = `Bearer error="invalid_token", ` + `error_description="Authentication required for this tool", ` + `resource_metadata="${BASE_URL}/.well-known/oauth-protected-resource/mcp", ` + `scope="orders:read"`; async function handleMcpPost(req: Request, res: Response): Promise { const token = extractBearer(req); const authed = isTokenValid(token); // Lazy-auth gate: fail with 401 BEFORE the MCP layer sees the request. // initialize, tools/list, and public tool calls fall through. if (!authed && callsProtectedTool(req.body)) { res .status(401) .set("WWW-Authenticate", WWW_AUTHENTICATE) .json({ error: "invalid_token", error_description: "Authentication required for this tool", }); return; } // Otherwise: stateless Streamable HTTP handling. const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true, }); const mcp = buildMcpServer(authed ? "demo-user" : null); await mcp.connect(transport); await transport.handleRequest(req, res, req.body); } app.post("/mcp", (req, res) => { handleMcpPost(req, res).catch((err) => { console.error("mcp request error", err); if (!res.headersSent) { res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null, }); } }); }); ``` `initialize`, `tools/list`, and calls to `list_products` never hit the gate, so the connector is fully usable before sign-in. When the user already has a valid token, every request — public or protected — carries it and the gate is a no-op. The same pattern covers **scope upgrades**: if the bearer is valid but lacks a required scope, return `403 Forbidden` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"` and Claude prompts the user to re-consent. See [Step-up authorization](#step-up-authorization) below for what scopes Claude requests on re-consent and how the challenge is cached. ## Serve the discovery documents After a 401, Claude fetches the URL from `resource_metadata` to learn which authorization server to use: ```ts src/index.ts theme={null} function protectedResourceMetadata() { return { resource: `${BASE_URL}/mcp`, authorization_servers: [BASE_URL], bearer_methods_supported: ["header"], }; } app.get("/.well-known/oauth-protected-resource", (_req, res) => { res.json(protectedResourceMetadata()); }); // Path-suffixed variant per RFC 9728 section 3.1 — clients try this first when // the resource URL has a path component (/mcp). app.get("/.well-known/oauth-protected-resource/mcp", (_req, res) => { res.json(protectedResourceMetadata()); }); ``` Claude then fetches the authorization server's [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) metadata to find the `/authorize` and `/token` endpoints. ## OAuth discovery caching Claude caches the discovery documents — your protected resource metadata and the authorization-server metadata it points to — **globally, keyed by URL**, with a staleness window of about five minutes by default. All Claude users connecting to the same server URL share a single cache entry, and distinct server URLs (for example, staging versus production) cache independently. The refresh is lazy and best-effort: after you change `scopes_supported` (or any other discovery field), the new value is picked up by the first authorization that successfully re-runs discovery once the staleness window has elapsed, then propagates to everyone. There is no per-user expiry to wait for. If a refresh fails, Claude serves the stale entry and tries again on a later request, so an unreachable discovery endpoint doesn't immediately break existing connections — it just delays the change. ## Step-up authorization The scope-upgrade case at the end of [Gate at the HTTP layer](#gate-at-the-http-layer) is the MCP specification's [Step-Up Authorization Flow](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#step-up-authorization-flow). When the bearer token is valid but missing a scope the requested tool needs, return `403 Forbidden` with a [`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1) challenge: ```http theme={null} HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:write" ``` Claude prompts the user to re-authorize and, on consent, retries the same tool call with the new token. **Which scopes Claude requests on re-authorization.** Claude unions the scopes named in your `403` challenge with the scope your server advertises during discovery (the `scope` parameter on your initial `401` `WWW-Authenticate` response, or your protected resource metadata's `scopes_supported` if you don't send one). Scopes the user picked up in an earlier step-up aren't reliably carried forward into the next one. To make sure the user keeps a permission they still need, follow the [MCP spec's recommended approach](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors) and include it in the `403` `scope` value alongside the newly required scopes — don't return only the single missing scope and depend on the client to remember the rest. If your `403` carries `error="insufficient_scope"` but **omits the `scope` parameter**, Claude still recognizes step-up and runs its normal scope selection: the discovery-time `WWW-Authenticate` scope first, then your protected resource metadata's `scopes_supported`, then the authorization server metadata's `scopes_supported`. The `scope` value from your `403` is cached **per user, per server** for up to fifteen minutes and consumed by the next re-authorization that user starts against your server. The cache holds the most recent challenge — a new `403` overwrites the previous one — and is cleared once it's used. Combined with the [global discovery cache](#oauth-discovery-caching) above, a newly-added scope is available to step-up shortly after the discovery cache refreshes, typically within about five minutes of deploying the updated metadata. ## Identify the client with CIMD The sample does **not** implement Dynamic Client Registration. Instead it advertises support for **Client ID Metadata Documents** ([draft-ietf-oauth-client-id-metadata-document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)) in its authorization-server metadata: ```ts src/index.ts theme={null} function authorizationServerMetadata() { return { issuer: BASE_URL, authorization_endpoint: `${BASE_URL}/authorize`, token_endpoint: `${BASE_URL}/token`, scopes_supported: ["profile", "orders:read"], response_types_supported: ["code"], grant_types_supported: ["authorization_code", "refresh_token"], token_endpoint_auth_methods_supported: ["none"], code_challenge_methods_supported: ["S256"], client_id_metadata_document_supported: true, }; } ``` With CIMD the `client_id` is itself an HTTPS URL that dereferences to the client's OAuth registration metadata. There is no per-client database and no `POST /register` round-trip: at `/authorize`, the server fetches the `client_id` URL, verifies the document is self-referential (its `client_id` field equals the URL it was served from), and checks the requested `redirect_uri` against the document's `redirect_uris`. Because the document is self-asserted, the consent screen must display the **host of the `client_id` URL** (not the `client_name` field) as the relying party, and the listed `redirect_uris` should be required to be same-origin with the `client_id` URL. Claude selects CIMD only when the authorization-server metadata advertises **both** `client_id_metadata_document_supported: true` **and** `"none"` in `token_endpoint_auth_methods_supported`. The second is required because Claude's CIMD client authenticates as a public client (`token_endpoint_auth_method: "none"`), so the token endpoint must accept [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)-only requests without a client secret. If either property is missing, Claude falls back to looking for a `registration_endpoint`. For native clients, compare loopback IP `redirect_uri` values (`http://127.0.0.1/…`, `http://[::1]/…`) with the **port ignored**, per [RFC 8252 section 7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) — native apps bind an ephemeral port at runtime. RFC 8252 section 8.3 discourages `http://localhost/…`, but Claude Code declares it in its CIMD and binds an ephemeral port at runtime, so apply the same port-agnostic match to `localhost` for compatibility. The sample's `redirectUriAllowed()` helper shows the comparison. ## Try it ```bash theme={null} npm install npm run build npm start ``` The server listens on `http://localhost:3000/mcp`. ```bash theme={null} curl -s http://localhost:3000/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_products","arguments":{}}}' ``` ```bash theme={null} curl -si http://localhost:3000/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_my_orders","arguments":{}}}' ``` Note the `WWW-Authenticate` header in the response. Claude reaches custom connectors from Anthropic's infrastructure, so `localhost` is not reachable directly. Expose the server over a public HTTPS tunnel (for example, `cloudflared tunnel --url http://localhost:3000` or `ngrok http 3000`), then in **Customize > Connectors**, select **Add custom connector** and enter the tunnel's `/mcp` URL. See [Testing your connector](/docs/connectors/building/testing) for details. Ask Claude to list products (no prompt), then ask for your orders — the inline **Connect** card appears, and after authenticating the same call completes. The sample's README includes a longer `curl` walkthrough that drives the stub `/authorize` and `/token` endpoints directly. ## Adapting to your server * List your protected tools in `PROTECTED_TOOLS`. * Replace `isTokenValid()` with real verification: JWT signature, `iss` matches your authorization server, `aud` equals the `resource` value you advertise in the PRM, and `exp`; or [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) token introspection against your IdP. * Point `authorization_servers` in the PRM at your real issuer and delete the stub `/authorize` and `/token` handlers. Keep `client_id_metadata_document_supported: true` in your issuer's metadata if you want registration-free onboarding for Claude clients. * If your server uses stateful Streamable HTTP sessions, the gate still belongs in the `POST /mcp` handler, before `transport.handleRequest`. # Managing your directory listing Source: https://claude.com/docs/connectors/building/managing-your-listing Track submissions, monitor server health and usage metrics, and edit your Connectors Directory listing Organizations that submit to the [Connectors Directory](/docs/connectors/directory) get a submissions dashboard in Claude.ai at [Organization settings > Directory](https://claude.ai/admin-settings/directory/submissions). Use it to track submissions through review, monitor your published server's health and usage, and edit your listing. The dashboard covers directory-listed remote MCP servers only. Custom connectors and local servers (desktop extensions) don't appear here, and the dashboard shows only your own organization's submissions. ## Access the dashboard The dashboard is part of your organization's admin settings, so you need: * **A Team or Enterprise organization** * **Directory management access.** By default, only organization Owners and Primary owners have it. On Enterprise, an Owner can delegate access through a custom role with the **Directory** or **Libraries** permission; see [Before you start](/docs/connectors/building/submission#before-you-start) for the steps. Team plans don't have custom roles, so on Team this stays with Owners. The same access covers everything on this page: viewing submissions, metrics, and reviewer feedback, and editing and submitting listings. ## Track submission status The dashboard lists each of your organization's submissions with its current status. Open a submission to see its full details and any reviewer feedback. When reviewers request changes, their feedback appears on the submission's detail page; address it and resubmit from the same page. ## Server health and usage metrics Metrics are in beta. They're computed daily from directory usage and can lag by up to 24 hours. Time windows with fewer than 5 calls, per-tool rows with fewer than 5 calls, and per-product rows with fewer than 50 calls are omitted. Once your server is published, its detail page shows health and usage data. ### What the metrics cover All of the metrics on this page measure traffic from Claude: Claude.ai, Claude Desktop, Claude Code, and other Claude surfaces. Connections that people make to your server from other MCP clients, and local servers that run on a user's own machine, aren't visible to Anthropic and aren't counted. Your own server logs can therefore show activity that this page doesn't. Tool call totals, error rates, and latency are measured at Anthropic's HTTP connector proxy. Tool call users and directory rank are measured from the MCP message stream, which covers both the HTTP and legacy WebSocket transports. If users reach your server only over the legacy WebSocket transport, you'll still see tool call users and a directory rank, but no tool call totals, error rates, or latency data. ### Health The health badge summarizes your server's recent reliability: | Status | Meaning | | --------------- | ------------------------------------------------------------------------------------------------------------ | | **Healthy** | The 30-day disconnect rate is at or below 5% | | **Degraded** | The 30-day disconnect rate is above 5% | | **Collecting…** | The server is published, but there isn't enough data yet to compute a disconnect rate (metrics update daily) | | **Not live** | The server isn't published yet; health appears after publication | The disconnect rate is measured against every distinct Claude account that sent your server any MCP message in the last 30 days, including connection attempts that never completed: it is the share of those accounts that chose to disconnect your connector during those 30 days. ### Topline metrics * **Directory rank**: your position among published directory servers, highest first, ranked by the number of distinct Claude accounts that sent your server any MCP message in the last 30 days. Every MCP message counts toward the ranking, including `initialize` and `tools/list`, and it includes accounts whose connection attempt never finished authenticating — a broader population than the Tool call users card below. A "Trending" tag marks servers in the top 10 by recent growth in that same message-based count. * **Tool call users (30d)**: the number of distinct Claude accounts that made at least one tool call (`tools/call`) to your server in the last 30 days. Accounts that only attempted to connect, or connected and browsed your tools without calling one, aren't counted. This card was previously labeled "Active users (30d)" and counted every MCP message, including handshakes from connection attempts that never completed; the renamed metric counts only accounts that actually used your tools, so it is usually much smaller than the number the old card showed. * **Tool calls (30d)**: the number of `tools/call` requests Anthropic received for your server in the last 30 days. Protocol messages such as `initialize` and `tools/list` aren't counted here. This is a count of requests, not of users, so retries are included, as are requests that were turned away for authentication problems. * **Error rate (30d)**: of the tool calls above, the fraction that either failed at the request level (for example, with a 5xx response or a timeout) or returned an MCP tool result with `isError: true`. Tool-call requests that were turned away for authentication problems aren't counted as errors, but they are included in the total number of tool calls that the rate is measured against. Shown with the most common error types. ### Error breakdown A table breaks errors out over 1-day, 7-day, and 30-day windows: total calls, overall error rate, tool versus request error rates, HTTP 4xx and 5xx rates, and the top error types in each window. ### Usage by product A per-product table shows 7-day calls, error rate, and p50/p95/p99 latency, broken down by the Claude product the calls came from, such as Claude.ai, Claude Desktop, Claude Code, and Cowork. Only a fixed set of Claude surfaces is shown, and Anthropic's own internal monitoring traffic is excluded. Because this table covers a shorter window, drops low-volume rows, shows only a fixed set of Claude surfaces, and excludes internal monitoring traffic, its call counts won't add up to the 30-day tool call total above. That's expected. A high error rate on a single product may reflect a client-side issue on Anthropic's end rather than a problem with your server. ### Usage by tool A per-tool table shows 7-day calls, the overall error rate, and the tool-result error rate for your top 15 tools by call volume. ## Edit your listing Open your submission's detail page to edit the listing. You can change directly: * **Listing metadata**: tagline, description, categories, documentation and privacy policy links, support contact, and icon * **Company details**: company name and website * **Display name**: editable, but changing the name of a published server affects existing users and requires re-review Save your edits as you go, then submit them for review. Submitted changes show as pending until a reviewer approves them, and you can discard pending changes before they're approved. The URL slug is locked: it's permanent after publication, since it determines your listing URL. For other edits or escalations, email `mcp-review@anthropic.com`. # Model Context Protocol (MCP) Source: https://claude.com/docs/connectors/building/mcp Understanding the open standard powering Claude's connectors The Model Context Protocol (MCP) is an open standard created by Anthropic for AI applications to connect with tools and data sources. ## What is MCP? MCP provides a standardized way for AI assistants like Claude to: * Connect to external tools and services * Access data from various sources * Perform actions on behalf of users * Maintain security and user control ## How MCP works ### Local vs remote servers | Type | Description | Use Case | | -------------- | ---------------------- | --------------------------------- | | **Local MCP** | Runs on your device | Desktop integrations, local tools | | **Remote MCP** | Hosted on the internet | Web services, cloud applications | ### Key components * **Tools**: Actions Claude can perform (search, create, modify) * **Resources**: Data Claude can access (files, documents, records) * **Prompts**: Predefined interactions for specific tasks ## Security model ### User control * You authenticate each connector individually * Permissions mirror your access on the external service * You can disconnect at any time ### Tool hints All MCP tools must declare: * [`readOnlyHint`](https://modelcontextprotocol.io/specification/latest/schema#toolannotations-readonlyhint): Tool only reads data * [`destructiveHint`](https://modelcontextprotocol.io/specification/latest/schema#toolannotations-destructivehint): Tool can modify or delete data This helps Claude and users understand what actions are possible. ## Building with MCP The [MCP documentation](https://modelcontextprotocol.io/docs) is the source of truth for building MCP servers. ### For developers * Open specification at [modelcontextprotocol.io](https://modelcontextprotocol.io) * [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and [Python SDK](https://github.com/modelcontextprotocol/python-sdk) available * Cloudflare hosting support with OAuth ### Submitting to directory Organizations can [submit MCP servers](/docs/connectors/building/submission) to the Connectors Directory for broader availability. ## Related topics Connect MCP servers to Claude Code from the command line. Review requirements and submit your connector. # Building cross-platform MCP Apps Source: https://claude.com/docs/connectors/building/mcp-apps/cross-compatibility Build MCP Apps that work with both Claude and ChatGPT using a single codebase MCP Apps can run in both Claude and ChatGPT from a single codebase. The SDK auto-detects the host environment and uses the appropriate transport, though some platform-specific behaviors require attention. ## How it works ### Server side Use [`registerAppTool()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/server-helpers.registerAppTool.html) and [`registerAppResource()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/server-helpers.registerAppResource.html) to register your tools and resources. These helper functions automatically generate platform-specific metadata, so you write the registration once and it works on both platforms. ### Client side Call [`App.connect()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#connect) without an explicit transport parameter. The SDK detects whether it's running in Claude or ChatGPT and uses the appropriate transport automatically. ## Platform differences While the SDK handles most cross-platform concerns automatically, some behaviors vary between hosts. ### Domain handling The [`Resource._meta.ui.domain`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html#domain) field format and validation rules are determined by each host platform. For example, hosts may use hash-based subdomains, URL-derived patterns, or other formats. For Claude, compute the `Resource._meta.ui.domain` value by running this command, replacing `https://example.com/mcp` with your server URL: ```shell theme={null} node -e 'const yourServerUrl = "https://example.com/mcp"; console.log(require("crypto").createHash("sha256").update(yourServerUrl).digest("hex").slice(0,32) + ".claudemcpcontent.com")' ``` Example output for `https://example.com/mcp`: ``` c3d80a4ed901ee05b21755a88273b4a4.claudemcpcontent.com ``` # Design guidelines Source: https://claude.com/docs/connectors/building/mcp-apps/design-guidelines Visual and interaction design guidelines for MCP Apps in Claude ## Overview MCP Apps are interactive interfaces that appear within Claude's conversational flow. Think of them as natural extensions of the conversation, not separate apps that happen to appear alongside it. Your app inherits conversational context and helps users accomplish meaningful tasks without breaking flow. **Core principles:** * **Conversational.** Fit naturally into dialogue. Don't force users to learn new interaction patterns. * **Contextual.** Use conversation history to inform what you display and when. * **Integrated.** Inherit styling and conventions from the containing environment. * **Adaptive.** Handle variable sizing, mobile viewports, and diverse accessibility needs gracefully. See our [Figma UI kit](https://www.figma.com/community/file/1597641111449594397/mcp-apps-for-claude) for components and patterns to help you get started. ## What makes a good MCP App **Good candidates:** * Tasks that fit naturally into conversation like data analysis, document review, or project coordination * Communication and collaboration context like message search results, conversation threads, or team member profiles * Tasks with a clear start and end like booking, ordering or scheduling * Information users can act on immediately * Functionality that extends Claude's capabilities meaningfully **Patterns to avoid:** * Long-form or static content better suited for external viewing * Complex multi-step workflows that exceed the display mode's scope * Deep navigation (no drill-ins, breadcrumbs, or multiple views) * Nested scrolling (inline cards should auto-fit content height) * Menus and popovers (dropdowns, context menus, and popover panels can get clipped by container boundaries or create z-index conflicts with the host UI — prefer visible controls like segmented buttons, toggles, or inline options) * Chat inputs or conversational UI (don't replicate Claude's features) ## Display modes ### Inline card Compact components embedded directly in conversation. Good for summaries, confirmations, and quick actions. Keep them focused. **When to use:** * Status updates and confirmations * Simple data displays or selections * Brief summaries with optional expansion * Quick actions that continue the conversation Inline card example showing a compact component Inline card example showing a data display **Constraints:** * Height: auto-fits to content (no nested scrolling) * Max actions: 2, placed at the bottom of the card * Max data points: 4-5 * No drill-ins, breadcrumbs, or multiple views * No menus or popovers — use visible controls instead **On mobile:** Inline cards render full-width within the conversation. Ensure all tap targets are at least 44pt. Content should adapt to narrower viewports without horizontal scrolling. Inline card mobile examples ### Inline carousel Side-by-side items for browsing options. Users swipe or scroll horizontally to explore. **When to use:** * Product listings or search results * Location or venue options * Media galleries * Any set of comparable items Inline carousel example showing browsable items **Constraints:** * 3-8 items for scannability * Each card: image + title + metadata (max 3 lines) + optional CTA * 1 optional CTA per card * Maintain consistent card dimensions within a carousel * Cards should have consistent visual hierarchy **On mobile:** Carousel cards are optimized for horizontal swipe. Design for thumb reach — keep primary actions in the lower portion of cards. Peek the next card to signal scrollability. Inline carousel mobile examples ### Full screen Immersive interfaces for complex interactions. The conversation composer remains available so users can continue talking to your app through Claude. Apps provide their own fullscreen button. A close button appears in the native header bar when in fullscreen mode. In fullscreen mode, avoid the use of floating panels. Use collapsible sidebars, tabs or pagination to disclose details. **When to use:** * Data visualizations and dashboards * Detailed analysis tools * Document editing * Content that benefits from focused attention * Rich tasks requiring more space than inline allows Full screen mode example Full screen mode with data visualization **Constraints:** * Your app provides its own fullscreen button; a close button appears in the native header bar * The composer is always visible — design your UX to work with it * No floating panels — use collapsible sidebars, tabs, or pagination to disclose details * Chat sheet maintains conversational context **On mobile:** Your app fills the entire screen with the chat input and navigation bar overlaid on top, so keep critical UI within the safe area. Use the full viewport width and support both portrait and landscape where it makes sense. Full screen mobile examples ## Mobile guidelines MCP apps on mobile share the same principles as web, but the constrained viewport and touch-based interaction require specific adaptations. On mobile, Claude renders apps in a native WebView (WKWebView on iOS, WebView on Android) rather than a sandboxed iframe. Current mobile-only constraints: no camera/mic/location access, and connectors must be added via web or desktop before they appear on mobile. ### Host context for layout The host passes layout hints via `hostContext`. **Safe areas.** The interactive portion of your app should be rendered inside of the safe area to ensure it's not obscured by the mobile navigation bar or chat input and respects the chat screen's content margins. The user won't be able to interact with anything rendered outside the safe area (e.g. buttons obscured by a mobile navigation bar). Read `hostContext.safeAreaInsets.{top, right, bottom, left}` (in pixels) and apply them as padding on your root container, or as `scroll-padding` on scroll-snap containers so items come to rest inside the visible region. Safe areas are not mobile-specific: on web and desktop the composer can overlay the bottom of an inline app, so avoid placing interactive controls flush against any edge. Safe area insets in full screen mode on web and mobile **Borderless inline.** Set `_meta.ui.prefersBorder` to true or false to explicitly determine whether your content should render with a border. If no value is specified, content will be rendered borderless on web and bordered on mobile. In borderless mode your content runs edge-to-edge with no host padding, so honoring `safeAreaInsets` becomes essential; the bordered card's built-in padding otherwise absorbs most of them. Borderless works well for carousels and other horizontally-scrolling content that should bleed to the screen edges while in motion: apply `safeAreaInsets.left` and `.right` as `scroll-padding-inline` on the scroll container so items at rest sit clear of the device edges, but can scroll underneath them. Safe area insets for borderless inline apps on mobile Apps always fill the container width—there are no fixed breakpoints. Design responsively from 320px up to fullscreen using container queries and the hostContext CSS variables. ### Display modes Declare which modes your app supports via `appCapabilities.availableDisplayModes` in `ui/initialize`. The host responds with the modes it supports, and your app can request a switch with `ui/request-display-mode`. Modes are `inline`, `fullscreen`, and `pip`. ### Content security policy Declare external origins per `ui://` resource via `_meta.ui.csp`: ```json theme={null} { "_meta": { "ui": { "csp": { "connectDomains": ["https://api.example.com"], "resourceDomains": ["https://cdn.example.com"], "baseUriDomains": [] } } } } ``` By default, all external origins are blocked. `frameDomains` (embedding third-party iframes) is currently restricted in Claude pending security review. ### Viewport and layout * Design for variable widths (320pt minimum, up to tablet) * Respect safe areas on notched devices * Full-width layouts — don't add side margins that waste mobile screen real estate * Content should reflow gracefully; avoid fixed-width layouts Viewport and layout do's and don'ts ### Touch targets * Minimum tap target: 44 x 44pt (per Apple HIG / Material guidelines) * Add sufficient spacing between interactive elements to prevent mis-taps * Prefer larger, thumb-friendly buttons over small text links * Place primary actions within natural thumb reach (lower portion of screen) Touch target do's and don'ts ### Scrolling and gestures On mobile touch devices, the conversation view owns vertical scrolling. When your app is rendered inline, vertical pan gestures that start inside it are passed to the conversation scroll instead of to your content. This keeps a tall widget from trapping the user and is why inline apps should fit their content height rather than relying on an internal vertical scroll container—the host caps inline height and clips content that exceeds it. Horizontal gestures (ex: carousels or panning a map) and taps work normally. If your app genuinely needs its own vertically scrollable viewport, request fullscreen presentation with `ui/request-display-mode` instead of rendering inline (see [Full screen](#full-screen)). ### Transitions * Inline cards expand to fullscreen with a smooth transition * Provide a clear visual affordance for expansion (fullscreen button or tap-to-expand) * Fullscreen close returns to the conversation at the same scroll position Transition from inline card to full screen ### Dark mode All views must support both light and dark themes. Use the host's style tokens — they automatically adapt. Never hardcode colors. Test both modes. Dark mode examples on mobile ### Loading states Show skeleton screens while content loads. Match the layout structure of the final content so the transition feels seamless. Avoid spinners for inline content — skeletons feel more native. Loading state examples on mobile ## Visual design MCP Apps should feel native to their environment while maintaining consistent visual hierarchy and accessibility standards. You can still express your brand through accent colors, custom controls and content. **Design guidance** **Color.** Use host tokens for all structural elements: backgrounds, text, borders, icons. You can use your own brand colors for accents and identity, but the core UI should use the provided palette. Color token examples for light and dark mode **Typography.** Stick to the three-level size scale (heading, body, caption) and two weights (regular, emphasized). This creates clear hierarchy without visual noise. Typography scale examples The Figma Community File uses Anthropic Sans and Anthropic Serif. When your app runs inside Claude, the host client provides Anthropic Sans at runtime through style variables. [Download and install the fonts from here](https://brand.anthropic.com/typography) for local development. **Borders.** Using a limited set of corner radii and thickness will keep your app feeling native to the surrounding UI. Border radius examples **Icons.** Use monochromatic, outlined icons that match the host's icon color tokens. Icons should support understanding, not be essential to it. Icon style examples **Spacing.** Maintain generous padding and logical groupings. Balance information density with readability, adapting to viewport constraints. ## Interaction patterns ### App vs. chat interactions Understanding the boundary between your app's interactions and Claude's conversational interface helps you build something that feels cohesive. **Handle within your app:** * Direct manipulation like sliders, toggles, and selections * Filtering or sorting data you're already displaying * Expanding and collapsing content sections * Confirming or executing a prepared action ("Mark complete," "Send," "Save") * Interacting with visualizations like hover states or clicking data points Prefer controls with visible options (segmented buttons, toggle chips, inline tabs) over menus and dropdowns, which can conflict with the host container. **Push to chat input:** * Text entry and freeform input * Follow-up questions or requests for clarification * Requests to modify, refine, or redo something * Navigation to different contexts or topics * Anything that benefits from Claude's interpretation If the interaction requires language understanding or generates a response from Claude, it goes through chat. If it's a direct UI action on content your app already controls, handle it in the app. ### Start simple Reveal complexity only when users need it. The inline card might show a summary; fullscreen mode can offer the detailed view. ### Visible controls over hidden menus Prefer controls with visible options (segmented buttons, toggle chips, inline tabs) over menus and dropdowns. Menus conflict with the host container and are harder to use on mobile. ## Accessibility Maintain high contrast standards (WCAG AA minimum). Support keyboard navigation and provide text alternatives for visual content. Test with assistive technologies. Your app must be usable by everyone. ## Style variables MCP Apps automatically receive style variables from the host client. Reference these CSS custom properties to create interfaces that feel native to Claude. **Color tokens** cover backgrounds, text, and borders. Semantic accent colors signal status. All tokens automatically adapt to light and dark mode. | | Light mode | Dark mode | | :--------------------------- | :-------------- | :-------------- | | **Background** | | | | `color-background-primary` | `#FFFFFF` | `#30302E` | | `color-background-secondary` | `#F5F4ED` | `#262624` | | `color-background-tertiary` | `#FAF9F5` | `#141413` | | `color-background-inverse` | `#141413` | `#FAF9F5` | | `color-background-ghost` | `#FFFFFF (0%)` | `#30302E (0%)` | | `color-background-info` | `#D6E4F6` | `#253E5F` | | `color-background-danger` | `#F7ECEC` | `#602A28` | | `color-background-success` | `#E9F1DC` | `#1B4614` | | `color-background-warning` | `#F6EEDF` | `#483A0F` | | `color-background-disabled` | `#FFFFFF (50%)` | `#30302E (50%)` | | **Text** | | | | `color-text-primary` | `#141413` | `#FAF9F5` | | `color-text-secondary` | `#3D3D3A` | `#C2C0B6` | | `color-text-tertiary` | `#73726C` | `#9C9A92` | | `color-text-inverse` | `#FFFFFF` | `#141413` | | `color-text-ghost` | `#73726C (50%)` | `#9C9A92 (50%)` | | `color-text-info` | `#3266AD` | `#80AADD` | | `color-text-danger` | `#7F2C28` | `#EE8884` | | `color-text-success` | `#265B19` | `#7AB948` | | `color-text-warning` | `#5A4815` | `#D1A041` | | `color-text-disabled` | `#141413 (50%)` | `#FAF9F5 (50%)` | | **Border** | | | | `color-border-primary` | `#1F1E1D (40%)` | `#DEDCD1 (40%)` | | `color-border-secondary` | `#1F1E1D (30%)` | `#DEDCD1 (30%)` | | `color-border-tertiary` | `#1F1E1D (15%)` | `#DEDCD1 (15%)` | | `color-border-inverse` | `#FFFFFF (30%)` | `#141413 (15%)` | | `color-border-ghost` | `#1F1E1D (0%)` | `#DEDCD1 (0%)` | | `color-border-info` | `#4682D5` | `#4682D5` | | `color-border-danger` | `#A73D39` | `#CD5C58` | | `color-border-success` | `#437426` | `#599130` | | `color-border-warning` | `#805C1F` | `#A87829` | | `color-border-disabled` | `#1F1E1D (10%)` | `#DEDCD1 (10%)` | | **Ring** | | | | `color-ring-primary` | `#141413 (70%)` | `#FAF9F5 (70%)` | | `color-ring-secondary` | `#3D3D3A (70%)` | `#C2C0B6 (70%)` | | `color-ring-inverse` | `#FFFFFF (70%)` | `#141413 (70%)` | | `color-ring-info` | `#3266AD (50%)` | `#80AADD (50%)` | | `color-ring-danger` | `#A73D39 (50%)` | `#CD5C58 (50%)` | | `color-ring-success` | `#437426 (50%)` | `#599130 (50%)` | | `color-ring-warning` | `#805C1F (50%)` | `#A87829 (50%)` | **Typography tokens** include the font family, sizes, weights and line heights. | Family | | | :----------------------------- | :----------------------------- | | `font-sans` | `"Anthropic Sans, sans-serif"` | | `font-mono` | `"ui-monospace, monospace"` | | **Weight** | | | `font-weight-normal` | `400` | | `font-weight-medium` | `500` | | `font-weight-semibold` | `600` | | `font-weight-bold` | `700` | | **Size** | | | `font-text-xs-size` | `12px` | | `font-text-sm-size` | `14px` | | `font-text-md-size` | `16px` | | `font-text-lg-size` | `20px` | | `font-heading-xs-size` | `12px` | | `font-heading-sm-size` | `14px` | | `font-heading-md-size` | `16px` | | `font-heading-lg-size` | `20px` | | `font-heading-xl-size` | `24px` | | `font-heading-2xl-size` | `28px` | | `font-heading-3xl-size` | `36px` | | **Line-height** | | | `font-text-xs-line-height` | `1.4` | | `font-text-sm-line-height` | `1.4` | | `font-text-md-line-height` | `1.4` | | `font-text-lg-line-height` | `1.25` | | `font-heading-xs-line-height` | `1.4` | | `font-heading-sm-line-height` | `1.4` | | `font-heading-md-line-height` | `1.4` | | `font-heading-lg-line-height` | `1.25` | | `font-heading-xl-line-height` | `1.25` | | `font-heading-2xl-line-height` | `1.1` | | `font-heading-3xl-line-height` | `1` | **Radius tokens** provide border radius values | Radius | | | :------------------- | :------- | | `border-radius-xs` | `4px` | | `border-radius-sm` | `6px` | | `border-radius-md` | `8px` | | `border-radius-lg` | `10px` | | `border-radius-xl` | `12px` | | `border-radius-full` | `9999px` | **Border width tokens** provide width values | | | | :--------------------- | :------ | | `border-width-regular` | `0.5px` | **Shadow tokens** provide drop-shadow values | | | | :---------------- | :----------------------------------------------------------------------- | | `shadow-hairline` | `0 1px 2px 0 rgba(0, 0, 0, 0.05)` | | `shadow-sm` | `0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)` | | `shadow-md` | `0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)` | | `shadow-lg` | `0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)` | ### Example usage ```css theme={null} .my-app { background: var(--color-background-primary); color: var(--color-text-primary); font-size: var(--font-text-md-size); line-height: var(--font-text-md-line-height); } .card { background: var(--color-background-secondary); border-color: var(--color-border-primary); border-width: var(--border-width-regular); border-radius: var(--border-radius-md); } .button { background: var(--color-background-inverse); color: var(--color-text-inverse); font-weight: var(--font-weight-semibold); border-radius: var(--border-radius-md); } ``` # Opening external links from MCP Apps Source: https://claude.com/docs/connectors/building/mcp-apps/external-links How Claude handles ui/open-link requests, and how directory connectors can allowlist destinations to skip the confirmation modal When your MCP App sends a `ui/open-link` request, Claude shows an "Open external link" confirmation modal before navigating. This protects users from being silently redirected by an embedded app. Directory connectors can declare a set of trusted destinations that open immediately without the modal. Custom connectors and locally configured servers always show the modal. ## Default behavior A `ui/open-link` request displays a confirmation modal showing the destination URL. The link opens in a new tab when the user confirms; the request resolves as cancelled if they dismiss the modal. ## Allowlisting link destinations If your connector is published in the [Connectors Directory](/docs/connectors/directory), you can declare destinations that skip the modal. Provide them in the **Allowed link URIs** field when you [submit](/docs/connectors/building/submission) or update your directory listing. Each entry must be one of two shapes: | Entry shape | Example | Matches | | ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTPS origin | `https://docs.example.com` | Any `https://` URL whose hostname is exactly `docs.example.com` (case-insensitive). Subdomains do not match implicitly; list each one you need. Port is not compared. | | Custom URI scheme | `example-app` or `example-app:` | Any URL with the scheme `example-app:`, typically a deep link into your native mobile or desktop app. | Entries that do not fit one of these shapes are ignored. This includes bare hostnames such as `example.com`, `http://` origins, and malformed values. ### Example Given the following allowlist: ```text theme={null} https://example.com https://docs.example.com example-app ``` These destinations open immediately: * `https://example.com/pricing` * `https://docs.example.com/getting-started?ref=claude` * `example-app://open/project/123` These destinations still show the confirmation modal: * `https://blog.example.com` (subdomain not listed) * `http://example.com` (not HTTPS) * `https://example.com.attacker.net` (different hostname) ### Restrictions on custom schemes A custom-scheme entry must name a scheme your application registers and owns. Entries that name a generic, browser-internal, or platform-reserved scheme are rejected. This includes `http`, `https`, `file`, `data`, `javascript`, `blob`, `mailto`, `tel`, `sms`, `intent`, `android-app`, browser-extension schemes, and Windows shell schemes such as `search-ms` and `shell`. ## User-activation requirement The modal is bypassed only when the `ui/open-link` request follows a real user gesture in your app, such as a button click. If your app sends `ui/open-link` without a preceding gesture (programmatically, on a timer, or after the browser's activation window has expired), the modal is shown so the user's confirmation click supplies the gesture the browser requires to open a new tab. A bypassed `ui/open-link` request resolves successfully once the open is attempted; it does not indicate whether the browser actually opened the tab. Do not treat the response as confirmation that the user reached the destination. ## Design for the modal Even with an allowlist configured, your app should remain usable when the modal appears: * Custom and local connectors always show the modal. Your app may run outside the directory during development or in self-hosted deployments. * Destinations not on your allowlist, or added since your last published directory update, show the modal. * Requests without user activation show the modal. Provide enough context in your UI that the destination URL shown in the modal is recognizable to the user. # Get started with MCP Apps Source: https://claude.com/docs/connectors/building/mcp-apps/getting-started Learn how to test MCP Apps in Claude ## Try an example MCP App ### Connect an example server Make sure you have installed and logged into Claude Desktop. Navigate to the [developer settings page](https://claude.ai/desktop/settings/desktop/developer) (**Settings > Developer**) and click the "Edit Config" button. Add one of the example servers to your `claude_desktop_config.json`: | Example | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [**Customer Segmentation**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/customer-segmentation-server) | Data visualization with scatter charts and clustering analysis | | [**Map**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) | Interactive 3D globe viewer using CesiumJS | | [**QR Code**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) | QR code generation with customizable colors and styling | | [**ShaderToy**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) | Real-time GLSL shader compilation and display | | [**Sheet Music**](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) | ABC notation rendering with interactive audio playback | | ⋮ | Explore [more examples](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)—each with ready-to-use config snippets! | ```json Customer Segmentation theme={null} { "mcpServers": { "customer-segmentation": { "command": "npx", "args": ["-y", "@modelcontextprotocol/customer-segmentation-server", "--stdio"] } } } ``` ```json Map theme={null} { "mcpServers": { "map": { "command": "npx", "args": ["-y", "@modelcontextprotocol/map-server", "--stdio"] } } } ``` ```json QR Code theme={null} { "mcpServers": { "qr": { "command": "npx", "args": ["-y", "@modelcontextprotocol/qr-server", "--stdio"] } } } ``` ```json ShaderToy theme={null} { "mcpServers": { "shadertoy": { "command": "npx", "args": ["-y", "@modelcontextprotocol/shadertoy-server", "--stdio"] } } } ``` ```json Sheet Music theme={null} { "mcpServers": { "sheet-music": { "command": "npx", "args": ["-y", "@modelcontextprotocol/sheet-music-server", "--stdio"] } } } ``` Save and restart the desktop app to connect. ### See it in action Once your local server is connected, prompt Claude to use it. For example, with the customer segmentation server, ask Claude to show you recent customer data. Claude will prompt you for permission to display the App. Click "Always allow", and you'll see the MCP App render inline in the conversation. ## Build your own MCP App Ready to add an MCP App to your own MCP server? Here are the key resources: * [MCP Apps Quickstart](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) - Step-by-step guide to building your first MCP App * [SDK API Documentation](https://modelcontextprotocol.github.io/ext-apps/api/index.html) - Full API reference * [Example implementations](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) - Vanilla JS, React, Vue, Svelte, and more If you are using an AI coding agent, [MCP Apps skills](https://github.com/modelcontextprotocol/ext-apps/tree/main/plugins/mcp-apps) provide guided development for agents that support the [Agent Skills](https://agentskills.io) standard, including Claude Code, Cursor, Gemini CLI, and others. In Claude Code, you can install the MCP Apps skills plugin with the following commands: ``` /plugin marketplace add modelcontextprotocol/ext-apps /plugin install mcp-apps@modelcontextprotocol-ext-apps ``` Once installed, ask your agent to "Create an MCP App" or "Add a UI to my MCP tool". You can test remote MCP Apps locally via a proxy like [mcp-remote](https://www.npmjs.com/package/mcp-remote). ## Migrate from OpenAI Apps SDK If you are migrating an existing app from the OpenAI Apps SDK to the MCP Apps SDK, see the [migration reference](https://modelcontextprotocol.github.io/ext-apps/api/documents/Migrate_OpenAI_App.html). You can also use the MCP Apps skills mentioned above to help migrate your apps. Ask your agent to "Migrate from OpenAI Apps SDK" or "Convert my OpenAI App to an MCP App". *** We'd love to see what you build! Send feedback to [mcp-apps@anthropic.com](mailto:mcp-apps@anthropic.com) or open an issue on the [ext-apps repository](https://github.com/modelcontextprotocol/ext-apps/issues). # Supersede older widget instances Source: https://claude.com/docs/connectors/building/mcp-apps/instance-supersession Keep only the newest copy of a widget active when its tool is called more than once in a conversation Each time Claude calls a tool that renders an MCP App, a separate iframe is mounted in the conversation. There is no host API to unmount earlier instances when a newer one appears, so by default you end up with several live copies of the same widget, each independently pushing [model-context updates](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#updatemodelcontext) (data the widget feeds into Claude's context for the next turn) and [messages](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage) to Claude. If your widget represents a single piece of state, such as a shopping cart or a dashboard, only the most recent instance should remain interactive. You can use [`BroadcastChannel`](https://developer.mozilla.org/docs/Web/API/BroadcastChannel) to make earlier instances disable themselves. The snippets on this page assume you have registered a UI resource and tool and created an `App` instance from `@modelcontextprotocol/ext-apps`. See the [SDK Quickstart](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) if you haven't. ## How it works All widget iframes from a single connector are served from the same sandbox origin on `*.claudemcpcontent.com` (the iframe sandbox includes [`allow-same-origin`](https://developer.mozilla.org/docs/Web/HTML/Element/iframe#sandbox)). That means a `BroadcastChannel` opened in one instance reaches every other instance from the same connector in the current conversation. See [Channel scope and `ui.domain`](#channel-scope-and-ui-domain) for how a fixed domain widens this. The pattern has three parts: 1. **The server stamps each tool result with an election key.** It returns a `{createdAt, seq}` pair (server wall-clock time and a monotonic counter) in [`structuredContent`](https://modelcontextprotocol.io/specification/latest/server/tools#structured-content), the typed JSON payload slot of an MCP tool result. Tool results are stored in the conversation transcript, so every device and every remount of the widget sees the same key. 2. **Each widget announces its key on a shared channel.** Shortly after `connect()` resolves, the host delivers the tool result that mounted this widget (including its `structuredContent`) via the SDK's [`toolresult` event](https://modelcontextprotocol.github.io/ext-apps/api/types/app.AppEventMap.html). The widget reads its key from that event, opens a `BroadcastChannel`, and broadcasts the key. 3. **Any widget that sees a younger sibling marks itself superseded.** It greys out its UI, disables its buttons, and short-circuits all calls that mutate model context or inject messages. ## Mint the election key on the server Use [`registerAppTool`](https://modelcontextprotocol.github.io/ext-apps/api/functions/server-helpers.registerAppTool.html) to register the tool, and return the key in `structuredContent` alongside your normal tool output. A per-process counter works for a demo; a production server should derive the key from something durable, such as a database row ID or a version number on the underlying record. ```ts theme={null} import { registerAppTool } from "@modelcontextprotocol/ext-apps/server"; import { z } from "zod"; let callSeq = 0; registerAppTool( server, "show_cart", { title: "Show cart", description: "Render the user's shopping cart as an interactive widget.", inputSchema: { items: z.array(z.string()).optional() }, _meta: { ui: { resourceUri: "ui://cart-demo/cart.html" } }, }, async ({ items }) => { const list = items ?? []; const seq = ++callSeq; const createdAt = Date.now(); return { content: [{ type: "text", text: `Cart rendered with ${list.length} item(s).` }], // The election key travels with the tool result in the transcript, // so rehydrated widgets on any device recover the same ordering. structuredContent: { items: list, seq, createdAt }, }; }, ); ``` ### Why not use client-side `Date.now()`? Client mount time does not reflect tool-call order. When a stored conversation is reopened, Claude lazy-mounts widget cells as they scroll into view, so an older widget can mount after a newer one and would win an election based on client timestamps. The server-minted key is written into the transcript at tool-call time and is identical everywhere. ## Run the election in the widget The four snippets in this section form a single module; paste them in order into your widget entry file. ### Read the key from the `toolresult` event Connect and read the values you need from the host: your instance ID from [`hostContext.toolInfo`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiHostContext.html#toolinfo), and the server-minted key from the `toolresult` event. The event's `structuredContent` is typed `Record`, so cast it to the shape your server returns. ```ts theme={null} import { App } from "@modelcontextprotocol/ext-apps"; type CartResult = { items?: string[]; createdAt?: number; seq?: number }; const app = new App({ name: "cart-demo", version: "1.0.0" }); let superseded = false; let keyFinalized = false; let orderKey: number | undefined; let seq: number | undefined; let items: string[] = []; app.addEventListener("toolresult", (params) => { const sc = params.structuredContent as CartResult | undefined; if (sc?.items) items = sc.items; if (sc && Number.isFinite(sc.createdAt)) { orderKey = sc.createdAt; seq = Number.isFinite(sc.seq) ? sc.seq : undefined; keyFinalized = true; announce(); // defined in "Broadcast and compare on a shared channel" below } }); await app.connect(); const hostContext = app.getHostContext(); const instanceId = hostContext?.toolInfo?.id ?? crypto.randomUUID(); ``` ### Broadcast and compare on a shared channel Broadcast the key and compare against every sibling you hear from. The comparison is `createdAt`, tie-broken by `seq`, then by instance ID for determinism. Ignore inbound messages until your own key is finalized so you never reply with an undefined key. ```ts theme={null} const channel = new BroadcastChannel("my-app-cart-supersede"); const peers = new Map(); function isYounger(other: { orderKey: number; seq?: number; instanceId: string }) { // keyFinalized guards every call site, so orderKey is set by the time this runs. if (other.orderKey !== orderKey) return other.orderKey > orderKey!; if (other.seq != null && seq != null && other.seq !== seq) return other.seq > seq; return String(other.instanceId) > String(instanceId); } function recompute() { superseded = [...peers.values()].some(isYounger); render(); // defined in "Reflect the state in the UI" below } channel.onmessage = (ev) => { const msg = ev.data; if (!msg || msg.instanceId === instanceId) return; if (!keyFinalized) return; if (msg.type === "hello") { channel.postMessage({ type: "born", instanceId, orderKey, seq }); } peers.set(msg.instanceId, msg); recompute(); }; function announce() { channel.postMessage({ type: "hello", instanceId, orderKey, seq }); channel.postMessage({ type: "born", instanceId, orderKey, seq }); } ``` ### Gate host-mutating calls on `!superseded` The election only matters if superseded instances actually stop talking to Claude. Guard every call to [`updateModelContext`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#updatemodelcontext) or [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage): ```ts theme={null} // addButton, card, badge: elements in your widget's DOM. // pickRandomItem: your own helper that returns a string. function updateModelContext() { if (superseded) return; app.updateModelContext({ content: [{ type: "text", text: `Cart has ${items.length} item(s): ${items.join(", ")}.` }], }); } addButton.onclick = () => { if (superseded) return; items.push(pickRandomItem()); render(); updateModelContext(); }; ``` ### Reflect the state in the UI In your render function, disable buttons and show a banner that points the user to the newest instance: ```ts theme={null} function render() { card.classList.toggle("superseded", superseded); badge.textContent = superseded ? "Superseded" : "Live"; addButton.disabled = superseded; } ``` ## Special considerations The election above covers the common case. A production widget should also handle the following. ### Channel scope and `ui.domain` `BroadcastChannel` is same-origin only. How far that origin extends depends on whether you set [`_meta.ui.domain`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html#domain) on your resource: * **Without `ui.domain`** (the default), Claude derives the iframe origin from the conversation and connector, so the broadcast is scoped to a single conversation. * **With a fixed `ui.domain`**, the origin is shared across every conversation and tab for your connector. A fixed channel name would let a widget in one conversation supersede a widget in another. Neither `hostContext` nor the tool-call arguments include a Claude-provided conversation ID, so if you need both a fixed domain and per-conversation elections, generate your own scope key on the server (for example, a UUID minted once per client connection) and return it in `structuredContent` for the widget to append to the channel name. ### Fall back if the server key is delayed The main snippet above waits for the `toolresult` event before announcing. If you want the widget to participate in the election even when that event is slow to arrive, replace that listener with one that resolves a promise, and race the promise against a short timeout after `connect()`: ```ts theme={null} let resolveServerKey!: (k: { orderKey: number; seq?: number }) => void; const serverKeyReady = new Promise<{ orderKey: number; seq?: number }>( (r) => (resolveServerKey = r), ); // Replaces the toolresult listener from the first widget snippet. app.addEventListener("toolresult", (params) => { const sc = params.structuredContent as CartResult | undefined; if (sc?.items) items = sc.items; if (sc && Number.isFinite(sc.createdAt)) { resolveServerKey({ orderKey: sc.createdAt!, seq: sc.seq }); } }); // Place after the announce() definition in the broadcast snippet, // so channel is initialized before announce() runs. const serverKey = await Promise.race([ serverKeyReady, new Promise((r) => setTimeout(() => r(null), 1000)), ]); orderKey = serverKey?.orderKey ?? Date.now(); seq = serverKey?.seq; keyFinalized = true; announce(); ``` If the server key arrives after the timeout, adopt it, recompute `superseded` against the peers you have already heard from, and re-announce so siblings update their view of you. The recomputed result may flip the instance back to live. ### Fallback caveat: don't compare server and client timestamps This applies only if you implemented the fallback above. If you fall back to a client-side `Date.now()` while waiting for the server key, tag the key with its source and refuse to compare a client value against a server value. A server `createdAt` from a tool call made hours ago will always be smaller than a fresh client timestamp, which would wrongly hand "live" to whichever instance happened to fall back. Include `keySource` in the broadcast payload (`announce()` and the `born` reply) and in the `peers` Map value type so siblings can read it: ```ts theme={null} type KeySource = "server" | "client"; let keySource: KeySource = "client"; function isYounger(other: { orderKey: number; seq?: number; instanceId: string; keySource: KeySource }) { if ((other.keySource === "server") !== (keySource === "server")) return false; // keyFinalized guards every call site, so orderKey is set by the time this runs. if (other.orderKey !== orderKey) return other.orderKey > orderKey!; if (other.seq != null && seq != null && other.seq !== seq) return other.seq > seq; return String(other.instanceId) > String(instanceId); } ``` ### Caching the key across remounts On Claude.ai web, [`hostContext.toolInfo.id`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiHostContext.html#toolinfo) is the stable tool-use ID, so you can persist the resolved server key to `localStorage` keyed by that ID and reuse it on the next mount without waiting for the `toolresult` event again. Treat this as an optimization rather than a correctness guarantee. On Claude iOS, `toolInfo.id` is `undefined` when a stored conversation is rehydrated, so there is no stable per-instance cache key. Detect that case and skip the cache; the server key from the `toolresult` event is the only ordering source that works on every platform. ### If you bypass the SDK `App` class The snippets on this page use the SDK's [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class. If you instead hand-roll a minimal `postMessage` bridge, it will silently drop requests sent from the host to the widget, such as `ping` (a liveness check) and [`ui/resource-teardown`](https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiResourceTeardownRequest.html) (the host asking the widget to clean up before unmount). Claude.ai web does not currently send either to widgets, and Claude iOS sends `ui/resource-teardown` only when the user navigates away from the conversation, so ignoring them is harmless today. The `App` class handles the full request surface and is recommended for production. ## Related topics * [Cross-platform compatibility](/docs/connectors/building/mcp-apps/cross-compatibility#domain-handling) for how `_meta.ui.domain` is computed on Claude. * [SDK API reference](https://modelcontextprotocol.github.io/ext-apps/api/index.html) for `registerAppTool`, `App`, and `McpUiResourceMeta`. # Blend your MCP App with Claude's theme Source: https://claude.com/docs/connectors/building/mcp-apps/transparent-theming Make your widget background transparent and style it with Claude's style variables Claude renders MCP Apps inside a sandboxed iframe, and every frame between your widget and the chat surface already has a transparent background, so the conversation can show through. When you leave your own background transparent and style text and borders with the host's [style variables](/docs/connectors/building/mcp-apps/design-guidelines#style-variables), your app looks like part of the conversation rather than an embedded box, and it follows the user's light or dark mode automatically. The snippets on this page assume you have registered a UI resource and created an `App` instance from `@modelcontextprotocol/ext-apps`. See the [SDK Quickstart](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) if you haven't. ## Let the host background show through Three settings on your side keep the transparency intact. ### Don't paint a body background Any opaque background on `` or `` hides the chat surface behind it. Explicitly set both to `transparent`: ```css theme={null} html, body { margin: 0; background: transparent; } ``` ### Declare `color-scheme` in your document head Browsers give iframe documents an opaque canvas backdrop (white in light mode, near-black in dark mode) when the iframe's [`color-scheme`](https://developer.mozilla.org/docs/Web/CSS/color-scheme) differs from the embedding page. Declaring both schemes opts your document into whichever mode the host is in, so the browser drops the backdrop and makes the CSS [`light-dark()`](https://developer.mozilla.org/docs/Web/CSS/color_value/light-dark) values in Claude's tokens resolve correctly: ```html theme={null} ``` ### Request a borderless frame Set [`prefersBorder: false`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html#prefersborder) in your UI resource's [`_meta.ui`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html) object so the host doesn't wrap your widget in its own bordered card. Claude web's default is already borderless, but other hosts differ, so being explicit keeps your app portable. Register the resource with [`registerAppResource`](https://modelcontextprotocol.github.io/ext-apps/api/functions/server-helpers.registerAppResource.html): ```ts theme={null} import { registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server"; registerAppResource(server, "My Widget", "ui://my-app/widget.html", {}, async () => ({ contents: [ { uri: "ui://my-app/widget.html", mimeType: RESOURCE_MIME_TYPE, text: widgetHtml, // the bundled HTML string of your widget; see the SDK Quickstart _meta: { ui: { prefersBorder: false, // lets applyHostFonts load Anthropic Sans; see "Allow the host font origin in your CSP" csp: { resourceDomains: ["https://assets.claude.ai"] }, }, }, }, ], })); ``` ## Apply the host's style variables Claude passes a [`hostContext`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiHostContext.html) object to your widget during the [`connect()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#connect) handshake. The fields relevant to theming are: | Field | Contents | | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | `theme` | `"light"` or `"dark"` | | `styles.variables` | CSS custom properties: `--color-background-*`, `--color-text-*`, `--color-border-*`, `--color-ring-*`, `--font-*`, `--border-radius-*`, `--border-width-*` | | `styles.css.fonts` | `@font-face` rules for Anthropic Sans, served from `https://assets.claude.ai` | The [Style variables](/docs/connectors/building/mcp-apps/design-guidelines#style-variables) section of the design guidelines lists every variable and its light- and dark-mode value. ### Read `hostContext` and listen for changes The [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class exposes the initial context via [`getHostContext()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#gethostcontext) once `connect()` resolves, and delivers subsequent updates (such as the user toggling dark mode) through the [`hostcontextchanged`](https://modelcontextprotocol.github.io/ext-apps/api/types/app.AppEventMap.html) event. Register the listener before you connect so you don't miss an early update. The SDK provides three helpers that do the DOM work for you, plus React hooks that wrap them: * [`applyDocumentTheme(theme)`](https://modelcontextprotocol.github.io/ext-apps/api/functions/app.applyDocumentTheme.html) sets `` and the root `color-scheme`, so `[data-theme="dark"]` selectors and `light-dark()` values resolve correctly. * [`applyHostStyleVariables(variables)`](https://modelcontextprotocol.github.io/ext-apps/api/functions/app.applyHostStyleVariables.html) writes every entry in `styles.variables` onto `:root` as a CSS custom property. * [`applyHostFonts(fontCss)`](https://modelcontextprotocol.github.io/ext-apps/api/functions/app.applyHostFonts.html) injects the host's `@font-face` rules once. * [`useApp(options)`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) creates and connects the `App` instance for you in React. * [`useHostStyles(app, hostContext)`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useHostStyles.html) applies all of the above and re-applies on `hostcontextchanged`. Keep the `` tag from the previous section even though `applyDocumentTheme` also sets `color-scheme` at runtime. The tag covers the first paint before your script runs and prevents an opaque-backdrop flash. ```ts TypeScript theme={null} import { App, applyDocumentTheme, applyHostFonts, applyHostStyleVariables, type McpUiHostContext, } from "@modelcontextprotocol/ext-apps"; function applyHostContext(ctx: Partial) { if (ctx.theme) applyDocumentTheme(ctx.theme); if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables); if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts); } const app = new App({ name: "my-app", version: "1.0.0" }); // Updates carry only the fields that changed. app.addEventListener("hostcontextchanged", (changed) => applyHostContext(changed)); await app.connect(); const initial = app.getHostContext(); if (initial) applyHostContext(initial); ``` ```tsx React theme={null} import { useApp, useHostStyles } from "@modelcontextprotocol/ext-apps/react"; function Widget() { const { app } = useApp({ appInfo: { name: "my-app", version: "1.0.0" }, capabilities: {}, }); // Applies theme + CSS variables + fonts, and re-applies on host-context-changed. useHostStyles(app, app?.getHostContext()); return
…
; } ``` ### Reference the variables in your CSS Once the variables are on `:root`, reference them directly. Provide fallbacks so the widget is still readable when rendered outside a host: ```css theme={null} body { font-family: var(--font-sans, system-ui, sans-serif); color: var(--color-text-primary, light-dark(#141413, #faf9f5)); } .card { border: var(--border-width-regular, 0.5px) solid var(--color-border-primary); border-radius: var(--border-radius-md, 8px); } ``` Claude's token values use CSS `light-dark()`, so once `applyDocumentTheme` has set the root `color-scheme`, every `--color-*` variable resolves to the right variant without any `[data-theme]` selectors on your side. ### Allow the host font origin in your CSP For `applyHostFonts` to load the `@font-face` files, your resource's [`_meta.ui.csp`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html#csp) allowlist must include `https://assets.claude.ai` in [`resourceDomains`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceCsp.html#resourcedomains) (shown in the [`registerAppResource` snippet above](#request-a-borderless-frame)). `resourceDomains` also adds the listed origins to `script-src` and `style-src`, so keep it to origins you trust to serve executable code; prefer bundling third-party fonts into your widget rather than allowlisting public CDNs. ## Related topics * [Design guidelines: Style variables](/docs/connectors/building/mcp-apps/design-guidelines#style-variables) and [Visual design](/docs/connectors/building/mcp-apps/design-guidelines#visual-design) for the full variable palette and usage guidance. * [SDK API reference](https://modelcontextprotocol.github.io/ext-apps/api/index.html) for `App`, `McpUiHostContext`, and `McpUiResourceMeta`. # Troubleshooting MCP Apps Source: https://claude.com/docs/connectors/building/mcp-apps/troubleshooting Debug and resolve common issues with MCP Apps ## Using developer tools ### Desktop Claude Desktop's Developer Tools can help you debug MCP Apps. To use them: 1. Open **Help > Troubleshooting** and click **Enable Developer Mode**. A new **Developer** menu appears in the menu bar. 2. Open Developer Tools by pressing `Cmd+Option+I` (Mac) or `Ctrl+Shift+I` (Windows) 3. Inspect the tool call element and look for an iframe nested inside another iframe. Your app will be loaded as the content of the inner iframe. From the **Developer** menu, select **Reload MCP Configuration** after editing your `claude_desktop_config.json` to apply changes without restarting. ### iOS On iOS, the Claude app renders your MCP app inside a `WKWebView`. You can inspect it from a connected Mac using Safari's Web Inspector—see Apple's guide to [inspecting iOS](https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios) for setup. Once connected, the Claude web view appears under your device in Safari's **Develop** menu, and you can use the console, network panel, and element inspector just as you would on desktop. ## Problem: Tool call appears but the app is invisible This is the most common issue when developing MCP Apps. Check these two causes: ### Missing `app.connect()` call Your app must call [`app.connect()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#connect) (Vanilla JS) or [`useApp()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) (React) to establish communication with Claude Desktop. ```javascript Vanilla JS theme={null} import { App } from "@modelcontextprotocol/ext-apps"; const app = new App({ name: "My App", version: "1.0.0" }); // Register handlers before connecting app.ontoolresult = (result) => { // Handle tool results }; await app.connect(); ``` ```javascript React theme={null} import { useApp } from "@modelcontextprotocol/ext-apps/react"; function MyComponent() { // The useApp hook handles connection automatically const { app } = useApp({ appInfo: { name: "My App", version: "1.0.0" }, capabilities: {}, onAppCreated: (app) => { app.ontoolresult = (result) => { // Handle tool results }; } }); } ``` Event handlers like `app.ontoolinput` and `app.ontoolresult` won't be invoked until the app is connected. ### Iframe has zero height Your app needs a non-zero height to be visible. A zero height can occur if: * Your app's container has no content yet * You called `sendSizeChanged({ width, height: 0 })` Check that your root element has explicit dimensions or content that gives it height. ## Problem: App doesn't render when tool results are large When a tool result exceeds approximately 150,000 characters and Claude's code execution sandbox is active, the result is written to the sandbox filesystem instead of being passed inline to the conversation. Your app receives a pointer to the stored file rather than the structured content it needs, so it never hydrates. This \~150,000-character threshold is specific to Claude.ai and Claude Desktop. Claude Code uses a separate 25,000-token default limit configurable via `MAX_MCP_OUTPUT_TOKENS`. To avoid this, keep initial tool result payloads lean: * **Paginate large results.** Return a summary or the first page of data, and let the user request more through follow-up interactions. * **Fetch details on demand.** Use app-initiated tool calls to load additional data from within your widget as the user explores, rather than returning everything upfront. * **Defer heavy content.** If your data includes large blobs—full document text, base64-encoded images, extensive logs—return identifiers or previews in the initial result and provide a separate tool to retrieve the full content when needed. ## Problem: Assets or API requests fail only on iOS If your app loads on desktop and web but fails to fetch scripts, images, or API data on iOS, check whether your server, CDN, or WAF is gating access on the `Referer` header. WebKit on iOS—both Safari and in the Claude iOS app—omits the `Referer` header on cross-origin subresource requests as part of its tracking prevention (WebKit bugs [206521](https://bugs.webkit.org/show_bug.cgi?id=206521) and [179053](https://bugs.webkit.org/show_bug.cgi?id=179053#c8)). A server that requires a `Referer` to allow the request will reject iOS traffic even though the same app works elsewhere. **Fix:** Allowlist on the `Origin` header instead, which WebKit does send. Requests from your app carry an `Origin` of `{hash}.claudemcpcontent.com`—see [Domain handling](/docs/connectors/building/mcp-apps/cross-compatibility#domain-handling) to compute the hash for your server URL. Configure your infrastructure to allow requests whose `Origin` matches `*.claudemcpcontent.com` and return a corresponding `Access-Control-Allow-Origin` header. This applies to requests your app makes directly from the user's device—loading bundles, images, or calling your own API from client-side code. MCP tool calls are proxied through Claude's backend and egress from Anthropic's published IP ranges, not the user's device. ## Problem: ui.domain validation fails Setting [`_meta.ui.domain`](https://modelcontextprotocol.github.io/ext-apps/api/interfaces/app.McpUiResourceMeta.html#domain) on your resource opts your app into a stable sandbox origin, which you need if your app runs its own OAuth flow. Claude validates the value against your connector URL and shows an `Invalid ui.domain format` or `ui.domain mismatch` error instead of rendering the app when validation fails. The value must be exactly `{hash}.claudemcpcontent.com`, where `{hash}` is the first 32 hexadecimal characters of the SHA-256 digest of your full connector URL. Compute it by running this command with your own URL: ```shell theme={null} node -e 'const yourServerUrl = "https://example.com/mcp"; console.log(require("crypto").createHash("sha256").update(yourServerUrl).digest("hex").slice(0,32) + ".claudemcpcontent.com")' ``` Common causes of a mismatch: * **The URL you hashed differs from the URL Claude connects to.** The hash covers the full URL string including scheme, path, and any trailing slash, so `https://example.com/mcp` and `https://example.com/mcp/` produce different values. Hash the exact URL configured in **Customize > Connectors**. * **The connector is local (stdio).** Local connectors have no URL to hash, so `ui.domain` is not available for them. Remove the field, or deploy the server as a remote connector to use a stable origin. See [Domain handling](/docs/connectors/building/mcp-apps/cross-compatibility#domain-handling) for how the origin is used across platforms. # Build a desktop extension with MCPB Source: https://claude.com/docs/connectors/building/mcpb Package a local MCP server as a single-click .mcpb install for Claude Desktop MCPB is the secondary distribution path. Remote MCP servers are recommended for directory listing—see [what to build](/docs/connectors/building/what-to-build). This guide covers building an MCP Bundle (`.mcpb`) for internal use, private distribution, or as a foundation for [submission to the Connectors Directory](/docs/connectors/building/submission). ## What is an MCPB? An `.mcpb` file is a zip archive containing a local MCP server and a `manifest.json`. It enables single-click installation in Claude Desktop, similar to a browser extension. Key characteristics: * Runs locally on the user's machine * Communicates via stdio transport * Bundles all dependencies * Works offline * No OAuth required See the [MCPB repository](https://github.com/modelcontextprotocol/mcpb) for the complete specification and the [Desktop Extensions blog post](https://www.anthropic.com/engineering/desktop-extensions) for an architecture overview. ## Local (MCPB) vs remote: which to build | Choose MCPB when you need | Choose a remote connector when you need | | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Access to systems behind your firewall (JIRA, Confluence, internal wikis, private databases) | Cloud services and public APIs with centralized infrastructure | | Authentication via existing SSO and browser sessions, no token management | OAuth flows with server-side token management | | Zero-trust compliance inside corporate network boundaries | Distribution across Claude on web, mobile, and desktop | | Direct filesystem access for code editing and Git operations | Centralized updates pushed to all users | | Integration with locally installed tools (Docker, IDEs, databases) | Public-facing integrations used by multiple organizations | | Hardware integration and desktop application control | | | Privacy-sensitive operations that should not leave the user's machine | | | One-click install with bundled Node.js runtime, no dependencies to manage | | | No cloud infrastructure, VPN configuration, or firewall rules | | | Organization-level admin controls (custom uploads, allowlists) | | | Full control over authentication, authorization, and audit logs | | **Key difference:** MCPBs run on the user's machine via stdio with access to local and internal resources. Remote connectors run on your servers via HTTPS and are accessed through Anthropic's infrastructure. Organizations commonly build MCPBs as secure proxies to internal MCP servers, for internal documentation access, and to connect development tools while preserving their security architecture. For remote connector guidance, see [building custom connectors](/docs/connectors/building/index). ## Choose a language Node.js is strongly recommended: * Ships with Claude Desktop on macOS and Windows, so users need no separate runtime * Best compatibility and reliability with Claude Desktop * Extensive MCP SDK support ## Platform support Claude Desktop runs on macOS (`darwin`) and Windows (`win32`). Specify supported platforms in the `compatibility` section of your `manifest.json`. Test on both platforms even if you primarily develop on one. See the [manifest spec compatibility section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#compatibility) for platform and runtime requirement details. ## Quickstart ```bash theme={null} npm install -g @anthropic-ai/mcpb ``` Build a stdio MCP server using the [MCP SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk). ```bash theme={null} mcpb init ``` ```bash theme={null} mcpb pack ``` Double-click the generated `.mcpb` file. For detailed implementation guidance, see the [MCPB repository](https://github.com/modelcontextprotocol/mcpb), the [examples directory](https://github.com/modelcontextprotocol/mcpb/tree/main/examples) including a Hello World, and the [README "For Bundle Developers" section](https://github.com/modelcontextprotocol/mcpb/blob/main/README.md). Before distributing your MCPB, review the testing and best-practices guidance in the MCPB README to ensure quality. ## manifest.json The `manifest.json` file is required metadata describing what your MCPB does, how to run it, which tools it provides, and what configuration it needs. | Reference | | | ---------------------------------------------------------------------------------------- | --------------------------- | | [MCPB Manifest Spec](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md) | Full schema with all fields | | [Example manifests](https://github.com/modelcontextprotocol/mcpb/tree/main/examples) | Real-world implementations | | [CLI documentation](https://github.com/modelcontextprotocol/mcpb/blob/main/CLI.md) | Command reference | ## Add an icon Icons are optional but recommended. Place `icon.png` in your bundle root and reference it in `manifest.json`. | Requirement | Value | | ----------- | ----------------------------------------- | | File name | `icon.png` (or a custom path) | | Size | 512×512px recommended (minimum 256×256px) | | Format | PNG with transparency | | Location | Bundle root or specified path | You can also provide multiple icon variants for different sizes and themes (light/dark mode). See the [manifest spec icons section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#icons) for variant syntax and best practices. ## User configuration Define a `user_config` section in `manifest.json` and Claude Desktop automatically generates a settings UI for your extension. The [manifest spec user configuration section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#user-configuration) covers the full schema, configuration types, validation constraints, sensitive-data handling, and multi-select patterns. ## How users install your MCPB Users can install three ways: 1. **Double-click** the `.mcpb` file 2. **Drag and drop** the `.mcpb` file into the Claude Desktop window 3. **Settings**: Settings → Extensions → Advanced settings → Install Extension… → select the `.mcpb` file All three open an installation UI where the user reviews extension details and permissions, configures required settings, grants permissions, and completes installation. Installation is per-user; each user installs separately on their own system. For the end-user installation experience and Team/Enterprise admin controls (organization management, allowlists, policy configuration), see [Getting Started with Local MCP Servers on Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop). ## Resources **MCPB framework** * [MCPB repository](https://github.com/modelcontextprotocol/mcpb): complete specification and tools * [MCPB Manifest Spec](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md): full manifest schema * [MCPB CLI documentation](https://github.com/modelcontextprotocol/mcpb/blob/main/CLI.md): command reference * [MCPB examples](https://github.com/modelcontextprotocol/mcpb/tree/main/examples): reference implementations **MCP protocol** * [MCP specification](https://modelcontextprotocol.io/docs/getting-started/intro): protocol documentation * [MCP quickstart](https://modelcontextprotocol.io/docs/develop/build-server): getting-started guide * [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk): Node.js implementation * [Python SDK](https://github.com/modelcontextprotocol/python-sdk): Python implementation **Claude Desktop** * [Release notes](https://support.claude.com/en/articles/12138966-release-notes): version updates * [Desktop Extensions blog](https://www.anthropic.com/engineering/desktop-extensions): architecture overview ## Get help * [MCPB GitHub issues](https://github.com/modelcontextprotocol/mcpb/issues): bug reports and feature requests * [MCP specification repo](https://github.com/modelcontextprotocol/modelcontextprotocol): protocol questions * [Claude support](https://support.claude.com/en/articles/9015913-how-to-get-support): general Claude Desktop support Check repository discussions for community Q\&A, follow release notes for updates, and review the examples for implementation patterns. ## Ready for distribution If you have a working MCPB and want broader distribution and discoverability, submit it to the Connectors Directory. See [submitting to the directory](/docs/connectors/building/submission) for requirements including: * Mandatory tool annotations for all tools * Privacy policy requirements * Working examples that exercise each tool * Test credentials where applicable * The complete submission process and review timeline # Pre-submission checklist Source: https://claude.com/docs/connectors/building/review-criteria What Anthropic reviewers test, so you can pass on the first try When you submit a server, it is automatically scanned for policy compliance and, by default, listed in the directory as a [community connector](/docs/connectors/verification). Anthropic may then escalate listings flagged as highly useful to Claude users to verified review, which is higher touch and slower; reviewers run a functional test of each tool. This escalation is assessed automatically, and you do not need to take any action. Every server in the directory must meet the criteria on this page, whichever label it carries. The label is a quality signal shown to users; it does not change how your connector runs once connected. This page surfaces the most common rejection reasons so you can self-correct before submitting. For the full legal text, see the [Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy). ## Tool design ### Separate read and write tools A single tool that accepts both safe HTTP methods (GET, HEAD, OPTIONS) and unsafe methods (POST, PUT, PATCH, DELETE) is rejected. Do not ship a catch-all `api_request` tool with a `method` parameter. Split into a read-only tool and one or more write tools. Ideally, split write operations further by action type (create, update, delete). Documenting safe versus unsafe operations within one tool's description does not satisfy this requirement—the operations must be in separate tools. ### Reference API docs in custom query tools If a tool accepts freeform endpoint paths, query strings, or request bodies that the caller constructs, its description must include a link to or explicit name of the target API. For example: "Queries the Slack Web API—see [https://api.slack.com/methods](https://api.slack.com/methods)". A description like "Makes a request to the API" with no further context fails. This applies only to custom query tools. Purpose-built tools that call a fixed endpoint internally do not need an API docs reference. ### Provide tool annotations Every tool must include a `title` and the applicable hint—`readOnlyHint: true` for read-only tools, `destructiveHint: true` for tools that modify or delete data. These determine auto-permissions in Claude: read-only tools can run without per-call confirmation; destructive tools always prompt. ### Keep tool names short Tool names must be 64 characters or fewer. ### Write narrow, accurate descriptions Each tool description should state precisely what the tool does and when to invoke it. The description must match the tool's actual behavior. ## Avoid prompt-injection patterns Tool descriptions are rejected if they: * Instruct Claude to call external software or tools the user didn't request * Interfere with Claude calling other tools * Direct Claude to pull behavioral instructions from external sources * Contain hidden, obfuscated, or encoded instructions * Tell Claude to behave in ways unrelated to the tool's function, attempt to override system instructions, or promote products and services Describe what the tool does. Do not tell Claude how to behave. ## Functional quality * Every tool must return a successful response when called with valid parameters. Generic errors ("Internal Server Error", "Bad Request" with no detail) fail review. * Validate inputs and return actionable error messages rather than silently accepting invalid data. * Keep responses reasonably sized for the task. Do not return a full database dump when a summary was requested. * Do not collect conversation data beyond what the tool needs for its function. * Do not query Claude's memory, chat history, conversation summaries, or user files. ## API ownership Your server must call your own first-party APIs, or APIs you legitimately proxy. The MCP server domain should match your service. ## Unsupported use cases Connectors that do the following are not accepted: * Transfer money, cryptocurrency, or other financial assets * Generate images, video, or audio via AI models (design tools that produce diagrams, charts, or UI mockups are allowed) ## Submission requirements * **Test credentials** are required and must be a fully populated account. * **Allowed link URIs** are recommended if your server calls `ui/open-link`. Declared HTTPS origins and custom URI schemes open without a confirmation prompt; anything else still prompts the user. See [Allowed link URIs](/docs/connectors/building/submission#allowed-link-uris). * **Public documentation** is required by your publish date—a blog post or help-center article is sufficient. You can share docs privately with Anthropic during review. * **Plugins** must link a public GitHub repo; closed-source is not accepted. * **MCPB** open-source and "spec will evolve" clauses in the [Software Directory Terms](https://support.claude.com/en/articles/13145338-anthropic-software-directory-terms) are required and not waivable. ## Before you submit Run `claude plugin validate` on plugins. For MCP servers, exercise every tool through the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) and as a [custom connector in Claude](/docs/connectors/building/testing). # Submitting to the Connectors Directory Source: https://claude.com/docs/connectors/building/submission Submit your MCP connector to the Connectors Directory The [Connectors Directory](/docs/connectors/directory) aims to be a collection of high-quality, vetted, and reviewed MCP servers that are helpful and harmless to users. Anyone is welcome to build MCP servers, but only servers meeting the review standards outlined on this page will be included in the directory. ## What you can submit Developers can submit: * **Remote MCP servers** — internet-hosted servers that provide tools and data to Claude * **Desktop extensions** — local MCP servers packaged as [MCP Bundles (MCPB)](https://github.com/modelcontextprotocol/mcpb) for Claude Desktop * **[MCP Apps](/docs/connectors/building/mcp-apps/getting-started)** — MCP servers that surface interactive UI elements. These have the additional requirement of including screenshots for submission and listing in the directory. ## Before you start Remote MCP server submissions happen inside Claude.ai, in the [submission portal](https://claude.ai/admin-settings/directory/submissions/new). The portal is part of your organization's settings, so you need: * **A Team or Enterprise organization.** Organization settings aren't available on individual plans. * **Directory management access.** By default, only organization Owners and Primary owners can submit and manage directory listings. On Enterprise, an Owner can delegate this to other members by creating a custom role in **Organization settings > Roles** with either the **Directory** permission (directory submissions only) or the **Libraries** permission (broader: it also covers managing the organization's plugins, connectors, and skills), and assigning that role. Team plans don't have custom roles, so on Team this stays with Owners. Desktop extensions (MCPB) use a separate [submission form](https://clau.de/desktop-extention-submission) and don't require the portal. ## Directory terms & conditions All servers in the directory must comply with: * [Anthropic Software Directory Terms](https://support.claude.com/en/articles/13145338-anthropic-software-directory-terms) * [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) By submitting a connector, you also agree to: * Maintain your connector's security and functionality * Respond to security issues promptly * Provide accurate descriptions and documentation ## Submission requirements All MCP connectors submitted to the directory must meet: 1. **Security**: Meet Anthropic's security standards 2. **Tool annotations**: All tools must include a `title` and the applicable `readOnlyHint` or `destructiveHint` 3. **Authentication**: Use OAuth 2.0 for authenticated services 4. **Privacy Policy**: Local connectors must include privacy policies 5. **Documentation**: Provide clear setup and usage instructions If your connector opens external links, also provide your [allowed link URIs](#allowed-link-uris) so users aren't prompted to confirm each one. ## Privacy policy requirements Local connectors must include: 1. "Privacy Policy" section in README.md 2. `privacy_policies` array in manifest.json (manifest\_version 0.2+) 3. HTTPS URLs to privacy policies The privacy policy must cover: * Data collection practices * Usage and storage * Third-party sharing * Data retention * Contact information Missing or incomplete privacy policies result in immediate rejection. ## Allowed link URIs If your connector uses the `ui/open-link` capability to open URLs in the user's browser or native apps, provide the list of link targets your server will request. Claude uses this list to suppress the "Open external link" confirmation prompt for destinations you've declared. Links to any other destination still work—users are simply asked to confirm before the link opens. Provide each entry in one of two forms: * **HTTPS origin** — `https://example.com`. Only the scheme and hostname are matched; paths, ports, and query strings are ignored. Subdomains are not implied—list each one (`https://app.example.com`, `https://docs.example.com`). * **Custom URI scheme** — `myapp:` for deep links into a native app you own (for example, `spotify:` or `notion:`). Only the scheme is matched. Every origin and scheme you list **must be owned by you** (the submitting organization). You may not list third-party domains or URI schemes registered to apps you don't publish. Entries you don't own will be removed during review. This field is optional. If omitted, your connector functions normally, but users are shown a confirmation prompt each time it opens a link. ## Asset specifications ### Carousel screenshots (MCP Apps) * **Format:** PNG * **Width:** at least 1000px * **Count:** 3–5 images * **Crop:** to the app response only—**do not include the prompt** in the image * **Aspect ratio:** any * **Paired prompts:** provide the prompt text separately for each screenshot * **Mobile:** no separate mobile assets are required—one batch covers all surfaces * **Video/GIF:** not accepted A carousel template is available in the [Anthropic MCP Apps Figma community file](https://www.figma.com/community/file/1597641111449594397/mcp-apps-for-claude). ### Detail card description You write the detail card description in the submission portal. It is not editable by Anthropic. The disclaimer text shown on connector cards is general and not customizable per partner. ## Review process Review times vary with queue volume. The submission portal is always open. After you submit, track your submission's status and read reviewer feedback in the [submissions dashboard](https://claude.ai/admin-settings/directory/submissions). See [Managing your listing](/docs/connectors/building/managing-your-listing) for what's available there, including server health and usage metrics after publication. Email `mcp-review@anthropic.com` for escalations. Run the [pre-submission checklist](/docs/connectors/building/review-criteria) and, for plugins, `claude plugin validate` before you submit. ## Submit your connector Ready to submit? Use the path that matches your connector type: * **Remote MCP servers (including MCP Apps)**: submit through the [submission portal](https://claude.ai/admin-settings/directory/submissions/new) in your organization's settings on Claude.ai. See [Before you start](#before-you-start) for access requirements. * **Desktop extensions (MCPB)**: use the [desktop extension submission form](https://clau.de/desktop-extention-submission). Skills are not a standalone submission type—bundle them in a [plugin](/docs/plugins/submit). ### What to expect in the portal Before you start, have your documentation URL, privacy policy URL, icon, and test account credentials ready, plus carousel screenshots if you're submitting an MCP App (see [asset specifications](#asset-specifications) above). The portal walks you through the following steps. Your progress saves automatically in your browser as you move between steps, so within a browser session you can jump back to earlier steps without losing work. Explains what a directory listing does and doesn't do: inclusion makes your connector discoverable but doesn't change the tools it exposes. The portal accepts remote MCP servers only. Local servers are distributed as [desktop extensions](https://clau.de/desktop-extention-submission) or [plugins](/docs/plugins/submit) instead. Connect the server you're submitting. You confirm the server URL (must be `https://`), the transport (streamable HTTP or SSE), and how users reach your server: one **Universal URL** for everyone, a fixed list of **Multiple URLs**, or a **URL pattern** that each user's own URL must match. See [Servers with per-customer URLs](/docs/connectors/building/authentication#servers-with-per-customer-urls) for how this choice limits your authentication options. Your server's tools, prompts, and resources sync automatically from the connected server, grouped by whether their annotations declare them read-only or write (tools without annotations are grouped separately). If any tools are flagged for missing titles or annotations, fix them on your server before submitting. The public-facing listing: server name (100 characters max), tagline (55 characters max), description (2,000 characters max), one to five categories, documentation URL, privacy policy URL, support contact, icon, and the URL slug for your listing page. The slug is permanent once published. Describe the primary use cases, what users need before they can connect (accounts, plans, or other setup), and whether the connector reads data, writes data, or both. Company name and website, plus a primary contact for review updates. The contact name and email are pre-filled from your account. How users authenticate: OAuth (with dynamic client registration, client ID metadata documents, or Anthropic-held client credentials), a custom connection where users supply their own URL or credentials at connection time, or no authentication. See [authentication](/docs/connectors/building/authentication) for which modes are supported out of the box and which need coordination with the review team. If your server starts without authentication and individual tools prompt for it on demand, you can flag that here. If you chose **URL pattern** in the Connection step, Anthropic-held client credentials can't be used. If you chose **Multiple URLs**, a custom connection can't be used. Whether the underlying API is your own, proxied from a partner with permission, or a third party's you don't control, and whether the connector handles personal health data or sponsored content. Test-account setup and access instructions detailed enough for a reviewer to access your server end to end: every link, credential, and step, including credentials for a fully populated account where relevant. You also confirm you've run every tool yourself, either via MCP Inspector or as a custom connector in Claude. Seven policy acknowledgments covering the directory guidelines, first-party API usage, financial transactions, AI media generation, prompt injection, conversation data collection, and public documentation. All seven are required. A final read-through of everything you've entered. Any quality warnings (for example, very short answers) are shown here and shared with the review team alongside your submission. Submit when you're ready. After you submit, your submission's status and any reviewer feedback appear in the [submissions dashboard](https://claude.ai/admin-settings/directory/submissions). See [Managing your listing](/docs/connectors/building/managing-your-listing). # Testing your connector Source: https://claude.com/docs/connectors/building/testing Test your MCP server against Claude before submitting to the directory Test your server against the real Claude client before submitting. There is no separate staging environment—you test in production using a custom connector. ## Test as a custom connector Any Claude account (Free, Pro, Max, Team, or Enterprise) can add a custom connector. Go to **Customize > Connectors**, select **Add custom connector**, and enter your server's URL. Custom connectors use the exact same runtime as directory connectors, so what works here will work after publication. ## Test a local server To test a server running on your machine, expose it as a public URL with a tunnel such as [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) or `ngrok`, then add the tunnel URL as a custom connector. This is the recommended pattern for iterating on MCP Apps as well. A tunnel exposes your local server to the public internet. Keep authentication enabled on your server while tunneling, and shut the tunnel down when you're done testing. ## Validate with MCP Inspector Use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to verify protocol compliance, exercise your auth flow, and inspect tool schemas before connecting to Claude. ## Detect Claude as the client Claude identifies itself in the MCP `initialize` handshake via `clientInfo`, but the exact value depends on the surface and the request path. You may see `"name": "claude-ai"`, `"name": "Anthropic"` (sometimes with a service suffix), or `"name": "claude-code"`: ```json theme={null} { "clientInfo": { "name": "Anthropic", "version": "1.0.0" } } ``` Don't gate behavior on an exact `name` or `version` string — both vary across surfaces, request paths, and releases. Use `clientInfo` for telemetry and coarse feature detection only, and remember it's unauthenticated: any client can claim any name, so it must never feed an authorization decision. ## Prepare test credentials for review Directory submission requires test credentials. Provide a **fully populated account**—not an empty shell—so reviewers can exercise real functionality (list real records, search real data, exercise write tools on real resources). Include step-by-step setup instructions for someone unfamiliar with your service. ## Debugging Partner-visible error logs are in development. In the meantime, use server-side logging on your end and the MCP Inspector to diagnose connection failures. Common causes of `initialize` timeouts include slow OAuth endpoints (keep discovery, registration, and token responses under ten seconds; see [endpoint latency](/docs/connectors/building/authentication#endpoint-latency)), overly strict `Origin`-header validation rejecting Anthropic's requests, and firewalls dropping Anthropic's egress traffic. If your infrastructure logs show `403 Forbidden` responses your application didn't generate, your CDN or WAF is likely blocking Anthropic's traffic. See [firewall or WAF blocks Anthropic's traffic](/docs/connectors/building/troubleshooting#2-firewall-or-waf-blocks-anthropic%E2%80%99s-traffic) for the fix. For a structured walkthrough of "Couldn't reach the MCP server" and "Authorization failed" errors, including DNS resolution checks, OAuth discovery diagnostics, and how to find the `ofid_` reference ID to include in a support request, see [troubleshooting connectors](/docs/connectors/building/troubleshooting). # Troubleshooting connectors Source: https://claude.com/docs/connectors/building/troubleshooting Diagnose and resolve common connection, authorization, and tool-call failures for custom and directory MCP connectors This page covers the most common reasons a connector fails to connect, authenticate, or run a tool, and how to diagnose each one. Each error Claude shows covers more than one root cause, so start with the section for the message you see: * "Couldn't reach the MCP server", when Claude can't complete the connection handshake * "Authorization with the MCP server failed", when the OAuth flow starts but doesn't complete, or when your server URL redirects to a different host * "Unexpected error while invoking tool", when the connector is connected but a tool call fails ## Find your reference ID When a connection fails, the error toast and the page URL include a reference ID that starts with `ofid_`. For example: ```text theme={null} .../customize/connectors?step=start_error&flow_id=ofid_d32594c73257a651 ``` Copy that ID and include it in any GitHub issue or support request. It lets Anthropic trace the exact failure on the server side. Reference IDs are time-limited, so report them soon after the failure. If you're filing on the [`anthropics/claude-ai-mcp` issue tracker](https://github.com/anthropics/claude-ai-mcp/issues), include the `ofid_` value, your server URL, and what your server-side access logs show during the Connect attempt. ## "Couldn't reach the MCP server" This error appears when Claude can't complete the connection handshake. Despite the wording, it isn't always a network failure. Work through these causes in order. ### 1. Hostname resolves to a private IP claude.ai connectors run on Anthropic's infrastructure and reach your server over the public internet. Before making any request, Claude resolves your server's hostname and validates the result. If **any** resolved address is not globally routable, Claude rejects the connection before any HTTP request leaves Anthropic's network. Your server's access logs see nothing, and Claude reports "Couldn't reach." Claude rejects the connection when the hostname: * resolves to a private address (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) * resolves to a carrier-grade NAT address (`100.64.0.0/10`) * resolves to a loopback or link-local address * resolves to a mix of public and non-public addresses — every returned address must be globally routable * has no `A` record from public DNS — connectors are IPv4-only, so a hostname that only publishes `AAAA` records can't be reached **Common gotchas:** * **Works in Claude Code or `curl` but not claude.ai.** The CLI and `curl` connect from your machine, while claude.ai connects from Anthropic's servers. If your hostname resolves differently inside and outside your network (split-horizon DNS), claude.ai may be getting a private IP. * **Dynamic DNS providers.** Dynamic DNS hostnames often resolve to a home network behind NAT or carrier-grade NAT. * **Internal corporate DNS.** A hostname that resolves on your VPN won't resolve to a routable address from the public internet. **How to check:** Run `dig +short your-server.example.com` from a machine outside your network, or use a public DNS lookup service. Every returned address must be globally routable. **How to fix:** Expose your server through a publicly-routable endpoint, such as a cloud host with a public IP, a public reverse proxy, or a tunnel. See [test a local server](/docs/connectors/building/testing#test-a-local-server) for the recommended tunnel setup. ### 2. Firewall or WAF blocks Anthropic's traffic If your hostname resolves correctly but a CDN, WAF, bot-management rule, or rate limiter in front of your server blocks the request, the connection fails before your application sees it. **How to check:** Look for `403` or `429` responses in your edge or CDN logs that your application didn't generate, especially during a Connect attempt. **How to fix:** Allowlist Anthropic's published outbound IP range in your WAF or CDN configuration, or exempt your MCP and OAuth paths from the blocking rule. The current range is on the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses) page. ### 3. Your server URL redirects to a different host If your registered MCP URL returns a `301`/`302`/`307`/`308` redirect to a different host (apex to `www.`, region routing, vanity domain to CDN), the `Authorization` header is dropped on the redirect per standard HTTP client security behavior. The redirect target receives an unauthenticated request and returns `401`, and the connection fails with "Authorization with the MCP server failed." This also explains the common report "works in MCP Inspector or Claude Code CLI but not claude.ai." Local clients fail fast on a redirect, so the misconfiguration is visible immediately. claude.ai follows the redirect, drops the credential, and the failure surfaces later as an authorization error. **How to check:** Run `curl -sI https://your-server.example.com/your-mcp-path` and look at the response status and `Location` header. If you see a `3xx` status pointing at a different host, that target is the URL you should register. **How to fix:** Register the URL your server actually listens on, not a URL that redirects to it. Common culprits are apex-to-`www.` canonicalization, geographic or region routing, and vanity-domain-to-CDN redirects. ### 4. OAuth discovery fails If your server requires authentication, Claude performs OAuth discovery before it can connect. A discovery failure can surface as "Couldn't reach" even though your MCP endpoint itself is reachable, or as a sign-in that redirects to `/authorize` on your MCP server's host and fails there. The redirect happens when Claude can't read your [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected resource metadata and falls back to treating your MCP server's origin as the authorization server, so the browser opens a sign-in page that doesn't exist on your server. The most common causes: * **Discovery metadata returns 404.** If your `401` response doesn't include a `WWW-Authenticate` header with a `resource_metadata` pointer, Claude looks for protected resource metadata and authorization server metadata at the standard `/.well-known/` paths on your MCP server's origin. If those paths return `404` and you haven't pointed Claude elsewhere, Claude can't locate your authorization server. * **No way to register a client.** Claude needs one of: [RFC 7591 dynamic client registration](https://www.rfc-editor.org/rfc/rfc7591) (a `registration_endpoint` in your authorization server metadata), [Client ID Metadata Documents](/docs/connectors/building/authentication#dcr-and-cimd-details) (`"client_id_metadata_document_supported": true`), or a pre-registered client. Without any of these, Claude can't obtain a client identity. See [supported authentication types](/docs/connectors/building/authentication#supported-authentication-types). * **Authorization server is on a different host than the MCP server.** Claude discovers protected resource metadata from your MCP server, then makes a *second* round of discovery requests against the authorization server host listed in `authorization_servers`. If that host lives behind a different CDN or WAF, it must also be reachable from Anthropic's egress range. See [cross-host authorization servers](/docs/connectors/building/authentication#cross-host-authorization-servers). * **A proxy or hosting platform alters the discovery response.** A layer in front of your server can rename or drop the `WWW-Authenticate` header, or answer `403` on the `/.well-known/` paths before the request reaches your application. Check the response at the deployed edge with `curl` from a public network, not with a tool that runs inside your platform. **How to check:** From a public network, run: ```bash theme={null} curl -i https://your-server.example.com/.well-known/oauth-protected-resource curl -i https://your-server.example.com/.well-known/oauth-authorization-server curl -i https://your-server.example.com/.well-known/openid-configuration ``` If your MCP endpoint includes a path component (such as `https://your-server.example.com/mcp`), append it to the well-known path: `/.well-known/oauth-protected-resource/mcp`. The protected resource metadata should return `200` with valid JSON. For authorization server metadata, your server only needs to answer **one** of the two discovery endpoints — Claude tries `/.well-known/oauth-authorization-server` ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) first, then falls back to `/.well-known/openid-configuration` ([OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)). A `404` on one is expected if the other returns `200`. Most hosted identity providers (Auth0, Okta, Microsoft Entra, Keycloak, Supabase Auth) only serve `/.well-known/openid-configuration`. Whichever metadata document resolves should advertise a `registration_endpoint` (DCR), `"client_id_metadata_document_supported": true` (CIMD), or you should be using pre-registered credentials. In a cross-host setup, run the protected-resource curl against your MCP server and the two authorization-server curls against your authorization server's issuer host. ## "Authorization with the MCP server failed" This error usually appears after the OAuth flow has started. The most common causes: * **Issuer mismatch.** The `issuer` value in your authorization server metadata must match the issuer that signs your tokens. If your tokens come from a third-party identity provider such as Supabase Auth or Auth0 but your metadata advertises a different issuer URL, validation can fail. * **Audience mismatch.** The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-handling) requires your server to verify each access token was issued for it. Claude sends the [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707) `resource` parameter on authorization and token requests, set to the canonical form of your MCP server URL — lowercase scheme and host, no trailing slash, no fragment, no default port — including any path component. Your authorization server should issue tokens with that audience, and your MCP server should accept the canonical value when checking `aud` rather than doing a strict byte-for-byte comparison against what the user typed. Or use whatever audience-binding mechanism your token format supports, as long as it confirms the token was minted for your server and not another service. * **PKCE not supported.** Claude includes a PKCE `code_challenge` with `code_challenge_method=S256` in every authorization request. If your authorization server doesn't implement S256 PKCE, the flow fails at the token endpoint. The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-code-protection) also requires authorization servers to advertise `"code_challenge_methods_supported": ["S256"]` so spec-compliant clients can verify support before starting the flow. * **Refresh failures.** Use RFC 6749-compliant error codes when a refresh token expires. See [token refresh](/docs/connectors/building/authentication#token-refresh). * **Slow token endpoint.** Claude waits up to 10 seconds for your `/token` response; if no response bytes arrive in that window, the flow fails here even if your server eventually issues the token. Check the end-to-end latency of your token handler and any proxy or gateway in front of it. See [endpoint latency](/docs/connectors/building/authentication#endpoint-latency). * **Your server URL redirects to a different host.** When the URL you registered redirects to another hostname, Claude drops the `Authorization` header as it follows the redirect, the redirect target returns `401`, and the connection fails with this message. See "3. Your server URL redirects to a different host" under "Couldn't reach the MCP server" on this page for how to find and fix the redirect. ### Microsoft Entra ID rejects the resource value If your authorization server is Microsoft Entra ID and the token request fails with `AADSTS9010010` (sometimes surfaced as `invalid_target`), Entra is rejecting the `resource` value Claude sends because it does not match any Application ID URI registered on your app. Claude sets `resource` to your MCP server URL, including the path, and Entra issues a token when that value is listed under **Expose an API** → **Application ID URI** (`identifierUris` in the manifest) on the app registration that represents your protected API. The default `api://{client-id}` URI alone is not sufficient here, because Claude sends the full MCP server URL as the resource value. **How to fix:** 1. In the [Microsoft Entra admin center](https://entra.microsoft.com), open the app registration that represents your protected API. If you have separate registrations for the OAuth client and the API, this is the API registration, not the client. 2. Under **Expose an API**, add your MCP server URL as an additional [Application ID URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-expose-web-apis). The value must match exactly, including the path, without a trailing slash. 3. If your server validates the token audience (for example, through Azure App Service Authentication), add the API app's Application (client) ID and its `api://` URI to the allowed token audiences so your server accepts tokens issued for the API. This is the **Allowed token audiences** setting, not **Allowed client applications**, which is a different list. 4. If the OAuth client and the API are separate app registrations, confirm the client has an admin-consented API permission for the scope your API exposes. By default, Microsoft Entra accepts a new Application ID URI only if it contains your tenant ID, your app ID, or a domain verified in your tenant, as described in [Microsoft's identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions). If your MCP server runs on a platform hostname, such as `*.azurewebsites.net`, Entra rejects that URL when you add it under **Expose an API**, so serve the server from a custom domain that your tenant has verified and register that URL instead. A tenant administrator can also exempt your app registration from this policy so that Entra accepts a noncompliant URI. Microsoft notes that an `https://` URI can require a verified domain even then, which makes the custom domain the dependable fix. If the OAuth flow completes successfully on your server (you see the token issued in your logs) but the connection still fails, file a [GitHub issue](https://github.com/anthropics/claude-ai-mcp/issues) with the `ofid_` reference ID and the timestamps from your server's OAuth logs. ## "Unexpected error while invoking tool" This error, followed by the name of the tool, appears when your connector shows as connected and signed in but one of its tool calls fails. Claude's tool call reached your server, and your server returned an error result for it. A failed tool call isn't a connection failure, so there is no `ofid_` reference ID for it. **How to check:** 1. Run the same tool call against your server in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) and compare the result with the error Claude reports. 2. Check your server's logs for the tool handler's error at the time of the failure, and whether the failure affects every user of your connector or one account. If you file a [GitHub issue](https://github.com/anthropics/claude-ai-mcp/issues) about a tool-call failure, include the tool name, the time of the failure in UTC, and the connector URL in place of an `ofid_` reference ID. ## Diagnostic checklist Run through these in order before filing an issue: From a network outside your own, confirm `dig +short your-server.example.com` returns a globally-routable address. From a public network, confirm `curl -i https://your-server.example.com/your-mcp-path` returns a response (a `401` or `405` is fine; a timeout or connection refused is not). Run `curl -sI https://your-server.example.com/your-mcp-path` and confirm the response is not a `3xx` redirect to a different host. If it is, register the redirect target instead. Check your edge logs for `403` or `429` responses. Allowlist Anthropic's published egress range if needed. See the [IP address reference](https://platform.claude.com/docs/en/api/ip-addresses). Confirm `/.well-known/oauth-protected-resource` returns `200` with valid JSON, and that one of `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration` does the same — only one is needed. The authorization server metadata should include a `registration_endpoint` (DCR) or advertise `"client_id_metadata_document_supported": true` (CIMD), or you should be using pre-registered credentials, and it should advertise `"code_challenge_methods_supported": ["S256"]`. If your authorization server is on a different host than your MCP server, confirm your protected resource metadata's `authorization_servers` field points at it, and that the authorization server's host is reachable from Anthropic's egress range and answers `/.well-known/openid-configuration` (or `/.well-known/oauth-authorization-server`). See [cross-host authorization servers](/docs/connectors/building/authentication#cross-host-authorization-servers). Reproduce the failure and copy the `ofid_` value from the error URL. Include it, your server URL, and your server-side logs in your report. ## Related topics OAuth requirements and supported auth types. How to test your server before publishing. The 401 + WWW-Authenticate discovery handshake. Anthropic's published IP ranges for allowlisting. # What should I build: MCP, plugin, or both? Source: https://claude.com/docs/connectors/building/what-to-build Decide between an MCP server, a plugin, or both for your Claude integration Most partners ship two things: a remote MCP server and a plugin that wraps it. They serve different purposes, and together they give users the best experience. ## The recommendation Build a **remote MCP server with OAuth** first to provide connectivity and core functionality. Then create a **plugin with skills** that helps users get the most out of that MCP server. | | MCP server | Plugin | | ---------------- | ------------------------------------------------ | ------------------------------------------------ | | **What it is** | A live tool surface Claude calls over HTTP | An installable bundle of skills and connectors | | **Mental model** | "Claude can call your API" | "Claude knows how to *use* your product" | | **Contains** | Tools, prompts, resources, optionally MCP App UI | Skills, MCP connector references, slash commands | | **Works in** | Claude.ai, Desktop, mobile, Cowork, Claude Code | Claude Code, Cowork | ## When to build only one **MCP server only** is fine when your integration is simple and doesn't need skills—a few well-named tools that Claude can use without additional guidance. **Plugin only** is fine when you already have a public API or CLI that doesn't need an MCP wrapper. A plugin can ship skills that teach Claude to use that API or CLI directly. ## What a plugin can bundle A plugin can contain any combination of: * Skills only * A single MCP connector reference * Skills plus one or more MCP connectors * Multiple MCP connectors Plugins can reference both remote and local MCP servers. A remote MCP works on every Claude surface (web, mobile, Cowork, Desktop, Claude Code); a local MCP works only in Claude Desktop and Claude Code. Most MCP servers are remote. ## How they coexist A plugin references a remote MCP server by **URL**. If a user has both your directory connector and your plugin installed, Claude sees one set of tools—the plugin and the connector point at the same server. If a plugin references an MCP URL that isn't in the directory, the connector appears as **Custom** in the user's settings. Both MCP servers and plugins can update without Anthropic involvement. When you add tools to your MCP server, plugins that reference it pick them up automatically. Plugin updates are pushed via GitHub and pass through automated screening. ## Skills are not a standalone directory type Skills are user-shared micro-workflows. **Plugins are the distribution mechanism for skills**—you can't submit a skill to the directory on its own. If you have skills to ship, bundle them in a plugin. ## Build it with Claude The fastest way to scaffold an MCP server is with Claude itself. Install the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) in Claude Code and run `/mcp-server-dev:build-mcp-server`—it interviews you about your use case, picks the right deployment model, and generates a working server. ## Next steps Start with the MCP building guide. Bundle skills and connectors together. # Desktop extensions Source: https://claude.com/docs/connectors/custom/desktop-extensions Deploy enterprise-grade MCP servers with MCPB Desktop extensions allow you to deploy local MCP servers for Claude Desktop with enterprise-grade features using MCPB (MCP Bundles). Available for Team and Enterprise plans with Claude Desktop. ## What are desktop extensions? Desktop extensions are local MCP servers that run on user devices, providing: * Local tool access without internet dependency * Enhanced security for sensitive operations * Custom integrations for internal tools * Enterprise deployment capabilities ## MCPB (MCP Bundles) MCPB is Anthropic's utility for building and deploying desktop extensions: * Package MCP servers for distribution * Handle cross-platform compatibility * Manage dependencies * Support enterprise deployment ### Key features * **Bundling**: Package your MCP server with all dependencies * **Distribution**: Deploy to users via your organization's channels * **Updates**: Manage version updates centrally * **Security**: Sign and verify extensions ## When to use desktop vs remote | Use Case | Recommended | | --------------------------- | ----------------- | | Access to local files/tools | Desktop Extension | | Internet-hosted services | Remote MCP | | Sensitive enterprise data | Desktop Extension | | Public APIs | Remote MCP | | Offline capability needed | Desktop Extension | ## Enterprise deployment For Team and Enterprise plans, admins can: 1. Build custom desktop extensions 2. Package with MCPB 3. Deploy through enterprise software management 4. Control which extensions are available to users ## Security considerations Desktop extensions run locally with user permissions: * Access only what the user can access * No data transmitted unless explicitly designed * Full audit capability for enterprise * Revocable by administrators ## Getting started 1. Review the [MCPB documentation](https://github.com/modelcontextprotocol/mcpb) 2. Build your MCP server 3. Bundle with MCPB 4. Test locally 5. Deploy to your organization ## Related topics Learn to build MCP servers. Using cloud-hosted connectors. # Third party connectors with remote MCP Source: https://claude.com/docs/connectors/custom/remote-mcp Connect Claude to your tools using the Model Context Protocol Custom connectors enable you to link Claude directly to your essential tools and data sources using the Model Context Protocol (MCP). ## What are third party connectors? Custom connectors allow Claude to operate within your preferred software and leverage comprehensive context from your external tools. You can: * Connect Claude to existing remote MCP servers * Build your own remote MCP servers for any tool ### Finding connectors Browse the [Connectors Directory](/docs/connectors/directory) to discover third-party MCP servers that are ready to use across all Claude products. Some are verified by Anthropic and others are community connectors; see [connector verification](/docs/connectors/verification). ## Adding custom connectors You can manually add any third-party connector to Claude as long as you have the URL of that remote MCP server. **Security Notice**: Custom connectors allow connections to unverified services. Claude can access and perform actions within these services, so review security considerations carefully. ### For Team and Enterprise plans **Owners must:** 1. Navigate to **Organization settings > Connectors** 2. Select **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**. 3. Enter the remote MCP server URL 4. Optionally configure OAuth Client ID/Secret in Advanced settings 5. Click "Add" If your Add custom connector dialog has two steps, see [The Add custom connector dialog, field by field](#the-add-custom-connector-dialog-field-by-field). **Members then:** 1. Go to **Customize > Connectors** 2. Find the connector with "Custom" label 3. Click "Connect" to authenticate ### For Free, Pro, and Max plans 1. Navigate to **Customize > Connectors** 2. Click "Add custom connector" 3. Enter the remote MCP server URL 4. Optionally configure OAuth credentials 5. Click "Add" If your Add custom connector dialog has two steps, see [The Add custom connector dialog, field by field](#the-add-custom-connector-dialog-field-by-field). ### Enabling connectors in chat Use the "+" button in your chat interface to access "Connectors," where you can enable/disable connectors per conversation. ## The Add custom connector dialog, field by field The two-step dialog described here is rolling out gradually. If your dialog shows a name, URL, and Advanced settings on one screen, your organization has the earlier version; the steps above still apply. **Name**: the display name shown in the connectors list. **MCP server URL**: the HTTPS address where the server accepts MCP requests, for example `https://mcp.example.com/mcp`. After you continue, Claude checks the URL and pre-fills the authentication settings it detects, marked "Detected." **Authentication**: how people connect to the server. * **Sign in now**: each user signs in through the server's OAuth flow before using it. * **Sign in when needed**: Claude connects without credentials and prompts users to sign in when the server asks. * **No sign-in**: anyone with access to the server URL can use the connector. If the server uses an API key, choose **No sign-in** and add the key under **Request headers**; Claude stores it as the connector's credential. **OAuth client** (shown unless you chose **No sign-in**): how Claude identifies itself to the server's authorization server. * **Use Claude's published identity** (recommended): the server reads Claude's client details from a URL Anthropic hosts (Client ID Metadata Document). Nothing to set up; the server must support it. * **Register automatically**: Claude registers OAuth clients with the server as users connect (Dynamic Client Registration). Works with most servers, but adds client registrations over time. * **Use your own OAuth client**: enter a client ID you registered with the server. Leave the secret blank unless your authorization server requires one. See [Authentication for connectors](/docs/connectors/building/authentication). **Request headers**: fixed credentials such as API keys, sent on every request. See [Authenticating with request headers](#authenticating-with-request-headers). **Advanced > Transport**: set from the URL automatically; a URL ending in `/sse` selects the older SSE transport. Change it only if the server's documentation says to. ## Authenticating with request headers Request header authentication is in beta and available to a limited set of organizations. If you don't see the **Request headers** section in the Add custom connector dialog, your organization doesn't have access yet. If your MCP server authenticates with an API key, bearer token, or other fixed credential instead of OAuth, you can configure it in the **Request headers** section of the Add custom connector dialog. Claude stores each header value securely, does not show it again after you save, and sends it on every request to your server. Request headers suit services where everyone in your organization shares one credential, such as an internal tool or a service account. If each person needs to sign in with their own account, use OAuth instead. You can also use request headers in addition to OAuth, including OAuth with your own pre-registered client credentials. Headers configured on an OAuth connection are sent on every request alongside the OAuth bearer token. This is useful for verifying where a request came from, passing additional client metadata, or working with tunnels and gateways that need their own routing header. The one exception is `Authorization`: OAuth owns that header, so it cannot be configured as a request header on an OAuth connection. ### Adding a request header 1. In the Add custom connector dialog, open **Request headers**. 2. Select a header name from the list, or choose **Custom header** to enter a different name. The list offers standard authentication and routing header names such as `authorization`, `x-api-key`, and `x-auth-token`, which every connector can use. Anthropic reviews and approves each custom header name before Claude will send it to a third-party server, which prevents connector configuration from being used to send arbitrary header names. If you enter a header name that isn't approved, Claude rejects the save with an error. To request approval for a custom header name, contact [Claude support](https://support.claude.com/en/articles/9015913-how-to-get-support). 3. Enter the header value exactly as your server expects to receive it. 4. Choose whether the header is **Required**. When a required header has no stored value at connection time, the connection fails. When an optional header has no value, Claude simply omits it from the request. 5. Repeat for any additional headers your server needs (you can add up to four), then click **Add**. ### Enter the full header value Claude sends the value exactly as you enter it. It does not add an authentication scheme or any other prefix. For an `Authorization` header, include the scheme in the value: | You enter | Claude sends | | ------------------- | ---------------------------------- | | `Bearer your-token` | `Authorization: Bearer your-token` | | `your-token` | `Authorization: your-token` | Most servers that use bearer tokens reject the second form. If your server's documentation shows `Authorization: Bearer YOUR_TOKEN`, enter `Bearer ` followed by your token, including the space. The same applies to Basic authentication: enter `Basic ` followed by the base64-encoded credentials. ## Managing connectors To edit a connector's name or URL, or to remove a connector: 1. Go to **Customize > Connectors** (Team and Enterprise owners: **Admin settings > Connectors**) 2. Click "Remove" or select the three-dot menu 3. Follow the prompts Authentication settings (OAuth credentials and request headers) can't be changed after a connector is added. To change them, remove the connector and add it again with the new details. Members will need to reconnect. ## Security and privacy ### Best practices * Only connect to servers from trusted organizations * Carefully review requested permission scopes during authentication * Be aware of prompt injection risks; Claude has built-in protections * Monitor for unexpected changes in tool behavior ### Tool actions Remote MCP servers enable Claude to invoke tools that can: * Read data from applications * Create, modify, or delete data * Take actions on your behalf **Usage guidelines:** * Monitor Claude's actions for unintended effects * Review tool approval requests carefully * Only click "Always allow" for trusted servers * Turn off connectors you aren't using with the toggles in the chat "+" menu's **Connectors** item * Block individual tools you don't need under **Customize > Connectors** by selecting the connector and setting the tool's permission to **Blocked** ## Reporting issues Report malicious MCP servers to [Anthropic's Bug Bounty Program](https://www.anthropic.com/responsible-disclosure-policy). ## Related topics Learn to build your own MCP servers. Browse pre-built connectors. Understand the Model Context Protocol. Deploy enterprise-grade MCP servers. Add the same server to Claude Code from the command line. # Connectors directory Source: https://claude.com/docs/connectors/directory Browse verified and community MCP integrations for Claude The Connectors Directory is a catalog of [MCP](/docs/connectors/building/mcp) servers that work across all Claude products — Claude.ai, Claude Desktop, Claude Mobile, Claude Code, and Cowork. The directory contains both verified connectors and community connectors. Verified connectors have been tested by Anthropic for quality and compatibility and met the Software Directory Policy requirements at the time of review, though verification is not a security audit. Anthropic screens community connectors before listing but does not review them in depth. The label reflects the level of review each connector received, not how it works: once connected, a community connector has the same capabilities and access as any connector you grant. See [connector verification](/docs/connectors/verification) to learn what each label means. All connectors in the directory are subject to the [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) and the [Anthropic Software Directory Terms](https://support.claude.com/en/articles/13145338-anthropic-software-directory-terms). ## How the directory works * The same catalog serves Claude.ai, Cowork, Desktop, mobile, and Claude Code. * Directory connectors are eligible for **Suggested Connectors**—in-chat recommendations when relevant to the user's task. Every directory entry is included automatically. * Ranking is usage-based, similar to other app stores. * No domain-ownership proof (DNS or `.well-known`) is required—that requirement applies only to the open MCP Registry, not the Anthropic Directory. * The help-docs link shown in the in-product connector setup flow is not partner-customizable. Directory connectors and custom connectors run on the same infrastructure—see [directory vs custom](/docs/connectors/building/directory-vs-custom). ## Browsing the directory Access the Connectors Directory through: * **[Customize > Connectors](https://claude.ai/customize/connectors)** in claude.ai * **[Organization settings > Connectors](https://claude.ai/admin-settings/connectors)** for Team/Enterprise admins ## Requesting a connector on a Team plan On Claude Team plans, members who do not have permission to enable connectors see a **Request** button on each directory connector instead of a connect action. Selecting **Request** sends the connector to your organization's admins for review. The button changes to **Requested** while the request is pending. If you are a Team admin with permission to manage connectors, member requests appear in two places: * **[Organization settings > Connectors](https://claude.ai/admin-settings/connectors)** shows a **Requested by your team** section above the connector list. * **[Organization settings > Notifications](https://claude.ai/admin-settings/notifications)** lists each requested connector on the **Requests** tab, and the **Notifications** item in the admin sidebar shows a count badge while requests are pending. From either location you can enable the connector for your organization or dismiss the request. Claude shows the requesting member the outcome the next time they open the connectors directory. ## When a connector's endpoint changes Occasionally a provider updates the endpoint URL behind its directory listing, for example moving a server from `https://mcp.example.com/sse` to `https://mcp.example.com/mcp`. This is a routine change on the provider's side. Here is what you may notice in Claude: * **Your existing connection keeps working.** Connectors you added before the change keep using the endpoint they were installed with, and your authentication is unaffected. * **It appears as a custom connector.** Because your connector no longer matches the updated directory listing, it shows under "Custom" in [Customize > Connectors](https://claude.ai/customize/connectors) instead of as a named directory connector. * **The directory listing shows as not installed.** Adding the connector from the directory again without removing the original gives you two connections: your original one and a new one on the updated endpoint. To move to the new endpoint, remove the connector and re-add it from the directory. Claude prompts you to authenticate with the service again. ## Submitting to the directory Organizations can submit their MCP servers for review and inclusion in the directory: 1. Review the [submission guidelines](/docs/connectors/building/submission) 2. Ensure your server meets security and compatibility standards 3. Submit through the [submission portal](https://claude.ai/admin-settings/directory/submissions/new) in Claude.ai admin settings Submitting requires a Team or Enterprise organization and directory management access (organization Owners by default); see [Before you start](/docs/connectors/building/submission#before-you-start). After publication, the same dashboard shows your server's health and usage; see [Managing your listing](/docs/connectors/building/managing-your-listing). ## Related topics Create your own MCP server. # Get started with connectors Source: https://claude.com/docs/connectors/getting-started Learn to connect Claude to your tools and data This tutorial walks you through setting up and using Claude's connector integrations to enhance your workflow. ## What you'll learn * Setting up your first connector * Using connectors in conversations * Best practices for each integration * Troubleshooting common issues ## Prerequisites * A Claude account (Pro, Max, Team, or Enterprise for most connectors) * Accounts on the services you want to connect ## Setting up your first connector ### Step 1: Access connector settings 1. Go to [claude.ai](https://claude.ai) 2. Select **Customize** in the sidebar 3. Select **Connectors** ### Step 2: Choose a connector Available connectors include: * Google Drive, Gmail, Calendar * GitHub * Slack * Microsoft 365 ### Step 3: Authenticate 1. Click "Connect" next to your chosen service 2. Log in to your account on that service 3. Grant Claude the requested permissions 4. Return to Claude ## Using connectors in conversations ### In chat 1. Start a new conversation 2. Click the "+" button 3. Select "Add from \[Service]" 4. Choose the content you want to include 5. Ask your question ### In projects 1. Open your project 2. Click "Add Content" 3. Select the connector 4. Add documents to your project knowledge ## Connector-specific tips ### Google Drive * Best for: Document analysis, research * Add multiple Google Docs for comprehensive context * Documents sync automatically with updates ### Gmail & Calendar * Best for: Finding information, scheduling context * Ask questions like "What did Sarah say about the budget?" * Claude can search your emails but can't send them ### GitHub * Best for: Code understanding, documentation * Add entire repositories or specific files * Use with Projects for persistent codebase context ### Slack * Best for: Finding discussions, team context * Search channels and direct messages * Requires installing the earlier Claude in Slack app first ### Microsoft 365 * Best for: Enterprise document search * Access SharePoint, OneDrive, Outlook, Teams * Requires a work or school Microsoft account ## Best practices 1. **Connect what you need**: Only connect services with relevant data 2. **Review permissions**: Understand what Claude can access 3. **Keep context focused**: Don't overload with too much data ## Troubleshooting * Clear browser cookies and try again * Check that you have the right account permissions * Try a different browser * Verify you have access to the data in the source service * Wait a moment for sync to complete * Try disconnecting and reconnecting * Go to Customize > Connectors * Click "Reconnect" or "Refresh" * Re-authenticate with the service ## Related topics See all available connectors. Build your own integrations with MCP. # GitHub integration Source: https://claude.com/docs/connectors/github/index Connect your code repositories to Claude Connect GitHub repositories directly to Claude to provide comprehensive context for software development tasks. Claude can understand your codebase and assist with development questions. Available on all plans including Free. ## Adding GitHub repositories ### In chats 1. Click the "+" button in the lower left corner of the chat interface 2. Select "Add from GitHub" from the dropdown menu 3. Use the file browser to select specific files and folders 4. When sending your message, Claude accesses and processes the selected content ### In projects 1. Click the "+" button in your project knowledge section 2. Select "GitHub" from the dropdown 3. Search accessible repositories or paste a repository URL 4. Use the file browser to select specific files and folders 5. Your selected content is added to project knowledge **Keeping content current:** * Use the "Sync" icon to ensure you're working with the latest codebase * Use the "Configure files" icon to modify which files Claude analyzes If you're not authenticated with GitHub, you'll be redirected to authenticate before using the integration. ## Connecting to private repositories If you see a warning after entering a valid URL, you're likely attempting to connect to a private repository. Follow the link to the GitHub App where you can: * **Grant access yourself**: Choose between allowing Claude access to all repos or specific ones * **Request access**: GitHub organization administrators receive an email notification. Once approved, you can sync and access the repository ## Best practices 1. **Start small**: Begin with a small codebase subset to understand how Claude interprets your code 2. **Iterate and refine**: Ask follow-up questions if initial responses need clarification 3. **Combine with human expertise**: Use Claude's insights as a starting point for team discussion 4. **Thoughtful file selection**: Include key files central to your task while staying within token limits 5. **Regular updates**: Refresh GitHub sync periodically, especially before new analysis or major repo changes ## What information is retrieved | Retrieved | Not Retrieved | | -------------- | ------------------- | | File names | Commit history | | File contents | Pull requests | | Branch content | Issues | | | Repository metadata | ## Frequently asked questions Click "Sync now" to fetch the latest changes from your repository. Yes, add multiple repositories to provide comprehensive context, provided they fit within Claude's context window. You won't be able to view its contents in projects where it was previously added. The repository preview is removed, but conversation history remains. # Google Calendar integration Source: https://claude.com/docs/connectors/google/calendar Access your calendar and meeting information with Claude The Google Calendar integration enables Claude to understand your calendar commitments, helping you manage your schedule more effectively. Available on Pro, Max, Team, and Enterprise plans. ## Connect Google Calendar 1. In claude.ai, go to **Customize > Connectors**. 2. Find Google Calendar and click **Connect**. 3. Sign in to your Google account and grant the requested permissions. On Team and Enterprise plans, an Owner or Primary Owner must enable the integration for your organization before it appears in your connector list. For the full walkthrough, including troubleshooting, see [Get started with connectors](/docs/connectors/getting-started). ## How to use Calendar integration ### 1. Ask about your schedule Simply ask Claude questions about your calendar. Claude automatically detects when calendar data is needed. **Example questions:** * "What meetings do I have tomorrow?" * "When is my next meeting with the product team?" * "Do I have any conflicts next week?" * "Who's attending the budget review meeting?" ### 2. Review Claude's response Claude provides answers that include: * Clear answers to your questions * Citations indicating which calendar events were used * Links to original events when applicable ### 3. Follow up You can ask for more details about: * Meeting attendees * Event timing and duration * Related meetings and patterns ## Privacy and data handling ### Authentication You must authenticate directly to your Google account. For Claude for Work (Team/Enterprise) plans, an Owner or Primary Owner must enable integrations at the account level. ### Data access * Claude accesses only data from your connected Google account * Access occurs only when you explicitly request it * Minimum information is retrieved to answer your question * Your existing calendar permissions are mirrored ## Limitations * Claude cannot create, modify, or delete calendar events * Claude cannot send calendar invitations * Only calendars you have access to can be searched ## Related topics Search and analyze your emails. Connect your documents. # Google Drive integration Source: https://claude.com/docs/connectors/google/drive Connect Google Docs directly to Claude The Google Drive integration lets you connect Google Docs directly to Claude on paid Claude.ai plans. You can add documents by pasting URLs or selecting recent files to provide context for your conversations. Available on Pro, Max, Team, and Enterprise plans. ## How to add Google Docs ### In chats 1. Click the plus sign (+) in the chat interface 2. Select "Add from Google Drive" 3. Authenticate with Google on first use 4. Search recent documents or paste a document URL 5. Claude accesses and processes the document when you send your message ### In projects The integration works only in private projects: 1. Click "Add Content" in project knowledge 2. Select "Google Drive" 3. Authenticate on first use 4. Search or paste a document URL 5. The document becomes available to Claude within that project ## Supported file types | Type | Supported | Notes | | -------------------- | --------- | -------------------------------- | | Google Docs | ✅ | Up to 10MB, text extraction only | | Google Sheets | ❌ | Not currently supported | | Google Slides | ❌ | Not currently supported | | Images in docs | ❌ | Not extracted | | Comments/Suggestions | ❌ | Not extracted | Convert .docx files by opening in Google Docs, clicking "File," then "Save as Google Docs." ## Key features * **Live sync**: Documents continue syncing with the latest Google Drive version * **Multiple documents**: Add multiple docs if they fit the context window * **Permission-based**: You can only sync documents you have permission to view ## Frequently asked questions Yes, documents continue syncing with the latest Google Drive version. Yes, you can add multiple docs as long as they fit within the context window. You'll lose document preview access but your conversation history remains. ## Troubleshooting For reconnection errors: 1. Navigate to **Customize > Connectors** 2. Find Google Drive 3. Click the menu button (...) 4. Select "Disconnect" 5. Authenticate again when prompted For persistent issues, disconnect from Google account connections at [myaccount.google.com](https://myaccount.google.com), search "Claude for Google Drive," and delete all connections. ## Related topics Search and analyze your emails. Access your calendar information. # Gmail integration Source: https://claude.com/docs/connectors/google/gmail Search and analyze emails with Claude The Gmail integration enables Claude to search your emails and provide answers based on your email content, reducing time spent retrieving information. Available on Pro, Max, Team, and Enterprise plans. ## Connect Gmail 1. In claude.ai, go to **Customize > Connectors**. 2. Find Gmail and click **Connect**. 3. Sign in to your Google account and grant the requested permissions. On Team and Enterprise plans, an Owner or Primary Owner must enable the integration for your organization before it appears in your connector list. For the full walkthrough, including troubleshooting, see [Get started with connectors](/docs/connectors/getting-started). ## How to use Gmail integration ### 1. Ask a question Simply ask Claude a question that needs email information. Claude automatically detects when email data is needed. **Example questions:** * "What did Sarah say about the project deadline?" * "Find emails about the Q4 budget review" * "Summarize my conversation with the sales team last week" ### 2. Review Claude's response Claude provides answers that include: * Clear answers to your questions * Citations indicating which emails were used * Links to original sources when applicable ### 3. Follow up You can ask for more details, such as: * Requesting additional email information * Finding related threads * Summarizing longer conversations ## Understanding citations Citations show which specific emails Claude used to answer your question. You can follow links back to original sources for verification and additional context. ## Privacy and data handling ### Authentication You must authenticate directly to your Google account. For Claude for Work (Team/Enterprise) plans, an Owner or Primary Owner must enable integrations at the account level. ### Data access * Claude accesses only data from your connected Google account * Access occurs only when you explicitly request it * Minimum information is retrieved to answer your question * Your existing Gmail permissions are mirrored ## Limitations * Claude cannot create, send, or modify emails * Embedded images in emails are not visible to Claude * Only emails you have access to can be searched ## Related topics Access your calendar information. Connect your documents. # Authenticate to MCP servers behind a tunnel Source: https://claude.com/docs/connectors/mcp-tunnels/oauth Make OAuth sign-in work for MCP servers reached through an MCP tunnel when the authorization server or identity provider is inside your network. Covers the Tunnel OAuth configuration fields (issuer, authorization endpoint, token endpoint, registration endpoint, scopes) and the split-metadata alternative. MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team. An MCP tunnel carries Claude's requests to an MCP server inside your network, but it does not authenticate to that server. Each tunneled server should still require OAuth, as the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) describes, so that a member signs in with their own account before Claude can call the server's tools. This page is for the administrator adding a tunneled server as a custom connector, and explains what to configure when the OAuth authorization server is itself only reachable inside your network. If your authorization server is reachable from the public internet and its metadata advertises public URLs, you don't need anything on this page. Add the connector as described in [Set up an MCP tunnel](/docs/connectors/mcp-tunnels/setup#add-tunneled-servers-as-connectors) and members sign in as they would for any other connector. ## How OAuth works through a tunnel Two different parties make requests during an OAuth sign-in, and they reach your authorization server by different paths. * **The member's browser** is redirected to the authorization endpoint to sign in and approve access. This request comes from the member's device, so the authorization endpoint must be a URL their browser can load, either on the public internet or on your corporate network. It can't be a `tunnel.anthropic.com` hostname, because tunnel hostnames accept connections only from Claude. * **Claude's servers** fetch the authorization server's metadata, register an OAuth client if the server supports dynamic registration, and exchange the authorization code for tokens at the token endpoint. These requests come from Anthropic's network, so the endpoints must be reachable from there, either publicly or through the tunnel. By default Claude discovers all of these URLs from the metadata your MCP server and authorization server publish. When the authorization server sits inside your network, that metadata usually advertises internal hostnames. Claude then can't reach the token endpoint, or the member's browser is sent to an address it can't load, and sign-in fails. You fix this by routing Claude's server-to-server calls through the tunnel and telling Claude explicitly which URL to use for each endpoint. ## Route the authorization server through the tunnel Add a route for the authorization server to the proxy configuration, next to the routes for your MCP servers, and apply it as described in [Add more servers later](/docs/connectors/mcp-tunnels/setup#add-more-servers-later). ```yaml theme={null} routes: docs: http://docs-mcp.example.corp:8080 auth: https://sso.example.corp:8443 ``` With a tunnel domain of `abc123.tunnel.anthropic.com`, Claude can now reach the authorization server at `https://auth.abc123.tunnel.anthropic.com`. For an `https://` upstream like this one, also set `upstream.tls.ca_file` or `upstream.tls.include_system_cas` in the proxy configuration so the proxy can verify the server's certificate. See the [proxy configuration reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#proxy-configuration). ## Set the Tunnel OAuth configuration When you add the tunneled MCP server as a custom connector in **Organization settings > Connectors**, turn on **Tunnel OAuth configuration** in the connector dialog. The values you enter replace the ones Claude would otherwise read from the authorization server's metadata. Anthropic enables this option for each organization in the research preview on request, so if the toggle does not appear in the dialog, contact your Anthropic account team. | Field | What to enter | Example | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | **Issuer** | The issuer identifier your authorization server puts in its metadata and tokens. This can be an internal URL, because Claude uses it for validation rather than as an address to connect to. | `https://sso.example.corp:8443` | | **Authorization endpoint** | The sign-in URL that members' browsers are redirected to. It must be loadable from their devices, on the public internet or your corporate network. | `https://sso.example.corp/authorize` | | **Token endpoint** | The token endpoint Claude exchanges the authorization code at. Either the endpoint as reached through the tunnel (an `https://` URL under your tunnel domain), or a public `https://` URL on the same origin (scheme, host, and port) as the **Authorization endpoint**. | `https://auth.abc123.tunnel.anthropic.com/oauth/token` | | **Registration endpoint (optional)** | The dynamic client registration endpoint, under the same rule as **Token endpoint**: a URL under your tunnel domain or one on the **Authorization endpoint**'s origin. Leave it blank if you select **Use your own OAuth client** and enter a client ID you registered with the authorization server yourself. | `https://auth.abc123.tunnel.anthropic.com/oauth/register` | | **Requested scopes** | The scopes Claude requests at sign-in, separated by spaces. | `openid wiki:read wiki:write` | The paths after the hostname (`/authorize`, `/oauth/token`, and so on) are whatever your authorization server uses. Copy them from its metadata document, usually served at `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration`, and change only the scheme and host. After you save the connector, connect it yourself from your own connector settings. Your browser should land on your sign-in page, and after you approve access the connector should show as connected. If either step fails, see [Troubleshooting](/docs/connectors/mcp-tunnels/troubleshooting#sign-in-redirects-to-a-tunnel-address-that-does-not-load). ## Publish split metadata instead If you operate the authorization server and can change the metadata it publishes, you can get the same result without the connector settings by advertising the split yourself. Point `authorization_endpoint` at the browser-reachable hostname and every other endpoint at the tunnel hostname in the authorization server's `/.well-known/oauth-authorization-server` document: ```json theme={null} { "issuer": "https://auth.abc123.tunnel.anthropic.com", "authorization_endpoint": "https://sso.example.corp/authorize", "token_endpoint": "https://auth.abc123.tunnel.anthropic.com/oauth/token", "registration_endpoint": "https://auth.abc123.tunnel.anthropic.com/oauth/register", "code_challenge_methods_supported": ["S256"] } ``` Then have the MCP server's `/.well-known/oauth-protected-resource` document name the tunnel hostname as its authorization server: ```json theme={null} { "resource": "https://docs.abc123.tunnel.anthropic.com/mcp", "authorization_servers": ["https://auth.abc123.tunnel.anthropic.com"] } ``` This approach also suits an authorization server that is publicly reachable but sits behind a source-IP allowlist that you don't want to open to Anthropic's egress ranges. The [platform troubleshooting guide](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#oauth-fails-behind-a-source-ip-allowlist) walks through the same configuration. Use **Tunnel OAuth configuration** when the authorization server is a product whose metadata you can't edit, or when you prefer to keep tunnel-specific addresses out of the server's configuration. Use split metadata when you control the authorization server and want the configuration to apply to every client that discovers it through the tunnel. # MCP tunnels Source: https://claude.com/docs/connectors/mcp-tunnels/overview Connect Claude to MCP servers inside your private network without opening inbound firewall ports or exposing the servers to the internet. How MCP tunnels work, what you deploy, network and plan requirements, and the security model. MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team. The preview is provided as-is, without uptime, support, or continuity commitments, and it depends on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time. MCP tunnels connect Claude to [Model Context Protocol (MCP)](/docs/connectors/building/mcp) servers that run inside your private network. You run a small tunnel stack on a host in your network, the stack opens an outbound-only connection to Anthropic, and Claude sends MCP requests to your servers over that connection. Your firewall needs no inbound rules and your MCP servers need no public endpoint. Members of your organization use the tunneled servers as [custom connectors](/docs/connectors/custom/remote-mcp) in Claude, the same way they use any other remote MCP server. This section is for administrators of claude.ai organizations on the Enterprise plan and the infrastructure teams they work with. To use MCP tunnels with the Claude Console, Claude Managed Agents, or the Messages API, see [MCP tunnels in the Claude Platform docs](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview). A tunnel belongs to the organization that created it, so a tunnel created from a Console organization can't serve connectors in claude.ai, and a tunnel created from claude.ai can't serve the API. ## When to use an MCP tunnel Use a tunnel when the MCP server your organization wants to reach from Claude is only reachable inside your network, and your security policy rules out giving it a public endpoint or allowlisting Anthropic's IP ranges at your edge. Internal knowledge bases, ticketing systems, and data services wrapped in an MCP server are typical candidates. If the MCP server is already reachable from the internet, you don't need a tunnel. Add it as a [custom connector](/docs/connectors/custom/remote-mcp) directly. ## How traffic flows The tunnel stack is two containers that you run inside your network, from images that Anthropic and Cloudflare publish: * **cloudflared** is Cloudflare's open-source tunnel connector. It dials out from your network to the tunnel edge and keeps that connection open. It never listens on an inbound port. * **The proxy** (`mcp-proxy`) is Anthropic's routing component. It terminates an inner layer of TLS, checks that each destination address falls inside an allowed private range, and forwards each request to the right MCP server based on the hostname it was sent to. When you create a tunnel, Anthropic assigns it a domain such as `abc123.tunnel.anthropic.com`. Each MCP server you expose gets a subdomain of that domain, chosen by you in the proxy's route configuration. A route named `docs` that points at `http://docs-mcp.example.corp:8080` makes that server reachable from Claude at `https://docs.abc123.tunnel.anthropic.com`. A request then travels like this: 1. cloudflared opens an outbound connection from your network to the tunnel edge on port 7844 and holds it open. 2. A member uses the connector in Claude. Claude sends the MCP request to `docs.abc123.tunnel.anthropic.com`, and the request travels over the already-open connection to cloudflared and then to the proxy. 3. The proxy decrypts the request, looks up the `docs` route, and forwards the request to `docs-mcp.example.corp:8080`. The response returns along the same path. Hostnames under `tunnel.anthropic.com` accept connections only from Claude. You can't open them in a browser or test them with `curl` from your own network, so you verify a tunnel by using it from Claude. ## What you need * A claude.ai organization on the Enterprise plan with MCP tunnels enabled. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team. * The Owner or Primary Owner role in that organization, to create the API key the tunnel setup uses and to add the tunneled servers as connectors. * A place to run the tunnel stack inside your network: a Kubernetes cluster (deployed with Helm) or a Linux host with Docker and Docker Compose. One stack serves one tunnel, and you can run replicas of it on several hosts for availability. * One or more MCP servers that speak the Streamable HTTP transport and are reachable from that cluster or host. * Outbound network access from the stack as listed under [Network requirements](#network-requirements). ### Network requirements | Component | Destination | Port and protocol | Used during | | --------------- | ---------------------------------------------------- | ---------------------------- | ---------------------------- | | Setup component | `api.anthropic.com` | 443 TCP | Provisioning, token rotation | | cloudflared | Tunnel edge (`198.41.192.0/19`, `2606:4700:a0::/44`) | 7844 TCP and UDP | Runtime | | Proxy | Your MCP servers | As configured in your routes | Runtime | No inbound rules are required. See [Cloudflare's tunnel firewall documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-with-firewall/) for the authoritative edge IP list. ## Security model Three independent layers protect every request through a tunnel. | Layer | Protects against | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Outer mutual TLS between Anthropic and the transport provider, with IP validation | Unauthorized clients reaching the tunnel | | Inner TLS from Anthropic's backend to your proxy | Payload inspection by the transport provider or any network intermediary | | OAuth on each MCP server | Unauthorized use of MCP tools by traffic that has reached the server | The proxy terminates inner TLS with a certificate signed by a certificate authority (CA) that the setup component generates inside your environment and registers with Anthropic. Only your deployment holds the private keys, so Cloudflare carries ciphertext and cannot read MCP requests or responses. Anthropic does not connect to a tunnel until a CA certificate is registered for it. Cloudflare does receive connection metadata: the egress IP address and a host fingerprint of the machine running cloudflared, connection timing and byte volume, and the `tunnel.anthropic.com` subdomain assigned to your tunnel. Cloudflare acts as a subprocessor for this research preview. The tunnel carries traffic to your MCP servers but does not authenticate to them. Configure each MCP server to require OAuth as described in the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), and see [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth) for how sign-in works when the authorization server is also inside your network. ### Shared responsibility | Anthropic handles | Your organization handles | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Restricting tunnel access so that only Anthropic can connect | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies, including Cloudflare's | | Validating your CA certificate before connecting to your proxy | Securing the tunnel token, the Tunnels API key, and the TLS private keys | | Sending Claude's requests only to tunnels that your organization owns | Renewing the server certificate before it expires | | | Requiring OAuth on each MCP server and limiting each server to the tools it needs | | | Restricting network access for the proxy hosts and MCP servers | | | Notifying Anthropic if you suspect a compromise | An attacker who obtains your tunnel token and one of your TLS private keys could impersonate your proxy and read MCP request payloads, including OAuth tokens. Store both with your organization's secrets-management controls, restrict file permissions, and rotate them on a schedule and immediately after any suspected exposure. See [Rotate credentials](/docs/connectors/mcp-tunnels/setup#rotate-credentials). ## Limits * An organization can have up to 10 active tunnels. * A tunnel holds up to two active CA certificates at a time, so you can rotate without downtime. * The server certificate that the setup component generates is valid for 90 days. * The proxy connects to upstream MCP servers over IPv4 only, and by default only to addresses in the RFC 1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`). ## Next steps Create the API key, deploy the tunnel stack with Helm or Docker Compose, and add your servers as connectors. Make OAuth sign-in work when your authorization server is inside your network. Diagnose connection, certificate, routing, and sign-in failures. Proxy configuration fields, certificate requirements, and the setup component. # Set up an MCP tunnel Source: https://claude.com/docs/connectors/mcp-tunnels/setup Create a Tunnels API key in claude.ai, deploy the MCP tunnel stack with Helm or Docker Compose, verify the connection, add tunneled MCP servers as custom connectors, rotate the tunnel token and certificates, and remove a tunnel. MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team. This page covers the full setup of an MCP tunnel for a claude.ai Enterprise organization, from creating the API key that provisioning uses to members calling a tunneled MCP server from Claude. You need the Owner or Primary Owner role in claude.ai, and someone who can deploy containers to a Kubernetes cluster or a Docker host inside your network. Read [MCP tunnels](/docs/connectors/mcp-tunnels/overview) first if the tunnel stack, the tunnel domain, and routes are unfamiliar. The deployment steps on this page are reference deployments. You are responsible for adapting them to your organization's security requirements. For the full set of proxy options, certificate requirements, and hardening guidance, see the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) and [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) pages in the Claude Platform docs. Those pages describe the Claude Console flow, which authenticates the setup component differently. For a claude.ai organization, follow the authentication steps on this page. ## Create a Tunnels API key The setup component that runs alongside the tunnel stack needs a short-lived credential to create the tunnel, register its certificate authority (CA) certificate with Anthropic, and fetch the tunnel token. In claude.ai that credential is a Tunnels API key. 1. In claude.ai, go to **Organization settings > Tunnels**. This page appears once Anthropic has enabled MCP tunnels for your organization. 2. Open **Tunnels API** and create a key. 3. Copy the key somewhere safe for the next section. You pass it to the setup component once. The tunnel stack does not use the key at runtime. Revoke the key as soon as setup completes, and create a fresh one later when you rotate the tunnel token. ## Deploy the tunnel stack Choose Helm if you run Kubernetes. The chart provisions the tunnel, stores the credentials in a Secret, and renews the server certificate automatically. Choose Docker Compose for a single host or a VM, where you run the setup component and certificate renewal yourself. Both paths need at least one route. A route maps a subdomain of your tunnel domain to the internal URL of an MCP server, in the form `scheme://host:port` with no path. The examples use `docs` pointing at `http://docs-mcp.example.corp:8080`. Replace them with your own servers. ```bash theme={null} helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > values.yaml ``` The file includes comments explaining each field. Edit `values.yaml` and add a `routes` entry under `gateway.config` for each MCP server. Leave `tunnel.id` empty so the setup component creates the tunnel during install. ```yaml values.yaml theme={null} tunnel: id: "" # Increment to rotate the tunnel token on a later upgrade. tokenVersion: "1" gateway: config: routes: docs: http://docs-mcp.example.corp:8080 search: http://10.0.12.7:9000 ``` With these routes, Claude reaches the servers at `docs.` and `search.`. If a route targets an address outside the RFC 1918 private ranges (some managed Kubernetes distributions allocate Service IPs elsewhere), add the range under `gateway.config.upstream.allowed_ips` as described in [Troubleshooting](/docs/connectors/mcp-tunnels/troubleshooting#proxy-logs-ip-validation-failed). Render the chart with a placeholder key and review the output according to your organization's practices for third-party manifests. Rendering makes no API calls. ```bash theme={null} helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml \ --set api.token=placeholder > rendered.yaml ``` Read the Tunnels API key into an environment variable so it stays out of your shell history and values file, then install into a dedicated namespace. ```bash theme={null} # Paste the Tunnels API key (input is hidden) read -rs API_TOKEN && export API_TOKEN helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml \ --set api.token="$API_TOKEN" ``` The setup component runs as a pre-install hook, so `helm install` blocks until the tunnel is created, the CA is registered, and the credentials are stored in the `mcp-tunnel` Secret. If the install fails with a hook error, see [Troubleshooting](/docs/connectors/mcp-tunnels/troubleshooting#helm-install-fails-with-a-hook-error). Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** as soon as the install completes. Helm records `--set` values in its release history Secrets, and Kubernetes Secrets are not encrypted at rest by default, so the key remains recoverable from the cluster until you revoke it. You need the tunnel domain to add connectors later. ```bash theme={null} kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d ``` The value looks like `abc123.tunnel.anthropic.com`. To restrict the pod's egress at the network level, set `networkPolicy.enabled: true` in `values.yaml` and list your MCP servers under `networkPolicy.mcpServers`. The policy already allows cloudflared to reach the tunnel edge. Your cluster's network plugin must support NetworkPolicy. For later configuration changes such as routes or replica count, edit `values.yaml` and run `helm upgrade` with the same `--version` and `-f values.yaml`, without the API key. Keep a complete `values.yaml` rather than relying on `--reuse-values`, because Helm's deep merge can silently keep a route you deleted. ```bash theme={null} mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data ``` The containers run as the non-root user ID `65532` and need write access to `data/`. The compose file pins images by digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation. ```bash theme={null} cat > docker-compose.yaml <<'EOF' services: # One-time provisioning. Run with: docker compose run --rm setup setup: image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013 entrypoint: ["/setup"] command: - init - --api-url=https://api.anthropic.com - --output=dir:/data - --token-version=1 environment: - API_TOKEN volumes: - ./data:/data user: "65532:65532" read_only: true security_opt: - no-new-privileges:true cap_drop: - ALL profiles: ["setup"] cloudflared: image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0 command: tunnel --no-autoupdate run --url http://localhost:8080 environment: - TUNNEL_TOKEN # Share the proxy's network namespace so localhost:8080 reaches it. network_mode: "service:mcp-proxy" restart: unless-stopped user: "65532:65532" read_only: true security_opt: - no-new-privileges:true cap_drop: - ALL stop_grace_period: 30s logging: options: max-size: "10m" max-file: "3" mcp-proxy: image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013 volumes: - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro - ./data:/data:ro restart: unless-stopped user: "65532:65532" read_only: true security_opt: - no-new-privileges:true cap_drop: - ALL # Match shutdown_timeout in the proxy config stop_grace_period: 30s logging: options: max-size: "10m" max-file: "3" EOF ``` Read the Tunnels API key into an environment variable, then run the setup component. It creates the tunnel, generates the CA and server certificate, registers the CA with Anthropic, fetches the tunnel token, and writes everything to `data/`. ```bash theme={null} # Paste the Tunnels API key (input is hidden) read -rs API_TOKEN && export API_TOKEN docker compose run --rm setup ``` Read the tunnel domain and keep it for later steps. ```bash theme={null} export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN" ``` Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** before continuing, and run `unset API_TOKEN`. The stack does not need the key at runtime. `tunnel_domain` is required so the proxy can strip the domain from incoming hostnames and look up the remaining subdomain in `routes`. `routes` is a map, not a list. ```bash theme={null} cat > config/mcp-proxy.yaml < ```bash theme={null} export TUNNEL_TOKEN=$(sudo cat data/tunnel-token) docker compose up -d ``` The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so repeat the export in every fresh shell and after a reboot. For a multi-host deployment, copy the `mcp-tunnel/` directory to each host and start it the same way. The same tunnel token and certificates work across all replicas. The `data/` directory now holds the tunnel ID, tunnel domain, tunnel token, CA key pair, and server key pair. Protect it with your organization's file-permission, encryption-at-rest, and secrets-management controls, and consider moving `ca.key` and `tunnel-token` to secure storage. ## Verify the connection Check the logs on your side first. cloudflared logs four `Registered tunnel connection` lines when it has reached the tunnel edge, and the proxy logs one `route configured` line per route. ```bash Helm theme={null} kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c cloudflared | grep "Registered tunnel connection" kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy | grep "route configured" ``` ```bash Docker Compose theme={null} docker compose logs cloudflared | grep "Registered tunnel connection" docker compose logs mcp-proxy | grep "route configured" ``` The containers take a few seconds to start, so rerun the commands if they come back empty. If cloudflared never registers, see [Troubleshooting](/docs/connectors/mcp-tunnels/troubleshooting#the-tunnel-stack-starts-but-cloudflared-never-connects). The end-to-end check happens from Claude, in the next section. ## Add tunneled servers as connectors Each route becomes a custom connector for your organization. The connector URL is the route's tunnel hostname plus the path your MCP server serves. Many servers serve at `/mcp`, and the proxy forwards the path unchanged. 1. In claude.ai, go to **Organization settings > Connectors**. 2. Select **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**. 3. Enter the server URL, for example `https://docs.abc123.tunnel.anthropic.com/mcp`. 4. Configure authentication for the server. If its OAuth authorization server is also inside your network, turn on **Tunnel OAuth configuration** and follow [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth). 5. Select **Add**. Members then find the connector in their own connector settings and select **Connect** to sign in, as described in [Third party connectors with remote MCP](/docs/connectors/custom/remote-mcp#adding-custom-connectors). To confirm the tunnel end to end, connect the server yourself and ask Claude to use one of its tools while you watch the proxy logs for the request. ### Add more servers later Add a route for the new server, apply the change, and register the new hostname as another custom connector. No certificate or cloudflared changes are needed, because the server certificate covers every subdomain of your tunnel domain. ```bash Helm theme={null} # After adding the route under gateway.config.routes in values.yaml helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml ``` ```bash Docker Compose theme={null} # After adding the route in config/mcp-proxy.yaml docker compose restart mcp-proxy ``` ## Rotate credentials Three credentials are involved, and each rotates differently. **Tunnels API key.** Used only while the setup component runs. Revoke it after every use and create a new one in **Organization settings > Tunnels > Tunnels API** when you next need to run setup. **Tunnel token.** Authenticates cloudflared's outbound connection. Rotate it on your regular schedule and immediately if you suspect exposure. Rotation does not sever connections that are already established, so you can rotate, restart cloudflared with the new value, and let the old connections drain. Increment `tunnel.tokenVersion` in `values.yaml`, create a fresh Tunnels API key, and upgrade. The setup component re-runs, rotates the token, and updates the Secret. ```bash theme={null} read -rs API_TOKEN && export API_TOKEN helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml \ --set api.token="$API_TOKEN" \ --set setup.force=true ``` Revoke the API key once the upgrade completes. Edit `docker-compose.yaml` and increment the `--token-version` value in the `setup` service (for example from `1` to `2`), so the new value persists for future runs. Then create a fresh Tunnels API key and re-run setup. ```bash theme={null} read -rs API_TOKEN && export API_TOKEN docker compose run --rm setup export TUNNEL_TOKEN=$(sudo cat data/tunnel-token) docker compose up -d cloudflared ``` Revoke the API key and run `unset API_TOKEN` once rotation completes. For a multi-host deployment, setup writes the new token only to the `data/` directory on the host where it ran, so copy the updated `data/` directory (at minimum `data/tunnel-token`) to every other host that runs a replica. Then repeat the last two commands on each of those hosts so every replica restarts with the new token. **Server certificate.** The certificate the proxy presents is valid for 90 days, and you are responsible for renewing it before it expires. Renewal is local. It signs a new certificate with the CA already stored in your deployment, makes no API calls, and needs no API key. The proxy reloads the certificate file automatically, so no restart is required. The chart deploys a CronJob that runs daily and renews the certificate once it is within 30 days of expiry. Monitor the CronJob and the certificate's expiry date to confirm renewal completes. Run the renewal from the deployment directory. With `--renew-before=720h` the command does nothing while more than 30 days of validity remain, so it is safe to run on a schedule such as a daily cron entry. ```bash theme={null} docker compose run --rm setup renew-cert --output=dir:/data --renew-before=720h ``` ## Remove a tunnel Decommission a tunnel when you no longer need it, or as the first steps of responding to a suspected compromise. Archiving a tunnel invalidates its token, detaches its domain, and is permanent. ```bash Helm theme={null} TUNNEL_ID=$(kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-id}' | base64 -d) ``` ```bash Docker Compose theme={null} TUNNEL_ID=$(sudo cat data/tunnel-id) ``` ```bash Helm theme={null} helm uninstall mcp-tunnel -n mcp-tunnel ``` ```bash Docker Compose theme={null} docker compose down ``` If you are responding to a suspected compromise, use `docker compose down --timeout 0` to sever the connection immediately. In **Organization settings > Connectors**, remove each custom connector that points at the tunnel's hostnames. Create a fresh Tunnels API key and call the [archive endpoint](https://platform.claude.com/docs/en/api/beta/tunnels/archive) of the Tunnels API. Revoke the key when you are done. ```bash theme={null} read -rs API_TOKEN && export API_TOKEN curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \ -H "Authorization: Bearer $API_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mcp-tunnels-2026-06-22" ``` ```bash Helm theme={null} # The setup component created this Secret, so helm uninstall leaves it behind kubectl -n mcp-tunnel delete secret mcp-tunnel ``` ```bash Docker Compose theme={null} sudo rm -rf data ``` If you archived the tunnel because of a suspected compromise, also notify your Anthropic account team, rotate any OAuth tokens or secrets your MCP servers issued, and review the proxy, cloudflared, and MCP server logs for the affected period before you provision a replacement tunnel. # Troubleshoot MCP tunnels Source: https://claude.com/docs/connectors/mcp-tunnels/troubleshooting Fix MCP tunnel problems: cloudflared won't connect, connector added but tools don't appear, no route for host, IP validation failed, TLS handshake failed, expired certificate, OAuth sign-in redirects to a tunnel.anthropic.com URL, token exchange fails, and setup or Helm hook errors. MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team. A request through an [MCP tunnel](/docs/connectors/mcp-tunnels/overview) can fail at three points, and it helps to check them in order. First the outbound connection from cloudflared to the tunnel edge, then the inner TLS handshake between Anthropic and your proxy, then the proxy's routing to your MCP server. The cloudflared and proxy logs on your side show which point a request reached. If the proxy logs nothing at all for a request, it never arrived in your network. ```bash Helm theme={null} kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c cloudflared kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy ``` ```bash Docker Compose theme={null} docker compose logs cloudflared docker compose logs mcp-proxy ``` For proxy configuration fields and certificate rules referenced below, see the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference). The [platform troubleshooting guide](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting) covers the same stack and applies to claude.ai tunnels as well, apart from its Console-specific steps. ## Connection ### The tunnel stack starts but cloudflared never connects cloudflared logs four `Registered tunnel connection` lines when it reaches the tunnel edge. If they never appear, the cause is almost always one of two things. Either `TUNNEL_TOKEN` is missing, truncated, or from a token that has since been rotated, or a firewall is blocking outbound TCP and UDP on port 7844 to the edge ranges `198.41.192.0/19` and `2606:4700:a0::/44`. On Docker Compose, confirm the variable is exported in the shell that ran `docker compose up`. After a token rotation, restart cloudflared on every host with the new value. ### cloudflared logs `failed to sufficiently increase receive buffer size` This is a QUIC tuning hint, not an error, and the tunnel works without addressing it. To remove the warning, raise the host's UDP buffer limits as described in the [quic-go UDP buffer documentation](https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes). ### The setup component fails with an authentication or permission error The setup component authenticates to the Tunnels API with the key in `API_TOKEN` (Docker Compose) or `api.token` (Helm). A `401` or `403` means the key was revoked, was copied incompletely, or was created in a different organization from the one where MCP tunnels are enabled. Create a new key under **Organization settings > Tunnels > Tunnels API** in the claude.ai organization whose members will use the connectors, and run setup again. ### Setup fails with `Organization already has the maximum of 10 non-archived Tunnels` Each organization can have at most 10 tunnels that are not archived, and every setup run with an empty `tunnel.id` (Helm) or no `--tunnel-id` (Docker Compose) creates a new one. Archive tunnels you no longer use, as described in [Remove a tunnel](/docs/connectors/mcp-tunnels/setup#remove-a-tunnel), then run setup again. To attach a new deployment to an existing tunnel instead of creating one, set `tunnel.id` in `values.yaml` or pass `--tunnel-id` to the setup command. ### Helm install fails with a hook error The setup component runs as a pre-install hook Job, and on failure Helm leaves the Job behind for inspection. Read its logs, then delete it before retrying, because Helm does not manage hook resources. ```bash theme={null} kubectl -n mcp-tunnel logs job/mcp-tunnel-setup helm uninstall mcp-tunnel -n mcp-tunnel kubectl -n mcp-tunnel delete job mcp-tunnel-setup ``` ### A tunnel hostname does not respond to curl or a browser This is expected. Hostnames under `tunnel.anthropic.com` accept connections only from Claude, so you can't test them from your own network or the internet. Verify the tunnel by connecting the custom connector in Claude and calling one of the server's tools while you watch the proxy logs. ## Routes and certificates ### Proxy logs `no route for host` The hostname Claude sent the request to did not match any route. Check that `tunnel_domain` in the proxy configuration exactly matches the domain the setup component reported (Helm sets this for you), that the subdomain in the connector URL matches a key under `routes`, and that you restarted the proxy or ran `helm upgrade` after editing routes. ### Proxy logs `IP validation failed` The full message is `IP validation failed: is not a private address`, and it means the MCP server's hostname resolved to an address outside the ranges the proxy is allowed to dial. By default those are the RFC 1918 private ranges, over IPv4 only. Check what the hostname resolves to from the proxy's host: ```bash theme={null} dig +short docs-mcp.example.corp ``` If the address is legitimate, for example a Kubernetes Service range that your distribution allocates outside RFC 1918, add the narrowest covering range to `upstream.allowed_ips`. Setting `allowed_ips` replaces the default rather than extending it, so list the private ranges your other servers use as well. ```yaml theme={null} upstream: allowed_ips: - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - 100.64.12.0/22 # example: a cluster Service range outside RFC 1918 ``` Don't set `0.0.0.0/0` or `disable_ip_validation` outside of isolated testing. IP validation is the proxy's protection against server-side request forgery. ### Proxy exits with `cannot unmarshal !!seq into map[string]string` `routes` was written as a YAML list. It must be a map from subdomain to upstream URL, for example `routes: { docs: "http://docs-mcp.example.corp:8080" }`. ### Proxy exits with `invalid upstream (must be scheme://host:port)` A route value includes a path or omits the port. Each upstream must be exactly `scheme://host:port`. Put the path in the connector URL instead, because the proxy forwards the request path unchanged. ### Proxy logs `tls handshake failed` Anthropic rejected the certificate the proxy presented. Check that the server certificate has not passed its 90-day validity, that its Subject Alternative Name covers `*.`, and that it was signed by the CA the setup component registered for this tunnel. On Docker Compose, also confirm the files in `data/` are readable by user ID `65532`. To renew an expired certificate, see [Rotate credentials](/docs/connectors/mcp-tunnels/setup#rotate-credentials). ## Connectors and tools ### Adding the connector fails, or it connects but no tools appear Work through these checks in order. 1. Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup#verify-the-connection). 2. Confirm the tunnel was created with a Tunnels API key from the same claude.ai organization where you are adding the connector. A tunnel created from another organization, including a Claude Console organization, is refused before any traffic reaches your network, and your proxy logs show nothing. 3. Confirm the connector URL includes the path your MCP server serves, such as `/mcp`. A request to the bare hostname reaches the proxy but the server may answer `404`. 4. Watch the proxy logs while you retry. `no route for host` and `IP validation failed` point to the sections above. An upstream connection error means the proxy can't reach the MCP server from where it runs. ## OAuth sign-in See [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth) for how the sign-in flow splits between the member's browser and Claude's servers. ### Sign-in redirects to a tunnel address that does not load The authorization server's metadata advertises an authorization endpoint on the `tunnel.anthropic.com` hostname or an internal hostname, and the member's browser can't load it. Turn on **Tunnel OAuth configuration** for the connector and set **Authorization endpoint** to the sign-in URL members' browsers can reach, or publish split metadata from the authorization server. Both are described on the [OAuth page](/docs/connectors/mcp-tunnels/oauth#set-the-tunnel-oauth-configuration). ### Sign-in succeeds in the browser but the connector never connects Claude could not complete the token exchange, usually because the token endpoint in the metadata is an internal hostname or sits behind a source-IP allowlist. Add a proxy route for the authorization server and set **Token endpoint** (and **Registration endpoint**, if you rely on dynamic client registration) to the corresponding `https://./...` URLs. Then watch the proxy logs during sign-in to confirm the token request arrives and the authorization server answers it. ### The Token endpoint field rejects the URL **Token endpoint** and **Registration endpoint** accept an `https://` URL that is either under `tunnel.anthropic.com` or on the same origin (scheme, host, and port) as the **Authorization endpoint**. Any other URL is rejected, because Claude sends the token exchange and the client credentials to it. Add a route for your authorization server as shown in [Route the authorization server through the tunnel](/docs/connectors/mcp-tunnels/oauth#route-the-authorization-server-through-the-tunnel) and enter the resulting tunnel URL. The **Authorization endpoint** field has no such restriction, because browsers load it directly. ### The Tunnel OAuth configuration toggle is missing Anthropic enables the option for each organization in the research preview on request. Contact your Anthropic account team. ## Get help If these steps don't resolve the problem, contact your Anthropic account team with the tunnel domain, the time of a failed request, and the relevant cloudflared and proxy log lines. # Microsoft 365 connector Source: https://claude.com/docs/connectors/microsoft/365 Connect SharePoint, OneDrive, Outlook, and Teams to Claude The Microsoft 365 connector enables Claude to search, analyze, and act on information across SharePoint, OneDrive, Outlook, and Teams. Available on all Claude plans: Free, Pro, Max, Team, and Enterprise. On Team and Enterprise plans, an organization Owner must enable the connector before members can connect. ## Capabilities With this connector, Claude can: * **Search and analyze documents** across SharePoint sites and OneDrive libraries * **Access email threads** and analyze Outlook communications * **Review meeting information** from Teams Calendar * **Pull insights** from Teams Chat discussions * **Send and manage email**, including drafts, labels, mail filters, and automatic replies * **Manage calendar events** and find meeting times * **Create and update files** in SharePoint ## Setup requirements On Free, Pro, and Max plans, no organization-level setup is needed. Connect from **Customize > Connectors** in claude.ai. A Microsoft Entra Global Administrator still needs to grant one-time tenant consent for your Microsoft organization. ### Prerequisites * A work or school Microsoft account on a Microsoft Entra tenant (personal accounts such as outlook.com, hotmail.com, or live.com aren't supported) * Claude user with Owner or Primary Owner role (Team and Enterprise plans) * Global Administrator access to Microsoft Entra tenant * Active Microsoft 365 accounts for all users (Team and Enterprise plans) ### Phase 1: Administrator setup **Automatic Setup (Recommended):** 1. Navigate to **Organization settings > Connectors** 2. Select **Add**, then **All available** 3. Find Microsoft 365 and select "Add to your team" 4. Connect individually and grant organization-wide permissions 5. (Optional) Restrict user access or revoke specific permission scopes ### Phase 2: User enablement Once enabled by administrators, team members: 1. Navigate to **Customize > Connectors** 2. Find Microsoft 365 and click "Connect" 3. Authenticate with credentials ## Usage Ask Claude questions requiring Microsoft 365 data, or ask Claude to take an action such as sending an email or updating a file. Claude automatically detects and uses the necessary tools. ### Example queries * "Find the Q4 strategic planning document in SharePoint" * "Summarize email conversations about the product launch" * "What discussions happened in Teams about the marketing campaign?" * "Review meeting notes from last week's leadership sync" * "Draft a reply to the latest email about the vendor contract" * "Schedule a 30-minute sync with the design team next week" ## What you can access | Service | Capabilities | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | **SharePoint/OneDrive** | Search and analyze documents; create and update files in SharePoint | | **Outlook** | Search email threads and archived emails; send and manage mail; create, update, and delete calendar events | | **Teams Calendar** | Review meeting summaries and attendance | | **Teams Chat** | Access channel and chat discussions | ## Write actions Claude can take actions in Outlook and SharePoint: send mail and manage drafts; organize mail with labels, filters, and trash; set automatic replies; create, update, and delete calendar events; and create and update files in SharePoint. Read and search tools work the same whether or not write actions are enabled. Write actions are controlled by your organization's administrators in two places: 1. **Approve the write permissions.** If your tenant's consent for the connector covers only read permissions, a Microsoft Entra Global Administrator or Application Administrator approves the updated permission set (mail, calendar, mailbox settings, and file writes) under **Enterprise applications** in the Entra admin center. This is a one-time action per tenant. 2. **Turn on write actions.** If write actions are off for your organization, administrators turn them on for all users in the Microsoft 365 connector configuration, or enable them for specific users with role-based access control (beta). Claude cannot attach files to the drafts it creates and cannot send Teams messages. For setup steps, see [Connect to Microsoft 365](https://support.claude.com/en/articles/15183774-connect-to-microsoft-365) and [Set up the Microsoft 365 connector](https://support.claude.com/en/articles/12542951-set-up-the-microsoft-365-connector) in the help center. The [Microsoft 365 connector security guide](https://support.claude.com/en/articles/12684923-microsoft-365-connector-security-guide) covers the permission model. ## Permissions All permissions are delegated: Claude acts on behalf of users and can only access and change content that you already have permission to access and change in Microsoft 365. Write actions are available when your administrators enable them (see [Write actions](#write-actions)). ## Troubleshooting * Verify correct Microsoft 365 credentials * Check active license status * Review organizational third-party app policies * Try a different browser * Clear cookies and cache * Verify direct access to the document in Microsoft 365 * Ensure document is in SharePoint/OneDrive (not local) * Recently uploaded documents may need time to index * Use specific SharePoint site names * Search by exact filename * Be more specific about requirements * Specify locations and date ranges * Use exact phrases * Break complex queries into simpler questions # Connectors overview Source: https://claude.com/docs/connectors/overview Connect Claude to external tools, data, and UI through MCP Connectors extend Claude's capabilities by connecting it to external tools and data sources. They are powered by the [Model Context Protocol (MCP)](/docs/connectors/building/mcp), an open standard created by Anthropic that provides a unified way for AI applications to interact with the outside world. ## How connectors work Connectors can do two things: * **Provide tools and information** — Give Claude access to external data and the ability to take actions (search files, read emails, create issues, etc.) * **Surface UI components** — Render interactive visual elements directly in the conversation through [MCP Apps](/docs/connectors/building/mcp-apps/getting-started) **Building for Claude?** Most partners ship both a remote MCP server and a plugin that wraps it with skills. See [what to build](/docs/connectors/building/what-to-build) for the decision guide. ## Types of connectors ### Prebuilt integrations Anthropic provides first-party integrations with popular services like Google Drive, Gmail, Google Calendar, GitHub, Slack, and Microsoft 365. These are ready to use with no setup beyond authentication. See [Getting started](/docs/connectors/getting-started) for setup instructions. ### Remote MCP servers [Remote MCP servers](/docs/connectors/custom/remote-mcp) communicate with Claude over the internet, giving it access to cloud-hosted tools and data. You can connect to existing remote MCP servers or build your own for any tool or service. ### MCP Apps [MCP Apps](/docs/connectors/building/mcp-apps/getting-started) allow MCP servers to display interactive UI elements in conversational MCP clients. Rather than only returning text, an MCP App can render charts, maps, forms, and other visual components directly in the chat. See the [design guidelines](/docs/connectors/building/mcp-apps/design-guidelines) and [cross-platform compatibility](/docs/connectors/building/mcp-apps/cross-compatibility) docs for building MCP Apps. ### MCP Bundles [MCP Bundles (MCPB)](/docs/connectors/custom/desktop-extensions) package MCP servers with their dependencies for distribution as desktop extensions. MCPB handles cross-platform compatibility, dependency management, code signing, and centralized version updates — making it suitable for enterprise deployment of local MCP servers to Claude Desktop. ### Self-serve local MCP Local MCP servers distributed through third-party package registries like npm or PyPI cannot be listed directly in the Connectors Directory. To distribute a local server, package it as an [MCPB](/docs/connectors/building/mcpb) for the Desktop Extensions gallery, or bundle it in a [plugin](/docs/plugins/overview) using `.mcp.json` and submit it to the [plugin directory](/docs/plugins/submit). ## Ways to connect ### Connectors directory The [Connectors Directory](/docs/connectors/directory) is an open catalog of MCP servers from Anthropic and third-party developers, available across all Claude products. It includes both connectors that Anthropic has verified and community connectors; see [connector verification](/docs/connectors/verification) to learn what each label means. ### Third-party connectors You can build and connect your own MCP servers for proprietary tools or workflows. See [Third-party Connectors](/docs/connectors/custom/remote-mcp) for remote MCP and [Desktop Extensions](/docs/connectors/custom/desktop-extensions) for local integrations. ## Related concepts ### Plugins [Plugins](/docs/plugins/overview) combine MCP connectors, [Skills](/docs/skills/overview), slash commands, and sub-agents into shareable capability packages. They are available in Claude Code and Cowork. You can also [submit your plugin](/docs/plugins/submit) to the plugin directory. ## Platform availability Prebuilt integrations and directory connectors work across all Claude products: * **Claude.ai** — Full remote MCP support & MCP Apps * **Claude Desktop** — Full MCP support and local desktop extensions * **Claude Mobile** — Remote MCP access * **Claude Code** — Remote MCP access and plugins * **Claude Cowork** — Full MCP and plugin support ## Next steps Set up your first connector. Browse verified and community integrations. Create your own MCP server. Build UI components for Claude. Add an MCP server to Claude Code from the command line. Install, configure, and use the Claude Code CLI. # Slack integration Source: https://claude.com/docs/connectors/slack/index Use Claude directly in Slack and connect your workspace Integrate Claude and Slack in two ways: add Claude directly to your Slack workspace, or enable the Slack connector for your Claude apps. This page covers the earlier per-user Claude in Slack app. The current product is [Claude Tag](/docs/claude-tag/overview), which gives your team one Claude identity set up by an admin. If your organization used the earlier app, see [Migrate from the earlier Claude in Slack](/docs/claude-tag/admins/migrate-from-earlier). ## Claude in Slack (earlier app) Claude is available to paid Slack plan users. Slack admins must approve the app before individual users can access it. ### Ways to interact with Claude 1. **Direct messaging**: Start private conversations with @Claude 2. **AI assistant panel**: Click Claude's icon in Slack's AI assistant header 3. **Thread participation**: Mention @Claude in any thread for assistance All surfaces support the same Claude capabilities you've enabled, including web search and tool integrations. Team and Enterprise plan users with Claude Code access can route coding tasks directly to Claude Code by mentioning @Claude. ## Installation ### For Slack admins 1. Navigate to the Claude app in Slack's App Marketplace 2. Click "Add to Slack" 3. Review and approve for your organization 4. Deploy org-wide or to specific workspaces **For multi-workspace deployment:** * Access your Slack management workspace * Navigate to **Integrations → Installed apps → Add to more workspaces** * Toggle through relevant workspaces ### For individual users 1. Find Claude in your apps list or the Slack App Marketplace 2. Click "Connect Account" 3. Select your organization 4. Click "Authorize" to grant access 5. Return to Slack and click "+ New Chat" or @mention Claude **Tip**: Add Claude to your Slack header by clicking the three dots and selecting "Add this app to header." ## Slack connector Available for Team and Enterprise plans, the Slack connector allows Claude to search your workspace's channels, direct messages, and files for relevant context. You must install Claude in Slack before enabling and using the Slack connector. ### Enabling the connector **For Owners**: Navigate to **Organization settings > Connectors** and enable the Slack connector. **For Individual Users**: Go to **Customize > Connectors**, find Slack, and click "Connect." ## Managing connections ### Viewing connection status 1. Click Claude in your Slack sidebar 2. Go to the "Home" tab 3. View your connection details ### Disconnecting **Claude app**: Go to Claude's Home tab and click the red "Disconnect" button. **Slack connector**: Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors), find Slack, and select "Disconnect." Disconnecting removes your account connection and deletes past conversations within 30 days. ## Privacy & data * Slack conversations remain separate from your Claude web history * Conversations initiated in Slack don't appear in your Claude chat history * Each platform maintains separate conversation histories * Conversations auto-delete within 30 days if you disconnect * Slack retention policies apply to your workspace messages ## Troubleshooting If your company Slack requires admin approval and you lack admin access, you'll see a "Request to install" prompt. Contact your Slack Admin to approve the app. # Connector verification Source: https://claude.com/docs/connectors/verification How Anthropic reviews connectors, and what Verified, Community, and Custom mean The [Connectors Directory](/docs/connectors/directory) includes connectors built by Anthropic and by third-party developers. Each connector shows how much Anthropic has reviewed it, so you can decide what to connect to. ## Verified Anthropic has tested this connector's tools for quality and compatibility and it has met our [Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) requirements at the time of review. Verified connectors show a checkmark next to their name. Verification means Anthropic has reviewed the connector more closely than a Community connector, but it is not a security audit or a guarantee of how the connector will perform. The developer operates the connector and controls its tools, which can change after review. ## Community A third-party developer built this connector. Anthropic screens community connectors before listing, but has not reviewed this connector in depth. We do not control the tools the Community developer makes available and cannot guarantee they will work as intended or will not change, so only connect developers you trust. Community connectors show a "Community" label in the directory and in [Customize > Connectors](https://claude.ai/customize/connectors). Before you connect one, Claude shows a reminder that it has not been reviewed in depth. The label reflects the level of review each connector received. It affects how the connector is displayed and discovered in the directory, not how the connector itself functions: once connected, a community connector has the same capabilities and access as any connector you grant. ## Custom You added this connector yourself. Anthropic has not reviewed it. See [custom connectors](/docs/connectors/custom/remote-mcp) to learn how to add one. ## The directory is optional The directory is a catalog, not a separate kind of connector. Connectors in the directory and custom connectors you add yourself use the same technology. If you have a connector's URL, it can be added as a custom connector. A connector does not need to be in the directory for you to use it. Listing a connector in the directory makes it discoverable by other people and gives it a review label (a checkmark if Anthropic has verified it, or "Community" if Anthropic has screened but not reviewed it in depth). It does not change the tools the connector exposes. See [directory vs custom](/docs/connectors/building/directory-vs-custom) for a detailed comparison. ## Advice for all third-party connectors Whatever the label, this advice applies to any connector built by someone other than Anthropic: * Only connect to servers from developers and organizations you trust. * A connector's developer controls which tools it exposes and can change them at any time. * Anthropic does not run a third-party connector's servers and does not control how it handles your data. * Carefully review requested permission scopes during authentication. * Be aware of prompt injection risks; Claude has built-in protections. * Monitor for unexpected changes in tool behavior. For more, see [security and privacy](/docs/connectors/custom/remote-mcp#security-and-privacy). ## List your own connector If you build connectors and want yours in the directory, start with the [review criteria](/docs/connectors/building/review-criteria) and the [submission guidelines](/docs/connectors/building/submission). # Changelog Source: https://claude.com/docs/cowork/changelog Release notes for Claude Desktop **General** * Added a `chromiumFlags` setting in `claude_desktop_config.json` for GPU-related switches such as `--disable-gpu`, applied before graphics start up, so users can work around GPU driver crashes and rendering issues on launch, including on Microsoft Store installs where command-line flags cannot be passed. * Changed the error screen shown after repeated crashes or failed starts to say what happened and offer a Restart Claude button, and crash recovery now waits progressively longer between retries instead of retrying immediately. * Fixed a new chat's first message sometimes being sent twice after a reload, failing repeatedly with "Missing files" over an attachment uploaded for an earlier chat attempt, or dropping you back to an empty new-chat page when the first reply was interrupted; also fixed an edited message being sent again each time Enter was pressed in the edit box that stays open after Save. * Fixed the app freezing and then reloading on Windows (Microsoft Store and other MSIX installs) while an update downloaded in the background. * Fixed the app sometimes failing to launch on Windows when its settings file briefly couldn't be opened. * Fixed the Code tab's agent detection, output styles, and other desktop features sometimes needing you to sign in to your Claude account again after a single network or server error while that sign-in was being renewed. **Code** * Changed SSH and WSL sessions to keep running when left idle in the background instead of being stopped, and fixed them stalling for up to 10 minutes after each reply while the desktop app was closed or the computer was asleep. * Removed the calendar view from the Routines page; routines now always show as cards. * Fixed messages sent to an SSH session around a disconnect being dropped, discarded with an error, or answered with a prompt to send them again; the app now checks whether the message arrived and delivers it once the session is restored. * Fixed permission requests and questions not appearing in popped-out windows and split panes after the main window switched away from the Code tab. * Fixed text typed in the prompt box sometimes disappearing, along with its undo history, while a session was open. * Fixed the app freezing on launch or session switch when a very large unsent prompt had been saved; it now comes back as an editable "Saved draft" attachment. **Cowork** * Fixed browser, computer use, and website access permission prompts in Dispatch sometimes being denied on their own before you could answer. * Fixed connected-folder issues: deleting a file failed with "Could not find mount for path" when two connected folders shared a name, and Claude could see the wrong files in a newly connected folder named `.claude`. * Fixed Cowork tasks being unable to read or update existing artifacts. * Fixed Cowork startup problems on Windows: some tasks failed to start, a task could appear to start when your drive couldn't be reached (it now stops with a clear error), mapped network drives no longer hold up startup, and projects now load and save on virtual desktops that use profile containers such as FSLogix. * Fixed Reconnect on an enterprise-managed connector doing nothing when your SSO session had expired; it now signs you in with SSO again, and offers signing in with your own account after a failed attempt. **3P** * Added `inferenceCredentialHelperArgs`: a list of arguments passed in order to the `inferenceCredentialHelper` script, so one installed script can serve several environments; when unset the script runs with no arguments, as before. * Added `inferenceFoundryBaseUrl`: routes Azure AI Foundry requests from Chat, Cowork, and Code through a gateway or proxy you run instead of the resource's own endpoint; it takes the same value as Claude Code's `ANTHROPIC_FOUNDRY_BASE_URL`. * Added `redirectHost` to `bootstrapOidc`, to `inferenceGatewayOidc` (interactive gateway sign-in), and to `inferenceVertexWorkforceOidc` (Vertex workforce sign-in), so organizations whose identity provider only accepts `localhost` in a registered redirect URI can complete browser sign-in; the default remains `127.0.0.1`. * Added `scheduledTasksEnabled`: set it to `false` to turn off scheduled tasks in Cowork and Code; the Scheduled page is hidden, existing tasks stop running, and Claude can no longer schedule new work. * Added effort and default-model controls: `defaultModelEffort` sets the effort level the default model starts at, `maxEffort` on an `inferenceModels` entry hides that model's higher effort levels and holds Code sessions to the cap, and `alwaysStartWithDefaultModel` starts every new conversation or task on the default model and stops saving a person's model and effort changes as their default. The Code tab also now uses the standard model picker, with effort as its own control beside the model name. * Added model catalog support: model names, descriptions, and thinking or effort options in the model picker now follow Anthropic's published Claude Code model catalog, matching what first-party users see, with your configured model list and order unchanged. By default the app fetches the signed catalog from `downloads.claude.ai` (the host it already uses for workspace and Claude Code downloads) every 5 to 15 minutes and keeps the last catalog it fetched, or the copy bundled with the app, when that host cannot be reached; set `modelCatalogEnabled` to `false` to keep the app's built-in labels and make no catalog request, or `modelCatalogUrl` to fetch the catalog and its signature file from a mirror inside your network instead (the document is still verified against the key built into the app). * Changed Chat to stop asking for approval when Claude hands back a file it produced and, with advanced file analysis on (`chatAdvancedFileAnalysisEnabled`), at each step of analyzing an attached file, matching Cowork; connector actions still ask. To keep the per-step prompt in Chat and Cowork, add `"Bash": "ask"` to `builtinToolPolicy`. * Changed the Cowork workspace's and other native log files on macOS to be written to `~/Library/Logs/Claude-3p` with the rest of the deployment's logs instead of `~/Library/Logs/Claude`. * Changed MCP tool permissions: entries in `managedMcpServers` and `orgPluginSettings` now apply to MCP servers from any installed plugin, including ones that run locally, a `managedMcpServers` entry can use `transport: "policy-only"` to set tool permissions for a server a plugin provides without declaring how to launch it, and permission rules now also apply to tools whose names contain characters such as dots or spaces. * Changed SSH connections in Code sessions on macOS and Linux to run through the OpenSSH `ssh` program on the device by default, so the organization's own SSH setup (for example Kerberos sign-in and `ssh_config` options) applies; set `sshTransport` (beta) to `builtin` to keep the app's built-in SSH library. * Fixed "Instructions for Claude" in Settings appearing blank right after saving, and profile settings switching to a different saved copy after a launch that asked the user to sign in. * Fixed Duplicate saving an empty copy of a configuration, and Claude API key sign-in overwriting a saved configuration, when the configuration's file could not be read, for example while another program briefly had it locked. * Fixed sign-in guidance when the deployment's credential has no sign-in to repeat: authentication error cards now show that credential's own guidance instead of asking to sign in again, the sign-in card says what failed when sign-in succeeded but the organization's configuration could not be loaded, and a gateway 403 is reported as a provider error instead of a request to re-enter credentials. * Fixed the model picker listing the same model name many times when a gateway returns several models under one display name; the extras now appear under More models, labelled by the part of the model ID that differs. * Fixed scheduled tasks silently not running after the provider sign-in (such as AWS IAM Identity Center) had expired; they now wait and run once you sign in again, and the "Scheduled task failed" notification now appears when a task could not start. Microsoft has released a Windows update that fixes the issue where Cowork could not reach your files on Windows PCs. Install the latest Windows update and restart your PC. On Windows 11 24H2 and 25H2 the fix is [KB5129195](https://support.microsoft.com/en-us/servicing/os/windows-11/2026/09/kb5129195-windows-11-24h2-25h2-security-update). No Claude Desktop update is needed. **General** * Updated the bundled Claude Code CLI to version 2.1.270. * Fixed organization plugins enabled through Claude Code's managed settings not loading; they load from the next session. * Fixed sessions with a very large prompt getting permanently stuck on a "Prompt is too long" error. **Code** * Fixed users sometimes being told a model they have access to is restricted, and a running session silently switching to the organization's default model. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * Changed the automatic move of scheduled tasks to the cloud, for accounts where it has started: the app now waits about a minute after the computer wakes, and while offline checks again each minute, instead of trying at once and then waiting hours after a failed try. * Fixed two problems with local projects that are moving to claude.ai, for accounts where that move has started: a project could refuse new tasks for hours while part of its memory copy waited on the server (it now accepts new tasks and the copy finishes in the background), and memory files shown in a moved project's earlier tasks would not open. **3P** * No user-facing changes. **General** * Changed messages sent while Claude is still replying: they now wait in the conversation looking like sent messages, the first waiting message offers Send now, which stops the current reply and sends it next, and Cmd/Ctrl+Enter sends your message right away, interrupting the current turn. * Fixed Claude's clicks, scrolls, screenshots, and page scripts in the built-in browser stalling, timing out, or failing while the browser pane was hidden or the window was minimized or in the background, and fixed elements picked with "Select element" reaching Claude without their styles or with a screenshot of the wrong part of the page. * Fixed links that open a new tab to claude.ai or claude.com pages, like Upgrade buttons and some download links, doing nothing when clicked; they now open in your default browser. * Fixed sites on a private network (VPN, Tailscale, or intranet hosts) loading without their styles, scripts, or data in the built-in browser, and URLs typed into the built-in browser in cloud sessions not reaching private-network sites. * Fixed the app window resetting to its default size and position after an update or a display change. **Code** * Added a default transcript view setting: choose whether new sessions open in the Normal, Thinking, or Verbose view from Settings > Claude Code, or make the current view the default from a session's Transcript view menu. The choice syncs between the desktop app and claude.ai. * Fixed Code sessions failing to start on some Microsoft Store and MSIX installs on Windows. * Fixed model changes being refused with a message saying organization-managed hooks could not be checked, for some organizations that manage Claude Code plugins; the session now restarts on the chosen model. * Fixed sessions failing to start on Windows for accounts with many plugins installed. * Fixed several SSH session issues: hosts slowly accumulating leftover background processes from older Claude versions until sessions there failed, sessions from one computer being ended when a second computer's Claude app cleaned up the same host, sessions permanently losing their connection after a saved connection's host or port was edited, and history missing its newest messages soon after launch or a reconnect. * Fixed WSL sessions failing to start or reconnect, including background reconnects right after an app update, when WSL reported a momentary error. **Cowork** * Changed what happens on Windows PCs where a Windows update released September 8, 2026 prevents Claude's workspace from reaching your files: the app now names that cause instead of deleting and reinstalling the workspace. This does not fix the underlying problem, and the workspace still can't reach your files on those PCs. * Fixed a session appearing stuck running when an organization hook blocked a message; the reason the message was blocked is now shown. * Fixed an Office file preview sometimes showing "Failed to load PDF document" instead of the spreadsheet or document view. * Fixed long-running tasks failing with an authentication error after the app renewed your sign-in in the background; the running task now picks up the renewed sign-in and continues. **3P** * Added `coworkVmIpv6Enabled`, which gives the Cowork workspace VM an IPv6 address and route so the agent's tools can reach IPv6-only hosts through the device's own IPv6 connectivity. macOS and Windows; off by default. `coworkEgressAllowedHosts` still decides which hostnames the tools may reach. * Added `sshTransport` (beta), which chooses the SSH engine that carries Code sessions: `system-openssh` runs the OpenSSH `ssh` program on the device, so connections can use the organization's own SSH setup (for example Kerberos sign-in, including on Windows), and `builtin` uses the app's built-in SSH library. Unset or `auto` keeps the build's default. * Added a deprecation notice in the Setup window under any managed-configuration setting that is scheduled to stop being accepted, naming the date and what to use instead. * Added organization-set session retention. `chatSessionRetentionDays`, `coworkSessionRetentionDays`, and `codeSessionRetentionDays` each delete that surface's idle sessions from the device, along with their files, after the set number of days (1 to 3650) without activity; unset deletes nothing. `sessionRetentionHold` suspends all automatic deletion for the users it is set for, as a legal hold. Projects, Spaces, and memory stay, and a Code session's uncommitted work stays on disk. * Changed app launch to open the home composer on the last-used Chat or Cowork mode instead of always opening Cowork first. * Changed hooks from organization plugins to also run in Chat, matching Cowork and Code. * Deprecated an undocumented client-certificate fallback setting that releases from 1.49585.0 on no longer read, since the app now presents TLS client certificates natively. Deployments that still set it keep working unchanged, but their users see an in-app deprecation warning from November 3, 2026, and the setting stops being accepted on November 17, 2026; remove it once every device is on 1.49585.0 or later. * Improved the connection test against gateways that require a TLS client certificate the device does not have: the result now says the device did not present a certificate the gateway accepts, so the connection could not be tested, instead of reporting the model as rejected. * Fixed Claude Code's own settings on the device (a user's or project's settings file, or a `managed-settings.json`) being able to turn OpenTelemetry trace export back on after an administrator configured a collector with traces off; with `otlpEndpoint` set, Cowork and Code sessions now export traces only when `otlpTracesEnabled` is `true`. * Fixed Amazon Bedrock and Google Vertex AI sessions retrying a failed request for several minutes when the AWS or Google Cloud credential on the machine had expired; the request now stops after one retry so the credential can be refreshed. **Resolved September 14, 2026.** Microsoft has released a Windows update that fixes this issue. Install the latest Windows update and restart your PC. A Windows update released September 8, 2026 (including KB5124008) stops Cowork from reaching your files when it runs on your Windows PC, so tasks fail or the workspace does not start. This affects Cowork on third-party inference deployments and Cowork sessions that run on your computer rather than in the cloud. Cloud sessions and Claude Code, including the Code tab, are not affected. Chat cloud sessions are not affected, but Chat sessions on third-party inference deployments are affected if using advanced file analysis. The cause is a change in Windows, so restarting or reinstalling Claude does not help. **General** * Changed an invalid "Required organization" device-policy value to block sign-in with a configuration error, shown in the diagnostic report, instead of being ignored. * Updated the app runtime to Electron 44 (Chromium 152); macOS 13 Ventura or later is now required. * Fixed chats started from the menu bar or Quick Entry panel opening as an empty page for up to a minute before the reply appeared, and ignoring your instructions from Settings > Instructions for Claude. * Fixed macOS sometimes showing repeated "bash would like to access data from other apps" prompts after quitting the app with sessions open. * Fixed scheduled tasks around Mac sleep: a task that ran while the Mac was asleep was sometimes stopped as unresponsive when it woke, tasks missed during sleep sometimes started during a brief background wake and failed (they now start once the Mac is fully awake), and a one-time task occasionally started many sessions at once after wake. **Code** * Improved terminal tabs: they now show when a command is still running and ask before closing one that is, and a tab whose shell crashed or was killed stays open with a Restart option instead of closing silently with its output. * Removed the Git requirement for local sessions that don't use a worktree; on Windows, Git for Windows (Git Bash) is no longer needed to start a session. * Fixed the Files pane discarding unsaved edits without asking when you closed the pane, expanded another pane, or opened it in a new window; fixed the editor joining lines in files that mix Windows and Unix line endings; and a failed save now says the file couldn't be saved and offers Try again instead of claiming the file changed on disk. * Fixed the selected model reverting or being refused when you switched models while a session was starting, restarting, or still answering; the session now uses the model you chose, and model changes in SSH and WSL sessions no longer fail with "plugin hooks could not be loaded". * Added automatic sending for messages held after you hit your 5-hour limit: they now send when the limit resets, and you can still edit, cancel, or send them early. **Cowork** * Fixed a conversation started from an artifact, or from an artifact comment's Send to Claude, not using your selected model. * Fixed a task disappearing from the app while its files stayed on disk when one of them was in use during delete; the task is now kept so the delete can be retried. * Fixed an issue where the app could quit at launch with a very large number of Cowork tasks. * Fixed the "Can't reach the Claude API" warning staying on screen until the app was restarted even after the connection had recovered; it now clears on its own. **3P** * Added `continuousAccessEvaluation` to the Microsoft 365 entry in `managedMcpServers`: the bundled connector's sign-ins, through the OS sign-in broker as well as the browser, request Continuous Access Evaluation tokens from Microsoft, which can live up to about 28 hours but are revoked within minutes when an administrator revokes sessions or a tenant network policy no longer allows them; set it to `disabled` to keep standard one-hour tokens on every sign-in path. Defaults to `enabled`. * Added each model's description from the gateway to the model picker for deployments that discover models from the gateway. * Changed `microsoftAuthBroker`: a new `required` option makes Microsoft 365 sign-in fail when the OS sign-in broker is unavailable instead of falling back to the browser, so the refresh token always stays held by the broker, and removes the token cache an earlier browser sign-in left on disk. Earlier versions treat `required` as `disabled` (browser sign-in only), so set it once every device is on this version or later. * Changed Claude API, Google Vertex AI, Amazon Bedrock, and Bedrock Mantle deployments that set no custom base URL to no longer suppress Claude Code's experimental features, so tool search is on by default there (on Vertex AI with Claude 4.5 and newer models) and `toolSearchEnabled` is no longer needed to turn it on; gateway and Foundry deployments, and those providers behind a custom base URL, are unchanged. * Fixed Amazon Bedrock sessions that use IAM Identity Center sign-in showing an internal error or a bare "operation was aborted" message when AWS sign-in could not be reached at session start; the app now says whether IAM Identity Center was unreachable, temporarily unavailable, refused the account or role, or returned an unreadable response, and what to do next. * Fixed find in page (⌘F) missing matches in messages scrolled out of view. * Fixed Google Cloud (Vertex AI) sessions sometimes running under the computer's own Google login instead of the credential your organization configured, and the app not asking you to sign in again after your Google session expired. * Fixed the app refreshing the sign-in token about once a second when an inference gateway answers 403 to the model list request. * Fixed the built-in Microsoft 365 connector showing Connected before anyone had signed in; its first request in a conversation now offers the sign-in, and a cancelled sign-in no longer hides its tools; the bundled connector also gains a tool that reads Teams channel messages. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * Added support for attaching your home folder, Windows Documents, AppData, the macOS Library folder, and whole drives; Claude's own configuration and session data inside them stay off-limits, as do certain credential and shell-startup locations (for example SSH keys, AWS and Google Cloud credentials, and bash, zsh and PowerShell profile files). **3P** * No user-facing changes. **General** * No user-facing changes. **Code** * Fixed Code sessions started in a git worktree failing to initialize on Windows. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Removed the "Mark as unread" action for chats. * Fixed links between artifacts and shared-artifact links clicked inside the app opening in the browser or losing their share key; they now open in place, and a teammate without access sees the request-access screen instead of "not available". * Fixed memory use on macOS growing steadily while working with files, which could end with the system reporting it had run out of application memory. * Fixed new messages being queued instead of sent after reopening a chat whose last message had no reply yet. * Fixed removing a file from the message box after stopping or losing a reply sometimes deleting that file from the message you had already sent, which made "Try again" on it fail. * Fixed side chat, the slash-command picker, usage insights, and other quick actions failing silently on machines where an organization deploys a Claude Code `managed-mcp.json`. * Fixed the dictation microphone button disappearing from the chat composer once a message had text, an attached file, or a quoted reply. **Code** * Added a queue for messages sent while your 5-hour usage limit is reached: they wait above the composer instead of failing, and you can edit, cancel, or send them when you're ready. * Added keep-awake while Claude works: the computer no longer idle-sleeps while Claude is working in the Code tab, with a "Keep computer awake while Claude works" setting (and a "Keep awake on battery power" option) under Settings > Claude Code, a "Keep computer awake for this session" item in the session menu, and a one-time notice after a long task. * Removed the Summary transcript view from the session's Transcript view menu; sessions that had it selected open in the Normal view. * Fixed Extra high and Max effort on Claude Opus 5 quietly running at High when thinking was turned off in your Claude Code settings; those efforts now run with thinking on for the session. * Fixed organization-managed settings not loading, and Remote Control not connecting automatically, for some users until they signed out and back in. * Fixed sessions failing to open: a "Couldn't load this" message now recovers on its own instead of needing a manual reload, sessions no longer show "No messages yet" on Windows hosts that use FSLogix or similar profile containers, and a transcript that can't be read shows the reason with a Retry button. * Fixed SSH sessions being restarted after some reconnects, which could leave duplicate Claude Code processes on the remote machine, and fixed messages held for an unreachable host: they are retried after an app restart, and when the host comes back needing your password or an unlocked SSH agent the app asks you instead of marking the message "needs you". * Fixed switching models in a session: a switch refused with a "plugin hooks could not be loaded" error now restarts that session's Claude Code on the model you picked, the model picker no longer shows a model Claude Code refused, and Remote Control sessions no longer offer models the connected Claude Code version can't run. * Fixed switching models staying blocked for the rest of the session when an organization-managed plugin's marketplace or a plugin hook failed to load. * Fixed the remembered folder sometimes getting mixed up with a remote machine's path, which made every local session launch fail with "working directory no longer exists". **Cowork** * Added automatic re-runs (after 5, 15, and 30 minutes) for a scheduled task that could not reach the model at all, for example right after the computer wakes behind a VPN. * Fixed Record a skill opening an unresponsive chooser window on Windows. * Fixed saving a skill Claude proposes in a conversation: a name that matches one of your skills now offers to update that skill instead of failing with "Try again", and when saving is blocked until you sign in again the Save skill button opens the sign-in prompt instead of a generic error. * Fixed scheduled tasks and other automatic ways of starting a session choosing a model the installed app version can't run, which made every turn fail. * Fixed the row under the composer (Add folder, permission mode, model) disappearing after switching a session to automatic approvals. **3P** * Added `blockReadsOutsideWorkingDirectories`: restricts Code sessions to reading files inside the session folder and `allowedWorkspaceFolders`; file tools refuse reads elsewhere, and sandboxed shell commands lose access to the home directory. * Added `configRecheckIntervalMinutes`: how often a running app re-checks its managed configuration for changes, from 2 to 30 minutes; unset means 10 minutes, where the app previously checked every 30. A served value applies without a restart, and the key can also be set from device management. * Added `disableBypassPermissionsMode`: removes bypass permissions mode from Code sessions and Cowork tasks, so Claude always follows the configured permission policy. * Added `sshClientPath` (beta): the absolute path of the OpenSSH program the app runs for SSH sessions; when unset, the app uses the first `ssh` on the user's PATH. * Added an Edit button to your most recent message in Cowork and Chat sessions, so you can revise and resend it, and fixed "Restart conversation from here" doing nothing in Chat sessions. * Added the restart prompt, escalating to a required restart after `relaunchEnforcementHours`, when device-managed configuration (the managed plist, Windows policy registry, or Linux managed-settings file) changes while the app is running; previously only configuration changes served from a customer bootstrap endpoint prompted one. * (breaking) Changed `relaunchEnforcementHours`: in served configuration the key moved from `bootstrap.relaunchEnforcementHours` to `lifecycle.relaunchEnforcementHours`; this release no longer reads the old path and earlier versions do not read the new one, so move the value under `lifecycle` (the flat-format and device-management key name is unchanged); the key can now also be set from device management; and the default window before a required restart is now 24 hours instead of 1. A device-management profile that sets any app-behavior key takes precedence over a served value for this key, so such a profile should set it too. * (breaking) Changed how unreadable Claude Code managed settings are handled: if a device's `managed-settings.json` file, a drop-in, the device-management plist, or the Windows policy registry value cannot be parsed, Claude Code now refuses to start and names the source, so sessions on that device will not start until that file or value is fixed or removed; previously they ran without those settings. Check that these sources parse on managed devices before rolling out this version. * Changed `allowedPluginMarketplaces` entries set to `auto_install` or `required` without a pinned commit SHA (or without `manifestSha256` for a `url` source) to show as available with a configuration warning, instead of being removed from the marketplace list. * Changed Claude Code's `allowedMcpServers` setting (in its `managed-settings.json`, not the managed-configuration schema) to govern only servers users add themselves: a server from a `managed-mcp.json` file that the allowlist used to filter out now loads, and `deniedMcpServers` is the way to keep it off. * Fixed chat search returning no results; searching finds chats by title and message content again. * Fixed deployments without cloud features, or with the Cowork tab turned off, showing controls that could not work there, including Remote Control, automatic pull requests, the Cloud and Slack session filters, Add marketplace, and Cowork slash commands. * Fixed organization plugins staying installed for users after an administrator removed the plugin's folder from the system `org-plugins` directory. * Fixed remote MCP connectors whose `headersHelper` mints the credential continuing to fail for up to several minutes after the server rejected an expired credential; the helper now re-runs immediately and the rejected request is retried once. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * Added support in Chat for skills from organization-provided plugins, and Chat-only users can now see and manage those plugins under Customize, matching Cowork and Code. * Fixed advanced file analysis in Chat failing with "Workspace unavailable" for users whose organization enables `chatAdvancedFileAnalysisEnabled` but turns Cowork off with `coworkTabEnabled: false`. * Fixed managed OAuth connectors showing a connection error instead of prompting to sign in when the app starts without a usable sign-in (expired with no refresh token, or never signed in on this machine), including servers added by URL alone, where Connect could fail instead of opening the sign-in page. * Fixed organization-configured URL plugin marketplaces failing to install or load plugins with "marketplace entry path does not stay inside the marketplace directory". **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * Fixed sessions on Windows being unable to run commands or fetch web pages. This reverts the 1.44121.1 fix for sessions failing to start on Windows for accounts with many saved artifacts, scheduled tasks, or connected folders. **3P** * No user-facing changes. **General** * Added Claude to the "Open with" menu for common work files, including spreadsheets, PDFs, Word and PowerPoint documents, text files, and images, on macOS and on Windows (Microsoft Store and MSIX installs). * Fixed a crash at launch when the app's settings file couldn't be read. * Fixed a new chat's first message being dropped when you had to sign in again or verify this device; the chat now asks for that step in a dialog over your message. * Fixed an issue where an invalid settings file could cause all app settings to be reset. * Fixed Claude not finding files attached in Cowork and Chat, including pasted files and a re-attached file with the same name; attachments that can't be read now say so instead of being dropped silently. * Fixed scheduled tasks failing with an error after a permission approval. * Fixed the app reloading endlessly when it keeps crashing right after loading; it now stops and shows what to do next. **Code** * Added a Split View submenu to the View menu for opening a new session beside or below the current one, and side panes (diff, terminal, plan, preview, and others) can now open in a window of their own. * Added Claude Code output styles: an "Output style" submenu in the session menu and a `/output-style` command for viewing and switching styles, a "New style…" option that drafts a custom style from a plain-language description, and a default style setting in Settings › Claude Code. * Changed the Files pane to open files as tabs beside a collapsible file tree, with single-click preview tabs, multi-select, richer right-click menus, and inline previews for PDF, Word, Excel, and PowerPoint files. * Fixed `/rewind` appearing undone when returning to a session after navigating away, which could also cause the next message to silently drop recent conversation history. * Fixed Code sessions repeatedly failing to start after a corrupt Claude Code download on macOS, failing to start on Linux arm64, and SSH and WSL session setup failing on slow connections; the one-time install now shows progress and can fall back to uploading Claude Code from your computer. * Fixed sessions failing to start on macOS 12 (Monterey). * Fixed sessions getting stuck on "responding" when a message was queued near the end of a turn. **Cowork** * Changed live artifact sharing to follow your organization's Artifacts setting and sharing policies: members no longer see sharing options their organization has turned off, and already-shared artifacts keep Copy link and Unshare. * Changed updating a skill from a file card or skill proposal to apply in one step with an Undo toast instead of a confirmation dialog; where a confirmation still appears, its Update button is the pre-selected action. * Changed what happens when web fetch isn't available for your organization: Claude now says so instead of retrying and reporting failed fetches. * Fixed a crash when previewing an image file that is empty or actually contains text. * Fixed a message with an attachment that couldn't be read or was too large failing to send over and over with no explanation; Claude now marks the attachment with the problem, says what to do, and offers Retry where it can help. * Fixed sessions failing to start on Windows for accounts with many saved artifacts, scheduled tasks, or connected folders. * Fixed sessions that run Claude Code directly on the device failing to start for organizations that set `disableSideloadFlags` in Claude Code's managed settings (`managed-settings.json`, an MDM profile, or the registry); in those sessions Claude Code loads none of the desktop's plugins, so their commands, agents, and hooks are unavailable. * Fixed the session page reloading after you connect a connector that signs in through the browser. **3P** * Added `claudeAiImport.automatic3pImport` (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, independently of `claudeAiImport.enabled`; a copy interrupted when the app quits resumes on the next launch. * Added `egressProxyUrl` and `egressProxyPacUrl`: route the app's and the agent's traffic through a corporate HTTP proxy, or let a PAC file choose the proxy per request, instead of following the operating system's proxy settings; on macOS and Windows, Cowork's workspace follows the pinned proxy too. Both keys are read from device management or the local configuration file only, and the PAC file wins when both are set. * Added `inferenceStreamIdleTimeoutSec`: how many extra seconds (300 to 1800, default 300) Chat, Cowork, and Code sessions wait for model output on a streaming response that is sending only keep-alive pings, for gateways that send keep-alives while the upstream model is silent. Gateway provider only. * Added a Duplicates step to the import wizard when an imported Project has the same name as one you already have, with the option to merge the imported sessions into your Project and remove the duplicate; the Projects page offers the same merge. * Added conversation titles to the OpenTelemetry export: a `desktop_session_title_set` event carries each Cowork and Code session's title plus the Claude Code session ID to join on, sent when `otlpDesktopLogLevel` is `info` or lower; the title text is included only when `otlpContentCapture` includes `userPrompts`. * Added installing and updating plugins from admin-configured marketplaces on devices where Cowork isn't available, from the Code tab or the Cowork tab. * Added local scheduled tasks to the Code tab, including the `/schedule` command and the Scheduled page, matching what Cowork already offered. * Added the ability to attach files in SSH Code sessions. * (breaking) Changed the Usage page cost estimate to require `inferenceModelPricingEnabled`; `inferenceModelPricingMultiplier` and `inferenceModelPricing` now refine the estimate only while it is on and no longer turn it on by themselves. * Changed `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` set in the `env` block of Claude Code's managed settings (`managed-settings.json` or your organization's server-managed Claude Code settings) to apply to Chat, Cowork, and Code sessions even when the computer has a system proxy configured. * Changed `isClaudeCodeForDesktopEnabled`: when it is `false`, the app no longer starts Code sessions even if asked directly, Preview no longer scans projects for a dev server, and the computer is no longer offered for Remote Control; a Code session requested anyway shows "Code sessions are turned off by your organization" instead of a retry prompt. * Fixed Bedrock and Bedrock Mantle sessions being cut off by network idle timeouts during long thinking phases on Opus 4.7 and later models. * Fixed Code tab sessions not prompting to re-authenticate when the deployment's credentials had expired; they now show the same sign-in prompt as Cowork. Also fixed Live Artifact `askClaude()` calls and the Code tab's "Detect dev server" failing on deployments that use SSO, credential helpers, Vertex, or Bedrock SSO. * Fixed managed MCP connector sign-in staying permanently stuck when the identity provider no longer recognizes the OAuth client the app registered; the app now registers a new client automatically. * Fixed MCP servers provided by plugins not connecting in Code and Cowork sessions when `managedMcpServers` is configured; in that case, with `isLocalDevMcpEnabled` set to `false`, plugins' remote MCP servers connect and their local (stdio) ones stay blocked. * Fixed plugins distributed as a zip whose top level is a single component folder (for example `skills/` or `commands/`) installing with no skills, commands, or agents. * Fixed the `allowedWorkspaceFolders` policy not always being applied to Code sessions over SSH. * Fixed the Code tab home's usage stats reporting a favorite model, per-model breakdown, and activity from other Claude Code history on the same machine instead of this deployment's own sessions. **General** * Updated the bundled Claude Code CLI to version 2.1.255. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Fixed Claude sometimes being unable to read or search a page in the built-in browser just after opening it or while it was still loading, and browser screenshots and interactions timing out or stalling on Windows and Linux while the browser pane was closed or another page was selected. * Fixed the app failing to launch when one of its settings files had become corrupted, and settings files sometimes being left corrupt after an unexpected shutdown or power loss on Windows. * Fixed the Share dialog: "Keep private" now takes effect immediately, and sharing a chat while offline shows an error instead of waiting indefinitely. * Fixed typing with an IME (Japanese, Chinese, or Korean): confirming or cancelling a conversion with Enter, Escape, or a digit key no longer sends half-composed text, discards typed drafts, denies tool approvals, rejects plans, or stops Claude's response in Code sessions, and no longer commits or discards text in the browser pane's address field. * Fixed scheduled tasks that run on this computer occasionally being marked as skipped without running; a run the app fails to pick up is now retried a few minutes later. **Code** * Added side-task suggestions in cloud sessions: Claude can suggest follow-up tasks that you start on your machine, in the cloud, or in the same session with one click. * Added `/resume`: search the Claude Code sessions started from your terminal on this computer and continue one in the app on the same transcript. * Added a view of the session's MCP servers: type `/mcp` in a local session to see the servers from `.mcp.json`, `~/.claude.json`, plugins, and your claude.ai connectors, with live status and Connect, Reconnect, and Re-authenticate actions. * Fixed "Import Claude Code CLI sessions" (Help > Troubleshooting): it again finds Code sessions whose sidebar entries were lost after a reinstall or repair, no longer rewrites a session file that a running Claude Code process is still using, and saves a backup of the original transcript when importing removes its thinking blocks. * Fixed inline plan comments being silently lost when left after a plan was approved; the Plan pane now accepts comments in Plan mode or while Claude is asking you to approve the plan, and says when commenting opens otherwise. * Fixed SSH sessions losing messages that were waiting to be sent when the remote host became unreachable or the app was quit, updated, or restarted; they are now kept and delivered automatically at the next connection, and Claude Code is restarted on the host when needed. * Improved SSH session reconnects: high-latency links no longer drop their own connection, a network change mid-stream is noticed within seconds, an unreachable host is no longer re-dialed every few seconds in the background, and the session shows the specific connection error with a Try again button instead of a generic message or an indefinite "Reconnecting…". **Cowork** * Fixed files dropped onto the composer together with a folder being discarded; they now attach alongside the folder. * Fixed shell commands that use plugin or skill file paths failing with "No such file or directory". * Fixed the app running out of memory after many scheduled task runs. * Fixed the Cowork readiness check appearing to hang for minutes when a network-redirected profile folder is unreachable, and reporting a computer as unsupported because of an encrypted leftover folder from an uninstalled Claude version. * Fixed organization plugins failing to install or update on some Windows Store installs. * Fixed a message that starts with a typed, pasted, or app-filled slash command for one of your enabled skills failing with "Unknown skill" in an existing task; it now sends. **3P** * Added `relaunchEnforcementHours` (served configuration only): when a served configuration change needs a restart, it sets how many hours (0 to 336) users may keep running on the previous configuration; at the deadline Claude shows a restart dialog and restarts on its own after 2 minutes of inactivity. Unset means 1 hour. * Added `sshHostAllowlist` (beta): admins can turn on SSH remote sessions in the Code tab by listing the hosts users may connect to (`["*"]` allows any host). Unset keeps SSH sessions off unless a Claude Code managed-settings file on the device already allows hosts; an explicit `[]` keeps them off even then when the configuration is admin-delivered (device management or trusted remote delivery), while on a self-configured install the device allowlist still applies. Works with a gateway, Claude API key, or Foundry, and with Bedrock and Vertex when they use token-based credentials; file-based credential kinds are refused at session start with a message naming the kind. * Added an estimated-cost view to the Usage page chart: when the organization has turned on cost estimates, the chart can switch between tokens and estimated cost per day (per week at 90 days), and days with turns that have no estimate show as gaps rather than \$0. * Added an in-app warning when the organization's configuration uses a deprecated field: each user sees a dismissible notice from September 10, 2026 and once more in the 24 hours before the field stops being accepted, with a Details dialog naming each field, its replacement, the cut-off date and what changes then, plus a Copy report button that puts a plain-text summary for administrators on the clipboard. The new `disableConfigDeprecationWarnings` key hides the first showing; the final 24-hour reminder still appears. The warning also appears on standard deployments whose device-management profile uses one of these fields. * Added Anthropic's Cowork and Claude Code plugin marketplaces as prefilled entries in the Setup window's `allowedPluginMarketplaces` Add menu. * (breaking) Deprecated a set of older managed-configuration spellings, each accepted until October 7, 2026, 12:00 PM Pacific Time, with an in-app warning from September 10, 2026: `inferenceGatewayHeaders` (use `inferenceCustomHeaders`), `trustBootstrapLocalExec` (use `trustBootstrapDelivery`), `enduserAttribution` (use `endUserAttribution`), `inferenceGatewayAuthScheme` values `sso` (use `inferenceCredentialKind: "interactive"`) and `auto` (remove the key; `bearer` is the default), `isDxtEnabled` (use `isDesktopExtensionEnabled`) and `isDxtSignatureRequired` (use `isDesktopExtensionSignatureRequired`), header maps written as strings or lists in `inferenceCustomHeaders`, `otlpHeaders`, `otlpResourceAttributes` and `bootstrapHeaders` (use a JSON object), the `orgPluginSettings` record form (use the array form), the `ask-session` tool-permission value in `builtinToolPolicy`, `managedMcpServers[].toolPolicy` and `orgPluginSettings[].tools[].permission` (use `ask`), and in `managedMcpServers` entries the `scopes` list (use `scope`), `transport: "builtin"` (remove it), `authorityHost` (use `azureCloud: "us-gov-high"` for a GCC High tenant), `source` (remove it), `oauth` written as a number or string (use `true` or an `oauth` object), `oauth.scopes` or a list-valued `oauth.scope` (use `oauth.scope` as one space-separated string), and entries other than a built-in server with no `transport` (add `transport: "http"`, `"sse"` or `"stdio"`; a built-in Microsoft 365 or GitHub entry takes no `transport`). After the cut-off a renamed key's old name falls back to its fail-closed value or default, and an invalid `managedMcpServers` or `orgPluginSettings` entry makes that connector or tool policy unavailable until it is rewritten. * Changed `inferenceVertexProjectId` and `inferenceVertexWorkforceUserProject`: a value delivered by a bootstrap URL the user configured themselves (in Settings or a local configuration file) now asks that user to approve it before it takes effect, and declining quits the app. Because the project ID is required, each such Vertex install prompts once after updating. Values delivered through device management, or by a bootstrap URL that device management set or that `trustBootstrapDelivery: true` covers, are unchanged and never prompt. Both keys must now match the Google Cloud project format. * Changed `toolSearchEnabled` on gateway deployments to enable tool search alone; other experimental Claude Code betas stay suppressed. * Changed how a managed-configuration value the app cannot read is handled: it now engages the restriction it belongs to instead of being ignored. Restriction keys such as `disabledBuiltinTools`, `builtinToolPolicy`, `coworkTabEnabled` and `disableBundledSkills` fall back to their restrictive value, an unreadable `managedMcpServers` keeps Code sessions restricted to managed MCP servers, an unreadable `isDesktopExtensionEnabled` or `isDesktopExtensionSignatureRequired` disables extensions or requires signed extensions, and a tool-permission value the app does not recognize is applied as the most restrictive setting (`ask` for a built-in tool, `blocked` for a plugin-delivered tool) and reported as a configuration error. `allowedPluginMarketplaces`, the built-in GitHub MCP preset and `otlpTracesEnabled` are no longer marked Beta. * Changed the Setup window's configuration exports and the published bootstrap JSON schema to write `orgPluginSettings` in its array form; the app still accepts the older record form until October 7, 2026. Desktop versions before 1.15200.0 read only the record form and do not enforce plugin tool locks given the array, so update the fleet past 1.15200.0 before deploying an exported configuration that uses it. * Changed the Vertex AI credential kind for Google sign-in to `inferenceCredentialKind: "interactive"`, matching other providers; `oauth` keeps working until October 7, 2026 (12:00 PM Pacific Time). If you deliver configuration as nested JSON (a self-hosted bootstrap server or a Setup JSON export), keep `oauth` until the whole fleet is on this release or later, because an older desktop drops the Google client ID from a nested `interactive` credential and Vertex sign-in stops working; flat MDM keys, .mobileconfig and .reg files are unaffected. Until October 7, 2026 a Vertex configuration that sets `interactive` together with `inferenceVertexWorkforceAudience` and no `inferenceVertexOAuthClientId` is still read as Workforce Identity; after that it means Google sign-in, so set `workforce` explicitly if that is the intent. * Improved Cowork reliability when the workspace is slow to start or has been idle, and made switching back to a recently opened Code tab session faster. * Fixed importing sessions from a previous Claude Desktop install: imported Cowork sessions keep their Project and its `~/Claude/Projects/` folder instead of getting a new empty one, an interrupted import now appears in Import history and its sessions are no longer imported twice on the next run, and the import wizard no longer re-creates a Project you had deleted (an imported Project that duplicates an existing name gets a "(1)" suffix). * Fixed the Code tab's plugin directory and Customize > Plugins not listing plugins from marketplaces configured with `allowedPluginMarketplaces`; an admin-configured marketplace is now managed as the organization's in both tabs. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Updated the bundled Claude Code CLI to version 2.1.246. **Code** * Fixed remote MCP servers never recovering after a dropped connection; they now reconnect automatically or report as failed. * Fixed signing in to some MCP servers, such as Linear, failing with an "Invalid redirect URI" error. **Cowork** * No user-facing changes. **3P** * Added support for the `inferenceModelPricing` rates and the `inferenceModelPricingMultiplier` discount in the Usage page's cost estimate; in 1.37937.0 the estimate always used Anthropic list price. **General** * Added support for legacy Word .doc files, which now open like .docx, and Excel .xlsx and .xls spreadsheets, which now attach as text where they used to be refused. * Removed sharing of chat artifacts for members of organizations whose admin has turned Artifacts off; links already shared keep working. * Fixed chat refusing new messages after the weekly Cowork limit was used up. * Fixed scheduled tasks set to run on both a day of the month and a weekday (for example "the 1st and every Monday") only running when the two coincided; they now run on either day, as their schedule description says. * Fixed several chat reliability issues: queued messages could disappear or send on their own, a send retried during a service overload could add repeated copies of a message, reopening a chat before the reply arrived could show a false "message wasn't sent" error, and a single failed response could show two error messages. * Fixed the app sometimes signing you out right after an automatic update. **Code** * Improved SSH session reliability: fixed connections failing when the configured identity file is a public key (common with 1Password setups), messages sent while the host reconnects are delivered once it is back, a Claude Code upload to the host now rides out a brief network pause, idle sessions no longer show a false "Lost connection" card, reconnecting can ask for a password or one-time code when needed, and a reconnect no longer reports lost output unless it truly could not be recovered. * Fixed all saved SSH connections disappearing when one stored connection entry was invalid. * Fixed background cleanup of old session worktrees on Windows sometimes also deleting the contents of folders that NTFS junctions inside the worktree pointed to, such as the main checkout's `node_modules`. * Fixed removing a claude.ai import run resetting uncommitted work in a session you had started from that import; the session's files are now kept on disk. * Fixed sessions failing to start for organizations using the `disableSideloadFlags` setting in Claude Code's `managed-settings.json`; sessions now start without the desktop's bundled skills and plugins instead. * Fixed very high memory use, and a blank or unresponsive window, when opening or reconnecting sessions with very large transcripts or many subagents. **Cowork** * Added dictation in the Claude in Chrome side panel; allow the microphone once in the extension's settings. * Fixed "upload failed" errors when staging Google Drive and other cloud-synced files that are not downloaded on your Mac yet; they now download automatically, and clearer messages explain when the sync app needs to be started. * Fixed a Rename, Delete, or Move dialog left open in a task's header staying open when you switched to another task and acting on the task you switched to; it now closes on switch. * Fixed only the last file staying attached when several files opened with Claude each needed confirmation. * Fixed restored Cowork tabs showing a "Try again" error when the app restarted before sessions finished loading, such as right after an update. * Fixed the tasks and files panel staying open as an empty pane after a restart. **3P** * Added `mcpToolTimeoutSec`, which sets how long an MCP tool call may run before it times out. Defaults to 180 seconds. * Added `organizationInstructions`: organization-wide instructions appended to Claude's system prompt in Chat, Cowork, and Code sessions (up to 3,000 characters); settable via device management, a local configuration file, or the bootstrap response. They are guidance the model follows, not an enforced control. * Added `skipWebFetchPreflight`. When enabled, Code sessions no longer contact api.anthropic.com before fetching a web page, which fixes page fetches failing on networks that block that host. Off by default. * Added `userPluginMarketplacesEnabled` and `userPluginUploadsEnabled`, which control whether members can add their own plugin marketplaces and upload their own plugins; when off, the add options are hidden and adds are refused. Unset keys change nothing. * Added Code tab features already available in the standard app: the Files panel with Show in Files, emoji autocomplete and inline prompt suggestions in the composer, interactive MCP app widgets in the conversation, and letting Claude read output from the integrated terminal panel. * Added cost estimates to the Usage page: `inferenceModelPricingEnabled` shows an estimated cost alongside token counts, priced at Anthropic list price; `inferenceModelPricing` supplies per-model rates and `inferenceModelPricingMultiplier` scales every estimate (a number between 0 and 1). The two rate keys take effect from 1.37937.1; in 1.37937.0 estimates use list price. Off by default. * Added suggestions for plugins and skills from your organization's own library in chat. * Added support for plugin marketplace credential helpers that return a username or `authtype=Bearer`, so marketplaces hosted on Bitbucket Data Center or behind GitLab deploy tokens can authenticate. * Added the `disableDesktopLocalSessions` setting to Claude Code's `managed-settings.json`, which turns off Code sessions that run on the device itself so the Code tab offers only remote environments such as SSH; the environment menu shows Local greyed out with a "Disabled by your organization" explanation. * Changed `allowedPluginMarketplaces` (beta): a `url` marketplace hosted on the bootstrap server's own origin can now use `credentialKind: "inferenceCredential"` and is fetched with the same sign-in the app already uses for its bootstrap configuration. * Changed `builtinToolPolicy` to accept argument-scoped Claude Code permission rules such as `Bash(curl *)` in addition to bare tool names; `WebSearch` and `WebFetch` entries stay bare tool names, and entries that are not usable rules are rejected with a configuration error. * Changed gateway device-code sign-in to show the signed-in account's email, when the gateway returns one, instead of the computer's login name. * Changed the Code tab's file pane and git panel to follow the administrator's `allowedWorkspaceFolders` setting. * Fixed Bedrock sessions behind a proxy that strips the response content type silently re-running every request without streaming, which billed each request twice. * Fixed Cowork scheduled tasks running on the 200K-context model when the 1M-context row or "Default model" was selected in the task form; the form now labels the 1M row. * Fixed the built-in Microsoft 365 connector publishing an invalid schema for updating a calendar event's end time. * Fixed the Microsoft 365 local connector on Windows failing for users with more than one Microsoft work account on the PC. The Reconnect card now opens the Windows account picker and the chosen account is remembered; users of this connector will be asked to reconnect once after this update. * Fixed the model picker showing a duplicate, mislabeled 1M-context row when `inferenceModels` lists a model both with and without the `[1m]` suffix. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * Fixed prompt caching not being applied in sessions that use an inference gateway or custom endpoint. **General** * Fixed a startup freeze on Macs that keep applications in iCloud Drive with Optimize Mac Storage turned on. * Fixed scheduled task problems: "every N days/months" schedules ran on the wrong days (existing tasks move to the correct days on their next run), re-enabling a task or editing its schedule immediately started a catch-up run for a time slot that passed while it was off, and manually run tasks sometimes did not record when they last ran. * Fixed the app crashing when signing in with Touch ID on macOS; Touch ID passkey sign-in is temporarily unavailable. * Fixed the app quitting on macOS when the disk was full or when stopping dictation. **Code** * Fixed archiving an SSH session discarding uncommitted or unmerged work in its remote worktree; the worktree is now kept, and unarchiving recreates it if it is missing so the session can pick up where it left off. * Fixed session history no longer updating or appearing lost on macOS for sessions in folders whose names contain accented, Korean, or Japanese characters. * Fixed sessions you hadn't opened for 30 days or more losing their conversation history even though the app was in regular use. * Fixed SSH connections on slow or unstable networks failing on the first attempt and needing a manual retry. * Fixed SSH sessions losing a task that was still running when the app reconnected after an app update. * Fixed the side chat answering once and then failing with an authentication error for the rest of a long session. **Cowork** * Fixed conversations failing to open when a message contained a very long run of bracketed text, a very long line starting with an unclosed `[`, or a very long run of `>` characters. * Fixed message ratings and "Send feedback" links sometimes appearing when your organization has product feedback turned off. * Fixed sessions failing to start on managed Macs where the app's temporary directory is not writable. **3P** * Changed gateway device-code sign-in to refresh silently when the gateway also issues a refresh token, instead of prompting you to sign in again each time the access token expires. * Fixed an ended gateway device-code sign-in going unnoticed while the app was idle; the app now notices at its next periodic configuration check or shortly after the computer wakes from sleep and asks you to sign in again, and the Setup window says "Session expired" instead of "Denied". * Fixed Cowork file previews showing "Preview unavailable" until the app was restarted once a preview pane had been closed for a few minutes. **General** * Added message queueing during Research: a message sent while a Research run is in progress is queued and sent when the report is ready. * Fixed 1Password credential requests failing when Claude in Chrome is signed in from more than one browser profile. * Fixed a crash on Windows when installing an update while a background update check was still running, and fixed update installs repeatedly failing after a newer update replaced one already staged. * Fixed a message sent immediately after stopping a reply sometimes being put back into the input box instead of sending. * Fixed reloading or reopening a temporary chat rebuilding the page a moment after it loads, which could discard text typed early. * Fixed the computer-use permission prompts in Cowork and Claude Code sessions accepting a keyboard shortcut aimed at the message box or another surface, and added a brief delay so a send keystroke that lands just as the prompt appears cannot approve it. **Code** * Fixed automatic continuation after a rate limit firing into the imported-session confirmation prompt or a stale sign-in state, and it now waits out the server's limit reset and sends a clearer continuation message. * Fixed inline bash commands being silently captured as input by a previous command still waiting for a response, such as an interactive login; a stuck command is now noted in the transcript and cleared before the next command runs. * Fixed messages sent from one session to another sometimes being silently dropped, which left the sending session showing a thinking state for many minutes. * Fixed slow session starts for people with MCP servers configured in `~/.claude.json`. * Fixed the Code tab wrongly asking you to install Git on Macs that have Apple's Command Line Tools but not Xcode. * Fixed worktree sessions failing with a "path contains control characters" error when a `WorktreeCreate` hook prints status output before the path. **Cowork** * Fixed an occasional "Something went wrong" error when a session's question card from Claude changed to a new set of questions. * Fixed Claude sometimes reporting a file as saved when it had been written to a temporary location you could not open. * Fixed Cowork failing to start on Intel Macs. **3P** * Added `bootstrapHeaders` and `bootstrapHeadersHelper` for authenticating the bootstrap configuration fetch with a service-account credential, the supported replacement for embedding `user:password@` in `bootstrapUrl` (rejected since 1.32352.0): `bootstrapHeaders` is a set of static headers sent on every fetch, and `bootstrapHeadersHelper` is the absolute path of an executable that prints headers as JSON, for a rotating token; helper output is merged over the static headers. When either is set and no `bootstrapOidc` provider is configured, the headers count as sufficient authentication for the fetch and no per-user sign-in is required for it; a per-user sign-in bearer, when also present, still wins on `Authorization`. Header values are masked in diagnostics, and both keys are accepted only from device management or a local configuration file. * Added the option to sign in to claude.ai directly from the import wizard to fetch your data export, with no manual zip download needed. * Changed new Cowork sessions to store Claude Code transcripts under a short fixed folder name, now that the bundled Claude Code (2.1.234) supports it, further shortening file paths on Windows; existing sessions are unchanged. * Changed organization plugin delivery: when the organization plugins endpoint is removed from your configuration, the plugins it had installed are removed from members' devices, as already happens for a removed plugin marketplace. * Fixed admin-configured plugin marketplaces and organization plugins not re-syncing until the next periodic refresh after signing in or after a delayed configuration fetch applied. **General** * Fixed a rare Windows startup failure where the first window could fail to initialize on a fresh install. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Fixed Windows updates sometimes leaving the app half installed, with later updates failing too. * Fixed the app staying on "Couldn't connect to Claude" when a network proxy blocked its first connection; it now keeps retrying for a few minutes and again when you return to the window. * Fixed the composer staying disabled after a usage-limit notice when your organization has extra usage turned off or not set up; sending works again once your admin turns it on. * Fixed settings and connector links in chat doing nothing, or opening your web browser, when clicked in the app; they now open the app's own settings. * Fixed text typed on the new chat page sometimes disappearing when turning on incognito. * Fixed the chat showing an error screen instead of the conversation when Claude created or linked a file whose name contains a percent sign. **Code** * Changed auto-continue after the 5-hour usage limit to be on by default: sessions left open resume when the limit resets. Uncheck "Auto-continue when limits reset" in the limit banner to turn it off for your account. * Fixed sessions sometimes hanging after resume, either showing "The session stopped responding" after the first message or never starting when a file system or MCP server stalled. * Fixed undo (Cmd+Z, or Ctrl+Z on Windows and Linux) in the message composer sometimes failing with an error and then no longer working. * Fixed a brand-new cloud session losing its first message when you navigated away within a few seconds of sending it. * Fixed sessions started right after the app opened sometimes running in a more permissive mode than your saved permission mode. * Fixed Remote Control sessions staying stuck at "connecting" after you completed the sign-in or device-check prompt, and file links not opening when the session was viewed from another computer. **Cowork** * Removed the "Allow all browser actions" option from Claude in Chrome permission cards; allow each website instead. The switch in Settings is unchanged. * Fixed the workspace startup error suggesting a restart or reinstall when the computer was low on disk space; it now asks you to free up space and retry. * Fixed a tool call hanging for a full minute when its local MCP server crashed mid-call; it now fails right away. * Fixed computer use on macOS refusing every click after you had taken a screenshot or while a screen recording was running. * Fixed the approval mode still showing "Skip all approvals" when your organization's policy had blocked it; switching back to "Manually approve" now asks again before Claude fetches web pages it visited while approvals were off. * Fixed the activity panel button doing nothing while a file was open beside the chat; it now closes the file and shows the panel. **3P** * **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. * Added `claudeAiImport.exportEnabled`. With it and `claudeAiImport.enabled` both `true`, users can export this computer's chats, Cowork tasks, and Code sessions from Settings > Import & export as a zip that another install can import. Off by default. * Added a `url` source for `allowedPluginMarketplaces` (beta): a hosted `marketplace.json` that delivers plugins as zip archives over HTTPS, with no git on the device. Set `manifestSha256` to pin the exact manifest; it is required for automatically installed plugins. * Added `inferenceCredential` as a `credentialKind` for `allowedPluginMarketplaces` (beta): a `url` marketplace hosted on your inference gateway is fetched with the same credential the app already uses for inference. * Changed `coworkEgressAllowedHosts`: a `:port` suffix now also applies to shell commands and package installs in Cowork sessions, which previously could not reach a port-scoped host at all. * Changed settings from a locally configured (not device-managed) bootstrap URL that need user approval to apply all or nothing: nothing takes effect until the user chooses Allow; Quit closes the app and asks again next launch. * Changed a served configuration with an invalid connection value to report that field by name and keep the organization's other settings in force; a non-Anthropic model entry is now skipped with a warning instead of invalidating the whole configuration. * Changed admin-configured plugin marketplaces (`allowedPluginMarketplaces`, beta), including automatically installed and required plugins, to apply to Code sessions as well as Cowork. * Changed new Cowork sessions to use much shorter folder names on disk so file paths are less likely to exceed Windows path-length limits; existing sessions keep their folders, and tooling that matches the `local_` prefix should also match the new names. * Fixed Settings > Import & export saying import isn't enabled on deployments that provision the sign-in import without setting `claudeAiImport.enabled`; that key now governs only file and earlier-session import, the import prompt, and session export. * Fixed the Setup window accepting a mis-typed inference region, Azure AI Foundry resource name, blank Vertex AI project ID, or non-Anthropic model ID that was only rejected later on the device; these are now flagged before saving. * Fixed imported project instructions arriving as a loose file instead of the project's editable Instructions; they are now shown for review on the project page and apply once you accept them. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Fixed Find (Cmd+F) doing nothing the first time it was pressed after launch. * Fixed right-to-left text in the composer scrambling around embedded left-to-right words; code blocks stay left-to-right. * Fixed the Artifacts entry missing from the sidebar on Windows machines that can't run local Cowork; it now opens the Artifacts gallery. * Fixed macOS asking for notification permission as soon as the app launched, instead of when the first notification is about to appear. * Fixed the app crashing at launch, or on a system theme change, on some Linux installs (most often repackaged builds); it now falls back to a default tray icon. **Code** * Added Rewind to cloud sessions (message menu, Esc Esc, or `/rewind`), and fixed rewound-away messages reappearing when a rewound cloud or Remote Control session was reopened. * Fixed an interrupted Claude Code download (for example, after a crash or power loss mid-install) leaving Code sessions on that computer unable to start, most often on Windows. * Fixed an unanswered permission or plan-approval prompt in a cloud session sometimes being treated as approved after the session's environment disconnected. * Fixed cloud sessions marked as needing input sometimes opening without the question or approval prompt. * Fixed Remote Control sessions sometimes never connecting when opened while idle, staying off your other devices after a stop or interruption until turned back on by hand, and looking idle instead of reporting that the host computer is offline. * Fixed copy and paste problems: transcript text pasted into rich-text apps lost the spaces around inline code, bold, and italics and mangled code blocks, and Cmd+C after selecting text in the Plan view copied nothing. **Cowork** * Fixed the earlier conversation being discarded when you chose Go back after a failed task resume, or edited a message right after the app restarted. * Fixed memory saves failing when the Claude Code `managed-settings.json` policy sets `allowManagedPermissionRulesOnly`. * Fixed Cowork on Windows failing on every launch with "VM service not running" after its background service had stopped; the service is now restarted automatically, and otherwise the error explains that restarting the computer restores it. * Fixed Cowork sometimes pulling you back to the bottom of a task after you had scrolled up, for example when a sub-agent step finished. **3P** * Added `otlpAuthMode` and `otlpHeadersHelper`, two ways to authenticate telemetry exports without static `otlpHeaders`: set `otlpAuthMode` to `inference-credential` to reuse the signed-in user's inference token, or point `otlpHeadersHelper` at an executable that prints the collector headers as JSON. * Added an optional `inferenceGatewayOidc.resource` subfield that sends an RFC 8707 resource indicator on gateway sign-in and token refresh, for identity providers that audience-restrict access tokens. * Changed `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 before it takes effect, the same prompt `inferenceGatewayBaseUrl` already shows. Managed deployments (bootstrap URL set by device management, or `trustBootstrapDelivery: true`) see no change. * Changed `claudeAiImport`: an imported session now asks the user to confirm once (Trust and resume) before Claude continues it for the first time; this also applies to sessions imported before this update. * Fixed a single malformed `allowedPluginMarketplaces` (beta) entry disabling every configured marketplace; the entry is now skipped and reported. * Fixed sending messages failing when a bootstrap server turned Cowork off (`coworkTabEnabled` set to `false`); the home screen now opens directly into Chat. * Fixed OpenTelemetry exports being rejected when the configured gateway also serves as the telemetry collector endpoint. **General** * Added the standard macOS full-screen keyboard shortcut, with an Enter Full Screen and Exit Full Screen item in the View menu. * Fixed a startup error on some Linux systems, most often repackaged or containerized installs, that left the app without a tray icon and recurred on every system theme change. * Fixed commands in the built-in terminal failing with error -1743 when controlling other apps on macOS, instead of showing the Automation permission prompt. * Fixed sign-in on macOS repeatedly failing with "Failed to login, it may have been cancelled"; Claude now opens the sign-in page in your default browser when the system sign-in sheet is unavailable. * Fixed some Windows installs (MSIX packages and enterprise-managed roaming profiles) failing to save chat history, settings, and scheduled tasks, and Cowork failing to start with "Download failed" after an app update. * Fixed the app's memory use growing without bound during long-running sessions. **Code** * Removed the ability for scheduled-task runs and other unattended sessions to start dev servers in the Browser preview; other sessions now approve each distinct dev server command once rather than on every start. * Fixed app settings, and the app's record of session worktrees, being discarded when those files had been re-saved with a UTF-8 byte-order mark by an external editor. * Fixed forked sessions starting from the original base branch instead of the parent session's current branch. * Fixed importing Claude Code CLI sessions changing the order of existing sessions in `claude --resume`. * Fixed sessions failing to resume, reporting their conversation history as missing, after Claude had moved the session into a worktree. * Fixed file uploads through Claude in Chrome from a Code session failing with "Invalid arguments for tool file\_upload". **Cowork** * Fixed a follow-up message sent while Claude was still writing a reply sometimes being dropped, with the reply cut off. **3P** * Added history import. When `claudeAiImport.enabled` is `true`, users can bring a Claude.ai data export, Cowork, Code, and Chat sessions from other Claude installs on the same computer or from an app data folder they choose, and terminal Claude Code sessions into the app from Settings > Import. `claudeAiImport.bannerBehavior` controls an optional banner on new tasks that offers it: `off` (default), `detect` (only when earlier sessions are found on the computer), or `show` (everyone, until dismissed or imported). * Added `modelPrefer1mContext`. When `true`, a user who has not yet chosen a model starts on the 1M-context variant of the default model whenever the deployment marks or reports that model as 1M-capable, including auto-discovered models. Saved selections are never changed. Defaults to `false`. * Added the gateway address, `inferenceGatewayBaseUrl`, to the one-time bootstrap consent prompt. When a bootstrap server delivers it and the bootstrap URL was not set through device management, each user is asked once at launch to allow the address, and again if it later changes; the app does not connect to the gateway until they choose Allow. Existing installs prompt the first time they start this version. Set `trustBootstrapDelivery` to `true` in your device-management profile or local configuration file to accept it for everyone in advance. * Changed the Code tab to be hidden entirely, rather than shown greyed out, when an administrator has disabled Code. * Fixed a session opened in a new window on Windows having no title bar, window controls, or drag area. * Fixed stored sign-ins being lost when the system keychain was temporarily locked. * Fixed the Chat tab ignoring `toolSearchEnabled`, which sent every connector's tool definitions with each request and could exceed the context window when many connectors were configured; Chat now loads them on demand when the key is `true`, as Cowork and Code do. * Fixed the credential-expired notice and the session error banners in Cowork and Code offering no way to sign in again when the credential comes from a helper script (`inferenceCredentialHelper`); they now show "Sign in again", which re-runs the helper. * Fixed the model picker reverting to the standard-context variant in new sessions, after relaunch, and when switching between Chat and Cowork once the 1M-context variant had been chosen. **General** * Added a "Start a new project" option to the "Add to project" menu, which opens the create-project dialog. * Added Esc as a way to end voice mode in the chat composer. * Added the ability to add suggested skills in local sessions, and plugins from your personal marketplaces, directly from their suggestion cards. * Fixed Claude Desktop on Linux entering a crash-and-relaunch loop that consumed heavy processor time when automatic session restore ran into persistent graphics failures. * Fixed starting a chat inside a project showing a blank screen until the response finished, and leaving the chat without its project name or title. * Fixed the scheduled-task prompt editor not being announced to screen readers as a labeled multiline text box. **Code** * Added session-window restore: Claude Code session windows that were open when you quit now reopen the next time you launch the app. * Changed permission-mode picks so they apply to the folder where you made them instead of becoming a machine-wide default. * Removed the "Always allow" option when approving dev server starts in the Browser preview; each new server start now asks, and a server that has crashed asks again instead of restarting silently. * Fixed "Try again" on session-error cards sometimes doing nothing, and a failed send's retry card and prompt text now survive an app relaunch. * Fixed leftover session workspaces building up on disk until new sessions could fail with a disk-space error. * Fixed repository pickers in project settings and scheduled tasks timing out or omitting repositories in large organizations; they now load quickly, can search every repository, and can load more results. **Cowork** * Added a ⋮ menu to scheduled tasks in the sidebar, including Mark as unread for the latest run. * Added a confirmation before a link in a live artifact opens in your browser, with a per-site "Don't ask again" option. **3P** * Added `updateViaUpdatesHost`. Set it to `true` to read the update feed from `releases.claude.com`, a host that serves only the desktop update check and carries no model API, so networks that block `api.anthropic.com` can still receive updates. Installer downloads continue to come from `downloads.claude.ai`. Defaults to `false`. * Added an access mode to each `allowedWorkspaceFolders` entry. Set `mode` to `ro` to let Claude read and search a folder without changing it: in Cowork, writes are blocked and Claude is directed to put modified copies in the session outputs folder. In the Code tab this covers Claude's file tools only; Bash in the Code tab and SSH sessions do not yet enforce it. Entries without `mode` stay read-write, so existing configurations are unchanged. * Added optional `:port` suffixes to `coworkEgressAllowedHosts` entries, for example `internal.corp.com:8443` or `*.corp.com:8443`, restricting that entry to the named port. This applies to the sandbox's web fetch now, and to shell egress once the updated virtual machine image ships; on the Code tab, a port-scoped entry is treated as its bare host (any port). Entries without a port keep allowing any port, and an invalid entry is dropped on its own with a warning in the logs. * Added settings that decide where users sign in for inference to the one-time bootstrap consent prompt: the Azure AI Foundry Entra tenant and client, Bedrock IAM Identity Center, the Vertex OAuth client and workforce identity, and gateway OIDC. Set `trustBootstrapDelivery` to `true` in your device-management profile to accept these for everyone in advance. * Added the merged Chat and Cowork home as the default. The "New" button starts a chat or a task from one composer, and the sidebar shows Home, which lists chats and tasks together, alongside Code. * Changed the `trustBootstrapLocalExec` key name to `trustBootstrapDelivery`, reflecting that it now covers sign-in targets as well as helper scripts and connectors. The previous name continues to work in existing profiles. * Fixed chats started inside a Project not picking up the Project's Instructions and Context links, including reading the files linked there. * Fixed Code sessions on a custom gateway endpoint ending with an idle-timeout error while the gateway was still sending keep-alive responses. * Fixed Code tab sessions on gateway and direct API key deployments still sending nonessential traffic to `api.anthropic.com` after an administrator turned off nonessential telemetry. * Fixed model selections provided by your deployment being overridden by an out-of-date Claude Code `managed-settings.json` left on the device. * Fixed the published `bootstrap-config-v2.schema.json` describing flat keys instead of the nested shape the app's own configuration export uses. **General** * Added a chevron next to the composer's microphone button that switches between dictation and voice mode and keeps your choice; clicking the microphone now starts dictation right away. * Fixed `⌘K` (or `Ctrl+K` on Windows and Linux) search missing results from tool output and archived sessions. * Fixed a crash on macOS during passkey and Touch ID prompts when the system language is German, Spanish, French, Hindi, Indonesian, Italian, Japanese, or Korean. * Fixed automatic and menu-triggered update restarts interrupting an in-progress Claude Code or Cowork task. * Fixed the app being left with no usable window: a failure during startup now shows an error dialog and records the details to a file, and a window the system shut down under low memory reloads instead of staying blank. **Code** * Added automatic resume for sessions interrupted when your computer goes to sleep. A banner with a manual Continue button appears only when resuming isn't safe, and you can continue the session in the cloud instead. * Added capture and annotation for the page the Browser pane is showing, including external sites, so you can mark up what you see and attach the image to chat. * Fixed a crash while using the in-app browser on pages with heavy console or network activity. * Fixed messages sent while Claude was working disappearing from a session after it was reloaded from disk. * Fixed sessions sometimes becoming permanently unopenable, showing "No messages yet" while their conversation history was still on disk. * Fixed starting a session and swapping repositories stalling in organizations with very large repository lists: the pickers now load repositories page by page, find the rest as you type, say when more are available by searching, and report a failed search instead of showing empty results. **Cowork** * Added pasted and attached images to the session's uploads folder, so Claude can open and edit the actual file. * Fixed "Allow for this task" not appearing for connector tools when your organization has turned off persistent "Always allow". * Fixed documents showing an internal file id instead of their title, including in export filenames and approval prompts. * Fixed long-running workspace shell commands, such as large database queries, being cut off too early. * Fixed scheduled task problems: a cron expression using `7` for Sunday never ran, stalled runs kept running in the background until the app was restarted, and "Allow for all scheduled runs" appeared on prompts where the choice could not be saved, so the task asked again on every run. **3P** * Added Projects for organizing Chat conversations: create a project, start a chat inside it, or move existing chats in. Projects stays available even when your administrator has turned the Cowork tab off. * Added `inferenceGatewayOidcAuthFlow` and `inferenceVertexWorkforceAuthFlow`, which choose whether identity-provider sign-in for gateway and Vertex workforce-identity credentials runs in the system browser (the default) or through the operating system's Microsoft account broker on Windows and macOS, so sign-in can satisfy Conditional Access policies that require a managed device. * Added `managedMcpServers[].oauth.authFlow`, which 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. * Added `skillCreationEnabled`, which controls whether users can create and upload their own skills. It defaults to on; setting it to `false` hides the creation and upload surfaces and turns off Claude's skill-creation tools. It appears in the Setup window under workspace restrictions. * Added `trustBootstrapLocalExec`. Each user is now asked once for consent when the bootstrap configuration includes settings that run local commands, such as credential helpers and local connectors. Set this key to `true` to accept them for everyone in advance. It defaults to `false` and is accepted only from MDM or a local configuration file. * Added a built-in GitHub connector to `managedMcpServers`: 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. The connector is also configurable from the Setup window. * Added support for mounting Windows mapped network drives into the Cowork sandbox, so shell commands and document processing can work with files on network drives, and fixed adding a mapped network-drive folder mid-session being rejected with a message to use the folder picker. * (breaking) Changed the nested v2 bootstrap response: `deploymentDisplayName` and `deploymentDisplaySubtitle` now sit under `appearance`, and `endUserAttribution` and `userContentRendererUrl` under `workspace`. The flat MDM key names are unchanged. * Changed `managedMcpServers` and `microsoftAuthBroker` to be supported on standard deployments as well, so an administrator can enable the built-in Microsoft 365 connector by adding it to `managedMcpServers` through MDM. It stays off unless configured. * Changed where several keys can be delivered from: `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 consent prompt above. * Deprecated `organizationPluginsUrl` and removed it from the configuration reference. The key is still honored, but organization plugins are better configured with `allowedPluginMarketplaces`. * Updated `enduserAttribution` to the corrected spelling `endUserAttribution`. The previous spelling is still accepted and now records a configuration warning. * Fixed connector sign-in recovery: connectors no longer ask you to sign in again after a slow startup when the credentials are still valid, and the GitHub connector shows its Reconnect card on the next tool call after its token is revoked on github.com instead of staying stuck. * Fixed tasks failing with "Couldn't start this task" for the rest of the session when the app launched while the network or the sign-in credential was unavailable. * Fixed the app losing administrator-enabled features, such as the Chat tab, for the rest of the session when the organization's configuration server was unreachable at launch. It now retries in the background and recovers. * Fixed the home composer and sidebar still offering Cowork when an administrator has turned the Cowork tab off; Cowork is now hidden instead of greyed out, while Chat and Projects remain available. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * Fixed sessions started while configured MCP servers were still connecting having no connector tools until a new conversation was started. * Fixed the Microsoft 365 connector not appearing after first-time sign-in until the app was restarted. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * Fixed plugin hooks silently doing nothing on Windows. **3P** * Added the `mcpPersistentAlwaysAllowEnabled` managed configuration key, letting admins disable the persistent "Always allow" approvals for MCP tools while keeping session-scoped approvals available. * Added the five-level effort selector for Claude Opus 5 in the model picker. Extended thinking is always on for Opus 5. **General** * Added an option to keep custom plugin marketplaces up to date automatically, and fixed a marketplace refresh reporting success before the sync ran and re-adding an existing marketplace not refreshing its contents. * Improved keyboard and screen reader support across the app: settings tabs and share-visibility choices respond to arrow keys, dialogs announce meaningful titles, decorative graphics no longer clutter screen reader output, and the find bar, search fields, and pane resize handles show a visible focus outline and announce their size. * Fixed failed uploads being reported as corrupted or unsupported files, and retries showing a "Server is busy" message for unrelated errors. * Fixed safety-block notices suggesting you switch models when no alternative model was available for that topic. * Fixed the app failing to launch when its settings file or logs folder was corrupted, and saved sessions disappearing after a relaunch when one session's stored data was invalid. * Fixed the app window resizing abruptly and losing its saved size and position when signing in or out; it now animates smoothly in place. **Code** * Added iOS Simulator support: Claude Code can build your iOS app, launch the simulator, and verify the result without leaving the session. * Added iOS Simulator and Android Emulator buttons to the session titlebar when the agent launches an app on a device, so the pane is one click to reopen. * Added Pause Project, which pauses a project's coordinator and new session spawning from settings and shows a Resume banner above the composer. * Added screenshot annotation in the composer: click a staged image, open the pencil, and draw with pen, shapes, text, and colors before sending. * Improved how large sessions open: the newest messages paint first while older history loads in the background. * Fixed Code sessions affecting the wrong files: background worktree cleanup could switch or reset the main repository checkout when a worktree folder was only partially removed, and new sessions could copy uncommitted files from the original folder. * Fixed session list problems: finished sessions still showing as running, deleted sessions reappearing as empty "Session not found on disk" entries after an update, archived sessions still appearing active on claude.ai and other devices, and sessions started from claude.ai missing Rename, Archive, and Delete in the sidebar menu. * Fixed the app freezing when Claude Code updated its configuration file during concurrent use, and web pages in the Browser pane freezing the app with alert and confirm dialogs. **Cowork** * Added /usage and /cost to Cowork tasks: an inline card shows your plan limits and the session's usage without sending anything to the model. * Improved background computer use so it types faster and no longer leaves menus stuck open on screen. * Updated folder access prompts for cloud Cowork tasks to note that files Claude uses leave your device and are processed on Anthropic's servers. * Fixed changes to Instructions for Claude sometimes not applying to new sessions, and edits reverting to an earlier version while a session was running, including after an app restart. * Fixed Cowork workspace problems: the Windows workspace failing to start when its virtual disk files were compressed, a backgrounded shell command leaving a session stuck reporting "already running", and bash commands failing when several subtasks ran them at once. * Fixed the message input staying stuck in a sending state when a folder access dialog went unanswered. **3P** * Added `deploymentDisplayName` and `deploymentDisplaySubtitle` to customize the deployment name and an optional subtitle shown in the account menu and sidebar. * Added `enduserAttribution`, which shows the signed-in user's identity in the sidebar, account menu, and Code tab, and includes it as the OpenTelemetry `enduser.id` attribute on telemetry sent to your configured collector. Administrators can turn it off, and an existing static `enduser.id` is kept. * Added `oauth.authorizationUrl` and `oauth.tokenUrl` to managed MCP servers for identity providers that do not serve a discovery document, and `oauth.additionalRedirectReferrerHosts` to allow sign-in callbacks from hosts other than the authorization URL's. * Added `userContentRendererUrl`, which sets the HTTPS origin that renders artifact and file previews; leave it unset to use the default Anthropic-hosted renderer. * Added a `broker` option to `inferenceFoundryAuthFlow` that signs in to Azure AI Foundry through the operating system's native account broker on Windows or Company Portal on macOS, so sign-in can satisfy Conditional Access policies that require a compliant device. Windows and macOS only. * Added a Usage page in Settings for custom deployments, showing token usage across Chat, Cowork, and Code. * Added Microsoft 365 Teams tools (send to a chat, channel, or thread; create a chat; @mention people) and formatted-body support for Outlook reply drafts. * Added the 1M context option in the model picker for gateway-discovered models that report the capability in `/v1/models`, without requiring an `inferenceModels` entry. * Changed telemetry on bootstrap-server deployments to default to disabled until the server explicitly enables it (previously only FedRAMP hosts), and added the ability to disable error and usage reporting through bootstrap configuration. * Fixed managed MCP connectors: a server that requires authentication now opens a sign-in window even when its configuration does not explicitly enable OAuth, and an `oauth` entry with sign-in fields but a missing or empty `clientId` is now rejected at load with a clear error instead of silently attempting automatic registration. * Fixed managed MCP tool policies that block all tools by default with per-tool exceptions denying the excepted tools in Claude Code sessions. * Fixed sessions, skills, and plugins intermittently disappearing after sign-in or configuration changes. * Fixed the Claude.ai sign-in option being hidden on deployments configured with a bootstrap URL; it is now hidden only when the administrator explicitly disables the deployment mode chooser. * Fixed the bundled Microsoft 365 connector showing only an opaque tool error when its sign-in expired; it now shows an inline Reconnect card. * Fixed the token-cap setup fields so the maximum tokens per window and the token cap window hours are required together; setting only one previously produced a cap that enforced nothing. **General** * Fixed sessions on Windows failing on every turn with a "Socket is closed" error when traffic passed through a corporate proxy that inspects encrypted connections, by updating the bundled Claude Code CLI to 2.1.215. Interrupted responses now retry on a fresh connection instead of ending the turn. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Improved responsiveness while artifacts generate, so typing and scrolling stay smooth during generation. * Improved the "Add to project" menu to show only projects you can move into, with your own projects listed first. * Fixed rare freezes when a transcript contained very large whitespace-padded messages or tool output. * Fixed tool errors blaming an organization policy when a site was actually blocked by your own site permissions or settings. **Code** * Added controls for project owners to remove members from a shared project and copy an invite link from the members dialog. * Added per-row actions to queued messages (Edit in composer, Send now, and Remove), with right-click support. * Fixed a new session sometimes taking over the directory another session was still working in. * Fixed Code sessions hanging at startup when skill syncing was slow, and tools on your shell `PATH` staying undetected when shell environment detection timed out at startup. * Fixed freezes, a stuck "loading earlier messages" spinner, and blank rendering when scrolling back through very large session transcripts or when a running task's output grew very large. * Fixed the New session button, `⌘N` (or `Ctrl+N` on Windows and Linux), and the project header "+" discarding an unsent composer draft. **Cowork** * Improved writing drafts to consistently appear as preview cards before being staged in a connected app such as Slack. * Fixed documents Claude creates not reliably opening in the editor. * Fixed files edited by Claude sometimes reading back stale or truncated content on Windows. * Fixed the chat window freezing and not updating while Claude uses your computer. * Fixed the document editor sometimes attributing your own typing to Claude while autosaving. * Fixed working documents disappearing from the Documents panel after a temporary disk error. **3P** * Added `disableBrowserExternalNavigation`, which admins can set to `true` in Claude Code's `managed-settings.json` to keep the Code tab's Browser pane limited to localhost for both users and Claude. Local dev servers and file previews are unaffected. * Added `otlpTracesEnabled` (beta), which also exports OpenTelemetry traces from Cowork tasks and Code sessions to your configured collector. * Updated the allowed workspace folders policy to also apply to Code sessions on SSH hosts, evaluated against the folders on the remote host. * Fixed enforcement of the managed Auto mode opt-out. * Fixed plugins being treated as required by your organization when their marketplace name merely resolved under a required marketplace entry; only the exact entry a name resolves to now applies, so affected plugins can be uninstalled again. * Fixed saving a skill created in chat failing; skills now save to the app's local skill storage. * Fixed tools without a configured `toolPolicy` offering only Allow once and Deny; they now show the full set of approval options (Allow for this task, Allow for all tasks) and the prompt-injection warning. Explicit `ask` policies still prompt on every call. **General** * Fixed installed extensions failing to load and showing an endless loading state. **Code** * No user-facing changes. **Cowork** * Fixed a status indicator that stayed on after a conversation finished. **3P** * No user-facing changes. **General** * Changed the web-fetch permission prompt to default to "Allow all for this website" when that grant is available; "Allow once" stays the default otherwise, and pressing Enter always answers "Allow once". * Updated the embedded Claude Code engine to the latest version. * Fixed a crash on launch when Claude's worktree bookkeeping file couldn't be read or written. * Fixed brief app freezes when opening terminals or switching sessions on Windows, and when the @ mention menu refreshed the list of open windows. * Fixed scheduled tasks and routines: editing a routine no longer deletes its one-time schedule, "Run now" no longer silently does nothing until the app restarts, and you can now rename routines and scheduled tasks from the edit dialog. * Fixed session exports that could produce an archive without the transcript; the transcript is now always included as `transcript.jsonl`, and the export shows a clear error when it can't be included. * Fixed the "Sign in again" prompt not appearing when a background session was blocked for session freshness, including while the desktop was idle. **Code** * Added a browser-style address bar to the preview pane, and a clear message, with the option to open the site in your browser, when a page can't be displayed instead of showing a blank page. * Added the ability to pin artifacts from the gallery or the artifact viewer, and to filter the gallery to your pinned artifacts. * Improved SSH session connection handling: messages no longer hang after the computer wakes from sleep, sessions recover from repeated disconnects, and a reconnecting indicator appears while the connection is restored. * Fixed `permissions.defaultMode` in Claude Code settings being ignored for new sessions after a per-folder permission mode had been chosen. * Fixed branch switches on large repositories failing after an uncommitted-changes stash timed out, and restored your stashed changes when a switch fails. * Fixed several session reliability problems: a session could get stuck showing "running" and queue new messages forever, a just-started session could disappear from the sidebar or show "session could not be found" during startup, and streamed responses could break or show a literal "undefined". **Cowork** * Added a live word count and a copy button to each document bar above the composer. * Changed Markdown files Claude delivers to open in the document editor instead of a plain-text preview, without flashing the old viewer first. * Changed the composer to keep the standard Send button while a response is running: it appears when you type, and sending mid-response queues your message instead of showing a separate Queue button. * Fixed Claude's mid-task replies not appearing in the conversation; they now show under a collapsed "Working notes" row. * Fixed screenshots from connected browsers and computer use not being saved to the task folder. * Fixed text typed in one conversation appearing in other conversations' composers when switching between sessions. **3P** * Added `envHelper` and `envHelperTtlSec` subfields to `managedMcpServers`, letting a managed stdio server load environment variables from an admin-provided helper executable. * Added an All tab to organization plugins that browses and searches every configured marketplace at once, and labeled plugins with their source marketplace so they can be filtered when more than one is configured. * Added support for the `eu` and `us` multi-region Vertex AI endpoints, required for the newest models with EU and US data residency. * Added the `disableFeatureDiscovery` key, which hides unprompted feature announcements such as the post-update "What's new" nudge and new-feature tips. Release notes remain available from the menu. * Fixed remote MCP connectors whose `headersHelper` mints short-lived credentials failing one token-lifetime after connecting: the helper now re-runs before expiry and the refreshed headers are applied to the live connection. The new `headersHelperRefreshBufferSec` subfield of `managedMcpServers` tunes how far ahead of expiry the refresh runs. * Added the `prefer1m` subfield to `inferenceModels`, which makes a model's 1M-context variant the default picker selection when paired with `supports1m`. * Added the `toolSearchEnabled` key. When enabled, Code and Cowork sessions load MCP tool schemas on demand instead of placing every schema in context up front, which helps when many configured tools would otherwise crowd the context window. Requires an inference endpoint that forwards `anthropic-beta` request headers. * Bootstrap-delivered model configuration is now forwarded to Claude Code sessions in third-party deployments. * Changed the projects environment picker to respect an organization policy that hides Anthropic-managed environments. * Removed the Beta designation from the `chatTabEnabled` and `chatAdvancedFileAnalysisEnabled` keys; the Chat tab and advanced file analysis are now generally available. Availability is unchanged, and both remain opt-in. * Fixed a bug affecting third-party plugins installed from external sources (GitHub, URL, or npm). **General** * Fixed an issue where permission prompts and in-session questions could silently stop appearing after an input-handling error — if Claude asked a question or requested permission and the prompt never showed up, this release fixes that. (Updates the bundled Claude Code CLI to 2.1.209.) **General** * Fixed `claude://` deep links being ignored when opening one launched the app from a closed state, including on Windows and Linux. * Fixed device attestation failing on Windows when sending several messages at once. * Fixed garbled tool summaries in the transcript: descriptions that don't start with a recognized verb (for example "Final verification") now appear as written instead of being mis-conjugated. * Fixed skill proposal and skill-file cards failing to save with "Couldn't save this skill" when a skill of that name already exists; they now offer "Update skill" and a replace confirmation. * Fixed the app forgetting your last-used tab (for example Code) after an update or re-login. * Fixed the menu bar usage menu showing an empty progress bar for extra usage when the spend cap is unlimited. **Code** * Added a Troubleshooting option to import Claude Code CLI sessions found on this computer into the session list. * Fixed a typed `` turn rendering as a spoofable "Message from `{server}`" card instead of as your own text. * Fixed cross-session messages going missing in the transcript: messages from another session no longer disappear when they arrive in the same turn as other content or when their envelope can't be fully parsed. * Fixed file links to files outside the working directory, including reports Claude writes to its scratchpad, showing "This file is outside the working directory" instead of opening. * Fixed the context window indicator and token count staying at the pre-compaction value after compacting a conversation. **Cowork** * Fixed admin-configured plugin marketplace sync failing behind corporate proxies on macOS. * Fixed plugin connectors sometimes missing from the Connectors list and tool permission prompts when they were slow to start. * Fixed skills saved in a remote session sometimes still returning "Unknown command" right after saving. * Fixed the "Run this task while your Mac sleeps" setting turning itself off after an app update. **3P** * Added `*` wildcard matching for managed MCP `toolPolicy` keys; partial wildcard keys such as `"outlook_*"` in existing configurations now take effect, including any `allow` wildcards, which pre-approve the tools they match. Exact keys and the standalone `"*"` key behave as before. * Added support for exporting Cowork task telemetry over `otlpProtocol: grpc` on macOS and Linux when no network proxy is configured. * Fixed Azure AI Foundry sessions failing with an authentication error on every message after interactive Microsoft Entra ID sign-in. * Fixed gateway-SSO bootstrap dropping cross-origin `managedMcpServers` entries, so admin-provisioned third-party connectors reach the app under device-code sign-in. * Fixed MCP connectors failing to connect through gateways that optionally request a TLS client certificate, even though the connection test passed. * Fixed sign-in timing out with identity providers (such as PingFederate) that redirect via a rendered page after authentication. * Fixed third-party settings ignoring managed configuration: the Claude Code pane now follows `isClaudeCodeForDesktopEnabled`, the Developer tab hides when `isLocalDevMcpEnabled` is off, and the Capabilities and Voice settings no longer appear. **General** * Added automatic updates on Linux through the Anthropic apt repository, so new versions arrive with `apt upgrade` (and unattended upgrades where enabled). * Added the ability to archive or delete the current chat, project, task, or coding session directly from the command palette (`⌘K`, or `Ctrl+K` on Windows and Linux). * Fixed bank payment-verification (3DS) pages not loading during checkout. * Fixed MCP connectors in artifacts being silently dropped; approving a connector now reliably grants its tools to the artifact, and a previously stuck approval heals itself the next time you approve. * Fixed repeated crashes on Linux caused by unstable graphics acceleration; the app now turns acceleration off automatically and tells you. * Fixed the app becoming unresponsive when a session folder is on a slow or disconnected network drive. **Code** * Added descriptive branch names for local Code sessions, derived from your first message, in place of the random adjective-noun names. * Changed the default transcript and composer width to a narrower, more readable column; a width you already chose in Settings → Appearance is preserved. * Fixed "Open in Finder", "Open in editor", and "Attach to chat" doing nothing, or using the wrong path, for files in the diff panel when the session folder differs from the repo folder. * Fixed freezes and stalls: while restoring a large number of sessions at startup, while builds or file syncs churned files inside a watched folder, and while the diff panel refreshed during a response. * Fixed newly trusted folders sometimes failing to start a session with a "workspace is not trusted" error. * Fixed security-key and phone sign-ins not completing in preview tabs. **Cowork** * Added a copyright-access notice in the session timeline when Claude in Chrome first operates on certain news publisher sites. * Added keyboard access to the preview pane: Tab reaches a "Preview page" control, Enter moves focus into the loaded page, and `F6` (or `Ctrl+F6`) moves it back out. * Fixed Cowork offering terminal access, and showing an impossible fix suggestion, on devices whose operating system cannot provide the virtualization its isolated environment needs (such as ChromeOS), where every command immediately failed. **3P** * Added `inferenceFoundryAuthFlow` to choose how interactive Microsoft Entra ID sign-in for Azure AI Foundry runs: `device-code` (the default, which shows a code to enter at `microsoft.com/devicelogin`) or `browser`, which opens the system browser for an authorization-code (PKCE) sign-in. * Added `microsoftAuthBroker`; set it to `disabled` to force browser-based Microsoft 365 sign-in instead of the native Company Portal or Windows account broker. * Added a "session expires soon" warning for Bedrock SSO and AWS-profile sign-in so you can re-authenticate before hitting an error. * Added a `startupTimeoutSec` option for managed local (stdio) MCP servers and raised the default startup timeout from 10 to 120 seconds, fixing connection failures when a server command downloads packages on first run (for example `uvx` or `npx`). * Added support for background agents: long-running tasks now stay signed in after your identity provider's access token expires. * Added the ability for administrators to grant Microsoft 365 write scopes (send mail; edit calendars and files; send Teams chat; mailbox settings) through managed configuration. * (breaking) Changed the default for Desktop Extensions (`.dxt` and `.mcpb`): they no longer load unless you set `isDesktopExtensionEnabled` to `true` in managed configuration. Previously they loaded by default and only the install UI was blocked. * Updated `allowedPluginMarketplaces` (beta) so it can be delivered per-user through the bootstrap server; a response that omits the key leaves MDM-provisioned marketplaces in place. * Fixed a one-time loss of sign-ins on some managed Windows machines after app data moved to a new location. * Fixed AWS credentials not reaching the Code tab's terminal for Amazon Bedrock configurations that use IAM Identity Center. * Fixed bundled Microsoft 365 and other MCP connectors failing to connect on networks with corporate TLS inspection (custom root CA). * Fixed connection tests reporting false failures: the test now runs MCP helper scripts and checks managed configurations exactly as saved, and uses the same Azure AI Foundry endpoint that sessions use. * Fixed managed MCP connectors failing with a credential-storage error when the server allows anonymous access. * Fixed the Microsoft 365 connector failing to sign in on Macs enrolled with Microsoft Company Portal. * Fixed the setup form incorrectly showing "Blocked address" for internal MCP or OAuth servers on IPv6 enterprise networks. **General** * Updated the embedded Claude Code engine to the latest version. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * Fixed `apt update` failing on Linux after uninstalling a Claude that was installed from the apt repository. * Fixed being asked to sign in repeatedly after a session expired while you were using the app; your in-progress message draft now returns when you sign back in within 10 minutes, and signing out still clears it. * Fixed being unable to disable, delete, or uninstall plugins from GitHub-connected marketplaces, or to remove those marketplaces. * Fixed pressing Enter not sending your message when an @mention had no matching results. * Fixed remote SSH sessions getting stuck in a reconnect loop on very large messages, being lost when the computer woke from sleep mid-reconnect, and occasionally sending the same input twice after reconnecting. * Fixed setup on Windows getting stuck retrying a download when the download folder was locked or inaccessible. * Fixed the file-open spinner on Linux staying up after the download completed. **Code** * Added a "Choose folder" option to recover a session whose working folder is missing: the conversation forks into the folder you pick and the stuck session is archived. * Added a "Switch organization" option on the "session not found" page so you can reopen a session link under the right organization. * Added drag-to-reorder for queued messages, and Steer now works for messages that include images. * Improved the Code tab's live preview: it now reports honest connection and loading status (including when a page arrives but never finishes loading, or a server overloads itself with requests), adds browser-style Back, Forward, and Reload/Stop controls, and lets you close other preview tabs. * Fixed background tasks and workflows continuing to show as running after they finished, the session restarted, or the session was stopped. * Fixed Remote Control sessions spinning forever with no error after you sent a message when the hosting computer was no longer connected. * Fixed the sidebar project + button opening an empty prompt (or pointing at github.com) for GitHub Enterprise repositories. **Cowork** * Added click-to-zoom and drag-to-pan to the fullscreen image viewer. * Fixed Computer Use teach mode where the Next and Exit buttons sometimes stopped responding until you switched apps and back, and cleared up teach-mode visuals so the screen-edge glow no longer flickers and the status indicator no longer sticks after you exit a guide. * Fixed dictation dropping back to the text box when started from the mic button in existing sessions. * Fixed document tools in cloud sessions acting on your local files instead of the session's files. **3P** * Added a usage breakdown by model family, source attribution, and usage tips to the `/usage` card. * Removed automatic addition of Anthropic's default plugin marketplace on third-party deployments, and removed the `disableDefaultPlugins` managed configuration key (which had no effect there). Provision marketplaces via `allowedPluginMarketplaces` (beta). **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * Added Claude Fable 5 to the model picker for organizations with access. **General** * Added Linux support: Claude Desktop is now available for Debian and Ubuntu on x64 and arm64, installable as a .deb package. * Updated the plugin Directory to show admin-configured marketplaces under the Organization tab and refresh them automatically when the source repository updates. * Fixed plugin and skill downloads stalling for several minutes on a dead connection before retrying; stalled downloads now retry sooner. * Fixed prompt and tool-detail content missing from OpenTelemetry exports for standard deployments that have not set an explicit content-capture policy; third-party deployments are unchanged. * Changed zoom in and out to use smaller steps for finer control. **Code** * Added an integrated terminal pane and inline image previews in the transcript for SSH sessions. * Added step-by-step progress and a Stop button while a session's worktree is being set up, so a long checkout on a large repository can be cancelled. * Added a right-click menu in the Terminal pane with Copy, Paste, and Attach selection as context. * Updated the transcript to mask API keys and tokens by default; click the eye icon to reveal them. * Fixed folder access and cross-session requests being rejected after you approved them when permission mode was Auto or Bypass permissions. * Fixed failed mid-turn message sends (for example, while offline) dropping your text instead of returning it to the input. * Fixed new session worktrees branching from the currently checked-out branch instead of the repository's default branch, and archived sessions leaving their worktree folders on disk. **Cowork** * Fixed a crash when resuming sessions with malformed remote connector data on disk. * Fixed the workspace download restarting from zero after a network interruption; it now resumes from where it left off and retries automatically. * Fixed folder and file names containing a dollar sign being misread, which broke file references. * Fixed dictation immediately dropping back to the text input in existing sessions. * Fixed an error caused by Claude trying to read a document creation skill that was not available. * Fixed clicking a built-in workflow (such as `deep-research`) in the activity panel's Skills section showing an empty drawer instead of its name and source. **3P** * Added the `allowedPluginMarketplaces` managed configuration key. Configured git repositories appear under the Directory's Organization tab. * Added an optional `omitOfflineAccess` subfield to the `inferenceVertexWorkforceOidc` configuration. Enable it when an identity provider rejects the `offline_access` scope; the app then prompts for sign-in each time the identity provider token expires instead of refreshing silently. * Added managed configuration support on Linux: administrators can provision settings in a root-owned `/etc/claude-desktop/managed-settings.json`, validated against the same schema as the macOS and Windows sources. * Fixed claude.ai sign-in never completing on Windows when an enterprise inference provider is configured. * Fixed subagents failing with an invalid model error on third-party inference providers. * Fixed `inferenceModels[].supports1m` being ignored, restoring the 1M-context option in the model picker for Bedrock, Vertex, Foundry, and gateway providers. * Fixed the Microsoft 365 connector showing an unexpected admin-consent prompt after updating on tenants with restrictive consent policies when the connector's Access setting was blank. Also updated the bundled connector with tools to read the signed-in user's profile and draft reply-all emails. * Improved expired sign-in handling for third-party inference providers and connectors: a sign-in prompt now appears whichever credential type expired, connector authentication errors are shown in Settings and inline in chat with a Reconnect action, and background Code sessions stay signed in across a credential refresh. * Fixed several connector reliability issues: connectors silently stopping mid-session after an OAuth refresh failed instead of prompting to reconnect, connectors configured with both OAuth sign-in and custom headers failing to connect, and admin-configured connectors not appearing in a session until they were signed in. **General** * Updated the embedded Claude Code engine to the latest version. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * No user-facing changes. **General** * No user-facing changes. **Code** * No user-facing changes. **Cowork** * No user-facing changes. **3P** * Fixed locally-configured stdio MCP servers being refused in third-party deployments that don't use MDM. * Fixed third-party MCP connectors disconnecting on every app restart when the OAuth provider returns a non-standard refresh response. * Fixed Microsoft 365 brokered sign-in failing with "No reply address provided" on managed Macs. **General** * Fixed a crash on launch caused by an unusually large saved session. * Fixed the conversation jumping and the Progress panel flashing when opening a completed task. * Improved keyboard navigation: a message's action buttons are now a single Tab stop, with arrow keys to move between them. **Code** * Fixed high background CPU usage when several Code sessions were open in the same large repository. * Fixed people without a Claude Code seat being sent to the marketing site from `/code`; they now see an in-app organization switcher. * Added support for custom cron expressions when scheduling local routines. * Added "Open in VS Code", "Open in Cursor", and similar actions to the file panel, file tree, plan panel, titlebar, and sidebar in SSH sessions. * Fixed attachment cards for files that exist only inside a session doing nothing when clicked; they now open in the File pane, lightbox, Preview pane, or Files browser. * Added a "Load more" button to the All sessions list for people with many sessions. **Cowork** * Fixed workspace setup repeatedly failing with the same checksum error after a corrupted download, until the cache was cleared. * Fixed Cowork sessions losing their project after restarting the app. * Added a one-time prompt before Claude runs a dynamic workflow, explaining what workflows do. * Improved the time it takes to start a session. **3P** * Added a managed `websearch` built-in tool so self-hosted deployments can search the web. Admins configure Brave, Tavily, Exa, or a custom endpoint in managed config, and it is available in both the Cowork and Code tabs. * Added an `otlpContentCapture` managed setting that lets admins opt in to sending specific categories of unredacted content — user prompts, assistant responses, tool inputs, tool outputs, and raw API request/response bodies — to their OTLP collector. * Updated the Microsoft 365 built-in connector's `scope` field to accept `MailboxSettings.Read`. * Fixed managed connectors that lost their connection staying broken with failing tool calls; they now reconnect automatically on the next tool call, including from newly started conversations, and show a message if reconnecting fails. * Fixed Microsoft 365 connector sign-in failing on Windows because of a broker error. * Fixed a sign-in loop when your organization's gateway denies access; the app now shows "Access denied" and points you to your administrator. * Fixed the selected model reverting after restarting the app and resuming a session. * Added a `disableBundledSkills` managed config key that turns off Claude Code's bundled skills and workflows (such as `deep-research`) on that device. **General** * No user-facing changes. **Code** * Added an inline card for multiple-choice questions from Claude, so you can pick an option and step through each question before your choices are sent as a single reply. * Fixed the app crashing shortly after opening the Code tab when local session history files are very large. * Fixed the integrated terminal eventually failing to open new shells after the app had been running for several days on macOS. * Fixed forked sessions not carrying over pull requests from the original conversation, and pull request rows staying marked as closed after being reopened on GitHub. * Fixed the @-mention dropdown, side-chat panel, and plan-comment popover rendering, resizing, and dismissing in the wrong window when a session is opened in its own window. * Fixed an extra tab opening in the system browser when navigating with the Artifacts pane open. **Cowork** * Added the ability to delete Cowork sessions from the sidebar, recents, and Spaces views. **3P** * Published the v2 bootstrap-response JSON schema (nested format). The v1 flat schema remains supported. * Removed support for installing connector extensions from local `.mcpb` and `.dxt` files. * Fixed the Setup panel being locked when only the auto-update policy was deployed via MDM. * Fixed connectors configured by your organization not appearing until restart after first sign-in. * Fixed the model picker dropping to "Default model" mid-session when a gateway's model-list response was temporarily degraded. **General** * Fixed the app prompting you to sign in again every day when your claude.ai session was more than a day old. * Fixed Claude Design links in chat navigating the app in place instead of opening Claude Design. * Fixed the app showing a blank window when a network proxy redirects the connection to Claude. **Code** * Changed routines to count against your regular usage limits instead of a separate daily included-run limit, and removed the included-runs indicator. * Updated the model picker to show restricted models as non-selectable with an explanatory badge, and to reflect your organization's allowed default model. * Fixed HTML and SVG file previews showing black text on a dark background in dark mode. * Fixed menus and popovers opening behind the preview panel. **Cowork** * Fixed Claude in Chrome file uploads failing for files in the session's shared folders and outputs. * Fixed scheduled tasks leaving earlier processes running after each scheduled run. * Fixed Windows file paths showing garbled characters in the folder access approval card, and reduced unnecessary folder access denials when allowed workspace folders are configured. **3P** * (breaking) Changed the `chatCodeExecutionEnabled` managed configuration key to `chatAdvancedFileAnalysisEnabled`. It still lets Claude analyze attached files such as spreadsheets and presentations by running code in a sandbox scoped to the session's attachments, and remains off by default. Update any managed configuration that sets the old key. * Deprecated the `betaFeaturesEnabled` managed configuration key; use the per-feature keys `chatTabEnabled` and `chatAdvancedFileAnalysisEnabled` instead. The Beta label in the Setup window is now informational only, and the Beta label has been removed from the built-in Microsoft 365 connector presets. * Added the `inferenceSessionLifetimeSec` managed configuration key. Set it to your identity provider's session lifetime to show users a re-authenticate reminder before their sign-in expires. * Added `~` and environment variable expansion (such as `%APPDATA%` and `%OneDriveCommercial%`) to the `allowedWorkspaceFolders` setting, so folder paths can vary per user. * Added a per-folder pre-select option to `allowedWorkspaceFolders` so an administrator-configured folder can appear as a ready chip when users start a new task, and removed the "Create workspace folder?" prompt for administrator-configured folders. **General** * Improved find-in-page to search the entire session transcript instead of only the text scrolled into view, and the find bar now reliably takes keyboard focus when opened. * Added a unified Artifacts view that lists your chat, Code, and Cowork artifacts in one searchable place, with a "New artifact" menu and a "Filter by" control to narrow the list by source. * Fixed keyboard shortcut conflicts failing silently. Assigning a shortcut already held by another app now tells you and keeps your previous shortcut working, and Quick Entry registration errors now appear in Settings. * Fixed the first-run notification explaining that Claude keeps running in the notification area never appearing on Windows. **Code** * Added running dev servers to the Background tasks panel, with stop and open-preview actions. * Improved the Code file viewer: images, video, and audio now play inline instead of showing as text, and Markdown, CSV, and image files refresh automatically when Claude edits them. * Updated the model picker. The three headline models appear at the top level with older models and context-size variants under "More models", each model shows a capability description, and currently-unavailable models appear disabled instead of failing when selected. * Updated the in-session artifact panel: switch between a session's published artifacts from the title dropdown, see when an artifact was last updated, copy a share link, and open, share, or delete the artifact from the overflow menu. * Changed the Code sessions tab from "Projects" to "All sessions". It now lists your non-project sessions alongside project sessions and adds a multi-select Environment filter. * Fixed pull request status checks. Failures now show a small warning indicator on the branch row instead of repeated error popups, the "status couldn't be checked" warning appears less often and can always be dismissed, and only GitHub CLI sign-in problems still raise a notification. **Cowork** * Fixed corrupt plugin downloads crashing or hanging the app. * Fixed skills sometimes staying on an older version after being edited until toggled off and on. **3P** * Added the Chat tab as a beta feature controlled by the `chatTabEnabled` managed configuration key. The separate `chatCodeExecutionEnabled` key lets Claude analyze attachments and create files such as spreadsheets and presentations by running code in an isolated sandbox scoped to the session's attachments, and is off by default. * Added the `betaFeaturesEnabled` managed configuration key. Setting it to false disables every beta feature in the deployment, including the Chat tab. * Added Bedrock Mantle as an inference provider option. It reuses the existing `inferenceBedrockRegion` and `inferenceBedrockBaseUrl` managed configuration keys and authenticates with a bearer token or a credential helper. * Added `anthropicFamilyTier` and `isFamilyDefault` to managed `inferenceModels` entries. Tag each configured model with the Claude tier it stands in for so tier shortcuts like opus and sonnet resolve to your configured model IDs instead of the canonical names your provider may not route. * Added the `inferenceBedrockAwsCliPath` managed configuration key to set the AWS CLI's absolute path. This fixes aws sso login failing when the app is launched from Finder on macOS and the CLI is not on the default search path. * Fixed Google Workspace connectors never starting their OAuth sign-in. The MCP client identifier the app sends to connected servers is now `claude-desktop-3p`, changed from `custom3p-desktop`, so update any MCP server allowlists or log filters that match the old value. * Fixed the managed Tool policy `*` entry being ignored. It now applies as the default for any tool not listed by name. * Fixed organization plugins sometimes not opening from the Directory right after launch or update. * Fixed several connection and sign-in issues: Bedrock sessions now prompt to sign in again after AWS IAM Identity Center expires instead of failing with repeated credential errors, remote MCP connectors no longer stay Connected after a non-refreshable access token expires, the connection test now passes against gateways that optionally request a TLS client certificate, signing in after signing out no longer needs a double click, and sign-in recovery no longer uses stale configuration after a server-side update or leaves the model picker empty until restart. **General** * Added Find Next and Find Previous keyboard shortcuts to in-app search. * Fixed preview panes stealing keyboard focus from the chat input when they reloaded or navigated. * Fixed sessions failing to start after your sign-in expired — the app now prompts you to sign in again. **Code** * Added the Files panel to remote and SSH sessions — search the session's files and open them in the viewer — plus a Show in Files button in the file viewer. * Added a running-tasks button to the activity indicator that opens the Tasks panel, and Bash rows in the Background tasks panel now open to show their output, including a live tail while the command runs. * Fixed SSH sessions: forking no longer opens an empty conversation, and connections no longer fail with "Failed to upload file" errors on remotes first set up by early-2026 versions of the app. * Fixed renaming a session while its title was still generating — the generated title no longer overwrites the name you set. * Fixed the Pull Requests view showing "No open pull requests" when GitHub isn't connected — it now prompts you to connect. * Added model-picker memory — the picker now remembers your last model choice. **Cowork** * Fixed scheduled tasks firing many duplicate runs at once when the computer wakes from sleep. * Fixed remote sessions re-prompting for access to folders you had already trusted. * Fixed plugins becoming corrupted when they synced while you switched accounts. **3P** * Added the built-in Microsoft 365 connector — admins can configure it from the Setup window's server presets. Users sign in through their browser, and Claude can search and read Microsoft 365 mail, calendar, OneDrive, and SharePoint. It requests read-only access by default; admins can grant additional read scopes, such as Teams channel messages and meeting transcripts, with the managed server entry's scope setting. * Deprecated the "sso" value for the inferenceGatewayAuthScheme managed configuration key in favor of inferenceCredentialKind "interactive" — existing configurations keep working and log a deprecation warning. * Added the inferenceVertexOAuthLoginHint managed configuration key to pre-fill the Google account chooser when signing in to Vertex AI, so users in organizations federated to a third-party identity provider land on the right account automatically. **General** * Fixed Clear Cache and Restart signing you out instead of just clearing caches. * Fixed mouse back and forward buttons not navigating on macOS for mice managed by driver software like Logitech Options+, and added trackpad swipe navigation. * Fixed organization plugins sometimes failing to open right after app launch, and the plugin directory now offers Install again after an uninstall. * Fixed connector, Chrome extension, and plugin toggles in the composer's "+" menu not responding when you click directly on the switch. * Fixed an issue where signing in could leave the app unable to start sessions until it was restarted. * Fixed shell-exported custom request headers not reaching Claude Code sessions. **Code** * Fixed Claude losing its coding instructions, file-link formatting, and worktree context after a session resumed from idle. * Fixed the preview pane sometimes connecting to an unrelated dev server that was already using the configured port, and it now reopens the dev server you last picked for each project. * Improved responsiveness in Code sessions: smoother streaming of long code blocks, quicker side-panel shortcuts, and less delay opening cloud sessions with many screenshots. * Fixed popovers, dialogs, and the rewind picker not appearing — and typed characters jumping to the end of the composer — when a Code session is opened in its own window. * Fixed the slash-command menu opening behind the side chat panel. * Fixed the source-branch picker showing nothing for SSH sessions with worktree enabled. **Cowork** * Added a "Free Up Cowork Disk Space" option under Help > Troubleshooting, and Cowork now cleans up caches and old temporary files automatically when its workspace disk runs low. * Improved the read/unread toggle on sidebar sessions: it now works on the currently open session, has a larger click target, and shows a tooltip describing what a click will do. **3P** * Added support for the Fable model family, and for Mythos where your organization has access. * Fixed sign-in failing with external identity providers that reject the offline\_access scope — admins can now disable the automatic append. **General** * Fixed reinstalling Claude on Windows failing after an uninstall when IT had installed it for all users. * Fixed the app not starting automatically at login on Windows. * Added a banner when an update fails to install, instead of failing silently. * Fixed built-in connectors staying disconnected after a crash — existing sessions now reconnect them automatically, and disconnecting a built-in connector now signs it out and keeps it disconnected across restarts. **Code** * Added math rendering for inline and block expressions in Claude Code transcripts. * Added Ultracode to the effort slider, which selects the highest effort level and turns on dynamic workflows for the session. * Added drag-to-reorder and A→Z sorting for projects in the Claude Code sidebar. * Added triple-click to select a whole code block, plus right-click menu actions to copy a code block or inline code, in Claude Code transcripts. * Fixed resuming Code sessions when the working folder had moved or been deleted — sessions saved with a \~ path no longer show as missing or re-prompt for trust, and a deleted remote folder now reports clearly and offers a Fork session button instead of retrying in a loop. **Cowork** * Added a low-disk-space warning before Cowork downloads the files it needs to run. * Added in-session effort and thinking controls for local Cowork projects. * Updated the New project folder picker to default to your Claude data folder (\~/Claude/Projects) instead of \~/Documents. * Fixed Claude reporting that a skill was updated when the change was never saved to your account. * Fixed the /schedule command in Cowork showing as unavailable. **3P** * Fixed managed connectors and SSO sign-in requesting broader OAuth scopes than the administrator configured. * Fixed three Bedrock sign-in and session issues: SSO sign-in failing behind corporate proxies that intercept secure traffic, expired SSO tokens prompting a new sign-in every hour instead of refreshing automatically, and resumed sessions failing on their first message. # Run tasks in the background with Dispatch Source: https://claude.com/docs/cowork/guide/dispatch Assign work to a Dispatch agent that plans, runs, and reports on tasks while you do something else, on this computer or from your phone. Dispatch is a long-running agent in Cowork that takes high-level instructions and carries them out in the background. You describe an outcome in a single conversation; the Dispatch agent breaks it into tasks, runs each one as a separate Cowork or Code session, and surfaces the results in the sidebar when they finish. Unlike a normal Cowork chat, you don't watch each step. Dispatch is for work you want to start and come back to later. ## Prerequisites Dispatch requires a Pro or Max plan and the latest Claude Desktop app on macOS or Windows. ## Start a Dispatch task The Dispatch agent appears as **Dispatch** in the left sidebar. Selecting it opens a single conversation with the agent. Select **Dispatch** in the left side panel. Tell the agent what you want done, the same way you'd brief a colleague. For example: "Summarize the open Linear issues tagged reliability and draft a status update for the team channel." The agent decides how to split the work and starts one or more child tasks. Each child task appears under the Dispatch group in the sidebar with its own status. You converse with one Dispatch agent, but it can run many child tasks beneath that conversation. Child tasks don't spawn further children of their own. ## How Dispatch routes work The Dispatch agent routes each child task to the surface that fits it. | Task type | Runs in | Examples | | -------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ | | Coding work | Code, against a workspace you've already set up | Fix a bug, open a pull request, run tests | | Knowledge work | Cowork, in the [project](/docs/cowork/guide/projects) you specify (or your default project) | Research, write a document, organize files | When starting a task, you can tell the agent which Code workspace or Cowork project to use. If you don't, it lists what's available and chooses. ## Track task status Each child task shows its current state in the sidebar. Select any task to open its full transcript, the steps Claude took, and any files it produced. | State | Meaning | | --------------- | ---------------------------------------------------------- | | Running | Claude is actively working on the task | | Awaiting input | The task needs information from you before it can continue | | Awaiting answer | The task asked you a question and is waiting for a reply | | Completed | The task finished | | Error | The task stopped because something went wrong | | Archived | You marked the task as done and set it aside | ## Approve actions Dispatch needs When a child task needs permission to take an action (such as running a command or writing a file outside its workspace), the prompt is forwarded to you. If you don't respond within ten minutes, the request is automatically denied and the task continues without that action. Permission prompts behave the same as in a normal Cowork session. ## Continue from a finished task Select any child task in the sidebar to open its session. You can read the transcript, send follow-up messages, or ask the Dispatch agent to start a new task that builds on the result. ## Assign tasks from your phone When Claude Desktop is running, your computer registers as a Dispatch host. From the Claude mobile app, you can start a Dispatch conversation that runs on your desktop, then check results from either device. Leave Claude Desktop open with your computer awake and online. In the Claude mobile app, open Dispatch and describe the task. The work runs on your desktop. Progress and results appear in the Dispatch sidebar on desktop and in the mobile app. ## Related * [Organize work with projects](/docs/cowork/guide/projects) for the project context Dispatch routes knowledge work into * [Cowork overview](/docs/cowork/overview) for how Dispatch fits alongside sessions and projects # Install plugins Source: https://claude.com/docs/cowork/guide/plugins Add packaged skills, connectors, and agents to Cowork from the plugin marketplace or a file. A plugin is a package that extends what Claude can do in Cowork. Installing one can add skills, MCP connectors, subagents, slash commands, or hooks in a single step. Plugins come from the marketplace, from your organization, or from a file you upload. Plugins are available in Cowork and Code. They aren't used in Chat. ## What a plugin can contain A plugin's manifest declares any combination of the following. | Component | What it adds | | ---------- | ---------------------------------------------------------- | | Skills | Reusable instructions that teach Claude a workflow | | Connectors | MCP servers that give Claude access to an external service | | Agents | Specialized subagents Claude can delegate to | | Hooks | Scripts that run at defined points in a session | After installing, open the plugin to see what it provides. Skills and agents appear as tabs; connectors and hooks have their own pages. ## Install a plugin Open **Customize** in the sidebar, then **Plugins**. Select **Browse plugins** to see available plugins. The default marketplace is Anthropic's official catalog; you can add other marketplaces by URL. Select a plugin and click **Install**. If the plugin includes a connector that needs authentication, you're prompted to sign in. Open the installed plugin to see its skills, connectors, agents, and hooks. Enable or disable individual components as needed. To install from a file instead, select the upload option on the Plugins page and select the plugin package. ## Use a Git repository as a marketplace A Git repository that contains plugin packages can serve as a marketplace. This is the typical way teams distribute their own plugins without publishing to the public catalog. Repositories on GitHub (including GitHub Enterprise) are supported; public repositories on GitLab and Bitbucket also work. On the Plugins page, select **Add marketplace** and enter the repository's URL. Cowork accepts the standard `https://github.com/owner/repo` form and the `owner/repo` shorthand for GitHub. Plugins defined in the repository appear alongside plugins from other marketplaces. Install them the same way. Click **Update** on a marketplace to pull the latest plugins from its repository. For administrator-managed marketplaces, see [MCP, plugins, skills, and hooks](/docs/cowork/3p/extensions) in the deployment guide. ## Limits The following are the default limits for plugin packages and marketplaces. | Limit | Value | | ---------------------------------- | ------ | | Plugin package size (uncompressed) | 200 MB | | Files per plugin package | 5,000 | | Marketplace repository archive | 512 MB | | Plugins per marketplace | 500 | | Marketplaces you can add | 25 | The in-app skill viewer previews individual files up to 1 MB. Larger files appear in the file list as "too large to preview" but are still available to Claude at runtime. ## Plugins managed by your organization On Team and Enterprise plans, administrators can require certain plugins for everyone in the organization. Required plugins install automatically and show **This plugin is required by your organization**; you can't remove them. For how administrators provision plugins, see [MCP, plugins, skills, and hooks](/docs/cowork/3p/extensions) in the deployment guide. ## Update and remove plugins Cowork checks for plugin updates from the marketplace they came from. If you've edited a plugin's files locally, Cowork detects the change and warns you before an update would overwrite it. To remove a plugin you installed, open it under **Customize → Plugins** and click **Uninstall**. Organization-managed plugins can only be removed by an administrator. ## Related * [Plugins overview](/docs/plugins/overview) for how plugins work across Claude products * [Submit a plugin](/docs/plugins/submit) to publish your own to the marketplace * [MCP, plugins, skills, and hooks](/docs/cowork/3p/extensions) for administrator provisioning # Organize work with projects Source: https://claude.com/docs/cowork/guide/projects Group folders, instructions, and context into a Cowork project so Claude starts each session with the right setup. A Cowork project collects everything Claude needs for a recurring area of work: the local folders to read and write, standing instructions, useful links, and a dedicated memory store. When you start a session inside a project, Claude is already set up with that context. Projects live on your computer. They aren't synced to the cloud or shared with other people. ## What a project holds Each project bundles the following, and you can change any of it after creation. | Item | Purpose | | ------------------ | ------------------------------------------------------------------------------------- | | Description | What the project is for; Dispatch reads it when choosing a project for a task | | Folders | One or more local folders Claude can read and write inside this project's sessions | | Instructions | Standing guidance applied to every session in the project | | Links | Reference URLs (documents, dashboards, repositories) Claude can consult | | Projects from Chat | Projects you made in Chat (claude.ai) whose knowledge this Cowork project can draw on | | Memory | A project-scoped memory store that persists across sessions | ## Create a project Open **Projects** in the left navigation and choose the **+** button to start. You're offered three starting points. Select **Start from scratch** to create an empty project with a new folder, **Import a project** to bring an existing claude.ai project into Cowork, or **Use an existing folder** to point at a folder you already work from. Give the project a name and a short description so you can tell it apart in the sidebar. Attach the local folders Claude should have access to, and write any standing instructions you want applied to every session. You can attach more folders, links, or projects from Chat at any time from the project's settings. ## Work inside a project Select a project in the sidebar to start a new Cowork session with that project's folders mounted and instructions applied. Files Claude creates land in the project's folders; what Claude learns during the session is saved to the project's memory for next time. [Dispatch](/docs/cowork/guide/dispatch) can also route background tasks into a project, so long-running work picks up the same folders, instructions, and memory. When you drag files or folders into a project, individual files are copied into the project's first folder and folders are mounted as additional project folders. Claude reads individual files up to 50 MB. ## Cowork projects and claude.ai projects A Cowork project is not the same thing as a project on claude.ai. They're stored separately and have different capabilities. | | Cowork project | claude.ai project | | ------------------------ | --------------------- | --------------------------- | | Lives | On your computer only | In your Claude account | | Holds local folders | Yes | No | | Shareable with teammates | No | Yes, on Team and Enterprise | You can link a claude.ai project into a Cowork project so Cowork sessions can draw on its knowledge. Linking doesn't merge them; the claude.ai project stays where it is. ## Archive a project Archiving removes the project from your list and deletes its metadata (name, instructions, links, memory). It does not touch the local folders you attached; your files stay exactly where they are on disk. To archive, open the project's menu in the sidebar and choose **Archive**. ## Related * [Run tasks in the background with Dispatch](/docs/cowork/guide/dispatch) to run work inside a project without watching each step * [Install plugins](/docs/cowork/guide/plugins) to extend what Claude can do in a project's sessions * [Cowork overview](/docs/cowork/overview) for how projects relate to sessions and Dispatch # Monitoring Source: https://claude.com/docs/cowork/monitoring Track Cowork usage and activity across your organization with OpenTelemetry Track Cowork usage and activity across your organization by exporting events through [OpenTelemetry](https://opentelemetry.io/) (OTel). Cowork exports events via the OTel logs/events protocol, giving you visibility into user prompts, model responses, API requests, tool usage, and errors. Monitoring is available for Team and Enterprise plans. OTel monitoring requires Claude desktop app version 1.1.4173 or later. ## Setup Configure monitoring from the Cowork admin settings: 1. Navigate to **Admin settings > Cowork** 2. Configure the following fields: | Field | Description | Example | | ----------------- | ----------------------------------------- | ----------------------------------- | | **OTLP endpoint** | Your OpenTelemetry collector URL | `http://collector.example.com:4318` | | **OTLP protocol** | Transport protocol | `http/json` or `http/protobuf` | | **OTLP headers** | Authentication headers for your collector | `Authorization=Bearer your-token` | 3. Save your settings 4. Start a new Cowork session — settings are loaded at session start, so existing sessions won't pick up the new configuration The OTel exporter runs inside the Cowork VM, so it is subject to the session's egress rules. If your organization restricts network egress, Cowork automatically adds your collector's hostname to the session's egress allowlist. You don't need to add it at **Admin settings > Capabilities > Network egress**. ## Events Cowork exports the following events to your OTel collector. By default, events include metadata only. User prompt content, model response text, and tool details are included only when you enable them with the [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) setting. ### Event correlation When a user submits a prompt, Cowork may make multiple API calls and run several tools. The `prompt.id` attribute links all events back to the single prompt that triggered them. | Attribute | Description | | ----------- | ------------------------------------------------------------------------------------ | | `prompt.id` | UUID v4 identifier linking all events produced while processing a single user prompt | To trace all activity triggered by a single prompt, filter your events by a specific `prompt.id` value. On third-party deployments, you can additionally enable OpenTelemetry trace export with the [`otlpTracesEnabled`](/docs/third-party/claude-desktop/telemetry#traces-beta) setting (beta). When it is enabled, events emitted while a prompt is processed also carry `trace_id` and `span_id`, linking them to the session's trace spans for end-to-end correlation in your observability backend. ### Standard attributes All events include these attributes: | Attribute | Description | | ---------------------- | -------------------------------------------------------------------------------------------- | | `session.id` | Unique session identifier | | `organization.id` | Organization UUID | | `user.account_uuid` | User's account UUID | | `user.account_id` | Account ID in tagged format matching Anthropic admin APIs (for example, `user_01BWBeN28...`) | | `user.id` | Anonymous device/installation identifier | | `user.email` | User email | | `workspace.host_paths` | Host workspace directories selected in the desktop app (string array) | | `terminal.type` | Terminal type (`non-interactive` for Cowork) | The account attributes — `organization.id`, `user.account_uuid`, `user.account_id`, and `user.email` — are populated from the user's Anthropic account, so they appear on first-party deployments only. On [third-party deployments](/docs/third-party/claude-desktop/overview) there is no Anthropic account and these attributes are absent; instead, the export carries the signed-in user's identity as the `enduser.id` resource attribute, described under [User attribution](/docs/third-party/claude-desktop/telemetry#user-attribution). The `process.owner` resource attribute (the operating-system login name) is standard OpenTelemetry process metadata and is present on all deployments. ### User prompt event Logged when a user submits a prompt. **Event name**: `user_prompt` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ----------------- | --------------------------------------------------------------------- | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `prompt_length` | Length of the prompt | | `prompt` | Prompt content | ### Model response event Logged when the model completes a response that includes text output. Requires Claude desktop app version 1.17377 or later. **Event name**: `assistant_response` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `model` | Model that produced the response | | `request_id` | API request identifier | | `response_length` | Length of the response | | `response` | Model response text. Includes text output only; thinking content is excluded. Truncated to 60 KB. When model response capture is disabled, the value is the literal string ``. | Model responses are captured when [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) includes `assistantResponses`, and also whenever user prompts are captured. ### Tool result event Logged when a tool completes execution. **Event name**: `tool_result` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `tool_name` | Name of the tool | | `success` | `"true"` or `"false"` | | `duration_ms` | Execution time in milliseconds | | `error` | Error message (if failed) | | `decision_type` | Either `"accept"` or `"reject"` | | `decision_source` | How the decision was made — `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"` | | `tool_result_size_bytes` | Size of the tool result in bytes | | `mcp_server_scope` | MCP server scope identifier (for MCP tools) | | `tool_parameters` | JSON string containing tool-specific parameters, including `mcp_server_name` and `mcp_tool_name` for MCP tools | | `tool_input` | JSON-serialized tool arguments. Individual strings over 512 characters are truncated; entire string limited to \~4K characters. Applies to all tools including MCP tools. | ### API request event Logged for each API request to Claude. **Event name**: `api_request` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ----------------------- | --------------------------------------------------------------------- | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `model` | Model used (e.g., `claude-sonnet-5`) | | `cost_usd` | Estimated cost in USD | | `duration_ms` | Request duration in milliseconds | | `input_tokens` | Number of input tokens | | `output_tokens` | Number of output tokens | | `cache_read_tokens` | Number of tokens read from cache | | `cache_creation_tokens` | Number of tokens used for cache creation | | `speed` | `"fast"` or `"normal"` | ### API error event Logged when an API request to Claude fails. **Event name**: `api_error` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ----------------- | --------------------------------------------------------------------- | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `model` | Model used | | `error` | Error message | | `status_code` | HTTP status code as a string, or `"undefined"` for non-HTTP errors | | `duration_ms` | Request duration in milliseconds | | `attempt` | Attempt number (for retried requests) | | `speed` | `"fast"` or `"normal"` | ### Tool decision event Logged when a tool permission decision is made. **Event name**: `tool_decision` **Attributes**: All [standard attributes](#standard-attributes), plus: | Attribute | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | `event.timestamp` | ISO 8601 timestamp | | `event.sequence` | Monotonically increasing counter for ordering events within a session | | `tool_name` | Name of the tool | | `decision` | Either `"accept"` or `"reject"` | | `source` | Decision source — `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"` | ## Event analysis The exported events support a range of analyses: **Tool usage patterns** — Analyze tool result events to identify most frequently used tools, success rates, average execution times, and error patterns. **Cost monitoring** — Track `cost_usd` from API request events to understand usage trends across users and teams. Group by `user.account_uuid` or `organization.id` for per-user or per-team breakdowns. **Performance monitoring** — Track API request durations and tool execution times to identify performance bottlenecks. Cost values from events are approximations. For official billing data, refer to your billing dashboard. ## Backend considerations Your choice of logs backend determines the types of analyses you can perform: * **Log aggregation systems** (e.g., Elasticsearch, Loki): Full-text search and log analysis * **Columnar stores** (e.g., ClickHouse): Structured event analysis and complex queries * **Observability platforms** (e.g., Honeycomb, Datadog): Advanced querying, visualization, and alerting ## Service information All events are exported with the following resource attributes: | Attribute | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `service.name` | `cowork` | | `service.version` | Claude app version | | `host.arch` | Host architecture (e.g., `arm64`) | | `os.type` | Operating system type (e.g., `darwin`) | | `os.version` | Operating system version string | | `enduser.id` | The signed-in user's identity, on third-party deployments only. Controlled by the [`endUserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) setting; see [User attribution](/docs/third-party/claude-desktop/telemetry#user-attribution). | | `process.owner` | Operating-system login name | ## Security and privacy * Events are only exported when an admin configures the OTLP endpoint * User prompt content is included only when you enable `userPrompts` in [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) * On Claude desktop app version 1.17377 or later, model response text is included when you enable `assistantResponses` in `otlpContentCapture`, and also whenever user prompt content is included * The `tool_input` attribute (file paths, URLs, search patterns, and other arguments) is included only when you enable `toolDetails` in `otlpContentCapture` * On first-party deployments, `user.email` is always included in event attributes, so configure your telemetry backend to filter or redact it if this is a concern * On third-party deployments, `user.email` is absent; the export identifies users with the `enduser.id` resource attribute, controlled by the [`endUserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) setting # Overview Source: https://claude.com/docs/cowork/overview Learn about Cowork, Anthropic's agentic workspace Cowork uses the same agentic architecture that powers Claude Code, accessible within Claude Desktop without opening the terminal. Rather than responding to prompts sequentially, Claude tackles intricate, multi-step tasks autonomously. Describe a desired outcome, then return later to completed work — polished documents, organized files, synthesized research, and more. ## Key capabilities * **Works directly on your computer** — Claude reads and writes local files without requiring manual uploads or downloads. * **Claude in Chrome** — Pair [Claude in Chrome](https://claude.com/chrome) with Cowork to automate your tasks on any website. * **Sub-agent coordination** — Complex work gets divided into smaller tasks with parallel workstreams for faster results. * **Professional outputs** — Creates polished deliverables including Excel spreadsheets with functional formulas, PowerPoint presentations, and formatted documents. ## Extend Cowork with integrations Cowork supports the same extensibility features available across Claude products: Connect Claude to your tools and data sources using MCP. Teach Claude reusable workflows with custom instructions. Bundle skills, connectors, and more into shareable packages. Track usage and activity across your organization. You manage connectors, skills, and plugins from **Customize** in the sidebar. Cowork loads the ones enabled for your claude.ai account, synced at session start, and doesn't read the [Claude Code](https://code.claude.com/docs/en/skills) CLI's `~/.claude` directory on your machine. To use a skill or plugin that exists only in `~/.claude`, add it in **Customize**. # Your account Source: https://claude.com/docs/government/account/overview Check your own account details, usage limits, and active sessions. > **Who this is for:** Anyone with a Claude for Government account. The Account portal is where you view your own details rather than manage other people. It covers your own identity details, your personal usage allowance, and the places you are currently signed in. Nothing you do here affects any other user. Every user has access to this portal regardless of what role they hold. If you are a regular user with no administrative role, this is also where you land immediately after signing in, and it is the only part of the web portal you will see. > **For organization owners:** You land in the organization admin area instead when you sign in. You can reach your own account pages at any time from the **Switch to user view** link in the page footer, and return the same way. ## What's here * The [**Account**](/docs/government/account/profile) tab shows who you are, including your name, email address, organization, role, and seat tier. Everything on this tab is read-only. Your name and email come from your agency's directory; your organization, role, and seat tier are set by your directory or by an administrator. * The [**Usage**](/docs/government/account/usage) tab shows how much of your personal allowance you have used in the current 5-hour and 7-day windows, and when each one next resets. If you have hit a limit and Claude is paused, this tab is marked with a pulsing indicator in the navigation so you can spot it at a glance. * The [**Sessions**](/docs/government/account/sessions) tab lists every browser and desktop application where you are currently signed in, with the option to sign any of them out remotely. ## The page footer At the bottom of every page in this portal you will find your email address and a **Sign out** button. Signing out from the footer ends the session you are currently using and, where your agency uses single sign-on, also ends your session with the identity provider so that you will be prompted for credentials the next time you visit. > **For organization owners and tenant administrators:** The footer also includes a **Switch to admin view** link that takes you back to the administrative area. ## Things to know * **Nothing here is editable.** Your name, email, organization, role, and seat tier are all set in your agency's directory or by an administrator, and they flow into Claude for Government automatically. If any of these details are wrong, the [Account](/docs/government/account/profile) page explains where each one comes from and who to contact. * **The three tabs are independent.** Looking at your usage or your sessions has no effect on the other tabs, and the Sign out button in the footer works from any of them. * **The pulsing indicator on the Usage tab is the only alert in this portal.** It appears while either of your usage limits is full and disappears on its own once the limit resets. # Account Source: https://claude.com/docs/government/account/profile Use this page to confirm that you are signed in as the right person and to see what access you have been given. > **Who this is for:** Anyone with a Claude for Government account. Use this page to confirm that you are signed in as the right person and to see what access you have been given. The **Account** tab is the landing page of the user area. It shows the basics of your account in one place: your name and avatar at the top, followed by four fields that describe your access. Everything on this page is read-only. The values come from your agency's identity system and from settings that an administrator controls, so this page is for checking your details rather than changing them. ## What you'll see | Field | What it means | Where it comes from | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | **Email** | The address you sign in with. It is the unique identifier for your account, and notifications such as sign-in links are sent to it. | Your agency's identity provider. | | **Organization** | The organization you belong to within your agency's tenant. A tenant is your agency's overall space in Claude for Government, and it can contain several organizations (for example, one per bureau or office). Your organization determines which administrators manage your access and which usage pool your activity draws from. | Set when your account was created or when directory sync placed you. | | **Role** | What you are allowed to manage. **User** means you can use Claude but do not administer anything. **Owner** means you can manage your organization's users, seats, and settings. **Primary Owner** is the same as Owner with a few additional safeguards: a primary owner cannot be removed by other owners, and each organization can have at most three of them. | Assigned by an organization owner or by directory sync. | | **Seat tier** | The allowance you have been given. A seat tier is a named package that sets two things for you: how much Claude usage you get (shown on the [Usage](/docs/government/account/usage) tab) and which Claude models you are allowed to use. The tiers themselves, their names, and what each one includes are defined by your agency, so the name you see here is specific to your deployment. | Assigned to you by an organization owner. | The name and avatar at the top come from your agency's directory. The avatar is generated from your name; you cannot upload a custom picture. ## How to change these details None of these fields can be edited on this page. Where to go instead depends on the field: * **Name or email.** These are owned by your agency's identity provider or directory. Update them there, and the change flows into Claude for Government automatically the next time you sign in or the next time directory sync runs. You do not need to do anything inside Claude for Government. * **Organization.** Users cannot move themselves between organizations. If you have been placed in the wrong organization, ask your organization's owner or a tenant administrator to move you. * **Role.** An organization owner can promote or demote users between **User** and **Owner** in the administrative area. Ask your organization's owner if your role needs to change. * **Seat tier.** An organization owner assigns and changes seat tiers from the administrative area. See the next section if yours is missing. If you are helping a colleague troubleshoot, ask them to read out this page. It tells you in one screen which organization they are in, what role they hold, and whether they have a seat, which is usually enough to diagnose a "Claude is not working for me" report. ## If your seat tier says "No seat assigned" This section only appears when you do not have a seat tier. If a tier name is shown in the Seat tier field, you can skip this section. Without a seat tier you can sign in and see the portal, but you cannot send any messages to Claude, and the [Usage](/docs/government/account/usage) tab will show "No seat tier assigned" instead of your allowance. This is the expected state for a brand-new account that has not yet been given a seat, or for an account whose seat was deliberately removed. Ask your organization's owner to assign you a seat. Once they do, the tier name appears here immediately and you can start using Claude straight away without signing out and back in. > **For organization owners:** When you view your own profile with no seat, the page links you straight to **Admin → Users** so you can assign yourself one. Being an owner does not give you a seat by itself, because administrative access and Claude usage are granted separately. If your organization has no seats at all yet and nobody in it holds a seat, members without a seat tier are seated automatically when its first seats are allocated, Primary Owners first. # Sessions Source: https://claude.com/docs/government/account/sessions Use this page to see every place you are currently signed in to Claude for Government and to sign out of any of them remotely. > **Who this is for:** Anyone with a Claude for Government account. Use this page to see every place you are currently signed in to Claude for Government and to sign out of any of them remotely. A session is created each time you sign in, whether that is in a web browser or in the Claude desktop application. This page lists your active sessions so you can confirm that nothing unexpected has access to your account, and clean up after yourself on a computer you no longer have. ## What each row shows Each row is one active sign-in. The one you are using right now is labeled **this session** and always appears at the top of the list; the rest are ordered with the most recent first. * **Client** tells you which kind of application the sign-in is for. It shows **Browser** for a web sign-in, or **Desktop app** for the Claude application installed on a computer. * **via …** tells you how that session was established. **Single sign-on** means you authenticated through your agency's identity provider. **Device pairing** means a code shown in the desktop application was entered and approved in a browser, linking that application to your account. **Email link** means a one-time link was sent to your inbox and followed to sign in. * **Signed in** tells you when the session started. The time is shown in your local time zone along with a relative hint such as "2 days ago". ## What is not shown To limit how much information about your devices is held in the system, the list deliberately does not include IP addresses, locations, device names, or browser details. You can tell a browser session from a desktop session and you can see when each one started, but you cannot tell two browser sessions apart by device. When in doubt, sign out anything you cannot positively account for; signing back in is quick. ## How long sessions last Sessions expire after a period of inactivity, and using a session extends it. Once you have been inactive for longer than the idle timeout, that browser tab or desktop application prompts you to sign in again the next time it tries to do anything. Your agency or organization sets the idle timeout, which is 24 hours unless they have changed it. Your agency or organization can set a maximum session length in addition to the idle timeout. When a session reaches that length, it expires even if you have been using it the whole time, and the browser tab or desktop application prompts you to sign in again. Sessions that expire either way drop off this list automatically. Sessions can also end early in these ways: you sign one out from this page, you use the **Sign out** button in the page footer to end the session you are currently using, or an administrator deactivates your account or your organization, which immediately invalidates every session you have. When you sign in, Claude for Government can end another of your sessions. You can have up to six active sessions in each Claude application, such as Claude Desktop. You can also have up to three browser sessions in total. If a new sign-in goes over one of these limits, Claude for Government ends your session of the same kind that expires soonest. ## Signing out of other sessions These controls only appear when you have sessions besides the one you are using. If this is your only sign-in, the list shows just the current session and no sign-out buttons. * To end one session, select **Sign out** on its row. * To end everything except the one you are using, select **Sign out *N* other sessions** below the list. Neither of these affects the session you are currently using, and there is no confirmation prompt; the session is revoked as soon as you select the button. To sign out of the session you are using right now, use the **Sign out** button in the page footer instead. ### What actually happens when you sign out another session The sign-out is recorded the moment you select the button. The other browser or desktop application is not sent a live message, but the very next thing it tries to do (load a page, send a message, or refresh) will be refused and it will be returned to the sign-in screen. In practice this means the other session is cut off within seconds of any activity. A request that was already in flight at the instant you revoked may finish, but nothing new can start. Signing out another session from this page does not touch your agency's single sign-on session, so if the person at that other computer tries to sign back in, the identity provider may still let them straight through without re-entering a password. If that is a concern (for example, you left a shared computer signed in), sign the session out here first, then contact your agency's identity team to end the single sign-on session, or change your directory password. Signing out here versus signing out from the footer behave differently at the identity provider. The footer **Sign out** ends both your Claude for Government session and your single sign-on session, so you will be asked for credentials the next time you visit. The per-row **Sign out** on this page ends only the Claude for Government session and leaves single sign-on alone. ## If you see a session you don't recognize Sign it out from here right away. You can use **Sign out *N* other sessions** if you want to be certain you have cleared everything. If an unrecognized session reappears after you have done so, or anything else about the list looks wrong, report it to your organization's administrator so they can investigate through your agency's identity system. # Usage Source: https://claude.com/docs/government/account/usage Use this page to see how much of your Claude allowance you have used and when it refreshes. > **Who this is for:** Anyone with a Claude for Government account. Use this page to see how much of your Claude allowance you have used and when it refreshes. Check this page if Claude tells you that you have reached a limit, or if you simply want to see how much headroom you have left before you start a large piece of work. Claude Desktop does not show how much of your allowance you have used. To check, sign in to the web portal in your browser and open the **Usage** tab. ## How limits work Your seat tier (the allowance package an administrator has assigned to you) gives you two rolling windows that run at the same time: * The **5-hour window** limits how much you can use in a short burst. * The **7-day window** limits how much you can use across a whole week. Each window shows a progress bar, a percentage from 0% to 100%, and the time it next resets. The bar will never show more than 100% even if your last message pushed you slightly past the line. Both windows refill automatically on their own schedules, so you never need to do anything to get your allowance back. Usage is not counted in messages. Each message to Claude consumes an amount of your allowance proportional to how much work it takes to answer, so a short question uses very little while a long conversation or a request that produces a lot of output uses more. That is why the page shows a percentage rather than a message count. If a request to Claude fails because of a problem on the service side, the allowance it would have used is given back to you automatically. If you cancel or close a response while it is still being written, that message still counts against your allowance. ## When a limit fills up If **either** window reaches 100%, your Claude access pauses until that window resets. While paused you can still sign in, browse the portal, and review past conversations, but you cannot send new messages. When this happens, you will see a banner at the top of this page telling you which limit you have hit and when it will clear, and the **Usage** tab in the navigation is marked with a pulsing indicator so you can spot it from anywhere in the account area. If both windows happen to be full at the same time, the banner names the one that resets later, since that is the one actually holding you. The paused banner and the navigation indicator only appear while a limit is actually at 100%. Once the window resets, both disappear on their own. The page also shows your seat tier name in the top right, so you can tell at a glance which allowance you are on. Below the windows there is a **How do these limits work?** link that expands a short plain-language summary, which can be useful when walking a colleague through the page. This page shows your personal limits only. If you are on a self-managed seat tier, your organization also draws from a shared credit balance. If that balance runs out or your organization reaches a spend cap your tenant administrator set, Claude will tell you that your organization is out of credits rather than that you have reached a limit, and nothing on this page will look full. A spent balance is resolved by Anthropic adding credits to the account. A reached spend cap clears when the rolling window moves forward or when a tenant administrator raises the cap. ## Reading the reset times Each window can be in one of three states, and the text beneath its label tells you which: * **Resets …** means the window is running. You will see a countdown such as "in 2 hr" if the reset is less than a day away, or a date and time if it is further out. Hover over the text to see the other format. Reset times always land on the top of an hour; the clock starts from the hour in which you sent your first message in the window, so your 5-hour window always ends on a round hour rather than at an odd number of minutes. * **Starts when a message is sent** means you have not used anything in this window yet. The window has no timer at all until you send your first message, at which point the countdown starts and the percentage begins to climb. * **Resets on next request** means the window's time has already passed but you have not sent anything since. The display may still show the old percentage, but the very next message you send will clear it to 0% and start a fresh window. You are not actually limited in this state even if the bar looks full. ## Keeping the numbers current The **Last updated** line at the bottom tells you when these figures were fetched. The page does not refresh on its own while you have it open, so if you have been using Claude in another tab or in the desktop application, the numbers here can fall behind. Select the refresh icon next to **Last updated** to pull the latest figures, or simply leave the page and come back. ## If you keep hitting limits Your organization owner can move you to a seat tier with a larger allowance. The tiers that are available, and what each one includes, are defined by your agency, so ask your administrator which options exist. When an administrator changes your seat tier, the usage you have already accumulated in each window carries over; what changes is the size of the allowance it is measured against. This means the percentages on this page will jump the moment the change is made: moving to a larger tier makes the same usage a smaller share of the new allowance, so the bars drop, while moving to a smaller tier makes them rise and can put you straight into a paused state if you had already used more than the new tier allows. The windows still reset at the same times they would have before. Separately from changing your tier, an administrator can also reset your usage windows, which clears both bars to 0% immediately. This is a distinct action that an administrator takes deliberately; it does not happen automatically as part of a tier change. ## If the page says "No seat tier assigned" This message replaces the whole page and only appears when you do not have a seat. If you can see the progress bars, this does not apply to you. You do not have a seat yet, so there is no allowance to show and you cannot send messages to Claude. Ask your organization owner to assign you one. Once they do, this page will show your limits straight away without you needing to sign out and back in. # Claude for Government changelog Source: https://claude.com/docs/government/changelog Release notes for Claude for Government * (breaking) Changed the **Telemetry endpoint** setting on the Config page to check its host name more strictly when you save; an address that is already saved stays until the setting is next changed. * Changed plugin uploads to ask for the Runs code confirmation when a plugin's `settings.json` sets anything other than its default agent or a `$schema` reference, such as a status line. * Added tenant-level Compliance API keys: tenant administrators can create, list, and revoke them on the tenant portal's **Compliance API keys** page under Settings, and a tenant-level key returns the events of every organization in the tenant together with tenant-level activity. * Improved accessibility in the Admin Console for people who use the operating system's reduce motion setting or a screen reader. * Fixed importing Claude for Government Web chats into Claude Desktop failing with "This account doesn't match your organization" for members of tenants that use directory provisioning (SCIM) now but did not on Claude for Government Web. * Added the "Let members add plugin marketplaces" and "Let members add their own plugins" settings under Config > Integrations at the tenant, organization, and group levels, both off by default: members on Claude Desktop 1.37937.0 or later can no longer add plugin marketplaces or their own plugins unless an admin turns these on, while marketplaces and plugins they already added keep working. * Changed the "Claude Code" and "Claude for Microsoft 365" switches under Config > Product availability so that turning a product off takes effect at once for members already signed in to it, instead of waiting for the product to re-read its settings; a member who signs in to Claude for Microsoft 365 while it is off is now told so on the sign-in page. * Added the "IPv6 in the sandbox" setting under Config > Access and models at the tenant, organization, and group levels, off by default: when it is on, Claude Desktop on macOS and Windows lets tools in its sandbox reach IPv6-only hosts during Cowork tasks, which takes effect once a Claude Desktop release that supports the setting is available. * Changed how the "Telemetry headers" setting and your connectors are delivered to Claude Desktop, ahead of Claude Desktop retiring the older formats: nothing changes in your settings or for members, and the notice about deprecated configuration fields that Claude Desktop 1.40609.0 or later can show no longer lists them. * Fixed web fetch failing in Claude Desktop's Code sessions on networks that block `api.anthropic.com`: sessions no longer contact that host before fetching a page, which takes effect on Claude Desktop 1.37937.0 or later after a restart. * Fixed the sign-in page Claude Desktop opens in the browser showing an error instead of a field to enter the code when it is opened without a code or with an expired one. * Changed the limit on a member's active app sign-ins from 3 shared across the Claude apps to 6 in each app: a new sign-in over the limit now signs out the one closest to expiring instead of the oldest. * Fixed Admin Console pages sometimes loading part light and part dark when your computer is set to dark mode, which made some text hard to read. * Improved the Admin Console for tenant admins who manage several organizations: every page shows which organization or tenant your changes apply to. * Fixed the Sessions page under Account showing every app sign-in as "Desktop app": each sign-in now names its app, or reads "Claude app" when the app is not known. * (breaking) Changed the "Telemetry endpoint" setting under Config > Compliance and telemetry to refuse an address products can't use, such as one with a password or a `?` query; an address you already saved is checked only when you next change the setting. * (breaking) Changed the "Telemetry resource attributes" setting under Config > Compliance and telemetry to refuse a value longer than 255 bytes, where a space or an accented letter counts as three or more bytes; values you already saved are checked only when you next change the setting. * (breaking) Changed the "Advanced file analysis in Chat" setting under Config > Product availability to apply only on Claude Desktop 1.14271.0 or later; on 1.13576.0, the only earlier version with this feature, it is off until the app is updated. * Improved screen reader and keyboard support in the Admin Console: actions such as revoking a key or saving seats now announce their result, and keyboard focus returns to the control you used instead of being lost. * Changed the main button on the sign-in pages to a dark button with a white label so it is easier to read; the page an emailed sign-in link opens now announces its result to screen readers. * Added the "Restart deadline for configuration changes" setting under Config > Compliance and telemetry: it sets how long members can keep working after a settings change before Claude Desktop requires the restart that applies it, and takes effect on Claude Desktop 1.40609.0 or later. * Added a search box to the Config page that finds a setting by its name or description and takes you to it. * Fixed members on the default 24-hour "Session idle timeout" being signed out a day after signing in even when they had kept using Claude; the timeout now counts from a member's last activity. * Improved screen reader support in the Admin Console: dialog options, repeated buttons, and usage meters are announced with distinct names, every page has its own browser title, and the setup wizards move keyboard focus to the new step's heading when you change steps. * Changed the "Session idle timeout" setting so a tenant admin can set it as high as 96 hours (5,760 minutes), with larger values refused; a value above 24 hours saved earlier, which was ignored until this release, now applies, and the 24-hour default is unchanged. * Added connector management to the Group configuration pages: tenant admins and organization owners can add, override, or remove connectors for one directory group instead of only for the whole tenant or organization, and these changes appear as new activity types in the Compliance API feed. * Fixed adding a plugin or marketplace under Config > Integrations > Plugins failing with "Something went wrong" for all but the smallest zip files. * Added text alternatives to the charts on the Admin Console's Analytics page: screen readers announce each chart by name and can read its plotted values as a table. * Fixed the "By product" table on the Analytics page counting Claude for Microsoft 365 activity as "Unknown". * Fixed Admin Console pages cutting off setting names, values, and buttons at high browser zoom or in narrow windows; content now wraps instead of scrolling sideways. * Added two settings under Config > Compliance and telemetry: "Application event level (Claude Desktop)" chooses how much of Claude Desktop's application event log goes to your telemetry collector, and "Telemetry resource attributes (Claude Desktop)" adds your own labels to every record. # How Config works Source: https://claude.com/docs/government/config/overview Understand how product settings in Claude for Government are resolved across the tenant, directory groups, and organizations, and how to find, change, compare, and lock them. > **Who this is for:** Tenant administrators and organization owners who set product behavior for the people they manage. The **Config** page in the admin portal is where you set product behavior such as the session timeout, Claude Desktop banner, product availability, and telemetry for the people you manage. The same page appears at both the tenant and the organization level, with the same list of settings, and this page explains how the two levels fit together. For the settings themselves, see [Available settings](/docs/government/config/settings). ## How settings are applied Each setting is resolved through a chain that runs from the Anthropic default, to your tenant, to each organization. Directory groups add two further levels, described under [Group-specific settings](#group-specific-settings) below. A value set at any level becomes the starting point for the levels below it. An organization that doesn't set a value uses the tenant's value, and a tenant that doesn't set a value uses the Anthropic default. When you expand a setting you can see each step of this chain, which value is currently **In effect**, where it came from, and (in the tenant view) which organizations have set their own value. ### Setting kinds Settings combine across the chain in one of three ways, and the kind is fixed per setting (you don't choose it): * A **simple value** is replaced at each level, and the most specific level that set it wins. Most settings work this way. * A **restriction** is a limit where the tightest value across all levels wins. Any level can tighten the limit but none can loosen it. For example, if the tenant sets a session timeout of 30 minutes, an organization can set 15 but cannot set 60. The value that takes effect is always the shortest one in the chain. * A **collection** accumulates entries from each level. A level can add entries to what the level above provided, or replace the list entirely. ### Locks A **lock** prevents levels below from changing a setting. When you lock a setting at your level it shows as **Enforced** to you, and levels below see it as **Managed**, which means it is read-only for them. Any value a lower level had previously set is ignored while your lock is in place, and it comes back into effect if you later remove the lock. How far a lock reaches depends on where you set it: * **On the tenant Config page**, the lock reaches everyone in the tenant. The setting becomes read-only for every organization and at both group levels. * **On a tenant-wide group setting**, the lock reaches the people that group's settings apply to. They get the locked value even if their organization has set a different one, and organizations cannot set their own value for that group while the lock is in place. Other people in those organizations are not affected. A group lock does not keep anyone on that group's settings. If someone in the group also belongs to a higher-priority group that has any configuration, that group's settings apply to them instead and the lock does not, as described under [When someone belongs to more than one group](#when-someone-belongs-to-more-than-one-group). **Locked by Anthropic** is the **Managed** state when the lock was applied by Anthropic at the application level rather than by your own tenant. It appears on features that are not available in Claude for Government, and only Anthropic can change or unlock those settings. Settings that may contain secrets, such as telemetry headers, are never echoed back in the chain view. You see that a value is set, but not what it is. ## When changes take effect Settings that govern the admin portal, such as whether organizations may manage seat tiers, apply immediately. Settings that govern the Claude applications themselves, such as the Claude Desktop banner, product availability, and telemetry endpoint, are delivered to each member's application the next time it refreshes its configuration, which happens when the application is launched or the member signs in. You do not need to push anything, but members who are currently running the application may need to restart it to pick up a change. Lowering the session idle timeout applies to new sign-ins only, and so does raising or removing the maximum session length. Lowering the maximum session length, or setting one for the first time, also reaches members who are already signed in, taking up to one idle timeout period to do so, as described under [Maximum session length](/docs/government/config/settings#maximum-session-length). ## Working with the list Settings are grouped by category in the sidebar on the left. Select a category to see its settings; the number beside each category shows how many settings it contains. Each setting appears as an expandable card showing its name, a one-line description, which products it applies to, its current value, and where that value comes from (for example, **From Anthropic default** or **Set at tenant**). Click a card to expand the full chain and the editor. The scope bar above the list shows which level you are editing and lets you switch between levels when you have access to more than one. Use **Compare config across levels** to see every setting side by side across the full chain. To change a setting, expand it, adjust the value, and save. To remove your value and return to whatever the level above provides, reset it. ## Previewing impact After you change a setting at the tenant level, a **Preview impact** button appears next to **Save changes**. Select it to see a table listing every organization with its current effective value and what it would become after your change. Organizations where nothing would change are marked **unchanged**. This is especially useful when locking a setting, so you can see which organizations currently have a different value that your lock will take priority over. Preview isn't available for settings whose values are hidden for security reasons (for example, settings that can contain authorization tokens). For those settings the preview shows whether a value is set rather than what it is. **Preview impact** is available at the tenant level because it shows the effect of a tenant change across every organization. It does not appear at the organization level. ## Comparing settings across levels Select **Compare config across levels** at the top of the Config page to open a read-only table that lays every setting out side by side across the full chain. This view is for understanding how a value got to be what it is, and for spotting which levels have set their own value for which settings. You can't change anything from here; each row has an **Edit** link that takes you back to that setting on the main Config page. The table has one row per setting and one column per level in the chain: the **Anthropic default**, your **Tenant**, **Groups** (tenant-wide group settings), each **Organization** you can see, **Org groups** (group settings scoped to one organization), and the **Final value** that actually takes effect. A dash means that level has not set a value for that setting. A lock icon next to a value means that level has locked it, and anything below it in the chain is ignored. Use the **All levels** / **Final only** toggle to hide the middle columns and show just the setting, where it was set, and the final value. Before you pick a person, the **Groups** and **Organization** columns list every group and organization that has set its own value for that setting, so you can see at a glance where different values have been set across the levels you can see. ### Looking up one person's settings Type a name into the search box above the table to see exactly what settings apply to that person. The table re-resolves every setting from that person's point of view: the **Groups** column shows the value from the one group that applies to them (with any lower-priority groups they belong to shown faded, since those do not count), the **Organization** column shows their organization's value, and the **Final value** column shows what they actually get. A summary card above the table lists the tenant, group, and organization being used for the lookup. Click any row to expand a plain-English explanation of how the final value was reached, for example "Anthropic's default is On. Your tenant hasn't changed it. The Program-Reviewers group sets this to Off." This is the quickest way to answer a question like "why is this turned off for this person?" or "why can't this person use Code in Claude Desktop?" ## Group-specific settings In addition to setting values for your whole tenant or organization, you can set values for the members of a directory group. A directory group is a group that your identity provider has pushed to Claude for Government over SCIM, as described on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page. There are two kinds of group level: * **Tenant-wide group settings** sit between the tenant and the organization in the chain. A value set here takes priority over the tenant default for the group's members, in every organization. Tenant administrators manage these. * **Organization group settings** are scoped to one organization. A value set here applies only to people who are both a member of the group and a member of that organization, and it is the most specific level in the chain. Organization owners manage these for their own organization and see the same list of groups the tenant does. To edit settings for a group, open the scope bar above the settings list and choose the group's name from the dropdown. The page switches to show the same settings editor, now scoped to that group. Editing, saving, resetting, and locking all work the same way as at the other levels. Anything locked at a higher level still shows as **Managed** here and cannot be changed. You can also add connectors for a group's members from the **Connectors** card while the page is scoped to the group. See [Who receives a connector](/docs/government/connectors/overview#who-receives-a-connector) for which members a group's connectors reach. ### When someone belongs to more than one group Only one group's settings apply to any given person. When someone is a member of more than one group, the settings from their highest-priority group that has any configuration are used, and the other groups are ignored for that person. A group has configuration for a person once any setting is set or locked for it, either as a tenant-wide group setting or as an organization group setting in that person's organization. When a higher-priority group gains configuration for someone, it takes the place of the lower-priority group that applied to them before, and the lower-priority group's settings, including locked ones, stop applying to them. Removing a group's last setting, changing the priority order, or changing someone's group memberships in your identity provider can change which group applies to a person in the same way. The priority order is set by a tenant administrator on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page by dragging the groups into the order they want. The same priority order is used wherever configuration is resolved for a person; seat-tier group mappings on the [Provisioning](/docs/government/org-admin/provisioning) page use a separate fixed order. At the organization level the priority order is shown for reference and cannot be reordered there. If no groups appear in the scope bar dropdown, none have been synced from the identity provider yet. Connect SCIM on the Identity and access page and push groups from your directory, and they will appear automatically. The **Organization instructions** and **Organization Analytics connector** settings can be set at the tenant and organization levels, but not at either group level. The **Plugins** card is read-only when you view a group, and the group's members receive the plugins added for their organization and tenant. ## What differs between the tenant and organization levels The Config page shows the same list of settings at both levels, and almost all of them can be set at either level. The genuine differences are: * **Two settings can be set only by a tenant administrator.** [Let organizations manage their own seat tiers](/docs/government/config/settings#let-organizations-manage-their-own-seat-tiers) and [Compliance API](/docs/government/config/settings#compliance-api) appear on both pages, but are always read-only at the organization level. * **Preview impact appears only at the tenant level.** See [Previewing impact](#previewing-impact) above. * **Group priority is set at the tenant level.** Organization owners see the priority order for reference but cannot change it. * **Tenant administrators can open any organization's Config page** and act on that organization's behalf. Organization owners see only their own organization. * **Inherited connectors and plugins are labeled at the organization level.** Connectors and plugins the tenant has added appear on the organization page with an **Inherited from your tenant** badge; see [The Connectors card](/docs/government/connectors/overview#the-connectors-card) and [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards). For more detail see [Config at the tenant level](/docs/government/tenant-admin/configuration) and [Config at the organization level](/docs/government/org-admin/configuration). ## Things to know * Some settings can only be changed by tenant administrators (and not by organization owners at all), regardless of whether they are locked. These are noted in the [Available settings](/docs/government/config/settings) descriptions. * Resetting a setting removes only that level's value. Values set at other levels are unaffected and remain in effect once yours is gone. # Manage plugins and connectors Source: https://claude.com/docs/government/config/plugins-and-connectors Choose between plugins and connectors in Claude for Government, prepare plugin archives for upload, decide how plugins install for members, update and remove plugins, and understand how connector tool policies apply to members. > **Who this is for:** Tenant administrators and organization owners who deliver plugins and connectors to the members they manage. You add plugins on the **Plugins** card and connectors on the **Connectors** card of the **Config** page in the admin portal. The card controls themselves are described under [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards), and this page covers the tasks around them, from choosing between a plugin and a connector to keeping plugins up to date. To distribute skills to members, bundle them in a plugin, as described under [Skills for administrators](/docs/government/desktop/skills#skills-for-administrators). ## Plugins versus connectors A connector gives Claude access to another service, such as a search tool your agency runs, and the **Connectors** card is the way to deliver a connector to members. A plugin is a package that changes how Claude works. It can add skills, slash commands, and sub-agents, and it can carry hooks, which are scripts a plugin author includes to run automatically at defined points during a session, such as when a session starts. For adding a connector, see [Connectors](/docs/government/connectors/overview). For what a plugin can contain across Claude products, see the [Plugins overview](/docs/plugins/overview); the Claude for Government differences are covered below. A plugin you upload on the **Plugins** card delivers its skills, slash commands, sub-agents, and hooks to members, and its hooks run on the member's machine. A plugin can also declare [MCP servers](/docs/connectors/overview) of its own, and [Plugins that run code](#plugins-that-run-code) describes how they behave. To deliver a connector to members, add it on the **Connectors** card. ## Plugin archive formats The **Plugins** card accepts a single `.zip` file. The file can be one plugin package or a marketplace archive that holds several plugins, such as the downloaded ZIP of a repository that publishes a set of plugins. A single plugin package can be up to 10 MB, and a marketplace archive can be up to 15 MB. When you upload a marketplace archive, the preview lists the plugins it found, and you select which ones to add. Only plugins whose files are packaged inside the archive are added, so an entry in the marketplace listing that points to a plugin hosted elsewhere is skipped. The plugins you add from one archive are grouped under a **Tag**, prefilled from the marketplace's name, which lets you identify the set later. To refresh the set, upload a new version of the same marketplace archive with the same **Tag**. The preview lists any plugin you added from that marketplace before that the new version no longer contains, and you can remove those plugins in the same step. ### What a plugin archive can contain A plugin package is laid out around a manifest at `.claude-plugin/plugin.json`. The [plugins reference](https://code.claude.com/docs/en/plugins-reference) describes the general plugin format. Claude for Government accepts the narrower set described here, so a package that follows only the general reference can be rejected. The manifest is a JSON object, saved as UTF-8 without a byte-order mark, which some Windows editors add unless told otherwise. It has two required keys. `name` becomes the plugin's identity everywhere it appears, in lowercase letters, digits, hyphens, and underscores, up to 64 characters and starting with a letter or digit. `version` is 1 to 64 characters. Add a short `description` for the preview and the plugin's row. Uploading an archive whose name matches a plugin you already added replaces that plugin, whatever the two versions say. Content sits in a fixed set of folders, all lowercase and case-sensitive: `skills/`, `commands/`, `agents/`, `hooks/`, and `monitors/`, plus `.claude-plugin/` for the manifest and an optional `icon.png`. Each folder accepts specific file types. `commands/` and `agents/` take `.md` files, `hooks/` and `monitors/` take `.json` files, and `skills/` takes six text formats (`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.csv`). The root can also hold `README.md`, `LICENSE`, `LICENSE.txt`, `CLAUDE.md`, `CONNECTORS.md`, and `.mcp.json`. Other text files in those six formats, at the root or in folders of your own, are accepted but not used by Claude. Any other file type, anywhere in the archive, is rejected. Apart from the optional icon, everything in an archive must be text in UTF-8. There is no way to ship a script, or any other binary asset such as an image, through the card, which is narrower than what members can add to skills on their own devices. File and folder names must be ASCII. Nothing in the archive may start with a dot apart from `.claude-plugin/` and a root `.mcp.json`: repository files such as `.github/` or `.gitattributes` must be left out, while `.gitignore` and `.DS_Store` are dropped for you. Paths inside the zip must use forward slashes: File Explorer's **Compress to ZIP file**, 7-Zip, `tar.exe`, PowerShell 7, and Python's `zipfile` all write them, while Windows PowerShell 5.1's `Compress-Archive` can write backslash paths, which the upload rejects. A zip that wraps everything in one top folder, which is what zipping the plugin folder or downloading a repository as a ZIP produces, works, as long as the repository holds no other dot-prefixed files. The upload looks inside the wrapper. Apple's `__MACOSX/` folders are dropped quietly too. A plugin package can hold up to 50 MB of uncompressed content, whether you upload it on its own or inside a marketplace archive. Inside `skills/`, each skill is one folder holding a `SKILL.md` whose frontmatter `name` matches the folder name, with any reference files beside it. A bare skill archive, such as a zip of just the skill folder or a `.skill` file from Claude Desktop, is not a plugin: add the manifest and move the folder under `skills/` to convert it. For the path from writing a skill to delivering it, see [Building and deploying your own skills](/docs/government/desktop/skills#building-and-deploying-your-own-skills). In a marketplace archive, each plugin sits in its own subdirectory, and the marketplace listing points at those subdirectories. A listing entry whose source is the archive root itself, `./`, is not supported and adds nothing, so for a repository laid out as a single plugin with its own marketplace file, remove the marketplace file and upload it as one plugin. A package is marked **Runs code** when it declares components that can run code on members' machines. That means any file under `hooks/` or `monitors/`, a `.mcp.json` at the root, or a manifest key that declares them, such as `hooks` or `mcpServers`. Manifest keys that describe the plugin, such as `name`, `version`, `description`, `author`, and `license`, leave the marker off, as do the keys that point to its skills, commands, and agents. A manifest key that the upload does not recognize turns the marker on as a precaution. ## Plugins that run code The upload preview marks any plugin that declares components that can run code on the member's machine, for example hooks or an [MCP server](/docs/connectors/overview), and you confirm that you trust such a package before it is added. For a marketplace archive, one confirmation covers every marked plugin in the batch. After you add it, the plugin's row on the **Plugins** card keeps a **Runs code** marker, so you can see at a glance which of the plugins you have added contain these components. The marker reflects what a plugin declares. In Claude for Government, a marked plugin's hooks run on the member's machine at defined points during a session. Claude Desktop can also run a local MCP server that the plugin declares on the member's machine, or connect to a remote one. Treat the marker as a prompt to review the package yourself. You are responsible for the plugins you distribute to members, so read each plugin's contents before you upload it. ## Install behavior Each plugin on the **Plugins** card has an install behavior that you set when you add it and can change later on its row. **Auto-install** installs the plugin on every member's Claude Desktop without the member doing anything. **Members choose** offers the plugin to members, who install it themselves from their organization's plugins in Claude Desktop, as described in [Plugins in Claude Desktop](/docs/government/desktop/plugins). You do not need to push anything for a plugin to reach members. Claude Desktop syncs your organization's plugin list when it starts and periodically while it runs, so an auto-installed plugin appears on its own, and a member who already has the application open receives it at the next sync. A member can remove a plugin you installed automatically, and it stays removed on the device where they removed it. Two switches, **Let members add plugin marketplaces** and **Let members add their own plugins**, control whether members can also add plugins of their own in Claude Desktop, as described under [Member-added plugins and marketplaces](/docs/government/config/settings#member-added-plugins-and-marketplaces). Both are off by default. Plugins that members add are separate from the ones you add and do not appear on the **Plugins** card. ## Where plugins are added Plugins are added at the tenant or organization level. Plugins the tenant adds flow to every organization and appear on each organization's **Plugins** card under **From levels above**, as described under [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards). A tenant administrator can lock the plugin list, which makes it read-only for organizations, following the lock behavior in [How Config works](/docs/government/config/overview#locks). [Group levels](/docs/government/config/overview#group-specific-settings) inherit the plugins of their tenant or organization, so the **Plugins** card is read-only when you view a group. ## Update or remove a plugin To update a plugin, upload the new version's archive. Because its name matches the plugin you added, the upload updates that plugin, the preview marks the update before you save, and members who have the plugin receive the new version automatically. To remove a plugin, click its remove icon and save the change. Removing a plugin stops delivering it, and there is not currently a way to uninstall a plugin remotely from members' devices, so members who already installed it keep their copy until they remove it themselves, as described under [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards). ## Connector tool policies for members You add and edit connectors on the **Connectors** card, and for each one you choose the products that receive it and set a policy for each of its tools. See [Connectors](/docs/government/connectors/overview) for the three-step wizard. On Claude Desktop, that tool policy shapes what members experience. A tool you switch off is blocked, so Claude cannot use it. A tool you switch on is available and asks the member on every use, and members are not offered a lasting approval for it. A tool you do not list is left to the member to turn on or off, and its approval prompts follow the member's own choices, which can include lasting approval. # Available settings Source: https://claude.com/docs/government/config/settings Reference for the product settings on the Config page in Claude for Government, including session timeout, maximum session length, organization instructions, telemetry, automatic updates, Claude Desktop banner, product availability, member-added plugins, and the tool and connector cards. > **Who this is for:** Tenant administrators and organization owners who set product behavior for the people they manage. This page describes the settings on the **Config** page in the admin portal. Each setting is written once here and can be set at both the tenant and organization level unless noted otherwise. For how the levels combine, what locking does, and how to compare and preview, see [How Config works](/docs/government/config/overview). ## Settings list ### Session idle timeout Controls how long a member can stay inactive before being signed out. The value must be a whole number of minutes from 15 to 5,760 (96 hours), and the default is 1,440 minutes (24 hours) until your tenant sets a value. This is a restriction, so organizations and groups can only set a shorter timeout than the tenant. ### Maximum session length Controls how long a member can stay signed in before they have to sign in again, even if they are active the whole time. The value must be a whole number of minutes from 60 to 525,600 (365 days), and by default there is no maximum. The maximum is an absolute limit on a session's lifetime that is independent of the session idle timeout, and a session ends as soon as it reaches either limit. This is a restriction, so each level can set or shorten the maximum but not lengthen it past what the level above allows, and the value that takes effect is always the shortest one in the chain. A shorter maximum, or a new maximum where there was none before, also applies to members who are already signed in. Open sessions pick up the change while the member is active rather than instantly, so allow up to one session idle timeout period (24 hours by default) for it to reach everyone who is currently signed in. Any session that has not picked it up by then has already expired from inactivity. The maximum always counts from when the member originally signed in, so a session that is already older than the new maximum ends when it picks up the change and the member is prompted to sign in again. A longer maximum, or removing the maximum set at your level by clearing the value or resetting the setting, applies only at each member's next sign-in. Sessions that are already open keep the limit they already have, and raising or removing the maximum does not restore sessions that a shorter value has already shortened or ended. When a session ends because it reached the maximum, the member signs in again, just as they do after the idle timeout. Your identity provider decides whether that sign-in asks the member to authenticate again (for example with a password, a multi-factor prompt, or a PIV card) or passes them straight through, according to its own session and re-authentication policy. Examples of that policy are the sign-in frequency control in Microsoft Entra Conditional Access and authentication policies in Okta. If you want members to authenticate again when they sign back in after reaching the maximum, set your identity provider's re-authentication interval to no longer than the maximum session length. ### Let organizations manage their own seat tiers Controls whether organization owners may create and edit self-managed seat tiers on the [Tiers](/docs/government/org-admin/seat-tiers) page, in addition to the Anthropic-managed ones. Only tenant administrators can change this setting; it is always read-only at the organization level, and organization owners cannot grant themselves the capability. When it is off, the **New seat tier** button and the edit and delete controls on the Tiers page are hidden, and the **Reset usage limits** action on the [Users](/docs/government/org-admin/users) page is also unavailable. **Set at the tenant level only.** This setting is read-only for organization owners. ### Compliance API Controls whether the [Compliance API](/docs/government/org-admin/compliance-api) is available. When it is off, organization owners and tenant administrators cannot create new keys and every request to the API returns an error, including requests made with keys that were valid before. Listing and revoking existing keys remains available even when this is off, so that an exposed key can still be revoked. **Set at the tenant level only.** This setting is read-only for organization owners. ### Organization instructions Instructions that Claude follows for everyone in your organization, in every product: Claude Desktop (Chat, Cowork, and Code), the Claude Code command-line tool, and Claude for Microsoft 365. Use them for rules that should apply to every conversation, such as compliance requirements, data handling, or formatting standards. Enter the instructions as plain text. A change takes effect from each member's next message, including in conversations that are already open, and needs no application update or restart. Members do not see the instructions in their applications. Instructions set at the organization level replace the tenant's instructions for that organization rather than adding to them, so repeat anything from the tenant level that should still apply. A tenant administrator who wants the same instructions in every organization can set them at the tenant level and [lock](/docs/government/config/overview#locks) the setting. Organization instructions guide how Claude responds, and they are not an enforced restriction. To restrict what Claude can do, for example which network hosts it can reach, use **Allowed network hosts** and the other settings on this page. **Set at the tenant and organization levels only.** This setting cannot be set for a group. ### Telemetry endpoint The base address of the collector where Claude Desktop sends usage telemetry using the [OpenTelemetry](https://opentelemetry.io/) protocol (OTLP), for example `https://otel-collector.example.gov:4318`. Claude Desktop appends the OTLP request paths `/v1/logs` and `/v1/metrics` itself, so enter the address without those suffixes. Leaving the value empty disables telemetry. The value must begin with `https://` and may include a port and a path prefix. Its host must be a hostname or a private-network address, and a public IP address is refused. Point this address at a receiver that accepts OTLP over HTTP in both its protobuf and JSON encodings. An [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) does this by default and conventionally listens for OTLP over HTTP on port 4318. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and enter the collector's address here. Claude Desktop on each member's device connects to this address itself rather than through the Claude for Government service. The collector must therefore be reachable from your members' networks and must present a TLS certificate that their operating system trusts. Members pick up a new or changed endpoint the next time they start Claude Desktop. Once a member has signed in and the app has loaded their configuration from Claude for Government, it takes its telemetry settings from that configuration alone and ignores telemetry keys set on the device itself, such as the `otlp*` keys in the Claude Desktop [configuration reference](/docs/third-party/claude-desktop/configuration). From then on your collector receives OpenTelemetry logs and metrics for each member's activity under three `service.name` values: * `cowork` for Chat and Cowork activity * `claude-code-desktop` for Code sessions * `claude-desktop` for events from the application itself, errors only by default Each conversation turn produces events such as `user_prompt`, `api_request`, and `tool_result` that record the model, token counts, durations, and tool names. Every record also carries the member's operating-system login name as the `enduser.id` and `process.owner` resource attributes. Message text, file contents, and tool output are included only for the categories you select in **Telemetry content capture**. See the [event reference in Monitoring](/docs/cowork/monitoring#events) for each event's attributes. Claude Desktop keeps working when the collector refuses requests or cannot be reached, and members see no error. To confirm telemetry is arriving, check your collector's own request logs or metrics for requests to `/v1/logs` after a member has restarted Claude Desktop and sent a message. ### Telemetry headers Headers sent with every telemetry request, typically the credential your collector requires. Leave the setting empty if your collector does not require one. Because the value may contain a secret, it is never displayed after you save it; you see only that it is set. Click **Add header**, then enter the header's name and value, for example `Authorization` and `Bearer `, and add a row for each additional header. A value can contain spaces and `=` characters, but not a comma. Because saved headers are hidden, the headers you enter later replace all of the saved ones when you save, so enter every header again when you add or change one. ### Telemetry content capture The content that Claude Desktop adds to the telemetry it sends to your collector, chosen from **Prompts**, **Claude's responses**, **Tool inputs**, **Tool results**, and **Full requests and responses**. Nothing is selected by default, so the export records activity such as models, token counts, durations, and tool names without any message or tool text. **Tool results** content is delivered only while **Telemetry traces** is on. Captured content goes only to your collector and is never sent to Anthropic. [Content capture](/docs/third-party/claude-desktop/telemetry#content-capture) in the Claude Desktop telemetry reference shows what each category adds. **Telemetry content capture** applies to Claude Desktop 1.15962.0 and later. Earlier versions ignore the setting. ### Application event level (Claude Desktop) How much of Claude Desktop's own event log goes to your collector, in addition to the usage telemetry from Chat, Cowork, and Code. These records arrive under the `claude-desktop` service name. The default, **Errors only**, sends failures such as a crash or a request that could not complete. **Off** sends no application events while usage telemetry is still sent, the two levels between **Errors only** and **Debug** add warnings and then routine events such as sign-in, updates, and settings changes, and **Debug** adds verbose diagnostic events for use while troubleshooting with support. At **Informational** and **Debug**, the application events also include each conversation's title. The title text is sent only when **Prompts** is selected in **Telemetry content capture**. ### Telemetry resource attributes Labels added to every telemetry record sent to your collector, such as your agency or environment name, so the collector can tell where each record comes from. Click **Add attribute**, then enter the attribute's name and value, for example `deployment.environment` and `production`. Attribute names are case-sensitive. A value can be up to 255 characters long when it uses only English letters, digits, and the characters `-`, `.`, `_`, and `~`. Any other character counts as three or more, so a space counts as three and an accented letter such as `é` counts as six. A list set at a more specific level, such as an organization, replaces the whole list inherited from the level above rather than adding to it, so repeat any attributes that should still apply. ### Telemetry traces Sends a trace for each request in Cowork and Code sessions to the `/v1/traces` path of the address in **Telemetry endpoint**, so your monitoring tools can follow the events of one request together. The setting is off by default and is in beta. Traces carry message and tool content only for the categories selected in **Telemetry content capture**. [Traces](/docs/third-party/claude-desktop/telemetry#traces-beta) in the Claude Desktop telemetry reference describes what a trace contains. **Telemetry traces** applies to Claude Desktop 1.22209.0 and later. Earlier versions ignore the setting. ### Block automatic updates Stops Claude Desktop on macOS and Windows from downloading and installing updates automatically. It is off by default, so Claude Desktop keeps itself updated on those systems. Turn it on only if your agency distributes Claude Desktop updates itself, and [lock](/docs/government/config/overview#locks) it if the levels below yours should not be able to turn updates back on. Claude Desktop applies this setting once a member has signed in and the app has loaded their configuration from Claude for Government. With that configuration loaded, the app follows this setting even when it is off, so a `disableAutoUpdates` value in the device's configuration profile does not stop a signed-in member's app from updating. When the app starts without a signed-in member, for example on a newly deployed device or when a member has to sign in again because their session expired, it follows the profile value instead, if one is set. To make sure macOS and Windows devices never update themselves, turn this setting on and also have your IT administrators set `disableAutoUpdates` in the profile, as described under [Automatic updates](/docs/government/deploy-desktop/configure#automatic-updates) on the Connect Claude Desktop to Claude for Government page. On Linux, apt installs Claude Desktop updates, and neither **Block automatic updates** nor `disableAutoUpdates` changes them. To keep Linux devices on the versions your agency distributes, follow the Linux steps under [Automatic updates](/docs/government/deploy-desktop/configure#automatic-updates). ### Restart deadline for updates How long a member can put off restarting Claude Desktop to install an update that the app has downloaded, as a whole number of hours from 1 to 72. When the deadline passes, the app restarts to install the update without waiting for the computer to be idle. Leave the value empty to allow 72 hours, after which the app restarts only once the computer is idle. While **Block automatic updates** is on, this setting has no effect, because the app downloads no updates. Members who are running Claude Desktop when you change **Block automatic updates** or **Restart deadline for updates** may need to restart the app to pick up the change. ### Restart deadline for configuration changes How long a member can put off restarting Claude Desktop after the app detects a configuration change, as a whole number of hours from 0 to 336 (14 days). When the deadline passes, the app shows a restart dialog that the member cannot dismiss, and restarts on its own once the member has been inactive for 2 minutes and Claude has no task in progress. A value of 0 requires the restart as soon as the app detects the change. Leave the value empty to allow 24 hours. ### Claude Desktop banner A persistent banner shown at the top of Claude Desktop. You can set the text, colors, and an optional link, and preview the result as you edit. Banner text may be up to 200 characters, leading and trailing spaces are rejected, colors must be valid hex codes, and the link (if set) must begin with `https://`. An empty banner is valid and simply hides it. The system-use notification shown at sign-in is separate from this banner. It is fixed text and cannot be edited. Use the Claude Desktop banner setting if you need a configurable message inside the application. ### Product availability A group of separate switches that control which Claude products and features are available to members. Each switch appears as its own row: **Claude Desktop**, **Chat in Claude Desktop**, **Advanced file analysis in Chat**, **Cowork in Claude Desktop**, **Code in Claude Desktop**, **Claude Code**, and **Claude for Microsoft 365**. All are on by default. Turning off one of the three product switches (**Claude Desktop**, **Claude Code**, or **Claude for Microsoft 365**) makes Claude for Government stop serving that application your organization's configuration. From then on, Claude Desktop and the Claude for Microsoft 365 add-in are refused the organization's configuration when they request it, and Claude Code that is signed in to Claude for Government exits when it next starts (or right after sign-in) with a message that it couldn't load settings from the cloud gateway. Claude Code that is already running is not cut off and keeps working until it is next started. The product switches are not an access control on the Claude for Government service itself. What a member can reach is governed by their account, their [seat tier](/docs/government/org-admin/seat-tiers), and your agency's device and network management. To cut a member off at once, deactivate their account, after which they cannot sign in and requests from their existing sign-ins are refused (see [Deactivated users](/docs/government/org-admin/users#deactivated-users)). Turning off one of the other four switches removes that feature from Claude Desktop, as described below. The **Chat in Claude Desktop**, **Cowork in Claude Desktop**, and **Code in Claude Desktop** switches each make one part of the app available to members. Chat is for simple conversations, Cowork is for longer tasks that Claude works through on its own in a local workspace folder, and Code is for software development. The **Claude Code** switch is separate and applies to the standalone Claude Code command-line tool. When Chat and Cowork are both available, Claude Desktop presents them together as **Home** in its sidebar, next to **Code**. From Home, a member chooses **Chat** or **Cowork** in the message box, and the sidebar lists their chats and tasks together. Turning a switch off also changes this layout. For example, with **Chat in Claude Desktop** off, the sidebar shows **Cowork** in place of Home and the message box offers no choice, and with **Cowork in Claude Desktop** off, the message box offers Chat only. If Chat, Cowork, and Code are all turned off, Claude Desktop keeps Cowork on. There is no setting that chooses what Claude Desktop opens to, or whether the message box starts on Chat or Cowork. This layout applies to Claude Desktop 1.26832.0 and later. Earlier versions show **Chat**, **Cowork**, and **Code** as three separate tabs, controlled by the same switches. ### Member-added plugins and marketplaces Two switches that control whether members can add plugins of their own in Claude Desktop. **Let members add plugin marketplaces** lets members add plugin marketplaces and install plugins from them. **Let members add their own plugins** lets members upload plugin files or have Claude create a plugin for them. Both switches are off by default. While a switch is off, Claude Desktop hides the corresponding controls from members. Marketplaces and plugins that members added earlier keep working, and members can still install plugins from those marketplaces. ### Allowed network hosts A list of hostnames that tools in Claude Desktop may reach, for example to install packages or fetch web pages. This covers the tools Claude uses during Cowork tasks, web fetch in Chat, and the sandboxed shell commands of Code sessions on macOS and Linux. For how the list applies to Code sessions on each operating system, see [Code in Claude Desktop](/docs/government/security/security-and-data-handling#code-in-claude-desktop). The connection to Claude is always allowed and does not need to be listed. An empty list shows as **Claude connection only**. Use **Add package registries** to add npm, PyPI, GitHub, crates.io, and other common registries so that Claude can install libraries; hosts added this way appear together as a single **Package registries** pill with a count. Entries are hostnames or wildcard patterns such as `*.example.com`, which matches subdomains at any depth but not `example.com` itself, so list both if you need both. The list does not accept IP addresses or ports, and unless you allow all traffic with a `*` entry, the tools this list covers cannot reach a destination by its IP address. Web search, connectors, and the app's own connections, such as sign-in, updates, and telemetry export, do not use this list. Web fetch refuses localhost and private-network addresses regardless of what the list contains. Because entries match by name, a hostname you list is reachable even when it resolves inside your network, so treat the list as one layer alongside your own network controls. ### Allowed workspace folders Controls which folders members can pick as a project folder in Claude Desktop, and where Claude can read and write files. Leave it unset to allow any folder. Add folder paths to limit members to those locations, or check **Block all workspace folders** to allow none, in which case Claude can still work in Chat and Cowork in folders it creates inside its own sandbox. A Code session starts only in a folder this setting permits and Claude's file tools stay inside the permitted folders, but the setting does not stop the shell commands Claude runs in a Code session from reading files elsewhere on the device, and [Code in Claude Desktop](/docs/government/security/security-and-data-handling#code-in-claude-desktop) describes what confines those commands on each operating system. You can list Windows and Mac paths together, and each device uses only the paths for its platform. An unset value shows as **Any folder** and an empty list shows as **No folders**. Write each entry as an absolute path. A path can start with `~`, which stands for each member's home folder on both Windows and Mac; write these with forward slashes, for example `~/ClaudeWork`, and they resolve on both platforms. A path can also use one of the per-user variables `%OneDrive%`, `%OneDriveCommercial%`, `%OneDriveConsumer%`, `%APPDATA%`, `%LOCALAPPDATA%`, and `%USERNAME%`. A device ignores an entry whose variable it does not define, so a list with only Windows entries leaves Mac users with no allowed folder. Include a `~` path or a Mac path as well. Subfolders of a listed folder are included, Claude Desktop creates a listed folder that does not exist yet when a member opens the folder picker, and the picker opens in one of the listed folders. If your agency redirects Desktop and Documents to OneDrive or another sync client, consider listing a local folder that is not synced, such as `~/ClaudeWork`, for Code sessions and other work that creates many files or scripts. Keep synced folders for documents and finished work. A member can start a Code session in any folder the list permits, synced or not. One list applies to Cowork and Code sessions alike, so ask members to choose the local folder when they start a Code session. To point at the synced Documents folder on Windows, use `%OneDriveCommercial%` or `%OneDrive%`, for example `%OneDriveCommercial%\Documents\ClaudeOutput`, because `~/Documents` refers to the local Documents folder in the user profile, not the redirected one. What the sync client uploads, including whether it skips particular file types, is controlled by your sync client's policies rather than by Claude for Government. ## Tool and connector cards Alongside the settings list, the Config page shows cards for the built-in tools (Web search, Web fetch, and Shell commands), the built-in connector (Microsoft 365), a **Connectors** card for the ones you add yourself, and a **Plugins** card for plugin packages you upload. A connector is an integration that lets Claude reach an external service on a user's behalf. The **Web search** card controls whether Claude can search the web in Claude Desktop. It is off by default. When you turn it on you are shown a short description of how search works and asked to acknowledge it before the setting is saved. A **Require approval for each search** sub-setting sits below the toggle and becomes available once web search is on; it is on by default, and turning it off lets each member choose whether to approve every search or allow searches to run automatically. Once you turn web search on, each member's Claude Desktop picks it up the next time the app starts and shows it in the message box's **+** menu, under **Connectors**, as a **Web Search** switch that the member can turn off for themselves. If one member has no **Web Search** switch after restarting Claude Desktop while others do, select [**Compare config across levels**](/docs/government/config/overview#comparing-settings-across-levels) at the top of the Config page and type the member's name into the search box to check whether another level, such as a [directory group](/docs/government/config/overview#group-specific-settings), turns web search off for them. If every level shows web search on, check whether that member's network is blocking it, as described in the troubleshooting table in [Connect Claude Desktop to Claude for Government](/docs/government/deploy-desktop/configure#troubleshooting). The **Web fetch** card controls whether Claude can fetch web pages in Claude Desktop. It is on by default, and fetches are subject to the Allowed network hosts list above. A **Require approval for each fetch** sub-setting sits below the toggle. Turning it on asks the member to approve every page fetch before it runs; when it is off (the default), each member chooses whether to approve fetches or allow them automatically. The **Shell commands** card controls whether Claude can run shell commands during tasks in Claude Desktop. It is on by default, and turning it off also turns off Advanced file analysis in Chat. A **Require approval for each command** sub-setting sits below the toggle. Turning it on asks the member to approve every shell command before it runs; when it is off (the default), each member chooses whether to approve commands or allow them automatically. On Claude Desktop versions earlier than 2.110.0, Chat asks before each command regardless of this setting. The **Microsoft 365** card lets members reach your agency's Microsoft 365 content, including SharePoint, OneDrive, Outlook, and Teams, from Claude Desktop. Each member signs in with their own Microsoft account. Enter the **Tenant ID** and **Client ID** from an application you register in Microsoft Entra, choose the **Azure cloud** your Microsoft tenant is in, and select which Microsoft Graph permissions to allow under **Access**. The connector is off while Tenant ID and Client ID are both blank. See [Set up the Microsoft 365 connector](/docs/government/connectors/microsoft-365) for the full walkthrough. The **Connectors** card lists the Model Context Protocol servers you have added for your own systems. Each connector is defined once and applied to the products you choose. See the [Connectors](/docs/government/connectors/overview) page for how to add and manage them. The **Plugins** card lets you upload plugin packages and deliver them to members in Claude Desktop. A plugin bundles skills, slash commands, and sub-agents for Claude Desktop, and can also carry hooks and declare connectors; see [Manage plugins and connectors](/docs/government/config/plugins-and-connectors) for how each component behaves in Claude for Government and the [Plugins overview](/docs/plugins/overview) for what a plugin can contain. Plugins are delivered only to Claude Desktop. Click **Add plugins** and drop a `.zip` file. The file can be a single plugin package or a whole marketplace archive, for example the **Download ZIP** of a GitHub repository that holds several plugins. A preview shows each plugin's name, version, and description, and marks any plugin that declares components that can run code on the member's machine, for example hooks or an MCP server. In Claude for Government, a plugin's hooks run on the member's machine at defined points during a session, and Claude Desktop can start or connect to an MCP server the plugin declares. For those plugins, you confirm that you trust the package before it is added. See [Plugins that run code](/docs/government/config/plugins-and-connectors#plugins-that-run-code) for what the marker means and how these components behave in Claude for Government. Each plugin you add appears as a row with an **Auto-install** or **Members choose** control. **Auto-install** installs the plugin for every member automatically, and **Members choose** makes it available for members to install themselves. Click the remove icon to queue a plugin for removal. Changes you make in these rows are staged: nothing is applied until you click **Save changes**, and **Discard** clears the pending changes. Plugins you add through the **Add plugins** dialog take effect as soon as you confirm them in that dialog. Removing a plugin stops delivering it, and members who already installed it keep their copy until they remove it themselves. At the organization level, plugins the tenant has added appear under a **From levels above** heading with an **Inherited from your tenant** badge. You can see them there but cannot change or remove them. Upload a plugin with the same name at your organization level to take priority over one. The Claude for Government deployment may include additional settings that are not listed above. Any extra setting follows the same chain, status badges, and edit and reset behavior. # Set up the Microsoft 365 connector Source: https://claude.com/docs/government/connectors/microsoft-365 Register an application in your Microsoft Entra tenant so that Claude Desktop can read your agency's Outlook, OneDrive, SharePoint, and Teams content on each member's behalf. > **Who this is for:** Organization owners and tenant administrators who want Claude to reach their agency's Microsoft 365 content, and who can register an application in Microsoft Entra ID (or can work with someone who can). The Microsoft 365 connector lets Claude read and search your agency's Outlook mail and calendar, OneDrive and SharePoint files, and Teams chat from Claude Desktop. The connector runs locally on each member's machine: when a member signs in with their own Microsoft account, Claude Desktop calls Microsoft Graph directly from their device, so those calls and the member's sign-in tokens stay between their device and Microsoft and never pass through any Anthropic service. What Claude reads into a conversation is then handled like anything else the member sends to Claude. Because each member signs in individually, Claude can only reach content that the signed-in member can already open in Microsoft 365. Your existing Microsoft 365 permissions, sharing rules, and Conditional Access policies apply unchanged. Setup has two parts. First, someone with administrator access in Microsoft Entra ID registers an application in your Microsoft tenant. Then you enter that application's details on the **Microsoft 365** card on the [Config](/docs/government/org-admin/configuration) page. ## Before you start You need someone with the **Cloud Application Administrator**, **Application Administrator**, or **Global Administrator** role in your Microsoft Entra tenant. That person registers the application and approves the Microsoft Graph permissions for your whole tenant. If that isn't you, send them the [Register an application in Microsoft Entra](#register-an-application-in-microsoft-entra) section below; you can fill in the Config page form once they send you the two IDs. Open the [Config](/docs/government/org-admin/configuration) page in another tab and find the **Microsoft 365** card. You'll paste two values from Entra into it at the end. ## Register an application in Microsoft Entra 1. In the [Microsoft Entra admin center](https://entra.microsoft.com), open **App registrations** from the left navigation and select **+ New registration**. 2. Enter a display name, for example "Claude for Government Microsoft 365". 3. Under **Supported account types**, choose **Single tenant only - \{your organization}**. Older versions of the portal label this option **Accounts in this organizational directory only (Single tenant)**. 4. Leave **Redirect URI** blank for now, and select **Register**. On the new application's left navigation, go to **Manage** > **Authentication** and open the **Redirect URI configuration** tab (on older versions of the portal, select **+ Add a platform** instead). 1. Select **Add redirect URI**. In the sidebar, choose the **Mobile and desktop applications** card (the Windows, UWP, and Console card, not the iOS/macOS card). 2. Leave the suggested redirect URIs unchecked. In the **Custom redirect URIs** box, enter `http://localhost` and select **Configure**. 3. Close the sidebar. A **Mobile and desktop applications** section now appears on the Authentication page. Select **Edit** on that section, and in the empty box that appears under `http://localhost`, enter each of the two broker redirect URIs below (a new empty box appears after you enter each one). Replace `APPLICATION_CLIENT_ID` with the **Application (client) ID** shown on the application's Overview page, and select **Save** at the top when done. ```text theme={null} ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID msauth.com.anthropic.claudefordesktop://auth ``` The `http://localhost` URI is the standard loopback redirect for browser sign-in. When a member signs in through their browser, Microsoft Entra sends the response to a temporary listener on the member's own machine, so it never leaves the device. The other two URIs let Claude Desktop sign in through the operating system's account broker on Windows and macOS devices that meet the [brokered sign-in requirements](#brokered-sign-in-requirements). Brokered sign-in carries the device-identity claim that Conditional Access policies such as **Require compliant device** evaluate, so register all three now even if you are not sure you need them. All three URIs must be under **Mobile and desktop applications**, not **Web**. Registering them as **Web** causes Entra error `AADSTS50011` at sign-in. After you save, Entra may display the `msauth.com.anthropic.claudefordesktop://auth` URI under a separate **iOS/macOS** section. That's expected, since both sections are public-client platforms. To double-check, open **Manage** > **Manifest** and confirm the three URIs appear under `publicClient.redirectUris` rather than `web.redirectUris`. If the list also contains `msauth.com.anthropic.claudefordesktop.helper://auth`, remove that entry. Claude Desktop does not use it. Still under **Authentication**, find **Allow public client flows** (on the **Settings** tab under **Web and SPA settings**, or under **Advanced settings** on older versions of the portal), set it to **Yes**, and select **Save**. This tells Microsoft Entra that the application runs on end-user devices and does not hold a secret. Claude Desktop signs in as a public client with no client secret, and with this setting off, brokered sign-in on managed devices fails with Entra error `AADSTS7000218`. Setting **Allow public client flows** to **Yes** also permits the device-code sign-in flow, which attackers can abuse for phishing. To close that path, apply a tenant Conditional Access policy that blocks the device-code authentication flow. Scope the policy to **All resources**, not to this app registration, because Conditional Access evaluates the resource a token is requested for rather than the requesting client. On the application's left navigation, go to **Manage** > **API permissions**. 1. Select **+ Add a permission** > **Microsoft Graph** > **Delegated permissions**. 2. Add `User.Read` (under **User**) and `offline_access` (under **OpenId permissions**). `User.Read` is usually already listed on a new application, so leave it in place. The connector always requests these two at sign-in, so they must be approved regardless of what you select under **Access** later. 3. Add every permission you plan to select under **Access** on the Config page. At minimum, add the eight Default permissions (`Mail.Read`, `Mail.Read.Shared`, `Calendars.Read`, `Calendars.Read.Shared`, `Files.Read.All`, `Sites.Read.All`, `Chat.Read`, `OnlineMeetings.Read`), since those are pre-selected on the Config page. See [Choose which Microsoft 365 permissions to allow](#choose-which-microsoft-365-permissions-to-allow) for what each one does and for the optional write permissions. 4. Select **Add permissions**. 5. Select **Grant admin consent for \{your tenant name}** and confirm. The **Grant admin consent** step approves these permissions once for every member of your Microsoft tenant, so individual members are not asked to approve them again when they sign in. Until you complete this step, members see Entra error `AADSTS65001` at sign-in (or, on tenants that allow members to approve permissions themselves, a per-member consent prompt). A delegated permission lets the application act on a member's behalf, limited to whatever that member can already do. It does not let Claude see content the member cannot see. For example, granting `Files.Read.All` lets Claude read files the signed-in member can open, not every file in your tenant. On the application's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You'll paste both into the Config page when you [configure the connector](#configure-the-connector-on-the-config-page). ### If your Microsoft tenant is in a US Government cloud Microsoft 365 GCC (the standard Government Community Cloud) uses the commercial Microsoft Entra service, so follow the steps above unchanged and leave **Azure cloud** set to **Commercial** when you [configure the connector on the Config page](#configure-the-connector-on-the-config-page). GCC High and DoD tenants use the Azure Government cloud instead. Register the application at `https://entra.microsoft.us` (or `https://portal.azure.us`) rather than `entra.microsoft.com`, and select the matching **Azure cloud** value when you [configure the connector on the Config page](#configure-the-connector-on-the-config-page). Claude Desktop then signs in at `login.microsoftonline.us` and calls `graph.microsoft.us` (or `dod-graph.microsoft.us` for DoD) instead of the commercial hosts. ### Allow outbound network access The connector calls Microsoft directly from each member's device, so devices need outbound HTTPS access to the Microsoft Entra and Microsoft Graph hosts for your cloud. | Azure cloud | Sign-in host | Microsoft Graph host | | ---------------------- | --------------------------- | ------------------------ | | Commercial | `login.microsoftonline.com` | `graph.microsoft.com` | | US Government GCC-High | `login.microsoftonline.us` | `graph.microsoft.us` | | US Government DoD | `login.microsoftonline.us` | `dod-graph.microsoft.us` | No outbound access to any Anthropic host is needed for the connector's Microsoft 365 calls. ## Configure the connector on the Config page On the [Config](/docs/government/org-admin/configuration) page, expand the **Microsoft 365** card and fill in the form. | Field | What to enter | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tenant ID** | The **Directory (tenant) ID** from the application's Overview page. | | **Client ID** | The **Application (client) ID** from the application's Overview page. | | **Azure cloud** | **Commercial** for most tenants, including Microsoft 365 GCC. Choose **US Government GCC-High** or **US Government DoD** only if your Microsoft tenant is in one of those clouds. | | **Access** | The Microsoft Graph permissions the connector requests when a member signs in. The standard read-only permissions are already selected; add or remove permissions as needed. See [Choose which Microsoft 365 permissions to allow](#choose-which-microsoft-365-permissions-to-allow). | Save the card. The connector reaches each member's Claude Desktop the next time it starts or the member signs in to Claude for Government. Members who already have Claude Desktop open are prompted to relaunch the next time the app checks for changes, which it does about every 30 minutes, and the connector appears after the relaunch. ## Choose which Microsoft 365 permissions to allow The **Access** picker controls which Microsoft Graph delegated permissions Claude Desktop requests when a member signs in. The permissions marked **Default** below are already selected when you first open the card and give read-only access to the member's mail, calendar, files, sites, Teams chat, and online meetings. Add write or administrator-approval permissions if you need them, or clear read permissions you do not want. At least one permission must be selected. Whatever you select here must also be added and approved on the Entra app registration (step 4 above). Keep the two lists in sync. Claude Desktop also always requests `User.Read` and `offline_access`. These two do not appear in the picker, but they must still be approved on the Entra app registration. ### Read access | Permission | What it lets Claude do | | --------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `Mail.Read` (Default) | Read the member's mail | | `Mail.Read.Shared` (Default) | Read mail in mailboxes shared with the member | | `Calendars.Read` (Default) | Read the member's calendar events | | `Calendars.Read.Shared` (Default) | Read events on calendars shared with the member and find free meeting times | | `Files.Read.All` (Default) | Read files the member can open in OneDrive and SharePoint | | `Sites.Read.All` (Default) | Read SharePoint site content the member can open | | `Chat.Read` (Default) | Read the member's Teams chats | | `OnlineMeetings.Read` (Default) | Read the member's online meetings | | `MailboxSettings.Read` | Read the member's mailbox time zone so that dates in requests follow the member's local time rather than UTC | ### Read access requiring administrator approval These two permissions always require the **Grant admin consent** step in Entra, regardless of your tenant's user-consent policy. Until that step is done, sign-in fails for every member when either permission is requested. | Permission | What it lets Claude do | | ---------------------------------- | ----------------------------------------------------- | | `ChannelMessage.Read.All` | Include Teams channel messages in chat search results | | `OnlineMeetingTranscript.Read.All` | Read meeting transcripts | ### Write access Write permissions let Claude take actions in Microsoft 365 on the member's behalf, such as sending mail, creating calendar events, and editing files. Members approve each write action in Claude Desktop before it runs. The connector is read-only unless you select at least one of these. | Permission | What it lets Claude do | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Mail.Send` | Send mail, send drafts, and forward mail on the member's behalf. Forwarding and sending drafts also use a mail read permission (any of `Mail.Read`, `Mail.Read.Shared`, or `Mail.ReadWrite`) for pre-send checks. | | `Mail.ReadWrite` | Create, edit, and delete drafts; trash, restore, and delete messages; apply and remove labels on messages | | `Calendars.ReadWrite` | Create, update, delete, and respond to calendar events | | `Files.ReadWrite.All` | Create, edit, rename, move, copy, and delete files and folders the member can edit in OneDrive and SharePoint | | `Sites.ReadWrite.All` | Additional SharePoint write access beyond files. No Claude action requires this permission; `Files.ReadWrite.All` covers file actions in both OneDrive and SharePoint. | | `ChatMessage.Send` | Send messages in the member's existing Teams chats | | `ChannelMessage.Send` | Post messages to Teams channels | | `Chat.Create` | Start new Teams chats | | `MailboxSettings.ReadWrite` | Create and delete the member's mail rules, manage labels, and configure automatic replies | Removing a permission from the **Access** picker changes what Claude Desktop requests the next time a member signs in, but it does not revoke permissions that Microsoft Entra has already approved for the application. To revoke a permission entirely, remove it in the Entra admin center under **Enterprise applications** > your application > **Permissions**. ## What members see After you save the card, **Microsoft 365** appears under **Settings** > **Connectors** in each member's Claude Desktop. The member selects **Connect** and signs in with their Microsoft work account. On devices that meet the brokered sign-in requirements below, this opens the operating system's account picker; otherwise, it opens the default browser. Once connected, Claude can search and read the member's Microsoft 365 content in conversations. Sign-in tokens are stored encrypted on the member's device and persist across restarts, so members are not asked to sign in again each session. Selecting **Disconnect** deletes the connector's stored tokens from the device. On the brokered sign-in path, the device's work or school account is managed by the operating system and remains after Disconnect, so selecting **Connect** again can re-acquire tokens without a fresh prompt. To end a member's access entirely, revoke the member's sessions in the Entra admin center (revocation takes effect once the member's current access token expires), or remove the account from the device in Windows Settings (**Accounts** > **Access work or school**) or macOS Company Portal. ### Brokered sign-in requirements If your Conditional Access policies require a compliant or managed device, sign-in must carry a device-identity claim. Brokered sign-in provides that claim directly; browser sign-in provides it only when the browser itself is integrated with device identity (for example, Microsoft Edge signed in with the work account on an Entra-joined Windows device, or a macOS browser with the Enterprise SSO integration deployed). Without the claim, members see Entra error `AADSTS53000` or `AADSTS53003` when Claude calls Microsoft 365. Brokered sign-in requires the broker redirect URIs from step 2, **Allow public client flows** set to **Yes** (step 3), and the following on each device: | Platform | Broker availability requirements | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Windows | Windows 10 or Windows Server 2019 or later. The device is joined or registered to Entra ID (Entra joined, Entra hybrid joined, or Entra registered). | | macOS | macOS 10.15 or later. The Mac is enrolled in device management and registered in Entra ID. **Intune Company Portal** is installed, and an **Extensible SSO** configuration profile of type **Redirect** pointed at the Microsoft Enterprise SSO plug-in is deployed through device management. The broker is unavailable without Company Portal and the SSO profile. | When the broker is unavailable, Claude Desktop falls back to browser sign-in automatically and stays on browser sign-in until Claude Desktop restarts. When the broker is available, it carries the device claim, and Conditional Access then evaluates that claim against your policy, so the device must also satisfy whichever grant control your policy applies: marked compliant in Intune (or by a partner compliance integration that reports to Intune) for a **Require compliant device** policy, or hybrid joined for a **Require Entra hybrid joined device** policy. A device with a working broker that does not satisfy the policy still fails with `AADSTS53000` or `AADSTS53003`. ## Common problems | What the member sees | What it means | How to fix it | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Entra error `AADSTS50011` at sign-in | One of the redirect URIs from step 2 is missing from the app registration, was entered with a different value, or was added under the **Web** platform instead of **Mobile and desktop applications**. The error message names the URI that Claude Desktop sent. | Compare it with step 2 and add or correct that URI under **Mobile and desktop applications**. | | Entra error `AADSTS900971` at sign-in on macOS | No redirect URI is registered for macOS brokered sign-in. | Add `msauth.com.anthropic.claudefordesktop://auth` under **Mobile and desktop applications** (step 2). | | Entra error `AADSTS65001` at sign-in | The Microsoft Graph permissions have not been approved for the tenant, or a permission the connector requests is not listed under the app registration's **API permissions** (so **Grant admin consent** never covered it). | Confirm that every permission selected under **Access** on the Config page, plus `User.Read` and `offline_access`, is listed under the app registration's **API permissions**. Add any that are missing, then select **Grant admin consent** (step 4). | | A Microsoft consent prompt appears at sign-in even though you selected **Grant admin consent** | Same cause as `AADSTS65001` above, on a tenant that allows members to approve permissions themselves. | See the `AADSTS65001` row above. | | Entra error `AADSTS7000218` at sign-in | **Allow public client flows** is set to **No** on the app registration. | Set it to **Yes** (step 3). | | Entra error `AADSTS53000` or `AADSTS53003` when Claude calls Microsoft 365 | A Conditional Access policy requires a compliant or managed device, and either sign-in fell back to the browser because brokered sign-in is not available, or the device does not satisfy the policy's grant control. | Meet the [brokered sign-in requirements](#brokered-sign-in-requirements) for the member's platform, confirm the device satisfies whichever grant control your policy applies (marked compliant, or hybrid joined), and restart Claude Desktop. On macOS, the most common broker cause is a missing Company Portal install or Extensible SSO profile. | | Entra error `AADSTS700016` at sign-in | The **Client ID** or **Tenant ID** on the Config page does not match an application in the selected **Azure cloud**. | Re-check the Client ID and Tenant ID against the application's Overview page, and confirm that **Azure cloud** matches the cloud where you registered the application. | | Sign-in or Claude's Microsoft 365 calls fail with a network error and no `AADSTS` code | The member's device cannot reach the Microsoft Entra or Microsoft Graph host for your Azure cloud. | Allow outbound HTTPS to the hosts listed under [Allow outbound network access](#allow-outbound-network-access). | | A tool returns a permission error | The Microsoft Graph permission that tool needs is not approved on the app registration, or is not selected under **Access**. | Add the permission in both places and select **Grant admin consent** again. | ## Things to know * Read and write permissions are separate per Microsoft 365 service. You can approve read broadly while limiting write to specific services or none at all by selecting only the permissions you want under [Choose which Microsoft 365 permissions to allow](#choose-which-microsoft-365-permissions-to-allow). * The **Access** selection applies to everyone who receives this connector card. There is no separate per-group write toggle inside the card. To give different groups different permissions, set the card at the group scope on the Config page; see [Group-specific settings](/docs/government/config/overview#group-specific-settings). # Connectors Source: https://claude.com/docs/government/connectors/overview Add Model Context Protocol servers for your own systems, choose which Claude products receive each one, and set which of their tools are available to members. > **Who this is for:** Tenant administrators and organization owners who want Claude to reach their agency's own systems (for example, an internal search service or a ticketing tool) from Claude Desktop and other Claude products. Use this page to add Model Context Protocol servers for your own systems, choose which Claude products receive each one, and set which of their tools are available to members. A **connector** is a link between Claude and an external service. The service runs a Model Context Protocol (MCP) server, which is a standard way for a service to publish a set of tools that Claude can call. You add the server once here, and Claude for Government delivers it to the products you select. ## The Connectors card The **Connectors** card appears on your [tenant](/docs/government/tenant-admin/configuration) or [organization](/docs/government/org-admin/configuration) Config page alongside the built-in connector cards, and on the Config page for each [directory group](/docs/government/config/overview#group-specific-settings). It lists the connectors added at the level you are viewing and the connectors that level inherits, with each one's name, address, the products it applies to, and a summary of how many of its tools are allowed. Click **Add connector** to open the wizard, or click the edit icon next to a connector added at this level to change it. An inherited connector has a badge that says where it comes from, such as **Inherited from your tenant** or **Inherited from your organization**, in place of the edit and remove controls. To change an inherited connector for the members at your level, click **Add connector** and create one with the same name. The inherited connector's details and stored secret are not copied, so you enter the server address and authentication again. Your entry then replaces the inherited one in the list and takes priority over it, as described under [Who receives a connector](#who-receives-a-connector). ## Who receives a connector Who receives a connector depends on where you add it: * On the tenant Config page, it reaches the members of every organization in the tenant. * On an organization's Config page, it reaches every member of that organization. * On the Config page for a [directory group](/docs/government/config/overview#group-specific-settings), it reaches that group's members: in every organization when you open the group from the tenant Config page (a tenant-wide group setting), or only in one organization when you open the group from that organization's Config page (an organization group setting). In every case it is delivered only to the products you select, with the tool policy you set. When the same connector name is added at more than one level, each member receives only the entry from the most specific level that applies to them: the organization's group settings first, then the organization, then the tenant-wide group settings, then the tenant. That entry replaces the others as a whole, including its address, authentication, products, and tool policy. You cannot remove a connector inherited from a level above, but you can stop it from reaching the members at your level by adding one with the same name and selecting no products under **Apply to**. A connector added for a group does not always reach every member of the group. Someone who belongs to more than one directory group receives group settings, connectors included, from only one of them: their [highest-priority group](/docs/government/config/overview#when-someone-belongs-to-more-than-one-group) that has any configuration. Adding a group's first connector or deleting its last one can therefore change which group, and so which group settings, apply to some members. The group's Config page shows a note when this could happen. To check which group applies to a particular member, use the person lookup described under [Comparing settings across levels](/docs/government/config/overview#comparing-settings-across-levels). ## Adding a connector The **Add connector** button opens a three-step wizard. ### Step 1: Server Enter the details of the MCP server. * **Name** is a short identifier for the connector. It must be lowercase letters, digits, hyphens, or underscores. * **Server URL** is the address of the server's MCP endpoint. It must begin with `https://`. * **Transport** selects how Claude talks to the server. Choose HTTP or SSE to match what your server supports. * **Authentication** selects how Claude proves who it is to the server. **None** sends no credentials. **Header (shared secret)** sends a fixed header (for example, an authorization token) with every request; the value is stored securely and shown as `••••` after you save. **OAuth (members sign in)** has each member sign in on first use, and their tokens stay on their own machine. **OAuth (pre-registered app)** also has each member sign in, through an app you register with the server's sign-in provider ahead of time. For **OAuth (pre-registered app)**, enter the **Client ID** your provider issued when you registered the app. A single-tenant Microsoft Entra app also needs its **Tenant ID** and the **Scope** the app requests. Enter the scope that your server's own API expects (for example, an `api://` scope for an app registered in your tenant), because Microsoft Graph scopes such as `Mail.Read` would give the connector's server access to members' Microsoft 365 data. Neither OAuth option stores a secret. When you choose either OAuth option, a confirmation checkbox appears on the final step asking you to confirm that the server address is exactly the one you intend, because members are sent to a sign-in page that the server chooses. When sign-in happens somewhere other than the server itself, for example when you set a tenant ID for a Microsoft Entra app, the checkbox names both that sign-in address and the server address. ### Step 2: Discover tools This step tries to list the tools the server offers so that you can set policy on the next step. Discovery runs from your own browser and is best-effort; many servers cannot be reached this way (for example, because they require authentication or are on a private network), and you can always add tools by name on the next step instead. Click **Discover tools** to run the probe. If the server answers, the tools it advertises are listed. If the server asks for sign-in, a **Sign in to discover** option appears: confirm the sign-in host, sign in through the popup, and the probe runs again with that one-time credential. The credential is used once in your browser for this probe and is never stored; it is separate from the **Authentication** choice on the Server step, which controls how members authenticate later. The **Sign in to discover** option does not appear when you choose **OAuth (pre-registered app)**, because this probe does not sign in with the app you registered. Add the tools by name on the next step. ### Step 3: Policy & scope Choose which products receive this connector and which of its tools are available. Under **Apply to**, tick the products that should receive this connector: Claude Desktop and Microsoft 365. A connector with no products ticked is saved but delivered nowhere, which is a way to pause it. A connector that uses OAuth cannot be applied to Microsoft 365, because per-user sign-in is not available there. A connector with any tool switched off in the table below also cannot be applied to Microsoft 365, and the checkbox is disabled with a **needs every tool on** note until every tool is on. Under **Tool policy**, the table lists the tools found during discovery with an on/off switch for each. **Refresh tools** probes the server again and fills in any tools that are new since you last looked, keeping the switches you have already set. **Add tool** lets you type a tool name by hand when discovery could not reach the server. On Claude Desktop, a tool you switch off is blocked, a tool you switch on is available and each member still approves its use, and a tool that is not listed at all is left to the member to enable or disable. You cannot apply this connector to Microsoft 365 while any tool in this table is switched off. If you are editing a connector that already applies to Microsoft 365 and you switch a tool off, a warning tells you that saving will remove it from Microsoft 365. Click **Save** to create the connector. It appears in the **Connectors** card and is delivered to the products you ticked. ## Editing and removing a connector Click the edit icon next to a connector in the card to open the same wizard with its current values filled in. Changing the authentication method clears any stored secret and the app details saved for **OAuth (pre-registered app)**. Click the remove button next to a connector to delete it; it is withdrawn from every product at the next refresh. If you delete a connector that takes priority over an inherited connector with the same name, the inherited connector applies again from that refresh. # Connect Claude Desktop to Claude for Government Source: https://claude.com/docs/government/deploy-desktop/configure Choose between single-machine setup and fleet deployment, understand the administrator requirements for each, and connect Claude Desktop to Claude for Government. > **Who this is for:** IT administrators who install Claude Desktop on agency devices and connect it to Claude for Government. A fresh install of Claude Desktop connects to claude.ai. To connect it to Claude for Government instead, each device needs one managed setting that tells the app where to reach Claude for Government. Once that setting is in place, everything else that governs the app (which products and features are available, model access, [connectors](/docs/government/connectors/overview), usage limits, the Claude Desktop banner) is controlled through the [tenant](/docs/government/tenant-admin/configuration) and [organization](/docs/government/org-admin/configuration) configuration pages in this portal and delivered to each user when they sign in. ## Choose how to deploy There are two ways to get Claude Desktop installed and connected to Claude for Government. They differ in who runs the installer, what rights that requires, and how the setting reaches the app. | | Configure a single machine | Deploy to your fleet | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Best for | Confirming the app works on a representative device before a wider rollout, or setting up a small group of devices by hand | Production rollout across your agency | | Who installs the app | A person at the device | Your device management system (for example Intune, Configuration Manager, or Jamf) | | Administrator rights to install | Needed by the person doing each install | Not needed by end users; the management system installs with elevated rights | | How the address is set | Entered in the app's built-in configuration window | Pushed as a configuration profile alongside the app | For a production rollout, use your device management system so end users never need administrator rights. The single-machine path is for testing first or for a small group you set up by hand, with an administrator doing each install. That path can also export a ready-made profile for your management system, so it is a useful starting point even when the fleet path is your destination. ## Before you begin Confirm each of the following before you start either path. * **User accounts exist.** Claude Desktop signs users in to the same accounts as this portal. For each user, including your own test account, check with your tenant administrators that the user can sign in (a [routing rule](/docs/government/tenant-admin/identity-and-access) covers them) and has a [seat tier](/docs/government/org-admin/seat-tiers) with at least one model enabled. * **Devices can reach Claude for Government.** Claude Desktop on every device must reach the Claude for Government host over HTTPS on port 443. That one host carries the app's configuration and chat traffic. * **Browsers can reach sign-in.** Sign-in happens in the user's default web browser, not in the app. Browsers on each device must reach the Claude for Government host, its sign-in service (a separate host that your Anthropic representative provides), and your agency's identity provider. * **The device meets Claude Desktop's requirements.** See the Claude Desktop [system requirements](/docs/third-party/claude-desktop/installation#system-requirements) for macOS and Windows device requirements. For a Windows fleet, work through the [Windows fleet checklist](/docs/government/deploy-desktop/windows-checklist), which covers the Virtual Machine Platform feature that Cowork needs along with the installer, policy, and network prerequisites. * **Windows devices used for Code have Git for Windows.** On Windows, only the Code part of Claude Desktop needs Git for Windows. Chat and Cowork work without it. Install Git on the devices whose users will work in Code, or turn **Code in Claude Desktop** off under [Product availability](/docs/government/config/settings#product-availability) so that users are not prompted to install Git. * **You can install the app.** Installing by hand needs administrator rights on each device; see [Configure a single machine](#configure-a-single-machine) for what that means on each platform. Installing through your device management system does not, because the management system installs with elevated rights. The [macOS deployment guide](https://support.claude.com/en/articles/12611117-deploy-claude-desktop-for-macos) and the [Windows deployment guide](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) cover where to download the installer and how to distribute it. * **The app is current.** Deploy Claude Desktop 1.46388.1 or later. ## The managed setting The setting is called `bootstrapUrl`, and its value is the Claude for Government host followed by the fixed path `/gateway-api/user/bootstrap`. ```text theme={null} https:///gateway-api/user/bootstrap ``` The Claude for Government host is the same domain name you use to access Claude for Government. If you are unsure of it, ask your Anthropic representative. The app uses the address exactly as entered; it fetches each user's configuration from it and starts sign-in from it, so include the full path. Use the host exactly as it was provided to your agency. An alias that your agency sets up on its own, such as a DNS record, redirect, or reverse proxy under your own domain that forwards to Claude for Government, does not work as the bootstrap address. The app accepts sign-in addresses only on the host in `bootstrapUrl`, and Claude for Government answers sign-in only on the host provided to your agency, so the app cannot sign in through such an alias. With any alias of this kind, the app still offers **Sign in with your organization**, but sign-in fails as soon as the user chooses it; see [Troubleshooting](#troubleshooting). The app supports routing its traffic through your network's proxy server, as the [Security and data handling](/docs/government/security/security-and-data-handling#network-egress-required-domains-and-proxies) page describes. ### How the app uses the bootstrap address The address is the same for every device and user in your agency and carries no credentials or user information, so the same profile is safe to push to your whole fleet. A request to the address without a signed-in session is refused. When a user chooses **Sign in with your organization**, the app asks the Claude for Government host to start a sign-in, shows the pairing code it receives, and opens the host's sign-in page in the user's default browser. That page asks for the user's agency email address, then sends the browser to the sign-in service and on to your agency's identity provider. After signing in, the user acknowledges the system-use notification, confirms that the code shown in the browser matches the one in the app, and approves. Claude for Government then issues the app a session for that user, which the app stores encrypted on the device. The app presents that session, and nothing from the profile, when it downloads the user's configuration from this address and when it sends chat traffic to the same host. It re-checks the configuration about every 30 minutes and at each launch. A session lasts until the user has gone without using Claude for longer than the [Session idle timeout](/docs/government/config/settings#session-idle-timeout) your tenant administrators set, which is 24 hours unless they change it, or until it reaches the [Maximum session length](/docs/government/config/settings#maximum-session-length) if one is set. Using Claude extends the session, but leaving the app open on an idle, locked, or sleeping device does not. When a session has ended, the app keeps the user's configuration and asks them to sign in again, with a message and a **Sign in again** button while the app is open, or with the sign-in screen the next time it starts, and it reloads the configuration once they sign in. Claude Desktop 1.34493.0 or later shows these prompts. Earlier versions can report an ended session as a **Configuration sync issue**, so update them. The configuration that the app downloads for a user includes the following settings, all of which you manage in this portal. | What the app receives | Where it is set | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Which of Chat, Cowork, and Code the user can open, and whether Advanced file analysis is on in Chat | [Product availability](/docs/government/config/settings#product-availability) on the Config page | | The models the user can choose | The user's [seat tier](/docs/government/org-admin/seat-tiers) | | Connectors, plugins, and the settings for the built-in tools | The [tool and connector cards](/docs/government/config/settings#tool-and-connector-cards) on the Config page | | The hosts that tools may reach | [Allowed network hosts](/docs/government/config/settings#allowed-network-hosts) | | The folders a user can choose as a workspace | [Allowed workspace folders](/docs/government/config/settings#allowed-workspace-folders) | | The banner shown across the top of the app | [Claude Desktop banner](/docs/government/config/settings#claude-desktop-banner) | | Where the app sends your agency's own telemetry, if you have set a collector | [Telemetry endpoint](/docs/government/config/settings#telemetry-endpoint) | | Whether automatic updates are blocked, and the restart deadlines for a downloaded update and for a configuration change | [Block automatic updates](/docs/government/config/settings#block-automatic-updates), [Restart deadline for updates](/docs/government/config/settings#restart-deadline-for-updates), and [Restart deadline for configuration changes](/docs/government/config/settings#restart-deadline-for-configuration-changes) on the Config page | ## Configure a single machine Installing by hand needs administrator rights on the device. On Windows, the installer registers a Windows system service, so it must run as a local administrator. On macOS, installing to the shared Applications folder requires an administrator. On Linux, installing the package requires root. Claude Desktop has a built-in configuration window that is hidden until you enable developer mode. These steps use it to set the address on one machine without any management tooling. Install Claude Desktop on the test machine and open it. On Windows, run the installer while signed in as a local administrator. The claude.ai sign-in screen appears; this is expected before the app is configured. Stay on this screen. From the **Help** menu, choose **Troubleshooting**, then **Enable Developer Mode**, and confirm the prompt. On Windows the **Help** menu is under the application menu (☰) on the sign-in screen. The app relaunches with a **Developer** menu added. From the **Developer** menu, choose **Configure Third-Party Inference**. This is the correct option for Claude for Government despite the name. The window opens on its **Connection** section. In the window's left sidebar, click **Source**, which on an unconfigured machine appears last in the list and is dimmed but is still clickable. Enter the full address from the section above in the **Bootstrap config URL** field. You do not need to change any other field, because Claude for Government supplies the provider, credentials, and model list after sign-in. A **Trust bootstrap-delivered settings** switch appears once the field has a value. Leave it off; the **Allow the gateway address** step below explains what it does. Click **Apply Changes**, then click **Save & Restart** and let the app relaunch. The sign-in screen now offers **Sign in with your organization** alongside the claude.ai option. Choose it. The app shows a pairing code and opens the sign-in page in your browser. Sign in with your agency credentials, confirm that the code in the browser matches the one in the app, and approve. The app picks up the session. After sign-in, the app opens a small **Apply settings from your organization?** window that lists a **Gateway base URL**. The window opens without taking keyboard focus, so if your browser is still in front, switch back to Claude to find it. Expand **Gateway base URL** and confirm that the address is on your Claude for Government host, then click **Allow**. The app applies your organization's settings and connects, and it does not ask again unless the gateway address later changes. The app asks because you entered the bootstrap address by hand rather than through device management, and it applies none of your organization's settings until you click **Allow**. Choosing **Quit**, pressing Esc, or closing the window quits the app, and it asks again the next time it opens. If the address is not on your host, do not click **Allow**. Leave the window open, reopen the configuration window from the **Developer** menu, correct the **Bootstrap config URL** in its **Source** section, click **Apply Changes**, and then click **Save & Restart** so that the app relaunches with the corrected address. The **Trust bootstrap-delivered settings** switch in the **Source** section turns this prompt off. With the switch on, the app trusts everything your Claude for Government host delivers without asking, including connectors and helper scripts that run on the device. That is the same trust the app extends when the bootstrap address comes from machine-wide device management. Most single-machine tests do not need the switch, because the app asks only once. If you do turn it on, first confirm that the bootstrap address is on your Claude for Government host. For the other settings this prompt can cover, see [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent). Work through [Confirm it worked](#confirm-it-worked) below. After the test, the same configuration window has an **Export** menu that produces files ready for your management system: a `.mobileconfig` profile for macOS, a `.reg` file for Windows, an ADMX template for Intune or Group Policy, and a Profile Manifest for Jamf. Before exporting, turn on **Disable Claude.ai sign-in** in the window's **Workspace** section so the exported profile hides the claude.ai option on managed devices, and make sure **Trust bootstrap-delivered settings** in the **Source** section is off so the exported files do not carry it. ## Deploy to your fleet When your device management system deploys Claude Desktop, end users receive the app without running an installer themselves. The management system installs the package with the system or root account on each platform, so end users need no administrator rights and see no elevation prompt. Push both the app installer and the configuration profile below through the same system. The recommended profile contains two keys. In the macOS and Windows profiles below, write every value as a string exactly as shown, including booleans as the strings `"true"` or `"false"`; the Linux file uses native JSON types, as shown. | Key | Value | Purpose | | ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `bootstrapUrl` | `https:///gateway-api/user/bootstrap` | Required. Points the app at Claude for Government. | | `disableDeploymentModeChooser` | `"true"` | Recommended. Hides the claude.ai sign-in option so users can only sign in to Claude for Government. Like any recognized key other than the automatic update settings, it also marks the device as managed (see [Order of deployment](#order-of-deployment)). | No other keys are needed to connect the app; Claude for Government supplies everything else per user after sign-in. If your agency distributes Claude Desktop updates itself, [Automatic updates](#automatic-updates) below describes one more key to add. The profile contains no secrets, only a host. Keys documented for other Claude plans, such as `forceLoginOrgUUID` or `loginSsoOrgDomain`, apply only to claude.ai workspaces and are not used here. Keys for a separate sign-in provider, such as `bootstrapOidc` and `inferenceGatewayOidc` in the Claude Desktop [configuration reference](/docs/third-party/claude-desktop/configuration), do not work with Claude for Government either. Leave them unset, because you cannot connect the app directly to your identity provider. With Claude for Government, the name the app shows for the connection in the lower-left corner of its window and at the top of its account menu is not controlled through device management. Leave the `deploymentDisplayName` and `deploymentDisplaySubtitle` keys unset, because the app discards them once it downloads the user's configuration after sign-in. ### macOS Claude Desktop reads managed preferences in the `com.anthropic.claudefordesktop` domain. Deploy a configuration profile that sets the two keys in that domain as strings. ```xml theme={null} bootstrapUrl https:///gateway-api/user/bootstrap disableDeploymentModeChooser true ``` Most device management consoles, including Jamf and Intune, build the profile around these keys for you. For a complete `.mobileconfig` ready to upload, use the Export menu described in the single-machine path. ### Windows Claude Desktop reads string (`REG_SZ`) values by name under `HKLM\SOFTWARE\Policies\Claude`. Deliver them with Intune, Group Policy, or any tool that writes machine policy. The ADMX template from the Export menu makes both keys available in the policy editor. As a `.reg` file: ```text theme={null} Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Claude] ; substitute the Claude for Government host "bootstrapUrl"="https:///gateway-api/user/bootstrap" "disableDeploymentModeChooser"="true" ``` The `.reg` file from the Export menu targets `HKEY_CURRENT_USER`, which is correct for single-machine testing. For fleet deployment, deliver the values under `HKEY_LOCAL_MACHINE` as shown here. After a user signs in, Claude for Government sends the app the address to use for chat traffic, which the app shows as **Gateway base URL**. When the registry values are under `HKEY_LOCAL_MACHINE`, the app accepts that address without asking the user. When they are under `HKEY_CURRENT_USER`, the app asks each user once to allow it, as described under [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent). Have each user confirm that the address is on your Claude for Government host before they click **Allow**. To approve the address in advance on a test device configured under `HKEY_CURRENT_USER`, first confirm that the `bootstrapUrl` value is on your Claude for Government host, then add `"trustBootstrapDelivery"="true"` next to it under the same key. That value tells the app to trust everything your Claude for Government host delivers without asking, including connectors and helper scripts that run on the device, which is the same trust the app extends when `bootstrapUrl` is under `HKEY_LOCAL_MACHINE`. If you later move a test device's values to `HKEY_LOCAL_MACHINE`, move all of them, because once any value exists under `HKLM\SOFTWARE\Policies\Claude` the app ignores `HKEY_CURRENT_USER` entirely. Cowork, the agentic workspace in Claude Desktop, requires the **Virtual Machine Platform** Windows optional feature. Enable that feature through your device management system before rollout. On a device where the feature is not enabled, Cowork is unavailable until someone turns the feature on, which requires administrator rights that a standard user does not have. Chat works without this feature, except for Advanced file analysis. The [Windows fleet checklist](/docs/government/deploy-desktop/windows-checklist) lists the remaining Windows prerequisites and explains what to do [if some devices are not ready for Cowork](/docs/government/deploy-desktop/windows-checklist#if-some-devices-are-not-ready-for-cowork). ### Linux Place a JSON file at `/etc/claude-desktop/managed-settings.json` containing the same keys at the top level. ```json theme={null} { "bootstrapUrl": "https:///gateway-api/user/bootstrap", "disableDeploymentModeChooser": true } ``` The file must be a regular file (not a symlink), and the file and its directory must be owned by root and must not be group- or world-writable. If the permissions are wrong, the app rejects the file, logs the reason to `main.log`, and treats the device as managed but unreadable, so local settings are also disabled until the permissions are corrected and the app is relaunched. ### Order of deployment Deploy the configuration before the app wherever you can. A user whose device already has the profile opens Claude Desktop for the first time and lands directly on the Claude for Government sign-in screen, with no opportunity to sign in to claude.ai by mistake. Once `bootstrapUrl`, `disableDeploymentModeChooser`, or any other recognized key except the automatic update settings is present in the profile, the device is managed. The in-app configuration window becomes read-only, and locally authored settings, including a single-machine test configuration, are ignored in favor of the profile. A managed device uses only the connection in the profile: users cannot add, import, or switch to other configurations in that window. Users on a managed device can still turn on developer mode from the **Help** menu by choosing **Troubleshooting**, then **Enable Developer Mode**. The configuration window it reveals stays read-only, so they can view the connection there but not change it. If a group of users needs a different connection, scope a different profile to their devices or users in your management system, or leave those devices without a profile and set them up as described under [Configure a single machine](#configure-a-single-machine). Removing the profile returns the device to local control. The app reads managed configuration at launch. After you change the profile on a device where the app is already running, have the user fully quit and reopen it. ### Automatic updates On macOS and Windows, Claude Desktop downloads and installs its own updates by default. If your agency distributes Claude Desktop updates itself, turn automatic updates off in both of the following places so that devices never update themselves. * **On the Config page.** Have a tenant administrator or organization owner turn on [Block automatic updates](/docs/government/config/settings#block-automatic-updates) and [lock](/docs/government/config/overview#locks) it, so that no level below theirs can turn updates back on. Claude Desktop applies this setting once a user has signed in and the app has loaded their configuration from Claude for Government. With that configuration loaded, the app follows this setting alone, whether it is on or off, and ignores the profile value. * **In the profile.** Add `disableAutoUpdates` with the value `"true"` to the [macOS](#macos) and [Windows](#windows) profiles above. The app applies the profile value only when it starts without a signed-in user, for example on a newly deployed device or when a user opens the app and has to sign in again because their session expired. Without the Config page setting, the profile value does not stop signed-in devices from updating. Claude Desktop reads its update settings when it starts. If the app is already running on a device when you change the Config page setting or the profile, the change applies the next time the app starts. If you leave automatic updates on, [Restart deadline for updates](/docs/government/config/settings#restart-deadline-for-updates) on the Config page sets how long a user can put off the restart that installs a downloaded update. On Linux, apt installs Claude Desktop updates, and the app does not download or install its own. By default, installing the `claude-desktop` package adds Anthropic's apt repository, so `apt upgrade` installs new versions from `downloads.claude.ai`, and so do unattended upgrades on devices that have them turned on. The **Block automatic updates** setting and the `disableAutoUpdates` key do not change these updates. To keep Linux devices on the versions your agency distributes, add the line `CLAUDE_DESKTOP_ADD_REPO=false` to `/etc/default/claude-desktop`, and create that file if it does not exist. The package then does not add the repository when it installs or upgrades. On a device that already has the package, also delete `/etc/apt/sources.list.d/claude-desktop.list`. ## Confirm it worked Run through these checks on a configured machine from either path. Launch the app. The sign-in screen offers **Sign in with your organization**. On a managed device with `disableDeploymentModeChooser` set, it is the only option. If only the claude.ai sign-in appears, the configuration did not reach the app. On a device that received the profile through your management system, open the configuration window (the first three steps of the single-machine path). It should be read-only with a banner noting that your organization manages the configuration. If it is still editable, no recognized key reached the app, even if your management console reports the profile as delivered. The diagnostic report's Configuration section (next step) shows exactly what the app read. From **Help**, choose **Troubleshooting**, then **Generate Diagnostic Report**. The report's Configuration section lists which keys the app read, where each came from, and any values that failed to parse. Secret values are redacted, so the report is safe to attach to a help-desk ticket. Sign in as a provisioned test user. If the app asks **Apply settings from your organization?**, expand the **Gateway base URL** it lists and confirm that the address is on your Claude for Government host, then click **Allow**. Chat works and the model picker lists the models you expect for that user's seat tier. After sign-in, what the app offers matches that user's [product availability](/docs/government/config/settings#product-availability) settings (with everything on, the sidebar shows **Home** and **Code**), and any organization-managed connectors appear in the app. One end-to-end test is to set a short message in the **Claude Desktop banner** setting on the tenant [Config](/docs/government/tenant-admin/configuration) page during rollout; if the message appears across the top of the app after sign-in, per-user delivery is working. If sign-in succeeds but none of these settings arrive, re-check the configured address. ## Troubleshooting | What you see | Likely cause | What to do | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Only the claude.ai sign-in screen; no organization option | The configuration never reached the app: the profile was not delivered, a key name is misspelled, the value is in the wrong location or registry type, or the app was not relaunched after the change | Verify delivery in your management console, generate a diagnostic report and check its Configuration section, then fully quit and reopen the app | | Sign-in times out, or the browser says the code expired | The app stops waiting after about five minutes | Cancel and start sign-in again; a fresh code is issued | | Sign-in fails as soon as the user chooses **Sign in with your organization**, and the error on the sign-in screen or in `main.log` says that an address "must be same-origin" as the configured host | `bootstrapUrl` points at an alias that your agency operates, such as a DNS record or reverse proxy under your own domain, rather than the host provided to your agency | Use the host provided to your agency in `bootstrapUrl`, exactly as provided, redeploy the profile, then fully quit and reopen the app | | The diagnostic report or `main.log` shows "Managed configuration is invalid; local settings are disabled until it is fixed" | The app detected a managed profile but could not read any of its values | Correct the profile and redeploy; the report's Configuration section names each key that failed | | Signed in, but the model picker is empty, or the app shows a **Configuration can't be used** banner whose **Details** or **Copy report for IT** text says the provider returned no usable models | The user has no seat tier, or none of the tier's models is available in Claude for Government, so the app received an empty model list. Nothing is wrong with the device's configuration | Have an organization owner check the user's seat tier on the [Users](/docs/government/org-admin/users) page and the tier's models on the [Seat tiers](/docs/government/org-admin/seat-tiers) page | | An **Apply settings from your organization?** window appears after sign-in or at every launch, or the app quits when the user dismisses that window | The bootstrap address was entered in the app or set per user (for example under `HKEY_CURRENT_USER`), so the app asks each user to allow the gateway address that Claude for Government sends before it applies any of the organization's settings, and the user has not yet clicked **Allow**. Choosing **Quit**, pressing Esc, or closing the window quits the app, and it asks again on the next launch. | Have the user expand **Gateway base URL** in that window, confirm that the address is on your Claude for Government host, and click **Allow**. The window does not take focus when it opens, so have the user switch to the Claude app to find it. If the address is not on your host, check the bootstrap address configured on that device. To stop the prompt across a fleet, deliver the bootstrap address through machine-wide device management, as described under [Deploy to your fleet](#deploy-to-your-fleet). Versions earlier than 1.32352.0 that ask for this approval also show a **Configuration sync issue** banner that says "bootstrap response is missing required field(s): inferenceGatewayBaseUrl" for the same cause. Update the app to the latest version, then answer the prompt. | | The browser shows a connection error instead of Claude for Government or its sign-in page: "Secure Connection Failed" with `PR_CONNECT_RESET_ERROR` in Firefox, or `ERR_CONNECTION_RESET` in Chrome | A web filter, firewall, or proxy reset the connection, either on your agency's network or on the Claude for Government side. | If the address opens in another browser on the same computer, check the first browser's proxy and DNS settings. Otherwise, open the address from outside your agency's network, for example on a phone using cellular data. If the phone shows a web page, not a connection error, have your network team allow the host in that address and the hosts described under [Before you begin](#before-you-begin). If the phone also fails, or the team finds no block, contact your Anthropic representative with the address, the time and time zone of the error, and your network's public IP addresses. | | During sign-in, the browser shows a Microsoft page titled "You cannot access this right now", sometimes in one browser but not in another | Microsoft Entra ID shows this page when one of your agency's Conditional Access policies blocks the sign-in, for example a policy that limits which browsers, devices, or locations can sign in. The refusal happens before the sign-in reaches Claude for Government, so nothing in the app or in this portal changes it. | Ask your identity team to find the failed sign-in in the identity provider's sign-in logs. In the Microsoft Entra admin center, the sign-in event's **Conditional Access** tab names the policy that blocked it and the condition that was not met. Adjust the policy, or have the user sign in from a browser or device the policy allows (Claude Desktop opens sign-in in the computer's default browser). | | The app shows **Your session has expired** or **You've been signed out** with a **Sign in again** button, or a device that was already set up opens to the sign-in screen | The user's Claude for Government session ended, most often because they had not used Claude for longer than your tenant's [Session idle timeout](/docs/government/config/settings#session-idle-timeout). A device left idle, locked, or asleep does not keep a session alive. A session also ends at the Maximum session length, or when the user or an administrator signs it out. A user can have at most six active Claude Desktop sessions. When they sign in to Claude Desktop again while six are active, Claude for Government ends the Claude Desktop session that is closest to expiring. | Have the user sign in again. The app keeps its configuration and reconnects. If the session limit is the cause, the user can go to their [Sessions](/docs/government/account/sessions) page and sign out of sessions they no longer use. If people are asked to sign in more often than you intend, ask a tenant administrator to review **Session idle timeout** and **Maximum session length** on the [Config](/docs/government/tenant-admin/configuration) page. On Claude Desktop versions earlier than 1.34493.0 the same situation can appear as a **Configuration sync issue** banner instead, so update the app. | | Web search is on for your organization, but a user does not have it, and under **Customize**, then **Connectors**, **Web Search** shows as not connected and **Connect** fails, while chat works | A firewall or secure web gateway on that user's network path filters traffic by application. Claude Desktop connects to web search on your Claude for Government host over HTTPS, and such equipment can classify that connection as Model Context Protocol (MCP) traffic and block it even when the host itself is allowed. | Ask your network team to allow this traffic to your Claude for Government host for the affected users. The user's `main.log` records each failed attempt, including any block page the network returned. Then have the user select **Connect** next to **Web Search**, or restart the app. | For anything else, the app writes its log to `~/Library/Logs/Claude-3p/main.log` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\main.log` on Windows, and `~/.config/Claude-3p/logs/main.log` on Linux. The log records which configuration keys were read or dropped and why. The diagnostic report from the verification checklist produces a bundle, without conversation content, that you can send to your Anthropic representative. ## Things to know * Configuration changes made in this portal do not need to be pushed to devices. The app re-checks Claude for Government for changes about every 30 minutes and at each launch, and prompts users to relaunch when something changed. * New and retired models appear in the model picker without any profile change or app update; model access is controlled through [seat tiers](/docs/government/org-admin/seat-tiers). * The sign-in flow and what a user sees on the [Sessions](/docs/government/account/sessions) page after pairing a device are covered on that page. # Windows fleet checklist Source: https://claude.com/docs/government/deploy-desktop/windows-checklist Device, installer, virtualization, policy, network, and account prerequisites to confirm before deploying Claude Desktop across a Windows fleet for Claude for Government. > **Who this is for:** IT administrators and desktop engineering teams who are preparing a Windows fleet for Claude Desktop connected to Claude for Government. Use this checklist to confirm what your devices, policies, network, and user accounts need before you push Claude Desktop to a Windows fleet. Several items concern the virtual machine that Claude Desktop runs on each device for Cowork, the agentic workspace in Claude Desktop, and for Advanced file analysis in Chat. When every item is in place, follow [Connect Claude Desktop to Claude for Government](/docs/government/deploy-desktop/configure) to deliver the managed setting and the app. ## Device requirements * **Windows version and architecture.** Devices need Windows 10 version 2004 (build 19041) or later, including Windows 11, on x64 or Arm64 hardware. See the Claude Desktop [system requirements](/docs/third-party/claude-desktop/installation#system-requirements). Devices in Windows S mode cannot run Cowork. * **Memory and disk.** Plan for at least 8 GB of memory and about 20 GB of free space on the drive that holds `%LOCALAPPDATA%`. Cowork keeps its workspace there after downloading it the first time a user starts a task. Cowork still starts on a device with less memory, but tasks run slowly. ## Installer and packaging * **Use the `.msix` package.** Cowork is available only when Claude Desktop is installed from the `.msix` package. The legacy `.exe` installer gives you Claude Desktop without Cowork. See [Install the app](/docs/third-party/claude-desktop/installation#install-the-app). * **Install machine-wide.** Have your management system (for example Intune or Configuration Manager) provision the package for all users from the system account, or provision it from an elevated PowerShell session with `Add-AppxProvisionedPackage` or the equivalent DISM command. The package registers a Windows service that Cowork uses, so an install run by a standard user fails, and installing by hand requires a local administrator. The [Windows deployment guide](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) covers downloading and distributing the package. * **Allow trusted app installation.** Make sure Windows policy allows trusted app packages to install from outside the Microsoft Store. If your security baseline configures **Allow all trusted apps to install** (the `ApplicationManagement/AllowAllTrustedApps` policy), set it to enabled. Windows Developer Mode is not required. * **Intune scripts.** For Intune, Anthropic publishes [install and detection scripts](https://downloads.claude.ai/releases/enterprise/intune/Claude-Intune-README.md) that deploy the `.msix` as a Win32 app, so that Intune keeps reporting the app as installed after the app updates itself. * **Offline installer.** For networks that cannot reach `downloads.claude.ai`, deploy the [offline installer](/docs/third-party/claude-desktop/installation#offline-installation), which includes the components that the app otherwise downloads from that host, as listed under [Network access](#network-access). * **Nothing else to pre-install.** The `.msix` package is self-contained, with no separate runtimes or frameworks to install first. Git for Windows is needed only on devices whose users will work in Code; see [Before you begin](/docs/government/deploy-desktop/configure#before-you-begin). * **Software intake.** The package is MSIX rather than MSI or EXE, and Intune, Configuration Manager, and PowerShell deploy MSIX natively. If your software intake process names MSI or EXE packages specifically, confirm that it accepts MSIX. An MSIX package installs without prompts when your management system deploys it and takes no vendor-specific switches. ## Application control rules If you enforce application control with AppLocker or App Control for Business (formerly Windows Defender Application Control), allow Claude Desktop by publisher or by package family name rather than by path, and let the rule match any version, so that it keeps matching as the app updates. | Identifier | Value | | ---------------------- | ---------------------- | | Package name | `Claude` | | Package family name | `Claude_pzs8sxrjxfjjc` | | Publisher display name | Anthropic, PBC | These values identify the `.msix` package from the download site and the offline installer, and they do not change between versions or architectures. Claude Desktop runs Chat conversations, Cowork tasks, and Code sessions through an agent helper named `claude.exe`, a separate executable signed by Anthropic. With the standard installer, the app downloads the helper and places it under each user's profile rather than inside the package. The helper runs during conversations, tasks, and Code sessions and connects to your Claude for Government host. If AppLocker executable rules or endpoint security software with path-based rules apply on your devices, allow the helper by publisher too, as described under [Endpoint security software](/docs/third-party/claude-desktop/installation#endpoint-security-software). ## Cowork virtualization Cowork runs the shell commands that Claude issues inside a dedicated virtual machine that the app manages on each device, and Advanced file analysis in Chat uses the same virtual machine. Users install nothing for this, but each device must be able to start the virtual machine. The [Cowork readiness check](/docs/third-party/claude-desktop/installation#check-device-readiness) is a small program that verifies most of the requirements below on a device without installing anything or signing in. Run it on one device of each hardware model, and resolve what it reports before the broad rollout. * **Virtual Machine Platform.** Enable the **Virtual Machine Platform** optional Windows feature (`VirtualMachinePlatform`) on every device before rollout, for example by running `Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All -NoRestart` from an elevated PowerShell session, then restart the device so that the feature takes effect. Turning the feature on requires administrator rights, so a standard user cannot enable it later. * **Hardware virtualization.** Turn on hardware virtualization in each device's firmware (Intel VT-x or AMD-V on x64 devices). * **Service logon right.** The virtual machine runs under an account in the built-in `NT VIRTUAL MACHINE\Virtual Machines` group (SID `S-1-5-83-0`), the same group that Hyper-V and WSL 2 use, so a fleet where either of those works already meets this requirement. You only need to act if your security baseline manages the **Log on as a service** right through Group Policy. In that case, include this group, and keep it out of **Deny log on as a service**. * **Uncompressed application data.** Leave `%LOCALAPPDATA%\Claude-3p` out of NTFS compression and Encrypting File System (EFS) policies, because the virtual machine's disk cannot start from a compressed or EFS-encrypted folder. * **Virtual desktops.** On virtual desktop infrastructure, the Windows desktops themselves run as virtual machines, so Cowork can start only where the hosting platform exposes nested virtualization to them. Run the readiness check on one desktop in each pool, and make Cowork available to virtual desktop users only where it passes. On a device that does not meet these requirements, Chat still works apart from Advanced file analysis, and Cowork reports that it is unavailable. If a device meets them and Cowork still fails to start, check whether endpoint security software is blocking the agent helper, as described under [Application control rules](#application-control-rules). ### If some devices are not ready for Cowork You can deploy Claude Desktop to devices that do not yet meet the [Cowork virtualization](#cowork-virtualization) requirements. Before you deploy to those devices, have a tenant administrator or organization owner turn off the **Cowork in Claude Desktop** and **Advanced file analysis in Chat** switches under [Product availability](/docs/government/config/settings#product-availability) for the devices' users, for example through a [directory group](/docs/government/config/overview#group-specific-settings) that contains them. With both switches off, those users keep Chat and Code, and the app does not download or start the virtual machine on their devices. Turn both switches back on once those devices meet the requirements. ## Configuration values * **Two registry values.** Push the two values described under [Windows](/docs/government/deploy-desktop/configure#windows) as machine policy under `HKLM\SOFTWARE\Policies\Claude`: the required `bootstrapUrl` and the recommended `disableDeploymentModeChooser`. No other values are needed to connect the app, because everything else reaches each user from Claude for Government at sign-in. If your agency distributes Claude Desktop updates itself, also add the value described under [Automatic updates](/docs/government/deploy-desktop/configure#automatic-updates). * **Delivery order.** Deliver the values before the app wherever you can, so that users land directly on the Claude for Government sign-in screen, as [Order of deployment](/docs/government/deploy-desktop/configure#order-of-deployment) explains. ## Network access Claude Desktop's own traffic and the browser's traffic to the Claude for Government sign-in service use HTTPS on port 443. Claude for Government does not publish IP addresses for its host or its sign-in service, so allowlist both by hostname. The [Security and data handling](/docs/government/security/security-and-data-handling#network-egress-required-domains-and-proxies) page explains what each connection carries. * **App traffic.** Allow Claude Desktop on every device to reach the Claude for Government host, which carries the app's configuration and chat traffic. * **Browser sign-in traffic.** Allow the browser on every device to reach the Claude for Government host, the Claude for Government sign-in service (a separate host that your Anthropic representative provides), and your agency's identity provider. Sign-in happens in each user's default browser, not in the app. * **`downloads.claude.ai`.** The app downloads two components from this host: the agent helper described under [Application control rules](#application-control-rules), which Chat, Cowork, and Code all need, and the Cowork workspace, which Cowork tasks and Advanced file analysis in Chat need. The app downloads each one whenever the device does not already have the version that the app needs, typically after an install or an app update. The offline installer includes both, so devices installed with it need this host only for application updates while automatic updates are on. * **`www.claudeusercontent.com`.** This host serves the frame that displays artifact previews. * **Update hosts.** While [automatic updates](/docs/government/deploy-desktop/configure#automatic-updates) are on, also allow the hosts listed under Auto-updates in [Required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths). The telemetry rows there never apply, because Claude for Government does not send telemetry to Anthropic. * **Hosts your tools and connectors use.** Allow the hosts you add to [Allowed network hosts](/docs/government/config/settings#allowed-network-hosts) (such as package registries), the addresses of any connectors you configure on the Config page (including Microsoft 365 if you set up that connector), and your telemetry collector if you set one. * **Proxies.** The app and the Cowork workspace follow the operating system's proxy settings, including PAC files, as described under [Network proxy](/docs/third-party/claude-desktop/network-proxy). If your proxy inspects TLS, validate sign-in, a chat, and a Cowork task on a pilot device before rollout. ## User accounts and seats Make sure every user in the rollout can sign in and has a seat before their device is set up. Each user needs a [routing rule](/docs/government/tenant-admin/identity-and-access) that covers them and a [seat tier](/docs/government/org-admin/seat-tiers) with at least one model enabled. A user without a seat tier can sign in but gets an empty model picker, which can look like a device problem and is covered in the [Troubleshooting](/docs/government/deploy-desktop/configure#troubleshooting) table. # Import your data from Claude for Government Web Source: https://claude.com/docs/government/desktop/import Copy your conversations, projects, and files from Claude for Government Web into Claude Desktop. > **Who this is for:** Anyone who used Claude for Government Web (the web app) and now uses Claude Desktop connected to Claude for Government. The import copies your conversations, their attached files, and the projects you created, including each project's files and instructions. It does not copy projects that other people shared with you. ## Before you begin * **You have an account on the web app.** It must use the same work email address as your account in Claude Desktop. * **You are signed in to the web app in your default browser.** The import opens a browser tab there and asks for a one-time code, which expires after a few minutes. > **For administrators:** Anthropic enables the import for each organization, so there is no [product setting](/docs/government/config/settings) for it. If a member's **Import & export** page says import is not enabled and their app is up to date, contact your Anthropic representative. The import needs Claude Desktop to download a component, so on a network that blocks `downloads.claude.ai`, deploy the offline installer described under [Installer and packaging](/docs/government/deploy-desktop/windows-checklist#installer-and-packaging) in the Windows fleet checklist. ## Run the import You start the import yourself from **Settings**, whenever you are ready. Claude Desktop does not prompt you to run it. In Claude Desktop, open **Settings**, then the **Import & export** page, and click **Import…**. Click **Sign in to Claude for Government Web…**, and in the dialog that opens, click **Sign in**. Claude Desktop shows a one-time code and opens the web app in your default browser. Sign in there with your work account if you are asked to, enter the code, and approve the request. Then return to Claude Desktop. Check that the email address shown is your work address, then click **Fetch export** and wait for the download to finish. Click **Continue**, review what will be added, then click **Import**. The import can take a few minutes. When the dialog reports what it brought over, click **Done**. Imported conversations appear in the sidebar, and imported projects appear under **Projects** with their files. ## Continue an imported conversation Imported conversations open in Chat. The first time you send a message in one, Claude Desktop shows a **Resume imported session?** prompt. Click **Trust and resume** to continue. ## Review imported project instructions If a project had instructions in the web app, open it after the import. Its page shows a notice that the instructions came from an import, and Claude does not follow them until you accept them. Click **Review instructions** to edit and save them, or **Use as is** to accept them unchanged. They then appear under **Instructions** on the project's page. ## Remove an import To delete what an import added, open **Settings**, then the **Import & export** page. Under **Import history**, click **Remove** next to the import, or **Remove all** to remove every import listed. Before you confirm, the dialog shows how many conversations and projects it will delete. Removing an import also deletes any imported conversation you have continued since, including the new messages, and you cannot undo it. ## Troubleshooting | What you see | Likely cause | What to do | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Your export exceeds the import size limit | You have more data than the import can bring over | Remove conversations or files you no longer need in the web app, in line with your organization's records policy, then run the import again | | The account does not match your organization | You signed in to the web app with a different account or organization | In the browser, sign in to the web app with your work account, then click **Sign in** in the dialog again | | The **Import & export** page says import isn't enabled for this deployment | Your app is out of date, or Anthropic has not yet enabled the import for your organization | Update Claude Desktop to the latest version. If the page still says import isn't enabled, contact your administrator, who can ask Anthropic to enable it | For anything else, try the import again; if it keeps failing, contact your administrator. ## Things to know * **You can run the import again.** Conversations you already imported are skipped. * **Conversations can arrive as Cowork tasks.** If **Chat in Claude Desktop** is turned off for your organization under [Product availability](/docs/government/config/settings#product-availability) when you run the import, your conversations are imported as Cowork tasks instead and open only on computers where Cowork is available. * **Projects other people shared with you are not imported.** Only the projects you created come over, with their files and instructions. # Models in Claude Desktop Source: https://claude.com/docs/government/desktop/models How the model picker in Claude Desktop works in Claude for Government, what the 1M context window entry does for long conversations that would otherwise be compacted at the standard 200K window, how to choose it, and what controls which models you see. > **Who this is for:** Anyone who uses Claude Desktop in Claude for Government. The last section is for administrators. The model picker shows which Claude model answers you and lets you switch to another. It sits at the bottom of the message box in Chat, Cowork, and Code. Which models it lists depends on the [seat tier](/docs/government/account/profile) your organization has assigned to you, so a colleague may see a different list. ## Larger context window Some models appear in the picker twice. In Chat and Cowork the second entry has **1M context window** under the model's name, and in Code it shows **1M** after the name. Both entries are the same model, and the difference is how much of a conversation Claude can keep in view at once, which is called the context window and is measured in tokens (a token is a short piece of text, roughly a word or part of one). The standard entry keeps up to about 200,000 tokens (200K) in view. The **1M context window** entry keeps up to about one million (1M), five times as much. When a long conversation or task gets close to filling the context window, Claude summarizes the earlier part to make room and carries on from the summary, which the app calls compacting. With the **1M context window** entry this happens much later, so long pieces of work keep their full detail for longer. Until a conversation outgrows the standard entry's window, the two entries behave the same and use the same amount of your [allowance](/docs/government/account/usage). Past that point the **1M context window** entry keeps sending Claude the whole conversation rather than a summary, so each further message uses more of your allowance and responses can take longer to start. For Cowork tasks on very large document sets, for example hundreds of pages of PDFs, use the **1M context window** entry so Claude can keep more of the documents in view before it compacts. To use the larger window, open the model picker and choose the model's entry marked **1M context window**, or **1M** in Code. The entry in use has a check mark next to it, and the model name in the message box reads the same for both entries in Chat and Cowork, so open the picker to check. If you have not picked a model before, the larger window may already be selected. The entry appears only for models where Claude for Government offers the larger window, so if no model in your picker has it, ask your organization's owner whether your seat tier can include a model that does. The **1M context window** entry appears in Claude Desktop 1.17377.1 and later. Claude Desktop 1.28929.0 and later also keep the entry you chose for new conversations and after a restart. Versions in between return to the standard entry each time, so choose the **1M context window** entry again when you start new work, or ask your IT administrator to update Claude Desktop. ## Model availability for administrators The models a member sees come from the **Allowed models** of their [seat tier](/docs/government/org-admin/seat-tiers). Whether a model also offers the **1M context window** entry is set by Anthropic for each model rather than in the admin portal. To see which models offer it, open the model picker in Claude Desktop, which shows the entries for your own seat tier. When you change a tier's allowed models, access changes straight away. A change of either kind, to a tier's allowed models or to which models offer the entry, shows in the picker's list the next time the member starts Claude Desktop. Usage on either entry counts against the same spend limits. A long conversation on the **1M context window** entry uses more only because each message carries more of the conversation. # Plugins in Claude Desktop Source: https://claude.com/docs/government/desktop/plugins Find, install, create, and remove plugins in Claude Desktop for Claude for Government, and understand what plugins add in this deployment. > **Who this is for:** Anyone who uses Claude Desktop in Claude for Government and wants to find, install, or create plugins. A plugin is a package that adds capabilities to Claude in a single step, such as skills, slash commands, sub-agents, and hooks. Plugins work in Cowork and in Code. See the [Plugins overview](/docs/plugins/overview) for more on what a plugin can contain. ## Where plugins come from In Claude for Government, plugins reach you in three ways: * Your administrators add plugins for your organization, and some of them install automatically. * If your administrators let you add your own plugins, you can upload a plugin file or ask Claude to create a plugin with you. * If your administrators let you add plugin marketplaces, you can add a marketplace and install plugins from it. Claude for Government does not include a public plugin marketplace; your administrators add your organization's plugins. Your deployment's network controls determine whether a marketplace you add can be downloaded. ## Find and install plugins Open **Customize** in the sidebar, then **Plugins**, to see the plugins you have installed. To find the rest, select **Browse** and open the **Organization** tab, which lists every plugin your administrators have made available to you. A plugin your administrators set to install automatically is already installed. A plugin they offer for you to choose stays available on the **Organization** tab until you install it. If your administrators let you add your own plugins, you can install a plugin from a file or have Claude build one. To install from a file, select **Add**, then **Upload plugin**, and choose the plugin's `.zip` file. Claude Desktop shows a notice reminding you to install only plugins you trust, since uploaded plugins are not controlled by Anthropic. To have Claude build one, select **Add**, then **Create with Claude**, and describe the plugin you want. Claude builds it for you, and you install the result. If your administrators let you add plugin marketplaces, you can add a marketplace of your own. To add one, select **Browse**, then select the **+** button (**Add marketplace**) at the top right of the **Directory** that opens. ## Manage installed plugins Open an installed plugin to see the skills, slash commands, sub-agents, and hooks it provides, and turn the plugin on or off. To remove a plugin, open it, select the three-dot menu, then **Remove**. Plugins you remove stay removed on this device, including ones your administrators set to install automatically. A plugin you upload or create is added only on the device you are using. ## What plugins add in Claude for Government A plugin adds its skills, slash commands, sub-agents, and hooks, and its hooks run on your machine at defined points during a session. The connectors you can use are the ones your administrators provide, which appear under **Customize**, then **Connectors**. Connectors declared by a plugin you add yourself are not added to Claude Desktop's connectors. # Skills in Claude Desktop Source: https://claude.com/docs/government/desktop/skills What skills are in Claude for Government, where they come from, how to create and manage your own, and how administrators distribute skills to members. > **Who this is for:** Anyone who uses Claude Desktop in Claude for Government. The last two sections are for administrators who distribute skills to members. A skill is a set of instructions, with optional scripts and resources, that Claude loads when a task matches it, so you can teach Claude a workflow once and reuse it. See the [Skills overview](/docs/skills/overview) for how skills work. ## Where skills come from In Claude for Government, your skills come from three places: * Skills you create yourself, which are stored on your device. * Skills bundled in plugins your administrators deliver, which arrive with the plugin as described in [Plugins in Claude Desktop](/docs/government/desktop/plugins). * Skills that ship with Claude Desktop for common document tasks, such as working with spreadsheets and presentations, which Claude loads automatically when a task calls for them. ## Create and manage skills Open **Customize** in the sidebar, then **Skills**, to see your skills and turn any of them on or off. Select **Add skill**, then choose **Create with Claude** to build one with Claude's help, **Write skill instructions** to write it yourself, or **Upload a skill** to add a skill file you have. You can also ask Claude to save a workflow as a skill while you work on a task. The [skill authoring guide](/docs/skills/how-to) describes the file format for skills you write by hand. Open a skill you created to rename or delete it. Skills you create are stored on your device, so they are available only there. ## Skills for administrators The admin portal does not currently have a skills view or per-skill controls, so there is no setting that allows, blocks, or distributes a skill on its own. To distribute skills to the members you manage, bundle them in a plugin, which can be as small as the skill plus a plugin manifest, and add it on the **Plugins** card, as described in [Manage plugins and connectors](/docs/government/config/plugins-and-connectors). A plugin set to **Auto-install** delivers its skills to every member without the member doing anything. A skill you distribute this way is managed through the plugin that carries it, so to change or retire the skill, update or remove the plugin. ## Building and deploying your own skills This section walks the full path from writing a skill to delivering it to the members you manage: write the skill, package it as a plugin, upload the plugin, and check the result on a device. The packaging rules live under [Plugin archive formats](/docs/government/config/plugins-and-connectors#plugin-archive-formats). **Write the skill.** A skill is a folder named after the skill, holding a `SKILL.md` file. The file starts with YAML frontmatter carrying `name` and `description`, followed by the instructions as markdown. The folder name must match the `name` in the frontmatter. The [skill authoring guide](/docs/skills/how-to) covers the format and what makes instructions work well. You can also have Claude help, with **Create with Claude** as described under [Create and manage skills](#create-and-manage-skills), or by asking Claude to draft the skill in a Cowork task, where those are available in your deployment. If Claude hands back a `.skill` file, keep the folder it came from instead. A `.skill` file is a zip of the bare skill folder, and the **Plugins** card accepts only plugin packages, so the folder needs the plugin wrapper described next. **Mind the text-only rule.** A skill delivered through the admin portal can contain only text files, in these formats: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.csv`. Skills you create on your own device can include scripts and binary assets such as images, and the skill authoring guide describes those, but a plugin upload that contains them is rejected, so keep a skill you plan to distribute textual. **Package it as a plugin.** Arrange the skill inside a plugin and zip it. The smallest valid package is the manifest plus your skill folder under `skills/`: ```text theme={null} acme-skills.zip ├── .claude-plugin/ │ └── plugin.json └── skills/ └── brand-guidelines/ ├── SKILL.md └── palette.csv ``` `plugin.json` needs two keys, and a description is worth adding, for example `{"name": "acme-skills", "version": "1.0.0", "description": "Agency writing skills"}`. One plugin can carry several skills, one folder per skill. Zipping the plugin folder itself also works, since the upload accepts the single wrapping folder. Claude can do the assembly in a Cowork task: give it the layout above, paste in the full rules from [Plugin archive formats](/docs/government/config/plugins-and-connectors#plugin-archive-formats), and ask it to arrange the files and produce the zip. Claude Desktop in Claude for Government does not include a packaging skill, so put the layout in your request rather than assuming Claude knows it. **Upload it.** On the **Config** page, open the **Plugins** card, click **Add plugins**, and drop the zip. The preview shows the plugin's name, version, and description. A plugin packaged as above, with only skills and the three manifest keys, is not marked **Runs code**. The marker and its confirmation appear when a package declares components that can run code on members' machines, or carries a manifest key the upload does not recognize, as described under [Plugins that run code](/docs/government/config/plugins-and-connectors#plugins-that-run-code). Choose **Auto-install** to deliver the skills to every member, or **Members choose** to let members install the plugin themselves. **Check it on a device.** The upload checks packaging, not skill content, so a plugin whose `SKILL.md` is malformed uploads without complaint and simply never loads as a skill. After adding the plugin, open Claude Desktop as a member: install the plugin if you chose **Members choose**, then give Claude a task the skill should match and confirm Claude picks it up. To change the skill later, update the plugin, as described under [Update or remove a plugin](/docs/government/config/plugins-and-connectors#update-or-remove-a-plugin). # Analytics Source: https://claude.com/docs/government/org-admin/analytics Use this page to review requests, tokens, spend, top users, and credit balance over time across your organization, and to download the data as CSV files for offline reporting. > **Who this is for:** Organization owners who need to understand how their organization is using Claude and how quickly it is consuming credits. Use this page to review requests, tokens, spend, top users, and credit balance over time across your organization, and to download the data as CSV files for offline reporting. Because this data takes a moment to compute, the page starts with a **Load analytics** button. After the data loads, the results are cached for the rest of your session. You can click **Refresh** to fetch the latest numbers, and this button becomes available again 30 seconds after the previous load. A **Download** menu next to **Refresh** saves what the page shows as CSV files, described in [CSV exports](#csv-exports). ## How the data is gathered Usage figures on this page are compiled from the same metering that enforces your users' rate limits, so the request, token, and spend numbers here will closely match what your users experienced. All times are shown in your browser's time zone; if your browser reports a time zone the service does not recognize, times fall back to UTC. ## Managed and self-managed views A control at the top switches between **Anthropic-managed tiers** and **Self-managed tiers**. The two are shown separately because their economics differ: managed-tier seats are purchased as seats, while **self-managed tiers** (tiers your organization created itself on the [Tiers](/docs/government/org-admin/seat-tiers) page) draw down the billing account's balance. Spend figures and the credit panel are therefore shown only in the **Self-managed** view. If your organization has only one kind of tier, the control does not appear and the page shows only the matching view. If all of your seat tiers are Anthropic-managed, you see only the managed view, with no spend figures, credit panel, or burndown chart. ## Credits (self-managed view only) The credit panel and burndown chart only appear in the **Self-managed tiers** view, and only once credit data is available for your organization. The runway estimate within the panel only appears once there has been enough recent activity to compute a burn rate. When credit data is available, the credit panel shows the current position of the account your organization draws from as of right now. It displays the **Credits remaining** out of the total added to the account, with a progress bar marked at the 70 percent and 90 percent warning thresholds. It also shows a runway estimate that tells you roughly how many days remain at your trailing 7-day burn rate. A **Low balance** badge appears once 70 percent of the total has been used, and a **Depleted** badge replaces it when no credits remain. The runway figure divides your remaining balance by your average daily spend over the last seven complete days. It is shown as "less than 1 day" when the balance is nearly exhausted and as "more than 180 days" when spend is low enough that a longer projection would not be meaningful. If there has been no spend at all in the last seven days, no runway is shown. Below the panel, the **Credit burndown** chart plots your balance, with markers on the days credits were added, and projects forward to the date you are estimated to reach \$0. The chart reaches back 30 days, or 90 days when you set the time-window selector described below to **90 days**. The credit panel always reflects the current position and is not affected by the time-window selector. The 7-day lookback used for the burn rate is also fixed and does not change when you switch the usage window. ## Active users The **Active users** section shows how many distinct people used Claude over fixed periods: the average number of daily active users over the last 7 days, the number of weekly active users over the last 7 days, and the number of monthly active users over the last 30 days. These figures always use the same fixed lookbacks and are not affected by the time-window selector below. ## Usage Everything below the **Usage** divider is scoped to a time window that you choose with the **24 hours**, **7 days**, **30 days**, or **90 days** selector. The summary tiles show the number of requests, the input and output token counts (a token is roughly a piece of a word, and it is the unit that Claude's usage is measured in), and, in the self-managed view, the estimated spend for the selected window. The **Token usage** chart plots input and output tokens over the window. It shows hourly data when you select the 24-hour window and daily data for the longer windows. The **Active users over time** chart plots the number of distinct users who made at least one request in each period of the window, using the same hourly or daily buckets as the token chart. The **By product** table breaks usage down by which Claude product it came from (for example, Claude Desktop or Claude Code), with the same request, token, and spend columns as the other tables. Chat and Cowork activity in Claude Desktop is counted together in a single Claude Desktop row. Code sessions in Claude Desktop run on Claude Code, so they are counted in the Claude Code row along with any use of the standalone Claude Code command-line tool. This table only appears once your deployment has recorded usage from at least one product. The **By model** table lists each model used in the window along with its request count, input tokens, output tokens, and, in the self-managed view, its spend. The **Top users** table lists the most active users in the window with the same columns, and each user's figures combine their usage across all products. The table starts with ten rows, and you can click **Show more** to reveal additional users. Up to 100 users are listed individually, and beyond that a note tells you how many more are not listed. ## CSV exports The **Download** menu at the top of the page, next to **Refresh**, saves what the page shows as CSV files. **All** downloads a ZIP archive of the current view, one CSV file per table. The other entries download one table each: **Summary**, **Usage over time**, **By product**, **By model**, and **Top users**, with **Credit burndown** and **Credit top-ups** added in the self-managed view. The menu becomes available again 30 seconds after the previous download. Exports follow the view and the time window you have selected. The credit files match the burndown chart, reaching back 30 days, or 90 days when you select the **90 days** window. In the summary file, the credit figures are the account's position at the time of the export, not spend within the window. The ZIP archive includes an `export_info.csv` file recording the export's context, including when it was made, the organization, the view, the window and its date range, and the time zone the dates are in. In the self-managed view it also records the date range the credit files cover. File names state the view, the time span, and the dates covered, and single-table files also name their table. The top users file lists every user the **Top users** table can show, whether or not you have expanded the table with **Show more**, and adds each user's ID and account status to the columns shown on screen. ## Things to know * Claude for Government does not currently offer a programmatic usage or analytics API. Usage data is available through this admin portal page. The [Compliance API](/docs/government/org-admin/compliance-api) returns governance and audit events, not usage metrics. * A user counts as **active** in the selected window if they made at least one request in it, regardless of which seat tier they were on at the time. * The **spend** column appears only in the self-managed view and is the amount debited from your billing account's balance. The managed view has no spend column because managed-tier usage is covered by the seat price rather than by credit drawdown. * To see how close each user is to their 5-hour and 7-day limits, use the **Usage** bars on the [Users](/docs/government/org-admin/users) page. The **Top users** table on this page shows how much each listed user consumed in the window, not how close they are to a limit. * If the credit panel is missing from the self-managed view, credit data for your organization's billing account is unavailable. The rest of the page will still load. * Usage that was cleared with **Reset usage limits** on the [Users](/docs/government/org-admin/users) page still appears here. The reset only clears the counter that enforces a user's limit; it does not remove the activity from analytics. # Billing Source: https://claude.com/docs/government/org-admin/billing Use this page to see the balance your organization spends from and any spend caps set on it, and to adjust your organization's seat allocation. > **Who this is for:** Organization owners who want to see the balance their organization spends from and any spend caps set on it, and manage their organization's seat allocation. Use this page to see the balance your organization spends from and any spend caps your tenant administrator has set, and to adjust your organization's seat allocation. A **billing account** is the funding pool that pays for one or more organizations in your tenant. Your organization's usage on self-managed seat tiers draws directly from this account's balance, and Anthropic adds credit to the account. Your tenant administrator can also set a **spend cap** on your organization, which limits how much it can draw from the account in a rolling 5-hour or 7-day window. The **Billing** tab appears in the navigation when the billing account is active and your own organization is active on it. If the tab is hidden, this page is still reachable from a direct link. Funding is arranged with Anthropic by your tenant administrators; contact them about credits or spend caps. ## Billing account At the top you see the billing account's available balance, or, when the balance is not shown to you, a line explaining who manages the account. The balance is shared by every organization the account funds. Below the balance, the page shows the spend caps currently set on your organization, in the form "\$X per 5 hours, \$Y per 7 days", or "No spend caps are set" if none are. These caps are set by your tenant administrator and cannot be changed here. A cap of \$0 pauses your organization's spending from the account, and a banner appears on this page saying so. When the account's balance reaches 70 percent, 90 percent, and 100 percent consumed, a spend-alert banner appears on every page of the organization admin portal and an email is sent to your organization's owners. The banner stays in place until Anthropic adds more credits to the account. Your organization's usage against the account balance is shown on the [Analytics](/docs/government/org-admin/analytics) page. ## Seats The **Seats** section shows the pool of Anthropic-managed seats funded by this account. For each tier the table shows the **Pool** total, which is the number of seats granted to the account, the **Distributed** count, which is how many of those seats have been handed out to organizations, and the **Remaining** count, which is the number still available to distribute. The seat allocation editor below only appears when the account has at least one seat tier in its pool. An editor below the table lets you set how many seats of each tier your organization holds. Enter the number you want for each tier and click **Save**. The change takes effect immediately. ### Rules for changing seat allocations The editor enforces the following rules and will refuse a save that violates any of them. * You cannot request more seats for a tier than the billing account has remaining in its pool after accounting for other organizations. * You cannot reduce a tier's seat count below the number of users currently seated on it in your organization. Move users off the tier on the [Users](/docs/government/org-admin/users) page first, then lower the count. * You can set a tier to zero seats, which removes the tier from your organization entirely, but only if no one is seated on it. * Each tier's seat count can be at most 100,000. Saving your organization's first seat allocation also gives seats to members who have no seat tier, Primary Owners first, as long as nobody holds a seat before the save. Saving any allocation also triggers a directory provisioning sync, so provisioned users who were left unassigned because their mapped tier was full are seated up to the new limit. Anyone else stays unassigned until an owner chooses a tier for them on the [Users](/docs/government/org-admin/users) page. # Compliance API Source: https://claude.com/docs/government/org-admin/compliance-api Stream your organization's audit events into a SIEM or log management system. > **Who this is for:** Organization owners, tenant administrators, and the security or compliance teams who connect Claude for Government to their agency's log management or SIEM platform. The Compliance API is a read-only HTTP endpoint that lets your security tools pull a continuous feed of audit events covering administrative activity across your organization, such as sign-ins, role changes, key creations, and seat assignments. A scheduled job can poll the endpoint and forward each event to a SIEM such as Splunk or Microsoft Sentinel. The API is available to every Claude for Government organization by default, and it is read-only, so a compromised key cannot change anything in your organization. ## Managing API keys To create and manage keys for your organization, open **Compliance API** under **Settings** in the organization admin portal. To create and manage keys that return events for every organization in your tenant, open **Compliance API keys** under **Settings** in the [tenant admin portal](/docs/government/tenant-admin/overview). Only tenant administrators can open the tenant admin portal. Both pages list only their own keys, showing each key's name, a hint with the last few characters of the key so you can tell keys apart, when the key was created, and whether it is active or revoked. To create a key, enter a name and click **Create key**. The full value is shown once, immediately after creation. Copy it somewhere safe before clicking **Done**. The full key value is shown **only once**, at creation time. If you lose it, create a new key and revoke the old one. Keys never expire on their own, so rotate them on whatever schedule your agency's policy requires. You can keep more than one key active at a time, which lets you rotate without interrupting your SIEM feed: create a new key, update your collector to use it, confirm events are still arriving, and then revoke the old key. Revoking a key takes effect immediately, and the next request made with it returns a 401. Each key is scoped to the organization or tenant it was created in. A key created in the organization admin portal returns events for that one organization only, regardless of who holds the key. A key that a tenant administrator creates in the tenant admin portal returns the events of every organization in the tenant, together with tenant-level activity such as changes to single sign-on, to the list of tenant administrators, and to tenant-wide settings. ## Calling the API Send a GET request to your Claude for Government host followed by the fixed path `/gateway-api/v1/compliance/activities`, with your key in the `x-api-key` header. The Claude for Government host is the address of your organization admin portal. If you are unsure of it, ask your Anthropic representative. ```http theme={null} GET https:///gateway-api/v1/compliance/activities?since=2026-07-01T00:00:00Z&limit=500 x-api-key: ``` ### Query parameters | Parameter | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `since` or `created_at.gte` | The earliest event time to return, as an RFC 3339 timestamp or epoch seconds. A lower bound is required on every request that does not carry a cursor. | | `until` or `created_at.lte` | The latest event time to return, in the same format. Optional. | | `after_id` | An opaque cursor that continues from where a previous page left off. Pass the `last_id` value from the previous response. | | `before_id` | An opaque cursor that pages in the other direction. Pass the `first_id` value from the previous response. Cannot be combined with `after_id`. | | `actor_ids[]` | Return only events performed by the listed actors. Repeat the parameter to pass more than one. | | `activity_types[]` | Return only events of the listed types. Repeat the parameter to pass more than one. | | `limit` | Maximum events per page, from 1 to 5000. Defaults to 100. | The exclusive bounds `created_at.gt` and `created_at.lt` are also accepted if your collector needs them. ### Response format The response is a JSON envelope containing a page of events and the cursors for the next and previous pages. ```json theme={null} { "data": [ { "id": "activity_01js0example000000000000", "type": "user.signed_in", "created_at": "2026-07-01T14:22:09.412Z", "organization_id": "org_00000000-0000-0000-0000-000000000000", "organization_uuid": "00000000-0000-0000-0000-000000000000", "actor": { "type": "user_actor", "user_id": "usr_00000000-0000-0000-0000-000000000000", "email_address": "person@agency.example.com" }, "user_id": "usr_00000000-0000-0000-0000-000000000000", "user_email": "person@agency.example.com" } ], "has_more": true, "first_id": "", "last_id": "" } ``` The `actor` object identifies who performed the action. Its `type` is one of: * `user_actor` for a person acting through the product or admin portal. * `admin_api_key_actor` for an action taken through an administrative API key. * `anthropic_actor` for an action performed by Anthropic personnel or systems on your behalf, such as initial provisioning. No individual identity is included. Each event also carries fields specific to its type, such as the role a user was changed to or the name of a key that was created. ### Identifying users When one of your own users performs an action, `actor.user_id` and `actor.email_address` name them, including on sign-in events. Actions taken by Anthropic personnel or automated systems appear as `anthropic_actor` with no individual identity, by design. On every `user.*` activity, two top-level fields identify the user the event is about, so your SIEM can map events back to people in your directory without a separate lookup. | Field | Description | | ------------ | -------------------------------------------------------------------------------- | | `user_id` | The Claude for Government user ID, in the same `usr_` format as `actor.user_id`. | | `user_email` | The user's email address at the time of the event. | The user an event is about is not always the actor. When an owner changes someone's role, the `actor` block names the owner and these fields name the user whose role changed. ```json theme={null} { "id": "activity_01js1example000000000000", "type": "user.role_changed", "created_at": "2026-07-02T09:18:33.205Z", "organization_id": "org_00000000-0000-0000-0000-000000000000", "organization_uuid": "00000000-0000-0000-0000-000000000000", "actor": { "type": "user_actor", "user_id": "usr_00000000-0000-0000-0000-000000000001", "email_address": "owner@agency.example.com" }, "user_id": "usr_00000000-0000-0000-0000-000000000002", "user_email": "person@agency.example.com", "old": "user", "new": "owner" } ``` The top-level `user_id` and `user_email` fields appear on activities recorded after they were added to the API. Earlier activities are not updated, so your collector should treat these fields as optional. ### Activity types Event types use a dotted `resource.action` naming convention. The categories emitted today include: * **Users** such as `user.created`, `user.signed_in`, `user.role_changed`, `user.deactivated`, and `user.reactivated`. * **Organizations** such as `org.created`, `org.renamed`, and `org.deactivated`. * **Credentials** such as `api_key.created` and `api_key.revoked`. * **Seats and tiers** such as `seat_allocation.set`, `seat_allocation.tier_assigned`, `seat_tier.created`, and `seat_tier.updated`. * **Configuration** such as `org_config.capabilities_set`. * **Tenant** such as `tenant.sso_configured`, `tenant.admin_added`, and `tenant.config_set`. Only keys created in the tenant admin portal return these types. New types may be added over time, so a collector should forward unfamiliar types rather than reject them. ## Connecting to your SIEM Most deployments run a small scheduled worker that polls the API on a fixed interval, forwards each event to the SIEM's HTTP ingest endpoint, and records a time watermark so the next run picks up where the last one left off. A typical run requests `since=`, forwards every event returned, and if `has_more` is true, follows `after_id=` for each further page until `has_more` is false. After all pages are drained, advance your watermark to the newest `created_at` you saw. Event `id` values are stable and unique, so your collector can deduplicate on `id` and safely retry a page or use an overlapping `since` without creating duplicate records in the SIEM. ## When the API is disabled Your tenant administrator can turn off the **Compliance API** setting on the [tenant Config page](/docs/government/tenant-admin/configuration). When that setting is off, the **Create key** button is hidden in the organization and tenant admin portals, and every call to `/gateway-api/v1/compliance/activities` returns a 400 error, including calls made with keys that were valid before the setting changed. Listing and revoking existing keys in either portal remains available even when the setting is off, so an exposed key can still be revoked. ## Things to know * The Claude for Government Compliance API is served from the Claude for Government service hostname, not from `api.anthropic.com`. Use the same host you use to reach the admin portal. * There is no separate Splunk add-on. The polling pattern described under [Connecting to your SIEM](#connecting-to-your-siem) is the reference implementation for a Splunk HTTP Event Collector job. * The desktop application's OpenTelemetry export is a separate log stream configured with **Telemetry endpoint** on the [Config](/docs/government/config/settings#telemetry-endpoint) page. It carries per-session tool and telemetry events to a collector you specify, while this API carries administrative audit events. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for what the OpenTelemetry export includes. * The Compliance API returns governance and audit events only. It does not return conversation content, files, or anything your users type into Claude. * Each organization can hold up to 50 active keys at once, and keys created in the tenant admin portal have a separate limit of 50 active keys. Revoked keys do not count toward either limit. * Events are returned newest first within each page. * `first_id` and `last_id` are opaque cursors. Pass them back exactly as received rather than constructing them yourself. * If your network enforces a [tenant restriction](/docs/government/tenant-admin/tenant-restrictions), the same restriction applies to Compliance API requests. # Config at the organization level Source: https://claude.com/docs/government/org-admin/configuration View and change the product settings that apply to everyone in your organization, and see where each effective value comes from. > **Who this is for:** Organization owners who set product behavior, such as the session timeout, Claude Desktop banner, and product availability, for everyone in their organization. Use this page to view and change the product settings that apply to everyone in your organization, and to see where each effective value comes from. The Config page works the same way at the tenant and organization levels, with the same list of settings. See [How Config works](/docs/government/config/overview) for the levels model, locks, groups, comparing across levels, and looking up one person's settings, and [Available settings](/docs/government/config/settings) for what each setting does. This page covers only what is specific to the organization level. ## What is specific to the organization level **Managed settings.** A setting that your tenant has locked shows as **Managed** and is read-only here. Any value you had previously set is ignored while the lock is in place, and it comes back into effect if the tenant later removes the lock. See [Locks](/docs/government/config/overview#locks). **Settings only the tenant can change.** [Let organizations manage their own seat tiers](/docs/government/config/settings#let-organizations-manage-their-own-seat-tiers) and [Compliance API](/docs/government/config/settings#compliance-api) are always read-only here, regardless of whether they are locked. **Inherited connectors and plugins.** Connectors and plugins the tenant has added are labeled **Inherited from your tenant** and cannot be changed from here. A connector or plugin you add with the same name takes priority over the inherited one for your members. See [The Connectors card](/docs/government/connectors/overview#the-connectors-card) and [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards). **Group settings within your organization.** A value you set for a directory group at this level applies only to people who are both a member of the group and a member of your organization, and it is the most specific level in the chain. Group priority is set by your tenant administrator and is shown here for reference; you cannot reorder it from the organization portal. See [Group-specific settings](/docs/government/config/overview#group-specific-settings). **Your own organization only.** Organization owners manage only their own organization's Config page. Tenant administrators can open any organization's Config page and act on that organization's behalf. # Organization administration Source: https://claude.com/docs/government/org-admin/overview Manage the people, seats, and settings for a single organization within your agency. > **Who this portal is for:** Organization owners. If you manage multiple organizations across your agency, see the [Tenant administration](/docs/government/tenant-admin/overview) guide instead. The organization admin portal is where you manage the people, seats, and settings for a single organization in Claude for Government. It covers the day-to-day work of administering who has access, how much they can use, and how the Claude products behave for your users. ## Key concepts Before you use the portal, it helps to understand how the pieces fit together. Your agency's deployment is a **tenant**, which is the top-level container that holds one or more **organizations**. An organization is a self-contained group of users with its own seats, settings, and usage. Most administrators work at the organization level, while tenant administrators oversee all of the organizations together and control tenant-wide resources such as single sign-on, directory provisioning, and billing accounts. Every person in an organization holds a **role**, which determines whether they can reach this portal at all, and occupies a **seat** on a **seat tier**, which determines which Claude models they can use and how much they can use them. Seat tiers come in two kinds: * **Anthropic-managed tiers** that are supplied to you as a fixed number of seats. * **Self-managed tiers** that your organization defines itself and that draw from the billing account's balance. ## Who can access it You can reach the organization admin portal if your role in the organization is **Owner** or **Primary Owner**. Users who hold the standard **User** role are redirected to their personal account page instead. > **For tenant administrators:** You can also open this portal for any organization in your tenant. When your tenant contains more than one organization, an **Acting as** selector appears at the top of every admin page so you can choose which organization you are currently managing. All the changes you make while acting as an organization apply to that organization, and the audit trail records your own identity as the actor. ## Getting around The portal header shows your organization's name, and a navigation bar below it gives you access to each admin page. If the account your organization draws from crosses a warning threshold, a banner appears just below the navigation on every page of this portal. When your organization manages the account or is the only one using it, the banner tells you the percentage of credits used. When the account is shared with other organizations and yours does not manage it, the banner instead says credits are running low and points you to your tenant administrators. The banner stays in place until more credits are added to the account, and it escalates in color and wording if usage crosses a higher threshold. Every owner sees the banner, including when the Billing tab is hidden, so that you always know when your organization is running low. > **For owners and tenant administrators:** You can reach the user view from the **Switch to user view** link in the page footer. If you are also a tenant administrator, the footer additionally offers **Switch to tenant view**. ## Pages in this portal The navigation groups the pages into three sections. **People** | Page | What it's for | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | [Users](/docs/government/org-admin/users) | Find users, change their role or seat tier, check their usage, and reset their rate limits. | | [Seats](/docs/government/org-admin/seats) | See how many seats of each tier your organization has and how many are currently in use. | | [Tiers](/docs/government/org-admin/seat-tiers) | Review the Anthropic-managed seat tiers and create your own tiers with custom model access and spend limits. | | [Group mappings](/docs/government/org-admin/provisioning) | Map directory groups to seat tiers and roles so that users added through your directory land in the right place automatically. | **Usage** | Page | What it's for | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [Analytics](/docs/government/org-admin/analytics) | Review requests, tokens, spend, top users, and credit balance over time across your organization. | | [Compliance API](/docs/government/org-admin/compliance-api) | Create and manage read-only API keys that stream your organization's audit events to a SIEM or log management system. | | [Billing](/docs/government/org-admin/billing) | See the billing account that funds your organization, its balance and any spend caps, and adjust your seat allocation. | **Settings** | Page | What it's for | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Config](/docs/government/org-admin/configuration) | Adjust product settings such as telemetry, the Claude Desktop banner, and product availability for everyone in your organization. | | [Readiness](/docs/government/org-admin/readiness) | See what is blocking users from using Claude and where each item is resolved. | The **Billing** tab only appears when the billing account is active and your own organization is active on it. If you don't see it, contact your tenant administrators about credits or spend caps. The **Group mappings** tab only appears if automatic directory provisioning has been set up for your tenant. If you don't see it, your tenant administrator has not connected a directory, and users are placed by the tenant's routing rules alone. Single sign-on and the SCIM provisioning connection are configured at the tenant level, so they are managed on the [tenant portal's Identity and access page](/docs/government/tenant-admin/identity-and-access) rather than here. ## How changes take effect Most changes you make in this portal take effect immediately. Changing a user's seat tier, updating a spend limit, or resetting a user's rate limits applies to their very next request. Group mapping changes trigger an immediate re-sync so you do not need to wait for a scheduled cycle. Settings on the [Config](/docs/government/org-admin/configuration) page that govern the Claude applications themselves, such as the Claude Desktop banner and telemetry, reach each user's application the next time it starts or the user signs in. Claude Desktop also checks for changes about every 30 minutes while it is running and prompts the user to relaunch when something has changed. # Group mappings Source: https://claude.com/docs/government/org-admin/provisioning Use this page to map the groups pushed from your identity provider to seat tiers and roles in this organization. > **Who this is for:** Organization owners who want directory groups to drive seat tiers and roles automatically. Use this page to map the groups pushed from your identity provider to seat tiers and roles in this organization. The **Group mappings** tab only appears in the navigation if automatic directory provisioning has been set up for your tenant. If you don't see the tab, your tenant administrator has not connected a directory. **SCIM** (System for Cross-domain Identity Management) is the standard protocol that identity providers such as Okta and Microsoft Entra use to push user accounts and group memberships into other applications. Once a SCIM connection is in place, your directory groups appear here and you can map each one to a **seat tier** (a named level of access that determines which Claude models and usage limits a user gets) and a **role** (which controls whether a user can access this admin portal). The SCIM connection itself, including the base URL and secret token, is set up once for the whole tenant on the [tenant portal's Identity and access page](/docs/government/tenant-admin/identity-and-access). This page only covers the group mappings for your organization. ## How provisioning works Your identity provider pushes users and groups to Claude for Government whenever something changes in your directory, and most providers also run a full sync periodically (the default interval depends on your identity provider). Each push is written to a staging area first and then applied to your real user list by a reconciliation pass. Reconciliation runs automatically whenever your identity provider pushes a change and also whenever you add, edit, or remove a mapping on this page. You do not need to trigger it manually, and you do not need to wait for a scheduled cycle after changing a mapping. ## Group to seat tier To add a mapping, choose a group and a tier and click **Add**. Existing mappings are listed with a **Remove** button. Each group can be mapped to at most one tier, and you can only select tiers that are available to this organization (either an Anthropic-managed tier you have been allocated or a self-managed tier you created on the [Tiers](/docs/government/org-admin/seat-tiers) page). The **Add** form only appears when at least one synced group is still unmapped. If no groups have appeared at all, assign groups to the Claude for Government application in your identity provider and run a provisioning sync first. ## Group to role The same mechanism can set a user's role. Map a directory group to **User** or **Owner**, and members of that group receive that role when they are provisioned. You cannot map a group to Primary Owner; that role must always be granted manually on the [Users](/docs/government/org-admin/users) page. ## How mappings are applied When a provisioned user belongs to several mapped groups, the first matching tier mapping and the first matching role mapping in a fixed order win. This order is deterministic but not one you can configure, so it is best to avoid assigning a user to overlapping mapped groups. A provisioned user who belongs to no mapped group is placed on a seat using the automatic assignment described on the [Seats](/docs/government/org-admin/seats) page and is given the standard **User** role. If a mapped tier has no free seats when a user is provisioned, the user is created but left **Unassigned** and has no model access. They will be seated automatically on the next reconciliation after seats become available, for example after you increase the allocation on the [Billing](/docs/government/org-admin/billing) page or another user is deactivated. Adding, changing, or removing a mapping triggers a full reconciliation immediately, so existing users are re-evaluated against the new mapping without waiting for your identity provider's next sync. ## Group to organization routing > **For tenant administrators:** Mapping directory groups to organizations is handled on the [tenant portal's Identity and access page](/docs/government/tenant-admin/identity-and-access) rather than here. ## Things to know * Provisioning is the source of truth while it is connected. A seat tier or role you set manually on the [Users](/docs/government/org-admin/users) page will be overwritten on the next reconciliation if the user's group mappings say otherwise. Make permanent changes in your directory instead. * Deactivating a user in your directory deactivates them in Claude for Government and releases their seat. Reactivating them in the directory reactivates them here and attempts to seat them again. * The reconciliation pass protects against removing your last administrator. It will not deactivate the organization's only active Primary Owner, and it will not deactivate the tenant's only tenant administrator, even if your directory says to. * A group mapping cannot be saved if it points at a seat tier that no longer exists, and a seat tier cannot be deleted on the [Tiers](/docs/government/org-admin/seat-tiers) page while a mapping still points at it. # Readiness Source: https://claude.com/docs/government/org-admin/readiness Use this page to see everything that is stopping people in your organization from using Claude, and where each blocker is resolved. > **Who this is for:** Organization owners who are setting up an organization for the first time, or who need to find out why their users are unable to use Claude. Use this page to see everything that is stopping people in your organization from using Claude, and where each blocker is resolved. Your organization is ready when a member can sign in, hold a seat on a tier that reaches a working model, and send a message that the organization can pay for. This page runs that check and lists each step that is complete, blocked, or waiting on someone else. You would normally work through it once when the organization is first set up and then return whenever the **Settings** menu shows a notification dot, which appears whenever anything on this page needs attention. ## How the checklist is presented Each step sits on a vertical track with a status marker. * A **green check** means the step is complete. The label is struck through and you can ignore it. * A **filled circle** marks the step you should act on next. It expands to explain why it is blocked and offers an **Open** button that takes you to the page where the fix is made. * A **clock** means the step is blocked but you are not the person who can clear it. A line underneath tells you whether it is waiting on Anthropic, on your tenant administrator, or on the owner of a shared billing account. * A **hollow circle** is a step still to come. It stays collapsed until the steps ahead of it are cleared. Below a divider is an **Optional** section. These steps do not stop anyone from using Claude, but the page surfaces them because they usually matter, and each offers its own **Open** button when there is something you can do about it. Use **Refresh** at the top right after you make a change elsewhere to see the updated state without leaving the page. ## What each check means * **Activate the tenant** appears on its own if your agency's tenant is still being provisioned by Anthropic or has been deactivated. Nobody in any organization can sign in until this clears. Only Anthropic can resolve it, so contact your Anthropic representative. * **Activate the organization** appears on its own if this organization has been deactivated. While it is inactive its members cannot sign in and none of the other checks can be cleared. Reactivation is handled by Anthropic. If the organization's billing account has also been retired, the page explains that it must be assigned a new account before it can be brought back. * **Add credits** checks that the billing account your organization draws from has enough balance to cover at least one request on the cheapest model available to it. Until it does, every message from a user on a self-managed tier is refused. Credit is added to the billing account by Anthropic, so this step shows who to contact: your tenant administrator, or the owner of the organization that manages the shared billing account. * **Raise the organization's spend cap** appears when a tenant administrator has set a spend cap on your organization that is lower than the cost of one request on the cheapest model available. Every request from a user on a self-managed tier is refused until the cap is raised or cleared. Only a tenant administrator can change caps, so this step shows **Waiting on your tenant admin**. * **Allocate seats** checks that the organization has been allocated at least one seat of any tier. This is advisory. Without an allocation you can still assign tiers to people individually, but anyone who signs in before you do lands without a seat and cannot send messages. **Open Seats** or **Open Billing** takes you to the page where allocations are set, depending on how your billing account is managed. If the shared seat pool is already fully distributed, the step instead explains that the pool needs to be raised and shows who can do that. * **Assign seat tiers to members** checks that every active member has a seat tier, because a member without one cannot use Claude. It is advisory and sits under **Optional**, since you may leave someone unassigned on purpose, but it also catches a member left without a seat by mistake, such as a Primary Owner who was added before the organization had any seats. When a seat is free, **Open Users** takes you to the [Users](/docs/government/org-admin/users) page, where a member without a seat shows **Unassigned** and you can choose a tier for them. If your organization has no seats at all yet and nobody holds one, those members are seated automatically when seats are first allocated, and the step points to the same place as **Allocate seats**. * **Assign a model to your seat tier** checks that at least one seat tier in this organization can actually reach a working model, meaning a model that is enabled, priced, and allowed by a tier whose usage limits are high enough to cover a single request. If no tier qualifies, nobody can send a message regardless of credits or seats. **Open Tiers** takes you to the [Seat tiers](/docs/government/org-admin/seat-tiers) page to add a model or raise a tier's limits. If every tier available to you is Anthropic-managed, only Anthropic can change its model list, so the step shows a waiting state. * **Enable a product** checks that at least one Claude product, such as Claude Desktop, Claude Code, or Claude for Microsoft 365, is enabled for this organization. This is advisory. With nothing enabled, direct API access still works, but no client application can start. Enable a product on the [Config](/docs/government/org-admin/configuration) page. ## Things to know * Every **Open** button goes to the page where the fix belongs. You make the change there and return here to see it reflected. * If a step you expect to clear yourself is shown as waiting on your tenant administrator, it usually means the resource it checks is managed at the tenant level. Your tenant administrator can clear it from the [tenant Readiness page](/docs/government/tenant-admin/readiness), which shows every organization's checklist in one place. * Hover the help icon next to any step's label for a one-line explanation of what the check looks for. # Seat tiers Source: https://claude.com/docs/government/org-admin/seat-tiers Use this page to see the models and spend limits attached to each tier and, when permitted, to create and edit self-managed tiers. > **Who this is for:** Organization owners who need to review the seat tiers available to their organization or define their own. Use this page to see the models and spend limits attached to each tier and, when permitted, to create and edit self-managed tiers. A **seat tier** bundles together which Claude models a user may access and how much they may spend in a given period. Every user sits on exactly one tier (or is unassigned), and the tier they hold controls their day-to-day limits. The **Tiers** page lists every tier available to your organization. ## The tier list Tiers are listed with Anthropic-managed tiers first, followed by your organization's self-managed tiers. Each entry shows the tier's name, how many users are currently on it, and the seat limit if one applies. Clicking any tier opens its detail page. ## Anthropic-managed versus self-managed tiers **Anthropic-managed tiers** are defined by Anthropic and allocated to you through your tenant's billing account. On the detail page you can see which models the tier allows, but the spend limits are not shown and you cannot change the tier's settings or delete it. These tiers are paid for as seats rather than through credit drawdown, so their per-user spend limits are an internal detail that Anthropic manages on your behalf. **Self-managed tiers** are created by your organization. They draw from the billing account your organization spends from instead of a fixed seat count, and you have full control over their name, spend limits, and allowed models. A self-managed tier may or may not have a seat limit, depending on how it was allocated; when it has no limit, you can place as many users on it as you wish and the account's balance and any spend cap set on your organization are the effective constraint. ## Creating a self-managed tier Click **New seat tier** and fill in the form. * **Name** sets what the tier is called, for example *Analyst* or *Reviewer*. Names must be unique within your organization, and cannot duplicate the name of any Anthropic-managed tier. * **Five-hour spend limit** sets the most each user on this tier can spend in any rolling 5-hour window, expressed in dollars. When a user reaches this amount, further requests are refused until the window rolls forward. Set it to zero to allow no usage at all. * **Seven-day spend limit** does the same for a rolling 7-day window. Both limits apply at the same time, so whichever is reached first stops the user. * **Allowed models** controls which Claude models users on this tier may use. If you leave it empty, users on the tier have no model access regardless of their spend limits. * **Sort order** is a number that controls the order in which a seat is automatically chosen for a newly provisioned user (lowest number is tried first). If two tiers share the same sort order they are ordered consistently, but it is clearer to give each tier a distinct value. An organization may create up to 50 self-managed tiers. The **New seat tier** button only appears if your tenant has allowed organizations to manage their own seat tiers. This permission is controlled by the **Let organizations manage their own seat tiers** setting on the tenant's Config page. If you don't see the button, ask a tenant administrator. ## Viewing and editing a tier A tier's detail page shows its current values along with an **Allowed models** section that groups the permitted models by family. The **Edit** form and **Delete** button only appear on self-managed tiers. For an Anthropic-managed tier the page is read-only. For a self-managed tier the **Edit** form lets you update any of the fields above. Changes take effect immediately for every user on the tier: if you lower the spend limit, a user who is already over the new limit will be blocked on their next request until their window rolls forward, and if you remove a model from the allowlist it becomes unavailable to every user on the tier straight away. ## Deleting a tier The **Delete** button removes a self-managed tier entirely. Deletion is permanent and cannot be undone from this portal. You can only delete a tier that nothing references. If any users are still assigned to it, any API keys are bound to it, or any group mapping on the [Group mappings](/docs/government/org-admin/provisioning) page points at it, the delete is refused with a message telling you so. Reassign or remove those references first, then delete the tier. ## Things to know * Changing a tier's **Sort order** affects where newly provisioned users land, but it does not move anyone who already has a seat. * The spend limits are per user, not per tier. Ten users on a tier with a \$20 seven-day limit can together spend up to \$200 from the billing account over seven days. * Moving a user between tiers does not reset their usage counters. A user who has spent \$15 in the current 5-hour window carries that spend with them, and it is measured against the new tier's limit on their next request. * Users choose among a tier's allowed models in the Claude Desktop model picker, described in [Models in Claude Desktop](/docs/government/desktop/models). For some models the picker also offers a **1M context window** entry, which Anthropic sets per model and which is not part of the tier. # Seats Source: https://claude.com/docs/government/org-admin/seats Use this page to check your organization's seat counts at a glance before assigning or reclaiming seats on the Users page. > **Who this is for:** Organization owners who need to see how many seats of each tier are available and how many are in use. Use this page to check your organization's seat counts at a glance before assigning or reclaiming seats on the Users page. The **Seats** page shows how many seats your organization has for each seat tier and how many of them are currently assigned to users. It is the default landing page when you open the organization admin portal. A **seat tier** is a named level of access that defines which Claude models a person can use and how much they can use them over a rolling time window. Every user in your organization occupies exactly one seat, and that seat belongs to a tier (or the user is **Unassigned**, in which case they have no model access at all). ## What you see Seats are grouped into two sections based on who controls the tier. Each section below only appears when your organization has at least one tier of that kind. If you have neither, the page shows a message explaining that seats are distributed by your tenant administrators. **Anthropic-managed tiers** are defined by Anthropic and allocated to your organization from your tenant's seat pool. For each one the table shows the **Assigned** count, which is how many of your users are on that tier, alongside the **Limit**, which is the number of seats your organization has been allocated. You cannot assign more users to a tier than its limit allows. **Self-managed tiers** are tiers that your organization created itself on the [Tiers](/docs/government/org-admin/seat-tiers) page. For each one the table shows the **Assigned** count and, if a seat limit has been allocated for that tier, the **Limit**. These tiers draw from the billing account your organization spends from, so the effective constraint is usually the account's balance and any spend cap set on your organization rather than a seat count. ## How seats are assigned automatically When a new user is created in your organization, whether they arrive through single sign-on or through directory provisioning, Claude for Government tries to place them on a seat tier automatically so they can start working right away. If the user arrives through directory provisioning and belongs to a group you have mapped to a specific tier on the [Group mappings](/docs/government/org-admin/provisioning) page, that mapping takes precedence and the user is placed on the mapped tier if a seat is available. Otherwise the system walks through all of your tiers, both Anthropic-managed and self-managed, in sort order (lowest first) and places the user on the first tier that has a free seat. Self-managed tiers may or may not have a seat limit, depending on how they were allocated. A user is left **Unassigned** when every tier that has a seat allocation is full, or when your organization has not been allocated any seats yet. An unassigned user has no model access. Automatic placement happens when a user first arrives. A user who is already **Unassigned** gets a seat tier in one of these ways: * An owner chooses one for them on the [Users](/docs/government/org-admin/users) page. A tenant administrator can do the same from your organization's admin view. * Your organization receives its first seat allocation. Members without a seat tier are seated automatically from the new seats at that moment, Primary Owners first and in the same tier order as above, provided nobody in the organization already holds a seat. Anyone still without a seat tier afterwards, for example because there were more members than seats, needs an owner to choose one for them on the Users page. Later allocation changes do not repeat this, so a user you deliberately leave unassigned stays that way. * The user arrived through directory provisioning and belongs to a group that is mapped to a tier. The next sync seats them once the mapped tier has a free seat, as described on the [Group mappings](/docs/government/org-admin/provisioning) page. If you see an Anthropic-managed tier whose **Assigned** count equals its **Limit**, new users cannot land on it automatically. Either increase the allocation on the [Billing](/docs/government/org-admin/billing) page, move existing users to a different tier to free seats, or ask a tenant administrator to add seats. ## What you can do here This page is read-only. To move a user onto a different tier, use the [Users](/docs/government/org-admin/users) page. To create or edit self-managed tiers, use the [Tiers](/docs/government/org-admin/seat-tiers) page. To change how many seats of an Anthropic-managed tier your organization holds, go to the [Billing](/docs/government/org-admin/billing) page if it is available to you, or ask a tenant administrator. ## Things to know * The **Assigned** count includes only active users. When a user is deactivated, their seat is released immediately and becomes available for someone else. * Changing a tier's limit on the Billing page does not move anyone who already holds a seat. If you lower a limit, you must first move enough users off the tier so the assigned count fits within the new limit, because the system will not let you reduce an allocation below the number of people currently seated on it. * The sort order that controls automatic assignment is managed on the [Tiers](/docs/government/org-admin/seat-tiers) page. Anthropic-managed tiers have a fixed order set by Anthropic, and self-managed tiers sort wherever their sort order number places them relative to the managed ones. # Setup wizard Source: https://claude.com/docs/government/org-admin/setup-wizard Walk through the steps that get your organization ready for users after a tenant administrator creates it. > **Who this is for:** Organization owners setting up a newly created organization, or returning to finish setup later. When a tenant administrator creates your organization and names you as its primary owner, a few things still need to be in place before your team can use Claude. The setup wizard walks you through those items in order, shows you which ones are already done, and tells you when something is waiting on someone else. Until setup is complete, a banner reading **A few steps remain before your team can use Claude** appears at the top of every page in the organization admin portal. Click **Resume setup** in that banner to open the wizard. The banner goes away once everything is ready, and it reappears on its own if a required item later becomes incomplete, for example if the billing account's balance runs out or a spend cap is set too low. You don't need to finish the wizard in one sitting. Use **Continue later** on any step to return to the admin portal, and come back through the banner whenever you are ready. ## How the wizard is laid out The wizard is titled **Set up your organization** and lists five steps down the left side. Each step shows a green check once its requirement is met, and you can click any step to jump straight to it. The checks reflect the live state of your organization rather than whether you have visited the step, so a step can already be checked when you arrive and can lose its check if something changes later. At the bottom of every step, **Continue later** exits to the admin portal and **Next** moves to the following step. ## Step 1: Welcome The first step confirms which organization and tenant you are setting up and what your role is. It also explains the division of responsibility: single sign-on and provisioning are configured by your tenant administrator rather than here, so your members will appear in this organization automatically once they sign in through the tenant's identity provider. There is nothing to fill in on this step. ## Step 2: Seat tiers A seat tier sets which Claude models a group of users can access and how much they can spend in a given period. This step lists every tier available to your organization. Anthropic-managed tiers are shown first and are labeled **Managed by Anthropic**, followed by any self-managed tiers your organization has defined. Each row shows the tier name and the number of allowed models, and self-managed tiers also show their five-hour and seven-day spend limits. Click any tier to open it. An Anthropic-managed tier opens as a read-only summary, because its limits are set by Anthropic. A self-managed tier opens as an editable form where you can change the name, spend limits, and allowed models without leaving the wizard. If your tenant lets organizations manage their own tiers, an **Add seat tier** button appears below the list so you can create one here. If that button is missing, your tenant has not turned on **Let organizations manage their own seat tiers**, and only Anthropic can create or change tiers for your organization. The step is checked once at least one of your tiers has at least one model allowed. See [Seat tiers](/docs/government/org-admin/seat-tiers) for more on creating and editing tiers. ## Step 3: Seats and credits This step shows whether your organization has the seats and credits it needs. Seats are allocated by your tenant administrator, and Anthropic adds credits to the billing account your organization draws from, so this step is a status display rather than a form. It is here so you can see at a glance whether you are still waiting on someone. Two status lines are shown: * **Add credits** is complete once the billing account your organization draws from has enough balance to serve at least one request. This is funded by Anthropic through your tenant administrator, so when it is incomplete the line shows **Waiting on your tenant admin**. Use **View billing** to open the [Billing](/docs/government/org-admin/billing) page and see the current balance and any spend caps set on your organization. * **Allocate seats** is complete once your organization has been allocated at least one seat. Use **View seats** to open the [Seats](/docs/government/org-admin/seats) page and see the counts. The step is checked only when both lines are complete. If either one is still waiting, contact a tenant administrator. ## Step 4: Products These are the Claude products your members sign in to, such as Claude Desktop, Claude Code, and Claude for Microsoft 365. This step shows an on/off switch for each one. Turning a product on allows your members to sign in to that application. This step is marked **Optional** in the step list, and you can leave every product off and still complete setup. A product that is not available appears with its switch disabled and a note to contact Anthropic if you would like it enabled. You can change these switches later from the [Config](/docs/government/org-admin/configuration) page. ## Step 5: Finish The final step shows the full readiness checklist for your organization so you can confirm everything is in place. Completed items are crossed out, and any item that is still outstanding shows the reason and who it is waiting on. If anything required is still incomplete, a warning banner appears at the top of this step and the primary button reads **Continue later**. Back in the admin portal the **Resume setup** banner will stay in place until the outstanding items are resolved. Once every required item is complete, the warning goes away, the primary button changes to **Go to the Admin Console**, and your users can sign in and start using Claude. ## Things to know * The wizard makes the same changes as the matching pages in the admin portal. Creating a seat tier here is exactly the same as creating one on the Tiers page. * Checks in the step list are derived from your organization's current state, so they update whenever that state changes, even outside the wizard. * Once setup is complete the subtitle changes to **Setup complete. Revisit any step to make changes**, and you can return at any time to review or adjust what you set. # Users Source: https://claude.com/docs/government/org-admin/users Use this page to find a user, change their role or seat tier, check how close they are to their usage limits, and reset those limits when needed. > **Who this is for:** Organization owners who need to manage individual users' roles, seat tiers, and usage limits. Use this page to find a user, change their role or seat tier, check how close they are to their usage limits, and reset those limits when needed. The **Users** page lists everyone in your organization and lets you manage their access. ## Finding users Type into the search box to filter the list by name or email address. Use **Filters** to include deactivated accounts. ## What's shown for each user Each user appears as a card with their name, email address, and the following fields: | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Role** | The user's role in this organization. You can change it directly from the dropdown. | | **Seat tier** | Which seat tier the user currently occupies. You can change it directly from the dropdown. | | **Usage** | Two bars showing how much of the user's 5-hour and 7-day spend limits are currently used, with the exact percentage alongside each. Hover over the bars to see when each limit resets. Users who have no seat tier show a dash instead of the bars. | | **Last login** | The date and time the user last signed in. | The **…** menu on each card has the **Reset usage limits** action, which clears the user's current rate-limit windows. The menu appears only when your organization has at least one [self-managed seat tier](/docs/government/org-admin/seat-tiers). ## Understanding roles A **role** controls what a person can do in the admin portal. It has no effect on which Claude models they can use or how much they can use them; those are controlled by the seat tier. * A **User** can use the Claude products but has no admin access. * An **Owner** can access this organization admin portal and perform every action described in this guide except for granting or removing the Primary Owner role. * A **Primary Owner** has the same access as an Owner and is additionally protected so that an organization can never be left without one. Only a Primary Owner can promote another user to Primary Owner or demote an existing one. An organization must always have at least one active Primary Owner and may have up to three. Keep at least two so that when one leaves your agency or loses account access, a remaining Primary Owner can promote a replacement and demote the person who left. If your organization no longer has a Primary Owner who can sign in, contact Anthropic to have a new one appointed. A tenant administrator cannot grant the role for you, because opening your organization from the tenant portal gives them Owner access only. Until the new Primary Owner is in place, your Owners and tenant administrators can keep managing users, seats, and settings. ## Changing a user's role Use the **Role** dropdown on a user's row to move them between User, Owner, and Primary Owner. The change applies immediately, and a user who is promoted to Owner can open the admin portal as soon as they refresh. The following safeguards apply and the dropdown will refuse the change if any of them would be violated. * You cannot change your own role. To be promoted or demoted, ask another Owner or Primary Owner to make the change for you. * Only a Primary Owner can grant or remove the Primary Owner role. An Owner can freely move people between User and Owner, but any change that crosses into or out of Primary Owner must be made by a Primary Owner. * You cannot demote the organization's only active Primary Owner. Promote a second person to Primary Owner first, then demote the original. * You cannot promote a deactivated user to Primary Owner. Reactivate them first. * You cannot add a fourth Primary Owner. Demote one of the existing Primary Owners first if you need to make room. If your organization uses directory provisioning with a group-to-role mapping, be aware that the next sync will re-apply the mapped role and may overwrite a manual change you make here. To make a permanent role change for a provisioned user, update their group membership in your identity provider instead. ## Assigning a seat tier Use the **Seat tier** dropdown to move a user onto a different tier or back to **Unassigned**. An unassigned user has no model access at all, which is the appropriate state for someone who should keep their account but should not consume any Claude usage. The dropdown lists Anthropic-managed tiers first, each labeled *Managed by Anthropic*, followed by your self-managed tiers with a short summary of their model count and spend caps. If a tier has no seats remaining it appears marked **(at capacity)** and cannot be selected, unless the user is already on it. Changing a user's tier takes effect on their very next request. If you move someone to a tier with a different set of allowed models, any model that is no longer in their tier's allowlist becomes unavailable to them immediately. If your organization uses directory provisioning with a group-to-tier mapping, the next sync will re-apply the mapped tier. For provisioned users, adjust their directory group membership rather than changing the tier here. ## Resetting a user's limits Every seat tier sets a rolling **5-hour** and **7-day** spend limit for each user. When a user reaches either limit, further requests are refused until the window rolls forward. If a user on a self-managed tier has hit a limit and you want them to continue working immediately, use **Reset usage limits** in the **…** menu on their card. This clears both of their current windows so their next request is admitted. The reset does not refund or alter any credits that have already been consumed, and it does not change anything shown on the [Analytics](/docs/government/org-admin/analytics) page; it only clears the per-user counter that enforces the limit. The reset button is disabled for users on Anthropic-managed tiers because those limits are set by Anthropic and are not yours to waive. Additionally, if a user moved off an Anthropic-managed tier within the last seven days, the reset button is temporarily unavailable for them and the tooltip tells you when it becomes available again. ## Deactivated users Accounts are deactivated through your directory's SCIM provisioning rather than from this page. A deactivated user cannot sign in and does not occupy a seat. Deactivating a user releases their seat immediately, and reactivating them later will attempt to place them back on a seat using the same automatic assignment logic described on the [Seats](/docs/government/org-admin/seats) page. Deactivated users keep their role, but a deactivated Primary Owner does not count toward the "at least one" rule or the limit of three. You must always have at least one *active* Primary Owner. ## Things to know * Claude for Government has exactly three organization roles: **User**, **Owner**, and **Primary Owner**. There are no additional roles such as Billing or Developer. Tenant administrator access is a separate tenant-level membership managed on the [Admins](/docs/government/tenant-admin/admins) page, not an organization role. # Claude for Government administrator guide Source: https://claude.com/docs/government/overview Set up and manage Claude for Government for your agency: how tenants, organizations, users, seats, and credits fit together. > **Who this guide is for:** Administrators who set up and manage Claude for Government for their agency. > **Find your section:** > > | If you are… | Start with | > | --------------------------- | ------------------------------------------------------------------ | > | A tenant administrator | [Tenant administration](/docs/government/tenant-admin/overview) | > | An organization owner | [Organization administration](/docs/government/org-admin/overview) | > | Any user | [Your account](/docs/government/account/overview) | > | Anyone using Claude Desktop | [Use Claude Desktop](/docs/government/desktop/plugins) | This guide covers the portals used to manage Claude for Government: how access, seats, and usage are organized, and who is responsible for each part. If you just want to use Claude for Government, you don't need this guide. You can simply sign in and start a conversation, and come back here when you need to manage other people's access or understand why something is configured the way it is. ## How your deployment is organized Claude for Government is organized as a three-level hierarchy: **Tenant** → **Organizations** → **Users** ### Tenant The tenant is the top level, and it represents your agency's overall deployment. There is exactly one tenant per agency, and it holds the things that are shared across everyone: your connection to your identity provider for single sign-on, automatic user provisioning (where your directory system creates and updates accounts for you), the list of verified email domains, and the pool of credits and seats issued to you by Anthropic. The tenant is managed by a short list of **tenant administrators**. They create organizations, decide how seats are divided among them and what spend caps are set, and set policies that apply across the whole agency. ### Organizations An organization is a group of users who share a pool of seats and a set of policies, with its own spend caps. You might create one organization for each bureau, office, or program, or you might run the whole agency as a single organization. Most agencies start with a single organization. You would create more when you need any of the following: * Separate billing accounts so one group's usage never draws down another group's balance. * Separate usage reporting for each bureau or program. * Different product settings, seat tiers, or access rules for different parts of your agency. Each organization has its own owners, its own members, its own seat assignments, and its own configuration. The organizations all share the tenant's single sign-on connection, so you configure identity once and every organization uses it. ### Users A user is a single person. Every user belongs to exactly one organization, and two properties control what they can do: * A user's **role** determines what they can manage. Most people have the **User** role, which means they use Claude but don't administer anything. **Owners** and **Primary Owners** manage the organization: they manage members' roles and seats, and adjust organization-level settings. * A user's **seat tier** determines how much they can use Claude. A seat tier is a named bundle of usage limits (for example, how much Claude usage a person gets in a given period). A user with no seat assigned can sign in and see their account, but they can't send messages until an owner assigns them a seat. A user never belongs to more than one organization at a time. Moving a person between organizations keeps the same account; their role and seat assignment are managed separately in the new organization. ## Billing accounts A **billing account** is where your agency's credits and seats live. Anthropic sets up one or more billing accounts with your agency, and each one holds a prepaid credit balance (a dollar amount that is drawn down as people use Claude) and a pool of seats (a fixed number of seats in each tier). Every organization is linked to exactly one billing account, and usage by that organization draws directly from the account's balance. Several organizations can share the same billing account, or each organization can have its own. Tenant administrators divide each billing account's seat pool among the organizations it funds, and can set per-organization spend caps to control how much any one organization draws from a shared balance. ## The three views The portal has three views. Which ones you can reach depends on your role, and you switch between them using the link in the page footer. | View | Who has it | What it's for | | ------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Tenant**](/docs/government/tenant-admin/overview) | Tenant administrators | Creating organizations, configuring identity and access (single sign-on, provisioning, and routing rules), distributing seats, setting spend caps, and managing who else is a tenant administrator. | | [**Organization admin**](/docs/government/org-admin/overview) | Organization owners and tenant administrators | Managing users and seats, setting usage tiers, viewing analytics, and configuring organization-level settings. | | [**Account**](/docs/government/account/overview) | Everyone | Viewing your own profile, checking your usage limits, and managing where you're signed in. | When you sign in, you land on the most relevant view for you. Organization owners land on the organization admin view, and everyone else lands on their account view. This includes tenant administrators who are not also an organization owner; they start on their account view and can use the **Switch to admin view** link in the page footer, and from there switch to the tenant view. ### A note on tenant administrators Being a tenant administrator is separate from the role you hold inside an organization. Roles (User, Owner, and Primary Owner) control what you can do within a single organization, while tenant administrator status is granted by adding someone to the tenant's **Admins** list and controls access to the settings that sit above every organization. The two are independent: an organization owner is not automatically a tenant administrator, and a tenant administrator does not automatically hold any particular role inside any organization. > **For tenant administrators:** Because the tenant sits above every organization, you can also open the organization admin view and act on behalf of any organization in the tenant, even ones you don't belong to. When the tenant has more than one organization, an organization switcher appears at the top of the admin view so you can choose which one you're managing. ## How people get access Users reach your deployment in one of two ways, both of which are configured by a tenant administrator on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page: * **Single sign-on.** The user enters their agency email address and is redirected to your identity provider (for example, Microsoft Entra, Okta, or ADFS). When they return authenticated, Claude for Government evaluates your tenant's routing rules to decide which organization they belong in. * **Directory provisioning.** If your identity provider supports SCIM, which is a standard way for directory systems to keep accounts in sync with other applications, you can connect it so that your directory pushes users and group memberships to Claude for Government automatically. Routing rules then place each provisioned user in an organization based on their group membership. Routing rules are the only way in. A new person who does not match any rule cannot sign in until a rule is added that covers them. Routing rules are also re-evaluated each time an existing member signs in, so a rule change can move someone to a different organization the next time they sign in. ## Where to go next * Read [**Tenant administration**](/docs/government/tenant-admin/overview) if you're a tenant administrator managing the overall deployment. * Read [**Organization administration**](/docs/government/org-admin/overview) if you're an owner managing a single organization. * Read [**Your account**](/docs/government/account/overview) if you want to understand your own profile, usage, and sessions. # Security and data handling Source: https://claude.com/docs/government/security/security-and-data-handling Answers for agency security review: sandbox isolation, network egress and required domains, approvals, connector credentials, telemetry, and where data is stored. > **Who this is for:** Security, compliance, and IT reviewers who are assessing Claude for Government for their agency, and administrators who need to explain the product's runtime behavior. The answers on this page cover the Claude Desktop application in Claude for Government and address the security and data-handling questions that come up most often during agency security review. Claude Desktop offers three ways to work with Claude: **Chat** for simple conversations, **Cowork** for longer tasks with a local workspace folder, and **Code** for software development. Each answer states what is specific to Claude for Government (the FedRAMP High boundary, the defaults Anthropic applies for government tenants, and the relevant admin portal control), then links to the Claude Desktop documentation for the underlying mechanism. For assurance materials such as the security architecture overview, SOC 2 report, and penetration testing summary, request access through the [Anthropic Trust Center](https://trust.anthropic.com). ## Claude Desktop The sections below cover the Claude Desktop application. For the admin portal and the Compliance API, see the [Organization administration](/docs/government/org-admin/overview) and [Tenant administration](/docs/government/tenant-admin/overview) sections. ### Sandbox and isolation In Cowork, and for the file-analysis steps in Chat, the Claude Desktop application runs shell commands and model-written code inside a dedicated local virtual machine. In Claude for Government, this sandbox is always the execution path for the code and shell commands that Claude runs in Chat and Cowork. Code sessions run on the workstation itself rather than in the virtual machine, as described under [Code in Claude Desktop](#code-in-claude-desktop). For the detailed threat model and isolation design, request the security architecture overview through the [Anthropic Trust Center](https://trust.anthropic.com). The sandbox virtual machine runs the shell commands and model-written code of Cowork sessions and of the file-analysis steps in Chat. The agent loop, built-in file tools, web fetch, and the connector client run in the Claude Desktop application on the user's device and are governed by separate controls: per-action approval prompts, administrator-set per-tool policies, and the network egress allowlist applied when each tool runs. Code sessions also run outside the virtual machine, as described under [Code in Claude Desktop](#code-in-claude-desktop). For a deeper description of the layered controls inside and outside the virtual machine, see the security architecture overview available through the [Anthropic Trust Center](https://trust.anthropic.com). Shell commands that Claude runs in the sandbox work on the folders the user has attached, a scratch area, and read-only reference material bundled by the application (such as skill and plugin directories). Shell commands cannot work on the rest of the user's files. Claude's file-read and file-write tools are limited to those same locations and to the session's own working folder, and they cannot read or write the rest of the user's files unless the user adds another folder. In Cowork, Claude can ask the user to add a specific folder during the session, and the user approves or declines that request; see [Approvals and Auto mode](#approvals-and-auto-mode). Administrators can restrict which local folders users may attach with **Allowed workspace folders** on the [Config](/docs/government/config/settings#allowed-workspace-folders) page. The desktop client then refuses folders outside that list in the workspace picker, in requests Claude makes during a session, and in Claude's file tools. See [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access) for how folder scoping is enforced. When a user attaches a local folder to a Cowork session, the entire folder is made available to that session's sandbox as a filesystem mount, so changes Claude makes are written directly to the folder on disk. A mapped network drive on Windows is an exception: Claude's host-side file tools can read, write, and search it, but shell commands in the sandbox cannot reach network shares, so a task that runs a script or build against those files must copy them to a local folder first (see [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access#network-drives-on-windows)). Files the user attaches individually to a conversation are copied or hard-linked into a per-conversation uploads directory and mounted read-only; where the filesystem hard-links, edits to the original file while the conversation is open can be visible to it. The allowed-folders setting is a policy control enforced by the desktop application. See [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access). Some attachment types, such as Excel and PowerPoint, need a conversion step that runs inside the sandbox. Enabling **Advanced file analysis in Chat** under **Product availability** on the [Config](/docs/government/config/settings#product-availability) page lets Claude run code against attachments in an offline sandbox, including that conversion. You do not need to make Cowork available to get this capability. See [Chat in Claude Desktop](/docs/third-party/claude-desktop/chat) for how Chat handles file attachments. ### Code in Claude Desktop Code sessions use Claude Code built into the desktop application and run on the user's workstation itself, not in the virtual machine. The shell commands Claude runs during a Code session execute on the workstation's own operating system under the user's own account. On macOS and Linux, those shell commands run inside an operating-system-level sandbox that the application builds from your organization's **Allowed network hosts** and **Allowed workspace folders** settings on the [Config](/docs/government/config/settings#allowed-network-hosts) page. The sandbox is in place whenever either setting restricts access, which the default configuration does. Inside the sandbox, a command can create or change files only in the session's folder, the other folders **Allowed workspace folders** permits, and temporary locations, but the sandbox does not limit which files the command reads: it can read any file on the device that the user's account can open, and by default it runs without asking the user first. A user can exempt specific commands from this sandbox in a Claude Code settings file, and an exempted command runs outside the sandbox under the permission mode the user selects for the session. On Linux, the sandbox requires the `bubblewrap` and `socat` packages, so install both on each workstation as described under [Set up Linux and WSL2](https://code.claude.com/docs/en/sandboxing#set-up-linux-and-wsl2) in the Claude Code documentation. If either package is missing, shell commands run outside the sandbox as they do on Windows. On macOS and Linux, the sandbox also blocks connections to local Unix sockets. A command that talks to a local agent through a socket, such as git signing a commit with a key held in an SSH agent or a hardware-backed key manager, cannot reach that agent from inside the sandbox. On macOS, a user who needs such a command to work can list the agent's socket path under `sandbox.network.allowUnixSockets` in their Claude Code settings file, which keeps the command inside the sandbox. Every sandboxed command in that user's Code sessions can then ask the agent to sign or authenticate, so this is appropriate only for an agent that asks the user to approve each use, for example with Touch ID, and not for an agent that signs without prompting. On Linux, the sandbox ignores `sandbox.network.allowUnixSockets` and has no exception for individual sockets. See [Sandbox settings](https://code.claude.com/docs/en/settings-reference#sandbox-settings) in the Claude Code documentation. Exempting git commands such as `git commit` with `sandbox.excludedCommands` is not a safe way around the socket restriction. A sandboxed command can still change files that git runs during a commit, such as hook scripts kept in the working tree, and an exempted `git commit` would then run that code outside the sandbox. On macOS, git also cannot reach remotes over SSH from inside the sandbox, so a user who needs to push can use an HTTPS remote whose host is on the **Allowed network hosts** list, or push from a terminal outside the Code session. In container-based Linux environments, such as cloud development workspaces, the sandbox can fail to start, and shell commands in Code sessions then fail with a `bwrap` error. To run Code sessions there, deploy Claude Code's own [managed settings file](https://code.claude.com/docs/en/managed-settings) at `/etc/claude-code/managed-settings.json`, set [`parentSettingsBehavior`](https://code.claude.com/docs/en/settings-reference#parentsettingsbehavior) to `"merge"` in it so that your organization's other settings for Code sessions stay in force, and add one of the two settings that follow. In that managed settings file, setting `sandbox.enableWeakerNestedSandbox` to `true` runs the sandbox in the [weaker mode that Claude Code documents for containers](https://code.claude.com/docs/en/settings-reference#sandbox-enableweakernestedsandbox), which keeps the network and filesystem restrictions but lets sandboxed commands see the container's other processes. Use it only where the container already provides the isolation you need. If the sandbox still cannot start with that setting, or you prefer to rely on the container's own controls alone, set `sandbox.enabled` to `false` instead. Shell commands then run directly in the container under the permission mode the user selects for the session, as they do on Windows, and the **Allowed network hosts** and **Allowed workspace folders** settings no longer confine what those commands can reach or change. On Windows, there is no operating-system-level sandbox for Code sessions. Shell commands run directly on the device under the permission mode the user selects for the session and under your agency's own endpoint and network controls. The **Allowed network hosts** and **Allowed workspace folders** settings do not confine what those commands can reach, read, or change. On every operating system, the application starts a Code session only in a folder that **Allowed workspace folders** permits when that setting is configured, and Claude's file reading and editing tools then work only inside the permitted folders. Administrators can also require a prompt on every shell command, in every permission mode, with the **Require approval for each command** sub-setting on the **Shell commands** card of the [Config](/docs/government/config/settings#tool-and-connector-cards) page. Code sessions in Claude for Government run on the local workstation only, and the environment options for Windows Subsystem for Linux (WSL) and SSH remote hosts are not available. Commands that belong to Claude Code's terminal interface, such as `/sandbox`, are not part of Code sessions in the desktop application. See [how your configuration reaches Code sessions](/docs/third-party/claude-desktop/code). If your agency also deploys Claude Code's own managed settings to the same devices, those settings take precedence over the sandbox policy described above unless they opt in to merging, as that page explains. ### Network egress, required domains, and proxies The desktop application and the sandbox honor the operating system's proxy settings, and a single allowlist controls outbound network access from Claude's tools. You manage the allowlist with the **Allowed network hosts** setting on the [Config](/docs/government/config/settings#allowed-network-hosts) page. The allowlist governs outbound network access from the shell commands and package installs of Cowork sessions, which run in the sandbox virtual machine, from the sandboxed shell commands of Code sessions on macOS and Linux (see [Code in Claude Desktop](#code-in-claude-desktop)), and from the host-side web fetch tool. It does not govern web search (which routes through the Claude for Government service) or connector traffic (covered under [Connectors](#connectors) below). When the list is empty or unset, the only hosts reachable from those tools are the Claude for Government service address and, if you have set a **Telemetry endpoint** on the [Config](/docs/government/config/settings#telemetry-endpoint) page, that collector's host, which the application adds to the allowlist automatically. Package installs and page fetches to any other host fail. The list accepts exact hostnames, wildcard patterns such as `*.example.com`, or `*` to allow all outbound traffic. See [Web search and web fetch](/docs/third-party/claude-desktop/web-tools) for the full allowlist semantics. For configuration and model inference, the application reaches the Claude for Government service hostname provided to your agency during onboarding. Sign-in happens in the user's default browser, which must reach that same hostname, the Claude for Government sign-in service (a separate host that your Anthropic representative provides), and your agency's identity provider. See the network prerequisites in [Connect Claude Desktop to Claude for Government](/docs/government/deploy-desktop/configure#before-you-begin). Claude for Government does not publish IP addresses for its service and sign-in hosts, so allow both by hostname on port 443. The [IP addresses](https://platform.claude.com/docs/en/api/ip-addresses) page in the Claude API documentation covers the Claude API, not the Claude for Government hosts. Anthropic-bound telemetry endpoints are not contacted in Claude for Government. Allow `downloads.claude.ai` for the agent helper that runs Chat, Cowork, and Code sessions and for the sandbox virtual machine image, which the app fetches at session start when it does not already have them (not required if your agency uses the offline installer variant that bundles both), and `www.claudeusercontent.com` for the artifact preview frame. For automatic application updates, the required hosts depend on how your agency distributes the client; see the network-requirements table in [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) and confirm the update hosts for your deployment before finalizing your allowlist. Yes. An agency that distributes Claude Desktop updates itself, for example to keep devices on an assessed version until the next one is approved, turns on **Block automatic updates** on the [Config](/docs/government/config/settings#block-automatic-updates) page and also blocks automatic updates in each device's managed configuration, as described under [Automatic updates](/docs/government/deploy-desktop/configure#automatic-updates). With both in place, the application neither downloads nor installs updates on its own. An agency that leaves automatic updates on can use **Restart deadline for updates** on the [Config](/docs/government/config/settings#restart-deadline-for-updates) page to set how long members may postpone the restart that installs a downloaded update. Sign-in, configuration, and model inference do not. Configuration and model inference go through the dedicated Claude for Government service hostname, and sign-in goes through that hostname, the separate Claude for Government sign-in service, and your agency's identity provider, none of which are under either domain. Blocking `*.claude.ai` and `*.anthropic.com` leaves sign-in and inference working. Blocking `*.claude.ai` also blocks `downloads.claude.ai`, which prevents Chat conversations, Cowork tasks, and Code sessions from starting on devices installed with the standard installer unless the app has already downloaded the components they need from that host. App updates often change one or both of those components, and the sandbox virtual machine that runs shell commands in Cowork and Advanced file analysis in Chat then cannot start until the app has downloaded the new versions from that host. Devices installed with the offline installer variant, which includes those components, are not affected. Automatic application updates use hosts under these domains, so an agency that blocks these domains distributes updates itself, as described under [Automatic updates](/docs/government/deploy-desktop/configure#automatic-updates). Blocking `claude.ai` does not affect sign-in or inference; neither uses any host under that domain. A personal Claude account cannot sign in to Claude for Government, and a Claude for Government account cannot sign in to `claude.ai`, so there is no shared sign-in surface to restrict. If you allow automatic application updates, keep the update hosts listed in the network-requirements table reachable. Yes. Every web page fetch is checked against your egress allowlist before the request is made, and redirects are re-checked against the allowlist on each hop. See [Web search and web fetch](/docs/third-party/claude-desktop/web-tools). Do not rely on this allowlist alone to restrict access to your private network; see **Allowed network hosts** on the [Config](/docs/government/config/settings#allowed-network-hosts) page. Yes. Both the desktop application and the sandbox honor the operating system's proxy settings, including PAC URLs, and route all outbound traffic through your proxy. TLS inspection at your proxy should work; validate this in your environment before rollout. See [Network proxy](/docs/third-party/claude-desktop/network-proxy) for details. Web search requests pass through your proxy to the Claude for Government service, and the service's onward call to the search provider originates from inside the FedRAMP High boundary. ### Approvals and Auto mode By default, Claude for Government prompts the user for connector actions, for each web search, and, in Cowork, when Claude asks to add another folder to the session. In Chat and Cowork, Claude's file tools do not write outside the attached folders and the session's working folder, as described under [Sandbox and isolation](#sandbox-and-isolation). In Cowork, shell commands run without a prompt because they run inside the sandbox virtual machine. Web page fetches run without a prompt in both Chat and Cowork and are checked against the egress allowlist described above. Administrators can require a prompt on every shell command or fetch with the **Require approval for each command** and **Require approval for each fetch** sub-settings on the [Config](/docs/government/config/settings#tool-and-connector-cards) page. In Chat on Claude Desktop versions earlier than 2.110.0, every shell command prompts regardless. The reduced-approval option in Claude for Government is Auto mode, which is off by default and can be enabled through device managed configuration (it is not a setting on the Config page). Cowork does not offer a Bypass Permissions mode. Yes. Connector actions prompt the user by default. For each connector an administrator adds, the administrator can switch individual tools on or off under **Tool policy**. A tool that is on stays available and each user approves every use. A tool that is off is blocked. Users cannot loosen these settings. Tools that are not listed in a connector's **Tool policy**, including tools the server adds later, stay under each user's control. The Microsoft 365 connector always asks for approval before write actions such as sending mail, changing calendar events, or posting Teams messages, and no Claude for Government setting removes that prompt. The **Microsoft 365** card has no per-tool setting, and the connector's read tools follow each user's own approval choices. On the built-in **Web search**, **Web fetch**, and **Shell commands** cards of the Config page, administrators can require approval for every use or turn the tool off. See [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards) and [Connectors](/docs/government/connectors/overview) for the available settings. Auto mode can be disabled by policy, but not conditionally based on which connector is attached. The Auto mode policy, delivered through device managed configuration, controls whether users see Auto mode in the Cowork and Code permission selectors, and it defaults to off in Claude for Government. You can combine that policy with per-tool policies (setting a sensitive connector's tools to **ask** or **blocked**) to achieve a similar effect. Not in Chat or Cowork. Administrators can turn the built-in **Web search**, **Web fetch**, and **Shell commands** tools on or off, or require approval on every use, but cannot allowlist individual commands within those tools. In Chat, an approval for a shell command covers that one command, with no standing approval. For analyses that take many steps, Cowork runs shell commands in the sandbox without prompting; you make Cowork available to members under **Product availability** on the [Config](/docs/government/config/settings#product-availability) page. Code sessions follow Claude Code's own permission rules, which your agency can set in a Claude Code managed-settings file. See [Code in Claude Desktop](#code-in-claude-desktop). For most tools, users who see an approval prompt can choose **Always allow**, which suppresses that prompt for them going forward. Administrators can remove that option on the Config page. Turning on the **Require approval for each search**, **Require approval for each fetch**, or **Require approval for each command** sub-setting on the **Web search**, **Web fetch**, or **Shell commands** card forces a fresh prompt on every use of that tool. A connector tool that an administrator has switched on under **Tool policy** also prompts on each use, without an **Always allow** choice. The Microsoft 365 connector's read tools keep each user's own choice, and its write actions never offer **Always allow**. The create-artifact prompt is an exception: it offers no standing approval. See [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards) and [Connectors](/docs/government/connectors/overview) for the available settings. ### Connectors In Claude for Government, connectors fall into three main categories: built-in tools (Web search, Web fetch, and Shell commands), the built-in Microsoft 365 connector, and connectors an administrator adds on the Connectors card of the [Config](/docs/government/config/settings#tool-and-connector-cards) page. Connectors are called from the desktop application, outside the sandbox. The built-in Microsoft 365 connector and administrator-added connectors call their endpoints directly from the user's device, through the system proxy where one is configured. OAuth tokens for both are stored encrypted on each user's device using operating system encryption (macOS Keychain on Mac, DPAPI on Windows). For administrator-added connectors, the bearer header entered on the Config page is delivered to each user's desktop. A plugin package can include skills, slash commands, sub-agents, and hooks, which run on the member's machine. The Config page asks the administrator to confirm trust before adding a plugin that declares components that can run code on the member's machine, for example hooks or an MCP server. When an administrator adds a plugin on the Config page, Claude Desktop can run a local MCP server that the plugin declares on the member's machine, or connect to a remote one. End users cannot add their own connectors. The **Let members add plugin marketplaces** and **Let members add their own plugins** switches on the Config page control whether end users can add plugin marketplaces or plugins of their own in Claude Desktop. Both are off by default, as described under [Member-added plugins and marketplaces](/docs/government/config/settings#member-added-plugins-and-marketplaces). A user-added plugin's skills, slash commands, sub-agents, and hooks run on that user's machine, and any connector it declares does not become available as an organization connector. Administrators distribute plugins to members on the Config page with a per-plugin choice of automatic installation or member opt-in. See [Connectors](/docs/government/connectors/overview) and the Plugins card under [Tool and connector cards](/docs/government/config/settings#tool-and-connector-cards). No. The built-in Microsoft 365 connector calls Microsoft Graph directly from the user's device; see the [Microsoft 365 connector](/docs/government/connectors/microsoft-365) page. Administrator-added connectors connect directly from the user's device to the address configured for that connector. Both pass through the system proxy where one is configured. Web search is a built-in tool rather than a connector and routes through the Claude for Government service; see [Web search and web fetch](#web-search-and-web-fetch) below. Artifacts follow the same tool settings as Claude's direct connector calls: a connector tool that an administrator has switched off is refused, and a tool that requires approval on every use never runs from an artifact without the user's approval of that call. There is no single switch to disable artifact-to-connector calls while keeping connectors available to Claude directly. ### Telemetry and logging In Claude for Government, Anthropic-bound error and usage telemetry is always disabled. The OpenTelemetry export to your own collector is a separate setting and sends data only to the endpoint you configure. No. Claude for Government does not include an inline content-inspection or DLP gate. The available inspection points are your own network proxy, which sees all endpoint traffic, and the desktop's OpenTelemetry export, which sends tool-call metadata (tool name, connector, outcome, duration, and approval status) to your collector for after-the-fact review. You set the OpenTelemetry endpoint with **Telemetry endpoint** on the [Config](/docs/government/config/settings#telemetry-endpoint) page. The **Telemetry content capture** setting on the [Config](/docs/government/config/settings#telemetry-content-capture) page adds prompt, response, and tool content to the export for the categories you select, and nothing is selected by default. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry). Chat, Cowork, and Code sessions write a local audit log to the user's disk recording tool invocations, permission decisions, and file operations; that log never leaves the device. The desktop can also export OpenTelemetry events to a collector you specify: tool name, connector, outcome, duration, and approval status are sent. Prompt text, Claude's responses, and tool inputs and results are included only for the categories you select in the **Telemetry content capture** setting on the [Config](/docs/government/config/settings#telemetry-content-capture) page. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for what the export can include. Server-side, the [Compliance API](/docs/government/org-admin/compliance-api) records identity and configuration events but never tool calls or conversation content. ### Data storage and retention In Claude for Government, conversation content stays on the user's device. If you select content categories in the **Telemetry content capture** setting on the [Config](/docs/government/config/settings#telemetry-content-capture) page, Claude Desktop also sends the selected prompt, response, and tool content to your own OpenTelemetry collector, and never to Anthropic. Model requests are proxied through the Claude for Government service to the model endpoint inside the FedRAMP High boundary, and the service records only per-request metadata, not content. No. Chat transcripts are stored on the user's workstation, and the Claude for Government service does not log request or response bodies. Inference requests pass through the service to the model endpoint but are not retained. If you select content categories in the **Telemetry content capture** setting on the [Config](/docs/government/config/settings#telemetry-content-capture) page, Claude Desktop also sends the selected content to your own OpenTelemetry collector, and never to Anthropic. See [User identity and local data](/docs/third-party/claude-desktop/data-storage) for where conversation content is stored. Conversation content lives under the owner-only application data directory (`%LOCALAPPDATA%\Claude-3p` on Windows, `~/Library/Application Support/Claude-3p` on macOS, `~/.config/Claude-3p` on Linux). Code session transcripts live in Claude Code's own folder in the user's home directory (`~/.claude/projects`). The application does not encrypt these files itself, so encryption at rest depends on the workstation's full-disk encryption, such as BitLocker, FileVault, or LUKS. The operating system encryption that protects connector credentials, described under [Connectors](#connectors), does not apply to conversation content. User-visible outputs such as artifacts are written separately to the user files directory (default `~/Claude`). See [User identity and local data](/docs/third-party/claude-desktop/data-storage) for the full list of what each location holds. No. Claude Desktop keeps conversation history in the application data directory of the operating system account in use on the device, and it does not divide that history by the Claude for Government organization or tenant the user signs in to. A user who is moved to another organization, or who signs in to a second tenant from the same operating system account, sees the same conversations and projects as before. Each operating system account's application data directory is written with owner-only permissions, so other accounts on the device cannot read it, and [Removing data](/docs/third-party/claude-desktop/data-storage#removing-data) describes how to clear it. In the folder layout that [User identity and local data](/docs/third-party/claude-desktop/data-storage) describes, Claude for Government uses a single fixed organization ID. The Claude Desktop [configuration reference](/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid) lists a `deploymentOrganizationUuid` key that separates local data by organization in other deployments. That key does not apply to Claude for Government, so leave it out of your [configuration profile](/docs/government/deploy-desktop/configure#deploy-to-your-fleet). A project in Claude for Government is stored in the application data directory on the user's own device, together with any instructions, links, and folder references the user adds to it. Files added to a project stay on the user's local disk; there is no service-side project store, and files are not vectorized or indexed. Claude reads them directly from disk on demand with its file tools. A new Cowork session in the project does not reuse what an earlier session read, so Claude reads the files it needs again. The project's [memory](/docs/third-party/claude-desktop/data-storage#memory) carries short notes between sessions, such as preferences and decisions, not the contents of the files. Content Claude reads from those files is handled like the rest of the conversation: inference requests pass through the Claude for Government service to the model endpoint but are not retained. See [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access). No. The location is fixed to the per-user application data directory, and the application avoids the roaming profile because the sandbox image cache can be large. Chat history exists only on the device that created it, so back up the application data directory through your endpoint management tools if you need to preserve it. Artifacts and project folders are separate locations on the same device; see the question above. See [User identity and local data](/docs/third-party/claude-desktop/data-storage) for the folder layout. ### Web search and web fetch Web search is operated by Anthropic inside the Claude for Government FedRAMP High boundary, and the search provider's API is the one case where traffic egresses that boundary. Before search is enabled, an administrator must acknowledge a disclosure covering this data flow when enabling the **Web search** card on the [Config](/docs/government/config/settings#tool-and-connector-cards) page. By default, users approve each query before it is sent, and Claude transforms it into a generic, de-identified search request and shows the user the exact text. Anthropic has a zero-data-retention agreement with the search provider. The [Web search and web fetch](/docs/third-party/claude-desktop/web-tools) page covers how web search is configured in other Claude Desktop deployments; the Claude for Government search path described here is specific to this deployment. Web search is built in and does not require obtaining a separate connector. An organization owner opens the [Config](/docs/government/config/settings#tool-and-connector-cards) page, finds the **Web search** card, turns it on, and acknowledges the data-flow notice. The **Require approval for each search** setting is on by default. Chat includes a web fetch tool, and every fetch is checked against the same egress allowlist that governs Cowork. With the allowlist empty or unset, a fetch to anything other than the Claude for Government service address (or, when configured, the **Telemetry endpoint** collector host) returns an error. Add hosts to **Allowed network hosts** on the [Config](/docs/government/config/settings#allowed-network-hosts) page to let Chat fetch from them, or turn off the **Web fetch** card on the same page if you prefer Claude not to see the tool. See [Web search and web fetch](/docs/third-party/claude-desktop/web-tools). ### Chat and Cowork differences Yes. Chat and Cowork share one list of projects, and users can start a Chat conversation or a Cowork session inside a project. A project in Claude for Government is stored only on the user's device. There is no service-side project store, and projects are not shared between users. A Chat conversation inside a project does not gain access to the project's folders, while Cowork sessions in a project use the same execution model as the rest of Cowork. Chat conversations in a project can read the project's [memory](/docs/third-party/claude-desktop/data-storage#memory) but cannot add to or change it. See [Data storage and retention](#data-storage-and-retention) for where project contents are stored. Yes. Artifacts are available in both Chat and Cowork. Claude creates an artifact by calling a tool when the output suits an interactive view, and the artifact opens in a side panel next to the conversation. Artifacts do not depend on the sandbox, so they remain available in Chat even when **Advanced file analysis** is disabled. In Chat and Cowork, a file that Claude creates on the user's device is in one of three places: * A folder the user attached to a Cowork task. * The working folder that each task or conversation has inside the [application data directory](#data-storage-and-retention). * For artifacts, the user files directory (default `~/Claude`). Files that Claude saves in a working folder appear in the conversation as file cards that the user can open or show in Finder or File Explorer and copy from there. Code sessions work directly in the folder the user opened, as described under [Code in Claude Desktop](#code-in-claude-desktop). In Cowork, Claude's file tools change files in an attached folder in place, so the changes appear there immediately. A user who wants results in a particular folder attaches that folder to the task and asks Claude to save the files there. Shell commands run inside the sandbox virtual machine, and on the device they can write only to the attached folders and the task's working folder. A file that a command writes anywhere else in the virtual machine, for example under `/tmp`, does not appear in any folder on the device. By design, Chat cannot save files to other folders on the device. Claude's file tools in Chat, and the analysis steps that run in the sandbox when **Advanced file analysis in Chat** is on (the default), write only to the conversation's own working folder. For work that should end up in a particular folder, the user can run it as a Cowork task with that folder attached. See [Chat in Claude Desktop](/docs/third-party/claude-desktop/chat) for what a Chat conversation can reach, and [User identity and local data](/docs/third-party/claude-desktop/data-storage) for the folder layout. ## More information Assurance materials including the security architecture overview, SOC 2 Type 2 report, and penetration testing summary are available on request through the [Anthropic Trust Center](https://trust.anthropic.com). # Admins Source: https://claude.com/docs/government/tenant-admin/admins Use this page to view, add, and remove the people who can use the tenant admin portal. > **Who this is for:** Tenant administrators who manage who else has tenant-level administrative access. Use this page to view, add, and remove the people who can use the tenant admin portal. ## How tenant admin access works **Tenant administrator** is a specific membership list, separate from any role someone holds inside an organization. Being on this list grants access to every page in the tenant admin portal: creating organizations, configuring sign-in and provisioning, writing routing rules, distributing seats, setting spend caps, and setting tenant-wide configuration. It also lets the person open any organization's admin view and act on that organization's behalf. Tenant admin membership is not tied to any organization role. Adding someone here doesn't make them an owner of any organization, and making someone an organization owner doesn't put them on this list. > **For organization owners:** Being an organization's owner does not make you a tenant administrator, and being a tenant administrator doesn't grant any particular role inside an organization. The two are independent. ## The admin list The table lists every current tenant administrator with their email and which organization they belong to. A tenant administrator doesn't have to belong to any organization; those rows show *No organization*. This is common for the initial administrator Anthropic sets up during onboarding. ## Adding a tenant administrator In the **Add admin** section, start typing a name or email address and select the person from the results, then click **Grant admin**. The change takes effect immediately; the next time that person loads the portal, the tenant admin view is available to them. The search covers organization owners across every organization in your tenant, plus any existing tenant staff who don't belong to an organization. The person must already exist in your tenant, meaning they have signed in at least once or have been provisioned through your directory. ## Removing a tenant administrator Click **Remove** next to a name to revoke their tenant admin access. The change takes effect immediately. The person keeps their account and whatever organization role they have; only the ability to open this portal is removed. You can't remove the last remaining tenant administrator. The button is disabled when only one is left. This protects your tenant from losing all administrative access. ## Things to know * Adding tenant administrators is self-service and does not require any action from Anthropic. See [Adding a tenant administrator](#adding-a-tenant-administrator) above. * You cannot remove yourself from the list. If your own access needs to be removed, ask another tenant administrator to do it. * There is no upper limit on the number of tenant administrators, but because the access is broad, keep the list as short as your operational needs allow. * If the only person on this list leaves your agency or loses account access, contact Anthropic to have a new tenant administrator appointed. # Config at the tenant level Source: https://claude.com/docs/government/tenant-admin/configuration Set tenant-wide defaults for product behavior, lock settings so organizations can't change them, and preview how a change affects each organization. > **Who this is for:** Tenant administrators who set and enforce product settings across every organization in their tenant. Use this page to set tenant-wide defaults for product behavior, lock settings so organizations can't change them, and preview how a change would affect each organization. The Config page works the same way at the tenant and organization levels, with the same list of settings. See [How Config works](/docs/government/config/overview) for the levels model, locks, groups, comparing across levels, and looking up one person's settings, and [Available settings](/docs/government/config/settings) for what each setting does. This page covers only what is specific to the tenant level. ## What is specific to the tenant level **Previewing impact across organizations.** After you change a setting here, a **Preview impact** button appears next to **Save changes**. It shows every organization with its current effective value and what it would become after your change. See [Previewing impact](/docs/government/config/overview#previewing-impact). This button does not appear at the organization level. **Two settings that only tenant administrators can change.** [Let organizations manage their own seat tiers](/docs/government/config/settings#let-organizations-manage-their-own-seat-tiers) and [Compliance API](/docs/government/config/settings#compliance-api) are always read-only for organization owners, regardless of whether they are locked. **Group priority order.** You set the priority order between directory groups on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page by dragging the groups into the order you want. Organization owners see this order for reference but cannot change it. See [When someone belongs to more than one group](/docs/government/config/overview#when-someone-belongs-to-more-than-one-group). **Managing any organization's config.** As a tenant administrator you can open any organization's Config page and act on that organization's behalf, using the scope bar above the settings list. Organization owners see only their own organization. **Resetting a tenant setting** removes only the tenant's value. Organization values are unaffected and remain in effect once your value is gone. # Billing Source: https://claude.com/docs/government/tenant-admin/credits Use this page to see each billing account's balance and to set per-organization spend caps. > **Who this is for:** Tenant administrators who monitor billing-account balances and set spend caps on organizations. Use this page to see each billing account's balance and to set spend caps that limit how much any one organization can draw from it. The **Billing** tab appears in the navigation only when credits apply to your tenant, which means at least one organization can use credits or there is a credit balance on any billing account in your tenant. If neither is true, the tab is hidden and **Seats** appears on its own in the navigation. This page is still reachable from a direct link and shows a short explanation. The tab appears automatically once Anthropic configures billing for your tenant. ## How billing works A **billing account** is a funding pool that Anthropic sets up for your tenant. It holds a dollar balance of credit, and Anthropic adds credit to the account as part of your agency's procurement. Each organization is linked to exactly one billing account, and several organizations may share the same one. Usage by any organization draws directly from its billing account's balance. Because organizations share the balance, one organization's usage can reduce what is available to the others on the same account. To control that, you can set a **spend cap** on each organization. A spend cap limits how much one organization can spend from its billing account in a rolling window. It is a policy limit, not a transfer of money. Nothing moves when you set or change a cap, and the billing account's balance is always the ultimate limit regardless of what caps are set. Spend caps apply to usage on self-managed seat tiers. Usage on Anthropic-managed seat tiers is covered by the seat price rather than drawn from the account balance, so it is not counted against a cap. ## What the page shows Billing account cards only appear once Anthropic has set up at least one billing account for your tenant. Until then, the page shows a message asking you to contact Anthropic. Each billing account appears as its own card showing: * The **available balance**, which is the credit remaining in the account. Every organization on the account draws from this one balance. * How many organizations the account funds. * A **Spend caps** section listing each organization on the account with its current caps. If every organization on an account uses only Anthropic-managed seat tiers, a banner explains that the balance and spend caps do not limit usage right now. They take effect once an organization starts using self-managed tiers. ## Setting a spend cap In a billing account's **Spend caps** section, click an organization's row to expand the editor, enter a dollar amount for the **5-hour cap**, the **7-day cap**, or both, and click **Save caps**. * Leave a cap blank for no limit on that window. The billing account's balance is still the ultimate limit. * Both caps apply at the same time. An organization's usage is refused once either cap is reached, until that window rolls forward. * Amounts can be from \$0 to \$1,000,000,000, and you can use cents. * A cap of \$0 pauses the organization. Requests billed to the account are refused until you raise or clear the cap. Changes take effect immediately. Raising or clearing a cap admits the organization's next request. Lowering a cap below the organization's current window usage refuses its next request until the window rolls forward. ## When you can't set caps If an account is **deactivated**, its organizations' requests are refused and you cannot edit caps. Contact Anthropic to move the organizations to an active account. ## Things to know * Spend caps are set by tenant administrators. Organization owners can see their own caps on their organization's Billing page, but cannot change them. * Adding credit to a billing account is arranged with Anthropic as part of your agency's procurement. There is no form on this page to add credit. * An organization that hits a spend cap does not affect other organizations on the same account. An account running out of balance affects every organization on it. # Identity and access Source: https://claude.com/docs/government/tenant-admin/identity-and-access Connect single sign-on, manage SCIM provisioning, and write the routing rules that place users into organizations. > **Who this is for:** Tenant administrators who connect the deployment to their agency's identity provider and control which organization each person belongs to. Use this page to connect single sign-on, manage the SCIM provisioning token, write the routing rules that place users into organizations, preview how a specific person would be routed, and review people who haven't been placed yet. Identity and access are configured once here and shared by every organization in your tenant. The page is laid out top to bottom in the order you'll usually work through it: connect single sign-on, optionally connect directory provisioning, then write routing rules, then use the preview and the waiting lists to confirm everyone is being placed where you expect. ## Status banners Three banners can appear at the top of the page: * **Still being provisioned** appears while Anthropic is finishing initial setup of your tenant. Sign-in is disabled for everyone until provisioning completes, but you can configure everything on this page in the meantime so that it takes effect as soon as the tenant goes live. * **No routing rules configured** appears when no routing rules exist. Until at least one rule is added, no new person can sign in. * **Last SCIM push** shows when your directory most recently pushed an update. It appears only after your directory has completed at least one sync. ## Domains Claude for Government routes users to your tenant by the domain of their email address, so at least one domain must be registered before anyone can sign in. The **Domains** section lists every domain registered to your tenant, along with whether it is verified and whether it was registered by Anthropic or by you. Domains that Anthropic registered on your behalf during onboarding are already verified. To add one yourself, enter the domain in the **Claim a domain** field and click **Claim**. You will be shown a DNS TXT record to publish on that domain; once the record is live, click **Verify now** and the domain becomes active. Until at least one domain is verified, the Single sign-on section's Connect button and the SCIM provisioning section's **Generate token** button are both unavailable, and each section shows a banner explaining why. Existing tenant administrators can still sign in by email link during this time. ## Single sign-on Every user signs in through your agency's identity provider (for example, Microsoft Entra, Okta, or ADFS). You register Claude for Government as an application in your identity provider, then enter your provider's connection details here. Once connected, sign-ins are redirected to your provider. A second sign-in from the same browser within a few minutes, such as connecting Claude Desktop right after signing in on the web, may not be redirected again. You need at least one verified domain before you can connect single sign-on. Until then, the Connect button is unavailable and a banner prompts you to verify a domain first. If single sign-on was already connected before your last domain was removed, the existing connection stays editable. The card header shows a **Connected (OIDC)**, **Connected (SAML)**, or **Not configured** badge so you can see the current state at a glance. Only one protocol is active at a time. Use the **OIDC** and **SAML** tabs to switch between the two forms; saving one replaces the other. ### Registering in your identity provider Copy the following values from the card into your identity provider when you create the application there: * **Redirect URI / ACS URL** is where your identity provider sends the user back after authentication. The same value is used whether you choose OIDC (where it's called the Redirect URI) or SAML (where it's called the Assertion Consumer Service URL). * **SP Entity ID / Audience** is the unique identifier your identity provider uses to recognize this application. Providers label this field differently; it may appear as Identifier, Entity ID, or Audience URI. For SAML, a **More values your IdP may ask for** expander below these fields lists the remaining details some providers request: the Name ID format, whether assertions and requests are signed, and the default RelayState. After you save a SAML connection, an **SP metadata URL** appears alongside these values. Most identity providers can import this address to fill in the other values automatically if you need to reconfigure. People start sign-in from Claude Desktop (**Sign in with your organization**) or from the web portal in a browser, and Claude for Government then sends them to your identity provider. Starting from the application's tile in your provider's app portal (such as Microsoft My Apps), or from a sign-in test in your provider's admin console, is not supported. ### Connecting with OIDC If your identity provider supports OpenID Connect, fill in the OIDC section: * **Client ID** is the application ID your identity provider assigned when you registered the app. * **Client secret** is the secret your identity provider generated for that application. It is stored securely and never shown again after you save. * **Authorization URL**, **Token URL**, **Issuer**, and **JWKS URL** are your identity provider's OIDC endpoints. Most providers show these on the application's overview or endpoints page, and some providers publish all four together on an OpenID Connect discovery document. ### Connecting with SAML If your identity provider uses SAML, fill in the SAML section instead: * **IdP metadata XML** is the federation metadata document for your identity provider. Download the XML file from your provider (in Microsoft Entra it's under Single sign-on → SAML → Federation Metadata XML; in ADFS it's under Endpoints) and paste the full document into the field. The metadata is read from what you paste; it is never fetched from a URL. Once SAML is active, the card shows the Entity ID and SSO URL extracted from your metadata so you can confirm the connection is pointing where you expect. ### Attribute mapping (advanced) Both the OIDC and SAML sections include an **Attribute mapping** panel that's collapsed by default. Open it if the email, first-name, or last-name fields arrive under different names than the defaults. Each field offers a short list of common names for your chosen protocol; you can pick one or type your own. For OIDC the defaults are the standard `email`, `given_name`, and `family_name` claims; for SAML the defaults cover the common attribute names most providers use. Leave a field blank to use its default. Saving a new single sign-on configuration takes effect immediately and applies to everyone, including you. Before saving, confirm you can authenticate with the new provider in another browser window so that you don't lock yourself out. ## SCIM provisioning SCIM is the standard protocol identity providers use to push users and groups to a connected service automatically, so that accounts are created, updated, and deactivated in step with your agency's directory. Connecting SCIM is optional; without it, users are created the first time they sign in. You need at least one verified domain before you can generate a SCIM token. Until then, **Generate token** is unavailable and a banner prompts you to verify a domain first. * **SCIM base URL** is the address your identity provider pushes user and group updates to. A copy button sits next to it. You'll paste this value into your identity provider's provisioning settings (Okta and Microsoft Entra call this the *Tenant URL*). ### SCIM secret token Your identity provider authenticates to the SCIM address with a bearer token that you generate here. Click **Generate token** to create one, then paste the value into your identity provider's *Secret Token* (or equivalent) field. The full token value is shown **only once**, immediately after you create it. Copy it into your identity provider before clicking Done. If you lose the value, generate a new token and revoke the old one. The token table lists every token with its created date, a short hint (the last few characters) so you can tell them apart, and a status of **Active** or **Revoked**. You can keep more than one token active at a time, which lets you rotate without an outage: generate a new token, update your identity provider to use it, confirm a sync succeeds, and then revoke the old one. Revoking a token takes effect immediately. Once a token is active and your directory completes its first sync, the provisioning-rule list and the **Synced, not routed** waiting list become available further down the page. ## Directory groups Once your identity provider has pushed groups over SCIM, they appear here with their member counts. Drag the groups into the order you want; this priority is used for group-level configuration on the [Config](/docs/government/config/overview#group-specific-settings) page. ## Routing rules A **routing rule** is an instruction of the form "if a person matches this condition, place them in this organization." Routing rules are the **only** way a new person gets into your deployment; there is no default organization and no fallback. Before any rule runs, the sign-in flow first checks that the person's email domain is one of your tenant's **verified domains** (listed in the Domains section above). An address outside your verified domains never reaches your tenant at all, regardless of what rules you've written. There are two separate rule lists, because there are two ways a person can arrive: * **Sign-in rules** run each time a person signs in through single sign-on. They apply on every sign-in, not just the first one, so changing a sign-in rule can move an existing member to a different organization the next time that person signs in. * **Provisioning rules** run when your directory creates or updates someone through SCIM. They match on synced directory groups, and changes take effect at the next directory sync. ### When rules move people Because sign-in rules run every time, a rule change has these effects on people who already exist: * If a person now matches a rule that points to a different organization, they are moved on their next sign-in. Their active sessions and API keys are revoked as part of the move, so they land cleanly in the new organization. * If a person no longer matches any rule (for example, you removed the only rule that covered them), they keep their current organization and can still sign in. The no-match refusal applies only to people who have never been placed. * If a person's account is managed by your directory (that is, it was created or linked through SCIM), sign-in rules do **not** move them. Directory-managed accounts are moved only by provisioning rules, so that your directory remains the single source of truth for where they belong. Because the Claude desktop app stores conversations on each person's own device, a move does not affect desktop chat history. When you add or edit a rule that would move people, a confirmation dialog shows how many existing members would be affected and a sample of their email addresses. Review that list before confirming. > **For organization owners:** A member being moved out of your organization by a rule change loses their seat and role in your organization. Their account itself is kept, and they are reseated in the destination organization according to its available seats. ### Sign-in rules Each sign-in rule reads as a sentence, for example *"Anyone with email domain `example.gov` → place in OEO."* A rule matches on one of the following: * An **email domain** rule matches the domain of the user's email address exactly. You choose from your tenant's verified domains; you cannot type an arbitrary domain. Subdomains are not matched automatically, so `sub.example.gov` needs its own rule if you want it routed. * An **identity provider (IdP) group** rule matches a value in the group membership list that your identity provider includes in the sign-in token. You type the exact value your provider sends, and matching is exact and case-sensitive. Rules are evaluated from top to bottom, and the first match wins. When you have more than one rule, drag the handle next to a rule (or focus the handle and press the up or down arrow key) to reorder the list. Only one rule can exist for any given condition. If you pick a domain or group that already has a rule, a message below the form shows which organization it currently routes to and asks you to remove that rule first. Each rule shows a status line with diagnostics: * **Last matched** (or **Never matched**) tells you when the rule most recently placed or moved someone. * A **matches broadly** badge marks a domain rule that sits above one or more group rules. Because it matches everyone on that domain, group rules below it can never win for those users; move it lower if that's not what you intended. * A **target deactivated** badge means the rule points at an organization that has been deactivated. The rule is skipped during evaluation. * A **stale value** badge means the condition refers to something that no longer exists, such as a domain removed from your verified list. The rule is skipped during evaluation. ### Provisioning rules (SCIM) This section only appears when SCIM is connected (you have an active SCIM token or your directory has synced groups) or when provisioning rules already exist. Provisioning rules match on **directory groups** that your identity provider has synced, and decide which organization a user is placed in when your directory provisions or updates them. You choose groups from the synced list; a group that hasn't synced yet won't appear in the picker. Provisioning rules work the same way as sign-in rules: they're an ordered list, the first match wins, and only one rule can exist per group. Because your directory re-evaluates placement on each sync, reordering or removing provisioning rules can move already-placed users at the next sync. You'll be asked to confirm before reordering. ### Adding and removing rules To add a rule, choose the match type (for sign-in rules), pick or type the value, choose the target organization, and click **Add rule**. New rules are added at the bottom of the list; reorder after adding if you need a different priority. To remove a rule, click **Remove** next to it and confirm. Removing the last sign-in rule is called out specifically: no new person can sign in until another rule is added, and existing members keep their current organization until another rule covers them. ## Preview routing Enter an email address (and, optionally, a comma-separated list of IdP groups) to see exactly how that person would be routed, without changing anything. The preview runs the same evaluation that real sign-in and provisioning use, so what you see here is what will actually happen. The result shows one panel for sign-in and a separate panel for directory provisioning. The directory provisioning panel only appears when SCIM is connected for your tenant. Each panel shows whether the person would be placed (and in which organization) or refused, and it lists every rule in order with the outcome for each: **matched**, **no match**, or **target deactivated**. If the email's domain isn't one of your tenant's verified domains, the preview explains that sign-in would never reach this tenant at all, and no rules are evaluated. Editing any rule clears the preview result automatically so you never read a verdict that's out of date. Re-run the preview after making changes. ## Unplaced users The unplaced-users lists collect people who have arrived but aren't in an organization yet. There are two kinds of entry: * **Rejected sign-ins** are people from one of your verified domains who tried to sign in but matched no rule and were turned away. Each entry shows who tried, when they last tried, how many times, and which IdP groups their sign-in token carried. These records are kept so you can see who's trying and failing to get in. * **Synced, not routed** entries are people your directory has provisioned through SCIM who don't yet match any provisioning rule. They exist in the sync but have not been placed in an organization, so they cannot sign in. The Rejected sign-ins list only appears when at least one sign-in has been turned away. The Synced, not routed list appears inside the provisioning-rules card and only when at least one provisioned user is waiting without a matching rule. For rejected sign-ins you can do the following: * Click **Test in preview** to load that person's email and recorded groups into the preview, so you can see exactly which rule would cover them before you add one. * Click **Clear** to delete the record, or **Clear all** to remove every entry. Clearing does not block the person; a fresh entry appears if they try again. For synced, not routed entries, add a provisioning rule that covers their group. They'll be placed automatically at the next directory sync; there is nothing to clear. Once a person is successfully placed (by signing in through a matching rule or by the next directory sync), their entries in these lists are cleaned up automatically. ## Things to know * Keep the DNS TXT record in place while you are using Claude for Government. * There is no local break-glass account or stored password. When single sign-on is unavailable, Primary Owners and tenant administrators can request an emailed single-use sign-in link from the sign-in page. * SCIM provisioning is configured entirely from this page, with no action needed from Anthropic. Use **Generate token** under [SCIM provisioning](#scim-provisioning) on this page to create a bearer token, then enter it along with the SCIM base URL shown there into your identity provider's provisioning settings. * If two administrators reorder the same rule list at the same time, the second save is rejected with a message that the rules changed in another session. The list refreshes so you can review the current order and try again. * A user who was previously deactivated cannot regain access by matching a rule; they are refused with a deactivated-user reason instead. * For users managed by your directory, the email address shown in Claude for Government is kept in step with your directory. The sign-in token's email is ignored for those users so that a provider that sends different values in different fields (a common quirk in Microsoft Entra) does not bounce the address back and forth. # Organizations Source: https://claude.com/docs/government/tenant-admin/organizations Use this page to see every organization in your tenant, open any organization's admin view, and create new organizations. > **Who this is for:** Tenant administrators who create and oversee the organizations within their agency's deployment. Use this page to see every organization in your tenant, open any organization's admin view, and create new organizations. ## How organizations work An **organization** is a workspace that holds a set of users, a set of seats, its own spend caps, and its own product settings. Users always belong to exactly one organization, and each organization is linked to exactly one **billing account** (the credit and seat pool that funds it). Organizations share the tenant's sign-in and provisioning setup. You configure single sign-on once on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page and every organization uses the same connection. What differs between organizations is who belongs to each one, and that is decided by the routing rules on that same page rather than here. ## The organization list Each organization appears with its name and ID. Clicking an organization's name opens its organization admin view. When you do this you are acting as an Owner of that organization and can manage its users, seats, and settings. You cannot grant or remove its [Primary Owner role](/docs/government/org-admin/users#understanding-roles), which stays with that organization's own Primary Owners. Which organization a user joins isn't controlled on this page. That's set by the routing rules on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page. ## Adding an organization Expand the **Add organization** section to create a new organization. You'll provide the following: * **Name** is what the organization will be called. Leading and trailing spaces are trimmed, and the name can be up to 256 characters. There is no uniqueness requirement, so you can create two organizations with the same name, but you generally shouldn't. * **Primary Owner email** is the email address of the person who will be the new organization's first administrator. This person becomes the Primary Owner and can immediately manage the organization's users and settings. They do **not** become a tenant administrator; tenant-level access is granted separately on the [Admins](/docs/government/tenant-admin/admins) page. * **Billing account** determines where the organization's credits and seats come from. Choose an existing billing account from the list; the new organization draws from that account's credit balance and seat pool alongside any other organizations already on it. Only billing accounts that are active and tenant-managed appear in the list. If the list is empty, your tenant has no active tenant-managed billing accounts yet. Contact Anthropic to have one set up. ### After you add an organization The new organization appears in the list immediately and you can click through to its organization admin view. A few follow-up steps are usually needed before people can use it: * Add a routing rule on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page so that the right people are placed in the new organization when they sign in or are provisioned. Until a rule targets the new organization, nobody will land there automatically. * Give it seats on the [Seats](/docs/government/tenant-admin/seats) page. A newly created organization starts with no seats distributed to it, so its Primary Owner has no seat tier and cannot use Claude yet. Saving the organization's first seats also seats the Primary Owner, and anyone else already in it without a seat tier, automatically. * If you want to limit how much the new organization can spend from its billing account, set a spend cap on it on the [Billing](/docs/government/tenant-admin/credits) page. This is optional. With no cap, the account's balance is the only limit. > **For organization owners:** Being named the Primary Owner of a new organization does **not** make you a tenant administrator. Tenant admin access is granted separately on the [Admins](/docs/government/tenant-admin/admins) page. ## Things to know * You choose an organization's first Primary Owner when you create it. After that, only that organization's Primary Owners can grant or remove the role. If an organization no longer has a Primary Owner who can sign in, for example because that person left your agency, contact Anthropic to have a new one appointed. * You cannot delete an organization from this page. If an organization is no longer needed, contact Anthropic to have it deactivated. Routing rules that target a deactivated organization stop matching, and users in a deactivated organization cannot sign in until it is reactivated or they are moved. * Organization names can be changed later from the organization's own admin view. * There is no fixed limit on the number of organizations you can create, but each one adds a row to your seat distribution and configuration surfaces, so create only as many as you need to keep administration manageable. # Tenant administration Source: https://claude.com/docs/government/tenant-admin/overview Manage the settings that apply across your whole agency: organizations, identity and sign-in, and how seats are distributed and spend caps are set. > **Who this portal is for:** Tenant administrators who manage their agency's overall Claude for Government deployment across every organization. If you manage a single organization, see the [Organization administration](/docs/government/org-admin/overview) guide instead. The tenant admin portal is where you manage the things that apply across every team using the service: identity, organization routing, seats, spend caps, and tenant-wide product settings. ## Tenants and organizations Your **tenant** is your agency's top-level account. Within your tenant you create one or more **organizations**, which are separate workspaces for different teams, bureaus, or programs. All organizations in your tenant share the same sign-in setup, so one connection to your identity provider covers everyone. What differs between organizations is who belongs to each one, how many seats each one is allocated and what spend caps are set on it, and which product settings each one can adjust for itself. Funding flows through **billing accounts**, which are credit and seat pools that Anthropic sets up with your agency. Every organization is linked to exactly one billing account, and several organizations may draw from the same one. The [Seats](/docs/government/tenant-admin/seats) page is where you divide each billing account's seat pool among its organizations, and the [Billing](/docs/government/tenant-admin/credits) page is where you see each account's balance and set per-organization spend caps. There are two admin portals: * The **tenant admin** portal (this one) is where you create organizations, connect your identity provider, decide which organization each user lands in, distribute seats and set spend caps, and set tenant-wide policy. Only tenant administrators can see it. * The **organization admin** portal is where each organization's own owners manage that organization's users, seats, and settings. As a tenant administrator, you can open any organization's admin view from the [Organizations](/docs/government/tenant-admin/organizations) page, or you can use the **Switch to org view** link at the bottom of every tenant admin page. ## Who can use this portal Only **tenant administrators** can open the tenant admin portal. Tenant administrators are a specific list of people that are managed on the [Admins](/docs/government/tenant-admin/admins) page, and this list is separate from any role someone holds inside an organization. > **For organization owners:** Owning an organization does *not* make you a tenant administrator. If you need tenant-level access, ask an existing tenant administrator to add you on the [Admins](/docs/government/tenant-admin/admins) page. Every page of this portal requires tenant administrator access. If you follow a link in this guide without tenant access, you'll be turned away with a permission error. ## Getting set up for the first time The [setup wizard](/docs/government/tenant-admin/setup-wizard) walks you through all of this step by step. If your tenant has just been created, work through the pages in this order: 1. **[Identity and access](/docs/government/tenant-admin/identity-and-access).** Connect single sign-on so that people can authenticate with their agency credentials, optionally connect SCIM provisioning so that your directory syncs users and groups automatically, and add at least one routing rule so that users are placed in an organization when they sign in. Until a rule exists, nobody else can sign in. 2. **[Seats](/docs/government/tenant-admin/seats) and [Billing](/docs/government/tenant-admin/credits).** Distribute seats from your billing account to the organizations that will use them, and optionally set spend caps. 3. **[Admins](/docs/government/tenant-admin/admins).** Add at least one more tenant administrator so that you are not the only person with tenant-level access. There is a short setup period after Anthropic first creates your tenant. During that period, a banner appears on the Identity and access page and nobody at your agency can sign in yet, including people who would normally be routed to an organization. You can still use that time to configure your single sign-on connection and routing rules, and they will start working automatically as soon as the setup period ends. ## Pages in this portal The navigation groups the pages into three sections. **Organizations and identity** * The **[Organizations](/docs/government/tenant-admin/organizations)** page lets you see every organization in your tenant, open any organization's admin view, and create new organizations. * The **[Identity and access](/docs/government/tenant-admin/identity-and-access)** page lets you connect single sign-on (using either the OIDC or SAML protocol, whichever your identity provider supports), manage the SCIM provisioning token, write the routing rules that place users into organizations, preview how a specific person would be routed, and review people who haven't been placed yet. **Seats and billing** * The **[Seats](/docs/government/tenant-admin/seats)** page lets you distribute the seats in each billing account's pool to the organizations that account funds. * The **[Billing](/docs/government/tenant-admin/credits)** page shows each billing account's balance and lets you set spend caps that limit how much each organization can draw from it. **Settings** * The **[Config](/docs/government/tenant-admin/configuration)** page lets you set product settings that apply to every organization, and optionally lock them so organizations can't override them. * The **[Admins](/docs/government/tenant-admin/admins)** page lets you manage who has access to this tenant admin portal. * The **[Readiness](/docs/government/tenant-admin/readiness)** page shows what is blocking your organizations from using Claude and where each item is resolved. * The **[Compliance API keys](/docs/government/org-admin/compliance-api)** page lets you create and revoke API keys that stream audit events for every organization in your tenant, together with tenant-level activity, to a SIEM or log management system. The [setup wizard](/docs/government/tenant-admin/setup-wizard) is not a page in this list; you reach it through the **Resume setup** banner that appears above the navigation until your tenant is fully set up. # Readiness Source: https://claude.com/docs/government/tenant-admin/readiness Use this page to see everything that is blocking your organizations from using Claude, and to find the one place where each blocker is resolved. > **Who this is for:** Tenant administrators who are setting up a deployment, or who need to find out why users in any organization are unable to use Claude. Use this page to see everything that is blocking your organizations from using Claude, and to find the one place where each blocker is resolved. A deployment is ready when a user in each organization can sign in, be placed in that organization, hold a seat, and send a message to a model. This page runs that check for the whole tenant and lists every step that is complete, blocked, or waiting on someone. You would normally work through it once during initial setup and then return whenever the **Settings** menu shows a notification dot, which appears whenever anything on this page needs attention. ## How the checklist is presented Each step sits on a vertical track with a status marker. * A **green check** means the step is complete. The label is struck through and you can ignore it. * A **filled circle** marks the step you should act on next. It expands to show why it is blocked and offers an **Open** button that takes you to the page where the fix is made. * A **clock** means the step is blocked but you are not the person who can clear it. A line underneath tells you whether it is waiting on Anthropic, on an organization owner, or on the owner of a shared billing account. * A **hollow circle** is a step still to come. It stays collapsed until the steps ahead of it are cleared. Below a divider is an **Optional** section. These items do not stop anyone from using Claude, but the page surfaces them because they usually matter, such as setting up SCIM provisioning or reviewing sign-in attempts that were turned away. Use **Refresh** at the top right after you make a change elsewhere to see the updated state without leaving the page. ## Tenant-level checks These are the items that appear in the top card. They cover the things every organization in your tenant depends on. * **Activate the tenant** appears on its own when Anthropic has not yet finished provisioning your tenant, or when the tenant has been deactivated. Nothing else can be configured until this clears, and only Anthropic can clear it, so the page shows a waiting state. * **Fund the billing account** checks that at least one billing account linked to an active organization has a positive balance. This is advisory because the blocking state is shown on each organization's own readiness check. Funding is arranged with Anthropic. * **Configure the seat pool** checks that at least one billing account has a seat pool set. This is also advisory. Until a pool is set, the [Seats](/docs/government/tenant-admin/seats) page has no seats on Anthropic-managed tiers for you to distribute. Organizations can still give their users seats on any [self-managed seat tiers](/docs/government/org-admin/seat-tiers) they create themselves. The pool is configured by Anthropic as part of your contract. * **Register a domain** is required. Claude for Government routes users to your tenant by the domain of their email address, so until at least one domain is registered nobody can start a new sign-in. Use **Open Identity and access** to go to the [Identity and access](/docs/government/tenant-admin/identity-and-access) page and add one. * **Set up SCIM provisioning** is optional. SCIM lets your directory push users and groups into Claude for Government automatically. If you plan to use it, generate a provisioning token on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page. * **Add a routing rule** is required. Routing rules decide which organization each user joins when they sign in. Until at least one rule points at an active organization, every new sign-in is turned away. Use **Open Identity and access** to add a rule. If your tenant has no active organizations yet, the button instead opens the [Organizations](/docs/government/tenant-admin/organizations) page so you can create one first. * **Review sign-in failures** is an optional summary of people who tried to sign in and were turned away. The description tells you how many need a routing rule, how many need their email domain registered, and how many conflict with an existing account. Use **Open Identity and access** to resolve them. If your tenant has a single organization, that organization's own checks (credits, spend caps, seats, seat tiers, and products) appear directly in this card below the tenant-level items, so you can work through the whole deployment from one list. ## Organizations When your tenant has more than one organization, a second card lists each one with a one-line summary: **Ready**, a named blocker with **(fix available)**, or a named blocker with who it is waiting on. The marker beside each row uses the same colors as the checklist above. Expanding a row loads that organization's full checklist inline. The steps are the same ones described on the [organization Readiness page](/docs/government/org-admin/readiness), and any buttons you click here act on that organization, not the one you are currently viewing in the organization admin portal. This lets you clear an organization's blockers without switching context. Deactivated organizations appear here with their reactivation status. An organization whose billing account is retired cannot be reactivated until the account has settled and Anthropic has assigned a new one, so those rows show a waiting state instead of a button. ## Things to know * Every **Open** button goes to the page where the fix belongs, with the right organization already selected when one applies. You make the change there and return here to see it reflected. * When a step is something only Anthropic can do, such as funding a billing account or reactivating an organization, the page shows **Waiting on Anthropic**. Contact your Anthropic representative to move it forward. * Hover the help icon next to any step's label for a one-line explanation of what the check looks for. # Seats Source: https://claude.com/docs/government/tenant-admin/seats Use this page to divide each billing account's seat pool among the organizations that account funds. > **Who this is for:** Tenant administrators who distribute purchased seats to the organizations in their deployment. Use this page to divide each billing account's seat pool among the organizations that account funds. ## How seats are organized A **seat** is what entitles one person to use Claude. Every seat belongs to a **seat tier**, which is a named level of access that determines how much a person in that seat may use (for example, different usage limits per tier). Seats live in **billing accounts**, which are the credit and seat pools Anthropic sets up with your agency. Anthropic grants each billing account a pool of seats, broken down by tier. Every organization is linked to exactly one billing account, and on this page you divide each account's pool among the organizations it funds. For each tier, the totals you hand out across those organizations can't exceed what's in the pool. Seat distribution is a two-step process. On this page you give each organization a number of seats per tier. Organization owners then assign those seats to individual people in the organization admin portal. ## What the page shows Billing account cards only appear once Anthropic has set up at least one billing account for your tenant. Until then, the page shows a message asking you to contact Anthropic. Each billing account appears as its own card, and each card contains the following: * The **seat pool** table shows each seat tier with the pool size, how many seats have been distributed across organizations, and how many remain. A negative **Remaining** number (shown in red) means the pool was reduced after seats were distributed; contact Anthropic to adjust the pool, or reduce some organizations' allocations. * The **organizations** section lists every organization funded by this account, and each one has a number field per tier showing its current allocation. ## Changing an organization's seats Edit the number fields next to an organization's name and click **Save**. Saving replaces that organization's allocation across all tiers at once. Changes take effect immediately: newly added seats are available for the organization's owners to assign right away. The save will be rejected in a few cases: * If the totals you entered across all of an account's organizations would exceed the pool for any tier, you'll see an error explaining which tier is over. * If you try to reduce a tier below the number of people (and service accounts) already seated on it in that organization, you'll see an error. Ask the organization's owners to unassign people from that tier first, then reduce the allocation. * Similarly, you cannot remove a tier from an organization entirely (by setting it to zero) while anyone is still seated on it there. ## How seats affect new users When a new person is placed in an organization (by a routing rule on the [Identity and access](/docs/government/tenant-admin/identity-and-access) page), they're automatically given a seat if one is free. Tiers are filled in a fixed order, so the first tier is filled before the next is started. If every tier the organization has is completely full, or the organization has no seats distributed to it yet, the new person is placed in the organization without a seat. They can sign in and see the portal, but cannot send messages to Claude until someone gives them a seat tier. An organization owner can do that on the organization's Users page, and so can you from the organization's admin view. The first seats you give an organization are also used for the people already in it. If nobody in the organization holds a seat when you save its first allocation, members without a seat tier are seated automatically from those seats, Primary Owners first. This covers an organization that was created with only a Primary Owner and given seats afterwards. Anyone the new seats do not cover stays without a seat tier until an owner assigns one. Later changes to an allocation do not repeat this. They add or remove free seats for new arrivals and for the organization's owners to assign, and directory-provisioned users with a group-to-tier mapping are seated from the added seats on the next sync. ## When you can't edit You'll see a note instead of the editor in a few situations: * If the billing account is **deactivated**, its seats can't be redistributed. Contact Anthropic to move its organizations to an active account. * If the account is **managed by one organization's administrators** rather than by tenant administrators, you won't be able to edit it here; the owning organization controls its own distribution. * If the account has **no seat pool yet**, contact Anthropic to set one up. ## Things to know * Reducing an organization's allocation never unassigns anyone automatically. The reduction is refused until enough people have been moved off the tier. * You can freely move seats between organizations on the same billing account by lowering one and raising another, as long as neither change violates the rules above. You may need to save the reduction first to free the pool, then save the increase. * Seat pools are set by Anthropic. If you need more seats in a tier, or a new tier added, contact Anthropic. # Tenant setup wizard Source: https://claude.com/docs/government/tenant-admin/setup-wizard Walk through the guided setup that takes a brand new tenant from first sign-in to ready for users. > **Who this is for:** Tenant administrators who have just been given access to a new Claude for Government deployment and need to get it ready for the rest of their agency. When Anthropic first hands over your tenant, only you and any other administrators invited by email can sign in. The setup wizard walks you through the handful of things that need to be in place before everyone else can use Claude: a verified email domain, a connection to your identity provider, at least one organization, seats for that organization, and a routing rule that places people in it. Until setup is complete, a **Resume setup** banner appears at the top of the tenant and organization admin pages so you can pick up where you left off. The wizard has a step list on the left and the current step on the right. Completed steps are ticked, and you can click any step in the list to jump to it. Every step has a **Continue later** link at the bottom that takes you back to the tenant admin portal; nothing is lost, and the **Resume setup** banner brings you back when you are ready. Steps marked **Optional** in the list can be skipped without blocking sign-in. ## Step 1: Welcome The first step is a read-only summary of what Anthropic has already set up for you: your tenant's name, any email domains that Anthropic verified on your behalf during provisioning, and how many organizations already exist. There is nothing to fill in here. It is simply a chance to confirm that the tenant name is what you expect before you continue. If a detail looks wrong (for example, the tenant name is misspelled), contact Anthropic before going further, because the tenant name cannot be changed from the portal. ## Step 2: Domains Claude for Government looks at the domain of a person's email address to decide which tenant they belong to, so at least one verified domain must be registered before anyone else can sign in. The table at the top of this step lists the domains already on your tenant, along with whether each one is verified and whether it was added by Anthropic or by you. If Anthropic already verified the domain you plan to use, you can move straight on to the next step. To add another domain, type it into the **Claim a domain** field and click **Claim**. You will be shown a DNS TXT record to publish on that domain. Once the record is live, click **Verify now** next to the pending claim and the domain becomes active. DNS changes can take anywhere from a few minutes to an hour to propagate, so try again shortly if verification does not succeed on the first attempt. For more detail on how domains work and how to remove one later, see the [Domains section of the Identity and access page](/docs/government/tenant-admin/identity-and-access#domains). ## Step 3: Single sign-on This step connects Claude for Government to your agency's identity provider (for example, Microsoft Entra, Okta, or ADFS) so that everyone signs in with their existing agency credentials. A **Connected** or **Not connected** badge next to the heading shows the current state. This step is unavailable until you have verified at least one domain on the previous step. A banner on this step says so, because sign-in routes people to your tenant by the domain of their email address. Setting this up is a two-way exchange: 1. Copy the values shown on this step and register a new application in your identity provider using them. **Redirect URI / ACS URL** is where your provider sends the user back after authentication (providers call it the Redirect URI for OIDC, or the Assertion Consumer Service URL for SAML). **SP Entity ID / Audience** is the identifier your provider uses to recognize this application. 2. Choose the **OIDC** or **SAML** tab to match what your provider supports, then fill in the form with the values your provider gives you for the new application. For OIDC these are the Client ID, Client secret, Authorization URL, Token URL, Issuer, and JWKS URL. For SAML this is a single IdP metadata XML document: paste the federation metadata from your provider, and the Entity ID and SSO URL are read from it and shown back to you once connected. 3. Save the form. The badge changes to **Connected** once the connection has been verified. After you save a SAML connection, an **SP metadata URL** appears with the other values; most providers can import it to fill in the values automatically if you need to reconfigure. Until single sign-on is connected, only owners who were invited directly by email can sign in. The full field reference for both protocols is on the [Identity and access](/docs/government/tenant-admin/identity-and-access#single-sign-on) page. Once single sign-on is connected, people sign in from Claude Desktop or the web portal, and Claude for Government sends them to your provider from there. Starting from the application's tile in your provider's app portal, or from a sign-in test in its admin console, is not supported. ## Step 4: Provisioning (optional) This step is optional. If your identity provider supports SCIM, which is a standard way for directory systems to push users and group memberships into other applications, you can connect it here so that accounts are created automatically rather than at first sign-in. Like single sign-on, this step is unavailable until you have verified at least one domain on Step 2. Copy the **Tenant URL** shown on this step into your identity provider's SCIM connector, then click **Generate token** and paste the token into the connector's secret token field. The token is shown only once, so copy it before closing the page. If you need to rotate it later, generate a new one and revoke the old one with the **Revoke** button. You do not have to finish the provider-side setup before moving on. Once your provider has pushed at least one group, you can come back to the Routing step (or the [Identity and access](/docs/government/tenant-admin/identity-and-access#scim-provisioning) page) and add rules that place people by group membership. ## Step 5: Organizations An organization is a workspace with its own members, its own seat allocation, its own spend caps, and its own settings. You need at least one before you can route anyone anywhere, and many agencies only ever need one. You would add more if different bureaus or programs need separate usage reporting, separate budgets, or different product settings. Any organizations that already exist are listed at the top. To create one, fill in the **Add organization** form: * **Name** is the display name shown throughout the portal. * **Primary Owner email** is the person who will manage this organization's members and seats. They will be invited by email and land in the organization admin view when they sign in. * **Billing account** is the account this organization draws from for seats and billed usage. Several organizations can share one account if they should be funded from a single budget. Click **Add** and the new organization appears in the list. You can create as many as you need now and add more later from the [Organizations](/docs/government/tenant-admin/organizations) page. ## Step 6: Seats and spend caps This step lets you give each organization seats and, optionally, a spend cap. Seats control how many people in each organization can use Claude. The table shows each organization with a seat-count field for the first seat tier. Enter the number of seats each organization should have and save. Saving an organization's first seats also seats its Primary Owner, and anyone else already in it who has no seat tier, automatically. For per-tier control, use the full [Seats](/docs/government/tenant-admin/seats) page after setup. Each organization's usage spends directly from its billing account's balance, and you can add a spend cap to limit how much any one organization can use in a rolling window. Caps are optional. If you leave them blank, the billing account's balance is the only limit. You can adjust both seats and caps later from the tenant [Seats](/docs/government/tenant-admin/seats) and [Billing](/docs/government/tenant-admin/credits) pages. ## Step 7: Routing Routing rules decide which organization a person lands in when they sign in. A new person who does not match any rule cannot sign in at all, so you need at least one rule that covers your users. A single rule that maps your main email domain to your main organization is enough to get started. Each rule reads like a sentence: a condition on the left, an arrow, and the target organization on the right. To add one, use the form at the bottom: * In the **If** field, choose **Anyone with email domain** to match on the domain of the person's email address, or **Anyone with IdP group** to match on a group claim from your identity provider. * In the second field, pick the domain or type the group name. * In the **Then place in** field, pick the organization. * Click **Add rule**. Rules run from top to bottom and the first match wins, so drag more specific rules above broader ones. Rules that match directory groups pushed over SCIM are managed on the full [Identity and access](/docs/government/tenant-admin/identity-and-access#routing-rules) page, which also has a preview tool for testing where a specific email address would land. ## Steps 8 and 9: Seat tiers and Products (single-organization tenants only) If your tenant has exactly one organization, the wizard includes two extra steps so that you can finish the organization-level setup without switching portals. You will only see these two steps in the step list if your tenant has a single organization. Tenants with more than one organization skip straight to the Finish step, and each organization's owner completes these two steps in their own [organization setup wizard](/docs/government/org-admin/setup-wizard) instead. * **Seat tiers** lists the seat tiers available to the organization. A seat tier bundles together which Claude models a user may access and how much they may spend. Anthropic-managed tiers are set up for you during provisioning; if your organization is allowed to create self-managed tiers, you can add one here. See the organization [Seat tiers](/docs/government/org-admin/seat-tiers) page for the full editor. * **Products** lets you choose which Claude products the organization's members can sign in to, for example Claude Desktop, Claude Code, and Claude for Microsoft 365. This is optional, and a product that is not available on your deployment is shown grayed out with a note to contact Anthropic. ## Final step: Finish The last step shows a live readiness checklist. Each row is something that has to be in place before people can sign in, and it is ticked or crossed out as soon as you complete it. Items under the **Optional** heading do not block sign-in. If anything required is still outstanding, a yellow banner tells you so, and the button at the bottom reads **Continue later** so you can come back. Once every required item is ticked, the button changes to **Go to tenant** and your deployment is ready. As colleagues sign in they will start appearing on each organization's Users page. There is no separate "mark complete" action. The wizard reads the live state of your tenant, so if something changes later (for example, you remove your only routing rule), the **Resume setup** banner reappears on the tenant admin pages until the checklist is satisfied again. ## Things to know * You can leave the wizard at any point using **Continue later**. Everything you have entered is saved, and the **Resume setup** banner on the tenant and organization admin pages brings you back to where you left off. * Every step in the wizard edits the same settings as the matching page in the full tenant admin portal. You can use either one, and changes made in one place show up in the other. * Steps tick automatically when the underlying condition is met. The **Provisioning** and **Products** steps are optional and never block the Finish step. * Single sign-on and at least one routing rule are the two things that actually gate sign-in for everyone else. If you only have a few minutes, do those two first and come back for the rest. # Tenant restrictions Source: https://claude.com/docs/government/tenant-admin/tenant-restrictions Restrict which Claude for Government tenants can be reached from your agency's network by having your network proxy inject an allowlist header. > **Who this is for:** IT and network administrators who operate their agency's outbound web proxy or secure web gateway and want to prevent users on that network from signing in to Claude for Government with a different agency's account. Tenant restrictions let you limit which Claude for Government tenants can be reached from your network. Your network appliance adds a header to every outbound request listing the tenants you allow, and Claude for Government refuses any request that authenticates as a tenant not on that list. This is useful when people on your network may hold accounts in more than one agency's tenant (for example, a contractor who supports several agencies) and you need to ensure that work done from your network stays within your own tenant. There is nothing to enable on the Claude for Government side. The restriction is activated entirely by the presence of the header on the request, so it takes effect the moment your proxy begins injecting it and only for traffic that passes through that proxy. ## How it works Your agency's network appliance (a forward proxy, secure web gateway, or similar device that can inspect and modify HTTPS traffic) injects an `Anthropic-Allowed-Tenant-Ids` header on every request it forwards to Claude for Government. The header value is a comma-separated list of tenant IDs. On each request, Claude for Government compares the authenticated user's tenant against the list in the header. When the header is present and the user's tenant is not on the list, the request is refused. When the header is absent, no restriction applies. The check covers every way a user can reach Claude for Government: * The web application, including the tenant and organization admin portals * The desktop application * Claude Code * The Claude for Microsoft 365 add-ins * Direct API calls * SCIM directory provisioning and the [Compliance API](/docs/government/org-admin/compliance-api) The same check applies at sign-in, so a user signing in to a tenant that is not on the list sees the refusal at the sign-in screen rather than after authentication completes. A tenant restriction can only narrow access. A user still needs valid credentials for a tenant on the list; the header never grants access to a tenant the user does not already belong to. ## Configure your network proxy Configure your appliance to do both of the following on every request to your Claude for Government domains: 1. **Remove** any `Anthropic-Allowed-Tenant-Ids` header that arrived from the client. 2. **Set** a single `Anthropic-Allowed-Tenant-Ids` header to your allowlist value. Your appliance must remove the incoming header before setting its own. If the appliance only appends, ordinary traffic still works, so the misconfiguration is not obvious. A client that supplies its own value can then reach the server with both values, which either bypasses the restriction or causes that client's requests to fail, depending on how the appliance merges the two. Most secure web gateway products have a distinct "set" or "overwrite" action that removes and replaces in one step; use that rather than "append" or "add". Apply the rule to requests for the Claude for Government domains provided to you during onboarding, as well as your agency's own custom domain if you have one. Because Claude for Government is served over HTTPS, your appliance must perform TLS inspection for these hosts so that it can add the header to the encrypted request. Requests that do not pass through your appliance (for example, from a device that is off your network) do not carry the header and are not restricted. Pair this feature with your existing controls that ensure managed devices route through the appliance. ## Header format The header name is `Anthropic-Allowed-Tenant-Ids`. Header names are not case-sensitive, so your appliance may send the name in any casing. The value is one or more tenant IDs separated by commas. A tenant ID has the form `umb_` followed by a lowercase UUID with dashes. The `umb_` prefix is optional, and whitespace around each ID is ignored. The UUID must be lowercase; an uppercase or mixed-case value is rejected as invalid. ```text theme={null} Anthropic-Allowed-Tenant-Ids: umb_00000000-0000-4000-8000-000000000000 ``` For more than one tenant, separate the IDs with commas: ```text theme={null} Anthropic-Allowed-Tenant-Ids: umb_00000000-0000-4000-8000-000000000000, umb_11111111-1111-4111-8111-111111111111 ``` ### Finding your tenant ID Anthropic provides your tenant ID during onboarding. If you do not have it on hand, contact Anthropic support and ask for the tenant ID for your deployment. ## What a blocked user sees A user who tries to sign in to a tenant that is not on your allowlist sees a refusal page titled **This account isn't permitted from this network**, with guidance to sign in with an authorized account or contact their IT administrator. A user who is already signed in when the restriction takes effect, or whose application makes a request in the background, receives an error in the product reading **Your organization restricts which accounts can be used from this network. Contact your IT administrator.** Direct API calls return HTTP 403 with the error code `tenant_restriction_violation` and the message `Access restricted by network policy. Contact your IT administrator.` The refusal does not tell the user which tenants are permitted. Keep a record of your allowlist alongside your proxy configuration so that your help desk can answer user questions without inspecting the appliance. ## How invalid headers are handled Claude for Government rejects malformed headers so that a misconfigured proxy fails visibly rather than silently allowing everything through. A request is rejected with HTTP 400 and the error code `tenant_restriction_header_invalid` when any of the following is true: * The header is present but empty, or contains only whitespace or commas. * Any value in the list is not a valid tenant ID. * The list contains more than 64 tenant IDs. * The request carries more than one `Anthropic-Allowed-Tenant-Ids` header. A request with no `Anthropic-Allowed-Tenant-Ids` header at all is not restricted. ## Verifying the configuration You can confirm the restriction is working before rolling it out broadly. To confirm a block, temporarily set the proxy's allowlist to a tenant ID you do not own (any validly formatted ID works), then sign in to your own tenant from a browser that routes through the proxy. You should see the **This account isn't permitted from this network** refusal page. A direct API request in the same configuration should return HTTP 403 with the error code `tenant_restriction_violation`. To confirm normal access, set the proxy's allowlist to your real tenant ID and repeat the request. It should succeed. To confirm the appliance is overwriting rather than appending, have the test client send its own `Anthropic-Allowed-Tenant-Ids` header with your real tenant ID while the proxy's allowlist is set to an ID you do not own. The request should still return 403 (the proxy's value wins), not 400 (two headers reached the server) or 200 (the client's value reached the server). ## Things to know * Personal Claude accounts use `claude.ai`, which is a separate host from the Claude for Government service. A personal account cannot sign in to Claude for Government, and a Claude for Government account cannot sign in to `claude.ai`. The header-based restriction on this page applies only to Claude for Government traffic; it does not govern access to `claude.ai`. # Welcome Source: https://claude.com/docs/index Connect Claude to your tools, teach it how your team works, and put it to work in Slack, on your desktop, in Microsoft 365, or through the Claude API.

All products

ConnectorsGive Claude access to your tools and data in Google Drive, GitHub, Slack, Microsoft 365, or any MCP server. Browse connectors SkillsTeach Claude how to do something your way with reusable instructions, scripts, and resources it loads when relevant. Learn about skills PluginsBundle skills, connectors, and more into shareable packages for Cowork and Claude Code. Explore plugins CoworkHand Claude a goal on your desktop and come back to completed work, from polished documents to organized files and synthesized research. Get Cowork Claude TagAdd Claude to Slack channels as a teammate your whole team can see, steer, and hand work to. Set up Claude Tag Claude ScienceRun literature reviews, data analyses, and computational workflows in a desktop research workbench. Set up Claude Science Claude for M365Use Claude inside Word, Excel, PowerPoint, and Outlook, with answers based on your organization's documents. Set up Claude for M365 Claude on third-party platformsGet the full Claude Desktop experience, including Cowork, with model inference through Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or a gateway you operate. Deploy Claude Desktop Claude for GovernmentSet up and manage Claude for your agency, with tenant, organization, seat, and credit administration. Manage Claude for Government

What's new: the Cowork changelog, the Claude Science changelog, and the Claude Desktop configuration changelog.

Which product do you need?

Start from what you're trying to do:

“I want Claude to see my files, Slack messages, calendar, or codebase” Connectorsaccess to your tools and data “I want Claude to read my Outlook mail and OneDrive files” Microsoft 365 connectoryour Microsoft 365 data in chat, not the Office apps “I want to turn a document into a slide deck” Claude for M365drafting decks, docs, and email inside the Office apps “I want Claude to do this task the way my team does it” Skillsinstructions and scripts for a task “I want to share a ready-made setup with my whole team” Pluginsbundled skills and connectors for Cowork and Claude Code “I want my whole channel to see and steer Claude’s work” Claude TagClaude in your team’s Slack “I want Claude to run through my own cloud provider” Claude on third-party platformsClaude Desktop through your cloud provider “I want to build or publish a connector” MCPbuild on the open protocol and submit to the directory “I’m using Claude Code in my terminal” Claude Code (opens in a new tab)Claude in your terminal and IDE

Create an account

2Select Continue with Google or enter your email address
3Follow the prompts to complete registration

All plans have access to the Connectors Directory. Free plans can also add one custom connector. Compare Claude plans and pricing (opens in a new tab).

Claude for Government access is set up by your agency's administrators, so you don't need to create an account. See the Claude for Government guide.

# Connectors and Skills Source: https://claude.com/docs/office-agents/connectors-and-skills Extend Claude for Excel, PowerPoint, Word, and Outlook with external context and reusable task recipes. Connectors and Skills work the same way across Claude for Excel, PowerPoint, Word, and Outlook. Both are enabled in your Claude settings. Connectors and Skills are available when you sign in with your Claude account directly. When connecting through a third-party platform such as Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, these capabilities may not be available. See the feature comparison in [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for the current status by connection mode. ## Connectors Connect external tools to give Claude context beyond what's in the file or email you have open. In any Claude for M365 add-in, click the **+** button below the chat input and select **Connectors** to see available options. Common connectors used with Claude for M365 include S\&P Global, LSEG, and Daloopa for financial data, plus any custom connectors your organization has enabled. Custom connectors can introduce security risks. Before enabling one, review [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for guidance on what to consider. ## Skills Skills you've enabled in your Claude settings are available in all Claude for M365 add-ins. Claude applies relevant Skills automatically based on what you're doing. You can also invoke a Skill directly: type `/` in the sidebar to see Skills available for the app you're in, then select one, such as `/deck-check` in PowerPoint. Skills that aren't relevant to the current app are excluded from this list. See [Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude) for details on enabling and managing Skills. ## Related See the per-app guides for setup and feature details. * [Use Claude for Excel](/docs/office-agents/excel) * [Use Claude for PowerPoint](/docs/office-agents/powerpoint) * [Use Claude for Word](/docs/office-agents/word) * [Use Claude for Outlook](/docs/office-agents/outlook) # Data storage and retention Source: https://claude.com/docs/office-agents/data-storage Where Claude for M365 stores chat history, skills, and credentials on each user's device, why reinstalling or switching add-ins keeps that data, and how long it is kept. Claude for M365 stores chat history, uploaded skills, connector registrations, and sign-in credentials on each user's own device, in the browser storage of the webview that Office provides. Anthropic holds no copy of this data, and nothing syncs between devices or browsers. A device that is rebuilt, reimaged, or handed to someone else loses this data unless you export it first. ## Every Claude add-in shares one store Users run more than one Claude add-in over time: the per-app store listings, an enterprise sideload, or a custom manifest that points the add-in at your own cloud. All of them are served from `https://pivot.claude.ai`, and browser storage is keyed to that address. They therefore read and write the same store on a given device. Separate Claude add-in installs, each with its own add-in ID, all served from pivot.claude.ai and sharing one store that holds five IndexedDB databases and local storage The reason is the ordinary web rule. Office reads the manifest, finds the `` URL, and opens it in an embedded browser. From that point the browser behaves as any browser does: it hands storage to the page's address, meaning its scheme, host, and port. The add-in's ID, version, and display name never enter the lookup, so a manifest is closer to a bookmark than to a container. Deleting a bookmark does not delete the site's cookies. Two consequences follow: * A query string is not part of an address. A third-party manifest is built for one organization and carries that organization's configuration in a query string, so no two are alike. All of them still land in the same store as every other install. * Changing the address does create a new, empty store. Serving the add-in from a different host, a different port, or over `http` instead of `https` gives it somewhere else to read and write. The previous store still exists, but nothing reads it. The table below gives the result for each change users and administrators actually make. | Change | Result | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Uninstall and reinstall the same add-in | Data intact | | Move to a different store listing, or to one published with a new ID | Data intact. A new listing means a new add-in ID, not new storage | | Move from a sideloaded manifest to a store listing, or the reverse | Data intact | | Swap the standard manifest for the custom third-party manifest, or the reverse | Storage intact, but the history list changes, because the connection mode change is an identity change. See [what chat history is keyed to](#what-chat-history-is-keyed-to) | | Run a store install and a sideloaded manifest at the same time | Shared storage. Two entries in Office, one history. Remove one to avoid confusion | | Bump the manifest version, or issue a new ID to clear an Admin Center cache | Data intact | | Serve the add-in from a different host or port, or over `http` | A new empty store | | Rebuild, reimage, or wipe the profile on the device | Data destroyed. Export first | ## What Claude for M365 stores The add-in uses five IndexedDB databases and one local storage store, all inside the signed-in user's operating system profile. The table below lists each one and what it is scoped to. | Store | Contents | Scoped to | | ------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ | | `claude-chat-history` | Conversation transcripts, titles, timestamps, and the contents of attached files | One user, one organization, one Office app | | `claude-local-skills` | Skills the user uploaded, including any templates bundled with them | The device profile, not the individual user | | `claude-mcp-gateways` | Client registrations for connectors the user has authorized | The connector's address, not the individual user | | `claude-mail-style` | Claude for Outlook only: learned writing style, draft preferences, and scratchpad | One user | | `claude-office-snipped-results` | Working scratch for long conversations, cleared at the start of every session | Nothing, transient | | Local storage | Settings, onboarding and terms flags, and the active sign-in profile | The browser profile | Conversations and the Outlook writing style guide are scoped to the individual user. Uploaded skills and connector registrations are scoped to the storage location instead, so anyone who reaches the same store shares them. The Windows and macOS sections below describe what splits a store on each platform. This only applies where people share a single operating system account. That arrangement already shares the browser profile, saved sessions, and local files between them, so the guidance is the same as for any browser-based tool: give each person their own operating system account. Claude for M365 also writes one value into the Office document itself: an opaque identifier that lets the add-in recognize the same file after a rename or a Save As. It holds no user information and no conversation content, and it travels with the file if the document is shared. ## Sign-in and credentials Every store above holds only content, with one exception. Local storage also holds the signed-in user's identity: the credential the add-in presents to the model endpoint you configured. Cloud provider sign-ins use short-lived tokens that the add-in renews automatically. A gateway token or API key that you configure yourself is held until you change it. This sits in the browser profile unencrypted, in the same way a saved web session does. The boundary protecting it is the operating system account: another account on the same machine cannot read it, and disk encryption covers the device at rest. Where the deployment signs in to a cloud provider, the credential is obtained on the device and used from the device. A gateway token or API key that you issue centrally is distributed to every user's device, so treat it as you would any other shared secret. An export of a user's add-in data contains these credentials as well as conversation text, because the export copies local storage. Treat an export folder as a secret, or delete the local storage folder from it before the export leaves the device. A rebuilt machine signs in again regardless. ## Where the data sits on Windows On Windows the store is split by signed-in Office account. Local storage is one database for the whole browser profile rather than one per address, which is the main difference from macOS. Windows layout: the webview2 folder contains one folder per signed-in Office account, each holding an IndexedDB folder named after the add-in address and a Local Storage folder shared by every address If chat history looks missing on Windows, check the signed-in Office account before anything else. Signing back in to the original account restores the history with nothing to copy or repair. ## Where the data sits on macOS On macOS the store is split by Office app instead. Each app runs in its own sandbox container, so Excel, Word, PowerPoint, and Outlook always keep separate histories, and local storage sits inside the folder for a single address. macOS layout: each Office app has its own container holding one folder per address, each with an IndexedDB SQLite file and a per-address LocalStorage SQLite file Office on the web behaves differently again. The add-in runs in a cross-origin frame, so browsers treat its storage as third-party. Tracking prevention, policies that block third-party cookies, and similar controls partition or evict it. Browsers evict third-party storage on their own schedule, so treat chat history on Office on the web as temporary. ## What chat history is keyed to Sharing a store is not the same as sharing a history list. Each conversation is stored against a user identity, an organization, and the Office app it was created in. The list shows only the conversations that match all three for the session in use. When users sign in with a Claude account, that account is the identity. In third-party platform deployments there is no Claude account, so the identity comes from the Microsoft Entra ID sign-in already present in Office, as a one-way hash of the directory object ID. Nothing about the user is stored in readable form, and the hash is not sent to Anthropic. Office builds without support for nested app authentication cannot supply the Entra ID sign-in the add-in reads. On those builds Claude for M365 falls back to a per-installation identifier. Conversations still persist on that device; they are tied to the installation rather than to the directory account. The table below gives the result for each case. | Situation | Result | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A user signs out of Claude and signs back in | The same conversations. Signing out does not change the identity | | A different person signs in to Office on that device | They see their own conversations, not the previous user's. On Office builds that fall back to a per-installation identifier, both people resolve to the same identity and share one list | | The same person opens the add-in on a second device | No conversations. Storage is per device and does not sync | | A user's organization changes, such as joining or leaving a team plan | Earlier conversations stop appearing. They remain on disk under the previous organization | | A deployment moves between a Claude account sign-in and a third-party platform, in either direction | Earlier conversations stop appearing. They remain on disk under the previous identity, and the add-in has no path to reach them | Changing connection mode is not a data loss event, because nothing is deleted, but it is an identity change and the history list follows the identity. One store derives identity differently from chat history. The Outlook writing style guide has no per-installation fallback. On Office builds where the Entra ID identity cannot be read, it falls back to a single shared key, so one learned writing style is shared by everyone using that browser profile. ## Data retention Claude for M365 bounds local storage in two ways, and users can clear it themselves at any time. | Store | Retention | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `claude-chat-history` | The 50 most recent conversations per user, per organization, per Office app. Older conversations are deleted automatically | | Any store | When the browser profile runs out of storage quota, the oldest conversations are deleted to make room | | `claude-office-snipped-results` | Cleared at the start of every session | | Everything else | Kept until the user deletes it or the browser profile is wiped | Users clear their own conversations from the add-in's settings. Under "Chat history", "Delete all" removes every saved conversation for that user in that Office app and starts a new chat. There is no expiry by age and no administrator-configurable retention window. Claude for M365 also does not inherit custom data retention settings configured for your organization. If your policy requires a retention limit on this data, the practical control is the device profile lifecycle, such as roaming-profile cleanup or reimaging, rather than a setting in the add-in. ## What leaves the device The table below covers each category and its destination, so you can scope a review to the paths that carry content off the endpoint. | Data | Where it goes | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Conversation text, attachments, and the document content Claude is asked to work with | The model endpoint your deployment is configured for. In third-party platform deployments that is your own Vertex AI, Bedrock, Azure, or gateway endpoint | | Chat history, uploaded skills, connector registrations, and the Outlook writing style guide | Nowhere. Local only, no sync, no server-side backup | | Sign-in credentials | Only to the identity provider they belong to | | Usage telemetry sent to Anthropic | Counts, durations, and error categories. Anthropic's collector is allowlist-filtered, so it excludes conversation text, document contents, file names, and the names of your connectors and their tools | | Telemetry sent to a custom OpenTelemetry collector you configure | The full audit trail, including prompt content and tool inputs and outputs. That path bypasses the allowlist filter by design. See [Audit and observability](/docs/office-agents/enterprise-readiness#audit-and-observability) | ## Export a user's data before a device is rebuilt The `claude-for-msft-365-install` plugin includes read-only export scripts for macOS and Windows. They read Office's storage and write only to the folder you name, and running them with no arguments reports what was found without copying anything. See [Deploy the add-in for your organization](/docs/office-agents/third-party-platforms#deploy-the-add-in-for-your-organization) for installation, then run `/claude-for-msft-365-install:export-data`. Export before any of the following: * A device is rebuilt, reimaged, or handed to another person. * Anyone clears the Office add-in cache on Windows. The storage sits inside the same `Wef` folder as the manifest cache, so deleting that folder destroys chat history along with the manifest. * Roaming-profile or FSLogix cleanup runs against the user's profile. * A browser policy such as `ClearBrowsingDataOnExit` is applied to the device. ## Related The pages below cover the deployment and security topics that reference this data. * [Security, admin auditability, and analytics](/docs/office-agents/enterprise-readiness) * [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) # Use dictation in Claude for M365 Source: https://claude.com/docs/office-agents/dictation Speak your prompts instead of typing them in Claude for Excel, PowerPoint, Word, and Outlook. Dictation lets you speak prompts instead of typing them. Click the microphone icon in the chat input, speak, and see your words appear in the composer in real time. Dictation requires the desktop version of Excel, PowerPoint, Word, or Outlook. It is not available in Office on the web because browser-hosted add-ins cannot access the microphone. On the web, use your operating system's built-in dictation or your Office application's dictation feature instead. Dictation is also available only for organizations using direct Claude authentication. It is not supported when Claude for M365 connects through a third-party platform such as Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for platform support details. ## Use dictation Click the microphone icon on the right side of the chat input. The placeholder changes to "Listening..." and the button highlights. Words appear in the composer as you talk. Click the microphone again to stop, or press Enter to stop and send in one step. To select a different microphone, hover over the microphone icon and click the arrow that appears. ## How it works When you start dictating, the add-in streams your audio to Anthropic's transcription service, the same infrastructure that powers dictation in the Claude apps. The transcribed text displays in real time in the composer. Nothing is transcribed on your device. Audio is streamed to Anthropic, which uses a contracted speech-to-text subprocessor to generate the transcript. Audio is not retained after transcription; only the resulting text remains in your composer. ## Why dictation is not available with third-party authentication In third-party environments, Claude for M365 does not send prompts to Anthropic directly. Spoken audio is effectively a prompt, so dictation is not offered there. Use your operating system's built-in dictation or your Office application's dictation feature instead. # Security, admin auditability, and analytics Source: https://claude.com/docs/office-agents/enterprise-readiness Security architecture diagrams, OpenTelemetry audit, usage analytics, and spend tracking for enterprise admins deploying Claude for M365. Enterprise administrators deploying Claude for Excel, PowerPoint, Word, and Outlook can review the security architecture for their chosen deployment mode and connect audit logs, usage analytics, and spend tracking to existing enterprise tooling. ## Security architecture The Trust Center publishes architecture diagrams that show how user prompts, document content, and responses flow between the Office add-ins, Claude, and your infrastructure. Review the diagram that matches your deployment mode before rollout. * **Anthropic first-party**: users sign in with their Claude accounts and requests go directly to Claude. See the [first-party architecture overview](https://trust.anthropic.com/resources?s=e3n7pvyjnxjyahmdmqujcx\&name=claude-for-excel,-powerpoint,-word:-architecture-overview-%28anthropic-first-party%29). * **Third-party platforms**: requests route through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway. The companion third-party architecture diagram is listed alongside the first-party one in the [Trust Center resources](https://trust.anthropic.com/resources?s=e3n7pvyjnxjyahmdmqujcx); filter for "Claude for Excel, PowerPoint, Word". [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) has per-mode request-flow diagrams for the [LLM gateway](/docs/office-agents/third-party-platforms#llm-gateway) and [Bedrock, Vertex AI, or Foundry direct](/docs/office-agents/third-party-platforms#bedrock-vertex-ai-or-foundry-direct) paths, plus deployment guidance. ## Audit and observability Forward Claude for M365 activity to your existing observability stack with a custom OpenTelemetry collector endpoint. When a custom collector is configured, spans are exported unfiltered to that endpoint and include the full audit trail: session identifiers, surface, tool inputs and outputs, prompt content, and document references. Treat the endpoint as containing prompt and document content when scoping access controls and retention. Only spans sent to Anthropic's own collector are allowlist-filtered to strip sensitive attributes; that path is bypassed entirely when a custom endpoint is set. The add-in exports its telemetry from each user's browser: the taskpane at `https://pivot.claude.ai` posts directly to the custom collector endpoint, so every export is a cross-origin request and the endpoint must support CORS. The endpoint must answer the `OPTIONS` preflight with `Access-Control-Allow-Origin` covering `https://pivot.claude.ai` and `Access-Control-Allow-Headers` covering `Content-Type` plus any headers you configure for the export, such as `Authorization`. It must also return the same `Access-Control-Allow-Origin` header on the `POST` response. The [CORS requirements for an LLM gateway](/docs/office-agents/third-party-platforms#cors-requirements) describe the same browser behavior in more detail. Managed OTLP ingest endpoints such as Grafana Cloud are designed for server-to-server export and generally do not answer browser CORS preflights, so the browser blocks the export before it sends any authentication header. Point the collector endpoint at an OpenTelemetry Collector that you run, configure the `cors` block on its OTLP HTTP receiver, and have the collector forward to your backend. The collector makes the authenticated call to your backend, so no credential needs to appear in the export headers, which reach every signed-in user's browser. See [Configure a custom OpenTelemetry collector](/docs/office-agents/opentelemetry) for the configuration keys, endpoint requirements, and full span reference. The usage analytics and spend tracking sections below apply when users sign in with their Claude accounts directly. When connecting through a third-party platform such as Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, usage and spend are tracked through your cloud provider's billing console and your gateway's logging instead. ## Usage analytics Pull Claude for M365 usage into your own BI or reporting pipeline through the Claude Enterprise Analytics API. The API exposes per-user, per-surface, and per-organization aggregates. See [Claude Enterprise Analytics API reference guide](https://support.claude.com/en/articles/13703965-claude-enterprise-analytics-api-reference-guide) for endpoints, request shapes, and aggregation windows. ## Spend tracking Download CSV exports of Team and Enterprise plan usage from the usage analytics dashboard in your admin console. Exports include per-seat and per-surface spend, making them suitable for chargeback and financial reconciliation. See [View usage analytics for Team and Enterprise plans](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans) for the steps to generate and download a report. ## Related The pages below cover deployment paths and plugins relevant to enterprise admins. * [Data storage and retention](/docs/office-agents/data-storage) * [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) * [Install financial services plugins for Cowork](/docs/office-agents/fsi-plugins) # Use Claude for Excel Source: https://claude.com/docs/office-agents/excel An Excel add-in that integrates Claude into your spreadsheet workflow, for Pro, Max, Team, and Enterprise plans. Claude for Excel is an add-in that brings Claude into Excel. Ask questions about open workbooks, adjust assumptions while preserving formula relationships, debug errors, and build or populate models, all without leaving Excel. Claude for Excel is generally available to Pro, Max, Team, and Enterprise plans. ## What you can do With Claude for Excel, you can: * Ask questions about your workbook and get answers with cell-level citations. * Adjust assumptions while keeping formula relationships intact. * Identify and resolve errors and their root causes. * Generate new spreadsheet models or populate existing templates. * Work across multi-tab workbooks. * Pull external context through connectors such as S\&P Global, LSEG, and Daloopa. * Apply enabled Skills automatically while you work. ## Get started with Claude for Excel ### Supported versions Claude for Excel runs on the following Excel builds. * Excel on the web * Excel on Windows with a Microsoft 365 subscription, build 16.0.13127.20296 or later * Excel on Mac, version 16.46 or later, build 21011600 or later ### Install for yourself Go to the [Claude for Microsoft 365 listing on Microsoft AppSource](https://marketplace.microsoft.com/en-us/product/office/WA200010725?tab=Overview). Select "Get it now" to install. Open Excel, activate the add-in, and sign in with your Claude account. ### Deploy to your organization Organization admins can deploy Claude for Excel through the Microsoft 365 Admin Center. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), go to Settings, Org Settings, User owned apps and services, and turn on ["Let users access the Office Store"](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-addins-in-the-admin-center). Go to Settings, Integrated apps, Add-ins. Search for "Claude for Microsoft 365" in Microsoft AppSource. Assign the add-in to your organization or to specific users or groups. Share [Microsoft's deployment guide](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins) with your team for activation steps. If your organization uses Microsoft Entra Privileged Identity Management (PIM) for admin roles, the Integrated apps page does not recognize roles activated through PIM, so deployment fails. This is a [known Microsoft issue](https://learn.microsoft.com/en-us/office/dev/add-ins/resources/resources-office-add-in-known-issues), tracking ID 11126536. To work around it, deploy from an admin account with the required role assigned as permanently active rather than PIM-eligible. See [Microsoft's troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/microsoft-365/admin/miscellaneous/cannot-deploy-add-in-integrated-apps-menu). Individual users can still [install the add-in themselves](#install-for-yourself). After deployment, users can activate the Claude add-in from Tools, Add-ins on Mac or Home, Add-ins on Windows, sign in, and start working. For environments where "Let users access the Office Store" is disabled, deploy using the custom manifest XML file instead. Download the [Excel manifest XML file](https://pivot.claude.ai/manifest-excel.xml), then follow [Deploy with a custom manifest](/docs/office-agents/word#deploy-with-a-custom-manifest) for the upload steps. The flow is identical apart from which manifest file you upload in Step 1. ### Connect through a third-party platform If your organization routes AI traffic through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, your admin can deploy the add-in without individual Claude accounts. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms). ## Key features ### Understand complex models Ask Claude to trace assumptions, explain formulas, or walk through how a number was derived. Answers include cell-level citations you can click to navigate to the referenced cell. Example prompts: * "Walk me through how the revenue number in cell C42 is calculated." * "What assumptions drive the gross margin forecast?" ### Update values safely Claude updates cell values while keeping formula relationships intact, so downstream cells recompute correctly. Example prompts: * "Change the discount rate to 8% and update dependent calculations." * "Flex the growth rate from 5% to 10% and show me the impact on terminal value." ### Build templates and models Populate an existing template or generate a new model from a natural language description. Example prompts: * "Populate this LBO template with a \$500M purchase price and 6x leverage." * "Build a three-statement model from this trial balance." ### Debug errors Locate the root cause of calculation errors and suggest fixes. Example prompts: * "Find the source of the #REF! error in the summary tab." * "Trace why cell H15 is returning #DIV/0." ### Native Excel operations Claude can sort, filter, edit pivot tables, apply conditional formatting, and create data validation dropdowns. Ask for these directly. ## Connectors and Skills Claude for Excel supports connectors for pulling external context into your workbook, and Skills for applying reusable task recipes. See [Connectors and Skills](/docs/office-agents/connectors-and-skills) for details. ## Set persistent instructions Open Settings in the add-in sidebar and use the Instructions field to set preferences that apply to every conversation in Excel. Instructions are useful for formatting conventions such as "format numbers with thousand separators" or "always bold column headers", currency or locale preferences, or recurring context about your workflow. Instructions you set in Excel only apply to Excel. They are separate from Instructions you set in PowerPoint or Word. ## Work across M365 apps Claude for Excel shares context with Claude for PowerPoint, Word, and Outlook, so a single conversation can span your open workbook, presentation, document, and inbox. See [Work across M365 apps](/docs/office-agents/work-across-apps). ## Context and session management The add-in handles long sessions and protects against accidental overwrites for you. * **Auto-compaction**: longer conversations are automatically compacted into new conversations to avoid running out of context. See [Understanding usage and length limits](https://support.claude.com/en/articles/11647753-understanding-usage-and-length-limits). * **Overwrite protection**: Claude warns you before overwriting existing data to avoid accidental data loss. Your use of Claude for Excel is associated with your existing Claude account and is subject to the same usage limits. ## Models available Claude for M365 offers a curated subset of the Claude models: the ones that work best for Office tasks, so the list you see in the add-in can be shorter than what you see in Claude.ai. Your organization's model access settings also apply, and a model appears here only if your role permits it. See [Manage model access for your organization](https://support.claude.com/en/articles/15694740-manage-model-access-for-your-organization) for how those settings interact with each product. If you connect through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, the available models come from that platform and your admin's configuration instead of your Claude.ai model access settings. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for details. ## Data handling Inputs and outputs are deleted on the backend within 30 days of receipt or generation, except in cases outlined in [How long do you store my organization's data?](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). Data is cached for a number of hours after deletion so users can access context in recently closed workbooks. Chat history is stored locally in your browser using IndexedDB. Conversations are not stored on Anthropic's servers, are not synced across devices, and can be cleared from Settings at any time. Reinstalling the add-in or switching between Claude add-ins does not remove it. See [Data storage and retention](/docs/office-agents/data-storage) for where it sits on disk and how long it is kept. Claude for Excel does not inherit custom data retention settings your organization might have set. Activity is not included in Enterprise audit logs. For Enterprise organizations with the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, Claude for Excel sessions are included in the Compliance API. This coverage is in public beta and requires no additional setup: the same Compliance Access Keys apply. ## Current limitations Claude for Excel is not recommended for: * Final client deliverables without human review. * Audit-critical calculations without verification. * Models containing highly sensitive or regulated data without proper controls. Unsupported capabilities: * Data tables. * Macros and VBA operations. ### Unsupported versions The add-in does not run on these Excel versions. * Excel 2016 and 2019 perpetual or volume license. * Excel on iPad. The add-in requires SharedRuntime support, which iPad does not provide. * Excel on Android. * Older builds of Microsoft 365 Excel below the SharedRuntime threshold. ## Prompt injection risk Only use Claude for Excel with trusted spreadsheets. Files from external sources can contain hidden instructions that manipulate the add-in into extracting data, modifying records, or performing destructive actions. External files such as downloaded templates, vendor files, and data imports can contain prompt injections that try to trick Claude into taking unintended actions. Testing has identified scenarios where Claude for Excel can be manipulated to extract sensitive information, modify critical data, or perform destructive actions if allowed to act without verification. When Claude proposes a risky operation, you are asked to confirm before it runs. Review confirmations carefully, especially for files from external sources. ## Best practices Follow these guidelines to use Claude for Excel safely and effectively. * Always review changes before finalizing your work. * Start with a trusted copy of the workbook before asking Claude to edit widely. * Be specific about what you want changed. * Verify that outputs match your organization's standards and your own judgment. # Install financial services plugins for Cowork Source: https://claude.com/docs/office-agents/fsi-plugins Add the open-source financial services plugin set to Cowork for financial modeling, equity research, investment banking, private equity, and wealth management workflows. A set of open-source plugins extends Cowork with specialized capabilities for financial services workflows: financial modeling, equity research, investment banking, private equity, and wealth management. The plugins also work in Claude Code. The plugins live in a [public GitHub repository](https://github.com/anthropics/financial-services) that you can add as a marketplace in Cowork. ## What's included The repository contains a core plugin and several add-on plugins that build on it. | Plugin | What it does | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Financial analysis (core) | Build comparable company analyses, DCF models, LBO models, and 3-statement financials. Includes all shared MCP connectors for financial data providers. Install this first. | | Investment banking | Draft CIMs, teasers, and process letters. Build buyer lists, run merger models, and create strip profiles. | | Equity research | Write earnings updates and initiating coverage reports. Track catalysts and screen for new ideas. | | Private equity | Source and screen deals, run due diligence checklists, draft IC memos, and monitor portfolio company KPIs. | | Wealth management | Prep for client meetings, build financial plans, rebalance portfolios, and identify tax-loss harvesting opportunities. | The repository also includes partner-built plugins from LSEG and S\&P Global, which bring their financial data and analytics directly into Cowork. ## Add the marketplace Open the Claude Desktop app and select the Cowork tab in the mode selector. Select "Customize" on the left sidebar, then "Browse plugins". Select "Personal", click the "+" button, then select "Add marketplace from GitHub". Enter the repository URL: `https://github.com/anthropics/financial-services` Once added, you'll see the available financial services plugins in your marketplace. ## Install plugins From your plugin marketplace, browse the available financial services plugins. Install the financial analysis plugin first. It provides shared tools and data connectors that the other plugins use. Install any additional plugins that match your workflow needs. Once installed, plugins activate automatically. Skills are applied when relevant, or you can invoke them manually during your Cowork session by typing `/` or clicking the "+" button. ## Available Skills After installation, you can invoke Skills like the following. AI-generated financial analysis should always be reviewed by a qualified professional before being used in decision-making. | Skill | What it does | | ------------------------------- | --------------------------------------- | | `/comps [company]` | Run a comparable company analysis. | | `/dcf [company]` | Build a DCF valuation model. | | `/earnings [company] [quarter]` | Generate a post-earnings update report. | | `/one-pager [company]` | Create a one-page company profile. | | `/ic-memo [project name]` | Draft an investment committee memo. | | `/source [criteria]` | Source deals based on criteria. | | `/client-review [client]` | Prep for a client meeting. | ## MCP connectors The financial analysis core plugin includes connectors for third-party financial data providers including Daloopa, Morningstar, S\&P Global, FactSet, Moody's, MT Newswires, Aiera, LSEG, PitchBook, Chronograph, and Egnyte. Access to these connectors may require a separate subscription or API key from the respective provider. Contact your data provider for details. ## Customize plugins for your firm These plugins are starting points. Plugins are file-based Markdown and JSON, so no code or infrastructure is required to customize them. Edit the plugin files directly to match your firm's workflows. * Add your firm's terminology, processes, and formatting standards to skill files. * Swap or add MCP connectors to point at your specific data providers. * Adjust workflow instructions to reflect how your team does analysis. * Use `/ppt-template` to teach Claude your firm's branded PowerPoint layouts. ## Learn more See the [Cowork and plugins for finance](https://claude.com/blog/cowork-plugins-finance) blog post for background on how the plugins were designed. # Configure a custom OpenTelemetry collector Source: https://claude.com/docs/office-agents/opentelemetry Route the full Claude for M365 audit trail, including prompts, tool inputs and outputs, and document references, to an OpenTelemetry collector you operate. Route complete audit telemetry from Claude for Excel, PowerPoint, Word, and Outlook to your own OpenTelemetry (OTEL) collector. This gives you control over retention and encryption and lets you feed the data into a SIEM or observability platform. This capability is available to Claude Enterprise organizations and to direct-provider deployments on Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway. ## What the collector receives When a custom collector is configured, the add-in sends trace data for every user turn. Each turn produces a tree of spans covering the prompt, each model call, each tool execution, file uploads, and context compaction. All span attributes are included. They carry user-generated content: prompt text, tool inputs and outputs, and document URLs. The allowlist filter that strips sensitive attributes on the Anthropic path does not run on this path. One normalization still applies: MCP connector tool names are recorded as the literal `mcp_tool` rather than the connector-specific name. Assistant response text is not included in span data. Your organization owns the collected data; treat the endpoint as containing prompt and document content when you scope access controls and retention. Metrics are not sent to custom collectors. The `office_agent.*` counter namespace routes to Anthropic only. Every counter increment is also recorded as a span event on the active span, so the same signals are recoverable from the trace stream. Telemetry is sent over OTLP/HTTP to `{your_url}/v1/traces`. gRPC is not supported because of Office WebView constraints. ## Endpoint requirements The add-in exports telemetry from each user's browser: the taskpane at `https://pivot.claude.ai` posts directly to your collector, so every export is a cross-origin request. The endpoint must: * Answer the `OPTIONS` preflight with `Access-Control-Allow-Origin` covering `https://pivot.claude.ai` and `Access-Control-Allow-Headers` covering `Content-Type` plus any headers you configure, such as `Authorization`. * Return the same `Access-Control-Allow-Origin` header on the `POST` response. Managed OTLP ingest endpoints such as Grafana Cloud are built for server-to-server export and generally do not answer browser CORS preflights. Point the add-in at an OpenTelemetry Collector you run, configure the `cors` block on its OTLP HTTP receiver, and have that collector forward to your backend. The collector makes the authenticated call to your backend, so no credential needs to appear in export headers that reach every signed-in user's browser. ## Set up the collector Configuration differs by how your users sign in. ### Claude Enterprise organizations An organization administrator sets the collector endpoint in the Claude admin console under Organization settings, Office agents. Two settings are available: | Setting | Description | | --------------- | --------------------------------------------------------------------------------- | | `otlp_endpoint` | Base URL of your OTLP collector. The add-in appends `/v1/traces` | | `otlp_headers` | Optional authentication headers in OpenTelemetry `key1=value1,key2=value2` format | ### Direct-provider deployments Deployments that authenticate against Bedrock, Vertex AI, Foundry, or a gateway supply the same two keys through the customer-configuration channels described in [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms). | Key | Format | Description | | --------------- | ------------------------- | ------------------------------------------------- | | `otlp_endpoint` | HTTPS URL | Collector base URL. Trailing slashes are stripped | | `otlp_headers` | `key1=value1,key2=value2` | Optional authentication headers | The `claude-for-msft-365-install` setup plugin writes these for you. To set them by hand, use any of the three channels below. Later channels override earlier ones: manifest parameters are read first, then Entra claims, then the bootstrap response. **Manifest URL parameter.** Append the keys to the taskpane URL in your custom manifest. ```text theme={null} https://pivot.claude.ai/taskpane.html?otlp_endpoint=https://otel-collector.example.com&otlp_headers=Authorization=Bearer%20 ``` **Entra ID directory extension.** Register the keys as directory extension attributes and assign them per user through Microsoft Graph. The add-in reads them from the user's ID token via Nested App Authentication. `extn.otlp_endpoint` maps to `otlp_endpoint` and `extn.otlp_headers` maps to `otlp_headers`. **Bootstrap endpoint response.** Include the keys in the JSON body your bootstrap endpoint returns. ```json theme={null} { "otlp_endpoint": "https://otel-collector.example.com", "otlp_headers": "Authorization=Bearer " } ``` ### Attribute size cap Prompt, tool-input, and tool-output attributes are truncated in the add-in at 4,000 characters each by default and marked with a trailing `…[truncated]`. Set the `otlp_attr_max_chars` configuration key to a positive integer to change the cap. Values are clamped to between 256 and 32,000. Before raising the cap, confirm your collector and tracing backend accept attribute values of the configured size: many backends truncate or drop over-limit attributes at ingest, and a dropped span is lost from the audit trail entirely. ## Deployment modes The audit trail differs slightly depending on the sign-in path. **Claude Enterprise (OAuth):** full audit trail including user identity (`user.email`, `user.account_uuid`, `organization.id`), MCP server metadata, and file-upload spans. **Direct provider (Bedrock, Vertex AI, Foundry, gateway):** core audit trail with prompts, tool inputs and outputs, and document URLs. No Claude user identity, MCP metadata, or file-upload spans. Attribute activity to a user by correlating `session.id` against your identity provider or gateway logs. ## Span reference Each user turn produces up to five span types. `agent.query` is the root; `agent.stream` and `agent.compaction` are its children; `agent.tool_execution` is a child of `agent.stream`; `file.upload` arrives as a separate root span. The `agent.query` and `agent.compaction` spans carry `agent.surface` (`sheet`, `doc`, `slide`, or `mail`) and `agent.vendor` (`m` for Microsoft); the other three do not. To filter those by surface, join `agent.stream` and `agent.tool_execution` to their parent `agent.query` by trace ID, and correlate `file.upload` to a turn by `session.id` and timestamp, since it has its own trace ID and no surface attribute. Attributes marked *content* carry user-generated data. Attributes marked *Claude sign-in only* are populated only when users sign in with a Claude account. ### Resource attributes These are set on every span. | Attribute | Description | | ----------------- | -------------------------------------------------------- | | `service.name` | Fixed value `office-agent` | | `service.version` | Fixed value `1.0.0`. Use `git.sha` to identify the build | | `git.sha` | Build commit | ### agent.query Root span, one per user turn. SpanKind `INTERNAL`. | Attribute | Description | | ----------------------------------------------- | ------------------------------------------------------------- | | `agent.surface` | `sheet`, `doc`, `slide`, or `mail` | | `agent.vendor` | `m` | | `user.message` *content* | User prompt, truncated per the attribute cap | | `user.message_chars` | Pre-truncation length of the prompt | | `session.id` | Opaque session identifier | | `document.url` *content* | URL of the open Office document | | `agent.selected_model` | Model selected for the session | | `office.platform` | `PC`, `Mac`, `OfficeOnline`, `iOS`, `Android`, or `Universal` | | `office.version` | Office build number | | `user.email` *Claude sign-in only* | User email | | `user.account_uuid` *Claude sign-in only* | Claude account UUID | | `organization.id` *Claude sign-in only* | Claude organization UUID | | `org.rate_limit_tier` *Claude sign-in only* | Subscription tier | | `mcp.configured_count` *Claude sign-in only* | Configured MCP servers | | `mcp.connected_count` *Claude sign-in only* | Connected MCP servers | | `mcp.failed_count` *Claude sign-in only* | Failed MCP connections | | `file.upload.count` *Claude sign-in only* | Files attached to the turn | | `file.upload.total_bytes` *Claude sign-in only* | Total uploaded bytes | | `error.name` | Exception class name, on failure | | `agent.query_phase` | Phase at failure, on failure | ### agent.stream One span per model API call, child of `agent.query`. SpanKind `CLIENT`. | Attribute | Description | | ----------------------- | ------------------------------------------------- | | `model` | Model ID used | | `max_tokens` | Maximum output tokens requested | | `agent.message_count` | Messages in the conversation at stream start | | `input_tokens` | Input tokens billed | | `output_tokens` | Output tokens billed | | `cache_read_tokens` | Tokens served from prompt cache | | `cache_creation_tokens` | Tokens written to prompt cache | | `stop_reason` | `end_turn`, `tool_use`, `max_tokens`, and similar | | `request_id` | Provider request ID for support correlation | The add-in requests prompt caching on every call. Cache token attributes are set from the provider's response and omitted when the provider does not return them. ### agent.tool\_execution One span per tool call, child of `agent.stream`. SpanKind `INTERNAL`. This is the primary record of what the model did to the document. | Attribute | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | | `tool_name` | Tool identifier, for example `get_cell_ranges` or `execute_office_js`. MCP connector tools are recorded as `mcp_tool` | | `tool.id` | Unique invocation ID | | `tool.caller` | `direct` for tools the add-in runs, or `server_tool` for tools the model provider runs | | `tool.owner` | `first_party` for built-in tools, or `third_party` for MCP connector tools | | `tool.read_write` | `read` or `write` | | `tool.accept_decision` | `manual` (user approved this action), `auto_accept` (standing approval), or `deferred` (queued for review) | | `tool.input` *content* | Serialized tool input, truncated per the attribute cap | | `tool.success` | Boolean | | `tool.output` *content* | Serialized tool output, truncated per the attribute cap | | `tool.output_chars` | Full output length in characters | | `tool.error_type` | Error classification, on failure | | `sheet.cells_read` | Cells read, sheet surface only | | `sheet.cells_written` | Cells written, sheet surface only | | `sheet.cells_copied` | Cells copied, sheet surface only | ### agent.compaction One span per automatic conversation summarization when context nears the window limit, child of `agent.query`. SpanKind `CLIENT`. Also carries `agent.surface`, `agent.vendor`, `session.id`, `office.platform`, `office.version`, and `user.email` (Claude sign-in only). | Attribute | Description | | ------------------------- | -------------------------------- | | `compaction.pre_tokens` | Token count before summarization | | `compaction.post_tokens` | Token count after summarization | | `compaction.tokens_saved` | Delta | | `compaction.success` | Boolean | | `compaction.trigger` | Currently always `reactive` | ### file.upload One span per uploaded file, emitted as its own root span rather than under `agent.query`. SpanKind `CLIENT`. Claude sign-in only. Also carries `session.id` and `user.email`. Correlate to the turn by `session.id` and timestamp. | Attribute | Description | | ------------------------ | ------------------------------ | | `file.upload.size_bytes` | File size | | `file.upload.mime_type` | MIME type | | `file.upload.file_id` | Anthropic Files API identifier | | `file.upload.success` | Boolean | ## Span events Spans carry timestamped events for lifecycle transitions: * `agent.query`: `exception`, `file_upload` * `agent.stream`: `first_token`, `stream_complete`, `stream_error` * `agent.tool_execution`: `tool_init`, `tool_run`, `tool_result`, `tool_error` * `agent.compaction`: `compaction_start`, `compaction_complete`, `compaction_error` * `file.upload`: `exception` Every internal product counter also records a span event with the same name on the active span. For example, `office_agent.token.usage` is emitted on each `agent.stream` span with `token_usage.type` (`input`, `output`, `cacheRead`, or `cacheCreation`), `token_usage.model`, and `token_usage.token_count`. Surface-specific events include `office_agent.cell_edit_collision_total` on Excel when a user is mid-edit while a tool writes, and the Word document-edit funnel (`office_agent.doc_edit_received_total`, `doc_edit_parsed_total`, `doc_edit_applied_total`, `doc_proposed_edit_reviewed_total`). PowerPoint and Outlook add no events beyond the common schema. ## Reconstruct a user session The span tree produces a complete, ordered transcript in both deployment modes. For Claude Enterprise deployments, filter `agent.query` spans by `user.email` or `user.account_uuid` and `session.id`, order them by timestamp, and read `user.message` and `document.url` for each turn. Then follow each `agent.query` span's trace ID to its `agent.tool_execution` descendants, ordered by timestamp, to see what was attempted (`tool.input`), the result (`tool.output`), and how it was approved (`tool.accept_decision`). For direct-provider deployments, filter `agent.query` spans by `session.id` to isolate one session, use `document.url` to identify the file, and correlate the session against your Entra sign-in events, gateway access logs, or bootstrap endpoint logs to attribute it to a user. Per-turn reconstruction then follows the same trace-ID walk. # Use Claude for Outlook Source: https://claude.com/docs/office-agents/outlook An Outlook add-in that integrates Claude into your inbox and calendar, for Pro, Max, Team, and Enterprise plans. Claude for Outlook is an add-in that brings Claude into your Outlook inbox and calendar. It is built for professionals whose work runs through email, including private equity and investment banking associates managing deal flow, in-house legal teams running counterparty negotiations, and consultants tracking multiple client threads. Claude for Outlook is currently in beta and available to Pro, Max, Team, and Enterprise plans. ## What you can do With Claude for Outlook, you can: * Triage your unread inbox into what needs you, what Claude can handle, and what is noise. * Draft replies, reply-alls, and forwards in your voice, landed unsent in Outlook's compose pane. * Summarize long threads into decisions made, open items, and who owes what, with per-email citations. * Read `.docx` and `.xlsx` attachments inline without opening them. * Find meeting times across attendees and draft invites into Outlook's native appointment form. * Prep for your next meeting with a one-page brief of recent threads and attached documents. ## Get started with Claude for Outlook ### Supported versions Claude for Outlook runs on the following Outlook clients. * Outlook on the web * Outlook on Windows, both new Outlook and classic Outlook, with a Microsoft 365 subscription * Outlook on Mac with a Microsoft 365 subscription The following are not supported: Outlook 2016 and 2019 perpetual or volume-licensed editions, Outlook on iOS, Outlook on Android, and mailboxes hosted on Exchange on-premises. Exchange Online through Microsoft 365 is required. ### Install for yourself Go to the [Claude for Outlook listing on Microsoft AppSource](https://appsource.microsoft.com/). Select "Get it now" to install. Open Outlook, open any email, select the Claude button in the message ribbon, and sign in with your Claude account. If you do not see the Claude button on the message, open the overflow menu on the reading pane, choose Customize actions, and check Claude under Apps. It then appears on every message and in the Home ribbon. ### Deploy to your organization Organization admins can deploy Claude for Outlook through the Microsoft 365 Admin Center. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), go to Settings, Org Settings, User owned apps and services, and turn on ["Let users access the Office Store"](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-addins-in-the-admin-center). Go to Settings, then Integrated apps. Search for "Claude for Outlook" in Microsoft AppSource. Deploy the add-in to your organization or to specific people. See [Microsoft's deployment guide](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins) for assignment options. Complete the [Microsoft Graph admin consent](#grant-microsoft-graph-consent) step below so users are not prompted individually. If your organization uses Microsoft Entra Privileged Identity Management (PIM) for admin roles, the Integrated apps page does not recognize roles activated through PIM, so deployment fails. This is a [known Microsoft issue](https://learn.microsoft.com/en-us/office/dev/add-ins/resources/resources-office-add-in-known-issues), tracking ID 11126536. To work around it, deploy from an admin account with the required role assigned as permanently active rather than PIM-eligible. See [Microsoft's troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/microsoft-365/admin/miscellaneous/cannot-deploy-add-in-integrated-apps-menu). Individual users can still [install the add-in themselves](#install-for-yourself). After installation, team members open Outlook, open any email, select the Claude button in the message ribbon, and sign in with their Claude credentials. Pinning the task pane keeps it open as you move between messages. Organizations that have disabled "Let users access the Office Store" may find that admin-deployed add-ins don't appear for users. To work around this, deploy using the manifest XML file described below. ### Install from a manifest file If your organization blocks the Microsoft Store, an IT administrator can deploy the add-in by uploading its manifest file directly. Download the [Claude for Outlook manifest](https://pivot.claude.ai/manifest-outlook.xml) and save it to a secure location. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), go to Settings, then Integrated apps. Select Upload custom apps, then Office Add-in. Choose "I have a manifest file on this device", select the file you downloaded, and upload it. Choose your deployment scope: the entire organization, specific people, specific groups, or just yourself for testing. Review the settings and select Deploy. The add-in appears within minutes for most people. Full organization rollout can take up to 24 hours on the Microsoft 365 side. Complete the consent step in the next section. ### Grant Microsoft Graph consent Claude for Outlook reads mail and calendar data through Microsoft Graph. This requires a one-time tenant-wide grant from a Global Administrator and is separate from the Integrated apps deployment. Have a Global Administrator open the following admin consent link in a browser where they are signed in to your Microsoft 365 tenant. ``` https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=c2995f31-11e7-4882-b7a7-ef9def0a0266&scope=https://graph.microsoft.com/Mail.ReadWrite%20https://graph.microsoft.com/Calendars.Read%20https://graph.microsoft.com/User.Read%20offline_access&redirect_uri=https://pivot.claude.ai/auth/callback ``` The administrator sees a Microsoft permissions screen listing `Mail.ReadWrite`, `Calendars.Read`, `User.Read`, and `offline_access`. After they select Accept, all users in the organization can use Claude for Outlook without additional Microsoft prompts. The grant takes effect immediately. Only the add-in rollout in the previous step can take up to 24 hours. If this step is skipped, every user sees a "Need admin approval" message when Claude first tries to read mail or calendar data. The redirect to `pivot.claude.ai` after consent carries only the consent outcome, never a token or authorization code. See [Why sign-in redirects through pivot.claude.ai](/docs/office-agents/third-party-platforms#why-sign-in-redirects-through-pivotclaudeai) for what each redirect carries and how to verify it in a network capture. #### Use your own Entra app instead If your organization's policy does not permit consenting to a third-party multi-tenant application, register a single-tenant application in the Microsoft Entra admin center and have the add-in use it instead. The data flow is identical; the Graph token stays in the user's Outlook client either way. The difference is that approval and Conditional Access policy live entirely under an application your organization owns. In the Entra admin center, go to App registrations and create a new registration. Choose "Accounts in this organizational directory only". Under Authentication, add a Single-page application platform with redirect URI `brk-multihub://pivot.claude.ai`. In Advanced settings, set "Allow public client flows" to Yes. Under API permissions, add the Microsoft Graph delegated permissions `Mail.ReadWrite`, `Calendars.Read`, `User.Read`, and `offline_access`. Select "Grant admin consent" for your tenant. Copy the application's client ID from the Overview page. Append `?graph_client_id=YOUR_CLIENT_ID` to the manifest URL from the [Install from a manifest file](#install-from-a-manifest-file) section and use that URL when downloading the manifest. With this option, skip the admin consent link entirely. Users do not see a Microsoft permissions prompt because your tenant has already consented to your own application. ### Deploy in a US Government or national cloud If your Microsoft 365 tenant is in GCC High, DoD, or 21Vianet, register your own Entra application with `graph_client_id` as described above (Anthropic's multi-tenant application exists only in the global cloud) and set `graph_cloud` to the matching value: | Tenant | `graph_cloud` | | ----------------- | ---------------------------------- | | Commercial or GCC | `global` (default; may be omitted) | | GCC High | `us-gov-high` | | DoD | `us-gov-dod` | | 21Vianet (China) | `china` | For a DoD tenant the manifest URL ends with: ``` ?graph_client_id=YOUR_CLIENT_ID&graph_cloud=us-gov-dod ``` For GCC High and 21Vianet tenants, `graph_cloud` may be omitted: the add-in detects those clouds at sign-in from the authority host Outlook reports. Setting it explicitly is still recommended when your compliance program requires the endpoints to be fixed in the reviewed manifest rather than derived at runtime. DoD tenants share an authority host with GCC High, so `graph_cloud=us-gov-dod` is always required for DoD. ### Connect through a third-party platform If your organization routes API traffic through an internal LLM gateway, Amazon Bedrock, Google Cloud Vertex AI, or Azure AI Foundry, you can use the add-in without Claude accounts. This is the same gateway pattern used by Claude Code. For setup instructions and gateway requirements, see [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms). ## Triage your inbox Ask Claude what needs your attention. Claude reads your unread mail and attachments and sorts them into three groups: action items for you, items Claude can handle for your review, and noise you can archive in one selection. Each action item carries a one-line reason. Items Claude can handle, such as scheduling asks, acknowledgments, and standard-form documents, arrive pre-drafted. Prompts to try: * "What needs me?" * "Draft replies for everything you can handle" * "Archive all the calendar responses and newsletters" ## Draft replies in your voice Tell Claude what you want to say. It drafts the reply into Outlook's native compose pane, unsent. Tone is learned from your sent folder, so the draft matches your sentence length and formality register. Claude leaves the closing off so Outlook can append your configured signature without duplication. Claude chooses reply versus reply-all deliberately and warns before adding anyone who was not on the thread. Prompts to try: * "Reply to this and agree to the extension, push back on the fee" * "Reply-all thanking everyone and confirming Thursday works" * "Forward this to Dana with a two-line summary" ## Summarize long threads Claude reads the entire conversation, including every reply and forward, and tells you what has been decided, what is still open, and who owes what. Every claim cites the specific email it came from. Selecting a citation opens that message in Outlook. Prompts to try: * "What's been decided and what's still open?" * "Who owes what on this thread?" ## Read attachments inline Claude reads `.docx` and `.xlsx` attachments on the open email without you opening them. For `.pptx` attachments, open the deck in PowerPoint with the thread loaded as context using [Work across M365 apps](/docs/office-agents/work-across-apps). PDF attachments are not currently read inline; save the file and upload it through the sidebar instead. Prompts to try: * "Summarize the attached memo" * "What's in the spreadsheet on this email?" ## Search your mailbox Ask Claude to find a past conversation by topic, not only by keywords. Results return as citations that open the source message in Outlook so you can verify every answer against the original email. Prompts to try: * "When did we last discuss the cap with Fernwood?" * "Find the email where Dana sent the revised term sheet" ## Find time and create events Claude checks free/busy for everyone whose calendar you can see and proposes slots that respect working hours and existing holds. The invite is drafted into Outlook's native appointment form with attendees, subject, and agenda for you to review and send. Prompts to try: * "Find 30 minutes with Dana and the Fernwood team next week" * "Block Thursday afternoon for deep work" ## Prep for meetings For your next event, Claude pulls the last thread with each attendee and any attached documents into a one-page brief, so you walk in knowing the open items and what each person last said. Prompts to try: * "Prep me for my 2pm" * "What's open with Dana before our call?" ## Work across M365 apps Claude for Outlook shares context with Claude for Excel, PowerPoint, and Word, so Claude can work across your open Office apps in a single conversation. For example, you can open an attached letter of intent in Word with the email thread already loaded as context, or pull numbers from an email into an open Excel model, without copying between apps. For setup instructions, see [Work across M365 apps](/docs/office-agents/work-across-apps). ## Model availability When you sign in with a Claude account, you can choose between Claude Opus 4.7, Opus 4.6, and Sonnet 4.6. When you connect through a third-party platform such as Vertex AI, Azure AI Foundry, or an LLM gateway, Opus 4.7 is the only officially supported model. ## How Claude accesses your mailbox Claude reads the email or event you have open via Office.js. For anything that spans your mailbox or calendar, including thread retrieval, search, free/busy lookups, and move or flag operations, Claude uses Microsoft Graph. All Graph calls run in your browser, and the Graph access token stays in the browser's MSAL cache and is never sent to Anthropic. Claude never sends mail or invites on its own. The add-in does not request the `Mail.Send` permission. Every draft lands unsent in Outlook's compose or appointment form, and you click Send. Claude reads the open item via Office.js and uses Microsoft Graph for mailbox-wide actions; the Graph token stays in the browser. Where mailbox content goes after Claude reads it depends on how you sign in. ### When you sign in with a Claude account Mailbox content that Claude reads becomes part of the prompt sent to `api.anthropic.com`. Standard API retention applies: see [Data retention and audit](#data-retention-and-audit). The add-in does not keep a server-side copy or index of your mailbox. ### When you connect through a third-party platform The prompt goes only to the inference endpoint you configured, such as Amazon Bedrock, Vertex AI, Azure AI Foundry, or an LLM gateway. On Amazon Bedrock, Vertex AI, or a gateway that routes to them, no mailbox content reaches Anthropic. On Azure AI Foundry, Anthropic operates the Claude models and processes prompts as an independent processor for Microsoft, as described in [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for configuration details. The add-in does not keep a server-side copy or index of your mailbox. ## Chat history Chat history is stored locally in your browser using IndexedDB. Conversations are not stored on Anthropic's servers and are not synced across devices or browsers. You can clear all chat history from Settings at any time. The local store is also cleared when you clear your browser data. Chat history is specific to the combination of the add-in surface, your user ID, and your organization ID, so your Excel and Outlook histories are separate. Reinstalling the add-in or switching between Claude add-ins does not remove it. See [Data storage and retention](/docs/office-agents/data-storage) for where it sits on disk and how long it is kept. ## Data retention and audit For Claude for Outlook use, inputs and outputs are deleted on Anthropic's backend within 30 days of receipt or generation, except as described in [How long do you store my organization's data?](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) Enterprise organizations can route full audit telemetry from Claude for Outlook to their own OpenTelemetry collector for integration with a SIEM or observability platform. See [Configure a custom OpenTelemetry collector](/docs/office-agents/enterprise-readiness) for setup. On Pro, Max, and Team plans, observability and audit export are not available. Claude for Outlook does not inherit custom data retention settings your organization may have configured and is not included in Enterprise audit logs. For Enterprise organizations with the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, Claude for Outlook sessions are included in the Compliance API. This coverage is in public beta and requires no additional setup: the same Compliance Access Keys apply. ## Prompt injection risks Be cautious with email from external or untrusted senders. Email bodies and attachments are untrusted input and may contain instructions intended to manipulate Claude rather than you. Prompt injection refers to malicious instructions hidden in an email body, signature, or attachment that try to trick the AI into taking unintended actions. For example, a routine inbound email might contain hidden text instructing Claude to forward a thread or draft a reply you did not ask for. Claude may interpret these instructions as legitimate requests. Review every draft and inbox action before accepting it, especially when working with email from external or untrusted senders. ## Recommended use during beta As a beta feature, Claude for Outlook is not recommended for: * Unattended sending. Claude never sends mail or invites on its own; every draft lands unsent for your review. * Client-facing or counterparty correspondence without reading the draft first. * Replacing your judgment on which emails matter or how to handle a relationship. * Mailboxes containing privileged or regulated data without appropriate organizational controls. To use Claude for Outlook safely and effectively: * Review drafted replies and invites before sending, especially recipient lists. * Verify thread summaries against the cited source emails for high-stakes conversations. * Apply appropriate Microsoft 365 permissions and Conditional Access policies for the add-in. * Maintain human oversight for anything leaving your organization. # Claude for M365 overview Source: https://claude.com/docs/office-agents/overview Claude for Excel, PowerPoint, Word, and Outlook. Claude for M365 is a set of Claude-powered add-ins that work inside your Microsoft 365 apps. Chat with Claude about the file or email you have open, ask it to read or edit content, and move work between Excel, PowerPoint, Word, and Outlook without leaving the app. ## What's available today The pages below cover each surface and the features that span them. * [Claude for Excel](/docs/office-agents/excel): read and write cells, formulas, formatting, pivot tables, and charts. * [Claude for PowerPoint](/docs/office-agents/powerpoint): read, edit, and generate slides using your existing templates. * [Claude for Word](/docs/office-agents/word): draft, redline, and review documents with tracked changes and comment-driven editing. * [Claude for Outlook](/docs/office-agents/outlook): triage your inbox, draft replies in your voice, summarize threads, and find meeting times. Admins must complete a one-time [Microsoft Graph consent](/docs/office-agents/outlook#grant-microsoft-graph-consent) before deployment. * [Work across M365 apps](/docs/office-agents/work-across-apps): Claude for Excel, PowerPoint, Word, and Outlook share conversation state, so actions in one app are informed by what happened in the others. * [Connectors and Skills](/docs/office-agents/connectors-and-skills): extend Claude with external context and reusable task recipes. * [Dictation](/docs/office-agents/dictation): speak prompts instead of typing them. ## Deployment These pages cover enterprise admin setup and observability. * [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms): connect through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway. * [Security, admin auditability, and analytics](/docs/office-agents/enterprise-readiness): security architecture diagrams, OpenTelemetry audit, usage analytics, and spend tracking. * [Configure a custom OpenTelemetry collector](/docs/office-agents/opentelemetry): route the full audit trail to a collector you operate, with the configuration keys and span reference. # Use Claude for PowerPoint Source: https://claude.com/docs/office-agents/powerpoint A PowerPoint add-in that integrates Claude into your presentation workflow, for Pro, Max, Team, and Enterprise plans. Claude for PowerPoint is an add-in that brings Claude into PowerPoint. Build decks from scratch, edit specific slides without regenerating everything, convert bullets into diagrams and native charts, and iterate on feedback while preserving template compliance. Claude for PowerPoint is generally available to Pro, Max, Team, and Enterprise plans. ## What you can do With Claude for PowerPoint, you can: * Build new slides using your existing client or corporate templates. * Make pinpoint edits to specific slides without regenerating entire decks. * Generate full deck structures from natural language descriptions. * Convert bullets into diagrams and native PowerPoint charts. * Pull external context through connectors. * Iterate on feedback while preserving formatting and template compliance. ## Get started with Claude for PowerPoint ### Supported versions Claude for PowerPoint runs on the following PowerPoint builds. * PowerPoint on the web * PowerPoint on Windows with a Microsoft 365 subscription, build 16.0.13127.20296 or later * PowerPoint on Mac, version 16.46 or later ### Install for yourself Go to the [Claude for Microsoft 365 listing on Microsoft AppSource](https://marketplace.microsoft.com/en-us/product/office/WA200010725?tab=Overview). Select "Get it now" to install. Open PowerPoint, activate the add-in, and sign in with your Claude account. ### Deploy to your organization Organization admins can deploy Claude for PowerPoint through the Microsoft 365 Admin Center. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), go to Settings, Org Settings, User owned apps and services, and turn on ["Let users access the Office Store"](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-addins-in-the-admin-center). Go to Settings, Integrated apps, Add-ins. Search for "Claude for Microsoft 365" in Microsoft AppSource. Assign the add-in to your organization or to specific users or groups. Share [Microsoft's deployment guide](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins) with your team for activation steps. If your organization uses Microsoft Entra Privileged Identity Management (PIM) for admin roles, the Integrated apps page does not recognize roles activated through PIM, so deployment fails. This is a [known Microsoft issue](https://learn.microsoft.com/en-us/office/dev/add-ins/resources/resources-office-add-in-known-issues), tracking ID 11126536. To work around it, deploy from an admin account with the required role assigned as permanently active rather than PIM-eligible. See [Microsoft's troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/microsoft-365/admin/miscellaneous/cannot-deploy-add-in-integrated-apps-menu). Individual users can still [install the add-in themselves](#install-for-yourself). After deployment, users can activate the Claude add-in from Tools, Add-ins on Mac or Home, Add-ins on Windows, sign in, and start working. Organizations that have disabled "Let users access the Office Store" may find that admin-deployed add-ins don't appear for users. To work around this, deploy using the manifest XML file described below. ### Deploy with a custom manifest For IT administrators deploying to multiple users when the Office Store is disabled: Download the [custom manifest XML file](https://pivot.claude.ai/manifest-powerpoint.xml) and save it to a secure location. Go to [https://admin.microsoft.com](https://admin.microsoft.com), sign in, and open Settings, Integrated apps. Select "Upload custom apps", choose "Office Add-in", then "I have a manifest file on this device". Upload the manifest. Choose entire organization, specific users, specific groups, or just yourself for admin testing. Review settings and select "Deploy". The add-in is available within minutes. Full organization rollout can take up to 24 hours. After deployment, users see Claude in PowerPoint's Home ribbon and sign in with their Claude credentials on first use. ### Connect through a third-party platform If your organization routes AI traffic through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, your admin can deploy the add-in without individual Claude accounts. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms). ## Key features ### Build from templates Start with a client or corporate template already loaded. Describe what you need, and Claude generates slides using the correct layouts, fonts, and colors from the slide master. Claude reads your deck's template and respects its formatting rules. Example prompts: * "Create a market sizing section, 3 slides covering TAM, SAM, SOM with supporting visuals." * "Add an executive summary slide using the one-column content layout." ### Edit existing slides Select a slide and tell Claude what to change. Claude makes edits while preserving formatting and surrounding context. Example prompts: * "Simplify the text on this slide." * "Add a chart showing the quarterly trend." * "Restructure the storyline across slides 4 to 7." ### Generate full decks Open a blank deck and describe your goal. Claude builds a draft with logical structure and professional defaults, which you can refine. Example prompts: * "Create a 10-slide deck walking through our market entry hypotheses." * "Build an internal project update presentation with timeline and next steps." ### Create native charts and diagrams Convert bullet points into professional visuals such as diagrams, process flows, or editable native PowerPoint charts. Claude produces visuals you can edit directly, not static images. Example prompts: * "Turn these bullets into a process flow diagram." * "Create a bar chart comparing Q1 to Q4 performance." ### Template awareness Claude reads the slide master, layouts, fonts, and color scheme in your deck and uses them when generating or editing slides. It aims to maintain template compliance without introducing off-brand elements. ## Connectors and Skills Claude for PowerPoint supports connectors for pulling external context into your deck, and Skills for applying reusable task recipes. See [Connectors and Skills](/docs/office-agents/connectors-and-skills) for details. ## Set persistent instructions Open Settings in the add-in sidebar and use the Instructions field to set preferences that apply to every conversation in PowerPoint. Instructions are useful for brand guidelines such as "always use one-line bullets" or "use the blue accent color for highlights", preferred slide structure, or recurring context about your workflow. Instructions you set in PowerPoint only apply to PowerPoint. They are separate from Instructions you set in Excel or Word. ## Work across M365 apps Claude for PowerPoint shares context with Claude for Excel, Word, and Outlook, so a single conversation can span your open deck, workbook, document, and inbox. See [Work across M365 apps](/docs/office-agents/work-across-apps). ## Context and session management The add-in handles long sessions for you so a single conversation can span an entire workflow. * **Auto-compaction**: longer conversations are automatically compacted into new conversations to avoid running out of context. See [Understanding usage and length limits](https://support.claude.com/en/articles/11647753-understanding-usage-and-length-limits). Your use of Claude for PowerPoint is associated with your existing Claude account and is subject to the same usage limits. ## Models available Claude for M365 offers a curated subset of the Claude models: the ones that work best for Office tasks, so the list you see in the add-in can be shorter than what you see in Claude.ai. Your organization's model access settings also apply, and a model appears here only if your role permits it. See [Manage model access for your organization](https://support.claude.com/en/articles/15694740-manage-model-access-for-your-organization) for how those settings interact with each product. If you connect through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, the available models come from that platform and your admin's configuration instead of your Claude.ai model access settings. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for details. ## Data handling Inputs and outputs are deleted on the backend within 30 days of receipt or generation, except in cases outlined in [How long do you store my organization's data?](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). Data is cached for a number of hours after deletion so users can access context in recently closed presentations. Chat history is stored locally in your browser using IndexedDB. Conversations are not stored on Anthropic's servers, are not synced across devices, and can be cleared from Settings at any time. Reinstalling the add-in or switching between Claude add-ins does not remove it. See [Data storage and retention](/docs/office-agents/data-storage) for where it sits on disk and how long it is kept. Claude for PowerPoint does not inherit custom data retention settings your organization might have set. Activity is not included in Enterprise audit logs. For Enterprise organizations with the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, Claude for PowerPoint sessions are included in the Compliance API. This coverage is in public beta and requires no additional setup: the same Compliance Access Keys apply. ## Current limitations Claude for PowerPoint is not recommended for: * Final client deliverables without human review. * Presentations containing highly sensitive or regulated data without proper controls. * Replacing your judgment on design and narrative flow. ### Unsupported versions The add-in does not run on these PowerPoint versions. * PowerPoint 2016 and 2019 perpetual or volume license. * PowerPoint on iPad. * PowerPoint on Android. * Older builds of Microsoft 365 PowerPoint below the SharedRuntime threshold. ## Prompt injection risk Only use Claude for PowerPoint with trusted files. Files from external sources can contain hidden instructions that manipulate the add-in into extracting data, modifying records, or performing destructive actions. External files such as downloaded templates, vendor files, collaborative documents, and data imports can contain prompt injections that try to trick Claude into taking unintended actions. Testing has identified scenarios where Claude for PowerPoint can be manipulated to extract sensitive information, modify critical data, or perform destructive actions if allowed to act without verification. When Claude proposes a risky operation, you are asked to confirm before it runs. Review confirmations carefully, especially for files from external sources. ## Best practices Follow these guidelines to use Claude for PowerPoint safely and effectively. * Always review changes before finalizing your work. * Start with your template already applied before asking Claude to generate content. * Be specific about what you want changed. Claude can target individual slides or elements. * Verify that outputs match your organization's brand guidelines. ## Example use cases ### Consulting deliverables Prompts that produce client-ready sections and summaries. * "Build a market sizing section with TAM, SAM, SOM slides." * "Create a competitive landscape slide comparing 4 players." * "Summarize these survey results." ### Iterative refinement Prompts that tighten or restructure an existing deck. * "Simplify the text on slide 3, it's too dense." * "Combine slides 5 and 6 into a single summary." * "Make the recommendations section more visual." ### Data visualization Prompts that turn raw data into native charts and diagrams. * "Convert these bullet points into a process flow." * "Create a bar chart from this data table." * "Add a pie chart showing market share breakdown." ### Deck restructuring Prompts that reorder or re-sequence slides. * "Reorder slides to lead with recommendations first." * "Add transition slides between each major section." * "Create an agenda slide that reflects the current structure." # Use Claude for M365 with third-party platforms Source: https://claude.com/docs/office-agents/third-party-platforms Deploy the Office add-ins through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, without individual Claude accounts. Organizations using Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway can deploy Claude's Office add-ins without requiring individual Claude accounts. The add-in connects through your organization's infrastructure, keeping prompts and responses within your trust boundary. ## Connection paths Four connection paths are available. Your IT admin selects one during deployment. End users see the same interface regardless. | Path | How it works | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | LLM gateway | Requests route through your gateway (LiteLLM, Portkey, Kong, and others) to your chosen provider. Matches the pattern used by Claude Code. | | Bedrock direct | The add-in authenticates via Microsoft Entra ID and calls Amazon Bedrock directly without intermediaries. | | Vertex AI direct | The add-in authenticates through Google OAuth and calls Vertex AI directly. | | Foundry direct | The add-in calls your Azure AI Foundry resource directly, authenticating with each user's Microsoft Entra ID token (keyless) or with the resource API key. | ## Requirements by connection path All paths need: * Claude for Excel, PowerPoint, Word, or Outlook installed from Microsoft AppSource or via admin deployment. * Microsoft 365 with Entra ID for admin consent and token issuance. * For Outlook: Microsoft Graph admin consent for `Mail.ReadWrite`, `Calendars.Read`, `User.Read`, and `offline_access`, granted via Anthropic's app or your own Entra app registration. | Path | Additional requirements | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | LLM gateway | Gateway URL and API token from your IT team. | | Bedrock direct | AWS account with Claude model access enabled in target region. IAM OIDC identity provider and role configured to trust Microsoft Entra ID tokens. | | Vertex AI direct | Google Cloud project with Vertex AI API enabled and Claude model access. Google OAuth client configured with the add-in's redirect URI. | | Foundry direct | Azure AI Foundry resource with at least one Claude model deployed. Deployment names must use default model IDs (for example, `claude-opus-4-6`), not custom names. Then one credential path: **keyless**, your own Entra app registration with the Azure Cognitive Services `user_impersonation` delegated permission (admin-consented) and users holding the Cognitive Services User role on the resource (see [Foundry direct without an API key](#foundry-direct-without-an-api-key)); or the resource API key from Azure Portal, your Foundry resource, Keys and Endpoint, KEY 1. | Your organization's IT team manages these resources. Anthropic cannot provide or reset credentials. ## Network allowlist The add-in requires access to specific domains. The required domains differ depending on whether your organization uses the Anthropic API directly (1P) or a third-party platform (3P). In all configurations, prompts and responses travel only to your chosen inference provider. Domains pointing to Anthropic (such as `pivot.claude.ai`) serve the add-in's interface, feature configuration, and operational telemetry, not prompt or response content. ### Anthropic API (1P) Use this table if your organization signs in with Claude accounts and inference goes to `api.anthropic.com`. | Domain | Required when | Purpose | | ------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | | `pivot.claude.ai` | Always | Add-in host serving task pane UI, analytics, icon search, skill downloads, and telemetry. | | `claude.ai` | Always | Anthropic OAuth sign-in and feature-flag evaluation. | | `api.anthropic.com` | Always | Claude inference API, file uploads, code-execution containers, and MCP connector registry. | | `appsforoffice.microsoft.com` | Always | Microsoft Office.js runtime script (required by all Office add-ins). | | `login.microsoftonline.com` | If using Outlook | Microsoft Entra ID sign-in via Nested App Auth for the Graph token. | | `o1158394.ingest.us.sentry.io` | Optional | Crash and error reporting; blocking degrades diagnostics only. | | `mcp-proxy.anthropic.com` | If using MCP connectors | Proxy for MCP connector tool calls. | | `bridge.claudeusercontent.com` | If using work across apps | WebSocket bridge for the work-across-apps feature. | | `graph.microsoft.com` | If using Outlook | Microsoft Graph mailbox and calendar API. | If your organization has [IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) enabled for Claude, route `bridge.claudeusercontent.com` through the same proxy egress as `claude.ai` and `api.anthropic.com`, for example by placing it in the same Zscaler app segment or Netskope steering policy. If you cannot route it that way, add the egress address your proxy uses for that domain to your organization's Claude IP allowlist, but only when that address is dedicated to your organization: a shared proxy egress range also admits the proxy vendor's other customers. Anthropic checks connections to `bridge.claudeusercontent.com` against your organization's Claude IP allowlist using the address they arrive from. If your proxy sends traffic for that domain out through an address that is not on that allowlist, [work across apps](/docs/office-agents/work-across-apps) stops while the rest of the add-in keeps working. ### Third-party platforms (3P) Use this table if your organization signs in with Microsoft Entra ID and inference goes to your LLM gateway, Bedrock, Vertex AI, or Azure AI Foundry. | Domain | Required when | Purpose | | ---------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------- | | `pivot.claude.ai` | Always | Add-in host serving task pane UI, analytics, and telemetry. | | `claude.ai/api/` | Always | Feature-flag evaluation without sign-in. | | `appsforoffice.microsoft.com` | Always | Microsoft Office.js runtime script. | | `login.microsoftonline.com` | Always | Microsoft Entra ID sign-in via Nested App Auth; reads admin config and issues tokens. | | `o1158394.ingest.us.sentry.io` | Optional | Crash and error reporting; blocking degrades diagnostics only. | | Your LLM gateway URL | If using LLM gateway | Organization's LLM gateway for inference. | | `sts.amazonaws.com` | If using Bedrock direct | AWS STS for exchanging Entra ID token for temporary Bedrock credentials. | | `bedrock-runtime..amazonaws.com` | If using Bedrock direct | Bedrock inference endpoint; replace `` with your configured AWS region. | | `accounts.google.com` | If using Vertex AI direct | Google OAuth consent screen. | | `oauth2.googleapis.com` | If using Vertex AI direct | Google OAuth token exchange and refresh. | | `aiplatform.googleapis.com` | If using Vertex AI direct | Vertex AI global inference endpoint. | | `-aiplatform.googleapis.com` | If using Vertex AI direct | Vertex AI regional inference endpoint; replace `` with your GCP region. | | `.services.ai.azure.com` | If using Foundry direct | Azure AI Foundry inference endpoint; replace `` with your resource name. | | `graph.microsoft.com` | If using Outlook | Microsoft Graph mailbox and calendar API. | If Anthropic serves your add-in settings from your Claude organization, as described in [Serve add-in settings from your Claude organization](#serve-add-in-settings-from-your-claude-organization), also allow `claude.ai` and `api.anthropic.com`. Members sign in with their Claude account at `claude.ai`, and the add-in reads your organization's settings from `api.anthropic.com`. Inference still goes only to the gateway or cloud provider those settings name. ## Deploy the add-in for your organization Use the `claude-for-msft-365-install` plugin to configure and deploy the add-in across your organization. The plugin provisions cloud resources (for Bedrock or Vertex AI direct), generates the add-in manifest, and obtains admin consent in a single guided flow. ### Run the setup wizard [Install the plugin](https://github.com/anthropics/financial-services/tree/main/claude-for-msft-365-install) from the financial services marketplace, then run the setup wizard from inside Claude. Add the marketplace in your shell: ```bash theme={null} claude plugin marketplace add anthropics/financial-services ``` Install the plugin: ```bash theme={null} claude plugin install claude-for-msft-365-install@claude-for-financial-services ``` Keep the plugin current before each deployment. List installed plugins with `claude plugin list` and compare your version against the [latest published version](https://github.com/anthropics/financial-services/blob/main/claude-for-msft-365-install/.claude-plugin/plugin.json). If yours is older, update it: ```bash theme={null} claude plugin update claude-for-msft-365-install@claude-for-financial-services ``` Then, from inside Claude, run the setup wizard: ``` /claude-for-msft-365-install:setup ``` The wizard walks you through the path you chose: * **LLM gateway**: collects the gateway URL and token, determines the API format, generates the manifest, handles Azure admin consent. * **Bedrock direct**: creates the IAM OIDC identity provider and role, generates the manifest, handles Azure admin consent. * **Vertex AI direct**: walks through Google OAuth client creation, generates the manifest, handles Azure admin consent. * **Foundry direct**: captures `azure_resource_name` and `azure_api_key`, then generates the manifest. For keyless Entra ID sign-in, add the parameters described in [Foundry direct without an API key](#foundry-direct-without-an-api-key) to the generated manifest. When complete, the add-in is ready for tenant-wide deployment. Bedrock and Vertex AI paths require Node.js for manifest generation and validation. The wizard checks for it and prompts installation if missing. ### Available commands The plugin exposes the following slash commands once installed. | Command | Function | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/claude-for-msft-365-install:setup` | Interactive wizard: provisions cloud resources, handles admin consent, writes manifest. | | `/claude-for-msft-365-install:manifest` | Generates a customized add-in manifest XML. | | `/claude-for-msft-365-install:consent` | Generates the Azure admin-consent URL for the add-in's app registration. | | `/claude-for-msft-365-install:update-user-attrs` | Writes per-user configuration via Microsoft Graph extension attributes. | | `/claude-for-msft-365-install:bootstrap` | Builds a bootstrap endpoint for per-user MCP servers, skills, and dynamic config. | | `/claude-for-msft-365-install:debug` | Diagnoses deployment issues: stale config after a manifest update, connection failures, an add-in that does not appear, sign-in or admin-consent loops, and reading the add-in's error paste. | | `/claude-for-msft-365-install:export-data` | Makes a read-only copy of a user's chat history, skills, connector registrations, and settings before a device is rebuilt. See [Data storage and retention](/docs/office-agents/data-storage). | Run `/claude-for-msft-365-install:debug` whenever a connection or sign-in does not behave as expected. It triages from the symptom, reads the "Copy error details" paste from the connection-failed screen, and explains how each connection path works, so you can resolve most third-party platform questions without escalating. ### What the wizard provisions The setup wizard creates resources in your cloud account based on the connection path you choose. | Path | Provisioned resources | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | LLM gateway | None. Collects your gateway URL and token, then generates the manifest. | | Bedrock direct | IAM OIDC identity provider trusting Microsoft Entra ID tokens, role with `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions, trust policy scoped to the Claude add-in's application ID. | | Vertex AI direct | Walks through creating a Google OAuth client in the GCP Console (not automatable via CLI), enables the Vertex AI API, captures client ID and secret for the manifest. | | Foundry direct | None. Collects resource name and API key for the manifest. | ### Per-user configuration If values vary per user, such as different gateway tokens or AWS roles for different teams, run `/claude-for-msft-365-install:update-user-attrs` with per-user keys after initial setup to write configuration via Microsoft Graph extension attributes. At load, the add-in resolves each configuration key from three sources in order of precedence: a bootstrap endpoint, Microsoft Entra ID extension attributes, then manifest parameters. Per-user attributes override the manifest defaults, so one deployed manifest can serve teams with different settings. The add-in resolves each configuration key from a bootstrap endpoint, then Entra ID extension attributes, then manifest parameters. ### Admin feature controls The `disabled_features` configuration key turns off individual add-in features for your users. It travels over the same three channels as every other key: manifest parameters (comma-separated), Entra ID extension attributes (comma-separated), or a bootstrap endpoint (JSON array), so it can apply org-wide from one manifest or vary per user. | Slug | Effect | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `skills.authoring` | Blocks creating, editing, and uploading skills. Running admin-provisioned skills is unaffected. | | `thumbs` | Blocks response feedback (thumbs up / down and the follow-up prompt). | | `addin.access` | Kill switch: the add-in refuses to run. | | `file.upload` | Blocks attaching files to the conversation. | | `web_search` | Removes the built-in web search and web fetch tools, whose queries are served by Anthropic's search provider, along with the user-facing web search toggle. Code execution is unaffected. | Unknown slugs are ignored, so setting a slug from a newer add-in version on an older deployment is safe. Disabling `web_search` pairs with the `mcp_servers` key: attach your own search tool from a server inside your network, and with the built-in search disabled the model uses the tool you provide. This keeps search queries on infrastructure you control. For document-scoped control, such as disabling a feature only on files carrying certain sensitivity labels, use the `access_policies` key instead; a statement without a resource behaves exactly like `disabled_features`. The setup wizard's `/claude-for-msft-365-install:manifest` and `/claude-for-msft-365-install:access-policies` commands document both keys in full. ### Deploy to Outlook Outlook requires a separate manifest file from Excel, PowerPoint, and Word. Microsoft uses a different add-in schema for mail applications, so the two cannot be combined into one file. When you tell the setup wizard you are deploying to Outlook, it generates a second file named `manifest-outlook.xml` alongside `manifest.xml`. Upload each file as its own custom app in the steps below. Claude for Outlook reads mail and calendar data through Microsoft Graph, which requires a one-time tenant-wide grant from a Global Administrator regardless of which platform serves the model. Complete the [Microsoft Graph admin consent](/docs/office-agents/outlook#grant-microsoft-graph-consent) step before deployment so users are not prompted individually. The Graph token stays in the user's Outlook client and is never sent to your gateway or to Anthropic. If your organization's policy does not permit consenting to a third-party multi-tenant application, register your own single-tenant Entra application with the same delegated Graph permissions and provide its client ID to the setup wizard as `graph_client_id`. See [Use your own Entra app instead](/docs/office-agents/outlook#use-your-own-entra-app-instead). Claude for Outlook on third-party platforms supports Claude Opus 4.7 and later and Claude Sonnet 5 and later. Earlier model generations are not available on the Outlook surface. ### Deploy to Microsoft 365 After the wizard generates your manifest files: Open the Microsoft 365 Admin Center and go to Settings, Integrated apps, Upload custom apps. Select "Office Add-in" as the app type, then upload the `manifest.xml` file. If you are deploying Outlook, repeat this step with `manifest-outlook.xml` as a second custom app. If all users share the same configuration, select "Entire organization". If you wrote per-user attributes, assign to "Specific users/groups" matching exactly who was configured. Others would open the add-in with no configuration. Accept permissions and finish deployment. Propagation to users takes up to 24 hours, usually faster. The add-in appears under Tools, Add-ins on Mac or Home, Add-ins on Windows in Excel, PowerPoint, and Word once deployed. In Outlook it appears in the message ribbon when an email is open. Custom manifest deployment is where most issues surface: the add-in does not appear, users see old configuration after an update, or sign-in fails. Run `/claude-for-msft-365-install:debug` to diagnose these, or to sideload and validate a manifest locally before a tenant-wide upload. Start with a pilot group to confirm functionality, then widen assignment. You can change assignment later without redeploying. ## Serve add-in settings from your Claude organization Anthropic can serve the add-in's configuration to the members of a Claude organization directly, in place of manifest parameters, Microsoft Entra ID attributes, or a bootstrap endpoint. Members sign in with the add-in's standard "Log in" button and their Claude account. The add-in then reads the organization's settings from Anthropic and connects to the gateway or cloud provider those settings name. Prompts and responses still travel only to that provider, never to Anthropic. This option is in preview. It works in Anthropic's preview environments and is not yet enabled for production organizations. Members need the add-in's "Log in" button, which the Microsoft AppSource install and any manifest without connection parameters show. ### How the sign-in works The sequence below is what a member sees. No per-member admin action is needed. 1. The member selects "Log in" on the add-in's sign-in screen and approves the sign-in in the browser with their Claude account. 2. Anthropic's sign-in response identifies the member's organization as one whose add-in settings Anthropic serves. The add-in confirms with Anthropic that the account and organization on the token match that response, stores the sign-in, and reloads the task pane. If the check fails, the add-in discards and revokes the token and shows "Couldn't verify your organization's sign-in." 3. After the reload, the add-in reads the organization's settings from `api.anthropic.com` and opens the connection screen with the served values filled in, such as the gateway URL, API format, authorization header, and available models. When the served settings include every value the connection needs, the add-in connects without further input. Otherwise the member enters the missing value, typically the gateway token from your IT team, and connects. 4. While the member stays signed in, the add-in reads the served settings again at each launch and periodically while it runs, so changes an admin makes apply without redeploying the manifest. ### What served settings control Served settings use the same configuration keys as the manifest and a bootstrap endpoint, including the keys described in [Per-user configuration](#per-user-configuration) and [Admin feature controls](#admin-feature-controls). A few rules are specific to this path: * **Single source**: for a member signed in this way, the served document is the only configuration source. The add-in does not merge it with manifest parameters, Entra ID attributes, or a bootstrap endpoint, and nothing from the task pane URL fills a key the served document leaves out. * **Applied as delivered**: the add-in applies served settings the same way it applies manifest configuration, with no per-setting consent prompt. The Claude organization admin who edits served settings can be a different person from the Microsoft 365 admin who deployed the manifest. * **No bootstrap endpoint**: a member signed in this way uses no bootstrap endpoint at all. If served settings name a `bootstrap_url`, the add-in ignores it and never sends the member's token there. * **Last known settings at reload**: the add-in keeps the most recent served document so a reloading task pane can start on it while it reads the current one. The saved copy is used only for the member and organization it was fetched for, and is replaced as soon as the current document arrives. * **Settings withdrawn**: if Anthropic stops serving settings for the organization, the add-in stops using any saved copy and shows "Claude isn't available for your organization here" until the member signs out. If the first read fails before any settings have arrived, the add-in shows "Couldn't load your organization's settings" with Try again and Sign out actions instead of starting on defaults. ### What the add-in stores for this sign-in The sign-in is an OAuth access token and refresh token that can read the member's profile and the organization's add-in settings. The add-in also sends it with the feature-flag and telemetry requests described in [What Anthropic collects](#what-anthropic-collects) so those requests identify the signed-in member. It carries no inference access, so it cannot be used to send prompts to Anthropic. The add-in stores the token in localStorage within its sandboxed iframe, in the same place and form as a Claude account sign-in, and refreshes it in the background. It is not synced to Anthropic's servers. Unlike a Claude account sign-in, it is also not copied to the Office add-in storage that lets a sign-in carry across Office applications, so a member can be asked to log in again in another Office application or after Office clears the add-in's browser storage. Signing out revokes the token with Anthropic, removes it and the saved settings from storage, and signs the member out of any other open Claude task panes that share that storage. If the browser blocks the add-in's storage, for example when third-party site data is blocked for Office on the web, the add-in refuses the sign-in rather than holding it in memory only. It revokes the token and asks the member to allow site data for the add-in and select "Log in" again. ## Connection instructions for end users ### Claude account with organization-served settings Use these steps if your IT team told you to sign in with your Claude account and your organization's settings are served by Anthropic. Open Excel, PowerPoint, Word, or Outlook and launch the Claude add-in. On the sign-in screen, select "Log in", then approve the sign-in in the browser window that opens. The task pane reloads when the sign-in is accepted. The connection screen opens with your organization's values filled in. If a field such as the gateway token is empty, enter the value your IT team provided, then connect. If every value was served, the add-in connects on its own. If another Claude task pane was already open, it shows "Reload to finish signing in". Select Reload in that pane. ### LLM gateway Open Excel, PowerPoint, Word, or Outlook and launch the Claude add-in. On the sign-in screen, select "Cloud provider or gateway". Then choose your connection: Gateway, Vertex, Bedrock, or Azure. Contact your IT team for connection details if you're unsure which one to select. For Gateway, enter the gateway URL (HTTPS base URL of your LLM proxy, for example `https://llm-gateway.example.com`) and the API token your IT team provided. By default the add-in sends the token in the `x-api-key` header with every request. If your admin set `gateway_auth_header: authorization` in the manifest, the add-in sends `Authorization: Bearer ` instead. The add-in checks the connection by sending a test request to the gateway. On success, you see the main add-in experience. Your credentials are stored locally in your browser's localStorage within the add-in's sandboxed iframe and are not synced to Anthropic's servers. Because the Office add-in runs in a sandboxed iframe within Microsoft applications, it cannot use your OS keychain the way Claude Code does. Only enter gateway-issued tokens, not raw cloud-provider credentials. In this path, every request travels from the add-in to your gateway, which forwards it to the provider you configured. Requests flow from the add-in to your LLM gateway, which forwards them to the configured model provider. ### Bedrock, Vertex AI, or Foundry direct Open Excel, PowerPoint, Word, or Outlook and launch the Claude add-in. For Bedrock (Excel, PowerPoint, and Word only), sign in with your Microsoft work account. The add-in uses your Entra ID token to assume the AWS role your admin configured, so no separate AWS credentials are needed. For Vertex AI, sign in with the Google account your admin authorized via the Google OAuth client created during setup. For Foundry, the add-in connects automatically if your admin pre-filled the Azure resource name and API key. If your admin enabled keyless sign-in, the add-in uses your Microsoft work account and no key is involved. Otherwise, enter the values your IT team provided and select Connect. The add-in reads the configuration your admin provisioned and connects to Bedrock, Vertex AI, or Foundry directly. If you see an error at sign-in, confirm with your IT team that your account is in the group assigned to the add-in. In a direct connection, the add-in authenticates with your identity provider and calls the model provider without an intermediary gateway. The flow differs by provider. Bedrock direct uses your Microsoft Entra ID token to assume an AWS role, then calls Amazon Bedrock. The add-in uses a Microsoft Entra ID token to assume an AWS role and call Amazon Bedrock directly. Vertex AI direct authenticates through Google OAuth, then calls Vertex AI. The add-in authenticates through Google OAuth and calls Google Cloud Vertex AI directly. ### Foundry direct without an API key Instead of a shared resource key, each user can authenticate to your Foundry resource with their own Microsoft Entra ID token. The add-in acquires the token through Nested App Authentication inside Office, sends it to `.services.ai.azure.com` as `Authorization: Bearer`, renews it silently before it expires, and re-authenticates once if Azure rejects a token early. No key is stored on the device and no key is embedded in the manifest. This uses the same Entra app registration that Claude Desktop's in-app Foundry sign-in uses (`inferenceFoundryClientId`), with the add-in's redirect URI added. Set up: 1. In your Entra app registration, add the **Azure Cognitive Services** delegated permission `user_impersonation` and grant admin consent. Register the add-in's redirect URI as described in [Use your own Entra app instead](/docs/office-agents/outlook#use-your-own-entra-app-instead). 2. Grant the users or groups who will sign in the **Cognitive Services User** role on the Foundry resource. 3. Put these parameters in the manifest URL (no `azure_api_key`): | Parameter | Value | | --------------------- | ----------------------------------------------------------- | | `azure_resource_name` | Your Foundry resource name. | | `entra_sso` | `1` | | `graph_client_id` | The application (client) ID of your Entra app registration. | | `entra_scope` | `https://cognitiveservices.azure.com/.default` | | `gateway_auth_source` | `entra` | When `gateway_auth_source=entra` is set, the add-in ignores any `azure_api_key` it receives: the administrator chose keyless sign-in. Each user sees a one-time Microsoft sign-in prompt if silent sign-in is not available; afterwards the add-in connects automatically. ### Change or update your gateway connection If your gateway API token expires or your IT team provides a new URL, go to Settings in the add-in sidebar, enter the new values, and select "Test Connection". This Settings section appears only for gateway connections. For Bedrock, Vertex AI, or Foundry direct, select Logout from the account menu and sign in again with your new credentials. ## Gateway requirements for IT teams The Office add-ins support the same three API formats as Claude Code. Set `gateway_api_format` in your add-in manifest to specify which format your gateway uses. ### CORS requirements The add-in's taskpane loads from `https://pivot.claude.ai`. Every request to your gateway is cross-origin, and the browser silently discards responses lacking CORS headers. Your gateway must return `Access-Control-Allow-Origin: https://pivot.claude.ai` (or `*`) on every response: GET, POST, OPTIONS, and all error responses. Setting it only on the OPTIONS preflight is insufficient. For the preflight, return `Access-Control-Allow-Headers` listing the request headers the add-in sends, such as `x-api-key, authorization, content-type, anthropic-version`. The `*` wildcard does not cover the `Authorization` header per the Fetch specification, so list it explicitly if you set `gateway_auth_header: authorization`. ### Required endpoints The endpoints your gateway must expose depend on which API format it speaks. **`gateway_api_format: anthropic` (default):** | Endpoint | Description | | ------------------- | ----------------------------------------------------------------------------- | | `POST /v1/messages` | Send messages to Claude; supports both streaming and non-streaming responses. | | `GET /v1/models` | List available models. | **`gateway_api_format: bedrock`:** | Endpoint | Description | | ---------------------------------------------------- | -------------------------------------------- | | `POST /model/{model-id}/invoke` | Send message and receive complete response. | | `POST /model/{model-id}/invoke-with-response-stream` | Send message and receive streaming response. | Native Bedrock `InvokeModel` pass-through. `gateway_url` must point at the pass-through prefix, for example `https://litellm.example.com/bedrock`. **`gateway_api_format: vertex`:** | Endpoint | Description | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `POST /projects/{project}/locations/{region}/publishers/anthropic/models/{model-id}:rawPredict` | Send message and receive complete response. | | `POST /projects/{project}/locations/{region}/publishers/anthropic/models/{model-id}:streamRawPredict` | Send message and receive streaming response. | Native Vertex pass-through. `gateway_url` must include the API-version segment, for example `https://litellm.example.com/vertex_ai/v1`. Also requires `gcp_project_id` and `gcp_region` so the add-in can build the path. ### Required header For `anthropic` format, the gateway must forward the `anthropic-version` request header to the upstream provider. For `bedrock` and `vertex` formats, the SDK places `anthropic_version` in the request body instead. The gateway must preserve it there. Failure to forward the header or preserve the body field may result in reduced functionality or prevent the add-in from working. ### Authorization header The add-in can send your gateway's authorization token in either the `x-api-key` header or the `Authorization` header. The default is `x-api-key`. To switch to `Authorization: Bearer`, set `gateway_auth_header: authorization` in the manifest. ### Model discovery For gateways using `gateway_api_format: anthropic`, the add-in attempts to discover available Claude models via `GET /v1/models` on login. If your gateway doesn't expose a model list at that path, the add-in falls back to prompting the user for a model ID manually. For `gateway_api_format: bedrock` and `gateway_api_format: vertex`, the add-in uses a built-in model list and probes the gateway to verify each model is reachable, rather than calling `GET /v1/models`. ### Differences from Claude Code gateway setup If your team already runs Claude Code through a gateway, the table below summarizes how the Office add-in setup differs. | Aspect | Claude Code | Office add-ins | | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Credential storage | OS keychain or environment variables | Browser localStorage (sandboxed iframe) | | Auth configuration | Environment variables, settings file, helper scripts | Manual entry in add-in UI (gateway), Entra ID (Bedrock, keyless Foundry), Google OAuth (Vertex AI), or Azure API key (Foundry) | | Token refresh | Supports helper scripts for rotation | Automatic via a bootstrap endpoint (gateway), Entra ID (Bedrock, keyless Foundry), or Google OAuth (Vertex AI); gateway tokens entered manually in the add-in UI require re-entry in settings | | Custom model names | Configurable via environment variables | Not configurable in v1 | When gateway configuration comes from a bootstrap endpoint, the add-in keeps the token current without user action. It calls the bootstrap endpoint again about five minutes before the expiry declared in the bootstrap response and applies the returned token to the running session. If the gateway rejects a request as unauthorized before that expiry, the add-in calls the bootstrap endpoint once and retries the request if the token changed. Gateway tokens entered manually in the add-in UI do not refresh automatically: update the token in settings when it rotates. ## Example gateway configuration with LiteLLM LiteLLM PyPI versions 1.82.7 and 1.82.8 contained credential-stealing malware. Do not install those versions. If already installed, remove the package, rotate all credentials on affected systems, and follow remediation steps in [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518). LiteLLM is a third-party proxy service. Anthropic does not endorse, maintain, or audit LiteLLM's security or functionality. This section is informational and may become outdated. Use at your own discretion. The example configurations below route Office add-in requests through LiteLLM to Anthropic, Bedrock, Vertex AI, or Azure. ### Route to Anthropic directly Use this `config.yaml` to point the gateway at the Anthropic API. ```yaml theme={null} model_list: - model_name: claude-opus-4-7 litellm_params: model: claude-opus-4-7 api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true ``` ### Route to Amazon Bedrock Use this `config.yaml` to route requests through Amazon Bedrock. ```yaml theme={null} model_list: - model_name: claude-opus-4-7 litellm_params: model: bedrock/us.anthropic.claude-opus-4-7 aws_region_name: us-east-1 litellm_settings: drop_params: true ``` ### Route to Google Cloud Vertex AI Use this `config.yaml` to route requests through Vertex AI. ```yaml theme={null} model_list: - model_name: claude-opus-4-7 litellm_params: model: vertex_ai/claude-opus-4-7 vertex_project: your-gcp-project-id vertex_location: us-east5 litellm_settings: drop_params: true ``` ### Route to Azure Use this `config.yaml` to route requests through Azure AI Foundry. ```yaml theme={null} model_list: - model_name: claude-opus-4-7 litellm_params: model: azure_ai/claude-opus-4-7 api_base: https://your-resource.services.ai.azure.com/anthropic api_key: os.environ/AZURE_API_KEY extra_headers: x-api-key: os.environ/AZURE_API_KEY litellm_settings: drop_params: true ``` For detailed setup instructions, see [LiteLLM's Anthropic format documentation](https://docs.litellm.ai/). ## What Anthropic collects Even when inference goes through your own infrastructure, the add-in communicates with `pivot.claude.ai` to load its interface and with `claude.ai/api/` to evaluate feature flags. These connections transmit operational telemetry such as which features are used, performance timings, and error rates, so Anthropic can maintain and improve the add-in experience. They do not transmit your prompts or Claude's responses. Anthropic collects information in accordance with Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Azure's terms, consistent with Anthropic's arrangements with customers. Anthropic does not have access to a customer's AWS, Google, or Microsoft instance, including prompts or outputs it contains. Anthropic does not train generative models with such content or use it for other purposes. Anthropic can access metadata such as tool use and token counts, and uses such metadata for analytic and product-improvement purposes. For details on what your organization's gateway or cloud provider logs, contact your IT team. To route a full audit trail, including prompts, tool inputs, tool outputs, and document references, to your own infrastructure, see [Configure a custom OpenTelemetry collector](/docs/office-agents/opentelemetry). That page covers the `otlp_endpoint`, `otlp_headers`, and `otlp_attr_max_chars` configuration keys, the CORS requirements for the collector endpoint, and the full span reference. ## Why sign-in redirects through pivot.claude.ai During Google sign-in for Vertex AI, Anthropic sign-in, or Microsoft admin consent, your identity provider redirects the browser to `https://pivot.claude.ai/auth/callback`. Security reviewers sometimes ask whether this means access tokens for your cloud provider or mailbox pass through Anthropic's servers. They do not. This section explains what the redirect carries in each flow and why the page cannot obtain a token. ### OAuth authorization-code redirects Google sign-in for Vertex AI and Anthropic sign-in use the OAuth 2.0 authorization-code grant and redirect to `pivot.claude.ai/auth/callback`. MCP connector authorization uses the same grant with a dedicated `pivot.claude.ai/auth/gateway-callback` redirect. In each case the URL contains two query parameters: * `code`: a one-time authorization code, not an access token * `state`: a random value the add-in generated before sign-in started The callback page is a static page served from `pivot.claude.ai`. It reads those two parameters from the URL, shows a Copy button, and instructs you to paste the value back into the add-in inside Office. The page has no server-side logic that stores, forwards, or exchanges the code. An authorization code on its own cannot be redeemed for an access token. The token endpoint requires an additional secret that only the add-in running on your machine holds: * **Anthropic sign-in and MCP connector authorization**: a Proof Key for Code Exchange (PKCE) verifier. The add-in generates a random verifier locally, sends only its SHA-256 hash to the identity provider when sign-in starts, and keeps the verifier in browser session storage. The token endpoint rejects any exchange that does not present the original verifier. * **Google sign-in for Vertex AI**: the `client_secret` belonging to the Google OAuth client your organization created during setup. This value is provisioned into the add-in's configuration on each user's machine and is sent only to `oauth2.googleapis.com` during token exchange. Anthropic does not have this value. The add-in also verifies that the `state` value pasted back matches the one it generated and stored locally before sign-in. A mismatch is rejected. This prevents an attacker from tricking a user into completing a sign-in the attacker initiated. After the add-in exchanges the code, the resulting access and refresh tokens are held in the browser's local storage inside the Office add-in sandbox. The add-in presents the access token only to the inference or MCP-proxy endpoint for your sign-in path, and presents the refresh token only to the OAuth token endpoint. Each of these endpoints appears in the [Network allowlist](#network-allowlist). These tokens never reach `pivot.claude.ai`. ### Why the redirect cannot target localhost Office add-ins run inside a sandboxed browser frame hosted by Microsoft 365\. There is no local web server to receive a loopback redirect, and the browser tab that handles sign-in is isolated from the add-in frame's storage. The redirect must therefore target a registered HTTPS URL, and the callback page at `pivot.claude.ai` bridges the two contexts by displaying the code for you to paste back into the add-in. ### Microsoft admin-consent redirects The Microsoft Graph consent link in [Grant Microsoft Graph consent](/docs/office-agents/outlook#grant-microsoft-graph-consent) uses Microsoft's [admin-consent endpoint](https://learn.microsoft.com/en-us/entra/identity-platform/v2-admin-consent). By Microsoft's specification, the redirect back to `pivot.claude.ai/auth/callback` carries only the consent outcome: an `admin_consent` boolean and the `tenant` ID. It never carries an access token or an authorization code. The callback page displays a confirmation message and nothing else. The Microsoft Graph access token itself is obtained separately through [Nested App Authentication](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/enable-nested-app-authentication-in-your-add-in), where the Office host brokers the token directly into the add-in on the user's machine. The Microsoft Authentication Library (MSAL) caches it in the browser's local storage, and the add-in calls `graph.microsoft.com` directly. The Graph token never reaches `pivot.claude.ai` or any other Anthropic endpoint. ### Identify Anthropic's Microsoft Entra application The admin consent link and Nested App Authentication both use a single multi-tenant application that Anthropic publishes in Microsoft Entra ID. When you review the consent prompt or the resulting enterprise application in your tenant, confirm it matches these values. | Field | Value | | ----------------------- | ---------------------------------------- | | Display name | Claude for Office | | Application (client) ID | `c2995f31-11e7-4882-b7a7-ef9def0a0266` | | Publisher | Anthropic, PBC (verified publisher) | | Supported account types | Accounts in any organizational directory | The add-in uses the following redirect URIs with this application. Each one exists for a specific Microsoft sign-in path, and none of them receives a Microsoft access token in the URL. | Redirect URI | Platform | Purpose | | -------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `https://pivot.claude.ai/auth/callback` | Web | admin consent confirmation page, receives only `admin_consent` and `tenant` from Microsoft. Google sign-in for Vertex AI reuses this URI for its [OAuth authorization-code redirect](#oauth-authorization-code-redirects) | | `https://pivot.claude.ai/msal-redirect.html` | Single-page application | MSAL response bridge for Office on the web, where the host cannot broker tokens natively | | `brk-multihub://pivot.claude.ai` | Single-page application | Nested App Authentication broker on Office desktop and Mac | | `https://pivot.claude.ai/auth/3p` | Web | legacy entry from earlier builds, not used by current builds, scheduled for removal | ### Verify this in your own environment You can confirm every claim above with a network capture on a test machine: * The redirect to `pivot.claude.ai/auth/callback` carries `code` and `state`, or `admin_consent` and `tenant`, in the query string. For an MCP connector the redirect to `pivot.claude.ai/auth/gateway-callback` carries `code` and `state`. No `access_token` parameter appears. * The `POST` that exchanges the code goes to `oauth2.googleapis.com` for Vertex AI, to `claude.ai` for Anthropic sign-in, or to the connector gateway's own origin for an MCP connector, originates from the add-in frame, and includes the `code_verifier` or `client_secret` that never appeared in any request to `pivot.claude.ai`. * Microsoft Graph calls go directly to `graph.microsoft.com` with a bearer token that was issued by `login.microsoftonline.com` and never transited an Anthropic domain. ## Differences from signing in with a Claude account When you sign in with a Claude account, the add-ins connect directly to Anthropic. When you connect through a third-party platform, the add-ins send inference requests to your organization's infrastructure instead, and your IT team controls how that traffic is routed and logged. Some features that rely on a Claude account are not available through third-party platforms yet. Support is being added. A member who signs in with a Claude account to an organization whose settings Anthropic serves is in the third-party platform column too, because inference goes to the organization's provider. | Feature | Claude account | Third-party platform | | ------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------- | | Chat with your spreadsheet, deck, document, or email | Yes | Yes | | Read and edit cells, slides, formulas, and document text | Yes | Yes | | Read, search, and triage your mailbox and calendar (Outlook) | Yes | Yes | | Connectors (S\&P, FactSet, and others) | Yes | Coming soon | | Working across apps | Yes | No | | Dictation | Yes | No | | Skills | Yes | Coming soon | | File uploads | Yes | No | | Web search | Yes | Vertex direct, Foundry direct, and gateways the add-in detects as routing to a Foundry-compatible upstream | | Code execution | Yes | Foundry direct, and gateways the add-in detects as routing to a Foundry-compatible upstream | If your team needs these features, talk to your Claude admin about which sign-in path fits your organization. ## Troubleshooting ### "Connection refused" or network error The gateway URL or cloud endpoint is unreachable from the user's network. Verify the URL is correct, the service is running, and there are no firewall or VPN restrictions blocking the connection. Check the [Network allowlist](#network-allowlist) to confirm all required domains are allowed. ### 401 Unauthorized or "Invalid token" The auth token is invalid or expired. For gateway connections, confirm the token with your IT team. For direct-cloud connections, verify the user's Entra ID account is in the assigned group and that the OIDC trust or OAuth client is configured correctly. For Foundry with an API key, regenerate the key in Azure Portal, Keys and Endpoint. For keyless Foundry sign-in, confirm the Entra app has the Azure Cognitive Services `user_impersonation` permission with admin consent and that `entra_scope` is `https://cognitiveservices.azure.com/.default`. ### 403 Forbidden or "Access denied" The token is valid but lacks the right permissions. For Bedrock, verify the IAM role has `bedrock:InvokeModel` permissions. For Vertex, verify your Google account has the Vertex AI User role on the project. For gateways, check the token's scope with your IT admin. For Foundry, check the resource's networking rules, or confirm the key belongs to the right resource. For keyless Foundry sign-in, confirm the user holds the Cognitive Services User role on the resource. ### 404 Not found The add-in could not reach the expected API path. For gateways, verify the URL is the base URL such as `https://litellm.example.com:4000`. Don't include `/v1/messages` in the URL field. ### 500 or other server errors The gateway or cloud provider encountered an internal error. Check your gateway logs, such as `docker logs litellm` for LiteLLM, for upstream provider errors. Try the request again, and contact your IT admin if the issue persists. ### "No models available" The add-in could not find Claude models. For gateways using `gateway_api_format: anthropic`, your gateway may not expose a model list at `GET /v1/models`; your IT team can configure the gateway to serve a model list or give you a specific model ID to enter manually. For gateways using `gateway_api_format: bedrock` or `vertex`, none of the built-in models responded to the add-in's probe; confirm with your IT team that the gateway routes to a region or project with Claude models enabled. For Bedrock or Vertex direct, confirm that at least one Claude model (Claude Sonnet 4.5 or later) is enabled in your account and region. For Foundry, confirm at least one Claude model is deployed in the resource Model catalog. ### Streaming responses fail or hang Verify that your gateway supports Server-Sent Events (SSE) pass-through. Some proxy configurations strip or buffer SSE connections, which prevents streaming responses from reaching the add-in. ### A feature I expected is not available Connectors, Skills, file uploads, dictation, and working across apps are not available through third-party platforms yet. If you need these, ask your admin about signing in with a Claude account instead. # Use Claude for Word Source: https://claude.com/docs/office-agents/word A Word add-in that integrates Claude into your document workflow, for Pro, Max, Team, and Enterprise plans. Claude for Word is an add-in that brings Claude into Word. Ask questions about your document with clickable section citations, edit selected passages while preserving formatting, review counterparty redlines, work through comment threads, and fill templates in your document's styles. Claude for Word is generally available to Pro, Max, Team, and Enterprise plans. ## What you can do With Claude for Word, you can: * Ask questions about your document and get answers with clickable section citations. * Edit selected text while preserving surrounding styles, numbering, and formatting. * Use tracked changes mode so every edit lands as a revision you can accept or reject in Word's native review pane. * Have Claude work through comment threads, editing the anchored text and replying with what it changed. * Summarize counterparty redlines and flag the revisions worth pushing back on. * Fill templates with drafted content that inherits your document's heading and paragraph styles. * Find every provision touching a theme with semantic navigation, not just keyword search. ## Get started with Claude for Word ### Supported versions Claude for Word runs on the following Word builds. * Word on the web * Word on Windows with a Microsoft 365 subscription, Version 2205, build 15202.10000 or later * Word on Mac, version 16.61, build 22040100 or later ### Install for yourself Go to the [Claude for Microsoft 365 listing on Microsoft AppSource](https://marketplace.microsoft.com/en-us/product/office/WA200010725?tab=Overview). Select "Get it now" to install. Open Word, activate the add-in, and sign in with your Claude account. ### Deploy to your organization Organization admins can deploy Claude for Word through the Microsoft 365 Admin Center. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), go to Settings, Org Settings, User owned apps and services, and turn on ["Let users access the Office Store"](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-addins-in-the-admin-center). Go to Settings, Integrated apps, Add-ins. Search for "Claude for Microsoft 365" in Microsoft AppSource. Assign the add-in to your organization or to specific users or groups. Share [Microsoft's deployment guide](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins) with your team for activation steps. If your organization uses Microsoft Entra Privileged Identity Management (PIM) for admin roles, the Integrated apps page does not recognize roles activated through PIM, so deployment fails. This is a [known Microsoft issue](https://learn.microsoft.com/en-us/office/dev/add-ins/resources/resources-office-add-in-known-issues), tracking ID 11126536. To work around it, deploy from an admin account with the required role assigned as permanently active rather than PIM-eligible. See [Microsoft's troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/microsoft-365/admin/miscellaneous/cannot-deploy-add-in-integrated-apps-menu). Individual users can still [install the add-in themselves](#install-for-yourself). After deployment, users can activate the Claude add-in from Tools, Add-ins on Mac or Home, Add-ins on Windows, sign in, and start working. Organizations that have disabled "Let users access the Office Store" may find that admin-deployed add-ins don't appear for users. To work around this, deploy using the manifest XML file described below. ### Deploy with a custom manifest For IT administrators deploying to multiple users when the Office Store is disabled: Download the [custom manifest XML file](https://pivot.claude.ai/manifest-word.xml) and save it to a secure location. Go to [https://admin.microsoft.com](https://admin.microsoft.com), sign in, and open Settings, Integrated apps. Select "Upload custom apps", choose "Office Add-in", then "I have a manifest file on this device". Upload the manifest. Choose entire organization, specific users, specific groups, or just yourself for admin testing. Review settings and select "Deploy". The add-in is available within minutes. Full organization rollout can take up to 24 hours. After deployment, users see Claude in Word's Home ribbon and sign in with their Claude credentials on first use. ### Connect through a third-party platform If your organization routes AI traffic through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, your admin can deploy the add-in without individual Claude accounts. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms). ## Key features ### Read and understand documents Ask Claude questions about specific sections, clauses, or defined terms in your document. Claude provides answers with clickable citations that navigate directly to the referenced section. Claude recognizes common document patterns including multi-level legal numbering, defined terms, cross-references, and standard contract structures. Verify that outputs match your specific requirements and your firm's standard positions. Example prompts: * "What's the liability cap and is it mutual?" * "Summarize the key commercial terms in this agreement." * "What assumptions drive the revenue forecast in section 3?" ### Edit selected text Select a passage and tell Claude what to change. Claude edits only the selection while preserving surrounding styles, numbering, and formatting. New text inherits the paragraph style, font, and numbering of the surrounding content. Example prompts: * "Tighten this paragraph and drop the passive voice." * "Rewrite this clause to make the indemnification mutual." * "Simplify this section for a non-technical audience." ### Tracked changes mode When you enter tracked changes mode, Claude's edits land as tracked revisions. The original text is visible as a deletion and the new text as an insertion, all reviewable in Word's native review pane. Review every edit before accepting it, and undo with Word's standard Ctrl+Z on Windows or Cmd+Z on Mac if you want to revert. Example prompts: * "Rewrite section 4.2 to cap damages at 12 months of fees, and make it mutual." * "Draft a mutual indemnification clause after section 8." ### Comment-driven editing Claude reads comment threads in your document, understands what text each thread is anchored to, and can work through them one by one. For each comment, Claude edits the anchored passage and replies to the thread with a note explaining what it did. Example prompts: * "Work through my open comments." * "Address the comment on the liability section." ### Summarize counterparty redlines When a counterparty returns a document with tracked changes, Claude can read and summarize what they changed. Ask Claude to group changes by severity or flag the ones worth pushing back on. Example prompts: * "Summarize what the other side changed and flag anything that's worth discussing." * "Which of these redlines are dealbreakers?" ### Fill templates Draft sections in your document's heading and paragraph styles. Claude uses your template's formatting when generating content, so new headings, bullets, and table entries match what's already there. Tables populate in place without reflowing layout or changing column widths. Example prompts: * "Draft the Key Risks section with four risks in the template's style." * "Populate the summary table with revenue, gross margin, and net retention for the last three years." ### Semantic navigation Find every provision or passage in your document that touches a specific theme. Claude returns thematic matches, not just keyword hits, and each result navigates to the relevant location on click. Example prompts: * "Find every provision touching data retention." * "Where does this agreement address termination?" ## Connectors and Skills Claude for Word supports connectors for pulling external context into your document, and Skills for applying reusable task recipes. See [Connectors and Skills](/docs/office-agents/connectors-and-skills) for details. ## Set persistent instructions Open Settings in the add-in sidebar and use the Instructions field to set preferences that apply to every conversation in Word. Instructions are useful for tone and style conventions such as "use formal tone" or "follow APA citation style", document structure preferences, or recurring context about your workflow. Instructions you set in Word only apply to Word. They are separate from Instructions you set in Excel or PowerPoint. ## Work across M365 apps Claude for Word shares context with Claude for Excel, PowerPoint, and Outlook, so a single conversation can span your open document, workbook, deck, and inbox. See [Work across M365 apps](/docs/office-agents/work-across-apps). ## Context and session management The add-in handles long sessions for you so a single conversation can span an entire workflow. * **Auto-compaction**: longer conversations are automatically compacted into new conversations to avoid running out of context. See [Understanding usage and length limits](https://support.claude.com/en/articles/11647753-understanding-usage-and-length-limits). Your use of Claude for Word is associated with your existing Claude account and is subject to the same usage limits. ## Models available Claude for M365 offers a curated subset of the Claude models: the ones that work best for Office tasks, so the list you see in the add-in can be shorter than what you see in Claude.ai. Your organization's model access settings also apply, and a model appears here only if your role permits it. See [Manage model access for your organization](https://support.claude.com/en/articles/15694740-manage-model-access-for-your-organization) for how those settings interact with each product. If you connect through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway, the available models come from that platform and your admin's configuration instead of your Claude.ai model access settings. See [Use Claude for M365 with third-party platforms](/docs/office-agents/third-party-platforms) for details. ## Data handling Inputs and outputs are deleted on the backend within 30 days of receipt or generation, except in cases outlined in [How long do you store my organization's data?](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). Data is cached for a number of hours after deletion so users can access context in recently closed documents. Chat history is stored locally in your browser using IndexedDB. Conversations are not stored on Anthropic's servers, are not synced across devices, and can be cleared from Settings at any time. Reinstalling the add-in or switching between Claude add-ins does not remove it. See [Data storage and retention](/docs/office-agents/data-storage) for where it sits on disk and how long it is kept. Claude for Word does not inherit custom data retention settings your organization might have set. Activity is not included in Enterprise audit logs. For Enterprise organizations with the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, Claude for Word sessions are included in the Compliance API. This coverage is in public beta and requires no additional setup: the same Compliance Access Keys apply. Claude reads the content of your currently open document, including text, comments, tracked changes, footnotes, tables, and bookmarks. It only accesses the document you have open in Word. For highly sensitive or regulated data, follow your organization's data handling policies. ## Current limitations Claude for Word is not recommended for: * Final client deliverables or counterparty sends without human review. * Litigation filings or audit-critical documents without verification. * Replacing legal or financial judgment. * Documents containing highly sensitive or privileged data without proper controls. ### Unsupported versions The add-in does not run on these Word versions. * Word 2016 and 2019 perpetual or volume license. * Word on iPad. * Word on Android. * Microsoft 365 Word builds older than Version 2205 on Windows or version 16.61 on Mac. * Legacy `.doc` files. Save as `.docx` first. ## Prompt injection risk Only use Claude for Word with trusted documents. Documents from external sources such as downloaded templates, counterparty files, or files shared via email can contain hidden instructions that manipulate the add-in into extracting data, modifying records, or performing destructive actions. Prompt injection attacks hide malicious instructions in document content such as text, comments, tracked changes, headers, and footers to trick Claude into taking unintended actions. Testing has identified scenarios where Claude for Word can be manipulated to: * Extract and share sensitive information through web searches containing your sensitive data or file system access that exposes proprietary information. * Modify critical content such as contract terms or financial figures. * Perform destructive actions without verification when allowed to act unsupervised. When Claude proposes a risky operation, you are asked to confirm before it runs. Review confirmations carefully, especially for content from external sources. ## Best practices Follow these guidelines to use Claude for Word safely and effectively. * Always review tracked changes before accepting them. * Verify that outputs match your firm's playbook and standard positions. * Use appropriate permissions and access controls. * Maintain human oversight for client-facing work. ## Example use cases ### Legal contract review Prompts that review and revise contracts and counterparty redlines. * "Summarize the key commercial terms: parties, term, governing law, and anything off-market." * "Flag provisions that deviate from standard market position, ranked by severity." * "Make the indemnification mutual and insert our standard fallback language." * "Work through all five reviewer comments as tracked changes." * "What did the counterparty change, and which revisions are dealbreakers?" ### Finance memo drafting Prompts that build out investment memos and finance writeups. * "Draft the Investment Thesis section with three points, pulling the numbers from the uploaded 10-K." * "Populate the summary table with revenue, gross margin, and FCF for the last three years." * "Too generic on point two. Use the customer count from the deck." * "Address the partner's comment on the Risks section." ### Document QA and consistency Prompts that check a document for internal consistency and quality. * "Flag inconsistent defined terms and broken cross-references." * "Check the numbering scheme for gaps." * "Proofread for spelling, grammar, and punctuation." * "Is the same party referred to by different names anywhere in this document?" ### General document editing Prompts that tighten or restructure prose. * "Tighten section 4 and drop the passive voice." * "Rewrite this for a non-technical audience." * "Add a fourth risk addressing customer concentration." * "Define this term and use it consistently throughout." # Work across M365 apps Source: https://claude.com/docs/office-agents/work-across-apps Let Claude read from one Microsoft 365 app and make changes in another in a single conversation. Claude can coordinate between the Excel, PowerPoint, Word, and Outlook add-ins in your Microsoft 365 suite. Instead of switching between apps and re-providing context each time, Claude can read from one app and make changes in another. Working across apps is available when you sign in with your Claude account directly. It is not supported when connecting through Amazon Bedrock, Google Cloud Vertex AI, Azure AI Foundry, or an LLM gateway. ## Requirements Install each Claude for M365 add-in and confirm your plan before turning on cross-app mode. * A paid Claude plan: Pro, Max, Team, or Enterprise. * [Claude for Excel](/docs/office-agents/excel) installed from the Microsoft AppSource. * [Claude for PowerPoint](/docs/office-agents/powerpoint) installed from the Microsoft AppSource. * [Claude for Word](/docs/office-agents/word) installed from the Microsoft AppSource. * [Claude for Outlook](/docs/office-agents/outlook) installed from the Microsoft AppSource. ## Enable cross-app mode Install Claude for Excel, PowerPoint, Word, and Outlook from the Microsoft AppSource. Open each app and activate the add-in at least once before using cross-app features. Open Settings in each add-in and turn on "Let Claude work across files". Pro and Max plans have this on by default; Team and Enterprise plans default to off. The toggle is per-device, so enable it in every host you want to coordinate from. Once enabled, connected-app indicators appear in the sidebar when other Excel, PowerPoint, Word, or Outlook sessions are linked. ## How it works When you describe a task that involves multiple files or apps, Claude coordinates automatically: * Claude uses the Excel, PowerPoint, Word, and Outlook add-ins to read from and write to open files and email threads. * Context transfers between apps automatically, so you don't need to copy and paste information manually. You stay in one place while Claude does the switching. ## What you can do ### Read and write across open apps Claude can read data from an open Excel workbook, PowerPoint presentation, Word document, or Outlook email thread, and make changes to them directly. For example: * Pull numbers from an Excel model into a PowerPoint slide or a Word memo. * Update a chart in PowerPoint with the latest figures from Excel. * Read content from a presentation and use it to populate a spreadsheet. * Summarize a Word document into PowerPoint slides. * Draft a Word memo using data from an Excel workbook. * Open an attached letter of intent in Word with the Outlook thread already loaded as context. * Pull figures from an email thread into an open Excel model. ### Pass context between apps Claude carries relevant context forward when working across multiple files. If you've been building a financial model in Excel and ask Claude to create a summary deck or draft an investment memo, Claude already understands the model's structure and key outputs, so you don't need to re-explain. ## Skills work across apps Skills you've enabled in your Claude settings apply when Claude is working in Excel, PowerPoint, Word, or Outlook during a cross-app task. If you have a Skill that enforces your team's modeling conventions in Excel and another that matches your slide template in PowerPoint, Claude uses each one in the right app as it moves through the workflow. For more on Skills, see [Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude). ## Manage access as an admin Team and Enterprise organization owners can control whether team members can access this capability. Go to Organization settings, Office agents. Turn "Let Claude work across apps" on or off. Admins can also manage member access to the Claude for Excel, PowerPoint, Word, and Outlook add-ins through the Microsoft 365 Admin Center. ## Data handling Inputs and outputs are deleted from Anthropic's backend within 30 days of receipt or generation, except in cases outlined in [How long do you store my organization's data?](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data). The Claude for M365 add-ins do not inherit custom data retention settings your organization may have set, and activity is not included in Enterprise audit logs or data exports. For Enterprise organizations with the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) enabled, add-in sessions are included in the Compliance API. This coverage is in public beta and requires no additional setup: the same Compliance Access Keys apply. Chat history is stored locally in your browser, not on Anthropic's servers, and can be cleared from Settings at any time. ## Current limitations * Claude can only read from and write to files that are currently open in Excel, PowerPoint, or Word, and the email or event currently open in Outlook. * Claude cannot create, open, close, or switch files directly. The files and add-ins must be open with the feature turned on. ## Troubleshooting ### Claude doesn't see my open file Make sure the add-in is activated in the app (Tools, Add-ins on Mac or Home, Add-ins on Windows) and that working across apps is turned on in the add-in settings. ### Changes aren't appearing in the other app Claude works on open files in sequence. Wait for Claude to finish its current action, then check the target file. You may need to ask Claude to refresh or re-read the file. # Plugins overview Source: https://claude.com/docs/plugins/overview Extend Claude with reusable capability packages that bundle MCP connectors, skills, slash commands, and sub-agents Plugins are reusable capability packages that extend Claude with custom functionality. They bundle together [MCP connectors](/docs/connectors/overview), [skills](/docs/skills/overview), slash commands, and sub-agents into a single shareable unit — turning Claude into a specialist tailored to your role, team, and company. ## What plugins do Plugins let you define how you like work done, which tools and data to pull from, how to handle critical workflows, and what slash commands to expose so your team gets consistent outcomes. Every component is file-based, so plugins are easy to build, edit, and share. As your team builds and shares plugins, Claude becomes a cross-functional expert. Best practices get baked into every interaction, so leaders and admins can spend less time enforcing processes and more time improving them. ## Plugin directory To help you get started, Anthropic has open-sourced 11 plugins built and used internally: | Plugin | What it does | | ---------------------- | ------------------------------------------------------------- | | **Productivity** | Manage tasks, calendars, and daily workflows | | **Enterprise search** | Find information across your company's tools and docs | | **Sales** | Research prospects, prep deals, and follow your sales process | | **Finance** | Analyze financials, build models, and track key metrics | | **Data** | Query, visualize, and interpret datasets | | **Legal** | Review documents, flag risks, and track compliance | | **Marketing** | Draft content, plan campaigns, and manage launches | | **Customer support** | Triage issues, draft responses, and surface solutions | | **Product management** | Write specs, prioritize roadmaps, and track progress | | **Biology research** | Search literature, analyze results, and plan experiments | | **Plugin Create** | Create and customize new plugins from scratch | Browse the full collection at [claude.com/plugins](https://claude.com/plugins-for/cowork) or use the Plugin Create plugin to build your own. ## Origins in Claude Code Plugins originated in [Claude Code](https://code.claude.com/docs/en/plugins), where developers create and distribute them as versioned, shareable directories. A Claude Code plugin lives in a directory with a manifest (`plugin.json`) that defines its identity, version, and available components. For technical details on plugin structure, manifests, and configuration, see the [Claude Code plugins reference](https://code.claude.com/docs/en/plugins-reference). ## Plugins in Cowork Plugins are fully supported in [Cowork](https://support.claude.com/en/articles/13345190-getting-started-with-cowork), Anthropic's agentic workspace for complex, multi-step knowledge work. In Cowork, Claude runs inside an isolated virtual machine environment, executes tasks in parallel workstreams, and writes outputs directly to your file system — and plugins extend all of that capability. A sales plugin, for example, could connect Claude to your CRM and knowledge base, teach it your sales process, and give you slash commands for everything from prospect research to call follow-ups. You define what goes in the plugin once, and Claude pulls from that context whenever it's relevant. ## How plugins compose capabilities | Plugin component | What it adds | Example | | ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **Skills** | Specialized instructions Claude follows when relevant tasks arise | A "brand voice" skill that activates when drafting external communications | | **MCP connectors** | Access to external tools and data | A connector to a CRM that lets Claude read and update deal records | | **Slash commands** | Explicit, user-triggered workflows | `/sales:prospect-research` to kick off a structured research workflow | | **Sub-agents** | Delegated workstreams that run in parallel | A sub-agent that handles competitive analysis while another drafts the proposal | ## Availability Plugin support in Cowork is available as a beta for all paid Claude users. Plugins are currently saved locally to your machine. Org-wide sharing and management are coming in the weeks ahead. | Platform | Plugin support | | ----------------- | ------------------------------------------------------------------ | | **Claude Code** | Full plugin support — create, install, and use plugins | | **Claude Cowork** | Full plugin support — plugins extend agentic, multi-step workflows | Looking to submit your own plugin? See [Submitting your plugin](/docs/plugins/submit#submitting-your-plugin). ## Next steps Browse the full plugin collection. Build and distribute plugins in Claude Code. Learn how skills work as a core plugin component. Understand MCP connectors that plugins can bundle. # Submitting your plugin Source: https://claude.com/docs/plugins/submit Submit your plugin to the plugin directory for Cowork The [plugin directory](https://claude.com/plugins-for/cowork) is a community-driven directory where developers can submit plugins for use in Cowork and Claude Code. In Claude Code, this directory is surfaced as the official `claude-plugins-official` marketplace and is automatically available to all users — see [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins#official-anthropic-marketplace). This is a separate and complementary directory from the [Connectors Directory](/docs/connectors/directory), which is specific to MCP connectors. ## Getting your plugin to users Once you've built a plugin, there are several ways to get it to users: 1. **Direct install** — You can install specific plugins yourself, or guide select users to install them. This is the simplest path for internal tools or small teams. 2. **Your own plugin marketplace** — You can serve your own [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces), which allows a subset of opted-in users to access any plugin you share. This is a great fit for enterprise contexts or communities with shared tasks. See the [Claude Code docs on sharing a marketplace](https://code.claude.com/docs/en/plugin-marketplaces) for setup instructions. 3. **[Submit to the Claude plugin directory](#submitting-your-plugin)** — You can submit to the Claude plugin directory, which is made available to all users of Cowork and Claude Code. ## Plugin Directory: Community vs. Anthropic Verified Plugins are submitted by developers and creators in the community. Anthropic performs basic automated review on submissions before adding them to the directory. Plugins with an "Anthropic Verified" badge have undergone additional review from a quality and safety perspective. That said, there are limits to what Anthropic is able to review — you should only install plugins from developers you trust. There are no guarantees that any community plugin will become Anthropic Verified. Exercise caution when installing community plugins. Always review a plugin's permissions, connected services, and data access before use. ## What makes a good plugin The best plugins bundle related capabilities together into a coherent package that solves a specific job function or workflow end-to-end. Rather than exposing a single tool, a good plugin combines skills, connectors, slash commands, and sub-agents so Claude has everything it needs to handle a category of work. For example, a sales plugin might bundle a CRM connector, a skill that teaches Claude your sales process, slash commands for common tasks like prospect research and call follow-ups, and a sub-agent that handles competitive analysis in parallel. Together, these components make Claude a specialist — individually, they're just building blocks. Plugins can include any combination of: * **Skills** — Task-specific instructions that Claude activates dynamically based on context * **MCP connectors** — Connections to external tools and data sources. Plugins can contain any MCP, including remote MCPs, local MCPs, and MCPBs. The MCP configuration within a plugin is highly customizable. * **Slash commands** — User-invoked commands for triggering specific workflows * **Sub-agents** — Custom agent definitions for delegating complex work ### Guiding Claude through MCP setup Plugins can include a `SETUP.md` skill to guide Claude through configuring and connecting any MCP servers bundled in the plugin. This lets you define step-by-step setup instructions that Claude follows when a user installs or activates your plugin. ### Using safe MCP connectors in plugins While a plugin can include any MCP of any kind in its `.mcp.json` definition, we strongly encourage using connectors that already exist in the [Connectors Directory](/docs/connectors/directory) or come from well-known developers. This will increase the likelihood of verification and will reduce the number of warnings shown to users. ## Directory terms & conditions All plugins in the directory must comply with: * [Anthropic Software Directory Terms](https://support.claude.com/en/articles/13145338-anthropic-software-directory-terms) * [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) ## Security Each plugin in the directory includes a link to where you can review its contents before installing. Plugins are capable of loading remote MCP servers, local MCP servers, and other local software tools to assist you in doing work. You should review any additional software that may be installed by a plugin, as community plugins may install unverified, third-party software that could be malicious or result in unintended behavior. Best practices when using community plugins: * Review the plugin's source code before installing * Check which MCP connectors are included and what permissions they request * Prefer Anthropic Verified plugins for production workflows * Report any suspicious activity to Anthropic ## Submitting your plugin To submit a plugin to the directory, share a GitHub link to your plugin. The repo must be public—closed-source plugins are not accepted. Before submitting, run `claude plugin validate` to check formatting and structure. Review times vary with queue volume. ### Before you start Both submission forms require you to be signed in with sufficient permissions: * **claude.ai** requires a Team or Enterprise organization and directory management access. Organization Owners have this by default; on Enterprise, an Owner can delegate it through a custom role, as described in the [connector submission access requirements](/docs/connectors/building/submission#before-you-start). * **Console** requires a Developer, Admin, or Owner role on a Console organization. Individual authors who aren't part of a claude.ai Team or Enterprise organization can sign up for Console at [platform.claude.com](https://platform.claude.com) and submit there. To submit please use one of our in-app submission forms: * **Claude.ai** — [https://claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new) * **Console** — [https://platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) After you submit on claude.ai, the **Directory** page in your organization settings ([claude.ai/admin-settings/directory/submissions](https://claude.ai/admin-settings/directory/submissions)) lists your submissions with their review status. After your plugin is published, updates pushed to your GitHub repo are picked up automatically—CI mirrors changes to the public marketplace and runs automated screening on each update. You do not need to re-submit the form for updates. Need help building your plugin? See the [Claude Code plugin guide](https://code.claude.com/docs/en/plugins) for a complete walkthrough of plugin structure, manifests, and testing, or the [plugins reference](https://code.claude.com/docs/en/plugins-reference) for full technical specifications. # Creating custom skills Source: https://claude.com/docs/skills/how-to Learn how to create, structure, and test your own custom skills Custom skills extend Claude with specialized knowledge and workflows. This guide explains how to create, structure, and test your own skills. Skills can range from simple instruction sets to multi-file packages with executable code. Effective skills: * Solve a specific, repeatable task * Have clear instructions Claude can follow * Include examples when helpful * Define when they should be used * Focus on one workflow rather than trying to do everything Skills follow the [Agent Skills specification](https://agentskills.io/specification) — see the specification for more in-depth information. ## Directory structure A skill is a directory containing at minimum a `SKILL.md` file: ``` brand-guidelines/ ├── SKILL.md ├── scripts/ # Optional: executable code ├── references/ # Optional: additional documentation └── assets/ # Optional: templates, images, data files ``` The directory name must match the `name` field in your `SKILL.md`. ## Creating a `SKILL.md` file The `SKILL.md` file must start with YAML frontmatter containing required metadata, followed by markdown instructions. ### Required fields ```markdown SKILL.md theme={null} --- name: brand-guidelines description: Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage. --- ``` **name**: Lowercase letters, numbers, and hyphens only. Maximum 64 characters. Must match the directory name. **description**: Explains what the skill does and when to use it. Claude uses this to determine when to invoke your skill. Maximum 1,024 characters, the same limit as the [Agent Skills specification](https://agentskills.io/specification). ### Markdown body After the frontmatter, write markdown instructions for Claude. Include: * Step-by-step procedures * Examples of inputs and outputs * Templates or formatting requirements * Edge cases to handle Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files. ### Complete example ```markdown SKILL.md theme={null} --- name: brand-guidelines description: Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage. --- # Brand Guidelines Apply these standards when creating presentations, documents, or marketing materials for Acme Corp. ## Brand colors - Primary: #FF6B35 (Coral) - Secondary: #004E89 (Navy Blue) - Accent: #F7B801 (Gold) - Neutral: #2E2E2E (Charcoal) ## Typography - Headers: Montserrat Bold - Body text: Open Sans Regular - Size guidelines: H1 32pt, H2 24pt, Body 11pt ## Logo usage Use the full-color logo on light backgrounds, white logo on dark backgrounds. Maintain minimum spacing of 0.5 inches around the logo. ## When to apply Apply these guidelines when creating: - PowerPoint presentations - Word documents for external sharing - Marketing materials - Reports for clients See the [assets/](assets/) folder for logo files and font downloads. ``` ## Adding resources For content too detailed for `SKILL.md`, add files to your skill directory: * **`references/`**: Additional documentation Claude can read when needed * **`assets/`**: Templates, images, lookup tables, schemas * **`scripts/`**: Executable code (see below) Reference these files in `SKILL.md` so Claude knows when to load them. Keep files focused—smaller files mean less context usage. ## Adding scripts Skills can include executable code in Python, JavaScript/Node.js, or Bash. Place scripts in the `scripts/` directory. Claude can install packages from standard repositories (PyPI, npm) when loading skills. Declare dependencies in your frontmatter: ```markdown SKILL.md theme={null} --- name: data-analysis description: Analyze CSV files and generate visualizations. dependencies: python>=3.8, pandas>=1.5.0, matplotlib --- ``` ## Packaging your skill To upload a skill to Claude: 1. Ensure the directory name matches your skill's `name` field 2. Create a ZIP file containing the skill directory **Correct structure:** ``` my-skill.zip └── my-skill/ ├── SKILL.md └── scripts/ ``` **Incorrect structure:** ``` my-skill.zip ├── SKILL.md # files directly in ZIP root └── scripts/ ``` ## Testing your skill ### Before uploading 1. Review `SKILL.md` for clarity 2. Verify the description accurately reflects when Claude should use the skill 3. Check that all referenced files exist 4. Validate using `skills-ref validate ./my-skill` ([validation tool](https://github.com/agentskills/agentskills/tree/main/skills-ref)) ### After uploading 1. Enable the skill in **Customize > Skills** 2. Try prompts that should trigger it 3. Review Claude's thinking to confirm it's loading the skill 4. Iterate on the description if Claude isn't using it when expected ## Best practices **Keep it focused**: Create separate skills for different workflows. Multiple focused skills compose better than one large skill. **Write clear descriptions**: Be specific about when the skill applies. Include keywords that help Claude identify relevant tasks. **Start simple**: Begin with markdown instructions before adding scripts. **Use examples**: Include example inputs and outputs to help Claude understand what success looks like. **Test incrementally**: Test after each significant change. **Leverage composability**: Claude can use multiple skills together automatically. ## Security considerations * Don't hardcode sensitive information (API keys, passwords) * Review any downloaded skills before enabling them * Use MCP connections for external service access ## Example skills See [github.com/anthropics/skills](https://github.com/anthropics/skills/tree/main/skills) for example skills you can use as templates. ## Related topics Create and test skills from the Claude Code CLI, including the `/skills` manager. Package your skill for the plugin directory. # Skills overview Source: https://claude.com/docs/skills/overview Extend Claude's capabilities with specialized instructions and workflows Skills are directories containing instructions, scripts, and resources that Claude dynamically loads to handle specific tasks. Each skill has a `SKILL.md` file that defines when it should be activated and what instructions Claude should follow. ## Availability Skills are available for users on Pro, Max, Team, and Enterprise plans. The Skills feature requires code execution to be enabled. ## How skills work Skills use progressive disclosure to manage context efficiently: 1. **Metadata loading**: Claude reads skill names and descriptions at startup (\~100 tokens each) 2. **Activation**: When a task matches a skill's description, Claude loads the full `SKILL.md` content 3. **Resource loading**: Additional files (scripts, references) are loaded only when needed This approach prevents context window overload while providing specialized capabilities on demand. ## Types of skills * **Anthropic skills**: Pre-built skills for document creation (Excel, Word, PowerPoint, PDF) that activate automatically when relevant. * **Partner skills**: Skills from partners like Notion, Figma, and Atlassian designed for seamless MCP connector integration. * **Organization-provisioned skills**: Skills deployed organization-wide by Team and Enterprise administrators. * **Custom skills**: Skills you create for specialized workflows—generating emails, applying brand guidelines, integrating with tools like JIRA or Linear, and more! ## Skills vs. other features | Feature | Purpose | | ------------------------------------- | --------------------------------------------------------------------------------- | | **Skills** | Task-specific procedures that load dynamically | | **[Plugins](/docs/plugins/overview)** | Shareable packages that bundle skills, connectors, slash commands, and sub-agents | | **Projects** | Static background knowledge always loaded in specific chats | | **MCP** | Connects Claude to external services | | **Custom Instructions** | Broad preferences applied to all conversations | ## Open standard Skills follow the [Agent Skills specification](https://agentskills.io/specification), a platform-agnostic standard. Skills you create can work across any platform adopting the standard. See [Creating custom skills](/docs/skills/how-to) to learn how to build your own, or bundle skills into [plugins](/docs/plugins/overview) to share them with your team. ## Related topics Create, install, and invoke skills from the Claude Code CLI. Bundle skills with connectors and commands. # Deploy with Enterprise Admin Console Source: https://claude.com/docs/third-party/claude-desktop/admin-console Manage your organization's Claude Desktop 3P configuration centrally with the Enterprise Admin Console, hosted by Anthropic The Enterprise Admin Console for Desktop 3P is in beta. Contact your Anthropic representative to have an organization provisioned. With 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 once 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. Prompts, responses, and files go to your inference provider, as they do with MDM or a bootstrap server. Anthropic holds your user list and the settings you save. If you turn on usage analytics, Anthropic also holds token and session counts from your users' apps. Anthropic never holds provider credentials. For the full list of what Anthropic stores, see [Where your data goes](#where-your-data-goes). ## How it works Anthropic creates a Claude Enterprise organization for your deployment and invites a Primary Owner. Your administrators sign in to that organization at [claude.ai](https://claude.ai) and open **Organization settings**. There they add users and groups, connect single sign-on, assign administrator roles, and edit the Claude Desktop configuration for the whole organization and for individual groups. On each device, the user signs in to Claude Desktop once. The app recognizes that the account belongs to a third-party deployment, downloads the configuration that applies to that user, and asks the user to restart. After the restart, the app runs in third-party mode. It sends model requests to your inference provider, as it does with MDM or bootstrap delivery. While the app runs, it re-checks the configuration on a timer. When you save a change, the app downloads it at the next check and asks the user to relaunch, as described under [Configuration updates](#configuration-updates). You don't push an MDM profile or run a bootstrap server. Users are provisioned a Claude account only to sign in to Claude Desktop and receive their settings. They sign in with their work email address, through your single sign-on if you connect it. ## Where your data goes Anthropic stores your organization's user accounts and the configuration you save, and delivers that configuration to users' apps. If you turn on usage analytics, Anthropic also stores the token and session counts that users' apps report. As with MDM or bootstrap delivery, prompts and model responses go to your inference provider and conversations stay on the device. | Data | Does Anthropic store it? | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Prompts, model responses, and tool inputs and outputs | **No.** They go to your inference provider, and tool calls go to the connectors you configure. Data handling at the provider depends on the provider, as described under [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider). | | Conversation history, projects, memory, and uploaded files | **No.** They stay on the device. | | Provider credentials, API keys, bearer tokens, and MCP secrets | **No.** They stay on the device, and the console refuses to save them. | | Plugin and skill content | **No.** It stays in your own repositories or on devices. The console stores marketplace locations and installation settings, not content. | | OpenTelemetry export, if you configure a collector | **No.** It goes to your collector only. | | User accounts (name and work email), group membership, and administrator roles | **Yes.** | | Single sign-on and SCIM connection settings, if you use them | **Yes.** | | The configuration your administrators save, organization-wide and per group | **Yes.** Anthropic delivers it to users' apps. It contains no credentials. | | 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. | | 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. | The 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. Both hosts 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. ## Get set up Contact your Anthropic representative to have an organization provisioned for your deployment. The Primary Owner receives an email invitation, signs in at [claude.ai](https://claude.ai), and finds an empty organization to configure. If your company already has a Claude organization that has verified your email domain, usually a Claude Enterprise organization, name that organization's Primary Owner as the Primary Owner of the new one too. The new organization then appears as an additional organization alongside your existing one and uses the existing organization's single sign-on connection, SCIM directory, and verified domains. Your existing organization is not changed. If no existing organization has verified the email domain of the person you name, the new organization starts with its own sign-in settings. ## Connect your identity provider Set up single sign-on before inviting users, as described in [Set up single sign-on](https://support.claude.com/en/articles/13132885-set-up-single-sign-on-sso). Users then sign in to Claude Desktop through your identity provider, and you can provision them with SCIM. Single sign-on is recommended rather than required. Without it, invited users sign in with their work email address through the standard Claude sign-in, such as a sign-in link emailed to them. A new organization starts set to **Invite only**, so only people you invite can join. For a pilot, keep that setting and invite the people you want. For a wider rollout, let people join automatically the first time they sign in through your identity provider (just-in-time provisioning), or sync them from your identity provider's directory with SCIM, as described in [Set up JIT or SCIM provisioning](https://support.claude.com/en/articles/13133195-set-up-jit-or-scim-provisioning). When the new organization shares your existing organization's single sign-on connection, as described under [Get set up](#get-set-up), you still choose, separately for each organization, how people join it and which groups from your identity provider it uses. Groups synced from your identity provider through SCIM appear among the organization's groups and can carry their own settings, as described under [Per-group permission policies](#per-group-permission-policies). The Claude sign-in is separate from the sign-in to your inference provider or gateway, and the app never sends Claude account credentials or tokens to your provider. Users sign in to Claude once to receive their settings. They then authenticate to your provider the same way they do with MDM or bootstrap delivery. ## Configure Claude Desktop Sign 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**. 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. ### Start from an existing configuration file If you already deploy Claude Desktop with an MDM profile, a bootstrap server, or a configuration built in the app, upload that configuration instead of entering each setting again. On the **Connection** page, click **Import configuration…**, then choose a `.json` file or paste the JSON. The console reads JSON in any of these forms: * The file that Claude Desktop saves from **Developer → Configure Third-Party Inference… → Export → JSON config**, on macOS or Windows. Export it on the workstation where you built the configuration. On a device whose MDM profile or registry policy sets the Claude Desktop configuration, that window is read-only and doesn't offer this export. * The JSON that your bootstrap server returns. * A macOS `.mobileconfig` profile converted to JSON with `plutil -convert json -o config.json YourProfile.mobileconfig`. * A Linux `/etc/claude-desktop/managed-settings.json` file. For a Windows fleet, use the JSON config export, because the console doesn't read `.reg` files or registry policy. The console fills in the matching settings and lists anything in the file that it can't store, such as credentials, bootstrap keys, and values that are set automatically from your organization, like the display name. It then shows every change against the saved configuration, and replaces the configuration when you click **Replace configuration**. If the connection in the file can't be stored, for example because it relies on an API key or token in the file, the console keeps your saved connection instead. Before the users of an existing fleet sign in, prepare their devices: * **MDM or bootstrap fleets:** remove the Claude Desktop configuration profile or registry policy, including a profile or policy that carries only bootstrap keys. A device that keeps one uses that configuration and ignores the admin console. A profile that sets only the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) can stay. * **Machines configured in the app:** a device set up from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) with **Apply Changes** stays in its local third-party configuration. Return it to standard Claude Desktop first. To do that, sign out in the app and choose the Anthropic sign-in option on the sign-in screen, as described under [Single-machine setup](/docs/third-party/claude-desktop/installation#single-machine-setup). Users then sign in as described under [Onboard users](#onboard-users). Conversations from the earlier configuration stay on the device. To let users bring those conversations into the app's history, turn on **Claude.ai data import** on the **Connectors** page, which sets the [`claudeAiImport`](/docs/third-party/claude-desktop/configuration#claudeaiimport) key. Users then open **Settings → Import & export** in the app, and the earlier sessions appear in the [Cowork & Code step of the import wizard](/docs/third-party/claude-desktop/import#step-2-local-cowork-and-code-sessions). ### What you can configure From the console you can set the same [configuration keys](/docs/third-party/claude-desktop/configuration) that MDM and bootstrap delivery support, apart from the items listed under [Limitations](#limitations). The **Desktop 3P** section of the left navigation has these pages: | Page | What you configure there | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connection** | The inference provider ([gateway](/docs/third-party/claude-desktop/gateway), [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock), [Bedrock Mantle](/docs/third-party/claude-desktop/mantle), [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex), or [Microsoft Foundry](/docs/third-party/claude-desktop/foundry)), its endpoint, region, or project, how users authenticate to it, custom request headers, and, under **Models**, the model list, default model, model discovery, and cost-estimate rates. **Desktop sign-in** on this page holds the **Require this organization in Claude Desktop** switch described under [Users in more than one Claude organization](#users-in-more-than-one-claude-organization). | | **Workspace** | Whether Chat, Cowork, and Code are each available, the folders and network hosts the app may use, permission modes and built-in tool policy, whether users may add their own skills and plugins, and organization instructions | | **Connectors** | Managed MCP servers, including the [built-in connectors](/docs/third-party/claude-desktop/built-in-connectors), whether users may add their own MCP servers, desktop extension policy, and [**Claude.ai data import**](/docs/third-party/claude-desktop/import) | | **Telemetry & updates** | Which telemetry categories go to Anthropic, whether users' apps report [usage analytics](#usage-analytics) to your organization, OpenTelemetry export to your collector, update policy, the [configuration relaunch window](#configuration-updates), and the configuration re-check interval | | **Limits** | A per-user token limit and its window | | **Appearance** | Banner text and colors, end-user attribution, and whether the app shows feature announcements and configuration deprecation warnings | | **Plugins** | The [plugin marketplaces](#plugin-marketplaces) that users' apps fetch, and how each one installs | The console stores no API keys, tokens, or secrets, and refuses them anywhere in the configuration, including in request headers and MCP server settings. Users authenticate to your provider on the device, as described under [Choose how users authenticate to your provider](#choose-how-users-authenticate-to-your-provider). Most of these settings can also differ per group of users, on the **Permission policies** page under **People**, as described under [Per-group permission policies](#per-group-permission-policies). ### Choose how users authenticate to your provider 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. The 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, **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. | Provider | Recommended credential kind | Credential fields on the **Connection** page | What users do at first launch | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [LLM gateway](/docs/third-party/claude-desktop/gateway#single-sign-on-with-your-identity-provider) | **Interactive sign-in** with your identity provider | **Gateway SSO IdP (OIDC)** with your identity provider's issuer URL and the client ID of the application you registered for Claude Desktop | The app shows a **Sign in to your organization** button that opens your identity provider's sign-in page in the browser. After sign-in, the app sends that user's token to your gateway on every request, and your gateway validates it. | | [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock#in-app-aws-sign-in) | **Interactive sign-in** through IAM Identity Center | **AWS SSO start URL**, **AWS SSO region**, **AWS SSO account ID**, and **AWS SSO role name** | The app shows a **Sign in with AWS** page and the user approves in the browser. No AWS CLI is needed. | | [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex#in-app-google-sign-in), users with Google accounts | **Interactive sign-in** with Google | **Vertex OAuth client ID** and **Vertex OAuth client secret** from a Desktop-app OAuth client in your own Google Cloud project. Google doesn't treat a Desktop-app client secret as confidential, so the console accepts it. | The app shows a **Sign in with Google** page and the user approves Google's consent screen in the browser | | [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex#in-app-workforce-identity-sign-in), users who sign in with another identity provider | **Workforce Identity** | **Workforce Identity audience** and **Workforce Identity IdP (OIDC)** with your identity provider's issuer URL and client ID | The app shows a **Sign in** page and the user signs in to your identity provider in the browser. No Google identity is needed. | | [Microsoft Foundry](/docs/third-party/claude-desktop/foundry#in-app-entra-id-sign-in) | **Interactive sign-in** with Microsoft Entra ID | **Entra ID tenant ID** and **Entra ID client ID**, and optionally **Entra ID sign-in flow** | The app shows a **Sign in with Microsoft** page and the user signs in with a device code, in the browser, or through the operating system's account picker | | [Bedrock Mantle](/docs/third-party/claude-desktop/mantle) | **Helper script**, because Mantle has no interactive sign-in | **Helper script** with the absolute path of a script that prints the bearer token | The app shows no sign-in page and runs the script whenever it needs a token | Tokens from these sign-ins are stored only on the user's device. The linked provider pages cover setup at the provider, network egress, and session lifetime for each option. #### When a helper script is the right choice Choose **Helper script** for Bedrock Mantle, or when the credential for your gateway or provider can only come from tooling that runs on the device, such as an internal secret broker. The console stores the script's path, not the script, and the same path goes to every device in the organization. Install the script at that absolute path on every device through your software distribution, in a location that users can't modify, for example `/usr/local/bin/corp-cred-helper` on a macOS fleet or `C:\Program Files\Corp\cred-helper.cmd` on a Windows fleet. Claude Desktop runs the script under the user's operating-system account, so anything that differs per user, such as reading that user's home folder or keychain, belongs inside the script. #### Managed MCP servers that need authentication A managed MCP server that supports OAuth needs nothing on the device. Set **OAuth** on the server's entry on the **Connectors** page to **Auto-register (dynamic client registration)** or **Bring your own client**, and Claude Desktop signs each user in through the browser, as described under [OAuth sign-in](/docs/third-party/claude-desktop/extensions#oauth-sign-in). For a server that needs a secret, such as a confidential OAuth client secret, a request header that carries a token, or environment variables for a local server, enter the absolute path of a helper script on the device that prints it, in the **Client secret helper script**, **Headers helper script**, or **Environment helper script** field. The [`managedMcpServers` schema](/docs/third-party/claude-desktop/configuration#managedmcpservers) describes each script's output format. Install that script at the same absolute path on every device, as with the inference helper script. ### Localhost base URLs The **Gateway base URL**, **Bedrock base URL**, and **Vertex AI base URL** fields on the **Connection** page take an `https://` URL. They also accept an address on the device itself (`localhost`, `127.0.0.1`, or `[::1]`) over `https://` or `http://`, for example `http://localhost:4000`. Use a localhost address only when your organization runs a proxy or tunnel to your provider on every device in the deployment, because Claude Desktop sends model requests to whatever program answers at that address on each device. A localhost address in these fields requires Claude Desktop 1.52386.0 or later on every device, so update your devices before you save a localhost address. With a localhost address saved, a user on an earlier release who signs in for the first time stays in standard Claude Desktop instead of switching to your configuration. A device on an earlier release that already runs your configuration loses its connection to your provider the next time the app starts, until the device updates or you remove the localhost address. ### Per-group permission policies The **Permission policies** page, under **People** in the left navigation, applies different settings to users in specific groups. You can add policies after you save the organization-wide settings on the **Connection** page, and each group can have one policy. Click **Add permission policy**, pick a group, and set only the settings that should differ. Every other setting comes from the organization-wide settings. A policy can, for example, turn Chat, Cowork, and Code on or off, narrow the model list and the managed MCP servers to a subset by name, and change built-in tool settings, network allowlists, telemetry, token limits, and the banner. The inference connection (the provider, its endpoint, and how users authenticate to it) is organization-wide, and a policy can't add models or managed MCP servers that the organization-wide settings don't define. Policies are ranked in the order shown on the page, and you drag them to change the ranking. When a user belongs to several listed groups, most settings, including the model list, come from the highest-ranked of their policies that sets them, and lower-ranked policies fill in only what the higher ones leave unset. Managed MCP servers combine instead, so the user keeps every server that any of their policies selects. The OpenTelemetry settings and the token limit each come from one policy only, the highest-ranked policy that sets any part of them. Lower-ranked policies' values for them are ignored, and any part that policy leaves unset keeps the organization-wide value. For example, if the Traders policy (ranked first) turns Code off and selects the wiki server, and the Analysts policy (ranked second) sets a token limit and selects the tickets server, a user in both groups has Code off, the Analysts token limit, and both servers. Everything these policies leave unset comes from the organization-wide settings, and a user in no listed group gets the organization-wide settings unchanged. Groups are managed on the **Groups** page under **People**, including groups synced from your identity provider. ### Plugin marketplaces On the **Plugins** page under Desktop 3P, list the [plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin) that users' apps should fetch. The marketplaces you add are git repositories, or a `marketplace.json` file and plugin archives on an HTTPS origin you control. The **Add marketplace** menu also offers Anthropic's public plugin marketplaces under **Curated by Anthropic**. The app does not add the Anthropic marketplaces on its own in third-party mode. ### Telemetry defaults The telemetry categories, keys, and egress hosts on [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) apply unchanged. Essential and non-essential telemetry are on until you turn them off on the **Telemetry & updates** page. The app attributes crash reports and product analytics to your organization automatically, and also attributes product analytics to the signed-in user's Claude account. An OpenTelemetry collector that you configure on the same page must use an `https://` endpoint. ### Usage analytics Usage analytics lets your administrators see how much each user uses Chat, Cowork, and Code in Claude Desktop. Usage analytics is off by default. A member with the Owner or Primary Owner role can turn it on: open **Organization settings**, go to the **Telemetry & updates** page under **Desktop 3P**, and turn on the **Report desktop usage to this organization** switch. If your organization needs HIPAA compliance, don't turn on the switch. Claude Desktop 1.46388.1 and later report usage. While the switch is on, each user's app counts its Chat, Cowork, and Code activity. The app sends the counts to Anthropic every few minutes during use and when it quits. A running app starts or stops reporting at its next configuration check (every 10 minutes by default), without a relaunch. Anthropic stores the counts for your organization and ties each report to the user's Claude account. The counts appear on the **Desktop usage** page. To open the page, click **Analytics** in the user menu on claude.ai, or **Desktop usage** under **Desktop 3P** in **Organization settings**. The page includes the following: * Sessions and tokens for Chat, Cowork, and Code (the page labels Code **Claude Code**). * A daily chart. * A chart of tokens by model. * A **Team** table with one row for each member who reported usage that month. Each row shows the member's name and email from your member list, their sessions, their tokens, and their last active day. Click a member's row in the **Team** table to show only that member's sessions and tokens. When the month's reports include cost estimates, switch the control at the top of the page from **Tokens** to **Cost** to show estimated cost in US dollars instead of tokens. Estimated cost and the chart of tokens by model cover the whole organization, and the page doesn't show them while a single member is selected. To download a CSV file, click the **Export** button above the **Team** table. The file has one row for each member who matches the table's search, including the member's input, output, cache read, and cache write tokens and, when the month has estimates, their estimated cost. Members with the Primary Owner, Owner, or Admin role can open the **Desktop usage** page. Members whose role from the **Admin roles** page includes the **Analytics** permission can also open the page. Each report contains only the following: | Data | Example | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | A session count: one for each Chat, Cowork, or Code conversation | `1` | | Token counts for each conversation and model: input, output, cache read, and cache write | `1300` input tokens | | An estimated cost in US dollars for each conversation and model. The app calculates the estimate on the device, at Anthropic list prices or at the rates you set under **Models** on the **Connection** page, and labels which it used (`list` or `managed`). A model ID that the app can't match to a Claude model (such as a gateway alias) has no estimate unless you [set a rate](/docs/third-party/claude-desktop/configuration#inferencemodelpricing) for that exact ID | `0.0133`, `list` | | The tab the activity happened in | `cowork` | | The model identifier, exactly as your provider or configuration identifies the model. For Amazon Bedrock, the identifier can be an inference profile ARN, which includes your AWS region and account ID. Claude Desktop 1.52386.0 and later mask the account ID before sending. For Google Cloud, the identifier can be a resource path that includes your project ID | `claude-sonnet-4-5` | | The date and time of the counted activity | `2026-08-27T21:00:01Z` | | A random identifier for the conversation | `local_c34fa9b2-…` | | A random identifier for the app installation. Crash reports and product analytics carry the same identifier | `49819623-…` | | The app version, the operating system type and version, the processor architecture, and a fixed product label | `1.49585.0`, `darwin`, `24.6.0`, `arm64`, `claude-desktop` | The reports never contain prompts, responses, file names or contents, tool names, tool inputs or outputs, folder or project names, connector names, or host names. When you turn off the **Report desktop usage to this organization** switch on the **Telemetry & updates** page under **Desktop 3P** in **Organization settings**, users' apps stop reporting at their next configuration check and discard any counts they haven't sent. Turning the switch off doesn't delete counts that Anthropic has already received. While the switch is off, the **Desktop usage** page shows a notice instead of the counts. If you remove a user from the organization, your totals still include the user's counts, shown without a name or email. ## Onboard users Before the first user signs in, confirm the following: * You hold the Owner or Primary Owner role in the new organization * You have saved a configuration that includes the inference provider, as described under [Configure Claude Desktop](#configure-claude-desktop) * Single sign-on is connected, if you use it, and the users you want on this deployment are invited or provisioned, as described under [Connect your identity provider](#connect-your-identity-provider) * Devices run the latest Claude Desktop release, installed as described in [Installation and setup](/docs/third-party/claude-desktop/installation) * Devices carry no MDM-delivered Claude Desktop configuration. If a managed profile or registry policy sets any key other than the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys), the app uses that configuration and ignores the configuration from the admin console. * Devices can reach `api.anthropic.com` at every launch and while the app runs, and `claude.ai` when users sign in, in addition to the hosts on [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) A 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. 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. 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). If your connection uses an interactive sign-in, sign in to your inference provider or gateway next, as with MDM or bootstrap delivery. 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. If 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. ### Users in more than one Claude organization A user's Claude account can belong to your deployment's organization and to other Claude organizations, and the user can move between them in Claude Desktop. When such a user signs in, the app opens in their other organization and asks whether to switch to yours, with **Switch and restart** and **Not now** buttons. A user who chooses **Not now** isn't asked again on that device and can switch later by choosing your organization from the account menu. Each move into or out of your organization restarts the app, because third-party mode runs as a separate app configuration. To go back, the user chooses **Sign out** and signs in to Claude again after the restart. From Claude Desktop 1.49585.0, they can instead pick their other organization from the account menu, which also restarts the app and asks them to sign in. To remove the choice, turn on **Require this organization in Claude Desktop** under **Desktop sign-in** on the **Connection** page. Members who also belong to another organization are then switched to yours the next time Claude Desktop starts or they sign in, and can't choose to stay. Browsers are not affected. ### Configuration updates From Claude Desktop 1.46388.1, a running app checks for a changed configuration about every 10 minutes, and after the device wakes. When it finds a change, it shows a **Relaunch Claude Desktop** card in the sidebar and gives the user 24 hours to relaunch. When the window ends, the app requires a restart and restarts itself after 2 minutes of inactivity. Earlier releases check about every 30 minutes and allow 1 hour. To change the window, set **Configuration relaunch window** on the **Telemetry & updates** page. The window can be 0 to 336 hours, and 0 requires the restart as soon as the app sees the change. The setting applies to Claude Desktop 1.46388.1 and later. Earlier releases always allow 1 hour. An app that isn't running picks up the change at its next launch. Connection and credential settings never change in a running session. If a setting is changed that affects where users' apps connect or sign in, or what can run on their devices (including when permission policies are added, removed, or reordered), Owners receive an email alert with the identity of the administrator who made the change. ## Remove users or return to MDM A user returns a device to standard Claude Desktop by choosing **Sign out** from the account menu. The app relaunches signed out. When 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 the sign-in screen, where **Or sign in with Claude.ai** returns the device to standard Claude Desktop, or a **Restart required** prompt whose **Restart** button does the same. To return a whole fleet to [MDM](/docs/third-party/claude-desktop/mdm) or [bootstrap](/docs/third-party/claude-desktop/bootstrap) delivery, deploy the configuration profile or registry policy again. The device-managed configuration takes precedence over the configuration from the admin console from 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. Conversations created under the admin console's configuration stay on the device but no longer appear in the app's history after the switch. Users can bring them into the app's history from **Settings → Import & export** in the app, as described at the end of [Start from an existing configuration file](#start-from-an-existing-configuration-file), 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. ## Manage the configuration with the Admin API The configuration that the admin console edits is also available as one JSON document through the Admin API. You can keep it in version control and apply it from a pipeline. Requests authenticate with an Admin API key that the organization's Primary Owner creates. Sign in at [claude.ai](https://claude.ai), switch to your Claude Desktop deployment's organization, and open **Organization settings → API**. Click **Create key**, name the key, and select the `read:desktop_config` scope to read the configuration and `write:desktop_config` to replace it. Only that organization's **Create key** dialog lists these two scopes. A key that reads and writes needs both scopes. Copy the key when it's shown, because you can't view it again. Pass the key in the `x-api-key` header. The key determines the organization, so there is no organization ID in the path. The examples read the key from the `ANTHROPIC_ADMIN_KEY` environment variable. ### Read the configuration ```bash theme={null} curl -sS --fail-with-body https://api.anthropic.com/v1/organizations/desktop_config \ -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \ -H "anthropic-version: 2023-06-01" \ -o desktop-config.json.tmp \ && mv desktop-config.json.tmp desktop-config.json ``` On an error status, curl exits non-zero before the `mv`, so your saved copy is kept and the error message is in `desktop-config.json.tmp`. `--fail-with-body` needs curl 7.76 or later. With an older curl, use `--fail`, which discards the error message. A read returns `404` until a configuration has been saved, on the **Connection** page of the console or by a first write through this API. The response has these fields: | Field | Contents | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config` | The organization-wide configuration as nested JSON, in the v2 format described under [Response schema](/docs/third-party/claude-desktop/bootstrap#response-schema) for bootstrap servers. Stored header values appear as a placeholder, as described under [Replace the configuration](#replace-the-configuration). | | `status` | `active` or `disabled`. A `disabled` configuration isn't served to users' apps, as the warning under [Replace the configuration](#replace-the-configuration) describes. | | `group_settings` | An object whose `entries` list holds the [per-group permission policies](#per-group-permission-policies) in rank order, highest first, each with a `group_id` and its `config`. A `group_id` that matches no group is accepted and applies to nobody until a group with that ID exists. | | `version` | An integer that increases with every change. | | `checksum` | A digest of `config` and `group_settings` as returned. It leaves out `status`, so compare `version` to detect changes. | | `updated_at` | The time of the last change. | ### Replace the configuration A write replaces the whole document and accepts only `config`, `status`, `group_settings`, and `expected_version`. Send `config`, `status`, and `group_settings` together, even the parts you are not changing. Sending `version`, `checksum`, or `updated_at` returns `400`. The `jq` line below keeps only the accepted fields, sets `expected_version`, and fails if `desktop-config.json` has no `version`. Set `expected_version` to the `version` you read, or to `0` for a first write when nothing has been saved. The write is then refused with `409` if anyone changed the configuration after you read it. Without `expected_version`, the last writer wins. Sending `update.json` unedited returns `200` without creating a new version. ```bash theme={null} jq -e 'select(.version != null) | {config, status, group_settings, expected_version: .version}' \ desktop-config.json > update.json # Edit update.json, then: curl -sS --fail-with-body -X POST https://api.anthropic.com/v1/organizations/desktop_config \ -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d @update.json ``` On an error status, curl prints the error body and exits non-zero (curl 7.76 or later, as under [Read the configuration](#read-the-configuration)). The response to a successful write is the stored document in the same shape as a read. Header values you save are never returned. In every `headers` or `customHeaders` map, including the request headers for your provider, OpenTelemetry export, and managed MCP servers, each stored value reads as the placeholder `[stored on server - enter a new value to replace]`. Sending the placeholder back keeps the stored value. A write that sends the placeholder is refused with `400` in two cases: nothing is stored under that header name yet (a first write, or a renamed header or server), or the same write changes where those headers are sent, for example with a new `baseUrl`. Send the actual header values in those cases. A write goes through the same checks as a save in the admin console. Users' apps 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_…`). 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. The admin console has no control for `status`, so only another API write can set it back to `active`. After that, users who clicked **Restart** sign in again as described under [Onboard users](#onboard-users). ### Admin API errors | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | The server refused the document. The message names the field and the rule, for example `config.inference.baseUrl: must not embed credentials in the URL`. Nothing is stored. | | `401` | The key in `x-api-key` is unknown, deleted, disabled, or expired. | | `403` | The key lacks the scope the request needs, or isn't an organization-level key. For a missing scope, the message lists the scopes the key has and the one required. | | `404` | The key was created in an organization other than your Claude Desktop deployment's, the `x-api-key` header is missing or its key is malformed, or (on a read) no configuration has been saved yet. | | `409` | `expected_version` is not the current version. Read the configuration again and reapply your change. | | `429` | Admin API requests share a per-organization limit of 100 requests per minute, as described under [Rate limits](https://platform.claude.com/docs/en/manage-claude/user-management#rate-limits). Retry after the number of seconds in the `retry-after` header. | ## Limitations * The [Claude API](/docs/third-party/claude-desktop/claude-api) is not available as the inference provider with the admin console. * If a device can't reach `api.anthropic.com` at launch, the app opens with a **Configuration sync issue** warning and can't connect to your inference provider until it downloads the configuration. It keeps retrying in the background and loads the configuration when a retry succeeds, without a relaunch. Quitting and reopening the app retries immediately. An app that is already running keeps working if the connection to Anthropic drops. * Bootstrap keys and settings that only make sense on the device, such as disabling claude.ai sign-in, are not available in the console. # Deploy Claude Desktop on 3P with Amazon Bedrock Source: https://claude.com/docs/third-party/claude-desktop/bedrock Set up AWS, choose an authentication path for your organization, and configure Claude Desktop on 3P to use Claude models on Amazon Bedrock This page walks an IT administrator through a complete Amazon Bedrock deployment: enabling Claude in your AWS account, choosing the authentication path that fits your organization, preparing devices, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app). ## Choose an authentication approach Amazon Bedrock supports several ways to authenticate, and the right one depends on whether your end users already work with AWS and whether you need per-user identity in CloudTrail. Use the table below to pick a path before doing any AWS or device setup. | Scenario | Use | Per-device prerequisite | Per-user CloudTrail identity | Notes | | ------------------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Proof of concept, single team | [Bearer token](#bearer-token) (`inferenceBedrockBearerToken`) | None | No (shared key) | A long-lived secret distributed in the managed profile. Simplest to start; not recommended for broad rollout. | | Broad rollout to users without AWS tooling | [In-app AWS sign-in](#in-app-aws-sign-in) (`inferenceBedrockSso*`) | None | Yes | Users sign in through IAM Identity Center inside the app. No AWS CLI required. Requires app version 1.6259.0 or later. | | Developers who already use the AWS CLI | [Named profile](#named-profile) (`inferenceBedrockProfile`) | AWS CLI v2 and a pushed `~/.aws/config` | Yes | IT can distribute the AWS config file directly; the app runs `aws sso login` for the user when the session expires. | | You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway) instead of Amazon Bedrock | None | At your gateway | The proxy holds the AWS credentials; the app authenticates only to the proxy. | If a static credential in the managed profile is acceptable but an Amazon Bedrock API key is not, you can also set [`inferenceCredentialHelper`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) to an executable that prints an Amazon Bedrock bearer token to stdout at runtime. When more than one credential is configured, the app uses the first one present in this order: in-app AWS sign-in, named profile, credential helper, bearer token. To remove ambiguity, set `inferenceCredentialKind` explicitly (see the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencecredentialkind)). ## Set up AWS These 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. 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`. Skip this step if you chose the bearer-token approach. The named-profile and in-app AWS sign-in approaches both use IAM Identity Center to issue per-user AWS credentials. 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: ```json theme={null} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ], "Resource": "*" }] } ``` Set the permission set's **Session duration** to between 8 and 12 hours. This value controls how long a user can run Claude Desktop before needing to sign in to AWS again. 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. 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. From the IAM Identity Center **Settings** page, note: * **AWS access portal URL**: of the form `https://d-xxxxxxxxxx.awsapps.com/start` (or your custom subdomain) * **Identity Center region**: the region where Identity Center is enabled, which may differ from your Amazon Bedrock region * **AWS account ID**: the 12-digit ID of the account where you enabled Amazon Bedrock * **Permission set name**: the name you gave the permission set above ## Prepare devices What each end-user device needs depends on the authentication approach you chose. ### Bearer token No per-device preparation is required. In the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/home#/api-keys), generate an API key. The key's underlying IAM principal must be allowed the `bedrock:CallWithBearerToken` action; without it, requests return an authorization error even though the key was created. You will place the key in the managed configuration; see [Configure the app](#configure-the-app). ### In-app AWS sign-in No per-device preparation is required. The sign-in experience uses **your organization's AWS IAM Identity Center instance**; the app registers an OIDC client dynamically with your Identity Center at runtime, so you do not create or distribute a client ID. Distribute the four `inferenceBedrockSso*` keys in the managed configuration (see [Configure the app](#configure-the-app)). #### How it works When all four `inferenceBedrockSso*` keys are set, the app shows a **Sign in with AWS** page at first launch. Clicking the button starts an OAuth device-authorization flow with your IAM Identity Center's OIDC endpoint and opens the AWS access portal in the system browser. The app displays a short verification code so the user can confirm that the browser prompt matches the app that requested it. Identity Center redirects the user to whichever identity provider you have configured (Entra ID, Okta, Google Workspace, or the Identity Center built-in directory). On success, the app stores the IAM Identity Center access token and refresh token encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows), dismisses the sign-in page, and shows Cowork. At the start of each Cowork session, the app exchanges the stored token with IAM Identity Center for short-lived AWS credentials scoped to the configured account and permission set, and passes them into the session sandbox as `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`. This is the same credential shape that `aws sso login` produces, obtained without the AWS CLI. If the stored token expires or is revoked, the app shows a **Sign in again** prompt; clicking it reopens the AWS access portal in the browser. If you deploy a different `inferenceBedrockSsoStartUrl`, the app finds no stored token for the new URL and shows the sign-in page on next launch. #### Allow network egress The sign-in flow and token refresh reach the IAM Identity Center endpoints for the region you set as `inferenceBedrockSsoRegion`: * `oidc..amazonaws.com` * `portal.sso..amazonaws.com` These hosts are included automatically in the **Egress** section of the in-app configuration window when the SSO keys are set, so if you built your firewall allowlist from that output, no additional changes are needed. The browser step also reaches your AWS access portal (`*.awsapps.com`) and, if federated, your external identity provider. #### Notes and limitations * **All four keys required.** If only some of the `inferenceBedrockSso*` keys are set, the app logs a warning and ignores the partial configuration. * **One account and role per deployment.** Every user in a given managed configuration signs in to the same AWS account and assumes the same permission set. To give different groups different Amazon Bedrock permissions, deploy distinct configuration profiles with different `inferenceBedrockSsoRoleName` values. * **Mid-session credential refresh.** The app checks the AWS credentials' expiry before each turn and silently mints new ones from the stored IAM Identity Center token when they are close to expiring. If the Identity Center token itself has expired or been revoked, the app shows a **Sign in again** prompt; click it to re-authenticate with AWS in your browser. The permission set's session duration controls how long the Identity Center token remains valid, so set it long enough to cover a working day. * **Connection probe.** The in-app **Test connection** button reports that the connection cannot be verified in this mode, because the app cannot sign Amazon Bedrock requests outside the sandbox. This matches the behavior of named-profile mode and does not indicate a problem. * **Configuration rotation.** If you change `inferenceBedrockSsoStartUrl` in the managed profile, existing users are automatically signed out and prompted to sign in again on next launch. ### Named profile Each device needs AWS CLI v2 installed and an AWS config file that defines the named profile. You do not need users to run `aws configure sso` interactively. That command is a wizard that writes a profile stanza to `~/.aws/config` (macOS) or `%USERPROFILE%\.aws\config` (Windows), and you can distribute that file directly through your device-management tooling instead. A profile that uses IAM Identity Center looks like: ```ini theme={null} [profile claude-cowork] sso_session = corp sso_account_id = 123456789012 sso_role_name = ClaudeCoworkAccess region = us-west-2 [sso-session corp] sso_start_url = https://d-xxxxxxxxxx.awsapps.com/start sso_region = us-east-1 sso_registration_scopes = sso:account:access ``` When the cached IAM Identity Center token is missing or expired, the app prompts the user to sign in and runs `aws sso login --profile claude-cowork` itself, which opens the browser for IAM Identity Center sign-in and caches a token under `~/.aws/sso/cache/`. Users can also run the command in a terminal; the app and the CLI share the same token cache. When the token can be refreshed silently, the app does so without prompting. To run the login command, the app locates the AWS CLI by searching the launch environment's `PATH`, the user's login-shell `PATH`, and standard install locations such as `/usr/local/bin` and `/opt/homebrew/bin` on macOS. If your fleet installs the AWS CLI somewhere else, or you want every device to use one specific binary, set `inferenceBedrockAwsCliPath` to the absolute path of the executable. If your AWS configuration files are not at the default location, set `inferenceBedrockAwsDir` to the directory that contains them. ## Configure the app With AWS set up and devices prepared, open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**) on an evaluation device. In the **Connection** section, set **Inference provider** to **Bedrock** and fill in the **Bedrock credentials** card with the values for whichever authentication approach you chose: | Field | Bearer token | In-app AWS sign-in | Named profile | | -------------------- | --------------------------- | ---------------------------------------- | ---------------------- | | AWS region | e.g. `us-west-2` | e.g. `us-west-2` | e.g. `us-west-2` | | AWS bearer token | your Amazon Bedrock API key | *leave empty* | *leave empty* | | Bedrock base URL | *optional* | *optional* | *optional* | | AWS profile name | *leave empty* | *leave empty* | `claude-cowork` | | AWS config directory | *leave empty* | *leave empty* | *only if not `~/.aws`* | | AWS CLI path | *leave empty* | *leave empty* | *optional* | | AWS SSO start URL | *leave empty* | `https://d-xxxxxxxxxx.awsapps.com/start` | *leave empty* | | AWS SSO region | *leave empty* | e.g. `us-east-1` | *leave empty* | | AWS SSO account ID | *leave empty* | `123456789012` | *leave empty* | | AWS SSO role name | *leave empty* | `BedrockInference` | *leave empty* | | Bedrock service tier | *optional* | *optional* | *optional* | Under **Models**, add a **Model list** entry using the Amazon Bedrock inference-profile ID (required for profile or SSO auth; optional for bearer-token or credential-helper auth, which auto-discover), for example `us.anthropic.claude-sonnet-5`. Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. ### Configuration keys The full set of `inferenceBedrock*` keys is below. Set `inferenceProvider` to `bedrock`, supply a region, and provide exactly one credential source. | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------- | -------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | AWS region
`inferenceBedrockRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. | | Bedrock base URL
`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. | | 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`. | | 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. | | 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. | | AWS SSO region
`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | IAM Identity Center home region. | | 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. | | 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. | | AWS profile name
`inferenceBedrockProfile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. | | 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. | | 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. | 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. Set `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; for profile or SSO authentication, 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). ## What users experience The first-launch and re-authentication behavior depends on the authentication approach. | Approach | First launch | Re-authentication | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bearer token | The app opens directly; no user action. | Never, until you rotate the key in the managed profile. | | In-app AWS sign-in | The app shows a **Sign in with AWS** page; the user approves in the browser, and the app returns to Cowork. | When the IAM Identity Center access portal session expires (defaults to 8 hours; configurable up to 90 days). The app prompts in-app; no terminal needed. | | Named profile | The app opens directly if the AWS SSO cache is fresh; otherwise it prompts in-app and runs `aws sso login` for you, which opens the browser. | When the IAM Identity Center session expires, the app prompts in-app and re-runs `aws sso login`. | For in-app AWS sign-in, the browser flow runs on the host (outside the Cowork sandbox), so it uses the user's existing identity-provider session and any security keys or passkeys configured on the device. The **AWS access portal session duration** setting (IAM Identity Center → **Settings** → **Authentication**) controls how long users stay signed in across app restarts. To force a user to sign in again sooner, delete their active session from the IAM Identity Center console. If the app cannot locate the AWS CLI, it cannot drive the login itself; it instructs the user to install AWS CLI v2 and run `aws sso login --profile ` manually. ## Troubleshoot To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage). # Deploy with a bootstrap server Source: https://claude.com/docs/third-party/claude-desktop/bootstrap 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 Requires Claude Desktop **1.10628.0** or later. Earlier builds ignore the `bootstrapUrl` keys. A **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. When 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. 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. Before 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: * **With MDM:** deploy a profile that sets `bootstrapUrl` (and `bootstrapOidc` if you use one). * **Without MDM:** give each user a small JSON file containing those keys, which they load from **Developer → Configure Third-Party Inference… → Import configuration**. Either way, the bootstrap server supplies everything else after the user signs in. See [Installation and setup](/docs/third-party/claude-desktop/installation) for the surrounding workflow. If you set `deploymentOrganizationUuid`, include it in the MDM profile or imported configuration file, and return the same value in your bootstrap response, as a plain UUID without braces in both places. Claude Desktop uses the device-side value at startup to locate sessions, skills, and plugins stored on the device. ## How it works 1. Your managed configuration (MDM or imported) sets `bootstrapUrl` (and `bootstrapOidc` if you use a separate identity provider). 2. At launch, the app authenticates via one of the [modes below](#authentication) and sends `GET ` with the resulting `Authorization: Bearer ` or the request headers you configured. 3. Your server validates the token, **authorizes** the caller against your directory or entitlement source, and returns a JSON object whose keys are the same managed-configuration key names documented in the [configuration reference](/docs/third-party/claude-desktop/configuration). 4. The app validates each key against the [response schema](#response-schema), drops anything it doesn't recognize or that fails validation, and applies the result as the effective configuration. 5. The response is cached in memory (until your `expiresAt`, or 1 hour by default). The app also re-checks in the background every [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes) (10 minutes by default, 2 to 30 allowed) with a conditional request, so an unchanged configuration costs your server a `304` (see [Caching and `expiresAt`](#caching-and-expiresat)). Releases before 1.46388.1 re-check every 30 minutes and ignore `configRecheckIntervalMinutes`. If the user has not yet signed in, or the fetch fails with no cached response from this session, the app starts in a degraded state with no inference provider configured and prompts the user to sign in. ### Availability The cached response is held **in memory only**; there is no on-disk fallback to a previous session's response. If your bootstrap server is unreachable when Claude Desktop launches, the user stays in the degraded sign-in state until the server recovers. A failed refetch *during* a running session keeps the in-memory response and retries, so an outage that starts mid-session does not disrupt active users until they relaunch. Run the endpoint across multiple replicas or regions behind a load balancer. Do not rely on response caching for availability: responses are per-user and carry credentials (see the `Cache-Control: no-store` guidance under [Server responsibilities](#server-responsibilities)). If your configuration data lives in a database, a read replica of that store improves availability without caching responses. A refetch that returns different values does **not** change the running session. The app keeps the configuration it launched with (inference credentials, egress allowlist, MCP servers, and renderer state such as the model picker all stay on the boot-time values), prompts the user to restart, and applies the new response when it relaunches. Claude Desktop 1.40609.0 and later enforce that restart. Once a background re-check returns a changed response, the user can keep working for [`relaunchEnforcementHours`](/docs/third-party/claude-desktop/configuration#relaunchenforcementhours) (24 hours by default, at most 336 hours, or `0` to require the restart at once; releases before 1.46388.1 default to 1 hour). After that window the app blocks further use until it restarts, and it relaunches on its own once it has been idle for two minutes (no Claude task running and no keyboard or pointer input). Return `relaunchEnforcementHours` in the bootstrap response to change the window, and `configRecheckIntervalMinutes` to change how often running apps check for a new response. The app reads both keys from the newest response, so changing them does not itself require a restart. In the nested response format ([`bootstrap-config-v2`](#response-schema)) both keys sit under `lifecycle`, as `lifecycle.relaunchEnforcementHours` and `lifecycle.configRecheckIntervalMinutes`. Releases before 1.46388.1 read the window from `bootstrap.relaunchEnforcementHours` and do not read the `lifecycle` path, so move the value when your fleet updates (the flat-format key name is unchanged). On a device where `bootstrapUrl` came from an imported file rather than MDM, a device-management profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence), such as the update keys, supplies these two keys as well, so set them in that profile or the defaults apply there. When rotating an inference credential, keep the previous credential valid until your fleet has relaunched. For devices that are running, allow at least one re-check interval plus the relaunch window: with the defaults that is `configRecheckIntervalMinutes` (10 minutes) plus `relaunchEnforcementHours` (24 hours), so about a day. For devices that are off, it is their next launch. ## Server responsibilities Your bootstrap endpoint is a security boundary. The response can carry inference credentials, so an unauthenticated or under-authorized endpoint leaks those credentials to anyone who can reach the URL. Host it on your private network (VPC, corporate intranet, or behind your zero-trust access proxy) rather than the public internet; reachability from managed devices is sufficient. **Authenticate.** Verify the bearer token's signature against your identity provider's JWKS, and check `iss`, `aud`, and `exp`. Reject anything else with `401`. **Authorize.** Verifying the token proves *who* the caller is, not that they're entitled to a configuration. Check the caller's identity claim against your directory before returning a response: | Identity provider | Stable per-user claim | Group/role claim | | ------------------ | --------------------------- | ---------------------------------- | | Microsoft Entra ID | `oid` (directory object ID) | `roles` (app roles) or `groups` | | Okta | `uid` or `sub` | `groups` (via a custom claim rule) | | Generic OIDC | `sub` | provider-specific | Return `403` when the token is valid but the caller is not entitled. Do not authorize on `email` or `preferred_username` alone; those claims are mutable and may be absent for guest or external-identity users. **Key the response on the caller** when configuration needs to differ. A single default profile returned to every entitled user is valid; vary by user or group only where you need per-user credentials, model allowlists, or telemetry attribution. ### Mapping groups to profiles The common pattern is one profile per directory group or app role. For Entra, define an app role on the registration (for example `cowork-power-user`), assign it to a group via **Enterprise applications → Users and groups**, and select the profile from the token's `roles` claim. For Okta, the equivalent is a `groups` claim on your custom authorization server; match on `payload.groups`. Moving a user between groups in your directory is picked up at the next refetch with no profile re-push to devices; the new configuration takes effect when the user's app next launches. A reference Node.js handler showing token validation, role-based authorization, and profile selection: ```js theme={null} import { createRemoteJWKSet, jwtVerify } from "jose"; const TENANT = process.env.ENTRA_TENANT; const CLIENT_ID = process.env.CLIENT_ID; const JWKS = createRemoteJWKSet( new URL(`https://login.microsoftonline.com/${TENANT}/discovery/v2.0/keys`), ); const BASE = { inferenceProvider: "gateway", inferenceGatewayBaseUrl: "https://YOUR_GATEWAY_HOST", inferenceGatewayAuthScheme: "bearer", }; const PROFILES = { default: { ...BASE, inferenceModels: ["claude-sonnet-5"] }, power: { ...BASE, inferenceModels: ["claude-opus-5", "claude-sonnet-5"], coworkEgressAllowedHosts: ["pypi.org", "registry.npmjs.org"], }, }; const ENTITLED_ROLES = new Set(["cowork-user", "cowork-power-user"]); export async function handleBootstrap(req, res) { res.set("Cache-Control", "no-store"); const token = (req.headers.authorization ?? "").replace(/^Bearer /, ""); let payload; try { ({ payload } = await jwtVerify(token, JWKS, { issuer: `https://login.microsoftonline.com/${TENANT}/v2.0`, audience: CLIENT_ID, algorithms: ["RS256"], })); } catch { return res.status(401).json({ error: "invalid_token" }); } const roles = payload.roles ?? []; if (!roles.some((r) => ENTITLED_ROLES.has(r))) { return res.status(403).json({ error: "not_entitled" }); } const profile = roles.includes("cowork-power-user") ? PROFILES.power : PROFILES.default; return res .status(200) .json({ ...profile, expiresAt: Date.now() + 3600_000 }); } ``` Set `Cache-Control: no-store` on the response. Without it, a reverse proxy or CDN between the app and your endpoint may cache one user's credentials and serve them to the next. ## Authentication The bootstrap request is always authenticated: either each user signs in and the app sends their bearer token, or the device sends request headers you configure. The mode is chosen by which keys you set alongside `bootstrapUrl`: | Mode | When to use it | MDM keys | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **Separate identity provider (PKCE)** | Users sign in through your existing OIDC provider (Microsoft Entra ID, Okta, Ping, or any compliant provider). The app runs an OAuth authorization-code grant with PKCE in the system browser. | `bootstrapUrl` and `bootstrapOidc` | | **Bootstrap server as authorization server (device code)** | Your bootstrap server (or the gateway it fronts) implements RFC 8414 discovery and the RFC 8628 device-code grant. One sign-in covers both the configuration fetch and inference when they share an origin. | `bootstrapUrl` only | | **Request headers (no per-user sign-in)** | The endpoint authenticates the device or a service account rather than the user: a static `Authorization: Basic …` or API-key header, or a short-lived token a script on the device fetches from your secrets manager. No browser step; the response cannot vary by signed-in user unless your headers identify one. | `bootstrapUrl` and `bootstrapHeaders` and/or `bootstrapHeadersHelper` (1.32885.1 or later) | ### Separate identity provider (PKCE) 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. 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. 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: | Provider | Scope to request | Resulting `aud` | | ---------------------------------- | ------------------------------------------------------ | ------------------------------------ | | Microsoft Entra ID | `openid offline_access CLIENT_ID/.default` | your client ID | | Okta (custom authorization server) | `openid offline_access YOUR_API_SCOPE` | your authorization server's audience | | Generic OIDC | `openid offline_access` plus your API's resource scope | provider-specific | Include `offline_access` so the app receives a refresh token and can renew silently between launches. 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. See [Server responsibilities](#server-responsibilities). What the token's `iss` and `aud` look like depends on your provider: | Provider | `iss` to expect | `aud` to expect | JWKS URL | | -------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- | | 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` | | Okta (custom authorization server) | `https://YOUR_DOMAIN.okta.com/oauth2/AUTH_SERVER_ID` | the audience configured on that authorization server | `/v1/keys` | **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. **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. 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: | Field | Value | | ----------------------------------------- | ------------------------------------------------------- | | Bootstrap config URL | `https://YOUR_BOOTSTRAP_HOST/user/bootstrap` | | Bootstrap OIDC parameters → Client ID | `YOUR_CLIENT_ID` | | Bootstrap OIDC parameters → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` | | Bootstrap OIDC parameters → Scopes | `openid offline_access YOUR_CLIENT_ID/.default` | | Bootstrap OIDC parameters → Redirect port | leave empty for Entra; set for Okta | 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 (`.mobileconfig`, ADMX, Intune OMA-URI JSON, or `.reg`). See [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) for per-platform instructions. #### Provider notes | Provider | Redirect URI to register | Redirect port field | Additional setup | | ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Microsoft Entra ID | `http://127.0.0.1/callback` under **Mobile and desktop applications** | Leave empty (any local port allowed) | Manifest: set the accepted-token-version field to `2`. **Expose an API**: set the Application ID URI. **Token configuration**: add the `groups` claim if your server authorizes on groups. | | Okta | `http://127.0.0.1:53180/callback` (any fixed port) on a **Native** application | Set to the registered port | Create a custom authorization server with an audience your bootstrap server validates. | | Other OIDC | `http://127.0.0.1/callback` | Set only if exact-port match is enforced | None | Register the redirect URI with `127.0.0.1` rather than `localhost`, because the app sends `http://127.0.0.1:/callback` by default. If your identity provider accepts only `localhost` in a registered redirect URI, set the `redirectHost` field of [`bootstrapOidc`](/docs/third-party/claude-desktop/configuration#bootstrapoidc) to `localhost` and register `http://localhost/callback` instead, or `http://localhost:/callback` when you set a redirect port. This page covers only the bootstrap sign-in. Authentication for inference is independent of bootstrap and depends on what your response provisions; see the relevant provider page ([gateway SSO](/docs/third-party/claude-desktop/gateway#single-sign-on-with-your-identity-provider), [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex), [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock), [Microsoft Foundry](/docs/third-party/claude-desktop/foundry)). ### Bootstrap server as authorization server (device code) Set 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. 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. ```text theme={null} GET https://YOUR_BOOTSTRAP_HOST/.well-known/oauth-authorization-server ``` ```json theme={null} { "issuer": "https://YOUR_BOOTSTRAP_HOST", "token_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/token", "device_authorization_endpoint": "https://YOUR_BOOTSTRAP_HOST/oauth/device" } ``` Every endpoint URL must share the `bootstrapUrl` origin. Metadata that points off-origin is rejected. `POST` to `device_authorization_endpoint` returns: ```json theme={null} { "device_code": "EXAMPLE-DEVICE-CODE-OPAQUE-TO-CLIENT", "user_code": "ABCD-EFGH", "verification_uri": "https://YOUR_BOOTSTRAP_HOST/activate", "verification_uri_complete": "https://YOUR_BOOTSTRAP_HOST/activate?user_code=ABCD-EFGH", "interval": 5, "expires_in": 600 } ``` `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. 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: ```json theme={null} { "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 3600 } ``` 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). 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. On `GET ` with a valid bearer, look up the user from the token claims and return their configuration (see [the HTTP contract](#the-http-contract)). ### Request headers (no per-user sign-in) Requires 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. ## The HTTP contract ### Request ```http theme={null} GET /user/bootstrap HTTP/1.1 Host: YOUR_BOOTSTRAP_HOST Authorization: Bearer eyJhbGciOiJSUzI1NiIs... If-None-Match: "abc123" ``` In request-headers mode the `Authorization` line is whatever your configured headers supply. The path is whatever you set in `bootstrapUrl`; there is no required path. Redirects are **not** followed: a `3xx` is treated as an error so a same-origin open redirect cannot exfiltrate the bearer. The request times out after 30 seconds. ### Response Return `200 OK` with `Content-Type: application/json` and a JSON object whose keys are a subset of the [published response schema](#response-schema). Keys use the exact managed-configuration key names. Unknown keys, keys that fail validation, and keys outside that schema are silently dropped; one bad key never invalidates the rest. ```json theme={null} { "inferenceProvider": "gateway", "inferenceGatewayBaseUrl": "https://llm-gateway.example.corp", "inferenceCredentialKind": "interactive", "inferenceModels": ["claude-opus-5", "claude-sonnet-5"], "managedMcpServers": [{ "name": "internal-tools", "url": "https://mcp.example.corp/sse", "transport": "sse" }], "coworkEgressAllowedHosts": ["*.example.corp", "pypi.org"], "otlpResourceAttributes": { "user.email": "alice@example.corp", "team": "trading" }, "expiresAt": 1778700000 } ``` | Status | App behavior | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Parse and apply. | | `304` | Re-serve the cached response (the app sends `If-None-Match` when it has one). | | `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. | | 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. | 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. ### Response schema The full set of bootstrap-settable keys is published as a machine-readable JSON Schema, generated from the same source as the [configuration reference](/docs/third-party/claude-desktop/configuration) and updated with each release: * [`/third-party/claude-desktop/schemas/bootstrap-config-v2.schema.json`](/docs/third-party/claude-desktop/schemas/bootstrap-config-v2.schema.json) (recommended): nested response format with a discriminated `inference` object. * [`/third-party/claude-desktop/schemas/bootstrap-config-v1.schema.json`](/docs/third-party/claude-desktop/schemas/bootstrap-config-v1.schema.json): flat format, with the managed-configuration key names at the top level as in the example above and in the [configuration reference](/docs/third-party/claude-desktop/configuration). The app accepts either format. Reference the schema with `"$schema"` in your response template, or with `# yaml-language-server: $schema=…` in YAML, for autocomplete and validation. Each configuration key in both schemas carries an `x-availableInVersion` annotation naming the first Claude Desktop release that reads it. The app sends its version as `Claude/` in the `User-Agent` header of the bootstrap request, so a server can vary its response by client version if it needs to. The response can supply any key in that schema, including inference credentials, model allowlists, MCP servers, the egress allowlist, telemetry endpoints, and the organization banner. 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). A small set of keys are **structurally excluded** and ignored if returned: * `bootstrapUrl`, `bootstrapOidc`, `bootstrapHeaders`, `bootstrapHeadersHelper`, `bootstrapEnabled`, and `trustBootstrapDelivery`: the trust anchor cannot redirect itself, authenticate itself, or grant trust in itself. * `egressProxyUrl` and `egressProxyPacUrl`: the app may need the [network proxy](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration) to reach your endpoint in the first place, so these keys are read from device management or the local configuration file only. These two and the six keys above are the keys whose Availability column reads **MDM only** in the [configuration reference](/docs/third-party/claude-desktop/configuration). * Loopback hosts (`127.0.0.1`, `localhost`, `[::1]`) in any URL-valued key, regardless of scheme. `managedMcpServers` entries are not restricted by transport in version 1.19367.0 and later: remote (`http`/`sse`) servers, local `stdio` commands, and the built-in `microsoft365` and `websearch` connectors can all be delivered in the bootstrap response. Earlier versions accept only remote entries and drop the rest. Because a `stdio` entry names a command that runs on the device, a bootstrap response can start local processes — part of why the warning at the top of this page says to treat this endpoint as fully trusted. Entries whose server URL or OAuth authorization-server URL is loopback or non-HTTPS are still dropped, and the desktop log (see [Troubleshooting](#troubleshooting)) records which keys were dropped and why. ### Keys that require user consent Some bootstrap-deliverable values point at local commands and credential files, change where a user signs in, or change where requests are sent. Examples are `inferenceCredentialHelper` and its related keys, `inferenceVertexCredentialsFile`, the AWS profile keys, the inference base URL keys, and connector or marketplace entries that name a local command or helper. The app applies these values only after the user approves them. When a response delivers such a value for the first time, the app applies none of that response until the user approves it. The app opens an **Apply settings from your organization?** dialog that lists each pending value, and nothing in that response takes effect while the dialog waits. Clicking **Allow** records the approval and applies the whole response. Clicking **Quit**, pressing Esc, or closing the dialog quits the app, and it asks again the next time it opens. Approval is per delivered value. If the server later changes an approved value, the dialog appears again. For a `managedMcpServers` or `allowedPluginMarketplaces` entry, one approval covers the entry's executable-related fields as a unit. The desktop log (see [Troubleshooting](#troubleshooting)) names the keys awaiting consent and records the user's decision. In versions earlier than 1.32352.0 that show this dialog, the app applied the rest of the response while the dialog waited and held back only the pending keys. Whether the dialog appears depends on how `bootstrapUrl` reached the device: * Deployed through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux): delivered values are trusted without prompting, because the admin already made a device-level decision. * Read from a local configuration file, or from user-scope registry policy: the dialog is shown by default. The `trustBootstrapDelivery` key overrides the default in either direction, and the previous name `trustBootstrapLocalExec` is accepted until October 7, 2026. The key is accepted from device management or the local configuration file only, never from the bootstrap response itself. When the rest of your configuration is a local file, set the key in that same file next to `bootstrapUrl`. Delivering only this key through device management makes the whole installation managed, and the app then ignores the local file entirely, including its `bootstrapUrl`. Consent gates only bootstrap-delivered values. The same keys delivered through device management apply without prompting. Versions that predate a key's availability ignore that key in a bootstrap response (the [configuration changelog](/docs/third-party/claude-desktop/configuration-changelog) records when each key became available), so a response can safely carry keys ahead of a fleet upgrade. ### Caching and `expiresAt` | Field | Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$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. | | `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. | Omitted → the client infers the version from the document shape (any cluster key present → 2, otherwise 1). Omitted → cache for 1 hour. A number ≥ 10¹² is read as Unix epoch **milliseconds**; below that, **seconds**. 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. ### Origin pinning When 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. When you supply `bootstrapOidc`, your configuration server and gateway are independent hosts you control, so origin pinning is disabled and the response can name any HTTPS host. In this mode the bootstrap server's integrity is the only control on where inference and MCP traffic are sent. ## MDM configuration keys | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------ | --------- | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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`. | | 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. | | 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). | | 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. Deprecated: `bootstrapHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no bootstrap request headers will be sent (the fetch may then fail to authenticate). | | 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. | | 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`. Previously named `trustBootstrapLocalExec` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): each user will be asked to consent to bootstrap-delivered sign-in targets, endpoints, helper scripts and connectors, even when the bootstrap URL came from a device-managed profile. | 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. 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. | Field | Type | Default | Description | | --------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `scopes` | `string` | — | Space-separated; the token’s audience must match what your bootstrap server validates. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `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. | 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. 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`. No `inferenceProvider` is needed in the MDM profile when using bootstrap; the response supplies it. ## Troubleshooting | Symptom | Likely cause | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Identity provider shows `AADSTS900144` (Entra) or `invalid_request: scope` | `bootstrapOidc.scopes` is empty. It is required. | | Server logs `unexpected "iss"` or `unexpected "aud"` for a valid Entra token | The app registration's accepted-token-version is at its default. Set it to `2` in the Manifest, or accept both v1 (`sts.windows.net` / `api://CLIENT_ID`) and v2 forms in your server. | | Sign-in succeeds in the browser but the app immediately re-prompts | Your server returned `401` or `403`. For `401`, check the `aud` match: the requested scope must produce a token whose audience your server validates. For `403`, the user authenticated but is not in the entitled group or role. | | Entra returns `AADSTS500011` ("resource principal not found") | The app registration has no Application ID URI. Set one under **Expose an API**. | | Silent refresh fails after \~1 hour with `AADSTS90009` | `scopes` uses the `api://CLIENT_ID/.default` form. Use the bare-GUID `CLIENT_ID/.default` form. | | Some keys you returned are not applied | They failed schema validation, are structurally excluded, or were dropped by origin pinning. If the app instead shows an **Apply settings from your organization?** dialog, the whole response is waiting for [user consent](#keys-that-require-user-consent) and none of it has been applied yet. The desktop log (`~/Library/Logs/Claude-3p/main.log` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\main.log` on Windows) records which keys were dropped and why. | | Browser opens to your identity provider's device page instead of yours | In device-code mode, `verification_uri` must share the `bootstrapUrl` origin. Federate behind your own page. | # Built-in connectors Source: https://claude.com/docs/third-party/claude-desktop/built-in-connectors MCP servers bundled inside Claude Desktop on 3P: which servers ship in the app, how built-in entries work, and where each one is documented Claude Desktop ships copies of some MCP servers inside the app itself. A built-in server runs as a local process on the user's device and calls the data provider directly, so no data or tokens pass through Anthropic's infrastructure. There is nothing to install or host on your side: a [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry activates the server, and the app runs it. A built-in entry names the bundled server in a `server` field, in place of the `url`, `transport`, or `command` fields that remote and stdio entries use. An entry that mixes `server` with any remote or stdio field is rejected. ## Available servers | Server | `server` value | What Claude can reach | Setup guide | | ------------- | -------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Microsoft 365 | `microsoft365` | Outlook mail and calendar, OneDrive, SharePoint, and Teams, through Microsoft Graph | [Connect to Microsoft 365, local connector](/docs/third-party/claude-desktop/connectors-m365#local-connector) | | Web search | `websearch` | Web search through Brave, Tavily, Exa, or a search endpoint you host | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) | | GitHub (beta) | `github` | Repositories, issues, pull requests, and other GitHub data, on github.com or GitHub Enterprise Server | [Connect to GitHub, local connector](/docs/third-party/claude-desktop/connectors-github#local-connector) | Each guide covers its server in full, including how the built-in server compares with the remote alternative where one exists. The GitHub built-in server is in beta, and the **Add server** menu marks it with a **Beta** pill. 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. ## How built-in servers behave All built-in servers share the same model: * **Managed configuration only.** A built-in server activates only from a `managedMcpServers` entry. Users cannot add one themselves and cannot remove one you deploy. * **Local execution.** The server runs on the user's device, and its network calls go directly to the data provider (Microsoft, your search provider, or GitHub). No Anthropic host is in the data path. * **Sign-in on the device.** Where the server needs user credentials (Microsoft 365 and GitHub), the user signs in from the app, and tokens are stored encrypted on the device. **Disconnect** in connector settings signs the user out. The web search server has no user sign-in; you supply the search key in the entry. * **Tool approvals.** Each entry accepts the same per-tool [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers) as any managed server. Without a policy, built-in write tools ask the user before each call, and a small set of irreversible actions (sending mail or merging a pull request, for example) stays at ask or stricter no matter what the policy says. * **Versioned with the app.** Each built-in server requires a Claude Desktop version that includes it. On older versions, the server is missing from the **Add server** menu, **Test connection** reports that it is not included, and a deployed entry is dropped. The fix is to upgrade Claude Desktop. # Chat in Claude Desktop on 3P Source: https://claude.com/docs/third-party/claude-desktop/chat What Chat can and cannot do in Claude Desktop on 3P, and how to configure it Chat 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 the project's memory 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. Like everything else in 3P mode, Chat conversations run against your configured inference provider, and conversation history lives on the user's device. See [User identity and local data](/docs/third-party/claude-desktop/data-storage#chat-conversations) for exactly what is written where and what can leave the device. ## What a Chat conversation can reach | Capability | Scope | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web search | Same options and rules as Cowork and Code sessions; depends on your provider or a configured search server. See [Web search](/docs/third-party/claude-desktop/web-tools#web-search). | | Web fetch | Runs in the app on the device, never inside a sandbox. Every fetch is checked against `coworkEgressAllowedHosts`; with no allowlist configured, fetch is disabled. See [Web fetch](/docs/third-party/claude-desktop/web-tools#web-fetch). | | Attached files | Read-only access to files the user attaches to the conversation. Each attachment is copied or hard-linked into the conversation's local uploads directory. | | Project memory | For a conversation inside a project, read-only access to that project's [memory](/docs/third-party/claude-desktop/data-storage#memory): the notes written during Cowork sessions in that project. Not used if memory was paused when the conversation started, or for conversations outside a project. | | Scratch directory | A per-conversation working directory where Claude can create and edit files (documents, data files, HTML artifacts) and offer them to the user for download or preview. | | Managed MCP servers | The servers you provision via [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) are available in Chat with the same approval model as Cowork sessions: a tool's `toolPolicy` of `"allow"` pre-approves it, `"blocked"` blocks it, and `"ask"` requires user approval on every call. A tool with no policy asks the user, who can allow it once or grant standing approval, as in Cowork. | | Clarifying questions | Claude can present multiple-choice questions to the user (the `AskUserQuestion` tool). | | Plugin skills and hooks | Skills from the plugins you provision through [organization plugins](/docs/third-party/claude-desktop/extensions#organization-plugins-admin) or [plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin) are available in Chat, including as slash commands. Hooks from those plugins also run in Chat conversations as they do in Cowork sessions, as described under [Plugin hooks](/docs/third-party/claude-desktop/extensions#plugin-hooks). Plugin sub-agents do not run in Chat, and a skill that runs scripts needs [advanced file analysis](#advanced-file-analysis). Plugin skills require Claude Desktop 1.44121.4 or later, and plugin hooks run in Chat on Claude Desktop 1.52386.0 or later. | | Code execution | Off by default. When you enable [advanced file analysis](#advanced-file-analysis), Claude can additionally run code in an offline local sandbox against attached files. | `disabledBuiltinTools` and `builtinToolPolicy` apply in Chat the same way they do in Cowork and Code sessions. For example, adding `"WebFetch"` removes web fetch from Chat conversations too. ## What a Chat conversation cannot do In a Chat conversation, Claude cannot: * **Read or write the filesystem** beyond the conversation's own uploads and scratch directories and, inside a project, the project's memory (read-only). Chat conversations never receive folder access: the tool for requesting folder access is removed, and the app refuses folder grants to a Chat conversation even when requested through internal interfaces. * **Run code on the host.** There is no shell access. With advanced file analysis off (the default), the sandbox VM is never started for Chat; with it on, code runs only inside the offline sandbox described below, never on the host itself. * **Act without asking.** Chat conversations always run in the default permission mode. Auto mode and other reduced-supervision modes are rejected for Chat regardless of `autoModeEnabled`. * **Create or run scheduled tasks**, or list the ones that exist. * **Escalate into an agentic session.** The tools that launch Code sessions or dispatch background agent tasks are removed. When a request needs capabilities Chat doesn't have, Claude says so and suggests starting the task in Cowork instead. * **Read other conversations.** The tools that list sessions or read other sessions' transcripts are removed, so a Chat conversation cannot search or quote your other chats, Cowork sessions, or Code sessions. * **Write memory.** Chat conversations cannot add to or change [memory](/docs/third-party/claude-desktop/data-storage#memory); inside a project they read the project's memory as described above, and outside a project they use no memory. These restrictions are enforced in the app's main process, not just hidden in the UI. ## Advanced file analysis By default, Chat can read attached files only in the formats Claude understands natively. Setting `chatAdvancedFileAnalysisEnabled` to `true` lets Claude also run code against attachments. This is useful for spreadsheets, PowerPoint files, and other formats that need parsing, and for inline data analysis on attached data. The execution environment is intentionally narrower than the Cowork sandbox: * Code runs in the same isolated local VM that Cowork uses. For Chat, the VM starts only when analysis is coming: on the first analysis call, or at the start of a turn with files attached. * The sandbox has **no network access**. This is unconditional for Chat and independent of `coworkEgressAllowedHosts`: an allowlist that opens egress for Cowork sessions does not open it for Chat analysis. * The only conversation data the sandbox sees is the conversation's attached files (read-only), its scratch directory (writable), and, for a conversation inside a project, that project's memory (read-only), plus read-only reference material bundled by the app. No user folders, and no other sessions' working directories or transcripts. * Each command runs independently; results land in the scratch directory, where Claude can offer them to the user as downloads or artifacts. The 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, 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. 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)). ## Configuration | Key | Default | Effect | | ------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | [`chatTabEnabled`](/docs/third-party/claude-desktop/configuration#chattabenabled) | off | Makes Chat available. Chat is opt-in: it appears in the app only when this key is explicitly `true`. | | [`chatAdvancedFileAnalysisEnabled`](/docs/third-party/claude-desktop/configuration#chatadvancedfileanalysisenabled) | off | Allows code execution on attached files in the offline sandbox, as described above. Has no effect unless Chat is enabled. | When `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. 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. Enforcement 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. The rule that at least one surface must stay enabled counts Chat only when `chatTabEnabled` is explicitly `true`: a configuration that disables Cowork and Code without enabling Chat re-enables Cowork with a validation warning, rather than leaving users with an empty app. With `chatTabEnabled` set to `true`, a chat-only configuration is valid. ## Where Chat data lives Chat conversations are stored on the local device, in the same per-session layout as Cowork sessions: conversation history, attachment copies, scratch outputs, and a tamper-evident audit log, all under the application-data directory. Nothing is synced to a server, and there is no server-side index of past conversations. See [Chat conversations](/docs/third-party/claude-desktop/data-storage#chat-conversations) on the data-storage page for the breakdown. # Deploy Claude Desktop on 3P with the Claude API Source: https://claude.com/docs/third-party/claude-desktop/claude-api Configure Claude Desktop on 3P to send inference directly to Anthropic's Claude API instead of a cloud-provider-hosted Claude deployment To use Anthropic's Claude API directly as the inference provider, set [`inferenceProvider`](/docs/third-party/claude-desktop/configuration#inferenceprovider) to `anthropic` and supply an API key as described below. 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. 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. ## Choose an authentication approach There are three options. With neither a static key nor a credential helper configured, each user sees **Sign in with Claude Console** on first launch: the app opens the browser, the user signs in and selects a Claude Console (API) organization, and the app creates a personal API key for them and stores it encrypted on the device until it is revoked in Console; usage is billed to that Console organization. Alternatively, place a static API key in the managed configuration as `inferenceAnthropicApiKey`, or, where static keys aren't permitted, set [`inferenceCredentialHelper`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) to an executable that fetches a short-lived credential at runtime; see [Write a credential helper](/docs/third-party/claude-desktop/credential-helper). Browser sign-in reaches `platform.claude.com` in addition to `api.anthropic.com`. ## Configure the app ### Configuration keys | Setting | Type | Availability | Default | Description | | ------------------------------------------------------ | -------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | | Claude API key
`inferenceAnthropicApiKey` | `string` | MDM + Bootstrap
Added in 1.8089.0 | — | Leave blank to fetch a key via browser sign-in, or to supply the key via a credential helper. | # Code in Claude Desktop on 3P Source: https://claude.com/docs/third-party/claude-desktop/code How Claude Desktop on 3P configuration applies to the embedded Claude Code engine Code in Claude Desktop on third-party (3P) is the embedded [Claude Code](https://code.claude.com/docs/en/overview) interface. It runs the same Claude Code engine as the standalone CLI, with a graphical session manager, and it inherits your Claude Desktop on 3P configuration automatically. ## How configuration propagates When the app starts a Code session, it translates your Claude Desktop on 3P [configuration keys](/docs/third-party/claude-desktop/configuration) into the equivalent Claude Code settings and passes them to the session. You configure one profile, and Cowork and Code both honor it. Each key reaches Claude Code through one of two mechanisms, and the distinction matters if you also deploy Claude Code's own managed settings (see [the next section](#interaction-with-claude-code%E2%80%99s-own-managed-settings)). ### Always applied These keys are passed directly to the Claude Code process as environment variables or launch options. They take effect on every Code session and cannot be overridden by user-level Claude Code settings or by a separately deployed `managed-settings.json`. | Claude Desktop on 3P key | Effect in Code sessions | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inferenceProvider` and all provider credential keys (`inferenceGateway*`, `inferenceAnthropicApiKey`, `inferenceVertex*`, `inferenceBedrock*`, `inferenceFoundry*`, `inferenceCredentialHelper*`) | Selects the inference backend and supplies credentials. Code sessions use the same provider, endpoint, and credentials as Cowork sessions. | | `inferenceModels` | Populates the model picker. The first entry is the default for new Code sessions. | | `autoModeEnabled` | Offers **Auto mode** in the Code session's permission selector. A separately deployed Claude Code managed-settings file that sets `disableAutoMode` to `"disable"` overrides this and keeps Auto mode hidden; see below. | | `disabledBuiltinTools` | Removes the listed tools from Code sessions. Tools your provider does not support, such as WebSearch on Amazon Bedrock, are removed automatically in addition to your list. | | `builtinToolPolicy` | Tools set to `"ask"` require approval on each call in Code sessions, enforced via a PreToolUse hook and Claude Code `permissions.ask` rules. | | `disableBypassPermissionsMode` | Removes bypass permissions mode. The app stops offering the mode and starts a session that requests it in a stricter permission mode instead, independent of Claude Code managed-settings precedence. The key requires Claude Desktop 1.46388.1 or later. A separately deployed Claude Code managed-settings file that sets `permissions.disableBypassPermissionsMode` to `"disable"` removes the mode as well. | | `skipWebFetchPreflight` | Turns off Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch) against `api.anthropic.com`. A separately deployed Claude Code managed-settings file that sets `skipWebFetchPreflight` takes precedence. | | `managedMcpServers` | Makes the same managed MCP servers available in Code sessions. The app handles the connection and authentication; the Code session sees only the resulting tool list. | | `mcpToolTimeoutSec` | Applies your per-call MCP tool timeout to Code sessions as well, taking precedence over a user-set `MCP_TOOL_TIMEOUT`. | | `organizationInstructions` | Appended to the Code session's system prompt after Claude Code's own. `CLAUDE.md` instructions still apply. | | `otlpEndpoint`, `otlpProtocol`, `otlpHeaders`, `otlpResourceAttributes` | Routes Claude Code's OpenTelemetry metrics and logs to your collector. See [Telemetry](/docs/third-party/claude-desktop/telemetry). | | `disableEssentialTelemetry`, `disableNonessentialTelemetry` | Disables Claude Code's crash reporting and usage telemetry to Anthropic, mirroring Cowork. | | `disableAutoUpdates` | The embedded Claude Code engine never self-updates regardless of this key; its version is managed by the app's own updater. | | `inferenceMaxTokensPerWindow`, `inferenceTokenWindowHours` | The token budget is shared across Cowork and Code sessions and enforced before each turn. | ### Applied as managed policy These keys are translated into Claude Code [managed settings](https://code.claude.com/docs/en/settings#settings-files) and supplied to the session as policy. They take precedence over user and project settings, but they participate in Claude Code's managed-settings precedence if you have also deployed a separate Claude Code policy. | Claude Desktop on 3P key | Claude Code policy it produces | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `coworkEgressAllowedHosts` | A network sandbox restricted to your hosts plus the inference and telemetry endpoints, `WebFetch` permission rules for the same hosts, and `allowManagedDomainsOnly`. | | `allowedWorkspaceFolders` | A filesystem sandbox for shell commands, which can then create or change files only inside your allowed roots and the session's temporary locations. The sandbox does not restrict which files those commands read unless you also set `blockReadsOutsideWorkingDirectories`. The roots are also passed as `additionalDirectories` at launch, which is always applied independent of managed-settings precedence, and the app keeps Claude's file tools inside the roots. The app also refuses to start a Code session outside an allowed root. | | `blockReadsOutsideWorkingDirectories` | Claude Code's `permissions.blockReadsOutsideWorkingDirectories` for Code sessions. Claude's file tools refuse to read outside the working directories (the session's folder plus your allowed roots, if any) in every permission mode. Where the sandbox from `allowedWorkspaceFolders` or `coworkEgressAllowedHosts` is running, it also hides the user's home directory and similar locations, such as other users' home folders and mounted volumes, from shell commands, so a sandboxed command that reads there fails without a prompt. Without a running sandbox, a shell command that reads outside the working directories, or that Claude Code cannot analyze, asks the user for approval first, even in bypass permissions mode. The key requires Claude Desktop 1.46388.1 or later. The block takes effect only in sessions that run Claude Code v2.1.257 or later; if the app cannot install its current Claude Code engine and a session runs one older than v2.1.257 that is still on the device, that session runs without the block and the app logs a warning. | | `managedMcpServers` | `strictPluginOnlyCustomization` set to `["mcp"]`, so the Code session does not load MCP servers that users define on Claude Code's side (`~/.claude.json`, a project's `.mcp.json`, or `claude mcp add`); your managed servers, which the app connects and supplies to the session itself, and MCP servers bundled in plugins still load. When [`isLocalDevMcpEnabled`](/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled) is `false`, the app also sets an `allowedMcpServers` list that admits only remote servers, with `allowManagedMcpServersOnly`, so local (stdio) servers bundled in plugins from marketplaces or that users install themselves are refused, while those plugins' remote servers still connect. Per-tool `toolPolicy` values on each server are emitted as `permissions.deny` (for `blocked`) or `permissions.ask` (for `ask`) rules against the corresponding `mcp____` names. | The 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 does not sandbox shell commands on Windows devices, and on a Linux device or SSH host without the dependencies commands run unsandboxed with a warning in the session. In those cases, and when neither sandbox key is set, `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 cannot verify. Under `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. An allowed root that is or contains the home directory, such as `~` or `/Users`, leaves the home directory readable, so list folders below it. The block guards against content a session reads steering Claude into the user's files, not against the user, who can re-open any path, up to their whole home folder, with `sandbox.filesystem.allowRead` (shell commands) or `permissions.additionalDirectories` (file tools and shell commands) in their own Claude Code settings, while a settings file tracked in a git repository cannot. ## Interaction with Claude Code's own managed settings Claude Code can also be configured directly by deploying a [`managed-settings.json` file](https://code.claude.com/docs/en/settings#settings-files), an OS configuration profile for Claude Code, or (with Anthropic authentication) server-managed settings. If a device has any of these, Claude Code treats it as the administrator policy and, by default, **ignores** the policy values Claude Desktop supplies from the [Applied as managed policy](#applied-as-managed-policy) table. The [Always applied](#always-applied) keys are unaffected. To have Claude Desktop's restrictions apply on top of your Claude Code policy, set `parentSettingsBehavior` to `"merge"` in the Claude Code managed settings you deploy: ```json managed-settings.json theme={null} { "parentSettingsBehavior": "merge" } ``` With `"merge"`, Claude Desktop's policy values are layered under your Claude Code policy. Your values win any conflict, deny and allow lists are unioned, and Claude Desktop's values are filtered so they can only tighten policy, never loosen it. See [`parentSettingsBehavior`](https://code.claude.com/docs/en/settings-reference#parentsettingsbehavior) in the Claude Code settings reference. Requires Claude Code v2.1.133 or later, which ships with Claude Desktop on 3P. With `"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. In a third-party deployment there is no Anthropic authentication, so Claude Code's server-managed settings tier is never present. If you have not separately deployed a Claude Code `managed-settings.json` or OS profile, Claude Desktop's policy applies automatically and you do not need to set `parentSettingsBehavior`. ## Remote sessions over SSH A Code session can run its Claude Code engine on a remote host over SSH while the session's interface stays in Claude Desktop on the user's device. In a 3P deployment this is off until you set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist), because the app forwards the session's inference credential to the host. [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) lists the credential kinds that work on a remote host and which of the keys above apply there. ## Further reading * [Claude Code settings reference](https://code.claude.com/docs/en/settings-reference) * [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) * [Settings precedence](https://code.claude.com/docs/en/settings#settings-precedence) ## Disabling Code To turn off Code, set `isClaudeCodeForDesktopEnabled` to `false` in your Claude Desktop on 3P configuration. Users can no longer open Code. Cowork is unaffected, and so is [Chat](/docs/third-party/claude-desktop/chat#configuration) if you have enabled it. # Configuration reference Source: https://claude.com/docs/third-party/claude-desktop/configuration Every managed-configuration key Claude Desktop on 3P supports, what it controls, and recommended security profiles Most settings on this page are easier to configure in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). Use this reference when you're scripting an MDM policy or bootstrap response by hand. Claude Desktop on third-party (3P) is configured through OS-native managed preferences: a `.mobileconfig` profile on macOS, registry policy on Windows, or a root-owned JSON file on Linux (organizations in the admin console beta can instead deliver these settings from **Organization settings** on claude.ai). This page documents every supported key. For the desktop release each key first appeared in, see the [configuration changelog](/docs/third-party/claude-desktop/configuration-changelog). The easiest way to author a configuration is the in-app configuration window (**Developer → Configure Third-Party Inference…**), which validates values, shows per-provider requirements, and exports directly to `.mobileconfig` or `.reg`. Use this reference when you need to author policy by hand, audit an existing profile, or understand exactly what a key does. ## How keys are read | Platform | Managed (MDM) location | Local (user) location | | -------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- | | macOS | `/Library/Managed Preferences//com.anthropic.claudefordesktop.plist` | `~/Library/Application Support/Claude-3p/configLibrary/` | | Windows | `HKLM\SOFTWARE\Policies\Claude` (machine), `HKCU\SOFTWARE\Policies\Claude` (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` | | Linux | `/etc/claude-desktop/managed-settings.json` | `~/.config/Claude-3p/configLibrary/` | The local location is a directory: `_meta.json` records which saved configuration is applied, and each configuration is a `.json` file alongside it. The in-app configuration window writes here. When a managed source is present, it wins and locally written values are ignored. The exception is a managed source that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) (the update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, and `updateViaUpdatesHost`, the lifecycle keys `relaunchEnforcementHours` and `configRecheckIntervalMinutes`, or the [network proxy keys](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration)): those keys are enforced from the managed source, but the rest of the configuration stays local and user-editable. Configuration takes effect **at launch**, so fully quit and reopen the app after any change. From version 1.46388.1 a running app also notices a changed managed configuration at its next re-check ([`configRecheckIntervalMinutes`](#configrecheckintervalminutes), 10 minutes by default), prompts the user to restart, and requires the restart after [`relaunchEnforcementHours`](#relaunchenforcementhours) (24 hours by default). On Windows, the two policy hives are not merged: when machine policy is present under `HKLM\SOFTWARE\Policies\Claude`, the app ignores `HKCU\SOFTWARE\Policies\Claude` entirely; [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) has the exact rule. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) for the full precedence rules. Claude Desktop on 3P reads the same managed-configuration sources as standard Claude Desktop but ignores keys scoped to standard deployments. Keys such as `forceLoginOrgUUID` have no effect in a 3P deployment. ### Value types Write every value as a **string** in the OS preference store, even booleans and arrays. | Documented type | What to write | Example | | ---------------- | ---------------------------------------------- | --------------------------------------------- | | string | Plain string | `vertex` | | boolean | `"true"` or `"false"` (or `1` / `0`) | `"true"` | | integer | Decimal string | `"3600"` | | string\[] (JSON) | JSON array **encoded as a string** | `["claude-sonnet-5","claude-opus-5"]` | | object (JSON) | JSON object mapping name to value, as a string | `{"X-Org-Id":"team1"}` | | object\[] (JSON) | JSON array of objects, as a string | see [`managedMcpServers`](#managedmcpservers) | Array- and object-typed keys such as `inferenceModels`, `inferenceGatewayOidc`, `managedMcpServers`, `coworkEgressAllowedHosts`, and `otlpHeaders` are single keys whose value is a whole JSON document. The portable encoding is a JSON string, which works on every platform. In a `.mobileconfig` that is a single `` element containing `[...]` or `{...}`, and on Windows a `REG_SZ` value. A macOS profile may instead carry the value as a native `` or ``, which the app reads as the equivalent JSON. Separate keys with dotted names, such as `inferenceGatewayOidc.clientId`, are never read. On Windows, write registry values as `REG_SZ`, directly under the policy key rather than nested in a subkey (the app never reads subkeys). `REG_DWORD` is also accepted for boolean and integer keys and is read as its decimal value. Avoid `REG_EXPAND_SZ`: the app counts it toward machine policy being present but cannot read its contents. The app cannot see `REG_QWORD`, `REG_MULTI_SZ`, or `REG_BINARY` values at all. ### Linux The managed source on Linux is a single JSON file, `/etc/claude-desktop/managed-settings.json`, with keys at the top level exactly as named in the [reference](#reference) — no wrapper object, no nesting: ```json theme={null} { "inferenceProvider": "gateway", "inferenceGatewayBaseUrl": "https://gateway.example.com/v1", "inferenceGatewayApiKey": "sk-example", "inferenceCustomHeaders": { "X-Tenant-Id": "acme" } } ``` Because the file is real JSON, array- and object-typed keys use native JSON values — the string-encoding rule above applies to plist and registry sources only. (String-encoded values are also accepted, so a profile generated for another platform can be reused.) The file is only honored when it can't be edited by the user it configures: * `managed-settings.json` must be a regular file (not a symlink), owned by root, and not group- or world-writable. * `/etc/claude-desktop` itself must be a directory (not a symlink), owned by root, and not group- or world-writable. A file that fails these checks is rejected: none of its settings are applied, the app treats the device as managed but unreadable, and local settings are also disabled until the file is fixed and the app is relaunched. The reason is logged to `main.log` in the app's logs directory — `~/.config/Claude/logs/` (or `~/.config/Claude-3p/logs/` once the app is running in 3P mode); search for `managed-settings.json`. The same log names any key that fails schema validation. There is no per-user managed location on Linux; per-user configuration goes through the in-app configuration window, which writes to the local `configLibrary` directory above. ## Reference The reference below is generated from the configuration schema and grouped to match the sidebar of the in-app configuration window. The **Availability** column shows whether a key can be set in an MDM profile, returned from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), or both. Its second line is the Claude Desktop version that added the key. For how the keys under **Models** work together, see [Models and effort levels](/docs/third-party/claude-desktop/models). ## Connection | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------------------------------------- | ---------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Custom inference headers
`inferenceCustomHeaders` | `object` | MDM + Bootstrap
Added in 1.8089.0 | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders` (the old name is accepted until October 7, 2026). If it is still present after that, no custom inference headers will be sent. Deprecated: `inferenceCustomHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no custom inference headers will be sent. | | Sign-in session lifetime
`inferenceSessionLifetimeSec` | `integer` | MDM + Bootstrap
Added in 1.14271.0 | — | How long a sign-in stays valid under your IdP’s session policy. Shows a re-authenticate banner before it expires. | | Helper script
`inferenceCredentialHelper` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Absolute path to an executable that prints the credential, optionally with per-request headers. | | Helper script arguments
`inferenceCredentialHelperArgs` | `string[]` | MDM + Bootstrap
Added in 2.110.0 | — | Arguments passed to the helper script, one per entry, in order. Leave unset to run it with none. | | Helper script TTL
`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | `3600` | Helper output is cached for this many seconds; once it expires the helper re-runs without a relaunch (before the next turn when set above 120). Defaults to `3600`. | | Credential helper timeout
`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.8089.0 | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | | Re-run helper for silent refresh
`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap
Added in 1.10628.0 | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | | Proxy server URL
`egressProxyUrl` | `string` | MDM only
Added in 1.44121.1 | — | Send the app’s and the agent’s traffic through this HTTP proxy instead of the operating system’s proxy settings. | | Proxy auto-config (PAC) URL
`egressProxyPacUrl` | `string` | MDM only
Added in 1.44121.1 | — | URL of a PAC file that decides the proxy per request. Wins over the proxy server URL when both are set. | | Enable IPv6 in the workspace VM
`coworkVmIpv6Enabled` | `boolean` | MDM + Bootstrap
Added in 1.52386.0 | — | Give the Cowork workspace VM an IPv6 address and route so the agent’s tools can reach IPv6-only hosts through the device. macOS and Windows; off by default. | | Artifact preview iframe origin
`userContentRendererUrl` | `string` | MDM + Bootstrap
Added in 1.24012.0 | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. | | Inference provider
`inferenceProvider` | `enum` | MDM + Bootstrap
Added in 1.2581.0 | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. | | Credential kind
`inferenceCredentialKind` | `enum` | MDM + Bootstrap
Added in 1.8555.0 | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `workforce`. Deprecated: `inferenceCredentialKind: "oauth" (Vertex AI)` (accepted until October 7, 2026); use "interactive" — the same Google sign-in under its new name (in hosted or nested documents, switch once every desktop is on a release that knows the Vertex "interactive" kind). If it is still present after that, "oauth" will no longer be a Vertex AI credential kind: the value will be reported as invalid and ignored — the device will then derive the kind from the credential fields present (Google sign-in when an OAuth client id is set), and the hosted editor will refuse to save the configuration until the kind is changed. Deprecated: `inferenceCredentialKind: "interactive" together with inferenceVertexWorkforceAudience (Vertex AI)` (accepted until October 7, 2026); use "workforce" — or remove inferenceVertexWorkforceAudience if Google sign-in ("interactive") is what is meant. If it is still present after that, the audience will no longer imply Workforce Identity: the kind will stay "interactive" (Google sign-in), which needs inferenceVertexOAuthClientId — without it the configuration will be reported as incomplete and inference will not start. | Sent on every inference and model-discovery request (joined into the CLI's `ANTHROPIC_CUSTOM_HEADERS`). Use this for fleet-wide, non-secret constants. **Do not put API keys, bearer tokens or other credentials here** — this map is stored and distributed as plain configuration. For tokens, and for per-user or per-session values, have the **credential helper script** emit JSON with a `headers` field; those are merged over these static entries (helper wins on conflict). Claude runs the executable with the entries of **Helper script arguments** as its arguments (none by default) and reads **stdout** (trimmed). Exit code must be `0`; any output on **stderr** is logged but ignored. **Stdout must contain only one of the formats below** (no banners, prompts, or log lines). **Output format** is either: * a single bare token (the API key / bearer token), or * a JSON object `{"token": "...", "headers": {"Name": "Value", ...}}` when per-request headers are needed (merged over **Custom inference headers**, helper wins on conflict) The helper receives `CLAUDE_HELPER_CONTEXT` in its environment (`interactive`, `mid-session-refresh`, `background`, `scheduled-task`, `setup-test`) so it can decide whether to prompt the user — see the credential-helper docs for the full contract. Result is cached for the TTL below. On TTL expiry the helper is re-invoked transparently (no user prompt, no relaunch). **Expiry and refresh:** the app checks the active credential's expiry before each turn and refreshes silently when possible (re-runs the helper, or uses the stored refresh token for interactive sign-in kinds). If the provider returns HTTP 401 mid-turn, the same silent refresh is attempted before surfacing an error. When silent refresh fails, a prompt appears with a provider-specific action (re-sign-in for interactive kinds; admin-contact for static credentials). Applies to all providers, and to both Cowork and Code. **Typical use:** a shell script that pulls from Keychain, 1Password CLI, or an internal secret broker. Example: `security find-generic-password -s anthropic-api -w` If this field is set, static credential fields (API key, bearer token) are ignored. The helper always wins. Each entry reaches the executable as one argument, exactly as written: `["--environment", "production"]` runs `helper --environment production`. Use it to keep one installed script and let the configuration each user receives decide what it does (which environment, tenant or vault to read), instead of packaging a script per case. Entries may not be empty and may not contain a double quote (`"`), a percent sign (`%`) or control characters, on any platform: a Windows `.cmd`/`.bat` helper receives its arguments through `cmd.exe`, where those characters would change the command. A `.cmd`/`.bat` script sees each argument quoted (`%1` is `"production"`, `%~1` strips the quotes); `.ps1`, `.exe` and POSIX helpers receive them bare. Arguments are visible in the diagnostic report and to other processes on the machine, so do not put secrets in them; the helper exists to fetch the secret. A changed list takes effect the way a changed path does. Pins the app (sign-in, the connection test, model discovery, MCP servers, plugins), the Claude Code engine behind Chat, Cowork, and Code, and on macOS and Windows the Cowork workspace VM (the agent's shell, package-install, `git`, and plugin commands, and the whole engine under `requireCoworkFullVmSandbox`) to one HTTP proxy. Use it when your gateway or the internet is reachable only through a corporate proxy and you cannot rely on the system proxy. It is a reachability setting, not an egress control. The value is an `http://` or `https://` URL, usually with a port. SOCKS proxies and embedded credentials (`user:pass@`) are rejected. Give a local forwarding proxy on the device as `http://127.0.0.1:port`; an `https://` loopback address cannot be verified from inside the Cowork workspace VM. Requests to `localhost`, `127.0.0.1`, `[::1]`, and `*.local` names bypass the proxy so local MCP servers keep working; everything else goes through it, and if the proxy is unreachable requests fail rather than connect directly. The engine receives it as `HTTPS_PROXY` and `HTTP_PROXY` with a matching `NO_PROXY`; if Claude Code managed settings on the device set those variables, they win for the engine on the host. Traffic that never uses this proxy: the Cowork workspace VM on Linux, credential and header helper scripts, the update download, the Windows sign-in broker, and pages opened in the system browser. Read once at launch from device management (MDM) or the local configuration file only; a configuration server cannot deliver it, because the app may need the proxy to reach that server. A profile that sets only this key (or only the other app-behavior keys, such as `disableAutoUpdates`) does not take over a connection users set up in the app, but those keys are read from one source as a group, so put the proxy in the same profile as your update settings. Changes apply at the next app start. When `egressProxyPacUrl` is also set, the PAC file wins and this key is ignored. At launch the app downloads the PAC script and asks it which proxy to use for each request, as a browser would, instead of following the operating system's proxy settings. Same value rules, coverage, exclusions, and delivery as `egressProxyUrl`, except that bypassing is the script's decision: `localhost`, `127.0.0.1`, and `[::1]` still never use a proxy, but `*.local` names and everything else follow whatever it returns. If the PAC file cannot be downloaded, the app connects directly rather than failing. On macOS and Windows the Cowork workspace VM is handed a copy of the script when it starts and evaluates it for each request itself; there `myIpAddress()` returns the VM's internal address rather than the device's, so a script that chooses by client subnet gives the VM its off-network answer (if that download fails, the VM connects directly). The Claude Code engine behind Chat, Cowork, and Code cannot evaluate a PAC file, so the app hands it one proxy (whichever the script returns for your inference endpoint) plus a bypass for loopback and `*.local` names. If the script answers `DIRECT` or only `SOCKS` for that endpoint, the engine uses no proxy at all, so have it return an HTTP `PROXY host:port` entry there; if the engine needs different rules, set `HTTPS_PROXY` and `NO_PROXY` in Claude Code managed settings, which win for the engine on the host. When set to `true`, the Cowork workspace VM on macOS and Windows gets a static IPv6 address (a unique local `fd…` address) and an IPv6 default route on its virtual network next to its IPv4 address, and the VM's gateway forwards that traffic over the device's own IPv6 connectivity, as it already does for IPv4. Use it when the tools the agent runs in the VM (shell commands, package installs, `git`, plugin commands, and the whole engine under `requireCoworkFullVmSandbox`) must reach IPv6-only destinations. The VM's resolver then also returns IPv6 (AAAA) answers. A connection the VM makes over IPv6 succeeds only where the device's own IPv6 does; on a device without working IPv6, destinations that have both keep working over IPv4 and IPv6-only destinations stay unreachable. Because the VM's address is unique-local, most tools in it keep preferring IPv4 for destinations that have both, so IPv6 mostly carries traffic to IPv6-only destinations. This is a reachability setting, not an egress control: `coworkEgressAllowedHosts` keeps deciding which hostnames the agent's tools may reach, by name, over either protocol, and IPv6 literals are still not accepted there. Hosts your policies allow must also be reachable, and filtered the way you intend, over IPv6 on your network. Unset (default): the VM is IPv4-only and its resolver returns no IPv6 answers. A change takes effect the next time the workspace VM starts, typically at the next app launch. Does not apply to the Cowork workspace VM on Linux or to Code sessions, which use the device's own network stack. The app activates 3P mode only when this is set and the required credential keys for the selected provider are present and valid; otherwise it launches in standard mode. Keys for providers other than the selected one are ignored. Each provider's required keys are documented on its dedicated page under Inference providers. ### Anthropic | Setting | Type | Availability | Default | Description | | ------------------------------------------------------ | -------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | | Claude API key
`inferenceAnthropicApiKey` | `string` | MDM + Bootstrap
Added in 1.8089.0 | — | Leave blank to fetch a key via browser sign-in, or to supply the key via a credential helper. | ### Bedrock | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------- | -------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | AWS region
`inferenceBedrockRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. | | Bedrock base URL
`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. | | 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`. | | 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. | | 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. | | AWS SSO region
`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | IAM Identity Center home region. | | 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. | | 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. | | AWS profile name
`inferenceBedrockProfile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. | | 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. | | 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. | 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. ### Foundry | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------------- | -------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Azure AI Foundry resource name
`inferenceFoundryResource` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Azure AI Foundry resource name used to construct the endpoint URL. | | Azure AI Foundry base URL
`inferenceFoundryBaseUrl` | `string` | MDM + Bootstrap
Added in 2.110.0 | — | Full base URL for a gateway or proxy in front of Foundry, path included (replaces [https://RESOURCE.services.ai.azure.com/anthropic](https://RESOURCE.services.ai.azure.com/anthropic)). | | Azure AI Foundry API key
`inferenceFoundryApiKey` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | API key for Azure AI Foundry inference. | | Entra ID tenant ID
`inferenceFoundryTenantId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. | | Entra ID client ID
`inferenceFoundryClientId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. | | Entra ID sign-in flow
`inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.19367.0 | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. | Set this only when the app reaches Foundry through a gateway or proxy you run, such as Azure API Management. Requests go to `/v1/messages` instead of `https://.services.ai.azure.com/anthropic/v1/messages`, carrying the same credential and headers the app would send to Foundry: each user's Entra ID token for the Azure Cognitive Services audience as `Authorization: Bearer` with Entra sign-in, otherwise the API key or the credential helper's output. Claude Code sessions receive the value as `ANTHROPIC_FOUNDRY_BASE_URL`, so use the same value you would give Claude Code in a terminal. `inferenceFoundryResource` is still required and should name the resource behind the gateway; the app sends nothing to the resource directly while this is set. Must be https, or http to a proxy at a loopback address on the device itself (127.0.0.1, localhost or \[::1]). * **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled. * **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code. ### Gateway | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------- | --------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Gateway base URL
`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Full URL of the inference gateway endpoint. | | Stream idle timeout
`inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.44121.1 | — | Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800. | | Gateway API key
`inferenceGatewayApiKey` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | API key for the configured inference gateway. | | Gateway auth scheme
`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap
Added in 1.3036.0 | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"` (accepted until October 7, 2026); use inferenceCredentialKind: "interactive". If it is still present after that, browser sign-in will no longer be inferred from it — the key will be reported as invalid and, unless inferenceCredentialKind or another credential field (an API key, inferenceGatewayOidc) says how to sign in, the gateway connection will have no credential and inference will not start. Deprecated: `inferenceGatewayAuthScheme: "auto"` (accepted until October 7, 2026); use "bearer" (or remove the key — bearer is the default). If it is still present after that, the value will be reported as invalid and ignored like any unrecognised scheme; the key will then take its default, "bearer", so the credential will still be sent as an Authorization: Bearer header. | | Gateway sign-in flow
`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | | Gateway SSO IdP (OIDC)
`inferenceGatewayOidc` | `object` | MDM + Bootstrap
Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code's `CLAUDE_STREAM_IDLE_TIMEOUT_MS`). It only helps when the gateway writes SSE keep-alive `ping` events (or `:` comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code's defaults. A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. While this key is set, the app's value takes precedence over `CLAUDE_STREAM_IDLE_TIMEOUT_MS` in Claude Code's own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies. * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control. **External IdP mode.** The app discovers `/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at `/.well-known/oauth-authorization-server`. **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the gateway validates signature, `iss`, and `aud` (the `clientId` configured here). `access_token` sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); `scopes` must then name the gateway's registered API scope. Either way the gateway must check `aud`, not just signature and issuer, or it accepts any token from your tenant. **IdP setup.** The callback is `http://127.0.0.1:/callback` by default (`http://localhost:/callback` with `redirectHost: "localhost"`); register exactly the one you use and include `/callback`. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback` (any port; omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the gateway API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with the exact URI `http://127.0.0.1:/callback` and that port in `redirectPort`. **Refresh.** With `offline_access` the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an `id_token` on refresh, so a Google Workspace-backed gateway in `id_token` mode re-prompts about hourly; `access_token` mode is unaffected. | Field | Type | Default | Description | | --------------------------------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `bearerTokenType` | `enum` | `id_token` | Which token to send as the gateway bearer. Use access token for gateways that validate as an OAuth resource server. One of: `id_token`, `access_token`. | | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway’s API scope. offline\_access is appended automatically unless disabled below. | | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. | | `resource` | `string` | — | Absolute URL identifying the gateway as the access-token audience. Sent as the RFC 8707 resource parameter when set; leave unset for Microsoft Entra ID. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `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. | ### Models | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------ | ---------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Model discovery
`modelDiscoveryEnabled` | `boolean` | MDM + Bootstrap
Added in 1.8089.0 | — | Auto-populate the model picker from the provider at launch. | | Default to 1M context
`modelPrefer1mContext` | `boolean` | MDM + Bootstrap
Added in 1.28929.0 | — | When a user has no saved selection, start the picker on the 1M-context variant of the default model if it offers one. | | Model list
`inferenceModels` | `object[]` | MDM + Bootstrap
Added in 1.2581.0 | — | Override the auto-discovered model list. First entry is the default. | | Default model effort
`defaultModelEffort` | `enum` | MDM + Bootstrap
Added in 2.110.0 | — | Effort level the default model (the first listed model) starts at, instead of Anthropic’s recommended level: low, medium, high, xhigh or max. One of: `low`, `medium`, `high`, `xhigh`, `max`. | | Always start with the default model
`alwaysStartWithDefaultModel` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | When true, each new conversation or task starts on the default model, and a person’s model and effort changes are no longer saved as their default. | | Show estimated cost
`inferenceModelPricingEnabled` | `boolean` | MDM + Bootstrap
Added in 1.37937.0 | — | Show an estimated cost on the Usage page at Anthropic list price; turn on to set a multiplier or per-model rates. | | Price multiplier
`inferenceModelPricingMultiplier` | `number` | MDM + Bootstrap
Added in 1.37937.0 | — | Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Range: 0–1. | | Model pricing
`inferenceModelPricing` | `object[]` | MDM + Bootstrap
Added in 1.37937.0 | — | Per-model rates replacing Anthropic list price in the Usage page’s estimate. | | Model catalog metadata
`modelCatalogEnabled` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | Label and describe the model picker’s entries from the published Claude Code model catalog, instead of the app’s built-in table. | | Model catalog URL
`modelCatalogUrl` | `string` | MDM + Bootstrap
Added in 2.110.0 | — | Fetch the model catalog and its signature file from this URL (a mirror inside your network serving Anthropic’s published files) instead of downloads.claude.ai. | Auto-populate the model picker from the provider's model-list endpoint at launch. For gateway and Anthropic providers, a config that doesn't set this key skips discovery automatically when the model list below already makes it unnecessary; the toggle here only sets it explicitly on or off. Turn off if the endpoint isn't reachable from your network, or to use a fixed list. When off, the model list below is required and must use full model IDs (aliases like sonnet/opus are resolved via discovery). When a user has no saved selection, start the picker on the 1M-context variant of the default model (the first listed model, or the first model your endpoint returns under discovery) if it offers one. A saved selection is always kept; users who picked a model before this version need to pick the 1M row once, after which it persists. Equivalent to setting `prefer1m` on the default entry of `inferenceModels`, but also applies under dynamic discovery. Use the **provider's exact model ID**: Vertex publisher IDs (`claude-sonnet-5`), Bedrock inference-profile IDs (`us.anthropic.claude-sonnet-5`), or Foundry deployment names. Entries may be plain ID strings or objects. **Gateway:** the `name` must be the exact ID your gateway's `/v1/models` endpoint returns. If you set `supports1m` on an alias (`sonnet`) but discovery returns the full ID, the variant won't appear. **Extended context** (`supports1m`) is a capability assertion you make about your deployment; only set it for models you've confirmed support the 1M-token window: ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` `"claude-sonnet-5[1m]"` is shorthand for the same entry. When an ID is listed both bare and with `[1m]` (as a gateway lists it), the picker shows one model with a 1M variant; put `labelOverride` on the bare entry (a label on the `[1m]` spelling is ignored there); tier-tagged entries are not folded. `prefer1m: true` (no effect without `supports1m`) makes the 1M variant the default picker selection when this entry is the default model; users can still switch, and an explicit pick is kept. Under dynamic discovery (no explicit list), set `modelPrefer1mContext` instead. **Display label** (`labelOverride`) is for IDs the picker can't derive a friendly name from (Bedrock ARNs, gateway routing aliases). Display-only; `name` is still what the app sends: ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "arn:aws:bedrock:us-east-1:123:application-inference-profile/abc", "labelOverride": "Claude Opus (Prod)"}] ``` **Tier mapping** (`anthropicFamilyTier`) tells the app which Claude tier (`haiku`/`sonnet`/`opus`/`fable`/`mythos`) an entry stands in for, so bare tier aliases (e.g. in Code sessions) resolve to your model. `isFamilyDefault: true` picks the winner when several entries share a tier: ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ``` | Field | Type | Default | Description | | --------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | — | Model ID exactly as the provider expects it. The first entry is the default model. | | `labelOverride` | `string` | — | Shown in the model picker. Leave blank to auto-format from the ID. | | `supports1m` | `boolean` | — | Adds a 1M-context variant of this model to the picker. Set only if the deployment accepts 1M-token context for it. | | `prefer1m` | `boolean` | — | Make the 1M-context variant the default picker selection when this model is the default (first) entry. Users can still choose the standard variant. | | `anthropicFamilyTier` | `enum` | — | Which Claude tier this model stands in for. Pins the bare alias (e.g. ‘opus’) and, for opus/fable, the refusal fallback. One of: `sonnet`, `opus`, `haiku`, `fable`, `mythos`. | | `isFamilyDefault` | `boolean` | — | When several models share a tier alias, marks this one as the model the alias resolves to. Otherwise the first listed wins. | | `maxEffort` | `enum` | — | Highest effort level offered for this model; higher levels are hidden and never requested by Claude Desktop. An unrecognized value caps the model at low. One of: `low`, `medium`, `high`, `xhigh`, `max`. | The effort level the default model (the first `inferenceModels` entry, or the first model your endpoint returns under discovery) starts at in Chat, Cowork and Code, in place of Anthropic's recommended level for that model: one of `low`, `medium`, `high`, `xhigh`, `max`. It is a starting point, not a lock: a person's own effort choice for that model still applies unless `alwaysStartWithDefaultModel` is on, and other models keep their recommended level. A level the model doesn't offer falls to the nearest level it offers below it (its lowest level when none is lower), and it never exceeds that model's `maxEffort`. In Code sessions a `CLAUDE_CODE_EFFORT_LEVEL` environment variable or an `effortLevel` in Claude Code's own settings still takes precedence, as it does over any picker default. When `true`, each new conversation or task in Chat, Cowork and Code starts on the default model (the first `inferenceModels` entry), and the model and effort choices a person makes are no longer saved as their defaults. When unset or `false`, a person's last model and effort choice is remembered per tab, as before. Choices saved before the setting was turned on are kept and apply again if it is turned off. Off unless set: the Usage page shows token counts only, since the app cannot know your negotiated provider rates. `true` turns on a USD estimate priced at Anthropic's published list price and is the only switch that does: `inferenceModelPricingMultiplier` and `inferenceModelPricing` refine the estimate while this is on and are ignored otherwise; turning this off hides them in the config editors without clearing them. Claude Code performs the calculation, so the same figures appear in its own cost reporting for Code sessions. Model IDs Claude Code cannot map to a Claude model (an opaque gateway alias, an inference-profile ARN it cannot resolve) are left out of the estimate until `inferenceModelPricing` gives them a rate. A machine-level Claude Code managed `modelPricing` (MDM / managed-settings.json / server-managed) takes precedence over all three keys. Mirrors Claude Code's managed `modelPricing.multiplier`: a number in (0, 1] applied to every computed cost, whether the model was priced at Anthropic list price or by an `inferenceModelPricing` row; use it for a flat contracted discount. Applies only while `inferenceModelPricingEnabled` is `true`; on its own it does not turn the estimate on. Ignored when a machine-level Claude Code managed `modelPricing` is present. Each row replaces Anthropic list price for one model in the Usage page's estimate, in USD per million tokens (`inputPerMtok`, `outputPerMtok`, `cacheReadPerMtok`, `cacheWritePerMtok`, all four required; `cacheWritePerMtok` prices both 5-minute and 1-hour cache writes); rows apply only while `inferenceModelPricingEnabled` is `true` and do not turn the estimate on by themselves. Mirrors Claude Code's managed `modelPricing.overrides`, and `name` is matched the same way: a built-in Claude model ID (e.g. `claude-sonnet-4-6`, or its Bedrock, Vertex, or Foundry ID) covers every dated and provider spelling of that model; any other value (a gateway alias, an inference-profile ARN) matches that exact ID only (case-insensitive) and wins over a built-in row. An ID Claude Code cannot map to a Claude model at all gets no estimate until a row here prices it. `inferenceModelPricingMultiplier` still applies on top of a row. ```json theme={null} theme={null} theme={null} theme={null} theme={null} {"inferenceModelPricingEnabled": true, "inferenceModelPricingMultiplier": 0.9, "inferenceModelPricing": [{"name": "claude-sonnet-4-6", "inputPerMtok": 2.4, "outputPerMtok": 12, "cacheReadPerMtok": 0.24, "cacheWritePerMtok": 3}]} ``` These are estimates for visibility, not an invoice; your provider bills at its own rates. A machine-level Claude Code managed `modelPricing` (MDM / managed-settings.json / server-managed) takes precedence over this table. | Field | Type | Default | Description | | ------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | — | A model ID from the list above, or any other ID or alias your provider serves. A built-in Claude ID also covers its dated and provider forms. | | `inputPerMtok` | `number` | — | USD per million input tokens. | | `outputPerMtok` | `number` | — | USD per million output tokens. | | `cacheReadPerMtok` | `number` | — | USD per million prompt-cache read tokens. | | `cacheWritePerMtok` | `number` | — | USD per million prompt-cache write tokens (5-minute and 1-hour writes alike). | When on (the default), the app reads the model catalog Anthropic publishes for Claude Code (a signed document fetched from `downloads.claude.ai`, or from `modelCatalogUrl` when that is set, and verified against a key built into the app; a copy bundled with the app is used until one has been fetched, or when the host is unreachable) and uses it to fill in each picker entry's display name, description, and thinking/effort options in the Chat, Cowork, and Code tabs. It never changes which models are offered, their order, or the default model (the first `inferenceModels` entry): those, 1M-context variants, and `labelOverride` still come from `inferenceModels` / discovery, and a model the catalog does not list keeps the built-in label. Set `modelCatalogEnabled: false` to keep the built-in labels and make no catalog fetch. Applies to deployments configured on the device or by a bootstrap server; an install managed from the Claude admin console takes its model names and options from the console's settings and never fetches the catalog. When set, the app fetches the catalog document and its signature file (the same URL with `.raw-sig.json` appended to the path) from this URL instead of `https://downloads.claude.ai/model-catalog/v1/catalog.json`, for a gateway or mirror inside your network serving Anthropic's two published files byte-for-byte. The document is still verified against the key built into the app, so an edited or re-signed copy is refused and the app keeps its last verified copy (or the bundled one); there is no key to configure. `https://` is required (`http://` only to a loopback address, and only when set on the device itself; a bootstrap server may not deliver a loopback or non-`https://` value); the server must answer the GET directly (redirects are not followed) and may honor `If-None-Match` with `304`, and must serve a document at least as new as the one the install last accepted (or the bundled seed) — an older one is refused and re-fetched on the retry interval until the mirror catches up. Ignored when `modelCatalogEnabled` is `false`, and on an install managed from the Claude admin console (which never fetches the catalog). A value that is not a valid URL, names a link-local or cloud-metadata host (e.g. `169.254.169.254`, `metadata.google.internal`), or is a loopback / non-`https://` value a bootstrap server delivers, turns the catalog fetch off (no fallback to `downloads.claude.ai`); the last fetched or bundled copy keeps labelling the pickers. On an install configured for a bootstrap server, the default location is not fetched until the server's configuration applies after sign-in, so a device does not poll `downloads.claude.ai` while the server may yet name a mirror; a mirror URL set on the device, cached earlier, or served in a pre-sign-in subset still fetches. Diagnostics report the location only as `hosted`, `custom`, `invalid` or `pending`; the value itself is treated like `bootstrapUrl`: host name only in telemetry, printed in full in the diagnostics bundle. ### Vertex | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------------- | -------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | GCP project ID
`inferenceVertexProjectId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Google Cloud project ID for Vertex AI inference. | | GCP region
`inferenceVertexRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | GCP region where your Vertex AI Claude models are deployed. | | Vertex AI base URL
`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | PSC endpoint, if using one. | | Vertex OAuth client ID
`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. | | Vertex OAuth client secret
`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config. | | Vertex OAuth scopes
`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. | | Vertex OAuth login hint
`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap
Added in 1.12603.0 | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. | | Workforce Identity audience
`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap
Added in 1.10628.0 | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. | | Workforce Identity billing project
`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap
Added in 1.10628.0 | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. | | Workforce Identity sign-in flow
`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | | Workforce Identity IdP (OIDC)
`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap
Added in 1.10628.0 | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. | | GCP credentials file path
`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. | * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. The GCP STS token-exchange step is unchanged in either flow; only how the Entra id\_token is acquired differs. | Field | Type | Default | Description | | --------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `scopes` | `string` | — | Space-separated scopes. Defaults to openid profile email offline\_access. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `omitOfflineAccess` | `boolean` | — | Only enable if your IdP rejects the offline\_access scope on this client. Without it the app prompts for sign-in each time the token expires. | | `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. | ## Workspace ### Authentication | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------- | --------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | Disable Claude.ai sign-in
`disableDeploymentModeChooser` | `boolean` | MDM + Bootstrap
Added in 1.3834.0 | `false` | Users see only this provider at the login screen. The option to sign in to Claude.ai is hidden. Defaults to `false`. | | Disable claude:// deep-link handling
`disableDeepLinkRegistration` | `boolean` | MDM + Bootstrap
Added in 1.6889.0 | `false` | Stop external apps and websites from opening Claude Desktop via claude:// links. Defaults to `false`. | ### Chat surface | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Allow Chat
`chatTabEnabled` | `boolean` | MDM + Bootstrap
Added in 1.13576.0 | — | Enable Chat. Quick questions and drafting. | | Advanced file analysis
`chatAdvancedFileAnalysisEnabled` | `boolean` | MDM + Bootstrap
Added in 1.14271.0 | — | Allow Claude to run code in a local sandbox to analyze attached files it can’t read natively — like Excel and PowerPoint. Off by default. | Also enables inline data analysis. The sandbox can only read files attached to the conversation and has no network access. ### Code surface | Setting | Type | Availability | Default | Description | | ------------------------------------------------------- | ---------- | ---------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allow Code
`isClaudeCodeForDesktopEnabled` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `true` | Enable Code. Claude writes and runs code. Defaults to `true`. | | SSH host allowlist
`sshHostAllowlist` | `string[]` | MDM + Bootstrap · Beta
Added in 1.40609.0 | — | SSH hosts users may connect to for Code sessions. Empty or unset: off unless the device’s Claude Code managed-settings allowlist applies. \* allows any host. | | SSH client program
`sshClientPath` | `string` | MDM + Bootstrap · Beta
Added in 1.46388.1 | — | Absolute path to the OpenSSH ssh program the app runs for SSH sessions. Unset: the first ssh on the user’s PATH. | | SSH connection engine
`sshTransport` | `enum` | MDM + Bootstrap · Beta
Added in 1.52386.0 | — | Which SSH engine carries Code sessions: the OpenSSH ssh program on the device, or the app’s built-in SSH library. Unset or auto: the build’s default. One of: `auto`, `system-openssh`, `builtin`. | When off, the SSH option is hidden and any connection attempt is refused. Entries are exact hostnames (`build01.corp.example.com`) or `*.` wildcards (`*.corp.example.com` matches the apex and subdomains at any depth); matching is case-insensitive and ignores a `user@` prefix. Both the host the user entered and the `HostName` their `~/.ssh/config` resolves it to must match, so an alias cannot reach a host outside the list. `ProxyCommand` is permitted when the resolved host matches (this key governs which hosts the app offers, not network egress); `ProxyJump` is permitted likewise on the system-OpenSSH engine (the default on macOS and Linux; see `sshTransport`) and refused, with a message suggesting `ProxyCommand`, by the built-in SSH library. This is opt-in because a remote session runs Claude Code on the SSH host and the app forwards the session's inference credential to it, plus your OTLP collector endpoint and auth headers when `otlpEndpoint` is set. List only hosts you trust with those. Token-based credentials are forwarded; file-based kinds (Bedrock IAM Identity Center sign-in or AWS profile, Vertex Google sign-in or a credentials file) are refused at session start. If this key is unset, an `sshHostAllowlist` in Claude Code's own managed-settings file on the device still applies; when both are set, this key wins where the app's configuration is admin-managed (MDM, the admin console, or a device-managed bootstrap URL) and otherwise applies only while that file sets none. `allowedWorkspaceFolders` still applies on the remote host. Pins which OpenSSH client the app runs wherever it starts `ssh`: evaluating the user's SSH configuration (`ssh -G`), making the SSH connection and its channels, and the Code tab's terminal. `ssh-keygen` and `ssh-add` are taken from the same directory when they exist there, otherwise from PATH. The program must be OpenSSH 7.6 or newer (on Windows, Win32-OpenSSH 9.4 or newer to carry the connection); on macOS and Linux a wrapper script that ends in one is accepted, on Windows it must be a native `.exe` (not a .cmd, .bat or .ps1 script). When this key is set and the program is missing, cannot be run, or is too old, SSH sessions fail with an error telling the user to ask their IT administrator (the configured path is in its details) — the app never falls back to another ssh. The connection itself runs through this program on the system-OpenSSH engine, which the SSH connection engine setting's `system-openssh` value selects on every platform, including Windows; when the app's built-in SSH library makes the connection instead, this key still governs configuration evaluation (`ssh -G`), host-key lookups (`ssh-keygen`) and the terminal. `system-openssh`: the app makes every SSH connection by running an OpenSSH `ssh` program — the one `sshClientPath` names, otherwise the first `ssh` on the user's PATH (on Windows, a Win32-OpenSSH `ssh.exe`: the PATH one, else the in-box or Microsoft-installed client) — so the organization's own OpenSSH build, with its Kerberos/GSSAPI, certificate and `ssh_config` support, is what authenticates. The program must be OpenSSH 7.6 or newer (Windows: Win32-OpenSSH 9.4 or newer). When `sshClientPath` is set and that program cannot be used, sessions fail with an error telling the user to ask their IT administrator rather than falling back; when it is unset and Windows has no usable client, the built-in library is used. `builtin`: the app's built-in SSH library makes the connection, whatever the build's default. `auto` or unset: the build's default engine. An explicit value applies to new connections (sessions already connected keep their engine) and overrides the build's default in both directions, including any remote switch-off Anthropic ships for the OpenSSH engine — so with `system-openssh` set, switching back is done here, by setting `builtin`. ### Cowork surface | Setting | Type | Availability | Default | Description | | -------------------------------------------- | --------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | Allow Cowork
`coworkTabEnabled` | `boolean` | MDM + Bootstrap
Added in 1.9659.0 | `true` | Enable Cowork. Claude works on longer tasks like research, analysis, and documents. Defaults to `true`. | ### Workspace | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------------------ | ---------- | --------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allow user-added plugin marketplaces
`userPluginMarketplacesEnabled` | `boolean` | MDM + Bootstrap
Added in 1.37937.0 | — | Allow users to add plugin marketplaces themselves. When off, the add-marketplace surfaces are hidden and in-app adds are refused. | | Allow user-added plugins
`userPluginUploadsEnabled` | `boolean` | MDM + Bootstrap
Added in 1.37937.0 | — | Allow users to add their own plugins. When off, every in-app option for adding one is hidden and uploads that still reach the app are refused. | | Disabled built-in tools
`disabledBuiltinTools` | `string[]` | MDM + Bootstrap
Added in 1.2581.0 | — | Built-in tools, or argument-scoped permission rules such as Read(\*\*/.env), denied in Cowork and Code. | | Disable bundled skills and workflows
`disableBundledSkills` | `boolean` | MDM + Bootstrap
Added in 1.15962.0 | — | Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available. | | Allow user-created skills
`skillCreationEnabled` | `boolean` | MDM + Bootstrap
Added in 1.25927.0 | — | Allow users to create and upload their own skills. When off, the creation and upload surfaces are hidden and the agent’s skill-creation tools are disabled. | | Allow scheduled tasks
`scheduledTasksEnabled` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | Allow scheduled tasks in Cowork and Code. When off, the Scheduled page is hidden, existing tasks stop running, and Claude cannot create new ones. | | Built-in tool policy
`builtinToolPolicy` | `object` | MDM + Bootstrap
Added in 1.8089.0 | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. Deprecated: `builtinToolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be read as "ask" (approval on every call), like any unrecognized value. | | Allow Auto mode
`autoModeEnabled` | `boolean` | MDM + Bootstrap
Added in 1.10628.0 | `false` | Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`. | | Disable bypass permissions mode
`disableBypassPermissionsMode` | `boolean` | MDM + Bootstrap
Added in 1.46388.1 | — | Remove the bypass permissions mode from Code sessions and Cowork tasks, so Claude always follows the permission policy. Off by default. | | Enable tool search
`toolSearchEnabled` | `boolean` | MDM + Bootstrap
Added in 1.21459.0 | `false` | Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`. | | Skip WebFetch domain check
`skipWebFetchPreflight` | `boolean` | MDM + Bootstrap
Added in 1.37937.0 | — | Skip Claude Code’s WebFetch domain lookup against api.anthropic.com in Code sessions. Off by default; turn on when that host is blocked. | | Allowed workspace folders
`allowedWorkspaceFolders` | `object[]` | MDM + Bootstrap
Added in 1.2581.0 | — | Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access. | | Block reads outside working directories
`blockReadsOutsideWorkingDirectories` | `boolean` | MDM + Bootstrap
Added in 1.46388.1 | — | Keep Claude from reading files outside a Code session’s working directories. File tools refuse such reads; sandboxed shell commands lose the home directory. | | Allowed egress hosts
`coworkEgressAllowedHosts` | `string[]` | MDM + Bootstrap
Added in 1.2581.0 | — | Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements. | | Require full VM sandbox
`requireCoworkFullVmSandbox` | `boolean` | MDM + Bootstrap · Deprecated
Added in 1.2581.0 | `false` | Runs tools inside an isolated VM instead of the host. Stronger isolation; slower file access and no host-process tools. Defaults to `false`. | | Organization instructions
`organizationInstructions` | `string` | MDM + Bootstrap
Added in 1.37937.0 | — | Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters. | When on (default), users can add plugin marketplaces from the plugin browser. Set to `false` to block user marketplace adds: the add-marketplace surfaces are hidden, and the app refuses adds that still reach it (deep links, stale UI). This is a feature-availability control enforced in the app, not a data boundary: marketplaces already registered on the user's machine (or registered outside the app, for example by the Claude Code CLI or by editing Claude Code's plugin files) are not removed or blocked by this key. Marketplaces provisioned by your organization (`allowedPluginMarketplaces`) are unaffected. This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set `disableDeploymentModeChooser` so the app stays in third-party mode. When on (default), users can upload plugin files and create plugins with Claude. Set to `false` to stop users adding plugins of their own: every in-app option for doing so is hidden, and the app refuses uploads that still reach it. This is a feature-availability control enforced in the app, not a data boundary: plugins already installed (or placed on disk outside the app) are not removed or blocked by this key. Plugins from organization-provisioned marketplaces and the organization plugins directory are unaffected. This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set `disableDeploymentModeChooser` so the app stays in third-party mode. Each entry is a Claude Code tool name (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`, `WebFetch`, `WebSearch`, `Task`, `TodoWrite`, `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`, `TaskStop`, `Skill`, `REPL`, `JavaScript`, `AskUserQuestion`, `ToolSearch`, `SendUserMessage`) or an argument-scoped [permission rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax) such as `Bash(curl *)` or `Edit(**/*.env)`. A bare name covers every call; a scoped rule covers matching calls in every permission mode, including Auto and bypass. Scopes are matched for `Bash(…)` (a command pattern) and for file paths written as `Read(…)` (covers `Read`, `Grep`, `Glob`) or `Edit(…)` (covers `Edit`, `Write`, `NotebookEdit`); other tools take `Tool(:)`. `WebSearch` and `WebFetch` are bare-name only: per-host web access is `coworkEgressAllowedHosts`. Scoped `Bash(…)` rules apply in Code sessions and in VM-sandboxed Cowork sessions (`requireCoworkFullVmSandbox`); Cowork's own sandboxed shell honors bare names only. Anchor file patterns with `**/` (`Read(**/secrets/**)`), because in the VM sandbox a host absolute path does not match. Scoped rules need a build that supports them across the whole fleet (`disableAutoUpdates` pins builds): an older build passes a scoped entry to Claude Code unchecked. An entry whose pattern contains `)` followed by a space or comma is enforced only through Claude Code's managed-settings channel, so another Claude Code [managed-settings source](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) replaces it unless that source sets `parentSettingsBehavior` to `"merge"`; every other entry is enforced either way. An unusable entry (a lowercase tool name, an unbalanced parenthesis, a scoped `WebSearch(…)` or `WebFetch(…)`) is kept, because the deny list is served exactly as written, and raises a configuration warning. When on (default), users can create new skills and upload skill files in the app. Set to `false` to block user skill creation: the skill-creation and upload surfaces are hidden (the `skill_creation` feature is served as blocked by the organization), and the agent's skill-creation tools (saving skills from a conversation, skill proposals) are not offered in sessions — the same effect as turning off the **User-created skills** organization setting available to claude.ai enterprise admins. This is a feature-availability control enforced in the app's UI, not a data boundary: skills are files on the user's machine, and files already present there (or placed there outside the app) are not removed or blocked by this key. Skills themselves remain usable; organization-distributed plugins and bundled skills are unaffected (to disable bundled skills, use `disableBundledSkills`). When on (default), users can schedule Cowork tasks and Code sessions to run later or on a recurring schedule, and Claude can create such schedules when asked. Set to `false` to turn scheduled tasks off for every user. The Scheduled section in Cowork and the routines list in the Code tab are hidden, together with every other place a schedule can be created. Tasks that already exist on a device no longer run; they are kept, not deleted, and run again once the key is removed or set to `true`. Claude is not offered the tools that create, change or run these tasks, and sessions start without Claude Code's own in-session scheduling tools (the `/loop` command, its cron tools and its wake-up timer). It does not remove task files already on the user's machine. A change takes effect at the next app launch. Keys use the same tool names and argument-scoped rule syntax as **Disabled built-in tools** (`disabledBuiltinTools`), and scopes apply in the same sessions. Scoped **ask** rules reach sessions only through Claude Code's managed-settings channel, so another Claude Code managed-settings source replaces them unless it sets `parentSettingsBehavior` to `"merge"` (bare names hold either way). They need the same fleet-wide build support, and an older build drops a scoped **ask** entry as a configuration error (which also blocks WSL sessions on Windows until that client updates), so the tool runs unprompted. An **ask** entry, bare or scoped, also turns off the app's remembered “always allow” choices for that tool, so each prompted call is confirmed individually. In Code side chats, and in Cowork sessions that run tools on the host, **ask** on a file tool (`Read`, `Write`, `Edit`, `Glob`, `Grep`) blocks matching calls instead of prompting; Code sessions and VM-sandboxed Cowork sessions show the prompt. An unusable entry is dropped and recorded as a configuration error; a value other than `allow` or `ask` is treated as `ask` and reported. To remove a tool or deny a rule outright, use **Disabled built-in tools** instead. When enabled, users can select **Auto mode** (Code) / **Automatically approve** (Cowork). Claude runs a safety classifier on each action and only prompts for approval on actions it judges risky, instead of following the static per-tool policy. Requires a model that supports the safety classifier — which models qualify depends on the deployment's provider and the app version. Models without support show the option greyed out. `builtinToolPolicy` and this key may both be set; Auto mode is a user-selectable option alongside the default policy, not a replacement for it. In Code sessions, a separately deployed Claude Code [managed-settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) file that sets `disableAutoMode` to `"disable"` overrides this key and keeps Auto mode hidden. When set to `true`, sessions cannot run in bypass permissions mode: the app stops offering the mode in Code and Cowork, and a session that requests it anyway is downgraded. This is the `disableBypassPermissionsMode` setting from the `permissions` section of Claude Code's [managed settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings); a separately deployed Claude Code managed-settings file that sets it to `"disable"` also removes the mode, whichever source sets it. Unset (default): users the deployment otherwise allows can choose bypass permissions mode. When enabled, Cowork, Code, and Chat sessions place only tool names in context up front, and Claude fetches a tool's full schema the first time it needs it. Use this when many MCP tools are configured and their inlined schemas crowd out the context window. If your endpoint does not accept the request shape it then receives, requests fail with HTTP 400. * **Claude API, Vertex AI, Bedrock, or Bedrock Mantle with no custom base URL**: not needed. The app leaves Claude Code's experimental betas on there, as terminal Claude Code does, so tool search is on by default (on Vertex AI, for Claude 4.5 and newer models). To turn it off in Code, Cowork, and Chat, set `ENABLE_TOOL_SEARCH` to `false` in the `env` block of OS-level Claude Code managed settings (with `parentSettingsBehavior: "merge"`). Earlier app versions treat these like the last case. * **Gateway provider, app versions bundling Claude Code 2.1.247 or later**: requests add only the tool-search shape (the `tool-search-tool-2025-10-19` `anthropic-beta` value, deferred tool loading, `tool_reference` content blocks); every other experimental Claude Code beta stays suppressed. OS-level Claude Code managed settings that keep that suppression or turn `ENABLE_TOOL_SEARCH` off still win; set `ENABLE_TOOL_SEARCH` to `force` there instead (with `parentSettingsBehavior: "merge"`). Sessions in Claude Code's own gateway mode (`CLAUDE_CODE_USE_GATEWAY`) get its gateway-safe tool-search shape regardless. * **Foundry, a custom base URL, and earlier app versions**: the app suppresses Claude Code's experimental betas for the session and the key lifts that, so requests carry the tool-search shape together with Claude Code's other experimental betas for that provider. On Vertex with app versions bundling Claude Code older than 2.1.221, leave this unset while any model older than Claude 4.5 is in use; those engines send the header regardless of model and Vertex's pre-4.5 stacks reject it. Before fetching a page, Claude Code's WebFetch tool asks `api.anthropic.com` whether the domain is on Anthropic's content blocklist, and refuses the fetch if that lookup cannot complete. Third-party deployments route inference elsewhere and often block `api.anthropic.com` at the firewall; with the lookup on, every WebFetch in Code sessions then fails with "Unable to verify if domain … is safe to fetch", and where the host is reachable, every fetched hostname is sent to Anthropic. (Cowork sessions fetch through the app's own allowlisted fetch and never run this lookup.) Off (default): the lookup runs as it does today, so `api.anthropic.com` must be reachable from users' machines for Code-session WebFetch to work (listed under Egress Requirements). Set to `true` when users' machines cannot reach `api.anthropic.com` (corporate firewall, government network) or you do not want fetched hostnames sent there: Code sessions then fetch without the lookup and never contact that host for it. This is the same `skipWebFetchPreflight` setting Claude Code reads from its own [managed-settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) file; the app passes it to every session it starts. To restrict which domains Claude may fetch, use `coworkEgressAllowedHosts` or `builtinToolPolicy` instead. Paths can reference `~` and these environment variables, expanded per user: `%OneDrive%`, `%OneDriveCommercial%`, `%OneDriveConsumer%`, `%APPDATA%`, `%LOCALAPPDATA%`, `%USERNAME%`, `%XDG_DOCUMENTS_DIR%`. The set is fixed; an entry that references any other `%VAR%`, or one that is unset on the device, is ignored. Each folder is interpreted on the machine the session runs on. For a Code session on an SSH host, `~` means the remote user's home, an entry that references a `%VAR%` is ignored there (environment variables belong to the machine that defines them), and the session's working directory must fall inside one of the folders as they exist on that host. One list serves every machine: `["/Users", "~"]` governs `/Users` on a managed Mac and the signed-in user's home on a Linux host. A folder that names nothing real on a given machine simply allows nothing there. | Field | Type | Default | Description | | ------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | `string` | — | Absolute folder path. May start with \~ or one of the listed %VAR% tokens, expanded per user. Subfolders are included. | | `isDefaultSelected` | `boolean` | — | Shows as a folder chip on the new-task page and skips the trust prompt. Users can remove it. | | `mode` | `enum` | — | Read-only folders can be viewed and searched but not modified in Cowork. In Code, applies to file tools only; Bash and SSH do not yet enforce read-only. One of: `rw`, `ro`. | When set to `true`, Code sessions refuse reads outside their working directories (the session folder plus any `allowedWorkspaceFolders`). The file tools (Read, Grep, Glob) refuse them in every permission mode; where Claude Code's sandbox runs (macOS, or Linux and SSH hosts with bubblewrap, once `allowedWorkspaceFolders` or an egress allowlist is also configured) shell commands cannot see the home directory and other user folders (`/Users`, `/home`, mounted volumes) and a read there is refused with no prompt; elsewhere (Windows, Linux without bubblewrap, or neither folders nor an egress allowlist configured) such shell reads prompt for approval. The app keeps the user's git configuration files (which may themselves embed credentials such as URL tokens; a symlinked one stays hidden), its own Claude Code installation, and the session's plugin and attachment folders readable (not on a Windows SSH host, where plugin files and attachments stay out of the file tools' reach under the block). An allowed folder that is or contains the home directory leaves it readable. Users can re-open folders (even their whole home) in their own Claude Code settings with `sandbox.filesystem.allowRead` or `permissions.additionalDirectories`; settings files tracked in a git repository cannot. The key travels on Claude Code's managed-settings channel: another Claude Code managed-settings source replaces it unless that source sets `parentSettingsBehavior` to `"merge"`, and one that sets `sandbox.filesystem.allowManagedReadPathsOnly` reduces it to approval prompts. This is `permissions.blockReadsOutsideWorkingDirectories` in Claude Code's [managed settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings). Unset (default): nothing changes. Applies to **both** Cowork and Code, and only to **tool calls**. In Cowork it governs the sandbox's web fetch, shell commands, and package installs; in Code sessions it is [translated into Claude Code's network sandbox allowlist](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy), where a separately deployed Claude Code managed-settings file takes precedence by default. It does **not** cover Web Search (which runs at your inference provider), inference, or MCP traffic. When unset, only the inference endpoint is reachable from the sandbox, so the agent's package installs and web fetches fail with a 403. Entries are exact hostnames (`api.github.com`), wildcards (`*.corp.com` matches subdomains at any depth, not `corp.com` itself), or `*` to allow all. IP addresses match only when listed exactly. `localhost` and private-network addresses are always blocked for web fetch; shell commands and package installs run in a network sandbox that reaches only the listed hosts plus your inference provider. With `*`, that sandbox is disabled and web fetch still blocks private addresses. Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting it to that port. IPv6 literals are not supported. An invalid entry is dropped (with a warning in the app log) and the rest keep working; an unreadable value counts as an empty list. Ports are enforced for the Cowork sandbox's web fetch, shell, and package-install egress; plugin CLIs ignore port-scoped entries for now, and the Code translation treats them as the bare host. Deploy port-scoped entries only once your whole fleet is on a build that supports them (`disableAutoUpdates` pins builds): on an older build one such entry invalidates the sandbox's whole shell and package-install allowlist for the session. Listed hosts also need to be open on your network firewall. Free-text instructions from your organization that Claude Desktop appends, in a clearly delimited block, after its own system prompt in **Chat**, **Cowork**, and **Code** (every chat, task, and Code session, including the sub-agents they spawn): for example house style, data-handling rules, or topics to decline. The model is told these instructions come from the organization's administrator and take priority over a user's personal preferences. This is guidance the model follows, not an enforced control: like any system-prompt text it steers the model's behavior and is usually honored, but it does not guarantee an outcome and is not a substitute for the restriction keys (tool policy, egress allowlist, folder allowlist). The app's own system prompt is never replaced or shortened by this key; in Code sessions it is added after Claude Code's own prompt and any `CLAUDE.md` instructions still apply. Read from the app's loaded configuration when a session starts; a changed value generally takes effect for sessions started after the next app launch. Leading and trailing whitespace is trimmed; an empty string is treated as unset. Maximum 3,000 characters; a longer value is rejected (the key is ignored with a configuration error) rather than truncated. Line breaks are preserved when the value is delivered as JSON, a bootstrap response, a `.mobileconfig` profile, or a `.reg` file; the Group Policy (ADMX) and Intune text box for this setting is single-line. ## Connectors | Setting | Type | Availability | Default | Description | | --------------------------------------------------- | -------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude.ai data import
`claudeAiImport` | `object` | MDM + Bootstrap
Added in 1.10628.0 | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, when `enabled` is true. `automatic3pImport` is a separate switch. | | Field | Type | Default | Description | | -------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `boolean` | `false` | Lets users import a Claude.ai data export and earlier Claude sessions on this computer from Settings → Import. Doesn’t affect a provisioned sign-in import. | | `automatic3pImport` · Beta | `boolean` | `false` | Copy this computer’s earlier third-party sessions into the app once, in the background. Independent of `enabled`. | | `exportEnabled` | `boolean` | `false` | Lets users export this computer’s chats, Cowork tasks, and Code sessions as a zip another install can import. No effect unless `enabled` is true. | | `bannerBehavior` | `enum` | — | Prompt to import at the top of a new chat or task. `detect`: only when earlier Claude sessions are found on this computer. `show`: always. Hidden when unset. One of: `off`, `detect`, `show`. | ### Authentication | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------------- | ------ | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Microsoft 365 native sign-in broker
`microsoftAuthBroker` | `enum` | MDM + Bootstrap
Added in 1.19367.0 | `auto` | “disabled” forces browser-based Microsoft 365 sign-in; “required” fails sign-in when the OS broker is unavailable, so the refresh token stays broker-held. One of: `auto`, `disabled`, `required`. Defaults to `auto`. | `auto` (default): use the OS sign-in broker where available (WAM on Windows, the Company Portal SSO extension on macOS) and fall back to a browser sign-in otherwise. `disabled`: always use the browser sign-in. `required`: fail sign-in when the broker is unavailable rather than falling back to the browser, so the refresh token stays broker-held. Linux has no broker, so `required` is not supported there. Desktop builds older than the version that introduced `required` treat it as `disabled` (browser-only sign-in) — the opposite posture — so gate rollout on client version. ### Extensions | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------------------- | --------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allow desktop extensions
`isDesktopExtensionEnabled` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | .dxt and .mcpb installs. Defaults to `false`. Previously named `isDxtEnabled` (the old name is accepted until October 7, 2026). If it is still present after that, the old name will be reported as unreadable and the key will read as false: desktop extensions will be disabled until the name is updated. | | Require signed extensions
`isDesktopExtensionSignatureRequired` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Reject desktop extensions that are not signed by a trusted publisher. Defaults to `false`. Previously named `isDxtSignatureRequired` (the old name is accepted until October 7, 2026). If it is still present after that, the old name will be reported as unreadable and the key will read as true: only signed extensions will load until the name is updated. | 1P builds default to enabled at runtime unless this is explicitly set. In 3P, enabling this allows loading extensions; local install additionally requires an org policy backend. ### MCP | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------ | ---------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Managed MCP servers
`managedMcpServers` | `object[]` | MDM + Bootstrap
Added in 1.2581.0 | — | Org-pushed MCP servers: remote (HTTP/SSE) or local (stdio command). May embed bearer tokens. Deprecated: `managedMcpServers[].scopes` (accepted until October 7, 2026); use scope (one space-separated string, for example "Mail.Read Calendars.Read"). If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].toolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].transport: "builtin"` (accepted until October 7, 2026); no longer needed — safe to remove. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].authorityHost` (accepted until October 7, 2026); use azureCloud: "us-gov-high" for a GCC High tenant; otherwise nothing. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten — the Microsoft 365 connector will disappear rather than guess a cloud. Deprecated: `managedMcpServers[].source` (accepted until October 7, 2026); no longer needed — safe to remove. If it is still present after that, it will be treated as any unrecognised entry member — ignored by the desktop (the connector still loads; the app assigns each connector's provenance itself) and refused by a customer-run Apps Gateway serving the configuration. Deprecated: `managedMcpServers[].oauth as a number or string` (accepted until October 7, 2026); use true (automatic registration) or an oauth object. If it is still present after that, it will be treated as any wrong-typed member: the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].oauth.scopes (or oauth.scope as a list)` (accepted until October 7, 2026); use oauth.scope as one space-separated string, for example "read write". If it is still present after that, it will be treated as any wrong-typed member: the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[] entry without transport` (accepted until October 7, 2026); use transport: "http" (or "sse" / "stdio") on every entry that is not a built-in server. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. | | Allow persistent tool approvals
`mcpPersistentAlwaysAllowEnabled` | `boolean` | MDM + Bootstrap
Added in 1.24012.9 | `true` | Offer the persistent “Always allow” approval options for MCP tools. Disable to keep tool approvals per-call or session-scoped only. Defaults to `true`. | | Allow user-added MCP servers
`isLocalDevMcpEnabled` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `true` | Local stdio servers added via the Developer settings. Remote servers come from the managed list above or organization plugins. Defaults to `true`. | | MCP tool call timeout
`mcpToolTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.37937.0 | — | Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600. | For OAuth-authenticated entries, the app builds the redirect URI as `http://:/callback`; register that exact value with the OAuth provider. Tokens refresh automatically during a session. `toolPolicy` locks the per-tool approval state, keyed by tool name: `"blocked"` removes the tool from the session and labels it admin-blocked, `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow), `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked` and `ask` are forwarded as Claude Code permission rules; `allow` is not. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; anchored, and `*` is the only wildcard). When several wildcard keys match, the strictest applies (blocked > ask > allow). An exact-name key wins over matching wildcards, with two exceptions in the stricter direction: in Code sessions a wildcard `ask`, or a wildcard `blocked` other than the bare `"*"`, beats a less strict exact key (so `"*": "blocked"` plus exact `"allow"` entries still works as deny-by-default there); and in chat approval prompts and always-allow persistence a wildcard `ask` keeps every matching tool behind a per-call prompt even when a more permissive exact key matches, while direct tool invocations such as artifact or widget calls follow the exact key. For the bundled Microsoft 365 connector, the send tools (`outlook_send_mail`, `outlook_send_draft`, `outlook_forward_mail`, `outlook_create_event`, `outlook_update_event`, `teams_send_chat_message`, `teams_send_channel_message`, `teams_reply_channel_message`) cannot be loosened below `ask`; an `allow` setting resolves to `ask`. | Field | Type | Default | Description | | --------------------------------------- | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | — | Unique name for this server. Shown to users and used to key tool policy and sign-in state. | | `server` | `string` | — | Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields. One of: `microsoft365`, `websearch`, `github`. | | `tenantId` | `string` | — | Your organization’s Microsoft Entra directory (tenant) ID. | | `clientId` | `string` | — | OAuth app client ID for this built-in server. | | `azureCloud` | `enum` | — | Microsoft cloud for sign-in and Graph. Leave as global for commercial Microsoft 365; US Government clouds require your own app registration (Client ID). One of: `global`, `us-gov-high`, `us-gov-dod`. | | `continuousAccessEvaluation` | `enum` | `enabled` | Request CAE-capable Microsoft Graph tokens: long-lived (up to about 28 hours) but revocable within minutes. Set “disabled” to keep standard one-hour tokens. One of: `enabled`, `disabled`. | | `scope` | `string` | — | What the server may request at sign-in. If blank, Desktop’s default read set is used. | | `toolPolicy` | `object` | — | Lock the approval state for specific tools. Unlisted tools stay user-controlled. | | `headers` | `object` | — | Static headers sent on every request — routing and tenant headers only. No credentials here; use the headers helper script for tokens and rotating values. | | `headersHelper` | `string` | — | Script that prints the auth header as a JSON object to stdout. Runs before each request (cached for the TTL below). | | `headersHelperTtlSec` | `integer` | — | How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300. | | `headersHelperRefreshBufferSec` | `integer` | — | Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime. | | `provider` | `enum` | — | Runs search from the desktop, for inference providers without native web search. Supply the provider’s API key through the headers helper script below. One of: `brave`, `tavily`, `exa`, `custom`. | | `customUrl` | `string` | — | POST endpoint accepting \{q} JSON and returning a results\[] array. Only used when provider is Custom. | | `host` | `string` | — | Leave blank for github.com. For GitHub Enterprise Server, your instance’s base URL. | | `toolsets` | `string` | — | Comma-separated github-mcp-server toolsets to enable. If blank, the bundled server’s default toolsets are used. | | `readOnly` | `boolean` | — | Offer only read tools — the server registers no write tools at all. | | `transport` | `enum` | — | How the app connects: Streamable HTTP, legacy SSE, or a local command (stdio). policy-only connects to nothing; it only sets a plugin server’s tool policy. One of: `http`, `sse`, `stdio`, `policy-only`. | | `url` | `string` | — | HTTPS endpoint of the remote MCP server. | | `oauth` | `object` | — | OAuth for a remote server: true to auto-register a client, a pre-registered client ID with tenant and scope, or mode “hosted” for an Anthropic-signed identity. | | `oauth.clientId` | `string` | — | OAuth client ID from your IdP app registration. Leave unset to auto-register (dynamic client registration) and only narrow scopes. | | `oauth.clientSecret` | `string` | — | Only for IdPs whose token endpoint requires a client secret (e.g. Box). Leave blank for PKCE-only public clients. | | `oauth.clientSecretHelper` | `string` | — | Executable that prints the client secret on stdout as a JSON object with a single clientSecret key; any other output is rejected. Overrides the inline value. | | `oauth.authorizationServer` | `string[]` | — | Issuer URLs the OAuth sign-in may use, as a JSON array. Pre-filled by presets; ask your IdP admin if unsure. | | `oauth.authorizationUrl` | `string` | — | Only for IdPs that don’t serve a .well-known discovery document. Set together with Token URL; requires Client ID. | | `oauth.tokenUrl` | `string` | — | Only for IdPs that don’t serve a .well-known discovery document. Set together with Authorization URL; requires Client ID. | | `oauth.tenantId` | `string` | — | Required for single-tenant Entra apps. Leave blank for multi-tenant or non-Microsoft IdPs. | | `oauth.authFlow` | `enum` | — | How Entra sign-in runs for this server: the system browser (default) or the OS identity broker. One of: `browser`, `broker`. | | `oauth.scope` | `string` | — | Space-separated scopes sent on the authorize request. Leave unset to use the scopes the server advertises. Required when Tenant ID is set. | | `oauth.appendOfflineAccess` | `boolean` | — | Adds offline\_access to the authorize request so the IdP returns a refresh token for silent renewal. | | `oauth.callbackHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `oauth.callbackPort` | `integer` | — | Only set if your IdP requires an exact-match redirect port. Entra accepts any. | | `oauth.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. | | `command` | `string` | — | Absolute path to the server executable, run on the user’s machine. | | `args` | `string[]` | — | Arguments passed to the command, one per entry. | | `env` | `object` | — | Environment variables set for the command. | | `envHelper` | `string` | — | Script that prints environment variables as a JSON object to stdout. Runs when the local server starts (cached for the TTL below). | | `envHelperTtlSec` | `integer` | `300` | Maximum age of a cached helper result, in seconds (default 300). Applies when the server starts or restarts. | | `startupTimeoutSec` | `integer` | `120` | Maximum wait in seconds for the server to start and list its tools. | When enabled (the default), approval prompts for tools without a `toolPolicy` entry offer a persistent grant — **Always allow**, or **Allow for all tasks** for tools that can modify data — the Tool permissions picker in Connector settings lets users pre-approve tools, and those grants persist across sessions with no expiry. When disabled, the persistent options are hidden from approval prompts and from the Connector settings picker, previously stored persistent grants stop being honored, and scheduled-task runs no longer record or replay cross-run tool approvals. Session-scoped approvals are unchanged: users can still approve each call, and tools that can modify data keep the session-scoped **Allow for this task** option. A per-tool `toolPolicy` entry on `managedMcpServers` always takes precedence over this key: `blocked`, `ask`, and `allow` behave exactly as documented there whether this key is enabled or not. This key governs the chat and Cowork surfaces. Code sessions use a separate permission path this key does not cover — govern Code tool approvals with per-tool `toolPolicy` entries, whose `blocked` and `ask` values are forwarded there. Sets the per-call timeout the agent applies to every MCP tool call; a call that runs longer fails with a timeout error the model can see. Cowork and chat sessions default to 180 seconds. Code sessions have no desktop-imposed MCP tool timeout today, so setting this key introduces one there as well. The desktop's own request deadlines toward MCP servers — the managed servers above and, where `isLocalDevMcpEnabled` permits them, user-added local servers — follow this value so they never cut a call short first; while the key is unset, calls to user-added local servers are additionally limited to 60 seconds by the desktop. Values outside 60–3600 are rejected at parse time (the error is listed in the diagnostics report) and the defaults apply. The timeout is global (there is no per-server or per-tool form), so size it for the slowest tool you need to complete: long-running tools on one server extend the window during which a stuck call on any server holds its turn. Cowork's built-in shell tool runs under the same cap: a single command's `timeout_ms` (itself limited to 600 seconds) cannot exceed this value. ## Telemetry & updates | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------ | --------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Organization UUID
`deploymentOrganizationUuid` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | A UUID you generate. Tags telemetry so Anthropic support can locate your fleet’s events, and namespaces each user’s local data. Not used for auth. | | Block essential telemetry
`disableEssentialTelemetry` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Crash and performance reports to Anthropic. Defaults to `false`. | | Block nonessential telemetry
`disableNonessentialTelemetry` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Product-usage analytics and diagnostic-report uploads. No message content. Defaults to `false`. | | Block nonessential services
`disableNonessentialServices` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Connector favicons and the artifact-preview and MCP Apps widget iframe origins. Artifacts will not render. Defaults to `false`. | If unset, a shared placeholder UUID is used: telemetry can’t be distinguished from other unconfigured deployments, and local data is stored under the placeholder. **Changing this value orphans data** stored under the previous value (sessions, skills, plugins). "Essential" means the signals Anthropic needs to keep your deployment working: **crash stacks**, **startup failure reasons**, and **version/OS metadata**. No prompts, completions, file contents, or identifiers beyond a random install ID. **What you lose when this is on:** when a Claude Desktop build hits a bug that only reproduces on your OS version or locale, Anthropic can't see it unless a user manually reports. Fixes ship slower. **Why this is discouraged, not blocked:** some air-gapped environments require zero outbound telemetry as a matter of policy. The switch exists for them. If you don't have that constraint, leave it off. "Nonessential" covers two things: **product-usage analytics** (which features get used, navigation patterns; no prompts or completions) and the **Send** action in Help → Generate Diagnostic Report. Turning this on stops both. Destinations are listed under Egress Requirements → Nonessential telemetry. "Nonessential services" covers three outbound fetches the app runs without: **connector favicons** (the icon proxy), the **artifact-preview** iframe origin, and the **MCP Apps widget** iframe origin (`*.claudemcpcontent.com`). Turning this on blocks all three. **What you lose when this is on:** connectors show without icons, artifacts do not render in conversations, and connectors that return MCP Apps show the text tool result instead of the widget. Destinations are listed under Egress Requirements → Nonessential services. ### Auto update | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Block auto-updates
`disableAutoUpdates` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Stop Claude Desktop from fetching updates entirely (no time limit). You’ll need to push new versions yourself. Defaults to `false`. | | Auto-update enforcement window
`autoUpdaterEnforcementHours` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | — | Hours before a downloaded update force-installs. Only applies when auto-updates are enabled. Blank = 72-hour default. Range: 1–72. | | Check for updates on releases.claude.com
`updateViaUpdatesHost` | `boolean` | MDM + Bootstrap
Added in 1.26832.0 | `false` | Read the update feed from releases.claude.com so api.anthropic.com can stay blocked. Defaults to `false`. | Has no effect when `disableAutoUpdates` is in place at launch: the updater never starts, so nothing is downloaded and this timer never arms. If the policy reaches an already-running app after an update has downloaded, that one staged update still installs on this timer; no further updates are fetched. Leaving it blank uses the 72-hour default *and* then waits for the machine to be idle (10+ minutes without input) before restarting; setting any explicit value (including 72) restarts once the window elapses regardless of user activity. In both cases the restart holds off while Claude is mid-task. By default the app asks `api.anthropic.com` which version to install. That host also serves the model APIs, so organizations that block un-approved LLM endpoints at the network edge end up blocking updates too. Turn this on to read the same feed from `releases.claude.com`, a hostname that carries no model API. `api.anthropic.com` can then stay blocked without breaking auto-update. Rollout behavior is unchanged; the installer download still comes from `downloads.claude.ai` as before. ### Configuration updates | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Configuration relaunch window
`relaunchEnforcementHours` | `integer` | MDM + Bootstrap
Added in 1.40609.0 | `24` | Hours a user may keep working on the old configuration after a managed-configuration change is detected. 0 = restart required at once. Blank = 24 hours. Defaults to `24`. Range: 0–336. | | Configuration re-check interval
`configRecheckIntervalMinutes` | `integer` | MDM + Bootstrap
Added in 1.46388.1 | `10` | Minutes between the running app’s checks for a changed managed configuration. Blank = 10 minutes. Defaults to `10`. Range: 2–30. | Set it via MDM (plist, registry, or file) or serve it from your configuration endpoint (remote bootstrap configuration). When the running app observes a managed-configuration change it cannot apply without restarting, it shows the sidebar relaunch card and starts this window. The window starts at the running app’s next configuration re-check (the re-check interval beside it), so allow up to one re-check interval on top of this value between saving a change and the restart dialog. When the window ends the app blocks with a restart dialog and restarts on its own after 2 minutes with no activity (no running Claude task and no keyboard or pointer input); the user can also restart right away. Defaults to 24 hours. Set a larger value (up to 336 = 14 days) to give users longer; `0` shows the dialog at the first observation. A served value is read from the newest served configuration, so tightening or loosening the window takes effect at the next poll without a restart, and a change to this key alone never asks for one. Like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group: set this key in the same profile as the update keys you deploy, or a served value is ignored on those devices and the 24-hour default applies. How often the running app re-checks its managed configuration for changes: it re-polls your configuration endpoint with a conditional request, so an unchanged configuration costs one `304` round-trip. A detected change shows the sidebar relaunch card and starts the `relaunchEnforcementHours` window, so a saved change reaches a running app within roughly one interval. Defaults to 10 minutes; each wait is jittered by ±10% so a fleet does not poll in lockstep. Values outside 2–30 are rejected with a parse error and the default applies. Applied without a restart: a new served value re-arms the timer at the check that delivers it, and a change to this key alone never asks for a relaunch. Set it via MDM or serve it from your configuration endpoint; like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group, and every key in it is then read from that profile alone: deploy this key in the same profile as the update keys (`disableAutoUpdates`, `autoUpdaterEnforcementHours`, …). A profile that sets the update keys without it ignores a served interval and the default applies; a profile that sets only this key ignores served update settings, so a served `disableAutoUpdates` no longer holds on those devices. A profile that also manages the connection itself (sets `bootstrapUrl` or the provider keys) follows the normal tier order instead: once a served configuration is in hand it, not the profile, supplies this key. ### OTLP | Setting | Type | Availability | Default | Description | | ----------------------------------------------------------------------- | --------- | --------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | OpenTelemetry collector endpoint
`otlpEndpoint` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Where OpenTelemetry logs and metrics are sent. Leave blank to disable. | | OpenTelemetry exporter protocol
`otlpProtocol` | `enum` | MDM + Bootstrap
Added in 1.2581.0 | `http/protobuf` | Transport protocol for the OpenTelemetry exporters. One of: `http/protobuf`, `http/json`, `grpc`. Defaults to `http/protobuf`. | | OpenTelemetry exporter headers
`otlpHeaders` | `object` | MDM + Bootstrap
Added in 1.2581.0 | — | Static collector headers — routing and tenant headers only. No credentials here; use Collector authentication or the headers helper script for tokens. Deprecated: `otlpHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no exporter headers will be sent. | | Collector authentication
`otlpAuthMode` | `enum` | MDM + Bootstrap
Added in 1.30096.1 | — | inference-credential sends the user’s inference bearer token to the collector as Authorization: Bearer. One of: `none`, `inference-credential`. | | OpenTelemetry headers helper script
`otlpHeadersHelper` | `string` | MDM + Bootstrap
Added in 1.30096.1 | — | Absolute path to an executable that prints a JSON object of collector headers. Merged over the static headers and Collector authentication; the helper wins. | | OpenTelemetry resource attributes
`otlpResourceAttributes` | `object` | MDM + Bootstrap
Added in 1.5354.0 | — | Extra resource attributes to attach to every span/metric. A static enduser.id set here always wins over the runtime identity. Deprecated: `otlpResourceAttributes as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no custom resource attributes will be attached. | | Desktop telemetry export level
`otlpDesktopLogLevel` | `enum` | MDM + Bootstrap
Added in 1.9255.0 | `error` | Controls the Claude Desktop application’s events, separate from Cowork and Code sessions. Defaults to error. One of: `off`, `error`, `warn`, `info`, `debug`. Defaults to `error`. | | Content capture categories
`otlpContentCapture` | `enum[]` | MDM + Bootstrap
Added in 1.15962.0 | — | Content categories the desktop exporter sends unredacted to your collector. Leave empty to redact all content (default). One of: `userPrompts`, `assistantResponses`, `toolDetails`, `toolContent`, `rawApiBodies`. | | Export traces
`otlpTracesEnabled` | `boolean` | MDM + Bootstrap
Added in 1.22209.0 | — | Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session tracing. | Code sessions export over the protocol set here. Chats and Cowork tasks export over `http/protobuf` instead of `grpc` on Windows, and on other platforms whenever the Claude Code engine is given an HTTP proxy (the operating system's proxy, `egressProxyUrl` or `egressProxyPacUrl`, or `HTTPS_PROXY` / `HTTP_PROXY` in a Claude Code settings file); the application log notes the substitution. The desktop application's own events always go over `http/json` to `/v1/logs`. None of this changes the endpoint, so choose `grpc` only for a collector that also serves OTLP/HTTP at the same address; otherwise keep `http/protobuf` and point `otlpEndpoint` at the collector's OTLP/HTTP receiver (conventionally port 4318). `inference-credential` adds `Authorization: Bearer ` to every export, using the token the app currently holds for the inference provider, with no helper script to deploy. The collector must accept that token as issued: a gateway OIDC token carries the gateway’s audience, Microsoft Entra on Foundry issues the Foundry resource’s token, and Vertex workforce identity forwards a Google Cloud access token; static gateway and Bedrock keys are forwarded as-is. Because the token can also call inference as the user, use this only for a collector you operate; for anything else, use the headers helper script with an ingest-scoped credential. Kinds that never produce a bearer (AWS SigV4 kinds on Bedrock, Google ADC / OAuth files on Vertex, API-key kinds) export without it — use the helper script instead. Cowork tasks pick up the current token each time they start; a Code session keeps the token it started with for as long as it stays open; the desktop’s own event exporter uses the current token on every flush. Before sign-in, exports go out unauthenticated. An `Authorization` header printed by the headers helper script wins over this. Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. `{"Authorization": "Bearer …"}`. The desktop runs it (no arguments; output cached for a few minutes, and a failure is not retried for 30 seconds) whenever it needs collector headers and merges the result over **OpenTelemetry exporter headers** and the **Collector authentication** header (the helper wins on conflict). Cowork tasks get the current output when they start; Code sessions and host-run Cowork sessions are also given the script as Claude Code’s own `otelHeadersHelper`, so an open session re-runs it as tokens rotate (on Windows this applies to `.exe`, `.cmd` and `.bat` helpers; a `.ps1` helper applies at session start only); the desktop’s own event exporter re-runs it per flush. Session start waits at most two seconds for a slow helper and otherwise proceeds without its headers until it finishes. Use this when the collector needs a credential the inference sign-in cannot provide, when the collector token rotates, or when the config comes from a hosted admin console, which cannot store header values. If the helper fails, telemetry is sent without its headers — check the app log. Extra resource attributes to attach to every span, metric, and log sent to your collector. When End-user attribution is on and no `enduser.id` is set here, the desktop fills it with the signed-in user's runtime identity; a value you set here always wins. `process.owner` (the OS login name) is always emitted; set it here to override. Each category enables a class of raw content in OpenTelemetry events sent to your collector (this data never reaches Anthropic): * `userPrompts` — user-typed prompt text * `assistantResponses` — assistant message text * `toolDetails` — tool input arguments, e.g. the web-search query string * `toolContent` — tool output content, e.g. fetched page text or command stdout * `rawApiBodies` — full inference API request and response bodies These mirror Claude Code's `OTEL_LOG_*` env vars; see the [Claude Code monitoring docs](https://code.claude.com/docs/en/monitoring-usage). Enables Claude Code's session tracing (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` + `OTEL_TRACES_EXPORTER=otlp`) in spawned Cowork tasks and Code sessions. Each user interaction exports a trace whose spans and events carry `trace_id`/`span_id`, enabling end-to-end correlation in your observability backend (metrics do not carry trace context; correlate those via `session.id`). Traces go to the collector endpoint and protocol configured above. When `otlpEndpoint` is set, this key alone decides whether those sessions export traces: leaving it unset or `false` keeps traces off even if Claude Code's own settings or managed settings (for example a `managed-settings.json` on the device) turn tracing on. Without `otlpEndpoint` it has no effect. The span structure may evolve between Claude Code releases; see the [Claude Code monitoring docs](https://code.claude.com/docs/en/monitoring-usage). ## Limits ### Session retention | Setting | Type | Availability | Default | Description | | ----------------------------------------------------------------- | --------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chat retention period
`chatSessionRetentionDays` | `integer` | MDM + Bootstrap
Added in 1.52386.0 | — | Delete chats, with their files, after this many days without activity. Unset: kept until the user deletes them. Projects and memory stay. Range: 1–3650. | | Cowork retention period
`coworkSessionRetentionDays` | `integer` | MDM + Bootstrap
Added in 1.52386.0 | — | Delete Cowork tasks, with their uploads and outputs, after this many days without activity. Unset: kept until the user deletes them. Spaces and memory stay. Range: 1–3650. | | Code retention period
`codeSessionRetentionDays` | `integer` | MDM + Bootstrap
Added in 1.52386.0 | — | Delete Code sessions, conversation included, after this many days without activity. Unset: kept until the user deletes them. Uncommitted work stays on disk. Range: 1–3650. | | Suspend session deletion
`sessionRetentionHold` | `boolean` | MDM + Bootstrap
Added in 1.52386.0 | — | Suspend all automatic session deletion for these users (legal hold). While on, the retention periods above delete nothing. | The app deletes whole sessions in the background shortly after it fetches this configuration (at launch and on each re-poll), or some minutes after launch and then daily when the configuration comes from device management alone. Idle time runs from the session's last activity; viewing an old Code session counts as activity, viewing an old chat or Cowork task without continuing it does not durably. A session that is running or open on screen is skipped and checked again on the next pass, as is a chat or Cowork task whose folder changed on disk within the period. Pinned sessions are not exempt. Minimum 1 day; a value that cannot be read as a whole number of days deletes nothing. Set through the served configuration or in the device-management profile that carries the rest of the configuration. What it does not reach: another account's sessions on the device (evaluated when that account signs in), Code sessions on a remote machine (SSH/WSL), Cowork background (dispatch) tasks the sidebar does not list, a chat or Cowork task whose folder cannot be located, and Claude Code files not named by a session id (prompt history, plans, shell snapshots), which keep Claude Code's own retention. Honored only by Claude Desktop configured for a third-party model provider. The app deletes whole sessions in the background shortly after it fetches this configuration (at launch and on each re-poll), or some minutes after launch and then daily when the configuration comes from device management alone. Idle time runs from the session's last activity; viewing an old Code session counts as activity, viewing an old chat or Cowork task without continuing it does not durably. A session that is running or open on screen is skipped and checked again on the next pass, as is a chat or Cowork task whose folder changed on disk within the period. Pinned sessions are not exempt. Minimum 1 day; a value that cannot be read as a whole number of days deletes nothing. Set through the served configuration or in the device-management profile that carries the rest of the configuration. What it does not reach: another account's sessions on the device (evaluated when that account signs in), Code sessions on a remote machine (SSH/WSL), Cowork background (dispatch) tasks the sidebar does not list, a chat or Cowork task whose folder cannot be located, and Claude Code files not named by a session id (prompt history, plans, shell snapshots), which keep Claude Code's own retention. Honored only by Claude Desktop configured for a third-party model provider. The app deletes whole sessions in the background shortly after it fetches this configuration (at launch and on each re-poll), or some minutes after launch and then daily when the configuration comes from device management alone. Idle time runs from the session's last activity; viewing an old Code session counts as activity, viewing an old chat or Cowork task without continuing it does not durably. A session that is running or open on screen is skipped and checked again on the next pass, as is a chat or Cowork task whose folder changed on disk within the period. Pinned sessions are not exempt. Minimum 1 day; a value that cannot be read as a whole number of days deletes nothing. Set through the served configuration or in the device-management profile that carries the rest of the configuration. What it does not reach: another account's sessions on the device (evaluated when that account signs in), Code sessions on a remote machine (SSH/WSL), Cowork background (dispatch) tasks the sidebar does not list, a chat or Cowork task whose folder cannot be located, and Claude Code files not named by a session id (prompt history, plans, shell snapshots), which keep Claude Code's own retention. Honored only by Claude Desktop configured for a third-party model provider. Meant to be set per user or group, through the served configuration's group overrides or in the same device-management profile that carries the rest of the configuration (a profile carrying only this key makes the device profile-managed, like any policy key); a hold in the device's profile also counts when the served configuration does not restate it. Deletion stops at the first configuration fetch that carries this value, before it takes effect as configuration at the next relaunch; a device that cannot reach its configuration server deletes nothing. ### Token limits | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------- | --------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | | Max tokens per window
`inferenceMaxTokensPerWindow` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | — | Per-user soft cap, counted client-side over the token cap window. Not a server-enforced quota. | | Token cap window
`inferenceTokenWindowHours` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | — | Tumbling window length for the token cap. Max 720 hours (30 days). Range: 1–720. | Requires `inferenceTokenWindowHours` to also be set — without a window length the cap is inert and no limit is enforced. Required when `inferenceMaxTokensPerWindow` is set — the cap only takes effect once both are configured. ## Appearance | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | End-user attribution
`endUserAttribution` | `boolean` | MDM + Bootstrap
Added in 1.25927.0 | — | Show the signed-in user’s identity-provider identity in the sidebar and account menu, and emit it as the OpenTelemetry enduser.id resource attribute. Previously named `enduserAttribution` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): end-user attribution will stay off — no identity shown, no enduser.id emitted — whatever the old name said. | | Deployment display name
`deploymentDisplayName` | `string` | MDM + Bootstrap
Added in 1.24012.0 | — | Overrides the provider label shown in the sidebar footer, user-menu header, and connection-error banner. | | Deployment display subtitle
`deploymentDisplaySubtitle` | `string` | MDM + Bootstrap
Added in 1.24012.0 | — | Optional detail shown after the deployment display name in the account-menu header. | | Hide configuration deprecation warnings
`disableConfigDeprecationWarnings` | `boolean` | MDM + Bootstrap
Added in 1.40609.0 | — | Don’t show users the in-app warning that this configuration uses a deprecated field. The final reminder in the 24 hours before the cut-off still appears. | | Organization banner
`banner` | `object` | MDM + Bootstrap
Added in 1.7196.0 | — | A persistent banner across the top of the app window after sign-in. | When on (default), the app resolves the signed-in user's identity from the configured credential source (the identity provider claim, or the OS login name when no claim is available) and shows it in the sidebar footer, the account menu, and the Code session greeting. If an OpenTelemetry collector is configured, the same identity is also emitted as the `enduser.id` resource attribute on every span, metric, and log sent to your collector — unless you have set a static `enduser.id` under OpenTelemetry resource attributes, in which case your static value is kept and the runtime identity is not emitted. When off, no identity is shown in the app and no runtime `enduser.id` is emitted; a static `enduser.id` under OpenTelemetry resource attributes still passes through unchanged. This setting does not gate the `process.owner` resource attribute (the OS login name), which is standard OpenTelemetry process metadata and is always emitted — set a static `process.owner` under OpenTelemetry resource attributes to override it. Applies to both Cowork tasks and Code sessions. Set this to the name users should see for this deployment (for example, "Claude for Government"). When unset, the desktop shows the default provider label. Maximum 60 characters. Optional detail shown after the deployment display name in the account-menu header (for example, "Claude for Veterans Affairs · Claude for Government"). Shown only when the display name is also set. Maximum 60 characters. When the organization's configuration uses a field that is deprecated — a renamed key, or a legacy value or entry form — the app shows every user a dismissable warning naming the field, what to use instead, and the date support ends (each field's cut-off is listed in the configuration changelog and takes effect at 12:00 PM Pacific Time on that date). The warning shows from the field's announced warning date until dismissed, and once more in the 24 hours before the cut-off. Set this to `true` to suppress the first showing for your users while you migrate; the final 24-hour reminder is always shown, and the deprecation stays listed in the diagnostic report (Help → Troubleshooting) and the hosted configuration editor regardless. Use this for compliance notices, an internal-support link, or to identify the deployment. The banner is shown on every page after sign-in and cannot be dismissed by the user. Colors are six-digit hex (`#RRGGBB`); when `linkUrl` is set the banner text becomes an HTTPS link. | Field | Type | Default | Description | | ----------------- | --------- | --------- | ------------------------------------------------------------------------------ | | `enabled` | `boolean` | — | Turns the banner on. When false or unset, the other banner fields are ignored. | | `text` | `string` | — | Single line, truncated on overflow. Maximum 200 characters. | | `backgroundColor` | `string` | `#F5F5F5` | Six-digit hex (#RRGGBB). Applied exactly as configured; not theme-adapted. | | `textColor` | `string` | `#000000` | Six-digit hex (#RRGGBB). Applied exactly as configured; not theme-adapted. | | `linkUrl` | `string` | — | Optional HTTPS URL. The banner text becomes a link when set. | ### Feature discovery | Setting | Type | Availability | Default | Description | | ----------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hide feature announcements
`disableFeatureDiscovery` | `boolean` | MDM + Bootstrap
Added in 1.21459.0 | `false` | Suppress unprompted feature-announcement UI: the post-update “What’s new” nudge and new-feature tips. Users can still open release notes themselves. Defaults to `false`. | Covers the version-shipped announcement UI baked into each release: the **What's new** button that appears on its own after an update, and the one-time **New feature** tips (coach-marks) that point out newly shipped capabilities. Useful when your organization gates feature availability and doesn't want the app advertising capabilities you haven't rolled out. User-initiated surfaces stay: the What's-new menu item and header button still open the release notes on demand. Auto-update behavior is unaffected — that is governed by `disableAutoUpdates` and `autoUpdaterEnforcementHours`. ## Plugins | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------- | ---------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Organization plugin settings
`orgPluginSettings` | `object[]` | MDM + Bootstrap
Added in 1.8089.0 | — | Admin policy applied to plugin-delivered MCP servers. Deprecated: `orgPluginSettings as a {"mcpServers": {…}} record` (accepted until October 7, 2026); use the array form \[\{"serverName": "…", "tools": \[\{"toolName": "…", "permission": "…"}]}] (read by desktop 1.15200.0 and later; older desktops ignore the array and enforce no tool blocks). If it is still present after that, the record will be rejected as malformed and the key will fail closed: every plugin-delivered MCP tool will be blocked until the value is rewritten. Deprecated: `orgPluginSettings[].tools[].permission: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, that tool will be treated as "blocked", like any unrecognized permission. | | Plugin marketplaces
`allowedPluginMarketplaces` | `object[]` | MDM + Bootstrap
Added in 1.17377.1 | — | Git repositories or hosted marketplace.json URLs to surface as plugin marketplaces in the Directory’s Organization tab. The app re-fetches each periodically. | Locks per-tool permissions on MCP servers provided by any installed plugin — from the org-plugins directory or a plugin marketplace, remote or run locally — one entry per server name (compared case-insensitively): ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"serverName": "internal-search", "tools": [{"toolName": "delete_document", "permission": "blocked"}]}] ``` The older record form (`{"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}}`) is deprecated and accepted only until October 7, 2026. Desktop versions before 1.15200.0 parse only the record form: on those builds an array value is ignored and plugin tool locks are **not enforced**, so update the fleet past 1.15200.0 before deploying the array form. If a Managed MCP servers entry is for the same server (same URL, else same name), that entry decides alone: its `toolPolicy` (if any) applies and the entry here is ignored. A value that cannot be read blocks every tool of every plugin-provided MCP server no Managed MCP servers entry covers. For a plugin server that Claude Code launches or connects to itself (a marketplace plugin's), the permissions travel on Claude Code's managed-settings channel: another Claude Code [managed-settings source](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) on the device replaces them unless that source sets `parentSettingsBehavior` to `"merge"`. `blocked` on a server the app connects to itself holds either way. | Field | Type | Default | Description | | ------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | | `serverName` | `string` | — | Name of the plugin-delivered MCP server this policy applies to. | | `tools` | `object[]` | — | Per-tool approval locks for this server. | | `tools.toolName` | `string` | — | MCP tool name as the server reports it. | | `tools.permission` | `enum` | — | Approval state locked for this tool. Unlisted tools stay user-controlled. One of: `allow`, `ask`, `ask-session`, `blocked`. | | Field | Type | Default | Description | | ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | `string` | — | Where the marketplace is fetched from: a GitHub repository (set repo), any Git remote (set url), or a hosted marketplace.json file (set url). One of: `github`, `git`, `url`. | | `repo` | `string` | — | GitHub repository in owner/repo form. Case-insensitive. | | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA. | | `path` | `string` | — | Folder within the repository that contains the marketplace, when it isn’t at the root. | | `expectedName` | `string` | — | Rejects the marketplace if its manifest name differs. | | `installationPreference` | `enum` | — | Whether users install plugins themselves or get them automatically. One of: `available`, `auto_install`, `required`. | | `credentialKind` | `enum` | — | How fetches authenticate: anonymously, with the user’s git credentials, via a helper executable, or as the app does to its gateway or bootstrap server (url). One of: `anonymous`, `userGit`, `credentialHelper`, `inferenceCredential`. | | `credentialHelper` | `string` | — | Executable that prints an access token for this marketplace. | | `url` | `string` | — | HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url). | | `manifestSha256` | `string` | — | SHA-256 of the exact marketplace.json to accept. Without it auto\_install and required act as available; a served manifest with any other digest is refused. | ## Source ### Bootstrap | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------ | --------- | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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`. | | 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. | | 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). | | 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. Deprecated: `bootstrapHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no bootstrap request headers will be sent (the fetch may then fail to authenticate). | | 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. | | 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`. Previously named `trustBootstrapLocalExec` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): each user will be asked to consent to bootstrap-delivered sign-in targets, endpoints, helper scripts and connectors, even when the bootstrap URL came from a device-managed profile. | 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. 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. | Field | Type | Default | Description | | --------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `scopes` | `string` | — | Space-separated; the token’s audience must match what your bootstrap server validates. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `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. | 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. 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`. ## Guides ### Recommended security profiles The profiles below are illustrative examples rather than built-in presets, and the labels are descriptive only. Use them as starting points and adjust for your environment. Layer the inference-provider keys for your cloud on top of whichever profile you choose. Recommended for most enterprise deployments. Telemetry and auto-updates stay on so Anthropic can diagnose issues and ship fixes; users can extend Claude Desktop with their own connectors. | Key | Value | | ----------------------------------------------------------------------------- | ------------------ | | [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `` | | [`autoUpdaterEnforcementHours`](#autoupdaterenforcementhours) | `24` | | [`isDesktopExtensionSignatureRequired`](#isdesktopextensionsignaturerequired) | `true` | | [`otlpEndpoint`](#otlpendpoint) | `` | For regulated environments that need to control what users can connect Claude Desktop to, while keeping Anthropic supportability. | Key | Value | | --------------------------------------------------------------- | --------------------------------- | | [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `` | | [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` | | [`disableNonessentialServices`](#disablenonessentialservices) | `true` | | [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` | | [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` | | [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` | | [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `["*.example.corp"]` | | [`otlpEndpoint`](#otlpendpoint) | `` | For air-gapped or maximally restricted environments. **The only traffic leaving the device goes to your inference endpoint and OTLP collector**, plus `downloads.claude.ai` for the VM bundle and Claude CLI binary at session start unless you deploy the [offline installer](/docs/third-party/claude-desktop/installation#offline-installation). With this profile, Anthropic receives no telemetry or logs from the app and does not deliver updates, so your team owns log collection and update distribution. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content still reaches Anthropic-operated infrastructure under this profile, as described under [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider). | Key | Value | | --------------------------------------------------------------- | --------------------------------- | | [`disableEssentialTelemetry`](#disableessentialtelemetry) | `true` | | [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` | | [`disableNonessentialServices`](#disablenonessentialservices) | `true` | | [`disableAutoUpdates`](#disableautoupdates) | `true` | | [`modelCatalogEnabled`](#modelcatalogenabled) | `false` | | [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` | | [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` | | [`skillCreationEnabled`](#skillcreationenabled) | `false` | | [`disabledBuiltinTools`](#disabledbuiltintools) | `["WebSearch","WebFetch"]` | | [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `[]` | | [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` | | [`otlpEndpoint`](#otlpendpoint) | `` | ### Tool permissions for managed MCP servers Each [`managedMcpServers`](#managedmcpservers) entry can carry a `toolPolicy` that locks the approval state per tool: * `"allow"` — the tool runs without prompting. * `"ask"` — the user approves every call; no session-scoped or standing grants are offered. * `"blocked"` — the tool is removed from Claude's session; connector settings show it as blocked by your organization. Tools with no policy entry stay user-controlled (built-in connectors apply default policies to some tools — see the reference above): the user is prompted and can approve once, approve for the rest of the task (offered for tools that can modify data), or grant a standing approval unless [`mcpPersistentAlwaysAllowEnabled`](#mcppersistentalwaysallowenabled) is `false`. Full prompt options require version 1.22209.0 or later; earlier third-party builds offered only per-call approval. The reference above also lists an `"ask-session"` value, which behaves exactly as `"ask"` and is accepted until October 7, 2026. After that date the app rejects an entry that uses it, so write `"ask"`. Managed policies take precedence over user grants, and enforcement happens in the desktop host process, not only in the prompt UI. A deny-by-default posture — `"*": "blocked"` plus exact `"allow"` entries for approved tools — is supported, including in Code sessions (where an allowed tool still gets Claude Code's own approval prompt). See the [`managedMcpServers` reference](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults. # Configuration changelog Source: https://claude.com/docs/third-party/claude-desktop/configuration-changelog Managed configuration keys by the Claude Desktop release they first shipped in Configuration 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).
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------- | | [`inferenceCredentialHelperArgs`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) | `string[]` | Helper script arguments | | [`inferenceFoundryBaseUrl`](/docs/third-party/claude-desktop/configuration#inferencefoundrybaseurl) | `string` | Azure AI Foundry base URL | | [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort) | `enum` | Default model effort | | [`alwaysStartWithDefaultModel`](/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) | `boolean` | Always start with the default model | | [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) | `boolean` | Model catalog metadata | | [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) | `string` | Model catalog URL | | [`scheduledTasksEnabled`](/docs/third-party/claude-desktop/configuration#scheduledtasksenabled) | `boolean` | Allow scheduled tasks |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "inference": { "credential": { "args": [""] }, "baseUrl": "" }, "models": { "defaultEffort": "", "alwaysStartWithDefault": "", "catalogEnabled": "", "catalogUrl": "" }, "workspace": { "scheduledTasksEnabled": "" } } ``` **Changed:** * `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://:/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:/callback`, so a `localhost`-only registration still fails sign-in on them until they update. * 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. * 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. No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------- | --------- | ------------------------------- | | [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) · Beta | `enum` | SSH connection engine | | [`chatSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#chatsessionretentiondays) | `integer` | Chat retention period | | [`coworkSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#coworksessionretentiondays) | `integer` | Cowork retention period | | [`codeSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#codesessionretentiondays) | `integer` | Code retention period | | [`sessionRetentionHold`](/docs/third-party/claude-desktop/configuration#sessionretentionhold) | `boolean` | Suspend session deletion | | [`coworkVmIpv6Enabled`](/docs/third-party/claude-desktop/configuration#coworkvmipv6enabled) | `boolean` | Enable IPv6 in the workspace VM |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "codeSurface": { "sshTransport": "" }, "sessionRetention": { "chatDays": "", "coworkDays": "", "codeDays": "", "legalHold": "" }, "workspace": { "vmIpv6Enabled": "" } } ``` **Changed:** * `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. * `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. No configuration changes in this release. No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------- | | [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath) · Beta | `string` | SSH client program | | [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes) | `integer` | Configuration re-check interval | | [`disableBypassPermissionsMode`](/docs/third-party/claude-desktop/configuration#disablebypasspermissionsmode) | `boolean` | Disable bypass permissions mode | | [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories) | `boolean` | Block reads outside working directories |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "codeSurface": { "sshClientPath": "" }, "lifecycle": { "configRecheckIntervalMinutes": "" }, "workspace": { "disableBypassPermissionsMode": "", "blockReadsOutsideWorkingDirectories": "" } } ``` **Changed:** * **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). No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`inferenceStreamIdleTimeoutSec`](/docs/third-party/claude-desktop/configuration#inferencestreamidletimeoutsec) | `integer` | Stream idle timeout | | [`egressProxyUrl`](/docs/third-party/claude-desktop/configuration#egressproxyurl) | `string` | Proxy server URL | | [`egressProxyPacUrl`](/docs/third-party/claude-desktop/configuration#egressproxypacurl) | `string` | Proxy auto-config (PAC) URL | | [`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`). |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "inference": { "streamIdleTimeoutSec": "" }, "workspace": { "egressProxyUrl": "", "egressProxyPacUrl": "" }, "claudeAiImport": { "automatic3pImport": "" } } ``` `egressProxyUrl` and `egressProxyPacUrl` are read from device management or a local configuration file only; a value served by a bootstrap URL is not applied. **Changed:** * **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. No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------- | | [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) · Beta | `string[]` | SSH host allowlist | | [`disableConfigDeprecationWarnings`](/docs/third-party/claude-desktop/configuration#disableconfigdeprecationwarnings) | `boolean` | Hide configuration deprecation warnings |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "codeSurface": { "sshHostAllowlist": [""] }, "bootstrap": { "relaunchEnforcementHours": "" }, "appearance": { "disableConfigDeprecationWarnings": "" } } ``` `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. **Changed:** * `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.:-]*$`). * `inferenceCredentialKind` accepts `interactive` for Vertex AI (Google sign-in); the Vertex `oauth` value is deprecated (below). * `orgPluginSettings` is published as an array of `{ "serverName", "tools": [{ "toolName", "permission" }] }` entries; the `{ "mcpServers": {…} }` record form is deprecated (below). * 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. * `allowedPluginMarketplaces` is no longer marked Beta. **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): * `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. After the cut-off no custom inference headers are sent. * `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. * `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. * `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. * `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. * `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. * `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. * `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. After the cut-off the key reads `false` and each user is asked to consent to bootstrap-delivered values. * `enduserAttribution`: use `endUserAttribution` instead. After the cut-off the key reads `false` and end-user attribution stays off. * `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. * `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. * 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). No configuration changes in this release. No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------ | | [`inferenceModelPricingEnabled`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingenabled) | `boolean` | Show estimated cost | | [`inferenceModelPricingMultiplier`](/docs/third-party/claude-desktop/configuration#inferencemodelpricingmultiplier) | `number` | Price multiplier | | [`inferenceModelPricing`](/docs/third-party/claude-desktop/configuration#inferencemodelpricing) | `object[]` | Model pricing | | [`userPluginMarketplacesEnabled`](/docs/third-party/claude-desktop/configuration#userpluginmarketplacesenabled) | `boolean` | Allow user-added plugin marketplaces | | [`userPluginUploadsEnabled`](/docs/third-party/claude-desktop/configuration#userpluginuploadsenabled) | `boolean` | Allow user-added plugins | | [`mcpToolTimeoutSec`](/docs/third-party/claude-desktop/configuration#mcptooltimeoutsec) | `integer` | MCP tool call timeout | | [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) | `boolean` | Skip WebFetch domain check | | [`organizationInstructions`](/docs/third-party/claude-desktop/configuration#organizationinstructions) | `string` | Organization instructions |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "models": { "pricing": { "enabled": "", "multiplier": "", "models": [ { "name": "", "inputPerMtok": "", "outputPerMtok": "", "cacheReadPerMtok": "", "cacheWritePerMtok": "" } ] } }, "plugins": { "userPluginMarketplacesEnabled": "", "userPluginUploadsEnabled": "" }, "mcp": { "toolTimeoutSec": "" }, "workspace": { "skipWebFetchPreflight": "", "organizationInstructions": "" } } ``` **Changed:** * `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. No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------- | | [`bootstrapHeaders`](/docs/third-party/claude-desktop/configuration#bootstrapheaders) | `object` | Bootstrap request headers | | [`bootstrapHeadersHelper`](/docs/third-party/claude-desktop/configuration#bootstrapheadershelper) | `string` | Bootstrap headers helper script |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "bootstrap": { "headers": "", "headersHelper": "" } } ``` **Changed:** * `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. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`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`). | | [`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. |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "claudeAiImport": { "exportEnabled": "" }, "plugins": { "marketplaces": [ { "source": "url", "url": "", "manifestSha256": "", "credentialKind": "" } ] } } ``` **Changed:** * **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. * `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). * `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. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`otlpAuthMode`](/docs/third-party/claude-desktop/configuration#otlpauthmode) | `enum` | Collector authentication | | [`otlpHeadersHelper`](/docs/third-party/claude-desktop/configuration#otlpheadershelper) | `string` | OpenTelemetry headers helper script | | [`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. |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "otlp": { "authMode": "", "headersHelper": "" }, "inference": { "credential": { "oidc": { "resource": "" } } } } ``` **Changed:** * `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.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------- | | [`modelPrefer1mContext`](/docs/third-party/claude-desktop/configuration#modelprefer1mcontext) | `boolean` | Default to 1M context | | [`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`). | | [`claudeAiImport.bannerBehavior`](/docs/third-party/claude-desktop/configuration#claudeaiimport) | `enum` | New subfield: when the import banner appears: `off` (default), `detect`, or `show`. |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "models": { "prefer1mContext": "" }, "claudeAiImport": { "enabled": "", "bannerBehavior": "" } } ``` **Changed:** * `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.
| MDM key | Type | Description | | ---------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------- | | [`updateViaUpdatesHost`](/docs/third-party/claude-desktop/configuration#updateviaupdateshost) | `boolean` | Check for updates on releases.claude.com | | [`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. |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "autoUpdate": { "viaUpdatesHost": "" } } ``` `trustBootstrapLocalExec` was renamed to `trustBootstrapDelivery`; the previous name is still accepted.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------- | | [`inferenceGatewayOidcAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencegatewayoidcauthflow) | `enum` | Gateway sign-in flow | | [`inferenceVertexWorkforceAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceauthflow) | `enum` | Workforce Identity sign-in flow | | [`trustBootstrapLocalExec`](/docs/third-party/claude-desktop/configuration#trustbootstrapdelivery) | `boolean` | Trust bootstrap-delivered local commands | | [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) | `boolean` | Allow user-created skills |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "inference": { "credential": { "authFlow": "" } }, "bootstrap": { "trustBootstrapLocalExec": "" }, "workspace": { "skillCreationEnabled": "" } } ``` **Changed:** * `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. * `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. * `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. * `enduserAttribution` is renamed to the corrected spelling `endUserAttribution`. The previous spelling is still accepted and now records a configuration warning. * `organizationPluginsUrl` is deprecated and removed from the configuration reference. The key is still honored, but organization plugins are better configured with `allowedPluginMarketplaces`. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------- | | [`mcpPersistentAlwaysAllowEnabled`](/docs/third-party/claude-desktop/configuration#mcppersistentalwaysallowenabled) | `boolean` | Allow persistent tool approvals |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "mcp": { "persistentAlwaysAllowEnabled": "" } } ```
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------- | --------- | ------------------------------ | | [`enduserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) | `boolean` | End-user attribution | | [`userContentRendererUrl`](/docs/third-party/claude-desktop/configuration#usercontentrendererurl) | `string` | Artifact preview iframe origin |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "deploymentDisplayName": "", "deploymentDisplaySubtitle": "", "enduserAttribution": "", "userContentRendererUrl": "" } ``` No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------------------------------------------------------------- | --------- | -------------------- | | [`otlpTracesEnabled`](/docs/third-party/claude-desktop/configuration#otlptracesenabled) | `boolean` | Export traces (beta) |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "otlp": { "tracesEnabled": "" } } ``` No configuration changes in this release.
| MDM key | Type | Description | | ----------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ | | [`disableFeatureDiscovery`](/docs/third-party/claude-desktop/configuration#disablefeaturediscovery) | `boolean` | Hide feature announcements | | [`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. | | [`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. | | [`managedMcpServers[].envHelperTtlSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: maximum age in seconds of a cached `envHelper` result (default 300). | | [`managedMcpServers[].headersHelperRefreshBufferSec`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `integer` | New subfield: how many seconds before credential expiry the `headersHelper` re-runs (default 60). | | [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) | `boolean` | Enable tool search |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "featureDiscovery": { "disabled": "" }, "workspace": { "toolSearchEnabled": "" } } ``` **Changed:** * `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. * `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. No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | ----------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------- | | [`inferenceFoundryAuthFlow`](/docs/third-party/claude-desktop/configuration#inferencefoundryauthflow) | `enum` | Entra ID sign-in flow | | [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) | `enum` | Microsoft 365 native sign-in broker | | [`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. |
**JSON (e.g. for non-MDM users or Bootstrap):** ```json theme={null} { "inference": { "credential": { "authFlow": "" } }, "authentication": { "microsoftAuthBroker": "" } } ``` **Changed:** * `isDesktopExtensionEnabled` — default changed from `true` to `false`: Desktop Extensions (`.dxt`, `.mcpb`) no longer load unless explicitly enabled. * `allowedPluginMarketplaces` (beta) — can now be delivered per-user through the bootstrap server; previously MDM-only. No configuration changes in this release. **Removed:** * `disableDefaultPlugins` — third-party deployments always skip the default plugin marketplaces and standard deployments always include them, so the key no longer has an effect. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [`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.) | | [`inferenceVertexWorkforceOidc.omitOfflineAccess`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) | `boolean` | New subfield: omit `offline_access` from the OIDC scope request. |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "oidc": { "omitOfflineAccess": "" } } } } ``` No configuration changes in this release. No configuration changes in this release.
| MDM key | Type | Description | | ------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------ | | [`otlpContentCapture`](/docs/third-party/claude-desktop/configuration#otlpcontentcapture) | `enum[]` | Content capture categories | | [`disableBundledSkills`](/docs/third-party/claude-desktop/configuration#disablebundledskills) | `boolean` | Disable bundled skills and workflows | | [`managedMcpServers[].server`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `enum` | Gained `"websearch"` — managed web search (Brave, Tavily, Exa or custom) |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "otlp": { "contentCapture": [ "" ] }, "workspace": { "disableBundledSkills": "" }, "mcp": { "managedServers": [ { "name": "Web search", "server": "websearch", "provider": "", "headers": { "": "" }, "customUrl": "" } ] } } ``` No configuration changes in this release.
| MDM key | Type | Description | | --------------------------------- | --------- | ------------------------ | | `chatAdvancedFileAnalysisEnabled` | `boolean` | Advanced file analysis | | `inferenceSessionLifetimeSec` | `integer` | Sign-in session lifetime |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "chatSurface": { "advancedFileAnalysis": "" }, "inference": { "sessionLifetimeSec": "" } } ``` **Deprecated:** * `betaFeaturesEnabled` — Allow beta features (added and deprecated in this release)
| MDM key | Type | Description | | ---------------------------- | --------- | -------------- | | `chatTabEnabled` | `boolean` | Allow Chat tab | | `inferenceBedrockAwsCliPath` | `string` | AWS CLI path |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "chatSurface": { "enabled": "" }, "inference": { "awsEnv": { "awsCliPath": "" } } } ```
| MDM key | Type | Description | | ------------------------------- | -------- | ----------------------- | | `inferenceVertexOAuthLoginHint` | `string` | Vertex OAuth login hint |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "loginHint": "" } } } ```
| MDM key | Type | Description | | ----------------------------------------------- | --------- | ---------------------------------- | | `inferenceVertexWorkforceAudience` | `string` | Workforce Identity audience | | `inferenceVertexWorkforceUserProject` | `string` | Workforce Identity billing project | | `inferenceVertexWorkforceOidc` | `object` | Workforce Identity IdP (OIDC) | | `organizationPluginsUrl` | `string` | Organization plugins endpoint | | `autoModeEnabled` | `boolean` | Allow Auto mode | | `inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | Re-run helper for silent refresh | | `bootstrapEnabled` | `boolean` | Use bootstrap config | | `bootstrapUrl` | `string` | Bootstrap config URL | | `bootstrapOidc` | `object` | Bootstrap OIDC parameters |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "audience": "", "userProject": "", "oidc": { "issuer": "", "authorizationUrl": "", "tokenUrl": "", "clientId": "", "scopes": "", "redirectPort": "" }, "silentRefreshEnabled": "" } } } ```
| MDM key | Type | Description | | ------------------ | --------- | ---------------- | | `coworkTabEnabled` | `boolean` | Allow Cowork tab |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "coworkSurface": { "enabled": "" } } ```
| MDM key | Type | Description | | -------------------------- | -------- | ------------------------------ | | `otlpDesktopLogLevel` | `enum` | Desktop telemetry export level | | `inferenceFoundryTenantId` | `string` | Entra ID tenant ID | | `inferenceFoundryClientId` | `string` | Entra ID client ID |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "otlp": { "desktopLogLevel": "" }, "inference": { "credential": { "tenantId": "", "clientId": "" } } } ```
| MDM key | Type | Description | | ------------------------- | ------ | --------------- | | `inferenceCredentialKind` | `enum` | Credential kind |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "kind": "" } } } ```
| MDM key | Type | Description | | ------------------------------------- | --------- | ----------------------------------------------------------------- | | `inferenceAnthropicApiKey` | `string` | Claude API key | | `inferenceCustomHeaders` | `object` | Custom inference headers (renamed from `inferenceGatewayHeaders`) | | `modelDiscoveryEnabled` | `boolean` | Model discovery | | `orgPluginSettings` | `object` | Organization plugin settings | | `builtinToolPolicy` | `object` | Built-in tool policy | | `inferenceCredentialHelperTimeoutSec` | `integer` | Credential helper timeout |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "apiKey": "", "timeoutSec": "" }, "customHeaders": "" } } ```
| MDM key | Type | Description | | -------- | -------- | ------------------- | | `banner` | `object` | Organization banner |
| MDM key | Type | Description | | ----------------------------- | --------- | ------------------------------------ | | `disableDeepLinkRegistration` | `boolean` | Disable claude:// deep-link handling | | `inferenceGatewayOidc` | `object` | Gateway SSO IdP (OIDC) |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "oidc": { "issuer": "", "authorizationUrl": "", "tokenUrl": "", "clientId": "", "scopes": "", "redirectPort": "", "bearerTokenType": "", "appendOfflineAccess": "" } } } } ```
| MDM key | Type | Description | | ------------------------------ | -------- | ------------------ | | `inferenceBedrockSsoStartUrl` | `string` | AWS SSO start URL | | `inferenceBedrockSsoRegion` | `string` | AWS SSO region | | `inferenceBedrockSsoAccountId` | `string` | AWS SSO account ID | | `inferenceBedrockSsoRoleName` | `string` | AWS SSO role name |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "ssoStartUrl": "", "ssoRegion": "", "ssoAccountId": "", "ssoRoleName": "" } } } ```
| MDM key | Type | Description | | ------------------------ | -------- | --------------------------------- | | `otlpResourceAttributes` | `object` | OpenTelemetry resource attributes |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "otlp": { "resourceAttributes": "" } } ```
| MDM key | Type | Description | | ----------------------------- | ------ | -------------------- | | `inferenceBedrockServiceTier` | `enum` | Bedrock service tier |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "serviceTier": "" } } ```
| MDM key | Type | Description | | ------------------------------ | --------- | ------------------------- | | `disableDeploymentModeChooser` | `boolean` | Disable Claude.ai sign-in |
| MDM key | Type | Description | | ---------------------------- | ------ | ------------------- | | `inferenceGatewayAuthScheme` | `enum` | Gateway auth scheme |
**JSON (Non-MDM User, Bootstrap Remote):** ```json theme={null} { "inference": { "credential": { "authScheme": "" } } } ```
| MDM key | Type | Description | | ------------------------------------- | ------------------------------------- | ----------------------------------------------------------------- | | `isDesktopExtensionEnabled` | `boolean` | Allow desktop extensions (renamed from `isDxtEnabled`) | | `isDesktopExtensionSignatureRequired` | `boolean` | Require signed extensions (renamed from `isDxtSignatureRequired`) | | `isLocalDevMcpEnabled` | `boolean` | Allow user-added MCP servers | | `isClaudeCodeForDesktopEnabled` | `boolean` | Allow Claude Code tab | | `coworkEgressAllowedHosts` | `array` | Allowed egress hosts | | `otlpEndpoint` | `string` | OpenTelemetry collector endpoint | | `otlpProtocol` | `enum` | OpenTelemetry exporter protocol | | `otlpHeaders` | `object` | OpenTelemetry exporter headers | | `autoUpdaterEnforcementHours` | `integer` | Auto-update enforcement window | | `disableAutoUpdates` | `boolean` | Block auto-updates | | `inferenceProvider` | `enum` | Inference provider | | `inferenceGatewayBaseUrl` | `string` | Gateway base URL | | `inferenceGatewayApiKey` | `string` | Gateway API key | | `inferenceVertexProjectId` | `string` | GCP project ID | | `inferenceVertexRegion` | `string` | GCP region | | `inferenceVertexCredentialsFile` | `string` | GCP credentials file path | | `inferenceVertexOAuthClientId` | `string` | Vertex OAuth client ID | | `inferenceVertexOAuthClientSecret` | `string` | Vertex OAuth client secret | | `inferenceVertexOAuthScopes` | `string` | Vertex OAuth scopes | | `inferenceVertexBaseUrl` | `string` | Vertex AI base URL | | `inferenceBedrockRegion` | `string` | AWS region | | `inferenceBedrockBearerToken` | `string` | AWS bearer token | | `inferenceBedrockBaseUrl` | `string` | Bedrock base URL | | `inferenceBedrockProfile` | `string` | AWS profile name | | `inferenceBedrockAwsDir` | `string` | AWS config directory | | `inferenceFoundryResource` | `string` | Azure AI Foundry resource name | | `inferenceFoundryApiKey` | `string` | Azure AI Foundry API key | | `inferenceModels` | `array` | Model list | | `deploymentOrganizationUuid` | `string` | Organization UUID | | `disableEssentialTelemetry` | `boolean` | Block essential telemetry | | `disableNonessentialTelemetry` | `boolean` | Block nonessential telemetry | | `disableNonessentialServices` | `boolean` | Block nonessential services | | `managedMcpServers` | `array` | Managed MCP servers | | `disabledBuiltinTools` | `array` | Disabled built-in tools | | `allowedWorkspaceFolders` | `array` | Allowed workspace folders | | `inferenceCredentialHelper` | `string` | Helper script | | `inferenceCredentialHelperTtlSec` | `integer` | Helper script TTL | | `inferenceMaxTokensPerWindow` | `integer` | Max tokens per window | | `inferenceTokenWindowHours` | `integer` | Token cap window |
**Deprecated:** * `requireCoworkFullVmSandbox` — Require full VM sandbox # Connect to GitHub Source: https://claude.com/docs/third-party/claude-desktop/connectors-github Give Claude access to your organization's GitHub repositories, issues, and pull requests, either through GitHub's hosted MCP server or a server built into the desktop app. When Claude Desktop is deployed on third-party inference, Claude can work with your organization's GitHub data (repositories, issues, pull requests, and more) through GitHub's open-source [github-mcp-server](https://github.com/github/github-mcp-server). Two connectors are available: a [remote connector](#remote-connector), where the desktop app connects to GitHub's hosted copy of the server, and a [local connector](#local-connector), a copy of the server built into the desktop app. In both cases the device talks to GitHub directly; no GitHub data or tokens pass through Anthropic's infrastructure. ## Choose a connector Both connectors expose the same family of GitHub tools; they differ in where the server runs and how users authenticate. Use this table to pick one, then follow that connector's section below. | | Remote connector | Local connector | | ------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Where the server runs | GitHub's infrastructure | On the user's device, bundled in the app | | Authentication | A personal access token you issue and distribute | OAuth device flow; no tokens to issue or distribute | | Credential handling | Token delivered through the entry's `headers` or a headers helper script | User signs in; the token is acquired and stored encrypted on the device | | GitHub Enterprise Server | Not available; github.com only | Supported; set `host` | | Tool surface controls | Per-tool [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | `toolsets`, `readOnly`, and per-tool [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers) | | Claude Desktop version | Any version that supports managed MCP servers | Requires a version that includes the bundled server (beta) | ## Remote connector GitHub hosts a copy of github-mcp-server on its own infrastructure. Claude Desktop on 3P connects to it as a standard remote [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry, authenticated with a GitHub personal access token: the device connects straight to GitHub's endpoint, and the token travels only in the request headers from the user's device. ```json theme={null} { "name": "GitHub", "url": "https://api.githubcopilot.com/mcp/", "transport": "http", "headersHelper": "/opt/org/bin/github-token" } ``` The `headersHelper` executable prints the request headers as a flat JSON object to stdout, for example `{"Authorization": "Bearer GITHUB_PAT"}`, and follows the execution model described under [short-lived credentials with a headers helper](/docs/third-party/claude-desktop/extensions#short-lived-credentials-with-a-headers-helper). Use it to fetch a per-user fine-grained token from your secrets manager. A static `headers` object also works, but it puts the same token on every device, so every session acts as that one identity; prefer the helper, a narrowly scoped fine-grained token, or the [local connector](#local-connector), which needs no tokens at all. Check the endpoint URL, the supported authentication methods, and the token scopes your tools need against [GitHub's github-mcp-server documentation](https://github.com/github/github-mcp-server), which is the source of truth for the hosted server. GitHub Enterprise Server instances are not reachable through GitHub's hosted endpoint; use the local connector instead. ## Local connector Claude Desktop includes a built-in copy of github-mcp-server and runs it as a local process when a `managedMcpServers` entry sets `server` to `github`. The server calls github.com, or your GitHub Enterprise Server instance, directly from the device. Users sign in to GitHub from the app through the OAuth device flow, so there are no personal access tokens to issue, distribute, or rotate. You register one OAuth app in your GitHub organization and ship its client ID in the entry; each user then authorizes their own sign-in. The local connector is in beta, and the in-app configuration window marks it with a **Beta** pill. ### Set up the local connector In your GitHub organization, open **Settings → Developer settings → OAuth Apps → New OAuth App** and register an app for Claude Desktop: 1. Set **Application name** and **Homepage URL** to values your users will recognize on the authorization screen. 2. Enter any valid URL as the **Authorization callback URL**. The device flow does not use a redirect, but GitHub requires the field. 3. After registering, select **Enable Device Flow** on the app's settings page and save. Sign-in fails without it. 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. 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. 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 connection** to verify that the bundled server starts and lists its tools, and select **Save**. 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`: ```json theme={null} { "name": "GitHub", "server": "github", "clientId": "OAUTH_APP_CLIENT_ID_FROM_STEP_1" } ``` | Field | Required | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Unique display name, shown to users in connector settings. | | `server` | Yes | Must be `github`. | | `clientId` | Yes | The client ID of the OAuth app (or GitHub App) from step 1. | | `host` | No | Base URL of your GitHub Enterprise Server instance, for example `https://github.example.com`. Leave unset for github.com. HTTPS is required. | | `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. | | `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. | | `readOnly` | No | `true` starts the server with read tools only; write tools are not registered at all. | | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). | 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. 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: | Host | Purpose | | ---------------- | ------------------------- | | `github.com` | OAuth device-flow sign-in | | `api.github.com` | GitHub API calls | GitHub Enterprise Server deployments need access to the instance's own host instead. No egress to any Anthropic host is needed for GitHub data. ### How users sign in The first time a user opens the GitHub connector, Claude Desktop shows a short code and opens GitHub's device-authorization page in the system browser. The user enters the code, reviews the requested access, and approves it. The resulting token is stored encrypted on the device and reused until it is revoked, it expires, or the entry's identity fields change; **Disconnect** in connector settings deletes it. ### Control what Claude can do Three levers narrow the local connector, from coarsest to finest: * **`readOnly`** removes every write tool from the server. Claude never sees them. * **`toolsets`** selects which github-mcp-server tool groups are registered, so you can expose repositories and pull requests without, for example, the Actions tools. * **`toolPolicy`** locks the approval state per tool. Without a policy, write tools ask the user before each call. A few irreversible GitHub actions (merging a pull request, pushing commits, or triggering a workflow, for example) stay at ask or stricter no matter what the policy says. The default `repo` OAuth scope grants read and write access to repositories the user can reach, so pair a broad scope with `readOnly` or a restrictive `toolPolicy` rather than relying on the scope alone to keep sessions read-only. A narrower `scope` list, or a GitHub App with minimal permissions, limits what the token itself can do. # Connect to Microsoft 365 Source: https://claude.com/docs/third-party/claude-desktop/connectors-m365 Give Claude access to your organization's Outlook, OneDrive, SharePoint, and Teams data through a connector you register in your own Microsoft Entra tenant. 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). When 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. ## Choose a connector Both connectors provide the same read and search tools; they differ in data path and authentication. Write actions (sending mail, managing drafts and calendar events, working with files, and sending Teams messages) are available on the local connector when you grant [write scopes](#grant-write-scopes). For write actions on the remote connector, contact your Anthropic representative. Use this table to pick one, then follow that connector's section below. | | Remote connector | Local connector | | ------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------- | | Microsoft 365 data path | Transits Anthropic's infrastructure (no storage) | Stays between the user's device and Microsoft | | App registrations you own | One desktop client app, plus tenant consent to Anthropic's connector app | One dedicated public client app | | Token exchange | On-behalf-of exchange in Anthropic's infrastructure | Tokens acquired and stored on the device | | Allowlisting with Anthropic | Required (two to three business days) | Not needed | | Device egress | `login.microsoftonline.com` and the connector host | `login.microsoftonline.com` and `graph.microsoft.com` | | Device-based Conditional Access | Not supported (the server-side exchange has no device identity) | Supported on managed Windows and Mac devices through brokered sign-in | | Write actions | Contact your Anthropic representative | Available with [write scopes](#grant-write-scopes) | | US Government clouds | Separate connector deployment; contact your Anthropic representative | Built in; set `azureCloud` | ## Remote connector When 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 Anthropic's Microsoft 365 connector service. The desktop app authenticates with an app registration you create in your own Microsoft Entra tenant, and the connector service performs the Microsoft Graph calls on the signed-in user's behalf. Anthropic's connector service receives the desktop's delegated access token on each request and exchanges it on-behalf-of the user for a short-lived Graph token. Neither token is persisted server-side beyond the request, and Anthropic never holds your tenant's client secrets or the user's refresh token (the refresh token stays encrypted on the user's device). Setup takes about fifteen minutes and requires a Global Administrator or Cloud Application Administrator in your Entra tenant. ### How the connection works Three applications participate in the sign-in chain. Understanding which one each ID refers to makes the setup steps below easier to follow. | Application | Owner | Purpose | | ----------------------- | ------------------------------- | ---------------------------------------------------------------------------- | | Desktop client app | You (registered in your tenant) | What Claude Desktop signs in as. Public client, PKCE, no secret. | | Anthropic connector app | Anthropic (multi-tenant) | Receives the desktop's token and calls Microsoft Graph on the user's behalf. | | Microsoft Graph | Microsoft | The Microsoft 365 data APIs. | Claude Desktop signs in through your desktop client app, receives a token scoped to the Anthropic connector app, and sends that token to Anthropic's connector service. The connector service exchanges it for a Graph token using the on-behalf-of flow and makes Graph calls as the signed-in user. ### Set up the remote connector The four steps below cover tenant consent, app registration, allowlisting, and desktop configuration. 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. Open the following URL after replacing `YOUR_TENANT_ID` with the Directory (tenant) ID shown in **Entra admin center → Overview**. ```text theme={null} https://login.microsoftonline.com/YOUR_TENANT_ID/adminconsent?client_id=07c030f6-5743-41b7-ba00-0a6e85f37c17 ``` The consent screen lists the delegated Microsoft Graph permissions the connector requests. All are read-only: | Scope | Purpose | | ----------------------------------------- | ----------------------------------------------------------- | | `User.Read` | Read the signed-in user's profile | | `Mail.Read`, `Mail.Read.Shared` | Read mail in the user's and shared mailboxes | | `Calendars.Read`, `Calendars.Read.Shared` | Read events in the user's and shared calendars | | `Files.Read.All` | Read files the user can access in OneDrive and SharePoint | | `Sites.Read.All` | Read SharePoint site content the user can access | | `Chat.Read`, `ChatMessage.Read` | Read Teams chat messages the user can access | | `offline_access` | Allow the desktop to refresh its token without re-prompting | Review the permissions and select **Accept**. FedRAMP and GovCloud deployments use a different connector app ID and a different connector service hostname. Contact your Anthropic representative for the app ID to use in this URL and in the scope string in step 4, and for the connector URL to use in step 4. Create the public client that Claude Desktop will sign in as. 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`. 2. Select **Register**, then note the **Application (client) ID** and **Directory (tenant) ID** shown on the overview page. 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**. 4. Select **Grant admin consent for \{your organization}**. No client secret is needed; this is a public client that uses PKCE. 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. Until the allowlist is updated, sign-in will succeed but the connector returns *Client application is not authorized for this resource*. 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. | Field | Value | | --------- | -------------------------------------------------------------------------- | | Client ID | The Application (client) ID from step 2 | | Tenant ID | Your Directory (tenant) ID | | Scope | `api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access` | Select **Save**, then deploy the configuration through your device-management tool as usual. 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). ```json theme={null} { "name": "m365", "url": "https://microsoft365.mcp.claude.com/mcp", "transport": "http", "oauth": { "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_2", "tenantId": "DIRECTORY_TENANT_ID", "scope": "api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access" } } ``` ### Sign in as a user After 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. ### Allow the required network hosts In addition to the [base egress hosts](/docs/third-party/claude-desktop/telemetry#required-egress-paths), Claude Desktop needs outbound HTTPS access to the hosts below. The connector service itself calls `graph.microsoft.com` from Anthropic's infrastructure, so user devices do not need egress to Graph. | Host | Purpose | | ----------------------------- | ------------------------------------------------------------- | | `login.microsoftonline.com` | Microsoft Entra sign-in | | `microsoft365.mcp.claude.com` | The connector service (substitute your deployment's hostname) | ### Troubleshoot sign-in errors The errors below are the ones most commonly seen during setup. Each maps to a specific step that was missed or misconfigured. | Error | Cause | Fix | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `AADSTS50011` redirect mismatch | Redirect URI is not exactly `http://127.0.0.1/callback`, or was registered under *Web* instead of *Mobile and desktop applications* | Re-check step 2.1 | | `AADSTS50194` multi-tenant required | Tenant ID is missing from the configuration | Add Tenant ID in step 4 | | `AADSTS65001` admin consent required | Step 1 was not completed, or step 2.4 was skipped | Complete admin consent | | `Client application is not authorized for this resource` | Anthropic allowlist not yet updated | Wait for confirmation from step 3 | | `AADSTS9000411` duplicate prompt parameter | Older Claude Desktop build | Upgrade to the current release | ## Local connector Claude Desktop includes a built-in copy of the Microsoft 365 server. As an alternative to the remote connector, you can configure the app to run that server as a local process on each user's machine: the user signs in to Microsoft Entra on the device, and the server calls Microsoft Graph directly from the device. No Microsoft 365 data or tokens pass through Anthropic's infrastructure. Choose the local connector when your data-residency requirements do not allow Microsoft 365 content to transit infrastructure outside your control, when your tenant enforces device-based Conditional Access policies (such as *Require compliant device*) that the remote connector's server-side token exchange cannot satisfy, or when you want to avoid the allowlisting step. The [comparison table](#choose-a-connector) above summarizes the differences. ### Set up the local connector 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. 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*. 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. 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. 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}**. 5. Note the **Application (client) ID** and **Directory (tenant) ID** from the overview page. 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 connection** to verify that the server starts and lists its tools, and select **Save**. | Field | Value | | ----------- | ----------------------------------------------------------------------------------------------------------- | | Tenant ID | Your Directory (tenant) ID | | Client ID | The Application (client) ID from step 1 | | Azure cloud | `global` (default), `us-gov-high`, or `us-gov-dod` | | Access | Leave empty for standard read access, or list scopes explicitly (see [Configure scopes](#configure-scopes)) | 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`: ```json theme={null} { "name": "Microsoft 365", "server": "microsoft365", "tenantId": "DIRECTORY_TENANT_ID", "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_1" } ``` | Field | Required | Description | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | Yes | Unique display name, shown to users in connector settings. | | `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. | | `clientId` | Yes | The Application (client) ID of the local-mode app from step 1. | | `tenantId` | Yes | Your Directory (tenant) ID. | | `azureCloud` | No | `global` (default), `us-gov-high`, or `us-gov-dod`. Selects the Microsoft Entra and Microsoft Graph hosts for US Government clouds. | | `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. | | `scope` | No | Space-separated delegated Graph scopes to request instead of the default read set. A string array named `scopes` is also accepted until October 7, 2026. See [Configure scopes](#configure-scopes). | | `toolPolicy` | No | Per-tool approval locks, the same as for any managed server. See [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers). | 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. 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: | Host | Purpose | | --------------------------- | ------------------------- | | `login.microsoftonline.com` | Microsoft Entra sign-in | | `graph.microsoft.com` | Microsoft Graph data APIs | US Government cloud deployments use `login.microsoftonline.us` and `graph.microsoft.us` (or `dod-graph.microsoft.us` for `us-gov-dod`) instead, 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. ### Configure scopes With no `scope` field, the connector requests the standard read set at sign-in: | Scope | Purpose | | ----------------------------------------- | ---------------------------------------------------------------------- | | `User.Read` | Read the signed-in user's profile | | `Mail.Read`, `Mail.Read.Shared` | Read mail in the user's and shared mailboxes | | `Calendars.Read`, `Calendars.Read.Shared` | Read events in the user's and shared calendars, and find meeting times | | `Files.Read.All` | Read files the user can access in OneDrive and SharePoint | | `Sites.Read.All` | Read SharePoint site content the user can access | | `Chat.Read` | Read Teams chat messages the user can access | | `OnlineMeetings.Read` | Read the user's online meetings | | `offline_access` | Refresh tokens without re-prompting | To request a different set, list scopes in the entry's `scope` field. The connector then requests exactly that list (plus `User.Read` and `offline_access`, which are always included). Use the list to narrow the read surface, to add the optional read scopes below, or to add [write scopes](#grant-write-scopes). Whatever you list must also be consented on the app registration from step 1; keep the two lists in sync. Six optional read scopes are not in the standard set: * `ChannelMessage.Read.All` adds Teams channel messages to chat search results and lets Claude list a channel's messages (`teams_list_channel_messages`). Requires tenant-admin consent. * `OnlineMeetingTranscript.Read.All` enables reading meeting transcripts. Requires tenant-admin consent. * `MailboxSettings.Read` lets the connector read the user's mailbox time zone so that dates in requests follow the user's local time rather than UTC. * `People.Read` enables people search (`search_people`), which resolves a name to a user before starting a Teams chat. * `Team.ReadBasic.All` and `Channel.ReadBasic.All` let Claude list the user's teams and their channels (`teams_list_teams`, `teams_list_channels`), which Claude uses to find the team and channel IDs that the channel-message tools take. Until `ChannelMessage.Read.All` and `OnlineMeetingTranscript.Read.All` are granted, chat search omits channel results and transcript requests return a permission error. The `search_people`, `teams_list_teams`, and `teams_list_channels` tools require Claude Desktop version 1.32885.1 or later, and `teams_list_channel_messages` requires 1.49585.0 or later. The `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. 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**. The connector provides these read and search tools: | Tool | What it does | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `outlook_email_search` | Search Outlook mail | | `outlook_calendar_search` | Search calendar events | | `find_meeting_availability` | Find free meeting times | | `chat_message_search` | Search Teams chat (1:1 and group; channel messages need `ChannelMessage.Read.All`) | | `sharepoint_search`, `sharepoint_folder_search` | Search SharePoint and OneDrive | | `read_resource` | Fetch a specific item, such as a message, event, or file | | `teams_list_chats` | List the user's Teams chats and their members, to find a chat to read or post in | | `get_me` | Return the signed-in user's own profile | | `search_people` | Search for people by name or email address (needs `People.Read`) | | `teams_list_teams`, `teams_list_channels` | List the user's teams and a team's channels (need `Team.ReadBasic.All` and `Channel.ReadBasic.All`) | | `teams_list_channel_messages` | List a channel's messages, or the replies in one conversation (needs `ChannelMessage.Read.All`) | Granting write scopes enables write tools; see [Grant write scopes](#grant-write-scopes). ### Grant write scopes With only read scopes granted, the connector is read-only. To let Claude take actions in Microsoft 365 (sending mail, managing drafts, labels, and calendar events, working with files in OneDrive and SharePoint, and sending Teams chat and channel messages), grant write scopes: add them to the entry's `scope` field and consent them on the app registration from step 1, the same as any other scope. Each write tool appears only when its scope is in the entry's list, so granting a subset of the write scopes exposes a matching subset of the tools, and removing the write scopes from the list returns the connector to read-only. Write tools require Claude Desktop version 1.19367.0 or later, and the Teams write tools require version 1.24012.0 or later. | Scope | What it enables | | --------------------------- | ------------------------------------------------------------------------------------------------------------- | | `Mail.Send` | Send mail, send drafts, and forward mail | | `Mail.ReadWrite` | Create, update, and delete drafts; trash, untrash, and delete messages; apply and remove labels on messages | | `Calendars.ReadWrite` | Create, update, delete, and respond to calendar events | | `Files.ReadWrite.All` | Create, update, rename, move, copy, and delete files and folders the user can edit in OneDrive and SharePoint | | `MailboxSettings.ReadWrite` | Create and delete mail filters, manage labels, and configure automatic replies | | `ChatMessage.Send` | Post messages in existing Teams chats | | `ChannelMessage.Send` | Post and reply to messages in Teams channels | | `Chat.Create` | Start 1:1 and group Teams chats | Sending drafts and forwarding mail also require a mail read scope (one of `Mail.Read`, `Mail.ReadWrite`, or `Mail.Read.Shared`) for the pre-send checks; the standard read set already includes one. Every write tool requires user approval on each call by default. Administrators can change a tool's approval state with [`toolPolicy`](/docs/third-party/claude-desktop/configuration#managedmcpservers), except for the send tools (`outlook_send_mail`, `outlook_send_draft`, `outlook_forward_mail`, `outlook_create_event`, `outlook_update_event`, `teams_send_chat_message`, `teams_send_channel_message`, `teams_reply_channel_message`): an `allow` setting for them resolves to `ask`, so they always require approval on each call. ### How users sign in After the configuration is deployed, the connector appears in **Customize → Connectors** in Claude Desktop. Sign-in starts when the user selects **Connect**. On both Windows and macOS, sign-in goes through the device's native authentication broker when the device is set up for it: a system account-picker dialog appears instead of the browser, and the issued tokens carry the device identity claim that device-based Conditional Access policies (such as *Require compliant device*) evaluate. When the broker is unavailable, sign-in opens the system browser instead. The requirements for each platform are listed below. The [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) configuration key controls whether sign-in uses the broker or the browser. `auto` (the default) uses the broker where it is available and the browser otherwise, `disabled` always uses the browser, and `required` makes sign-in fail when the broker is unavailable instead of opening the browser, so the refresh token stays held by the broker. Set `required` only after every device that receives the configuration is on Claude Desktop 1.49585.0 or later, because earlier versions read `required` as `disabled` and fall back to browser-only sign-in. Linux has no broker, so `required` is not supported there. Browser 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. Brokered sign-in on Windows requires Claude Desktop version 1.13576.0 or later. * Windows 10 or later (desktop editions). The broker (Web Account Manager, or WAM) is built into Windows; no separate install is needed. * 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. * 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: ```text theme={null} ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID ``` 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. 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. Brokered sign-in on macOS requires Claude Desktop version 1.19367.0 or later. * 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. * **Intune Company Portal** is installed; it provides the broker. * 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. * 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): ```text theme={null} msauth.com.anthropic.claudefordesktop://auth ``` If the app registration also lists `msauth.com.anthropic.claudefordesktop.helper://auth`, remove that entry. Claude Desktop does not use it. 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. ### Token storage and sign-out The connector's Entra tokens are stored on the device, encrypted by Claude Desktop using the operating system's secure storage. Each configured entry has its own token store, and tokens persist across app restarts so users are not asked to sign in again each session. Selecting **Disconnect** next to the connector signs the user out and deletes its stored tokens. Where the user signed in through the broker, the device's work or school account itself is managed by the operating system and remains after Disconnect, as with any other brokered app; remove the account in Windows Settings (**Accounts → Access work or school**) or macOS Company Portal, or revoke the user's sessions in Entra, to end access entirely. With `continuousAccessEvaluation` at its default of `enabled` on Claude Desktop 1.49585.0 or later, Microsoft Graph rejects the connector's current access token within minutes of the revocation. With `continuousAccessEvaluation` set to `disabled`, or on earlier app versions, revocation takes effect once the current one-hour access token expires. ### Troubleshoot the local connector | Symptom | Cause | Fix | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Test connection** reports that the built-in server is not included | The installed Claude Desktop version predates the built-in connector | Upgrade Claude Desktop | | **Microsoft 365** is missing from the **Add server** options | The installed Claude Desktop version predates the built-in connector | Upgrade Claude Desktop, or author the JSON entry directly | | Connector missing from settings | The entry was rejected during configuration parsing: an unrecognized scope name in `scope`, a missing `tenantId` or `clientId`, or a `url`, `transport`, or `command` field mixed into the entry | Check the app's main log for a line naming the dropped entry | | Sign-in opens the browser on a managed device where the broker was expected | macOS: Claude Desktop is older than 1.19367.0, Company Portal is not installed, the SSO configuration profile is not deployed, or the broker redirect URI is not registered. Windows: Claude Desktop is older than 1.13576.0, the device is not Entra-joined or Entra-registered, or `microsoftAuthBroker` is set to `disabled` | Re-check the brokered sign-in requirements above | | `AADSTS50011` redirect mismatch | The redirect URI named in the error message (`http://localhost` for browser sign-in, or the platform's broker redirect URI for brokered sign-in) is missing from the local-mode app registration, was entered with a different value, or was added under *Web* instead of *Mobile and desktop applications* | Add or correct that URI under *Mobile and desktop applications* (step 1.2, or the brokered sign-in requirements above) | | `AADSTS900971` no reply address provided | The macOS broker redirect URI is not registered on the local-mode app | Register `msauth.com.anthropic.claudefordesktop://auth` as described in step 1.2 (after you save, it appears under the **iOS / macOS** section) | | `AADSTS65001` admin consent required | Graph delegated permissions were not admin-consented | Re-check step 1.4 | | `AADSTS53003` blocked by Conditional Access | A device-compliance policy is evaluating a sign-in that carries no device claim | Meet the brokered sign-in requirements for the platform, then restart Claude Desktop | | `AADSTS7000218` request body must contain client\_assertion or client\_secret | **Allow public client flows** is set to No on the local-mode app registration, so brokered token requests are classified as confidential | Set **Allow public client flows** to **Yes** (step 1.3) | | Tools return a permission error or Graph `403` | A scope the tool needs is not consented on the app registration, or is excluded by an explicit `scope` list | Add the scope in both places and grant admin consent | | Write tools are missing or fail | The matching write scope is not listed in the entry's `scope` field, or the installed Claude Desktop version predates write support | Add the scope to the entry and consent it on the app registration (see [Grant write scopes](#grant-write-scopes)), and upgrade Claude Desktop | The connector writes its sign-in and Microsoft Graph errors to its own log file in the Claude Desktop logs directory (`~/Library/Logs/Claude-3p/` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\` on Windows), named `mcp-server-office365-builtin.log`. Configuration parsing and connection lifecycle messages appear in `main.log` in the same directory. # Write a credential helper Source: https://claude.com/docs/third-party/claude-desktop/credential-helper Supply Claude Desktop on 3P with a short-lived inference token by running an executable you provide A credential helper is an executable on the user's machine that prints an inference token to stdout. Claude Desktop on 3P runs it whenever it needs a credential for the configured inference provider, caches the result for a configurable time, and re-runs it when the credential expires. Use a helper when your token comes from an internal secret broker, a CLI, or an SSO flow that the built-in interactive sign-in options don't cover. Configure the helper with the `inferenceCredentialHelper` key; see the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) for the full list of helper-related keys. `inferenceCredentialHelper` supplies credentials for the inference connection only. An MCP server deployed through [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) uses the separate per-server `headersHelper` key, which follows the same execution model but prints a flat JSON header map and has its own cache and renewal settings (`headersHelperTtlSec`, default 300, versus `inferenceCredentialHelperTtlSec`, default 3600). See [Short-lived credentials with a headers helper](/docs/third-party/claude-desktop/extensions#short-lived-credentials-with-a-headers-helper). ## What the helper must do Claude Desktop runs the executable at the configured path and reads stdout. The executable receives no arguments unless you set [`inferenceCredentialHelperArgs`](#pass-arguments-to-the-helper). The exit code must be `0`. Anything written to stderr is logged for diagnostics but otherwise ignored. Stdout must contain exactly one of the following, with no banners, prompts, or log lines mixed in: * **A single bare token.** The whole trimmed stdout becomes the bearer token. * **A JSON object**, when per-request headers are needed: ```json theme={null} { "token": "...", "headers": { "X-Org-Route": "prod" } } ``` Headers from the JSON object are merged over [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders); the helper's value wins on a conflict. ## Pass arguments to the helper Set [`inferenceCredentialHelperArgs`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) to a JSON array of strings to pass arguments to the helper. Claude Desktop passes each entry to the executable as one argument, in order and exactly as written. One installed script can then serve users whose configurations differ, for example by environment or tenant. This configuration runs `/usr/local/bin/corp-cred-helper --environment production`: ```json theme={null} { "inferenceCredentialHelper": "/usr/local/bin/corp-cred-helper", "inferenceCredentialHelperArgs": ["--environment", "production"] } ``` In a macOS configuration profile or the Windows registry, write the array as a JSON string, as with the other [array-typed keys](/docs/third-party/claude-desktop/configuration#value-types). A [bootstrap server](/docs/third-party/claude-desktop/bootstrap) can deliver `inferenceCredentialHelperArgs` too, under the same [user-consent rule](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent) as the helper path. In the nested response format ([`bootstrap-config-v2`](/docs/third-party/claude-desktop/bootstrap#response-schema)), set `args` next to `command` in `inference.credential`. On Windows, a `.cmd` or `.bat` helper receives each argument wrapped in double quotes, so read the values with `%~1`, `%~2`, and so on to remove the quotes. A `.ps1` helper, a `.exe` helper, and helpers on macOS and Linux receive each value as written. An entry cannot be empty and cannot contain a double quote (`"`), a percent sign (`%`), or a control character. If any entry breaks these rules, Claude Desktop does not run the helper and tells the user that the configuration can't be used until you fix the entry. Keep secrets out of the arguments. The arguments appear in the diagnostic report and are visible to other processes on the device, so have the helper fetch any secret itself. ## When the helper runs Claude Desktop sets the `CLAUDE_HELPER_CONTEXT` environment variable on every invocation so the script can decide whether interactive authentication (opening a browser, prompting for a device code) is appropriate. | Value | Meaning | | --------------------- | ----------------------------------------------------------------------------------------------- | | `interactive` | The user started a session and is present. Interactive sign-in is acceptable. | | `mid-session-refresh` | A running session's credential expired. Prefer a silent refresh; the user is waiting on a turn. | | `scheduled-task` | A scheduled task started with no user present. | | `setup-test` | The in-app configuration window's connection test. | | `background` | A background probe or health check. | A well-behaved helper should attempt its silent path (cached token, refresh-token grant) for any value other than `interactive`, and exit non-zero rather than block on user input when that path is exhausted. Claude Desktop treats a non-zero exit as a refresh failure and surfaces it to the user. The legacy variable `CLAUDE_HELPER_MANUAL_RUN=1` is also set when `CLAUDE_HELPER_CONTEXT` is `setup-test`, for scripts written before the context variable existed. New scripts should branch on `CLAUDE_HELPER_CONTEXT` instead. The helper runs with a `PATH` that includes the user's login-shell `PATH` and standard install locations in addition to the app's launch environment, so a script can invoke tools such as `aws` or `gcloud` by name even when the app was launched from the Dock or Finder rather than a terminal. ## Timeouts and caching The helper's output is cached for `inferenceCredentialHelperTtlSec` seconds (default 3600). Claude Desktop checks the cached credential's expiry before each turn and, when it has expired or is about to, re-runs the helper transparently before sending the turn, with no sign-in prompt and no app relaunch. With a TTL of 120 seconds or less, Claude Desktop skips the per-turn check; the helper then re-runs at the next session start, or mid-session when the provider rejects the credential (see [Turn off mid-session re-runs](#turn-off-mid-session-re-runs)). Each run is bounded by `inferenceCredentialHelperTimeoutSec` seconds (default 60, maximum 600). When Claude Desktop re-runs the helper to recover a session mid-turn (`CLAUDE_HELPER_CONTEXT=mid-session-refresh`), the timeout is additionally clamped to 20 seconds so a slow helper can't stall the turn. A helper's silent path should comfortably finish within that window. ## Turn off mid-session re-runs By default, when a running session's credential is rejected, Claude Desktop re-runs the helper with `CLAUDE_HELPER_CONTEXT=mid-session-refresh` to recover without interrupting the user. If your helper can't run safely outside the `interactive` context, set `inferenceCredentialHelperSilentRefreshEnabled` to `false`. Claude Desktop then keeps the cached credential until the next session start and surfaces an expiry prompt instead of re-running the helper mid-session. # User identity and local data Source: https://claude.com/docs/third-party/claude-desktop/data-storage How Claude Desktop on 3P identifies users and where it stores conversations, settings, and credentials on disk Claude Desktop on third-party (3P) keeps conversations, settings, and credentials on the device. When the configuration comes from MDM, a local file, or a bootstrap server, users have no Anthropic account and never sign in to Anthropic, and Anthropic holds no per-user state. When your organization manages the app from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), users sign in with a Claude account to receive their settings, and [Where your data goes](/docs/third-party/claude-desktop/admin-console#where-your-data-goes) lists what Anthropic stores in that case. ## Identity When the app first launches in 3P mode, it generates a random UUID and writes it (base64-encoded) to the `ant-did` file in the application-data directory. When the configuration comes from MDM, a local file, or a bootstrap server, this identifier and the `deploymentOrganizationUuid` from your managed configuration are what's attached to telemetry events. The identifier is random per device and per OS-user account, and Anthropic cannot trace it back to a real device or person. In an organization managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), users sign in with a Claude account, so the app is not anonymous to Anthropic there, and [Where your data goes](/docs/third-party/claude-desktop/admin-console#where-your-data-goes) describes what Anthropic stores in that case. The OpenTelemetry export to your own collector is the exception: it identifies the user directly. Each exported record carries an `enduser.id` resource attribute with the user's identity and a `process.owner` attribute with the operating-system login name, so attributing activity to named users needs no collector-side correlation. See [User attribution](/docs/third-party/claude-desktop/telemetry#user-attribution) for where the identity comes from and the `endUserAttribution` key that controls it. ## Where data lives Claude Desktop on 3P stores everything under a dedicated directory, separate from standard Claude Desktop, so the two modes can coexist on one machine without interfering. | Platform | Application data | Logs | | -------- | ------------------------------------------ | -------------------------------------- | | macOS | `~/Library/Application Support/Claude-3p/` | `~/Library/Logs/Claude-3p/` | | Windows | `%LOCALAPPDATA%\Claude-3p\` | (under the application-data directory) | | Linux | `~/.config/Claude-3p/` | (under the application-data directory) | On Windows, earlier Claude Desktop releases stored this data under `%APPDATA%\Claude-3p\` (the Roaming profile). On first launch after upgrading, the app moves the existing directory to `%LOCALAPPDATA%` automatically; if Roaming is redirected to a network share, conversation history and configuration are copied and large regenerable caches are re-downloaded. Update any external tooling, backup jobs, or endpoint policies that reference the old path. macOS paths are unchanged. Within the application-data directory: | Path | Contents | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ant-did` | The random device identifier described above. | | `configLibrary/` | Locally authored configuration (from the in-app configuration window). `_meta.json` records which saved configuration is applied; each is a `.json` file alongside it. Ignored when a managed profile is present. | | `local-agent-mode-sessions/.../cowork_account_settings.json` | User-level preferences set in the app (display name, locale, memory toggle). | | `local-agent-mode-sessions/` | Cowork and Chat conversation history. One `local_.json` file plus a working directory per session, scoped by account and organization ID. The working directory includes an `uploads/` subdirectory with copies of files attached to the conversation and an `outputs/` subdirectory for files Claude creates. | | `local-agent-mode-sessions/.../memory/` | Cowork memory: a `CLAUDE.md` instructions file plus a `memory/` subdirectory of Markdown notes Claude writes about the user's preferences, projects, and feedback. See [Memory](#memory). | | `local-agent-mode-sessions/.../spaces//memory/` | Markdown memory notes for one project, used by Cowork sessions and Chat conversations inside that project. See [Memory](#memory). | | `local-agent-mode-sessions/...//audit.jsonl` | Append-only log of session events (tool invocations, permission decisions, file operations). Each entry is HMAC-chained to the previous one so edits or deletions are detectable; the companion `.audit-key` file holds the per-session signing key, encrypted via the OS keychain. | | `claude-code-sessions/` | Code session records holding each session's working folder, settings, title, and sometimes a short summary. The conversation transcripts themselves are in Claude Code's own store at `~/.claude/projects/`, outside this directory. | | `claude-code/`, `claude-code-vm/` | Claude Code binary and VM workspace data for Code sessions. | | `vm_bundles/` | Cached copy of the VM workspace bundle that Cowork sessions run in, plus the data disk the app creates to hold those sessions' home directories inside the VM. | | `cowork_plugins/` | User-installed and [org-provisioned](/docs/third-party/claude-desktop/extensions#organization-plugins-admin) plugins. Created on first plugin install. | | `IndexedDB/`, `Local Storage/`, `Session Storage/` | Renderer-side UI state (window layout, recent folders, preferences). | Files in this directory are written with owner-only permissions so other OS accounts on the same machine cannot read them. The logs directory contains `main.log` (application and configuration-validation events), `cowork_vm_node.log` (sandbox VM activity), `claude.ai-web.log` (renderer events), and `mcp.log` / `mcp-server-.log` (MCP connection events). Separately from the application-data directory, Claude Desktop writes user-visible outputs (Artifacts and scheduled-task results) to `~/Claude/` in your home directory, or `~/Documents/Claude/` on legacy installs. This folder is intended for you to browse directly and is not removed when you delete the application-data directory. ## Memory During Cowork sessions, Claude writes short Markdown files recording what it has learned about the user — working preferences, project context, and corrections — and reads them at the start of subsequent sessions. These files live under `local-agent-mode-sessions/.../memory/memory/` and never leave the device. Users can review and delete individual entries, or pause memory for new sessions and conversations (existing files are kept but not read or updated), under **Settings → Cowork → Memory**. The same page exposes a **Global instructions** editor for the `CLAUDE.md` file that is included in every session. Each [project](/docs/cowork/guide/projects) also keeps its own memory under `local-agent-mode-sessions/.../spaces//memory/`. Cowork sessions inside a project read and update the project's memory rather than the files under `local-agent-mode-sessions/.../memory/memory/`. A Chat conversation inside a project can read the project's memory but cannot change it, as described under [Chat conversations](#chat-conversations). ## Chat conversations [Chat](/docs/third-party/claude-desktop/chat) conversations follow the same storage model as Cowork sessions: each conversation is a session state file plus a working directory under `local-agent-mode-sessions/`, in the layout described in the table above. The state file records the conversation; the working directory holds the transcript, an `uploads/` directory with copies (or hard links) of files attached to the conversation, an `outputs/` directory for files Claude creates during the conversation (its scratch space), and the same HMAC-chained `audit.jsonl` event log. Because attachments are hard-linked where the filesystem allows it, edits made to the original file while the conversation is open can be visible to the conversation. Conversation content leaves the device only as inference requests to your configured provider, as web search queries to your configured search backend, through web access your egress configuration allows, in connector tool calls permitted by your `toolPolicy` configuration and the user's approvals, and, if you have enabled [content capture](/docs/third-party/claude-desktop/telemetry#content-capture), in telemetry to your own collector. For the questions security reviews most often ask about Chat: * **Memory is read-only and applies only inside projects.** A Chat conversation inside a project can read that project's memory unless memory was paused when the conversation started, but cannot add to or change it. Chat conversations outside a project do not read or update memory. * **Claude cannot search past chats.** Users can search their own conversations in the app, which scans the per-session files on the device on demand, but there is no index of conversation content, server-side or local (history exists only as the per-session files above), and a Chat conversation has no tools for listing or reading other sessions' transcripts. Each conversation is isolated to its own directory. * **The advanced file analysis sandbox writes only inside the session directory.** When [advanced file analysis](/docs/third-party/claude-desktop/chat#advanced-file-analysis) is enabled, code runs in a local sandbox with no network access. The sandbox writes only to the conversation's `outputs/` directory, and reads its `uploads/` directory plus, for a conversation inside a project, that project's memory. Deleting a conversation's session state file and working directory removes all of this; there is no other copy. ## Credentials Inference credentials are handled according to how they're delivered: * **Managed configuration** (for example, `inferenceGatewayApiKey`, `inferenceBedrockBearerToken`): read from the OS preference store or registry at launch and held in memory. The app also writes resolved credentials to a small set of transient, owner-only files for its own session processes, described below. * **OAuth tokens** (in-app Google sign-in, MCP servers with `oauth: true`): stored in the application-data directory, encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows). * **Credential-helper output**: held in memory for `inferenceCredentialHelperTtlSec` seconds, then discarded and re-fetched. ### Transient credential files Parts of each session run as separate processes: the sandbox VM for Cowork sessions, and the Claude Code runtime for Code sessions. Processes that cannot receive credentials through an in-memory channel read them from short-lived files that the app writes for them. All of these files are created with owner-only permissions and are cleaned up automatically: | Path (within the application-data directory) | Contents | Lifecycle | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `host-creds-.json` | The resolved inference credential (bearer token or API key, plus the endpoint), as environment values for background Claude Code worker processes. Written atomically with owner-only permissions (mode `0600` on macOS; per-user ACLs on Windows). | Rewritten on each credential refresh; deleted when the app quits; leftovers from a crash are removed at the next launch. The random path segment is regenerated when you sign out of the inference provider or its credentials are rotated, so a process holding the old path loses access. | | `ccd-session-secrets//` | File-based credentials for Code sessions: Google Cloud application default credentials for Google Cloud's Agent Platform, or AWS configuration files for Amazon Bedrock. The directory is created with owner-only permissions (mode `0700` on macOS; per-user ACLs on Windows). | Created when the session starts; removed when the session ends; the whole directory is swept before the next Code session starts and when you sign out of the inference provider. | | Per-session working directory | For Cowork sessions, the same file-based credentials (Google Cloud's Agent Platform and Amazon Bedrock) are written into the session's working directory, which is mounted into the sandbox VM. | Scoped to the session; removed with the session directory. | Aside from these files, credentials delivered through managed configuration are held in memory only. ## Automatic deletion of idle sessions By default, chats, Cowork tasks, and Code sessions stay on the device until the user deletes them. To delete them after a period without activity, set [`chatSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#chatsessionretentiondays), [`coworkSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#coworksessionretentiondays), or [`codeSessionRetentionDays`](/docs/third-party/claude-desktop/configuration#codesessionretentiondays) to a number of days from 1 to 3650. Each key covers one kind of session, and a kind you leave unset is kept until the user deletes it. Idle time counts from the session's last activity, and pinned sessions are not exempt. The app deletes whole sessions in the background. A chat or Cowork task is deleted with its attached files and outputs, and a Code session with its conversation. Projects, memory, and the files in a Code session's working folder stay, and Code sessions on an SSH host are not affected. A session that is running or open on screen is skipped until a later pass. To suspend all automatic deletion for some users, for example under a legal hold, set [`sessionRetentionHold`](/docs/third-party/claude-desktop/configuration#sessionretentionhold) to `true` for them. While the hold is on, nothing is deleted, and a device that gets its configuration from a server and cannot reach that server also deletes nothing. These keys require Claude Desktop 1.52386.0 or later. ## Removing data To fully reset a device's Claude Desktop on 3P state, delete the application-data directory above and the `~/Claude/` user-files folder. Code session transcripts are in Claude Code's store at `~/.claude/projects/`, which Claude Code in the terminal also uses, so delete them there separately if you need to remove them. For [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions#host-requirements), that store and any attached files are on the remote host. To return to standard Claude Desktop without removing data, choose the Anthropic sign-in option on the sign-in screen; to also remove the locally authored 3P configuration, delete the `configLibrary/` directory. Conversation history exists only on this device, or on the SSH host for remote Code sessions, so deleting it is unrecoverable. # Sign in through the OS identity broker Source: https://claude.com/docs/third-party/claude-desktop/entra-broker Use the operating system's native Microsoft Entra sign-in broker so Claude Desktop on 3P satisfies device-based Conditional Access policies Several Claude Desktop on 3P features can authenticate to Microsoft Entra ID, including the Microsoft Foundry inference provider, gateway and Workforce Identity sign-in when Entra ID is the identity provider, managed MCP servers, and the Microsoft 365 connector. Each of these can run its Entra sign-in through the operating system's native identity broker instead of a browser or device code. This page covers what the broker is, when to choose it, and the prerequisites that apply wherever the app uses it. The feature-specific pages linked under [Where the broker is used](#where-the-broker-is-used) describe how to turn it on for each feature. ## What the broker is The OS identity broker is the operating system's built-in Microsoft sign-in component. On Windows it is Web Account Manager (WAM), which ships with Windows 10 and later. On macOS it is provided by the Intune Company Portal app together with the Microsoft Enterprise SSO plug-in. When Claude Desktop signs in through the broker, the operating system shows its own account picker, the user selects or signs in to a work account, and the broker issues the token. Nothing opens in a web browser, and the app never handles the user's password. ## Why use the broker The broker is the most reliable sign-in flow for Microsoft Entra Conditional Access policies that require a compliant or managed device, or that require token protection, because it always carries the device identity claim those policies evaluate. Device-code sign-in never carries that claim. Browser sign-in carries it only when the browser itself is integrated with device identity (for example, Microsoft Edge signed in with the work account on an Entra-joined Windows device, or a macOS browser with Microsoft's Enterprise SSO integration deployed). The broker satisfies these policies on any supported device without relying on browser configuration. The broker also removes the need for a `localhost` or `127.0.0.1` loopback redirect on the device, which some network policies block, and it is not affected by Conditional Access policies that block the device-code authentication flow. ## Where the broker is used | Feature | How to enable it | Page | | ------------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Microsoft Foundry inference provider | Set `inferenceFoundryAuthFlow` to `broker` | [Microsoft Foundry](/docs/third-party/claude-desktop/foundry#in-app-entra-id-sign-in) | | LLM gateway single sign-on | Set `inferenceGatewayOidcAuthFlow` to `broker` | [LLM gateway](/docs/third-party/claude-desktop/gateway#single-sign-on-configuration-keys) | | Workforce Identity sign-in for Google Cloud's Agent Platform | Set `inferenceVertexWorkforceAuthFlow` to `broker` | [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex#in-app-workforce-identity-sign-in) | | Managed MCP server | Set `authFlow` to `broker` in the entry's `oauth` object | [Managed MCP servers](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin) | For the gateway and Workforce Identity flows, the broker is available only when your identity provider is Microsoft Entra ID: the `issuer` in `inferenceGatewayOidc` or `inferenceVertexWorkforceOidc` must have the form `https://login.microsoftonline.com/TENANT_ID/v2.0`. For a managed MCP server, the `oauth` object must also set `tenantId`, `clientId`, and `scope`. The [Microsoft 365 connector](/docs/third-party/claude-desktop/connectors-m365#how-users-sign-in) also uses the OS broker for its own Entra sign-in. Its broker setup is documented on that page, and its app registration needs the same settings described under [Register the Entra ID application](#register-the-entra-id-application). ## Platform support Brokered sign-in is available on Windows and macOS. Linux has no OS identity broker. What happens on Linux, or on a Windows or macOS device where the broker is unavailable, depends on the feature. For the inference sign-in flows (Foundry, gateway, and Workforce Identity), the app shows an error that names the browser flow as the alternative rather than falling back to a browser or device-code flow, because a silent fallback would bypass the device policy the broker was chosen to satisfy. Managed MCP servers and the [Microsoft 365 connector](/docs/third-party/claude-desktop/connectors-m365#how-users-sign-in) fall back to the system browser instead. To make the Microsoft 365 connector's sign-in fail rather than fall back, set [`microsoftAuthBroker`](/docs/third-party/claude-desktop/configuration#microsoftauthbroker) to `required` (Claude Desktop 1.49585.0 or later). ## Register the Entra ID application Brokered sign-in places two requirements on the Entra ID app registration that the feature signs in against. These are in addition to whatever API permissions the feature itself needs. Under **Authentication**, set **Allow public client flows** to **Yes**. The control is on the **Settings** tab under **Web and SPA settings** (on older versions of the portal, under **Advanced settings**). Brokered token requests carry no client secret, so Entra ID relies on this setting to classify the app as a public client. With it set to No, brokered sign-in fails with error code `AADSTS7000218`. Under **Authentication**, add the broker redirect URI for each platform you deploy to under the **Mobile and desktop applications** platform: | Platform | Redirect URI | | -------- | ---------------------------------------------------------------- | | Windows | `ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID` | | macOS | `msauth.com.anthropic.claudefordesktop://auth` | Replace `APPLICATION_CLIENT_ID` in the Windows value with the registration's own Application (client) ID. The macOS value is a fixed string. ## Prepare devices On Windows, WAM is built into the operating system. The device must be Entra joined, Entra hybrid joined, or Entra registered so the broker has a work account to present. For Conditional Access policies that require a compliant device, the device must also be marked compliant in Intune (or hybrid joined) as your policy requires. On macOS, the broker is provided by Intune Company Portal. Each device needs: * Intune Company Portal installed. * An Extensible SSO configuration profile of type Redirect, pointed at the Microsoft Enterprise SSO plug-in, deployed through your MDM. The broker is unavailable without it. * Enrollment in an MDM and registration in Entra ID. For Conditional Access policies that require a compliant device, the device must also be marked compliant in Intune as your policy requires. For MDMs other than Intune, use the partner device-compliance integration that reports compliance to Intune and Entra. ## Token storage The operating system's broker holds the credential and renews it silently from the device's primary refresh token. The app stores only a reference to the signed-in account, not a refresh token. When the broker can no longer renew silently (for example, the device falls out of compliance or the user's sessions are revoked in Entra), the app prompts the user to sign in again. ## Troubleshoot If sign-in fails with error code `AADSTS7000218`, **Allow public client flows** is set to No on the app registration. Set it to **Yes** under **Authentication**. If sign-in fails with error code `AADSTS50011` or `AADSTS900971`, the platform's broker redirect URI is missing from the app registration or does not exactly match the value under [Register the Entra ID application](#register-the-entra-id-application). Add or correct it under **Authentication → Mobile and desktop applications**. If sign-in fails with a message that the OS identity broker is unavailable, the device does not meet the requirements under [Prepare devices](#prepare-devices). On macOS, confirm Company Portal is installed and the Enterprise SSO configuration profile is deployed. On Windows, confirm the device is Entra joined or registered. The broker writes its own diagnostic log outside the app. On Windows, WAM events appear in Event Viewer under **Applications and Services Logs → Microsoft → Windows → AAD → Operational**. On macOS, Company Portal writes to the unified log; view it with `log show --predicate 'subsystem == "com.microsoft.CompanyPortalMac"' --last 1h` in Terminal. The app's own log records when a brokered sign-in was attempted and the error it returned; see [Data storage and residency](/docs/third-party/claude-desktop/data-storage) for the log location. # MCP, plugins, skills, and hooks Source: https://claude.com/docs/third-party/claude-desktop/extensions Extend Claude Desktop on 3P with connectors, plugin marketplaces, organization plugins, skills, and hooks for administrators and end users Claude Desktop on third-party (3P) supports the same extensibility model as standard Claude Desktop ([MCP connectors](/docs/connectors/overview), [skills](/docs/skills/overview), and [plugins](/docs/plugins/overview)), with the key difference that administrators provision them through managed configuration and the filesystem rather than the claude.ai admin console. There are three layers, in order of precedence: | Layer | Provisioned by | Delivered via | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Managed MCP servers | Admin | `managedMcpServers` configuration key | | Organization plugins | Admin | A [plugin marketplace](#plugin-marketplaces-admin) hosted in git or over HTTPS (recommended), or a [system-wide directory](#organization-plugins-admin) on each device | | User extensions | End user | In-app Connectors and Plugins UI | Admins can disable the user layer entirely; see [Controlling user extensions](#controlling-user-extensions). ## Managed MCP servers (admin) Use the `managedMcpServers` configuration key to deploy MCP servers (remote HTTP/SSE or local stdio command) to every device. These appear in the user's connector list automatically, can't be removed by the user, and support per-tool policy locks (`allow` / `ask` / `blocked`). The same key also activates the servers bundled inside the app (Microsoft 365, web search, and GitHub); see [Built-in connectors](/docs/third-party/claude-desktop/built-in-connectors). The **Connectors** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) provides a form for each server: name, per-tool policy, headers or a headers helper script, transport, and URL. In-app configuration window showing a managed MCP server named sentry, with fields for name, tool policy, headers, headers helper script, Streamable HTTP transport, and URL. In the exported configuration, each server is one entry in the `managedMcpServers` array: ```json theme={null} [ { "name": "internal-search", "transport": "http", "url": "https://mcp.example.corp", "oauth": true, "toolPolicy": { "search": "allow", "delete_document": "blocked" } }, { "name": "ticketing", "transport": "http", "url": "https://tickets.example.corp/mcp", "headersHelper": "/usr/local/bin/corp-sso-token", "headersHelperTtlSec": 900 } ] ``` See the [`managedMcpServers` schema](/docs/third-party/claude-desktop/configuration#managedmcpservers) in the configuration reference for every field, including static headers, OAuth, and the headers-helper executable for short-lived tokens. In the in-app configuration window, each server you add under **Connectors** has a **Test this connection** button that runs a live MCP `initialize` and `tools/list` against the server using the headers or OAuth settings you've entered, then shows the round-trip latency, the discovered tool list, or the error returned. Use it to validate reachability and credentials before exporting the configuration. ### OAuth sign-in For a remote server entry with `oauth` set, Claude Desktop signs each user in through the system browser and receives the authorization code on a fixed loopback address. Register this redirect URI on the OAuth client, or allow it on your authorization server if clients register themselves: ```text theme={null} http://127.0.0.1:53280/callback ``` The value is the same on every device and for every delivery method (device management, a local configuration file, or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap)). On identity providers that accept any port on a loopback redirect URI (the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) native-app pattern), a registration of `http://127.0.0.1/callback` also matches. With `"oauth": true`, Claude Desktop registers its own public client through dynamic client registration and lists this URI as the client's only redirect URI, so the authorization server must offer a registration endpoint and accept an `http` loopback redirect URI. With a client you registered yourself, set `oauth.clientId` and add the URI to that registration. If the registration uses `localhost` or another port, set `oauth.callbackHost` or `oauth.callbackPort` to match; both require `clientId`. An `http` or `sse` entry with no `oauth`, no `headersHelper`, and no `Authorization` header is treated as `"oauth": true` when its server asks for authentication (Claude Desktop 1.24012.0 or later). This redirect URI applies to MCP server sign-in only. [Gateway single sign-on](/docs/third-party/claude-desktop/gateway#set-up-single-sign-on) and [bootstrap sign-in](/docs/third-party/claude-desktop/bootstrap#provider-notes) register their own loopback redirect URI. #### How OAuth sign-in works Claude Desktop starts sign-in only when the MCP server answers an unauthenticated request with HTTP `401`. A redirect to a web sign-in page does not start sign-in, so a gateway in front of the server must answer an unauthenticated MCP request with `401` rather than `302`. At launch, Claude Desktop connects to every managed server without user interaction. A server with a stored token connects silently, and Claude Desktop refreshes the token first when it is near expiry. A server with no usable token appears under **Customize → Connectors** with a **Connect** button, and no browser window opens until the user selects it. When the user selects **Connect**, Claude Desktop: 1. Starts a temporary HTTP listener on `127.0.0.1:53280` (or the host and port set in `oauth.callbackHost` and `oauth.callbackPort`). If another process holds the port, sign-in fails with a port-in-use error. 2. Reads the `401` response. The `resource_metadata` URL in its `WWW-Authenticate: Bearer` header, or else the server's `/.well-known/oauth-protected-resource` URL, leads to the protected-resource metadata. Its `resource` must be the server URL or a parent path on the same origin, and Claude Desktop uses the first authorization server it lists, or looks for authorization-server metadata on the MCP server's own origin when the server publishes no protected-resource metadata. Claude Desktop then fetches the authorization server's metadata from `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration`, and the `issuer` in the metadata must match the authorization server URL, or sign-in stops. 3. Uses the client from `oauth.clientId`, or registers one at the authorization server's registration endpoint and stores it for later sign-ins. 4. Opens the authorization URL in the system browser with a PKCE (`S256`) challenge and a `state` value. The authorization endpoint must use `https`. 5. Waits up to 120 seconds for the browser to return to the redirect URI, exchanges the code at the token endpoint, and connects to the server with the resulting access token. The listener closes when sign-in completes or fails. To name the authorization server yourself instead of discovering it, set `oauth.clientId` together with one of `oauth.tenantId` plus `oauth.scope` (Microsoft Entra ID), a single `oauth.authorizationServer` entry (the issuer URL exactly as that server's metadata states it), or `oauth.authorizationUrl` and `oauth.tokenUrl` for a provider that serves no discovery document. With several `oauth.authorizationServer` entries, discovery runs as in step 2 and the discovered authorization server must match one of them. Tokens are stored on the device, encrypted with the operating system's secure storage (see [Credentials](/docs/third-party/claude-desktop/data-storage#credentials)), and refreshed in the background before they expire. When the authorization request carries a scope and the authorization server's metadata lists `offline_access`, Claude Desktop adds `offline_access` so that a refresh token is issued; see `oauth.scope` and `oauth.appendOfflineAccess` in the [configuration reference](/docs/third-party/claude-desktop/configuration#managedmcpservers) to change the requested scopes. If the authorization server rejects a refresh, or issued no refresh token and the access token expires, the server returns to the **Connect** state and the user signs in again. If sign-in fails (the callback does not arrive within 120 seconds, the authorization server rejects the registration or the redirect URI, or the identity provider completes sign-in from a host other than the authorization endpoint's), the user sees a connection error, the server keeps its **Connect** button, and `main.log` in the [logs directory](/docs/third-party/claude-desktop/data-storage#where-data-lives) records the reason. For an identity provider that completes sign-in from a different host than its authorization endpoint, list that host in `oauth.additionalRedirectReferrerHosts`. The log names the rejected host. For a server whose OAuth sign-in goes to Microsoft Entra ID, you can run that sign-in through the [OS identity broker](/docs/third-party/claude-desktop/entra-broker) instead of the system browser by setting `authFlow` to `broker` inside the entry's `oauth` object, alongside `tenantId`, `clientId`, and `scope`. On a device where the broker is unavailable, sign-in for that server falls back to the system browser, so keep the loopback redirect URI registered as well if any devices lack the broker. ### Short-lived credentials with a headers helper For short-lived header credentials, configure the helper per server: | Key | Default | What it does | | ------------------------------- | ------- | ----------------------------------------------------------------------------------------- | | `headersHelper` | None | Executable that prints the request headers as a flat JSON object to stdout. | | `headersHelperTtlSec` | 300 | Seconds the returned headers stay valid. | | `headersHelperRefreshBufferSec` | 60 | Seconds before expiry that the helper re-runs. Set it above the helper's typical runtime. | The helper follows the [`inferenceCredentialHelper`](/docs/third-party/claude-desktop/credential-helper) execution model, with four differences: no arguments, a 30-second time limit, no `CLAUDE_HELPER_CONTEXT`, and no prompting for input. The helper applies only to servers provisioned through managed configuration and never replaces the `Authorization` header on `oauth` entries. While the connection is open, the TTL schedule triggers renewal, and a request that the server rejects with HTTP 401 or 403 also re-runs the helper and, when it returns new headers, is retried once with them (Claude Desktop 1.46388.1 or later). A failed helper run does not interrupt the connection; Claude Desktop keeps the current headers and retries on its schedule. A failure while the server is connecting shows the server as needing authentication. Mid-session renewal requires Claude Desktop 1.21459.0 or later. Earlier versions run the helper only when the server connects. ### Supported MCP servers Any MCP server reachable from the user's device over HTTPS works with Claude Desktop on 3P, including public servers from third parties and internal servers you build and host (including on internal gateways). Claude Desktop does not present a TLS client certificate when connecting to MCP servers, so a server that requires mutual TLS (mTLS) client-certificate authentication fails to connect. Terminate the client-certificate requirement before the MCP endpoint (for example, at a gateway or reverse proxy), and authenticate the connection with headers or OAuth instead. The [Claude connector directory](https://claude.com/connectors) is the canonical catalog of vetted servers. **Every connector in the directory that is not labeled "Made by Anthropic" is accessible in Claude Desktop on 3P** and can be deployed via `managedMcpServers` or installed by users. Connectors labeled "Made by Anthropic" are hosted on Anthropic infrastructure and are available only in standard Claude Desktop. Some connectors return [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), interactive widgets that Claude Desktop renders in place of a plain-text tool result. Each widget loads in a sandboxed iframe on `*.claudemcpcontent.com`, and setting [`disableNonessentialServices`](/docs/third-party/claude-desktop/configuration#disablenonessentialservices) to `true` blocks that origin, so Claude Desktop shows the connector's text result instead of the widget. The same key also blocks artifact previews and connector favicons. To keep MCP Apps rendering, leave `disableNonessentialServices` unset or `false`, and allow the widget hosts listed under [Required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths) at your perimeter firewall. ### Productivity suites Google Workspace and Microsoft 365 each have a dedicated setup path: Gmail, Calendar, Drive, Docs, and more via Google's own Workspace MCP servers. See [Google's setup guide](https://developers.google.com/workspace/guides/configure-mcp-servers) to get started. Outlook, OneDrive, SharePoint, and Teams. Requires registering an app in your Entra tenant and an Anthropic allowlist step. ## Plugin marketplaces (admin) A **plugin marketplace** is a catalog file (`marketplace.json`) that lists one or more Claude plugins. You host it either as a git repository or as a plain file over HTTPS. Claude Desktop fetches it on each device, shows the plugins under **Settings → Plugins → Organization** in both **Cowork** and [**Code**](/docs/third-party/claude-desktop/code), and keeps them in sync with the revision you pin. You control which plugins are available, which install automatically, and which are required. This is the recommended way to distribute organization plugins. For a git-hosted marketplace, Claude Desktop clones with the git already installed on each device, so include git in your device baseline (Git for Windows on Windows; the Xcode Command Line Tools provide it on macOS); devices without git can use a [marketplace hosted over HTTPS](#host-the-marketplace-over-https-instead-of-git) instead. Use the [system-wide directory](#organization-plugins-admin) path when end-user devices cannot reach a git server or an HTTPS file host. Plugin marketplaces are in beta and require Claude Desktop 1.17377.1 or later. ### Create the marketplace repository A marketplace repository contains a `.claude-plugin/marketplace.json` file at its root that lists each plugin and its location. The format is shared with Claude Code; see [Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) for the full schema and walkthrough. ```json .claude-plugin/marketplace.json theme={null} { "name": "acme-internal", "owner": { "name": "Acme IT" }, "plugins": [ { "name": "expense-policy", "source": "./plugins/expense-policy", "description": "Answers questions about Acme travel and expense policy" } ] } ``` Put plugin content directly in the marketplace repository with a relative `source` path. Plugins whose `source` points at a different repository are listed in the Organization tab but are not fetched or auto-installed. The marketplace `name` must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` and must not be one of the reserved values `unknown`, `org`, or `org-provisioned`. ### Host the marketplace over HTTPS instead of git When end-user devices do not have git available, or when you already run an internal web server, artifact repository, or object store, you can serve the marketplace as static files over HTTPS instead. Claude Desktop downloads the manifest and each plugin archive itself, so the endpoint has no git dependency, and the fetch goes through the same proxy and TLS path as the rest of the app. Serve a `marketplace.json` file at any HTTPS path and package each plugin as a zip archive on the **same origin** as the manifest: ```json marketplace.json theme={null} { "name": "acme-internal", "owner": { "name": "Acme IT" }, "plugins": [ { "name": "expense-policy", "description": "Answers questions about Acme travel and expense policy", "source": { "source": "archive", "url": "https://plugins.acme.example.com/claude/expense-policy-1.3.0.zip", "sha256": "9f2c04d1...b8e7 (64-character hex SHA-256 of the zip)" } } ] } ``` Then add a `"source": "url"` entry to `allowedPluginMarketplaces` whose `url` points at this manifest (see the [field table](#configure-the-marketplace) below). Claude Desktop verifies each archive's `sha256` before unpacking it. The zip must contain the plugin at its root (a single wrapping folder is tolerated), including `.claude-plugin/plugin.json`. Archive URLs must share the manifest's origin. That origin is the only host you need to allow through your perimeter firewall, and the only host the [marketplace credential](#marketplace-credentials) is sent to. Plugins in the manifest with any other `source` kind, or an archive on a different origin, are listed for users but never fetched. If any archive in a fetch fails to download or fails its digest check, Claude Desktop installs nothing from that fetch and retries on the next sync. ### Configure the marketplace You can add marketplaces directly in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): in the **Plugins** section, click **Add marketplace** and choose **Blank**, **GitHub repo**, **Git URL**, or **Marketplace URL**. The form validates the entry and exports the encoded JSON for you. In-app configuration window Plugins section showing the plugin marketplaces card with an open Add marketplace menu offering Blank, GitHub repo, and Git URL, above the organization plugins folder path with two loaded plugins. To write the configuration by hand instead, add the repository to the [`allowedPluginMarketplaces`](/docs/third-party/claude-desktop/configuration) configuration key. The key is read from an MDM profile, local configuration, or the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) response. In an MDM profile the value is a JSON array encoded as a string (see [Value types](/docs/third-party/claude-desktop/configuration#value-types)). In a local configuration file or the bootstrap response the value is a native JSON array. ```xml .mobileconfig (macOS) theme={null} allowedPluginMarketplaces [{"source":"github","repo":"acme-corp/claude-plugins","ref":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0","credentialKind":"userGit","installationPreference":"auto_install"}] ``` On Windows, write the same string to the `allowedPluginMarketplaces` value in the registry policy key your deployment already uses (`HKLM\SOFTWARE\Policies\Claude` for machine policy). Keep the value in the same hive as the rest of your configuration: when machine policy is present, the app ignores user policy entirely; see [Deploy the configuration](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) for the exact rule. For GitLab, Bitbucket, or a self-hosted git server, use `"source": "git"` with a full HTTPS `url` instead of `repo`. For a [marketplace hosted over HTTPS without git](#host-the-marketplace-over-https-instead-of-git), use `"source": "url"` with `url` pointing at the `marketplace.json` file: ```json theme={null} [{"source":"url","url":"https://plugins.acme.example.com/claude/marketplace.json","credentialKind":"inferenceCredential","installationPreference":"available"}] ``` | Field | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | **Required.** `"github"` (with `repo`), `"git"` (with `url`), or `"url"` (with `url` pointing at a hosted `marketplace.json`). | | `repo` | GitHub repository in `owner/name` format. `github` sources only. | | `url` | For `git` sources, the full HTTPS clone URL. For `url` sources, the HTTPS address of the `marketplace.json` file. Use a bare URL with no embedded credentials or query string, and set `credentialKind` for authentication. | | `ref` | Branch name, tag name, or full 40-character commit SHA. Git sources only. **Required, and must be a full commit SHA,** when `installationPreference` is `"auto_install"` or `"required"`. | | `path` | Subdirectory containing `.claude-plugin/marketplace.json` when not at the repository root. Git sources only. | | `manifestSha256` | 64-character hex SHA-256 of the exact `marketplace.json` file to accept. `url` sources only. **Required** when `installationPreference` is `"auto_install"` or `"required"`; a served manifest with any other digest is refused. | | `expectedName` | If set, the fetch is rejected unless the `name` in `marketplace.json` matches this value exactly, so a change to the manifest name cannot silently replace another configured marketplace. | | `credentialKind` | `"anonymous"` (default), `"userGit"`, `"credentialHelper"`, or (for `url` sources) `"inferenceCredential"`. See [Marketplace credentials](#marketplace-credentials). | | `credentialHelper` | Path to an executable that prints an access token on stdout. Required, and only valid, when `credentialKind` is `"credentialHelper"`. | | `installationPreference` | `"available"` (default), `"auto_install"`, or `"required"`. See [Marketplace installation preferences](#marketplace-installation-preferences). | You can configure multiple marketplaces; each appears as its own sub-tab under **Settings → Plugins → Organization**. If an admin-configured marketplace has the same `repo`, `url`, or manifest `name` as one the user added themselves, the admin entry replaces the user's. ### Marketplace installation preferences | `installationPreference` | Behavior | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"available"` | Plugins appear in the Organization tab for users to install manually. Nothing is installed automatically. | | `"auto_install"` | Every plugin is installed automatically the first time the pinned `ref` is seen. Users can uninstall individual plugins; when you later change the `ref`, each plugin is installed again at the new revision. | | `"required"` | Every plugin is installed automatically and re-asserted on every sync. Users cannot uninstall or disable required plugins. | `"auto_install"` and `"required"` marketplaces must carry an admin-side content pin so the exact plugin content deployed to every device is deterministic and auditable. Git sources must set `ref` to a full 40-character commit SHA; Claude Desktop refuses to auto-install from a branch or tag name. `url` sources must set `manifestSha256` to the SHA-256 of the exact `marketplace.json` bytes and give every archive a `sha256`; Claude Desktop refuses a served manifest with a different digest and skips unpinned archives. #### Per-plugin auto-install from a trusted origin A `url` marketplace served from your deployment's own [inference gateway](/docs/third-party/claude-desktop/gateway) origin (`inferenceGatewayBaseUrl`) or [bootstrap server](/docs/third-party/claude-desktop/bootstrap) origin (`bootstrapUrl`) can mark individual plugins for automatic installation inside `marketplace.json` itself, without a `manifestSha256` pin in configuration. Leave the entry's `installationPreference` at `"available"` and set `installationPreference` on each plugin you want installed automatically: ```json marketplace.json theme={null} { "name": "acme-internal", "owner": { "name": "Acme IT" }, "plugins": [ { "name": "expense-policy", "installationPreference": "auto_install", "source": { "source": "archive", "url": "https://plugins.acme.example.com/claude/expense-policy-1.3.0.zip", "sha256": "9f2c04d1...b8e7" } } ] } ``` Each plugin marked this way still needs a `sha256` on its archive. Claude Desktop re-fetches the manifest periodically and picks up a newly published version without a configuration change or an app relaunch. A plugin the user removes stays removed. Claude Desktop honors these per-plugin marks only when the manifest is served from your inference gateway's or bootstrap server's own origin, because those hosts already carry your deployment's configuration and credentials. On any other origin the marks are ignored, and the marketplace behaves as `"available"`. Entry-level `"auto_install"` and `"required"` continue to require the [admin-side content pin](#marketplace-installation-preferences) on every origin. ### Marketplace credentials Claude Desktop fetches marketplaces on the host operating system, outside the Cowork VM. The credential is used only for this fetch and is never passed into the VM or exposed to the model. | `credentialKind` | How it authenticates | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"anonymous"` | No credential is sent. Use for public repositories or unauthenticated file hosts. | | `"userGit"` | Uses the git credential helpers already configured for the signed-in OS user (for example, `git-credential-manager`, macOS Keychain, or a GitHub CLI credential helper). Use when each user already has read access through their own account. For `url` sources, the same credential is sent as HTTP Basic on the manifest and archive requests. | | `"credentialHelper"` | Runs the executable at `credentialHelper`. If it prints a bare token, the token is used as the git password for username `x-access-token` (accepted by GitHub, GitLab, and Azure DevOps) and, for `url` sources, sent as `Authorization: Bearer ` on the manifest and archive requests. For hosts that need a particular username, print git-credential lines `username=` and `password=` instead (for example `x-token-auth` for Bitbucket Data Center access tokens, or `gitlab+deploy-token-N` for a GitLab deploy token); `url` sources then use HTTP Basic. Print `authtype=Bearer` and `credential=` to force a bearer header. Unlike an inference credential helper, it does not accept JSON output. Username forms require Claude Desktop 1.37937.0 or later. Otherwise follows the execution model of an [inference credential helper](/docs/third-party/claude-desktop/credential-helper). | | `"inferenceCredential"` | `url` sources only. Sends the credentials Claude Desktop already sends to your inference gateway or to your [bootstrap server](/docs/third-party/claude-desktop/bootstrap), so a marketplace hosted on either is private to signed-in members without a separate credential. On the gateway's origin it sends the same `Authorization` bearer as inference and works for [gateway single sign-on](/docs/third-party/claude-desktop/gateway#single-sign-on-with-your-identity-provider), a [credential helper](/docs/third-party/claude-desktop/credential-helper), and bearer-scheme API keys. On the bootstrap server's origin (Claude Desktop 1.37937.0 or later) it sends the bootstrap sign-in token or your `bootstrapHeaders` and `bootstrapHeadersHelper` headers. Claude Desktop sends a credential only when the marketplace URL is on one of those two origins. When there is nothing to send yet (no sign-in held and no bootstrap headers configured, or a gateway API key sent as `x-api-key` rather than a bearer), no request is made and the entry reports why in the diagnostic report. | Because the fetch happens on the host, the marketplace host does not need to be on the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) allowlist. It does need to be reachable from end-user devices. ### Roll out marketplace updates For a git marketplace, commit the change to the repository, update the `ref` in `allowedPluginMarketplaces` to the new commit SHA, and distribute the updated managed configuration. For a `url` marketplace with a `manifestSha256` pin, publish the new archive, update its `url` and `sha256` in `marketplace.json`, and update `manifestSha256` in configuration to the new file's digest. For a `url` marketplace using [per-plugin auto-install from a trusted origin](#per-plugin-auto-install-from-a-trusted-origin), publish the new `marketplace.json` and no configuration change is needed. Devices sync to the new revision on the next app launch or periodic re-fetch. To remove a marketplace, delete its entry; Claude Desktop unregisters it and uninstalls its plugins on the next sync. ## Organization plugins (admin) For most deployments, distribute organization plugins via a [plugin marketplace](#plugin-marketplaces-admin) instead. Marketplaces let you manage plugin content in git or on any HTTPS file host and roll out updates by changing a single configuration value, rather than pushing files to every device. Use the directory path below when end-user devices cannot reach a git server or an HTTPS file host. [Plugins](/docs/plugins/overview) bundle MCP connectors, skills, slash commands, hooks, and sub-agents into a single directory. On this path, admins distribute plugins by placing them in a system-wide directory on each device, typically via the same MDM or software-distribution channel used for the app itself. Plugins distributed this way are available in Cowork sessions and Chat conversations. Code sessions do not load their skills, commands, sub-agents, or hooks, so a plugin that must reach Code sessions has to be distributed through a [plugin marketplace](#plugin-marketplaces-admin) instead. ### Plugin directory location | Platform | Path | | -------- | -------------------------------------------------- | | macOS | `/Library/Application Support/Claude/org-plugins/` | | Windows | `C:\Program Files\Claude\org-plugins\` | On Windows, the directory is under `Program Files` (not `ProgramData`) so that only administrators can create or modify it. Claude Desktop treats the presence of this directory as an admin-provisioned source. ### Plugin structure Each subdirectory of `org-plugins/` is one plugin. The directory name is the plugin's canonical name. ```text theme={null} org-plugins/ └── code-reviewer/ ├── .claude-plugin/ │ └── plugin.json ├── version.json ├── .mcp.json ├── agents/ │ └── code-reviewer.md ├── commands/ │ └── find-all-bugs.md └── skills/ └── security-review/ └── SKILL.md ``` | File | Purpose | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.claude-plugin/plugin.json` | **Required.** Plugin manifest (name, description, version). Directories without this file are ignored. | | `version.json` | `{"version": "1.2.3"}`. When this string changes, Claude Desktop re-syncs the plugin on next launch. Any string change triggers re-sync (there's no semver ordering, so a downgrade is just another version string). If absent, the directory's modification time is used instead. | | `.mcp.json` | MCP servers bundled with this plugin. A JSON object keyed by server name: `{"mcpServers": {"": {"type": "http", "url": "...", "oauth": true}}}`. A remote entry uses `type` (`http` or `sse`), not `transport`, and supports `url`, `headers`, and `oauth` only. `toolPolicy`, `headersHelper`, and `headersHelperTtlSec` are not read from this file. A local entry gives a `command` with optional `args` and `env` (`type` is `"stdio"` or omitted). Give `command` as a program name on `PATH` or an absolute path, using `${CLAUDE_PLUGIN_ROOT}` for the plugin's directory under `org-plugins/`. Claude Desktop starts these local servers itself, including when [`isLocalDevMcpEnabled`](/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled) is `false`. Local entries require Claude Desktop 1.49585.0 or later. A local entry that references `${user_config.}` is skipped, because per-user plugin settings are not available to organization plugins. The diagnostic report's **MCP servers** section lists each server, with the reason for any it skipped. | | `agents/` | Sub-agent definitions. | | `commands/` | Slash-command definitions. | | `skills/` | [Skill](/docs/skills/overview) directories. | | `hooks/` | Hook definitions that run on agent lifecycle events. See [Plugin hooks](#plugin-hooks) for where they run. | Each entry in `org-plugins/` must carry a valid manifest: a `.claude-plugin/plugin.json`, or a top-level `SKILL.md` for an entry that distributes a single skill. A directory with neither is not loaded and never appears in the user's plugin browser; the diagnostic report's plugin section shows the rejected entry and why. To distribute an MCP connector, declare it in a plugin's `.mcp.json` or use [`managedMcpServers`](#managed-mcp-servers-admin). See the [plugins reference](https://code.claude.com/docs/en/plugins) for the full file format of each component, including the hooks schema. Symlinks inside a plugin are followed as long as the target resolves to a path inside the plugin directory. Symlinks that point outside the plugin (for example, `skills/foo/SKILL.md → /etc/hosts`) are skipped. A symlinked top-level plugin directory (for example, `org-plugins/my-plugin → /opt/shared/my-plugin`) is also followed. MCP servers declared in a plugin's `.mcp.json` don't carry a `toolPolicy` field in the plugin file itself. To lock tools on a plugin-delivered server, set [`orgPluginSettings`](/docs/third-party/claude-desktop/configuration#orgpluginsettings) in managed configuration, keyed on the server's `name`. ### Auto-installing organization plugins By default, organization plugins appear in the user's plugin browser as available to install, and each user opts in. To install a plugin automatically for every user, set `installationPreference` in the plugin's `.claude-plugin/plugin.json`: ```json theme={null} { "name": "code-reviewer", "version": "1.0.0", "description": "Internal code review assistant", "installationPreference": "required" } ``` | Value | Behavior | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `"required"` | Installs automatically when the user signs in. The Uninstall action is hidden. If the plugin is removed from disk, it reinstalls on the next sign-in. | | `"auto_install"` | Installs automatically when the user signs in. Users can uninstall it, and it stays uninstalled for that user. | | `"available"` (or omitted) | Default. Users install manually from the plugin browser. | This mirrors the installation preference behavior of remote-managed plugins on claude.ai. Changing a plugin's `installationPreference` takes effect the next time each user signs in. ### Updating organization plugins To roll out a new version of a plugin: 1. Update the plugin contents in `org-plugins//` via your software-distribution tool 2. Bump the `version` string in `version.json` 3. Users pick up the change on their next app launch To withdraw a plugin, remove its folder from `org-plugins/`. On Claude Desktop 1.46388.1 or later, each user's installed copy is unregistered the next time the app syncs organization plugins (at launch or when a session starts); earlier versions leave the copy installed. ## Plugin hooks [Hooks](https://code.claude.com/docs/en/hooks) bundled in a plugin, under `hooks/` or declared in its manifest, run wherever the plugin itself loads: * **Cowork sessions** run hooks from marketplace plugins, from plugins in the `org-plugins/` directory, and from plugins users add themselves. * **Code sessions** run hooks from marketplace plugins (Claude Desktop 1.32352.0 or later) and from plugins the user installed for Claude Code. Hooks from plugins in the `org-plugins/` directory do not run in Code sessions. In [remote SSH sessions](/docs/third-party/claude-desktop/ssh-remote-sessions#managed-configuration-on-the-remote-host), hooks from the plugins Claude Desktop copies to the host do not run. * **Chat conversations** run hooks from the same plugins as Cowork sessions, on Claude Desktop 1.52386.0 or later. A `UserPromptSubmit` hook that blocks a prompt stops that turn and shows the hook's reason to the user. When a conversation or session is created, Claude Desktop also sends its first message to your inference provider in a separate request, without tools, to generate the title shown in the sidebar. That request does not pass through plugin hooks, so a first message that a hook blocks still reaches your provider for titling. Claude Code [managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) deployed on the device govern these hooks as they do in the Claude Code CLI: `disableAllHooks` turns them off, and `allowManagedHooksOnly` keeps only the hooks those managed settings define. ## User extensions Unless restricted by an admin, end users can add their own extensions through the in-app UI: * **Plugins:** install plugins (which can bundle skills, hooks, slash commands, and sub-agents) from the Plugins settings page * **Skills:** create and upload their own [skills](/docs/skills/overview), including by asking Claude to save one in a conversation * **Local MCP servers:** add local MCP server processes from **Settings → Developer** End users cannot add remote MCP servers or install desktop extension files (`.mcpb`) themselves. Remote servers are available only via admin-provisioned `managedMcpServers` or organization plugins. User-added extensions are stored in the user's [local data directory](/docs/third-party/claude-desktop/data-storage) and apply only to that device. ## Controlling user extensions Admins can restrict or disable each user-extension surface independently via managed configuration: | Key | Default | Effect when `false` | | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isLocalDevMcpEnabled` | `true` | Users cannot add their own local MCP servers from **Settings → Developer**. | | `isDesktopExtensionEnabled` | `false` | Desktop extensions (`.mcpb`) bundled in plugins are not loaded. Set to `true` to allow them. | | `isDesktopExtensionSignatureRequired` | `false` | (When `true`) Unsigned `.mcpb` extensions are rejected. | | `skillCreationEnabled` | `true` | Users cannot create or upload skills in the app. Claude does not offer to create or update skills in conversations. | | `userPluginMarketplacesEnabled` | `true` | Users cannot add plugin marketplaces of their own; the add-marketplace options are hidden. Marketplaces you provision with `allowedPluginMarketplaces` are unaffected. Requires Claude Desktop 1.37937.0 or later. | | `userPluginUploadsEnabled` | `true` | Users cannot upload plugin files or create plugins with Claude; every in-app option for adding a plugin of their own is hidden. Plugins from your marketplaces and the organization plugins directory are unaffected. Requires Claude Desktop 1.37937.0 or later. | Setting `isLocalDevMcpEnabled` to `false` and leaving `isDesktopExtensionEnabled` at `false` restricts MCP servers and connectors to those delivered through `managedMcpServers` and `org-plugins/`. Setting [`skillCreationEnabled`](/docs/third-party/claude-desktop/configuration#skillcreationenabled) to `false` turns off skill creation and upload in the app. Skills already on the device keep working, as do skills from [organization plugins](#organization-plugins-admin). Users can still install plugins from the marketplaces you provision regardless of these settings. Setting `userPluginMarketplacesEnabled` and `userPluginUploadsEnabled` to `false` removes only the options for adding marketplaces and plugins of their own, and anything a user added earlier stays in place. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete example. ## Related topics How extensions and managed settings reach the embedded Claude Code engine. Configure MCP servers for the standalone Claude Code CLI. Plugin structure, marketplaces, and management for Claude Code. Restrict which MCP servers Claude Code users can add. # Features Source: https://claude.com/docs/third-party/claude-desktop/feature-matrix Feature comparison between Claude Enterprise and Claude Desktop on third-party (3P) The tables below compare the feature set of Claude Desktop on third-party (3P) to Claude Enterprise. ## Key differences **Configuration.** Both are administered from the web-based [admin console](/docs/third-party/claude-desktop/admin-console) in **Organization settings** on claude.ai. Claude Desktop on 3P can also be configured through [MDM](/docs/third-party/claude-desktop/mdm) (Jamf, Intune, Group Policy) or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap). **Telemetry.** Claude Desktop on 3P sends usage and debugging metrics only, and these can be fully disabled via managed configuration. Claude Enterprise does not offer telemetry toggles. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry). **Inference.** Claude Desktop on 3P routes all inference through the provider you configure, and data handling at the inference endpoint depends on that provider. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by Google Cloud and Amazon Bedrock respectively. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page for each provider's data path. **Pricing.** Claude Desktop on 3P is token-based consumption billed by your cloud provider, with no seat licensing. **Features not available in 3P.** Features marked with — are absent from the UI. Users see a clean interface without error states for unavailable features. ## User features | Feature | Claude Enterprise | Claude Desktop on 3P | | --------------------------------------------------------------------------------------------------------------------------------------------- | :---------------: | :------------------: | | Chat | ✓ | ✓ | | Cowork | ✓ | ✓ | | Code | ✓ | ✓ | | Auto mode (Code) | ✓ | ✓ | | [SSH remote Code sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) | ✓ | ✓ | | Automatically approve / Skip all approvals (Cowork) | — ¶ | ✓ | | Projects | ✓ | ✓ | | Code execution for analysis | ✓ | ✓ | | Web search | ✓ | ✓ § | | File access, upload, and export | ✓ | ✓ | | Local MCP | ✓ | ✓ | | Remote MCP | ✓ | ✓ | | [Microsoft 365](/docs/third-party/claude-desktop/connectors-m365) and [GitHub](/docs/third-party/claude-desktop/connectors-github) connectors | ✓ | ✓ | | Skills, plugins, and hooks | ✓ | ✓ | | Artifacts | ✓ | ✓ | | Memory | ✓ | ✓ † | | Scheduled tasks | ✓ | ✓ | | Global languages | ✓ | ✓ | | Project and plugin sharing | ✓ | — | | Plugin marketplaces | ✓ | ✓ | | Mobile | ✓ | — | | claude.ai web-based access | ✓ | — | | Voice mode | ✓ | — | | Claude in Chrome | ✓ | — | | Claude Design | ✓ | — | | Claude Security | ✓ | — | | Claude Tag | ✓ | — | | Computer use | — | — | § Amazon Bedrock deployments and gateways that do not forward Anthropic server tools need a web search provider configured first; see [Web search options](/docs/third-party/claude-desktop/web-tools#web-search-options). † Memory in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Users can review, delete, or pause it under **Settings → Cowork → Memory**; see [Memory](/docs/third-party/claude-desktop/data-storage#memory). Chat-history search and nightly summary generation are not available in Chat on 3P. ¶ Cowork's Automatically approve and Skip all approvals modes are not available for Claude Enterprise organizations. ## Admin features | Feature | Claude Enterprise | Claude Desktop on 3P | | -------------------------------------------------------------------------------------------------- | :---------------: | :------------------: | | Endpoint / gateway configuration | — | ✓ | | Skills, hooks, and plugins distribution | ✓ | ✓ | | MCP server allowlist | ✓ | ✓ | | Feature toggles (web search, local MCP, etc.) | ✓ | ✓ | | Auto-updates | ✓ | ✓ | | Per-user usage caps | ✓ | ✓ | | [Data retention policies](/docs/third-party/claude-desktop/configuration#chatsessionretentiondays) | ✓ | ✓ | | Compliance API | ✓ | — ‡ | | Analytics API | ✓ | — ‡ | | OpenTelemetry export | ✓ | ✓ | | User management via UI | ✓ | ✓ ◊ | | RBAC | ✓ | ✓ ◊ | ‡ Many of these capabilities can be achieved via OpenTelemetry export to your own collector. See [Monitoring](/docs/cowork/monitoring). ◊ With the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), administrators add users and groups, connect single sign-on and SCIM, assign administrator roles, and set per-group permission policies from **Organization settings** on claude.ai. Deployments configured through MDM or a bootstrap server manage access through those channels. # Deploy Claude Desktop on 3P with Microsoft Foundry Source: https://claude.com/docs/third-party/claude-desktop/foundry Set up Microsoft Foundry, choose an authentication path for your organization, and configure Claude Desktop on 3P to use Claude models on Microsoft Foundry This page walks an IT administrator through a Microsoft Foundry deployment: creating the Microsoft Foundry resource, choosing the authentication path that fits your organization, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app). Microsoft Foundry offers Claude models in two hosting options, Hosted on Azure and Hosted on Anthropic, and you choose one when you configure the model deployment in Microsoft Foundry. Under both options, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. Your use of Claude through Microsoft Foundry is subject to Anthropic's data use terms. Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details. ## Choose an authentication approach | Scenario | Use | Per-user identity | Notes | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Proof of concept, single team | [API key](#api-key) (`inferenceFoundryApiKey`) | No (shared key) | A long-lived secret distributed in the managed profile. Simplest to start. | | Broad rollout with per-user identity | [In-app Entra ID sign-in](#in-app-entra-id-sign-in) (`inferenceFoundryTenantId`, `inferenceFoundryClientId`, `inferenceFoundryAuthFlow`) | Yes | Users sign in with their Entra ID account inside the app, through a device code, the system browser, or the OS identity broker. The device-code flow requires app version 1.9255.0 or later; the browser flow requires app version 1.19367.0 or later. | | Your organization already has tooling that obtains a Microsoft Foundry credential | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | Depends on what the helper obtains | An executable that prints the credential to stdout at runtime. | ## Set up Azure These steps are performed once per Azure subscription. You need permission to create resources and, for in-app sign-in, to register an application in Microsoft Entra ID. In the Azure portal, create a Microsoft Foundry resource in your subscription. Record the **resource name**; the app constructs the endpoint as `.services.ai.azure.com`. If the app should reach Microsoft Foundry through a gateway or proxy you operate instead, see [Route requests through a gateway](#route-requests-through-a-gateway). The resource name is still required in that case. In the Microsoft Foundry portal for your resource, deploy the Claude models you intend to serve. Record each **deployment name**; you will list these in `inferenceModels`. If you chose the API-key approach, copy one of the resource's keys from the Azure portal. You will place it in the managed configuration in [Configure the app](#configure-the-app). If you chose in-app Entra ID sign-in, register an application in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Identity → Applications → App registrations → New registration**. On the registration: * Under **API permissions**, select **Add a permission**, find **Azure Cognitive Services** in the API picker, and add the **Delegated** permission **user\_impersonation** so the issued token is accepted by your Microsoft Foundry resource. (The app requests this permission as the scope `https://cognitiveservices.azure.com/.default`.) All three sign-in flows need it. After adding the permission, select **Grant admin consent**; in tenants that disable user consent, sign-in fails with error code `AADSTS65001` until consent is granted. * Under **Authentication**, complete the setup for the sign-in flow you plan to use (see [In-app Entra ID sign-in](#in-app-entra-id-sign-in) for how the flows differ): * For the device-code flow (the default), enable **Allow public client flows**. Entra ID rejects device-code sign-in without it. * For the browser flow (`inferenceFoundryAuthFlow` set to `browser`), select **Add a platform → Mobile and desktop applications** and add the redirect URI `http://127.0.0.1/callback`. Use the literal address `127.0.0.1`, not `localhost`: Entra ID matches the scheme, host, and path exactly and ignores only the port. The browser flow completes sign-in without **Allow public client flows**. Conditional Access policies that block the device-code authentication flow do not apply to the browser flow. * For the broker flow (`inferenceFoundryAuthFlow` set to `broker`), enable **Allow public client flows** and add the platform's broker redirect URI under **Mobile and desktop applications**. See [Register the Entra ID application](/docs/third-party/claude-desktop/entra-broker#register-the-entra-id-application) on the OS identity broker page for the redirect URI values and why the public-client setting is required. Record the **Directory (tenant) ID** and **Application (client) ID**. Grant the users or groups who will sign in a role on the Microsoft Foundry resource that permits inference (for example, **Cognitive Services User**). ## Prepare devices What each end-user device needs depends on the authentication approach you chose. ### API key No per-device preparation is required. Place the resource's API key in the managed configuration as `inferenceFoundryApiKey`. ### In-app Entra ID sign-in Distribute `inferenceFoundryTenantId` and `inferenceFoundryClientId` in the managed configuration. To use the browser or broker flow instead of the default device-code flow, also set `inferenceFoundryAuthFlow` to `browser` or `broker`. The device-code and browser flows need no per-device preparation. The broker flow signs in through the operating system's native Microsoft identity broker, so each device must meet the platform requirements on the [OS identity broker](/docs/third-party/claude-desktop/entra-broker#prepare-devices) page. When the tenant and client IDs are set and `inferenceCredentialKind` is `interactive`, the app shows a **Sign in with Microsoft** page at first launch. Clicking the button starts a sign-in against `login.microsoftonline.com`; what the user sees depends on `inferenceFoundryAuthFlow`: * **Device code** (the key is unset or `device-code`): the app displays a short verification code and opens the Microsoft sign-in page in the default browser, where the user enters the code and approves access. * **Browser** (the key is `browser`): the app opens the Microsoft sign-in page in the default browser, where the user signs in and approves access. The browser shows a confirmation page and the user switches back to the app; there is no code to enter. * **Broker** (the key is `broker`): the app opens the operating system's native Microsoft account picker, where the user selects or signs in to a work account. The dialog closes and the app returns to Cowork; nothing opens in the browser. Because the broker issues the token, sign-in satisfies Conditional Access policies that require a compliant or managed device or token protection, which the other two flows cannot satisfy on their own. See [Sign in through the OS identity broker](/docs/third-party/claude-desktop/entra-broker) for what the broker is and when to choose it. On success, the app returns to Cowork. For the device-code and browser flows the app stores the refresh token encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows), and both flows store the same token against the same app registration, so switching between them later does not itself prompt users to sign in again. For the broker flow the operating system's broker holds the credential, and the app stores only a reference to the signed-in account. If the app can no longer renew the credential silently, it shows a **Sign in again** prompt; clicking it reopens the configured sign-in flow. For the device-code and browser flows this happens when the stored refresh token expires or is revoked. For the broker flow it happens when the broker can no longer renew the token silently. `inferenceFoundryTenantId`, `inferenceFoundryClientId`, and `inferenceFoundryAuthFlow` can be set through an MDM profile or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap). When a bootstrap server delivers `inferenceFoundryTenantId` or `inferenceFoundryClientId`, the values are among the [keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent), so users may see a one-time approval dialog depending on how `bootstrapUrl` reached the device. In-app sign-in and a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) are separate layers that work together. In-app sign-in supplies each user's inference credential, the Entra ID token that authorizes model calls. A bootstrap server supplies per-user configuration values when the app starts. A bootstrap server does not replace sign-in: a deployment with a bootstrap server still needs each user to sign in, and signing in does not deliver configuration. #### Allow network egress The sign-in flow reaches `login.microsoftonline.com` in addition to your Microsoft Foundry endpoint. Both hosts are included automatically in the **Egress** section of the in-app configuration window when these keys are set. When you [route requests through a gateway](#route-requests-through-a-gateway), the gateway's host replaces the resource host there. ### Route requests through a gateway To send Microsoft Foundry traffic through a gateway or proxy you operate, such as Azure API Management in front of the resource, set `inferenceFoundryBaseUrl` (**Azure AI Foundry base URL**) to the gateway's base URL including any path, for example `https://llm-gateway.example.com/foundry`. It replaces the default `https://.services.ai.azure.com/anthropic` endpoint in Chat, Cowork, and Code, and it takes the same value as Claude Code's `ANTHROPIC_FOUNDRY_BASE_URL`, so one value serves both. `inferenceFoundryResource` is still required. The value must use `https`; from an MDM profile or the local configuration file it may instead be `http` for a proxy listening on the device's own loopback address (a bootstrap server response cannot deliver a loopback value). The app sends the gateway the same credential it would send Microsoft Foundry: the API key, the credential helper's output, or with in-app sign-in each user's Entra ID token issued for the Azure Cognitive Services audience. A gateway that validates tokens must therefore accept that audience. If you want users to sign in against your own API's app registration instead, for example to map app roles to gateway policy, use the [gateway provider](/docs/third-party/claude-desktop/gateway) with its Entra ID sign-in rather than the Microsoft Foundry provider. This key works from an MDM profile, the local configuration file, and a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), where it is one of the [keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent). The Claude add-in for Microsoft 365 does not apply it yet and keeps calling the resource endpoint directly; if the add-in must also go through your gateway, configure the add-in's own gateway mode. ## Configure the app Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Foundry**, then fill in the **Foundry credentials** card with the values for whichever authentication approach you chose: | Field | API key | In-app Entra ID sign-in | | ------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Azure AI Foundry resource name | `your-foundry-resource` | `your-foundry-resource` | | Azure AI Foundry API key | your resource key | *leave empty* | | Entra ID tenant ID | *leave empty* | `00000000-0000-0000-0000-000000000000` | | Entra ID client ID | *leave empty* | `11111111-1111-1111-1111-111111111111` | | Entra ID sign-in flow | *leave empty* | `browser` or `broker`, or leave empty for the default device-code flow | | Azure AI Foundry base URL | *optional*, see [Route requests through a gateway](#route-requests-through-a-gateway) | *optional* | Under **Models**, add at least one **Model list** entry using the Microsoft Foundry deployment name. Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. ### Configuration keys The full set of `inferenceFoundry*` keys is below. Set `inferenceProvider` to `foundry`, supply the resource name, and provide exactly one credential source. | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------------- | -------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Azure AI Foundry resource name
`inferenceFoundryResource` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Azure AI Foundry resource name used to construct the endpoint URL. | | Azure AI Foundry base URL
`inferenceFoundryBaseUrl` | `string` | MDM + Bootstrap
Added in 2.110.0 | — | Full base URL for a gateway or proxy in front of Foundry, path included (replaces [https://RESOURCE.services.ai.azure.com/anthropic](https://RESOURCE.services.ai.azure.com/anthropic)). | | Azure AI Foundry API key
`inferenceFoundryApiKey` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | API key for Azure AI Foundry inference. | | Entra ID tenant ID
`inferenceFoundryTenantId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. | | Entra ID client ID
`inferenceFoundryClientId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. | | Entra ID sign-in flow
`inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.19367.0 | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. | Set this only when the app reaches Foundry through a gateway or proxy you run, such as Azure API Management. Requests go to `/v1/messages` instead of `https://.services.ai.azure.com/anthropic/v1/messages`, carrying the same credential and headers the app would send to Foundry: each user's Entra ID token for the Azure Cognitive Services audience as `Authorization: Bearer` with Entra sign-in, otherwise the API key or the credential helper's output. Claude Code sessions receive the value as `ANTHROPIC_FOUNDRY_BASE_URL`, so use the same value you would give Claude Code in a terminal. `inferenceFoundryResource` is still required and should name the resource behind the gateway; the app sends nothing to the resource directly while this is set. Must be https, or http to a proxy at a loopback address on the device itself (127.0.0.1, localhost or \[::1]). * **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled. * **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code. You must also set `inferenceModels` to a list of Microsoft Foundry deployment names. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels). ## What users experience | Approach | First launch | Re-authentication | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | API key | The app opens directly; no user action. | Never, until you rotate the key in the managed profile. | | In-app Entra ID sign-in, device-code flow | The app shows a **Sign in with Microsoft** page; the user approves a device code in the browser, and the app returns to Cowork. | When the stored refresh token expires or is revoked under your tenant's policy. The app prompts in-app. | | In-app Entra ID sign-in, browser flow | The app shows a **Sign in with Microsoft** page; the user signs in through the system browser, with no code to enter, and the app returns to Cowork. | When the app can no longer renew the stored token. The app prompts in-app. | | In-app Entra ID sign-in, broker flow | The app shows a **Sign in with Microsoft** page; the user picks or signs in to a work account in the operating system's native account picker, and the app returns to Cowork. | When the broker can no longer renew the token silently. The app prompts in-app. | ## Troubleshoot To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage). If sign-in fails at the token step, confirm the **Azure Cognitive Services** permission is granted and consented on the app registration. For the device-code flow, also confirm **Allow public client flows** is enabled; Entra ID rejects device-code sign-in without it. If sign-in fails with error code `AADSTS650057`, the **user\_impersonation** permission is missing from the app registration. Add it under **API permissions**. If sign-in fails with error code `AADSTS65001`, the permission has not been consented. Select **Grant admin consent** on the **API permissions** page, or have the user accept the consent prompt if your tenant allows user consent. If browser-flow sign-in fails in the browser with error code `AADSTS50011`, the redirect URI is missing from the app registration or does not match. Add `http://127.0.0.1/callback` under **Authentication → Mobile and desktop applications**, using the literal address `127.0.0.1`, not `localhost`. If the browser shows the confirmation page but in-app sign-in still fails, with error code `AADSTS7000218` in the application logs, the redirect URI is registered under the **Web** platform. Move it under **Mobile and desktop applications**. For broker-flow sign-in failures (error codes `AADSTS50011`, `AADSTS900971`, `AADSTS7000218`, or a message that the OS identity broker is unavailable), see [Troubleshoot](/docs/third-party/claude-desktop/entra-broker#troubleshoot) on the OS identity broker page. To unblock a device that cannot meet the broker requirements, set `inferenceFoundryAuthFlow` to `browser` for that device instead. Each sign-in attempt has a time limit: five minutes for the device-code and broker flows and two minutes for the browser flow. If the user does not finish within the limit, the attempt fails and the user can click **Sign in with Microsoft** to start again. # Deploy Claude Desktop on 3P with an LLM gateway Source: https://claude.com/docs/third-party/claude-desktop/gateway Configure Claude Desktop on 3P to use Claude models on a self-hosted gateway that implements the Anthropic Messages API To use a self-hosted LLM gateway (for example LiteLLM, Portkey, or an in-house proxy) as the inference provider, set `inferenceProvider` to `gateway` and supply the base URL and credentials described below. The gateway must implement the Anthropic [Messages API](https://docs.claude.com/en/api/messages): * `POST /v1/messages` with [streaming](https://docs.claude.com/en/api/streaming) and [tool use](https://docs.claude.com/en/docs/tool-use) is required. * `GET /v1/models` is optional. If the gateway implements it, Claude Desktop on 3P auto-discovers available models; if not, set `inferenceModels` explicitly. The gateway should also preserve [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Cowork and Code sessions send `cache_control` breakpoints with each turn so that the provider can reuse the tool definitions, system prompt, and earlier turns of the conversation instead of reprocessing them. A gateway that forwards these fields, or translates them for its upstream provider, keeps that behavior. A gateway that strips `cache_control`, or that changes the system prompt or tool list from one request to the next, makes the provider reprocess the whole conversation on every turn at full input-token cost and higher latency. To verify, check the [usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) your gateway returns or logs for Claude Desktop traffic: after the first request of a session, `cache_read_input_tokens` should be well above zero on most requests. If it is zero on every request, review the gateway's request transformation and caching settings for the route that serves Claude models. ## Choose an authentication approach | Scenario | Use | Notes | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Proof of concept, or your gateway already issues per-team keys | [Static API key](#static-api-key) (`inferenceGatewayApiKey`) | A long-lived secret distributed in the managed profile. | | Per-user attribution and identity-provider enforcement (MFA, conditional access) | [Single sign-on](#single-sign-on-with-your-identity-provider) (`inferenceGatewayOidc`) | Each user signs in with their own work account. Requires app version 1.6889.0 or later. | | Your organization already has tooling that obtains a gateway credential | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the gateway credential to stdout at runtime. | ## Prepare devices ### Static API key No per-device preparation is required. Generate an API key in your gateway and place it in the managed configuration as `inferenceGatewayApiKey` (see [Configure the app](#configure-the-app)). ### Single sign-on with your identity provider Instead of distributing a shared gateway API key, you can have each user sign in with their own work account. The first time a user opens Claude Desktop, the app opens their browser to your organization's normal sign-in page (Microsoft Entra ID, Okta, or any OpenID Connect provider). After they sign in, the app sends a per-user token to your gateway on every request, and your gateway checks that token to confirm who the user is. This gives you per-user attribution in your gateway logs, lets your identity provider enforce MFA and conditional access, and means there is no long-lived credential to distribute or rotate. You need three things in place: * An LLM gateway that can validate JSON Web Tokens (LiteLLM, Kong, Envoy, and Azure API Management all support this) * Admin access to your identity provider to register a new application * A way to push managed configuration to user devices (your existing MDM) The walkthrough below uses Microsoft Entra ID. An Okta variant follows. #### Set up single sign-on In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → App registrations** and select **New registration**. Give it a name such as `Claude Desktop gateway`, choose **Accounts in this organizational directory only**, and select **Register**. On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You will use both in the next two steps. Open the **Authentication** blade, select **Add a platform**, and choose **Mobile and desktop applications**. Under **Custom redirect URIs**, add exactly: ```text theme={null} http://127.0.0.1/callback ``` A few details that matter here: use `127.0.0.1` (not `localhost`), include the `/callback` path, and add it under the **Mobile and desktop applications** platform specifically. That platform is the only one Entra allows to use any local port, which the app needs because it picks a free port at sign-in time. You do not need a client secret or any additional API permissions. Tell your gateway to accept the bearer token only if it was issued by your tenant **for this application**. In LiteLLM that looks like: ```yaml theme={null} general_settings: litellm_jwtauth: public_key_url: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys audience: YOUR_CLIENT_ID user_id_jwt_field: oid ``` Replace `YOUR_TENANT_ID` and `YOUR_CLIENT_ID` with the values from step 1. The `audience` line is required. Without it, your gateway accepts tokens issued to any application in your tenant, not just this one. For Kong, Envoy, or Azure API Management, configure the equivalent JWT validation policy with the same JWKS URL and audience. Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway** and **Credential kind** to **Interactive sign-in**. This hides the API-key field and reveals **Gateway SSO IdP (OIDC)**: | Field | Value | | -------------------------------------- | ------------------------------------------------------- | | Gateway base URL | `https://llm-gateway.example.corp` | | Credential kind | **Interactive sign-in** | | Gateway SSO IdP (OIDC) → Client ID | `YOUR_CLIENT_ID` | | Gateway SSO IdP (OIDC) → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` | | Gateway SSO IdP (OIDC) → Scopes | *leave empty for the default* | | Gateway SSO IdP (OIDC) → Redirect port | *leave empty* | Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. When a user next opens Claude Desktop, they see a **Sign in to your organization** button. Clicking it opens their browser to your Entra sign-in page; once they approve, they return to the app and can start working. The app keeps them signed in and refreshes the token in the background. If the session is revoked or expires under your tenant's policy, the app shows a **Sign in again** prompt; clicking it reopens the sign-in page in the browser. #### Using Okta instead In the Okta Admin Console, create a **Native** application with the **Authorization Code** and **Refresh Token** grant types. Okta requires the redirect URI to match exactly, including the port, so pick a fixed port (for example `53180`), register `http://127.0.0.1:53180/callback`, and set that same port in **Gateway SSO IdP (OIDC)**: | Field | Value | | ------------- | ----------------------------- | | Client ID | `YOUR_CLIENT_ID` | | Issuer URL | `https://YOUR_ORG.okta.com` | | Scopes | *leave empty for the default* | | Redirect port | `53180` | Use the **issuer** value, not the **Metadata URI**. Okta's admin console shows the metadata URI (ending in `/.well-known/openid-configuration`) prominently — that is the discovery document the app fetches *from* the issuer, not the issuer itself. If you are unsure, open the metadata URI in a browser and copy the `"issuer"` field from the JSON response. For a custom Okta authorization server the issuer is `https://YOUR_ORG.okta.com/oauth2/AUTH_SERVER_ID`. Point your gateway's JWT validation at `https://YOUR_ORG.okta.com/oauth2/v1/keys` with `audience` set to the Okta client ID. #### Map users at the gateway Claude Desktop forwards the identity provider's token to your gateway verbatim — it does not add, remove, or rewrite any claims. With the default scopes (`openid profile email offline_access`), the ID token your gateway receives contains the standard OIDC `sub`, `email`, and `name` claims, plus whatever your provider includes for the `profile` scope. You can confirm exactly what is present by base64-decoding the middle segment of the `Authorization: Bearer` value your gateway receives. Key the gateway's user record on the provider's immutable user ID rather than email, so the record survives email or name changes: | Provider | Stable user-ID claim | | ---------------------------------- | -------------------- | | Entra ID | `oid` | | Okta and most other OIDC providers | `sub` | If your gateway has no existing user records to preserve, the simplest setup is to auto-provision on first sign-in. For LiteLLM, extend the validation block from step 2: ```yaml theme={null} general_settings: enable_jwt_auth: true litellm_jwtauth: public_key_url: https://YOUR_ORG.okta.com/oauth2/v1/keys audience: YOUR_CLIENT_ID user_id_jwt_field: sub # use "oid" for Entra ID user_email_jwt_field: email user_id_upsert: true ``` If you need additional claims (for example, a `groups` claim for team-level budgets), add them on your identity provider's authorization server — they pass through to the gateway unchanged. To request a non-default scope, set `scopes` in `inferenceGatewayOidc` (see [Single sign-on configuration keys](#single-sign-on-configuration-keys)). #### Refresh tokens and session lifetime Silent token refresh requires a refresh token from your identity provider, which in turn requires the `offline_access` scope on the authorization request. Whether Claude Desktop sends that scope depends on how you set `scopes` and `bearerTokenType`: * **`scopes` left unset** — the default (`openid profile email offline_access`) includes `offline_access`, so a refresh token is issued. * **`bearerTokenType: "access_token"`** — Claude Desktop automatically appends `offline_access` to whatever `scopes` value you supply, unless `appendOfflineAccess` is set to `false`. * **`bearerTokenType: "id_token"` (the default) with `scopes` set explicitly** — Claude Desktop does **not** add `offline_access` for you. Include it in your `scopes` value if you want silent refresh; without it, users are prompted to sign in again each time the ID token expires (commonly about one hour). Per [OpenID Connect Core 1.0 §11](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess), requesting `offline_access` signals that the client may use the refresh token while the user is not present, and the provider must obtain consent for it. Claude Desktop therefore does not add this scope to an administrator-supplied `scopes` value in the default mode, so that requesting offline access remains an explicit choice. **Authorization servers that reject `offline_access`.** Standard OIDC providers (Entra ID, Okta, Auth0) accept `offline_access` and require it to issue a refresh token, so the automatic append is what you want. If your authorization server instead rejects unrecognized scopes with an `invalid_scope` error — for example, servers that issue refresh tokens via a provider-specific scope rather than `offline_access` — set `appendOfflineAccess` to `false` and include your provider's own refresh-token scope in `scopes` directly. Refresh tokens govern whether users are re-prompted to sign in, not how long a sign-in may stay valid. To cap the sign-in lifetime under your identity provider's session policy, set [`inferenceSessionLifetimeSec`](/docs/third-party/claude-desktop/configuration#inferencesessionlifetimesec); Claude Desktop shows a re-authenticate banner before the session expires. ## Configure the app Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway**, then fill in the **Gateway credentials** card: | Field | Value | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Gateway base URL | `https://llm-gateway.example.corp` | | Gateway API key | your gateway key (or a placeholder if your gateway has none) | | Credential kind | **Static API key** (default), or **Interactive sign-in** for [single sign-on](#single-sign-on-with-your-identity-provider) | | Gateway auth scheme | **Bearer** (default) or **x-api-key** | Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. ### Configuration keys | Setting | Type | Availability | Default | Description | | ---------------------------------------------------------------- | --------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Gateway base URL
`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Full URL of the inference gateway endpoint. | | Stream idle timeout
`inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.44121.1 | — | Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800. | | Gateway API key
`inferenceGatewayApiKey` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | API key for the configured inference gateway. | | Gateway auth scheme
`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap
Added in 1.3036.0 | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"` (accepted until October 7, 2026); use inferenceCredentialKind: "interactive". If it is still present after that, browser sign-in will no longer be inferred from it — the key will be reported as invalid and, unless inferenceCredentialKind or another credential field (an API key, inferenceGatewayOidc) says how to sign in, the gateway connection will have no credential and inference will not start. Deprecated: `inferenceGatewayAuthScheme: "auto"` (accepted until October 7, 2026); use "bearer" (or remove the key — bearer is the default). If it is still present after that, the value will be reported as invalid and ignored like any unrecognised scheme; the key will then take its default, "bearer", so the credential will still be sent as an Authorization: Bearer header. | | Gateway sign-in flow
`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | | Gateway SSO IdP (OIDC)
`inferenceGatewayOidc` | `object` | MDM + Bootstrap
Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code's `CLAUDE_STREAM_IDLE_TIMEOUT_MS`). It only helps when the gateway writes SSE keep-alive `ping` events (or `:` comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code's defaults. A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. While this key is set, the app's value takes precedence over `CLAUDE_STREAM_IDLE_TIMEOUT_MS` in Claude Code's own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies. * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control. **External IdP mode.** The app discovers `/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at `/.well-known/oauth-authorization-server`. **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the gateway validates signature, `iss`, and `aud` (the `clientId` configured here). `access_token` sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); `scopes` must then name the gateway's registered API scope. Either way the gateway must check `aud`, not just signature and issuer, or it accepts any token from your tenant. **IdP setup.** The callback is `http://127.0.0.1:/callback` by default (`http://localhost:/callback` with `redirectHost: "localhost"`); register exactly the one you use and include `/callback`. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback` (any port; omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the gateway API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with the exact URI `http://127.0.0.1:/callback` and that port in `redirectPort`. **Refresh.** With `offline_access` the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an `id_token` on refresh, so a Google Workspace-backed gateway in `id_token` mode re-prompts about hourly; `access_token` mode is unaffected. | Field | Type | Default | Description | | --------------------------------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `bearerTokenType` | `enum` | `id_token` | Which token to send as the gateway bearer. Use access token for gateways that validate as an OAuth resource server. One of: `id_token`, `access_token`. | | `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway’s API scope. offline\_access is appended automatically unless disabled below. | | `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. | | `resource` | `string` | — | Absolute URL identifying the gateway as the access-token audience. Sent as the RFC 8707 resource parameter when set; leave unset for Microsoft Entra ID. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `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. | To send additional HTTP headers on every inference request (tenant routing, org IDs, and similar), set [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders). It applies to all providers, not just gateways. ### Single sign-on configuration keys Single sign-on is enabled by setting `inferenceCredentialKind` to `interactive` **and** supplying `inferenceGatewayOidc`. Both are required — `interactive` alone (without `inferenceGatewayOidc`) selects a different mode where the gateway itself acts as the authorization server. | Setting | MDM key | Required | Description | | ---------------------- | ------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Credential kind | `inferenceCredentialKind` | Yes — must be `interactive` | Selects sign-in instead of an API key. | | Gateway SSO IdP (OIDC) | `inferenceGatewayOidc` | Yes | A **single JSON object** describing the identity provider (fields below). The resulting token is sent to the gateway as the bearer credential. | | Sign-in flow | `inferenceGatewayOidcAuthFlow` | No | `browser` (the default) runs the sign-in in the system browser. `broker` runs it through the [OS identity broker](/docs/third-party/claude-desktop/entra-broker) on Windows and macOS, which requires `issuer` to be a Microsoft Entra ID issuer (`https://login.microsoftonline.com/TENANT_ID/v2.0`) and needs no loopback redirect. | The `inferenceGatewayOidc` value is one JSON object with these fields: | Field | Required | Description | | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | Yes | Application (client) ID registered with the identity provider. | | `issuer` | Yes\* | OIDC issuer URL — the base URL only, **without** `/.well-known/openid-configuration`. The app appends that path itself to discover the authorization and token endpoints. | | `authorizationUrl` | No\* | Explicit OIDC authorization endpoint. Use together with `tokenUrl` instead of `issuer` when the identity provider does not serve `/.well-known/openid-configuration`. Ignored when `issuer` is set. | | `tokenUrl` | No\* | Explicit OIDC token endpoint. Must be set together with `authorizationUrl`. Ignored when `issuer` is set. | | `scopes` | No | Space-separated OIDC scopes. Defaults to `openid profile email offline_access`. Required when `bearerTokenType` is `access_token`. See [Refresh tokens and session lifetime](#refresh-tokens-and-session-lifetime) for how this field interacts with silent refresh. | | `redirectPort` | No | Fixed local port for the loopback redirect. Leave unset to let the app choose an ephemeral port (Entra). Set when the provider requires an exact port match (Okta). | | `redirectHost` | No | Host in the loopback redirect URI, `127.0.0.1` (the default) or `localhost`. Set to `localhost` when the identity provider accepts only `localhost` in a registered redirect URI, and register the `localhost` form of the URI instead (`http://localhost/callback`, or `http://localhost:/callback` with `redirectPort`). | | `bearerTokenType` | No | Which token the app sends to the gateway as the `Authorization: Bearer` value. `id_token` (the default) sends the OIDC ID token — the gateway validates it offline against the provider's JWKS with `aud` equal to the client ID. `access_token` sends the OAuth access token instead — use this for gateways that validate as an OAuth resource server rather than validating the ID token directly. When set to `access_token`, `scopes` is required. | | `appendOfflineAccess` | No | Whether to automatically append `offline_access` to `scopes` in `access_token` mode. Defaults to `true`. Set to `false` only if your authorization server rejects `offline_access` as an unrecognized scope. See [Refresh tokens and session lifetime](#refresh-tokens-and-session-lifetime). | | `resource` | No | RFC 8707 resource indicator: an absolute `https://` URL identifying the gateway as the access-token audience. When set, the app sends `resource=` on the authorization, token, and refresh requests. Use only with `bearerTokenType: "access_token"` and an identity provider that implements RFC 8707 (for example AD FS); leave unset for Microsoft Entra ID, which rejects the parameter; request the gateway's API scope in `scopes` instead. Changing it signs users in again. Ignored by the OS-broker sign-in flow (`inferenceGatewayOidcAuthFlow: broker`). | | `additionalRedirectReferrerHosts` | No | Space-separated hostnames also accepted as the referrer of the sign-in callback, for identity providers that complete sign-in from a different host than the authorization URL's (for example a portal or step-up page on a sibling host). When a callback is rejected for a referrer mismatch, the app log names the host to add. | \* Either `issuer`, or both `authorizationUrl` and `tokenUrl`, is required. `inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration#value-types). The in-app **Export** produces the correct format automatically. In a macOS `.mobileconfig` payload (Okta example): ```xml theme={null} inferenceCredentialKind interactive inferenceGatewayOidc {"issuer":"https://YOUR_ORG.okta.com","clientId":"YOUR_CLIENT_ID","redirectPort":53180} ``` Earlier app versions used `inferenceGatewayAuthScheme: "sso"` to select this mode. That value is deprecated; set `inferenceCredentialKind: "interactive"` instead. Existing deployments that still send `inferenceGatewayAuthScheme: "sso"` continue to work until October 7, 2026. After that date the value no longer selects browser sign-in, so set `inferenceCredentialKind: "interactive"` before then. ### Models When `inferenceModels` is unset, Claude Desktop on 3P populates the model picker from your gateway's `GET /v1/models` response. Auto-discovery shows only models whose IDs are recognizably Claude; if your gateway advertises models under opaque aliases, set `inferenceModels` explicitly. Set [`inferenceModels`](/docs/third-party/claude-desktop/configuration#models) to override discovery with an explicit list — the picker will show exactly the entries you provide. Use the model IDs your gateway expects (for example `bedrock/us.anthropic.claude-opus-5` for a LiteLLM-style routing prefix). If your gateway serves a Claude model under an opaque routing alias, it can mark the model as Claude by returning an `anthropic_family_tier` field (a Claude tier name such as `sonnet` or `opus`) on that model object in its `/v1/models` response, optionally with `is_family_default: true` when several models map to the same tier. Models marked this way pass the auto-discovery filter. The app also reads other optional fields on each model object. `display_name` sets the picker label when the app cannot derive one from the model ID, as with an opaque alias. `description` adds a one-line description beneath the label (Claude Desktop 1.49585.0 or later). `supports_1m: true`, or a `max_input_tokens` value of 1,000,000 or more, marks a discovered model as supporting the 1M-token context window, as `supports1m` does on an `inferenceModels` entry. If your gateway does not implement `GET /v1/models`, give every `inferenceModels` entry the full model ID your gateway accepts; bare tier aliases such as `sonnet` rely on discovery to resolve. When every entry is a full model ID, the app skips the `/v1/models` call automatically. A list that contains a bare alias keeps discovery on, so for a gateway without the endpoint, replace the alias with the full model ID; a bare alias cannot be resolved without discovery. On earlier app versions that do not skip the call automatically, also set [`modelDiscoveryEnabled`](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) to `false` to avoid the discovery attempt. The cost of leaving discovery on without the endpoint depends on how the gateway fails: an error response makes the app fall back to the `inferenceModels` list immediately, while an endpoint that accepts the request and hangs delays the model list by up to 10 seconds at launch. If your deployment supports the 1M-token context window for a model, set `supports1m: true` on that model's entry: ```json theme={null} [{"name": "bedrock/us.anthropic.claude-opus-5", "supports1m": true}] ``` The model picker then shows a second entry for the model, described as **1M context window**; the standard entry has no context-size label, and the default selection is unchanged. `supports1m` is an assertion about your gateway rather than something the app can verify: if the gateway does not accept 1M-token requests for that model, requests made from the 1M picker entry fail at inference time. Only set it on models you have confirmed against your deployment. The [Models section of the configuration reference](/docs/third-party/claude-desktop/configuration#models) documents the remaining entry fields, including display labels and tier mapping. ### MCP tool search [MCP tool search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) loads MCP tool schemas on demand instead of inlining every schema into the context window. It reduces context pressure when many MCP tools are configured (sessions that otherwise compact every turn or two). On gateway deployments, Claude Desktop turns tool search off by default, along with Claude Code's other experimental beta features, because strict gateways reject the experimental `anthropic-beta` request headers and request fields those features add. The same applies to Microsoft Foundry deployments and to any provider configured with a custom base URL. Setting the `ENABLE_TOOL_SEARCH` environment variable to `true` does not lift this suppression. To turn tool search on for these deployments, set the [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) configuration key. Requires app version 1.21459.0 or later. On Claude API, Google Cloud's Agent Platform, Amazon Bedrock, and Amazon Bedrock Mantle deployments with no custom base URL, tool search is on by default from Claude Desktop 1.49585.0 and `toolSearchEnabled` is not needed. These versions leave Claude Code's experimental beta features on for those providers, as terminal Claude Code does (on Google Cloud's Agent Platform, tool search applies to Claude 4.5 and newer models). To turn tool search off on these deployments, set `ENABLE_TOOL_SEARCH` to `false` in the `env` block of OS-level [Claude Code managed settings](https://code.claude.com/docs/en/settings#settings-files), with [`parentSettingsBehavior`](/docs/third-party/claude-desktop/code) set to `merge`. On earlier app versions these providers also have tool search off by default, and `toolSearchEnabled` turns it on. Setting `toolSearchEnabled` causes sessions to send experimental request headers and fields to your gateway or provider. On gateway deployments running Claude Desktop 1.40609.0 or later this is only the tool-search request shape (the `tool-search-tool-2025-10-19` value in the `anthropic-beta` header, deferred tool loading, and `tool_reference` content blocks), and every other experimental Claude Code beta stays off. On earlier versions, on Microsoft Foundry, and on providers behind a custom base URL, the key instead lifts the experimental-beta suppression for these sessions, so requests also carry Claude Code's other experimental beta headers and fields for that provider. Enable it only if your gateway forwards and accepts what it will receive; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks. ## Troubleshoot **`gateway SSO: server does not advertise device_authorization_endpoint`** — The app could not read your `inferenceGatewayOidc` value, so it fell back to treating the gateway itself as the sign-in server. Almost always this means the value is missing or not valid JSON, for example because it was written as separate dotted keys instead of one `inferenceGatewayOidc` value. Re-export from the in-app configuration window, or copy the `.mobileconfig` snippet above. **`OIDC discovery failed (HTTP 404)` or `(HTTP 405)`** — The `issuer` value is not the issuer base URL. Most often the metadata URI (ending in `/.well-known/openid-configuration`) was pasted instead, which doubles the path. Remove that suffix so `issuer` is just `https://YOUR_ORG.okta.com` (or the equivalent for your provider). **`no credential configured for provider "gateway": set inferenceCredentialKind or one of the credential fields`** — `inferenceCredentialKind: "interactive"` is not present in the pushed configuration. **Browser shows "Connected" but the app reports the sign-in failed, or `Token exchange failed (HTTP 401)`** — The browser step succeeded, but the identity provider rejected the follow-up token request. This usually means the IdP application is registered as a confidential (Web) client, which expects a client secret. Claude is a public PKCE client and doesn't send one. Register a public/native client instead: **Native Application** in Okta, or the **Mobile and desktop applications** platform in Entra ID. Application type generally can't be changed after creation, so you may need to create a new one. Google Workspace can be used as the identity provider, but in the default `id_token` mode Google does not issue a fresh ID token on background refresh, so users are prompted to sign in again roughly once an hour. Setting `bearerTokenType` to `access_token` avoids this. Entra ID and Okta are not affected in either mode. **Model picker is empty or missing models.** Auto-discovery filters out model IDs that are not recognizably Claude, so models your gateway serves under opaque aliases appear only if the gateway marks them with `anthropic_family_tier` in its `/v1/models` response or you list them in `inferenceModels` (see [Models](#models)). When `/v1/models` is unreachable or returns an error, the picker falls back to the `inferenceModels` list; if that list is empty, so is the picker. **The 1M context window entry does not appear in the picker.** `supports1m` takes effect only when the entry's `name` matches the model ID the picker uses. Setting it on a bare alias (for example `sonnet`) while discovery returns full model IDs produces no match. Set `supports1m` on an entry whose `name` is the exact ID your gateway's `/v1/models` endpoint returns. # Import history from claude.ai Source: https://claude.com/docs/third-party/claude-desktop/import Bring conversations, projects, and local Cowork and Code sessions into Claude Desktop on 3P from a claude.ai workspace or an earlier install Import brings a copy of your claude.ai conversations and projects into Claude Desktop on third-party (3P), along with any Cowork and Claude Code sessions already on this machine from an earlier install. Everything lands in the local session store described in [User identity and local data](/docs/third-party/claude-desktop/data-storage), so you can pick up work you started on claude.ai and continue it against your organization's own inference provider. Each import is a one-time copy. New activity on claude.ai after you import does not appear in Claude Desktop unless you import again, and re-running the import does not create duplicates. ## Before you start * Your administrator has turned import on by setting [`claudeAiImport`](/docs/third-party/claude-desktop/configuration#claudeaiimport) with `enabled` set to `true` in the managed configuration. Import is off by default; until then, **Settings → Import & export** reports that import isn't enabled for this deployment. * Claude Desktop is installed and running in third-party mode. See [Installation and setup](/docs/third-party/claude-desktop/installation). * To bring history over from a claude.ai Team or Enterprise workspace, an owner of that workspace has enabled member data export (next section). Personal claude.ai accounts can always export. ## Enable member data export (admins) On Team and Enterprise workspaces, member data export is off by default. A workspace owner enables it on claude.ai under **Settings → Organization → Data and privacy → Allow members to export their own data**. claude.ai organization settings, Data and privacy page, with the Allow members to export their own data toggle turned on and a confirmation toast reading Member data export enabled. Members of the workspace can then export their own conversations. The toggle does not expose one member's data to another; each member can download only their own history. ## Open the import wizard In Claude Desktop, go to **Settings → Import & export** and click **Import…** to open the **Import from Claude** wizard. Claude Desktop settings with Import and export selected and the Import from Claude wizard open on step 1, showing Sign in to claude.ai and Choose file buttons. The wizard has three steps: **Chats** (your claude.ai export), **Cowork & Code** (local sessions on this machine), and **Review**. Skip any step you don't need. A fourth step, **Duplicates**, appears after the import only when an imported project has the same name as one you already have. See [If a project already exists](#if-a-project-already-exists). ## Step 1: claude.ai chats and projects You can pull your claude.ai history straight into the wizard by signing in, or download it from claude.ai yourself and choose the file. Click **Sign in to claude.ai…**. Your browser opens to claude.ai; sign in if prompted, choose your organization if you belong to more than one, and click **Authorize**. claude.ai organization selector titled Select organization, listing one organization. claude.ai authorization card reading Claude Desktop Import would like to connect to your Claude chat account, with an Authorize button. Back in Claude Desktop, click **Fetch export**. The wizard requests an export from claude.ai, downloads it, and shows what it found. Import from Claude wizard step 1 showing a claude.ai export row with the account email and a summary of 7 chats and 1 project. On claude.ai, go to **Settings → Privacy → Export data** and click **Export**. If you don't see **Export data**, ask a workspace owner to [enable member data export](#enable-member-data-export-admins). claude.ai settings Privacy page with the Export data subpage open, showing an Export button and a note that a download link will be sent by email. claude.ai emails you a download link when the export is ready. The link expires after 24 hours. Email from Claude titled Your data is ready for download with a Download data button. Download the `.zip`, then in the import wizard click **Choose file…** and select it. Import from Claude wizard step 1 showing a selected member-data zip file with a summary of 7 chats and 1 project. Click **Continue**, or **Skip this step** if you only want to bring in local sessions. ## Step 2: local Cowork and Code sessions The wizard scans this machine for Cowork and Claude Code sessions from an earlier Claude Desktop install and lists what it finds. Choose how far back to include, and add any other folder that holds sessions (for example, a backup or a folder copied from another machine). Import from Claude wizard step 2, Cowork and Code, listing 5 local sessions with a time-range selector and an option to add another location. Sessions are copied, not moved. Your original history stays where it is. ## Step 3: review and import The **Review** step summarizes what will be added. Click **Import** to copy everything into your local session store. Import from Claude wizard step 3 showing a claude.ai export summary of 7 chats and 1 project alongside 5 local Cowork and Code sessions, with an Import button. Import from Claude wizard success screen showing a checkmark and the number of sessions imported, with a note that re-running import will not create duplicates. ## If a project already exists When an imported project has the same name as a project already in Claude Desktop, the wizard adds a **Duplicates** step after the import finishes. This happens, for example, when you set up **Northwind** on this machine and then bring over history from another machine that also has a Northwind project. The step lists each match with two choices. Import from Claude wizard step 4, Duplicates, headed These projects already exist, listing five Northwind projects each with Merge into existing and Keep separate buttons and a Continue button. * **Merge into existing** moves the imported chats and sessions into your existing project and removes the duplicate. Folders you attached to the duplicate move with them. If your existing project has no instructions of its own, the imported project's instructions are shown there for you to review and accept. Later imports from the same source land in the existing project as well. * **Keep separate** leaves both projects in place. The imported one keeps a numbered name, such as **Northwind (1)**, and Claude Desktop stops offering to merge it. The **Projects** page offers the same two choices, in a row under the duplicate project's card and at the top of the duplicate project's own page. Decide there if your history was brought over automatically when you signed in, so you never saw the wizard, or if you closed the wizard before choosing. ## Continue an imported conversation Open any imported conversation from the sidebar and keep chatting. The first time you send a message in an imported session, Claude Desktop shows a **Resume imported session?** prompt. Click **Trust and resume** to continue; the reply comes from your configured inference provider, not from claude.ai. An imported conversation open in Cowork with a yellow Resume imported session card offering Go back and Trust and resume buttons. ## Export sessions to move them to another device When your administrator also sets `exportEnabled` to `true` under `claudeAiImport`, **Settings → Import & export** offers **Export…**, which writes this computer's chats, Cowork tasks, and Code sessions (not terminal Claude Code sessions) to a zip file. On the other device, open the import wizard and select that zip with **Choose file…**; the wizard lists its sessions in the [Cowork & Code step](#step-2-local-cowork-and-code-sessions). The export is a one-time snapshot, not a sync, and the zip contains full conversation content, so handle it as sensitive data. ## What is and isn't included * **Your data only.** An export contains your own conversations, projects, and memory. Other workspace members' content is not included. * **Chats and projects come over.** Each imported project appears on the **Projects** page. If the project has custom instructions, Claude Desktop shows them in the project for you to review and accept before they take effect. * **Project knowledge files and conversation attachments do not.** A member's own export never includes the contents of files uploaded to a project's knowledge or attached to a conversation. This is a security policy on claude.ai, and it applies to both the **Sign in to claude.ai** and **Choose a downloaded file** paths. Imported chats keep the messages that referenced an attachment, but not the file itself. The only export that includes file contents is an organization-level export, which only a workspace owner can request. * **One-time copy.** Imported history does not stay in sync with claude.ai. Run the import again to pick up newer conversations; existing imports are matched and skipped, so you won't get duplicates. * **Download links expire.** The email link from claude.ai is valid for 24 hours. Request a new export if it lapses. # In-app configuration Source: https://claude.com/docs/third-party/claude-desktop/in-app-configuration Build, test, and export a Claude Desktop on 3P configuration from inside the app, with validation and per-provider guidance The in-app configuration window is the recommended way to configure Claude Desktop for third-party inference. It validates values as you enter them, shows exactly which fields your inference provider requires, tests the connection against your endpoint, and computes the network egress allowlist for your settings, so you don't have to hand-edit JSON, plists, or registry keys. ## Open the configuration window From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the sign-in screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…**. Claude Desktop in-app configuration window with the sidebar of setting groups on the left and the Connection form on the right. The sidebar groups settings the same way the [configuration reference](/docs/third-party/claude-desktop/configuration) does. Fill in **Connection** first, then work down through the sections your deployment needs. ## Apply locally or export for a fleet Use **Apply Changes** to write the configuration to this device only and relaunch into it. This is the [single-machine setup](/docs/third-party/claude-desktop/installation#single-machine-setup) path for evaluation and pilots. Use the **Export** menu to generate deployment artifacts for a fleet: | Export option | Use with | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `.mobileconfig` profile | Jamf or any macOS MDM | | `.reg` policy file | Intune, Group Policy, or any Windows MDM | | ADMX template (`.zip`) | Intune or Group Policy; a schema-only template, you enter values in the management console | | Profile Manifest (`.plist`) | Jamf, ProfileCreator, or similar macOS tools; a schema-only template, you enter values in your tool | | JSON config | The response body for a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), or a configuration file for a device without MDM | | Egress allowlist | Your firewall or network team | See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) or [Deploy with a bootstrap server](/docs/third-party/claude-desktop/bootstrap) to distribute what you exported. When a managed profile is already present on the device, the window opens in read-only mode and shows the deployed values. Author new configurations from a device without a managed profile. # Installation and setup Source: https://claude.com/docs/third-party/claude-desktop/installation Install Claude Desktop on 3P, check device readiness, and choose whether configuration reaches your devices through the Enterprise Admin Console, an MDM profile, or a bootstrap server Claude Desktop on third-party (3P) is the standard Claude Desktop application plus a managed configuration that activates third-party inference mode. Setup is two pieces: install the regular Claude Desktop app, and deliver the configuration to it. ## System requirements Cowork, the agent workspace at the center of Claude Desktop on 3P, has the following device requirements: | Requirement | macOS | Windows | | ---------------- | ---------------------------- | -------------------------------------------------------------------- | | Operating system | macOS 14 (Sonoma) or later | Windows 10 build 19041 (version 2004) or later, including Windows 11 | | CPU architecture | Apple silicon or Intel (x64) | x64 or Arm64 | | Installer | `.dmg` | `.msix` | On Windows, Cowork requires the `.msix` package: fleets provisioned with the legacy `.exe` installer get Claude Desktop without Cowork, and migrating them to `.msix` enables it. Cowork also requires working hardware virtualization and, on Windows, the Virtual Machine Platform optional feature. The [readiness check](#check-device-readiness) verifies both along with the requirements above. ## Check device readiness Before installing Claude Desktop, you can confirm that a device supports Cowork by running the readiness check: a small standalone program that requires no installation or sign-in. | Platform | Download | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | macOS | [Cowork readiness check for macOS](https://claude.ai/api/desktop/darwin/universal/cowork-readiness-check/latest/redirect) | | Windows (Arm) | [Cowork readiness check for Windows arm64](https://claude.ai/api/desktop/win32/arm64/cowork-readiness-check/latest/redirect) | | Windows (x64) | [Cowork readiness check for Windows x64](https://claude.ai/api/desktop/win32/x64/cowork-readiness-check/latest/redirect) | Open the downloaded program to run the check. A ready device reports **This computer is ready for Cowork**. For fleet deployments, run the check on one device of each hardware model in your fleet before the broad rollout to identify unsupported models early. ## Install the app Download the installer for your platform from [claude.com/download](https://claude.com/download). | Platform | Installer | Notes | | -------- | --------- | ----------------------------------------------------------- | | macOS | `.dmg` | Drag **Claude.app** to Applications | | Windows | `.msix` | Supports per-machine provisioning for enterprise deployment | For fleet rollouts, distribute the installer through your standard software-distribution mechanism. On the MDM and bootstrap paths, distribute it after the configuration reaches devices; [Choose a configuration delivery model](#choose-a-configuration-delivery-model) covers how the configuration gets there. ## Choose a configuration delivery model Configuration reaches devices in one of three ways. With the Enterprise Admin Console, Anthropic hosts the configuration and users receive it by signing in to the app. With MDM or a bootstrap server, you typically push a profile to devices with your MDM tooling, and the two differ in what the profile contains. | | Enterprise Admin Console | MDM profile | Bootstrap server | | -------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | What you deploy to devices | Only the app, which downloads each user's configuration when they sign in with their work account | The full configuration, exported as a `.mobileconfig` or `.reg` profile | A minimal profile containing only the bootstrap keys (`bootstrapUrl`, optionally `bootstrapOidc` or request headers) | | Where settings live | In the Enterprise Admin Console, which Anthropic hosts and your administrators edit in a browser | In the profile, identical for every device the profile targets | On an HTTPS endpoint you operate, which returns each user's configuration at sign-in | | Per-user values | Permission policies per group of users | Separate profiles per device group | The server keys its response to the signed-in user | | Changing settings | Save the change in the console. Running apps pick it up at their next check and ask the user to relaunch | Export and push an updated profile | Change your server's response; devices pick it up at the next fetch, with no profile push | Choose the Enterprise Admin Console when you want to manage the configuration centrally without operating MDM profiles or a server, and your users can sign in to Claude Desktop with a Claude account tied to their work email. Anthropic stores your user list and the settings you save. Prompts still go only to your inference provider, and conversations stay on the device. Contact your Anthropic representative to have an organization provisioned. Choose an MDM profile when one configuration, or a few group-scoped profiles, covers your fleet and no device should depend on a sign-in to Anthropic. Most MDMs support role-based distribution, so per-group configuration doesn't require a bootstrap server. Building the configuration in the app is optional. The [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) can also export schema-only templates (an ADMX template for Windows, a Profile Manifest `.plist` for macOS) from its **Export** menu, so you can enter values directly in your management console instead. See [Export the profile](/docs/third-party/claude-desktop/mdm#2-export-the-profile) for all formats. Choose a bootstrap server when your organization doesn't use MDM, or when per-user credentials or frequently changing settings would make per-group profiles unwieldy. The tradeoff is that you operate the endpoint. The models don't combine. A device whose MDM profile or registry policy sets any key other than the [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) uses that configuration and ignores the Enterprise Admin Console. When a bootstrap response is in effect, it replaces MDM-delivered values wholesale, and a few device-level keys are only available via MDM (see the Availability column in the [configuration reference](/docs/third-party/claude-desktop/configuration)). Pick your path: * [Deploy with Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) covers provisioning, configuring the app in the console, and onboarding users. * [Deploy with MDM](/docs/third-party/claude-desktop/mdm) covers authoring the configuration in the app, exporting the profile, and deploying it to your fleet. * [Deploy with a bootstrap server](/docs/third-party/claude-desktop/bootstrap) covers getting the bootstrap keys onto devices and running the server. On the MDM and bootstrap paths, deploy the configuration before the app so users open Claude for the first time and land directly in the third-party deployment. With the Enterprise Admin Console, save a configuration in the console first, and users then install the app and sign in. ## Single-machine setup For evaluating before a fleet rollout, for pilots, or for organizations that don't use MDM, a single machine can be configured directly in the app. 1. Install Claude Desktop from [claude.com/download](https://claude.com/download). 2. Launch the app. **Do not sign in or create an Anthropic account.** From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). 3. Enter the provider, endpoint, and credential values supplied by your administrator. 4. Click **Apply Changes**, then click **Save & Restart**. The app relaunches and the sign-in screen now offers the option to start in Claude Desktop on 3P using the configuration you entered. The configuration is written to the application's local config file and applies only to that device and user account. It can be edited from the same window at any time. To return to standard Claude Desktop, choose the Anthropic sign-in option on the sign-in screen instead. If your organization runs a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) but doesn't use MDM, your administrator can instead supply a small configuration file containing only the bootstrap keys. Load it with **Import configuration** in the same window; the bootstrap server supplies everything else after you sign in. When the configuration works on a single machine, roll it out to the fleet with the [delivery model you chose](#choose-a-configuration-delivery-model); on the MDM path, you can export the tested configuration as the profile you deploy. ## Verifying the deployment On any configured device, open Claude Desktop, go to **Help → Troubleshooting → Generate Diagnostic Report**, and click **Export to file**. In the saved `.zip` file, `managed-config.txt` shows where the configuration was read from and every key the app applied, with secret values redacted and anything it could not parse listed under `Parse errors`. `provider-status.txt` shows whether the provider settings are complete and valid, and `deployment-mode.txt` shows whether the app is running in third-party mode. Also confirm that the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) (**Developer → Configure Third-Party Inference…**) opens read-only on a managed device. The app reads managed keys from the profile by name and silently ignores a misspelled key rather than reporting an error. On macOS, a window that is still editable means no recognized key reached the app, even if your MDM shows the profile as delivered. On Windows, even a misspelled value under `HKLM\SOFTWARE\Policies\Claude` counts as machine policy and locks the window, so check `managed-config.txt` in the diagnostic report to see which keys were actually read. If your profile deliberately sets [only app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) (the update, relaunch window, configuration re-check, or network proxy keys), an editable window is expected. If the app shows the standard claude.ai sign-in screen instead of Cowork, the configuration was not read. Common causes: * `inferenceProvider` is missing, misspelled, or set to an unrecognized value * The configuration was applied while the app was running (fully quit and relaunch) * The configuration was written to the local config file but you're checking the managed location (or vice versa) * A required key for the chosen provider is missing; check **Help → Troubleshooting** or the application log at `~/Library/Logs/Claude-3p/main.log` (macOS) / `%LOCALAPPDATA%\Claude-3p\Logs\main.log` (Windows) * On Windows (v1.19367.0 and later), the configuration is in `HKCU\SOFTWARE\Policies\Claude` but machine policy is also present: any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude` causes the app to ignore user policy entirely. In the diagnostic report (**Help → Troubleshooting → Generate Diagnostic Report**, then **Export to file**), `managed-config.txt` shows which keys the app read and lists under `Parse errors` any machine-policy values it could not use. A `REG_EXPAND_SZ` value shows as present in `reg query` output while the app reports the managed configuration as invalid or absent, because the app counts the value as machine policy but cannot read its contents ## Troubleshooting If installation or setup fails, generate a diagnostic report before requesting support: on the affected machine, go to **Help → Troubleshooting → Generate Diagnostic Report**, click **Export to file**, choose where to save the `.zip` file, and send that file to your Anthropic representative. The report contains the configuration state, application logs, and environment details needed to investigate. It does not include user data or conversation content. ## Endpoint security software Claude Desktop runs Chat conversations, Cowork tasks, and Code sessions through an agent helper, a signed binary that it keeps under its user-data directory (with the standard installer) and launches when a user works in Chat, Cowork, or Code. If your organization runs binary-authorization or EDR software (such as [Santa](https://santa.dev), CrowdStrike Falcon, or Microsoft Defender ASR) with path-based deny rules, the agent helper may be blocked from launching. The symptom is that Claude Desktop opens normally and reads the managed configuration, but Chat conversations, Cowork tasks, and Code sessions fail to start. **Allowlist the helper by signing identity rather than path** so the rule survives version updates. **macOS** ``` ~/Library/Application Support/Claude-3p/claude-code//claude.app/Contents/MacOS/claude ``` The helper is Developer ID signed and notarized: * Team ID: `Q6L2SF6YDW` (Anthropic PBC) * Signing ID: `com.anthropic.claude-code` For Santa, a `TEAMID` allow rule for `Q6L2SF6YDW` covers the helper across version updates. Standard (non-3P) installs use `~/Library/Application Support/Claude/` with the same subpath. **Windows** ``` %LOCALAPPDATA%\Claude-3p\claude-code\\claude.exe ``` The helper is Authenticode-signed with publisher `Anthropic, PBC`. For Defender ASR or AppLocker, allowlist by publisher rather than path. Standard installs use `%APPDATA%\Claude\` with the same subpath. ## Offline installation Standard installs fetch two large runtime components from `downloads.claude.ai` at session start: the VM workspace bundle that Cowork sessions run in, and the Claude CLI binary. For networks that cannot reach `downloads.claude.ai`, Anthropic publishes an offline installer variant with both components built into the installer package and verified against checksums compiled into the application, so sessions can start without any connection to Anthropic. The offline installers are several gigabytes larger than the standard ones. Each supported platform and architecture has a fixed download URL that serves the current offline installer: | Platform | Format | Download URL | | --------------------- | ------- | -------------------------------------------------------------------- | | Windows (x64) | `.msix` | `https://claude.ai/api/desktop/win32/x64/offline/latest/redirect` | | Windows (Arm) | `.msix` | `https://claude.ai/api/desktop/win32/arm64/offline/latest/redirect` | | macOS (Apple silicon) | `.dmg` | `https://claude.ai/api/desktop/darwin/arm64/offline/latest/redirect` | | macOS (Intel) | `.dmg` | `https://claude.ai/api/desktop/darwin/x64/offline/latest/redirect` | Each URL responds with an HTTP redirect to a versioned installer file, so any HTTP client that follows redirects downloads the installer directly. New versions of Claude Desktop roll out to connected devices gradually; these URLs serve the newest version whose rollout has completed. The redirect's `Location` header contains the version number, so tooling can detect a new version by requesting the URL without following the redirect. If the offline installer for the version the URL serves is not yet available, the download fails with HTTP 404 rather than falling back to an older installer; this can happen just after a new version appears in the `Location` header. Keep the installer you last downloaded and retry later. Download the installer from a connected machine and bring it across your boundary with your usual software-distribution process. Pair the offline installer with [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration#disableautoupdates). The app cannot reach the update feed from an air-gapped network, and you update the fleet by distributing each new offline installer through your MDM. Also set [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false`, or point [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) at a mirror inside your network. Otherwise the app tries to fetch the signed model catalog from `downloads.claude.ai` at launch and every 5 to 15 minutes after that, and while those requests fail the model picker keeps the names and effort options that ship with the app. With updates and the catalog fetch handled this way, the only egress an air-gapped deployment needs is your inference provider; see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths). ## Updates By default, Claude Desktop downloads updates from Anthropic's update server automatically and applies them the next time the app restarts. If the app hasn't restarted within 72 hours of downloading an update, it restarts itself, waiting for 10 minutes of user inactivity before doing so. This enforcement is always on and offers no in-app prompt to defer the restart; the `autoUpdaterEnforcementHours` key tunes the 72-hour window rather than enabling it. In 3P deployments you can: * **Leave auto-update enabled** (recommended) so fixes reach users without IT intervention. Set `autoUpdaterEnforcementHours` to shorten the enforcement window (1 to 72 hours; values above 72 are rejected). Setting the key also makes the window strict: the restart fires as soon as the window elapses, without waiting for a pause in user activity. * **Disable auto-update** (`disableAutoUpdates`) and redistribute new builds through your MDM on your own cadence. This is required for [air-gapped environments](#offline-installation) but means your IT team owns the update pipeline. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the network paths the updater uses. # Legal and compliance Source: https://claude.com/docs/third-party/claude-desktop/legal Legal agreements, compliance, and security information for Claude Desktop on 3P ## Legal agreements ### License Your use of the Claude Desktop application, including in Claude Desktop on third-party (3P) mode, is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). ### Commercial agreements Claude Desktop on 3P routes model inference through the provider you configure (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, a compatible gateway, or the Anthropic API directly). Inference usage is billed by, and subject to your agreement with, that provider. When you configure the Anthropic API as your provider, inference billing and data terms fall under your Anthropic agreement. Your existing commercial agreement with Anthropic continues to apply to your use of the Claude Desktop application, unless we've mutually agreed otherwise. ### Enterprise Admin Console for Desktop 3P If your organization manages Claude Desktop on 3P from the [Enterprise Admin Console for Desktop 3P](/docs/third-party/claude-desktop/admin-console) (**Organization settings** on claude.ai), rather than authoring the configuration in MDM or hosting your own bootstrap server, Anthropic hosts that console. Your use of the Enterprise Admin Console for Desktop 3P is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). When you access Claude through a third-party provider (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or a compatible gateway), the Commercial Terms apply only to your use of the Enterprise Admin Console, unless we've mutually agreed otherwise. ## Compliance When using Google Cloud's Agent Platform or Amazon Bedrock, the app sends conversation content only to your configured inference endpoint and stores it on the local device. Data handling at the endpoint is governed by [Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/data-governance) and [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html) respectively, and the compliance posture of your deployment is determined by your inference provider and the device environment you control. When using Microsoft Foundry, the app also sends conversation content only to your configured inference endpoint and stores it on the local device. Microsoft Foundry offers Claude models in two hosting options, Hosted on Azure and Hosted on Anthropic, and you choose one when you configure the model deployment in Microsoft Foundry. Under both options, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. Your use of Claude through Microsoft Foundry is subject to Anthropic's data use terms. Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details. See the [Overview](/docs/third-party/claude-desktop/overview) for the architecture and [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) for each provider's data path. For Anthropic's certifications and compliance reports, see the [Anthropic Trust Center](https://trust.anthropic.com). For HIPAA, see [HIPAA](/docs/third-party/claude-desktop/overview#hipaa) on the Overview page. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not interact with PHI; the BAA relationship is between you and your cloud service provider, and any remote MCP servers you connect need your own HIPAA review. For Microsoft Foundry, HIPAA readiness (Anthropic's arrangement of a signed BAA plus safeguards for processing PHI) is not available, as described under [What HIPAA readiness does not cover](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#what-hipaa-readiness-does-not-cover) in the Claude API documentation. ## Usage policy Use of Claude models, including via Claude Desktop on 3P, is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). ## Privacy and telemetry The Claude Desktop application sends operational telemetry (crash reports and product analytics) to Anthropic by default. This telemetry contains no prompt or response content. You can fully disable it through managed configuration, or from the console for an organization managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console). See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for what each category contains and how to disable it. An organization managed from the Enterprise Admin Console can also turn on usage analytics. Users' apps then report session, token, and estimated-cost counts to Anthropic, and the organization's administrators can see each user's sessions, tokens, and estimated cost. The reports contain no prompt, response, or file content. [Usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) lists who can see the counts and exactly what each report contains. Anthropic's [Privacy Policy](https://www.anthropic.com/legal/privacy) describes how Anthropic handles data it receives. ## Security and trust Security architecture, threat-model, and data-flow documentation for Claude Desktop and Claude Desktop on 3P is available on the [Anthropic Trust Center](https://trust.anthropic.com). ### Security vulnerability reporting Anthropic manages our security program through HackerOne. [Use this form to report vulnerabilities](https://hackerone.com/4f1f16ba-10d3-4d09-9ecc-c721aad90f24/embedded_submissions/new). *** © Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service. # Desktop and filesystem access Source: https://claude.com/docs/third-party/claude-desktop/local-access How Claude Desktop on 3P reads and writes files on the user's machine, and how to constrain it Like [Cowork](/docs/cowork/overview) in standard Claude Desktop, Claude Desktop on third-party (3P) works directly with files on the user's computer. Users attach one or more **workspace folders** to a session; the agent can then read, create, and modify files anywhere inside those folders, and run code against them inside the sandbox VM. In Claude Desktop on 3P, administrators can constrain which folders users are allowed to attach. ## Workspace folder allowlist Set [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) in the managed configuration to restrict which paths users may attach as workspace folders. The [Configuration reference](/docs/third-party/claude-desktop/configuration) covers where the managed configuration lives on each platform and how to deploy it. | Value | Behavior | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Unset | Unrestricted. Users can attach any folder they have OS-level access to, matching standard Claude Desktop. | | `["~/Documents/Claude", "/Volumes/Shared/Projects"]` | Users may attach only folders **inside** one of the listed roots. | | `[]` | No folders may be attached. The agent can still create files in its own sandbox scratch space, but cannot read or write the user's filesystem. | A leading `~` expands to the user's home directory, so a single profile can express per-user roots like `~/Documents/Claude` across the fleet. A path may also reference one of a fixed set of environment-variable tokens, such as `%OneDrive%` or `%USERNAME%`, listed in the [configuration reference](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders). An entry that references any other `%VAR%`, or one that is unset on the device, is ignored. Each entry is either a plain path string or an object with these fields: | Field | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The folder path (required). Subfolders are included. | | `mode` | `rw` (the default) or `ro`. The agent can view and search a read-only folder but cannot modify it in Cowork. In Code sessions, read-only applies to Claude's file tools only; shell commands and [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) do not enforce it. | | `isDefaultSelected` | When `true`, the folder appears already selected on the new-task page and skips the trust prompt. Users can remove it. | For example, `[{"path": "~/Documents/Claude"}, {"path": "/Volumes/Shared/Reference", "mode": "ro"}]` lets users work in their own folder and consult the shared reference folder without changing it. The check is enforced against the **resolved** path, so symlinks and `..` traversal can't be used to escape an allowed root. The allowlist controls what users can **attach**. Within an attached read/write folder, the agent can read and write every file the user's OS account can reach. Data outside the allowed roots cannot be attached in Cowork and is out of reach of Claude's file tools in Code sessions. A Code session's shell commands are confined only by the sandbox described under [Code](/docs/third-party/claude-desktop/code#applied-as-managed-policy): where it applies they can change files only inside the roots and temporary locations but can still read outside them unless you also set [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), and where it does not apply (Windows devices, hosts without the sandbox dependencies) the allowlist does not confine them and that key can only turn such reads into approval prompts. To let the agent read data in Cowork without changing it, list the folder with `mode` set to `ro`. ## Network drives on Windows Users can attach a mapped network drive (for example, `Z:\`) as a workspace folder through the folder picker. Raw UNC paths (`\\server\share`) are not supported; map the share to a drive letter first. What the agent can do on the network drive depends on whether the drive was mapped and reachable when the sandbox started: * **Mapped and reachable at sandbox start:** the sandbox mounts the attached folder alongside local folders. File tools and shell commands both work. * **Mapped later, or unreachable at sandbox start:** file tools still work, but shell commands cannot reach the drive. Copy the relevant files to a local folder before running a script or build against them. The sandbox can stay running between sessions. A drive the user maps while the sandbox is already up falls into the second case until the sandbox next restarts. The agent cannot attach a network-drive path on its own; only the user can, through the folder picker. This is a security boundary. On macOS, network mounts under `/Volumes/` are currently treated as local folders. ## WSL You do not need Windows Subsystem for Linux (WSL) to run Claude Desktop or Cowork. On Windows, Cowork's sandbox runs on the operating system's built-in virtualization, which the [readiness check](/docs/third-party/claude-desktop/installation#check-device-readiness) verifies. Install the macOS or Windows package (see [System requirements](/docs/third-party/claude-desktop/installation#system-requirements)); there is no installation path inside WSL. Run the Windows app and work with WSL files from there. Windows exposes a WSL distribution's filesystem as a UNC path (`\\wsl$\` or `\\wsl.localhost\`). Like any other raw UNC path, these cannot be attached as workspace folders directly. To attach files that live inside WSL as a workspace folder, map the share to a drive letter and attach the mapped drive, or copy the files to a local Windows folder. [Network drives on Windows](#network-drives-on-windows) describes what the agent can do on a mapped drive. # Deploy Claude Desktop on 3P with Amazon Bedrock Mantle Source: https://claude.com/docs/third-party/claude-desktop/mantle Configure Claude Desktop on 3P to use Claude models through Amazon Bedrock Mantle's Anthropic-native API surface Amazon Bedrock Mantle is Amazon Bedrock's Anthropic-native API surface. Unlike the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock), Mantle speaks the Anthropic Messages API directly and authenticates with a bearer token rather than the AWS SigV4 credential chain, so no AWS CLI, named profile, or IAM Identity Center setup is needed on the device. In practice, Mantle is the Amazon Bedrock provider with a different runtime endpoint and a single bearer-token credential path. ## Choose an authentication approach Mantle supports a bearer token only. There is no in-app AWS sign-in or named-profile support for this provider; if you need per-user IAM Identity Center authentication, use the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock) instead. | Scenario | Use | Notes | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | Any Mantle deployment | [Bearer token](#bearer-token) (`inferenceBedrockBearerToken`) | A long-lived token distributed in the managed profile. | | Token must not be stored statically | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the bearer token to stdout at runtime. | ## Set up AWS Enable Claude models in Amazon Bedrock for the region you will set as `inferenceBedrockRegion`, and obtain a Mantle bearer token for that account. See [Set up AWS](/docs/third-party/claude-desktop/bedrock#set-up-aws) on the Amazon Bedrock page for the model-access step; the IAM Identity Center steps there are not needed for Mantle. ## Prepare devices ### Bearer token No per-device preparation is required. Place the Mantle bearer token in the managed configuration as `inferenceBedrockBearerToken`. The app reaches `bedrock-mantle..api.aws` (or the host in `inferenceBedrockBaseUrl` if you set one). This host is included automatically in the **Egress** section of the in-app configuration window. The `.api.aws` zone has no FIPS endpoint variant. ## Configure the app Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Bedrock Mantle**, then fill in the credentials card: | Field | Value | | ---------------- | ------------------------ | | AWS region | e.g. `us-east-1` | | AWS bearer token | your Mantle bearer token | | Bedrock base URL | *optional* | If you set **Bedrock base URL**, provide the full SDK base URL including the `/anthropic` path (for example `https://bedrock-mantle.us-east-1.api.aws/anthropic`); it replaces the default `bedrock-mantle..api.aws/anthropic` endpoint. Under **Models**, add at least one **Model list** entry. Mantle has no model-list endpoint, so model discovery is not available and `inferenceModels` is required. Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. ### Configuration keys Mantle reuses the `inferenceBedrock*` key names. Only `inferenceBedrockRegion`, `inferenceBedrockBearerToken`, and `inferenceBedrockBaseUrl` apply; the other keys below (`inferenceBedrockProfile`, `inferenceBedrockSso*`, `inferenceBedrockAwsDir`, `inferenceBedrockAwsCliPath`, `inferenceBedrockServiceTier`) are ignored for this provider. | Setting | Type | Availability | Default | Description | | --------------------------------------------------------------- | -------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | AWS region
`inferenceBedrockRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. | | Bedrock base URL
`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. | | 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`. | | 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. | | 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. | | AWS SSO region
`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | IAM Identity Center home region. | | 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. | | 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. | | AWS profile name
`inferenceBedrockProfile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. | | 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. | | 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. | 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. You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels). ## What users experience The app opens directly on first launch with no user action. Users are never prompted to sign in; re-authentication happens only when you rotate the bearer token in the managed profile. ## Troubleshoot To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage). # Deploy with MDM Source: https://claude.com/docs/third-party/claude-desktop/mdm Author a full configuration in the app, export it as a profile, and deploy it fleet-wide with Jamf, Intune, Group Policy, or any MDM On the MDM delivery model, the profile you deploy carries your organization's full configuration, and every device the profile targets gets the same settings. This page covers the workflow end to end: build the configuration in the app, export it, open the firewall, and deploy the profile and installer to your fleet. Before you start, install Claude Desktop on an admin workstation; see [Installation and setup](/docs/third-party/claude-desktop/installation). If you deliver configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) instead, follow that page; your profile then carries only the bootstrap keys, but it is exported and deployed the same way described here. ## Recommended rollout Roll out in this order; the numbered sections on this page cover each step in detail. An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) on their own device. Export the validated configuration in the format your MDM expects. Open the hostnames your configuration requires on your perimeter firewall; the configuration window lists them for the exact settings you chose. Distribute the profile through your MDM, then push the installer. Deploying the configuration first means users open Claude for the first time and land directly in the third-party deployment, with no opportunity to sign in to claude.ai by mistake. ## 1. Build a configuration in the app Launch Claude Desktop. **Do not sign in or create an Anthropic account**; stay on the login screen. From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the configuration window. The window is organized into sections in the left sidebar. Work through them in order; each maps to a group of [configuration keys](/docs/third-party/claude-desktop/configuration), and the window validates values as you enter them. | Section | What you set | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connection** | Inference provider (Gateway, Claude API, Google Cloud's Agent Platform, Bedrock, Bedrock Mantle, or Foundry) and its credentials
Model list
Organization UUID
Optional credential-helper script | | **Workspace** | Which of Cowork, Code, and Chat are available
Allowed egress hosts for the sandbox
Disabled built-in tools
Allowed workspace folders | | **Connectors** | Managed MCP servers pushed to all users
Whether users can add their own local MCP servers
Whether desktop extensions (`.mcpb`) are allowed
Whether unsigned extensions are rejected | | **Telemetry & updates** | OpenTelemetry collector endpoint
Whether auto-updates are blocked, and the enforcement window if not
The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) | | **Limits** | Per-device token cap and its window length
Retention periods after which idle chats, Cowork tasks, and Code sessions are deleted, and the hold that suspends deletion | | **Appearance** | Persistent banner shown across the app window
Deployment display name and subtitle
Whether the signed-in user's identity is shown and exported (end-user attribution)
Whether feature announcements are shown | | **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL
Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window | | **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature
**Copy hostnames**, **Download .txt**, and **Test connectivity** actions | | **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) delivery model instead of a full MDM profile
Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key | When a managed (MDM-delivered) configuration is already present on the device, the configuration window opens read-only: it shows what the admin deployed, marks the configuration as organization-managed, and directs users to their IT administrator. To author a new configuration, use a device without a managed profile, or temporarily remove the profile. Profiles that set [only app-behavior keys](#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys) leave the window editable. ## 2. Export the profile Once your configuration tests successfully, click **Export** and choose a format: | Format | Platform | Deploy with | | --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `.mobileconfig` | macOS | Jamf, Kandji, Mosyle, Workspace ONE, or any Apple MDM | | `.reg` | Windows | Group Policy (import into a GPO), Intune (via custom ADMX or script), or any MDM that can write registry policy | | `.zip` (ADMX template) | Windows | Schema-only template for Intune or Group Policy; you enter values in the management console | | `.plist` (Profile Manifest) | macOS | Schema-only template for Jamf, ProfileCreator, or similar macOS tools | **Apply Changes** and **Export** do different things: * **Apply Changes** asks you to confirm, then writes the selected configuration to your own machine's Claude settings and relaunches the app, so you can test it end to end before deploying it. * **Export** writes a deployment file in the format you choose and leaves your local settings untouched. ### Creating profiles for multiple user groups Many organizations deploy distinct configurations to different populations: for example, a permissive profile for an engineering pilot group and a restricted profile for the broader rollout, or per-region profiles that point at different inference endpoints. The configuration window can hold multiple named configurations. Use the picker in the top-right of the window: * **New configuration** creates an empty configuration. * **Duplicate** copies the current configuration as a starting point for a variant. * **Rename** and **Delete** manage the list. * **Reveal in Finder** opens the on-disk location where saved configurations are stored. Selecting a configuration in the picker loads it for editing; the **applied** badge marks the one currently active on your machine. **Apply Changes** and **Export** each act on whichever configuration is selected, so you can test each one locally and export them independently. In your MDM, scope each exported profile to the corresponding device or user group. Targeting is handled by your MDM's assignment rules; the configuration name is for your authoring workflow and is not part of the deployed profile. On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap). ## 3. Allow required network egress The hosts the app needs to reach depend on the configuration you built: your inference provider's endpoint is always required, and each telemetry, update, and service setting you leave enabled adds its own hosts. The configuration window shows the exact allowlist for your settings and can export it as a text file for your network team. `downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the latest Claude Code binary, fetched at session start. Without it, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. The [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation) builds both components into the installer package and does not need this host. The app still requests the model catalog from `downloads.claude.ai` unless [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) names a mirror inside your network, and sessions start whether or not that request succeeds. Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the full list of hosts grouped by the setting that controls each one, and for the distinction between the perimeter firewall and the in-app sandbox allowlist. ## 4. Deploy the configuration Push the exported configuration through your MDM. The app reads from these locations: | Source | Path | Precedence | | ------------------ | -------------------------------------------------------------------------- | ---------- | | Managed (per-user) | `/Library/Managed Preferences//com.anthropic.claudefordesktop.plist` | Highest | | Managed (machine) | `/Library/Managed Preferences/com.anthropic.claudefordesktop.plist` | | | Local (user) | `~/Library/Application Support/Claude-3p/configLibrary/` | Lowest | A `.mobileconfig` profile delivered by MDM lands in the Managed Preferences locations automatically. Both managed paths are read; where a key appears in both, the per-user value wins. | Source | Path | Precedence | | -------------- | ----------------------------------------- | ---------- | | Machine policy | `HKLM\SOFTWARE\Policies\Claude` | Highest | | User policy | `HKCU\SOFTWARE\Policies\Claude` | | | Local (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` | Lowest | A Group Policy Object or Intune configuration profile writes to the registry policy paths. The hives are not merged: when machine policy is present (any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude`, including an empty string, and the key's unnamed default value when set), the app ignores `HKCU\SOFTWARE\Policies\Claude` entirely. Deploy the complete configuration to one hive; machine policy (`HKLM`) is the recommended location. Values must sit directly under `HKLM\SOFTWARE\Policies\Claude` or `HKCU\SOFTWARE\Policies\Claude`. The app never reads values nested in a subkey, as some ADMX-based and Policy CSP tooling writes them: they do not apply as configuration and do not count as machine policy being present. Write values as `REG_SZ` (`REG_DWORD` is also accepted for boolean and integer keys and is read as its decimal value). Avoid `REG_EXPAND_SZ`: the app counts it as machine policy being present but cannot read its contents, so a single `REG_EXPAND_SZ` value under `HKLM` disables user policy without supplying any configuration. The app cannot see `REG_QWORD`, `REG_MULTI_SZ`, or `REG_BINARY` values at all. In releases before v1.19367.0, the app read both hives and merged them key by key, with the `HKLM` value winning where a key appeared in both. Fleets that split keys across both hives must consolidate the full configuration into one hive before updating to v1.19367.0 or later. When a managed source sets any key other than the [app-behavior keys](#update-keys-and-managed-precedence) listed below, the managed configuration owns the device: it takes effect, the in-app configuration window becomes read-only, and locally authored values in `configLibrary/` are ignored. ### Update keys and managed precedence A small group of **app-behavior keys** is treated specially, so you can set an update policy, a restart window, or a network proxy from MDM without managing the whole configuration: * The update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, and `updateViaUpdatesHost`. * The configuration lifecycle keys [`relaunchEnforcementHours`](/docs/third-party/claude-desktop/configuration#relaunchenforcementhours) and [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes), which MDM can set from version 1.46388.1. * The network proxy keys `egressProxyUrl` and `egressProxyPacUrl`. See [Network proxy](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration). When a managed source sets only keys from this group (any of them), the device keeps its locally authored configuration and the configuration window stays editable. The group is still enforced as a unit: every key in it is resolved from the managed source alone, so a locally set or bootstrap-served value for any of them is ignored even if the profile sets only one. A profile that sets the update keys but not `relaunchEnforcementHours` or `configRecheckIntervalMinutes` therefore runs their defaults (24 hours and 10 minutes) on those devices, so set them in the same profile when you want other values. If the managed profile sets any other recognized key, the normal rule above applies and the whole configuration is managed. ## 5. Distribute the app Deploy the Claude Desktop installer to enrolled devices using your standard software-distribution mechanism. On launch, the app reads the managed configuration, detects the configured inference provider and credentials, and the sign-in screen offers users the option to start in Claude Desktop on 3P. ## 6. Deploy organization plugins (optional) If you're distributing [organization plugins](/docs/third-party/claude-desktop/extensions#organization-plugins-admin), push the plugin bundles to the org-plugins directory on each device alongside the configuration profile. Plugins are picked up at the next app launch. ## Next steps After deployment, confirm devices picked up the configuration with the checks in [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment). # Models and effort levels Source: https://claude.com/docs/third-party/claude-desktop/models Which models Claude Desktop on 3P offers, the default model and its starting effort level, per-model effort caps, display names, and 1M-context variants Claude Desktop on third-party (3P) builds the model picker in Chat, Cowork, and Code from your configuration. Your configuration decides which models the picker offers, which model and effort level each new conversation starts with, and which effort levels users can choose. You control all three with the keys under **Models** in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). The [configuration reference](/docs/third-party/claude-desktop/configuration#models) lists every field. ## Model list and default model [`inferenceModels`](/docs/third-party/claude-desktop/configuration#inferencemodels) lists the models the picker offers. Write each entry with the exact model ID your provider expects, such as `us.anthropic.claude-sonnet-5` on Amazon Bedrock or `claude-sonnet-5` on Google Cloud's Agent Platform. The first entry is the default model. New Chat conversations, Cowork sessions, and Code sessions start on the default model until a user picks another model. To control whether a user's choice carries over to later conversations and sessions, see [Start every conversation on the default model](#start-every-conversation-on-the-default-model). If you leave `inferenceModels` unset and your provider supports [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled), Claude Desktop fills the picker from the provider's model list at launch. The first discovered model is then the default model. Each entry is either a model ID string or an object. In an object, `name` holds the model ID and every other field is optional. Two of the optional fields change how the picker shows the model: * `labelOverride` sets the display name for an ID the picker can't turn into a readable name, such as a gateway routing alias or an Amazon Bedrock application inference profile ARN. Claude Desktop still sends `name` to your provider. * `supports1m: true` adds a second entry that shows the same name with **1M context window** beneath it. Set it only when your deployment accepts 1M-token requests for that model. Otherwise, requests from the 1M entry fail at the provider. Add `prefer1m: true` to the default model's entry to make its 1M entry the default selection. Users can still choose the standard entry. ## Effort levels An effort level sets how much thinking Claude puts into each response. Higher levels give more thorough answers but take longer and use more tokens. Users choose the level with the **Effort** control in the model picker. Each model starts at Anthropic's recommended level unless you configure otherwise. The **Effort** control marks the recommended level **Default**. ### Per-model effort cap [`maxEffort`](/docs/third-party/claude-desktop/configuration#inferencemodels) on an `inferenceModels` entry sets the highest effort level Claude Desktop offers for that model in Chat, Cowork, and Code. Set it to `low`, `medium`, `high`, `xhigh`, or `max`. The picker shows `xhigh` as **Extra**. The **Effort** control doesn't offer levels above the cap. In Code sessions, the cap also limits Claude Code's own effort settings, such as a `CLAUDE_CODE_EFFORT_LEVEL` environment variable or the `/effort` command. If a model's recommended level is above its cap, the model starts at the cap. If Claude Desktop doesn't recognize the `maxEffort` value, it caps the model at low. ### Starting effort level for the default model [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort) sets the effort level the default model starts at, in place of its recommended level. Other models keep their recommended level. If you set a level the default model doesn't offer, or one above its `maxEffort`, the default model starts at the nearest lower level it offers. `defaultModelEffort` also applies when [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list. ### Models without an Effort control Some model IDs, such as a gateway routing alias, don't name a specific Claude model. For such a model, the picker shows no **Effort** control, so users can't change its effort level. Its conversations and sessions never run above the `maxEffort` on its entry. When such a model is the default model, its conversations and sessions run at [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort), up to that cap. With only `maxEffort` set, they run at that cap. ## Start every conversation on the default model Set [`alwaysStartWithDefaultModel`](/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) to `true` to start every new Chat conversation, Cowork session, and Code session on the [default model](#model-list-and-default-model) at its [starting effort level](#effort-levels), not on the user's last choice. When the user picks a model or effort level, it applies only for that conversation or session. If you leave `alwaysStartWithDefaultModel` unset, the default model and its starting effort level apply until a user picks a different model or effort level. Claude Desktop remembers that choice and starts the user's new conversations and sessions from it. When you turn the setting on, Claude Desktop keeps the choices users saved earlier. If you later turn it off, those choices apply again. `alwaysStartWithDefaultModel` also applies when [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list. ## Example configuration The following configuration offers Claude Sonnet 5, with a 1M-context variant, and Claude Opus 5. It makes Claude Sonnet 5 the default model at medium effort, caps both models at high effort, and starts every new conversation and session from those defaults: ```json theme={null} { "inferenceModels": [ { "name": "claude-sonnet-5", "supports1m": true, "maxEffort": "high" }, { "name": "claude-opus-5", "maxEffort": "high" } ], "defaultModelEffort": "medium", "alwaysStartWithDefaultModel": true } ``` With this configuration, a user who starts a new Cowork session sees Claude Sonnet 5 selected at medium effort. The **Effort** control offers low, medium, and high for every entry. In that session, the user can switch to Claude Opus 5, which starts at its recommended high effort, or raise Claude Sonnet 5 to high. The session keeps either choice. The user's next new conversation or session opens on Claude Sonnet 5 at medium effort again. The example is plain JSON, which is the form a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) response and the Linux managed file use. For a macOS profile or the Windows registry, encode the same values as the [Value types](/docs/third-party/claude-desktop/configuration#value-types) section describes. # Network proxy Source: https://claude.com/docs/third-party/claude-desktop/network-proxy How Claude Desktop on 3P and the Claude Code engine it runs use your network proxy: the default behavior, pinning a proxy from managed configuration, what is and is not routed through it, and how to troubleshoot. Claude Desktop on 3P works behind a corporate HTTP proxy without extra configuration in most environments. This page explains which proxy each part of the product uses, how to pin a specific proxy from managed configuration, which traffic does not go through the proxy at all, and how a separately deployed Claude Code policy interacts with it. Three parts of the product make network connections, and they do not all resolve the proxy the same way: * **The app**: the Claude Desktop window itself, including sign-in, the connection test, Web Fetch in Chat and Cowork sessions, managed MCP servers the app connects to, and plugin marketplace sync. * **The agent**: the Claude Code engine the app runs for every Chat, Cowork, and Code session. It sends inference requests and, in Code sessions, also makes its own web fetches, remote MCP connections, and plugin installs. * **Cowork's sandboxed shell**: the isolated environment where commands the agent runs in a Cowork session (`curl`, `pip`, `npm`, and so on) execute. ## Default behavior With no proxy-related configuration, the app follows the operating system's proxy settings, including a PAC (proxy auto-configuration) script or automatic proxy detection if the OS is set up that way. PAC rules are evaluated per request, so different hosts can go to different proxies or connect directly, exactly as the script says. The agent does not read the OS settings itself. When a session starts, the app asks the OS which proxy applies to your inference endpoint (your gateway URL, or the provider endpoint for Google Cloud's Agent Platform, Amazon Bedrock, and Microsoft Foundry) and hands that one proxy to the agent as `HTTPS_PROXY` and `HTTP_PROXY`, with `NO_PROXY` set to `localhost,127.0.0.1,::1,.local`. The agent then uses that proxy for all of its own traffic. If the OS answer for the inference endpoint is a direct connection, the agent gets no proxy variables and connects directly. On macOS and Windows, Cowork's sandboxed shell also follows the OS proxy settings, including a PAC script, which the sandbox evaluates per request itself. On Linux, no proxy settings reach the sandboxed shell and its commands connect directly. A few limits apply to the agent regardless of how the proxy is chosen: * Only `http://` and `https://` proxies are handed to the agent. If the OS or PAC answer is a SOCKS proxy, the app skips it and the agent connects directly. * There is no interactive proxy sign-in. If your proxy requires a username and password, neither the app nor the agent can prompt for them and requests fail. Run a local forwarding proxy that authenticates upstream on the device (for example, Cntlm or Px) and point the OS or the pinned key at it. * If your proxy intercepts TLS, see [TLS-intercepting proxies](#tls-intercepting-proxies) below. ## Pin a proxy from managed configuration Pinning requires Claude Desktop 1.44121.1 or later. Earlier releases ignore the `egressProxyUrl` and `egressProxyPacUrl` keys and keep following the OS proxy settings. If you want the app, the agent, and (on macOS and Windows) Cowork's sandboxed shell to use a specific proxy regardless of what the device's OS settings say, set one of two managed configuration keys: | Key | Value | Effect | | ------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `egressProxyUrl` | An `http://` or `https://` proxy URL, for example `http://proxy.example.com:8080` | The app sends its traffic through this proxy, and the agent receives it as `HTTPS_PROXY` and `HTTP_PROXY` in every session on the device. On macOS and Windows, commands in Cowork's sandboxed shell receive the same variables. Loopback and `.local` hosts still connect directly. | | `egressProxyPacUrl` | An `http://` or `https://` URL to a PAC script, for example `http://wpad.example.com/proxy.pac` | The app evaluates the script per request. The agent receives the single proxy the script returns for your inference endpoint. On macOS and Windows, Cowork's sandboxed shell is handed a copy of the script when the sandbox starts and evaluates it per request itself. If both keys are set, this one wins. | Both keys are read once at launch; a change takes effect the next time the app starts. While either key is set, the OS proxy settings are ignored for the app, the agent, and (on macOS and Windows) Cowork's sandboxed shell; with neither key set, the sandboxed shell keeps following the OS settings as described under [Default behavior](#default-behavior). SOCKS URLs and URLs with embedded credentials (`user:password@`) are rejected. If you point the key at a local forwarding proxy on the device, give it as `http://127.0.0.1:`. Cowork's sandboxed shell reaches the device's loopback address through a host alias, so an `https://` loopback proxy cannot pass TLS verification from inside the sandbox and the shell's commands fail to connect; the app logs a warning at sandbox start when it sees that combination. These keys are read from an MDM profile, registry policy, or local configuration file only; they are ignored if returned from a bootstrap server. They also follow the same precedence rule as the update keys: when an MDM profile or registry policy sets any key in that group, values for these keys in a local configuration file are ignored. See [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence). On Linux, or wherever you deploy the local configuration file, the key sits alongside your other settings: ```json /etc/claude-desktop/managed-settings.json theme={null} { "egressProxyUrl": "http://proxy.example.com:8080" } ``` In a macOS configuration profile the same key is a `egressProxyUrlhttp://proxy.example.com:8080` pair in the `com.anthropic.claudefordesktop` payload, and on Windows it is a `REG_SZ` value named `egressProxyUrl` under `HKLM\SOFTWARE\Policies\Claude`. See [Value types](/docs/third-party/claude-desktop/configuration#value-types) and [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the surrounding profile and registry structure. Three behaviors to plan for: * If the pinned proxy is unreachable, requests fail. The app does not fall back to a direct connection. * If a pinned PAC script cannot be downloaded, the app connects directly and the agent gets no proxy. Cowork's sandboxed shell gets its own copy of the script through a separate download when the sandbox starts; if that download fails, the shell connects directly too. Combine the key with network-layer egress rules if a silent fallback to direct is not acceptable (see the warning below). * Inside Cowork's sandboxed shell, a pinned PAC script's `myIpAddress()` returns the sandbox's internal address rather than the device's, so a script that chooses a proxy by client subnet gives the shell its off-network answer. ## What is and is not routed The table summarizes which proxy source each kind of traffic follows. "App proxy" means the pinned key if one is set, otherwise the OS settings, with PAC rules applied per request. | Traffic | Proxy it follows | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | App window, in-app sign-in, connection test, model list | App proxy | | Inference requests from Chat, Cowork, and Code sessions | The single proxy resolved for the inference endpoint (from the pinned key or the OS), or Claude Code managed settings if deployed | | Agent web fetch, remote MCP servers, and plugin installs in Code sessions | Same single proxy as inference | | Web Fetch and managed MCP servers in Chat and Cowork sessions | App proxy (the app makes these connections) | | Plugin marketplace sync and `aws` CLI calls the app makes for Bedrock sign-in | App proxy, resolved for the specific host | | Cowork sandbox download from `downloads.claude.ai` | App proxy | | Telemetry and crash reports to Anthropic, if enabled | App proxy | | OpenTelemetry export to your collector | App proxy for the app's own events; the same single proxy as inference for Claude Code metrics and logs | | Commands in Cowork's sandboxed shell on macOS and Windows | The pinned key if one is set (a pinned PAC script is evaluated per request inside the sandbox), otherwise the OS proxy settings | | Commands in Cowork's sandboxed shell on Linux | None; commands connect directly | | The agent in an [SSH remote Code session](/docs/third-party/claude-desktop/ssh-remote-sessions) | None from the device; the remote host's own network route applies | | App update check and download | OS proxy settings only | | Credential helper and header helper scripts you configure | None injected; the script's own environment applies | | Brokered Microsoft Entra sign-in (Company Portal on macOS, Web Account Manager on Windows) | The OS broker's own settings | | Pages opened in the system browser | The browser's own settings | ## Traffic that bypasses the app proxy Some traffic never uses the pinned key or the proxy the app resolved, and it is worth being explicit about each case and what you can do about it. * **App updates.** Checking for and downloading Claude Desktop updates is handled by the OS-native updater on macOS and Windows, which follows the OS proxy settings only. This is the one app-controlled path with no admin-side option other than the OS proxy: neither the pinned key nor Claude Code managed settings reach it. If updates must not traverse a direct path, configure the OS proxy on the device or distribute updates yourself with [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration) and your software-distribution tool. On Linux, updates come from your package manager, which has its own proxy configuration. * **Commands in Cowork's sandboxed shell on Linux.** No proxy settings reach the Cowork sandbox on Linux, so `curl`, `pip`, `npm`, `git`, and anything else the agent runs there connect directly. On macOS and Windows those commands follow the pinned key, or the OS proxy settings when no key is set, and are not a bypass. On every platform, [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/web-tools) still applies inside the sandbox and sits in front of any proxy: a host must be on the allowlist to be reachable at all, and an allowed host is then reached through the proxy. * **SSH remote Code sessions.** When a user runs a Code session on another machine through [`sshHostAllowlist`](/docs/third-party/claude-desktop/ssh-remote-sessions), the agent runs on that host and connects to the inference endpoint from there. Claude Desktop passes the endpoint address to the remote agent but not the pinned key, the device's OS proxy settings, or proxy variables from Claude Code managed settings on the device. The host's own network route and any Claude Code managed settings installed on the host apply instead. See [Inference credentials on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#inference-credentials-on-the-remote-host). * **Pages opened in the system browser.** Some sign-in flows open your default browser. That traffic follows the browser's proxy settings, which normally track the OS; pin it with the browser's own policy (for example, the Chrome or Edge `ProxySettings` policy) or the device's network profile. * **Brokered Microsoft Entra sign-in.** When [brokered authentication](/docs/third-party/claude-desktop/entra-broker) is in use, the token request is made by Company Portal (macOS) or Web Account Manager (Windows), not by the app. Those components follow the OS proxy settings; configure them through the same MDM that manages the device. * **Helper scripts.** An `inferenceCredentialHelper` or MCP `headersHelper` script runs with the app's environment and no injected proxy variables, because helpers typically talk to internal vaults or identity providers that should not go through the inference proxy. If a helper needs a proxy, set it inside the script. * **Programs that ignore proxy variables.** The agent passes `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` to the programs it launches on the device, but a program that does not honor those variables connects directly if the network allows it. The only complete control for this case is blocking direct egress at the network layer. A proxy setting is routing, not enforcement. Nothing on this page prevents a process on the device from connecting directly if the network permits it. If you need a guarantee that traffic leaves only through your proxy, block direct egress at the firewall or secure web gateway and allow only the proxy. The inverse also holds: on an open network, a misconfigured or unreachable PAC script can quietly result in direct connections. ### The agent uses one proxy The agent sends all of its own traffic (inference, and in Code sessions its web fetches, remote MCP connections, and plugin installs) through the one proxy resolved for your inference endpoint. Per-host PAC rules are not re-evaluated inside the agent. For most organizations this is the desirable outcome: everything the agent does is logged and inspected at one place, with nothing further to configure. It needs attention only when that one proxy is not right for everything the agent reaches: typically some hosts (an internal MCP server, a private package registry, a self-hosted plugin marketplace) must be reached directly while the proxy only carries public traffic, or the reverse. In order of preference: 1. Let the proxy these devices use carry both kinds of traffic. Nothing else needs configuring. 2. Otherwise, list the domains that must connect directly in `NO_PROXY` through Claude Code managed settings (see the next section), using leading-dot suffixes such as `.example.corp`, and accept that everything not listed goes to the proxy. The inverse edge case: if your PAC script returns `DIRECT` for the inference endpoint (common when the gateway is on your internal network), the agent gets no proxy at all, even for hosts the script would proxy. If the agent's other traffic must go through a proxy in that layout, set `HTTPS_PROXY` and a `NO_PROXY` entry for the gateway's domain through Claude Code managed settings. ## Interaction with Claude Code managed settings The precedence described here requires Claude Desktop 1.44121.1 or later, the same release as the pinned-proxy keys above. If you deploy Claude Code [managed settings](https://code.claude.com/docs/en/settings#settings-files) on the device (a `managed-settings.json` file or an OS-level Claude Code policy) and its `env` block sets `HTTPS_PROXY`, `HTTP_PROXY`, or `NO_PROXY`, those values apply to the agent in Chat, Cowork, and Code sessions alike and take precedence over what the app would have supplied. Precedence is per variable: a managed `HTTPS_PROXY` replaces the app's proxy while the app's loopback `NO_PROXY` entries stay in place, and a managed `NO_PROXY` replaces the app's list (the loopback entries are appended for you when the app is also supplying the proxy). See Claude Code's [network configuration](https://code.claude.com/docs/en/network-config) page for the variables themselves. ```json managed-settings.json theme={null} { "env": { "HTTPS_PROXY": "http://proxy.example.com:8080", "NO_PROXY": "localhost,127.0.0.1,::1,.example.corp" }, "parentSettingsBehavior": "merge" } ``` Set `parentSettingsBehavior` to `"merge"` whenever you deploy a Claude Code managed-settings file alongside Claude Desktop on 3P: without it, the presence of that file makes Claude Code ignore the policy Claude Desktop supplies (network and filesystem sandbox, allowed MCP servers), even if the file only sets proxy variables. [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) explains the merge behavior. `NO_PROXY` matching in the agent follows these rules: * A bare hostname matches that host exactly. To cover a domain and its subdomains, use a leading dot: `.example.corp` matches `example.corp` and `api.example.corp`. * IP addresses match literally. CIDR ranges such as `10.0.0.0/8` are not supported. * `host:port` entries match that host on that port only. * `*` disables the proxy entirely, and only when it is the whole value; it is not a wildcard inside a list. These settings reach the agent process only. The app itself and Cowork's sandboxed shell keep the proxy behavior described above, and the other paths listed under [Traffic that bypasses the app proxy](#traffic-that-bypasses-the-app-proxy) are likewise unaffected by Claude Code managed settings. ## TLS-intercepting proxies If your proxy performs TLS interception, it presents its own certificate authority. The app trusts the operating system's certificate store. On macOS, the app also configures the agent to trust the System keychain in addition to the bundled CA roots, so a corporate CA installed there normally works without extra setup. If inference or tool requests still fail certificate verification, the CA was likely added with policy-restricted trust: certificates installed via `security add-trusted-cert -p ssl …` are trusted by Safari and Chrome but are not picked up by the agent's keychain reader. Re-add the CA with full root trust (omit `-p`): ```bash theme={null} sudo security add-trusted-cert -d -r trustRoot \ -k /Library/Keychains/System.keychain /path/to/corp-ca.pem ``` If the certificate is MDM-managed and you cannot change how it is installed, set `NODE_EXTRA_CA_CERTS` as a fallback, then quit and relaunch Claude: ```bash theme={null} security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem launchctl setenv NODE_EXTRA_CA_CERTS "$HOME/corp-ca.pem" ``` `launchctl setenv` makes the variable visible to apps launched from Finder or the Dock (shell-profile exports only reach terminal sessions). It applies until the next reboot; to make it permanent, run the command from a LaunchAgent at login. ## Troubleshoot **"Can't reach" banner.** The app could not get a response from the inference host the banner names. Behind a proxy this usually means the proxy resolved for that host is unreachable, requires a sign-in the app cannot perform, or does not allow the host. Use **Copy report** on the banner to capture the details, confirm the device's OS proxy settings (or the pinned key) point at a reachable HTTP proxy, and confirm the proxy allows the inference host listed in [Required egress paths](/docs/third-party/claude-desktop/telemetry#required-egress-paths). **Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](/docs/third-party/claude-desktop/data-storage). When a key is pinned, startup logs `[egress-proxy] pinned to fixed proxy at proxy.example.com:8080; OS proxy settings ignored` (or `pinned to PAC script at …`). When a session starts, the log records the proxy handed to the agent, for example `Resolved system proxy for Code sessions: http://proxy.example.com:8080`, and a `Skipping SOCKS proxy entry` line if the OS answer was SOCKS. If Claude Code managed settings supplied any proxy variable, a line names the variables it set or replaced and the settings file they came from. For Cowork's sandboxed shell, `cowork_vm_node.log` in the same directory records `[VM:start] guest egress pinned to fixed proxy at …` (or `PAC script at …`) when the sandbox starts with a key pinned, and `[VM:start] PAC fetch from … failed (…); guest connects directly` if the sandbox's copy of the script could not be downloaded. **Agent connects directly while the app is proxied.** The OS or PAC answer for the inference endpoint was `DIRECT` or SOCKS-only. Adjust the PAC rule for the inference host, or pin `egressProxyUrl`. **Web fetches or MCP connections fail in Code sessions but inference works.** Either the proxy resolved for the inference endpoint does not carry that traffic, or the answer for the inference endpoint was `DIRECT` and the agent has no proxy. See [The agent uses one proxy](#the-agent-uses-one-proxy). **Certificate errors.** See [TLS-intercepting proxies](#tls-intercepting-proxies). ## Related * [Configuration reference](/docs/third-party/claude-desktop/configuration) for `egressProxyUrl`, `egressProxyPacUrl`, and `coworkEgressAllowedHosts` * [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the hosts your proxy must allow * [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code) for how Claude Code managed settings combine with Claude Desktop policy * [Web tools](/docs/third-party/claude-desktop/web-tools) for `coworkEgressAllowedHosts` # Overview Source: https://claude.com/docs/third-party/claude-desktop/overview Run Claude Desktop against your own cloud inference provider Claude Desktop on third-party (3P) is a deployment mode of Claude Desktop that routes all model inference through a provider you configure: Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, any compatible gateway you operate, or the Anthropic API directly. The app runs from a bundled local web application, and conversation history is stored on the user's device. You get the full Claude Desktop experience (Chat, Cowork, and Code, including file creation, multi-step research, and sub-agent coordination) with inference and billing handled by the provider you choose. ## Who it's for Claude Desktop on 3P is designed for organizations whose security, regulatory, or contractual requirements prevent them from sending data through Anthropic's first-party products (claude.ai or the Claude API). Typical deployments include: * **Highly regulated enterprises on 3P only:** organizations that use third-party inference for regulatory or security reasons * **International enterprises with data residency requirements:** organizations that require in-region data residency and cannot send conversation data to the United States How far a deployment is separated from Anthropic depends on the provider you choose. On Google Cloud's Agent Platform and Amazon Bedrock, the cloud provider processes conversation data in the region you select. On Microsoft Foundry, Anthropic operates the Claude models, and residency follows the Foundry deployment type. Review [Data handling by provider](#data-handling-by-provider) and [Data residency and international deployment](#data-residency-and-international-deployment) before choosing a provider. If your organization can use Anthropic's first-party products directly, standard Claude Desktop with [Cowork](/docs/cowork/overview) on a Team or Enterprise plan is simpler to deploy and releases new features more quickly than Claude Desktop on 3P. Choose Claude Desktop on 3P when routing inference through Anthropic's API is not an option. ## Architecture Claude Desktop on 3P keeps the standard feature set and relocates inference to the provider you configure. | Component | Standard Claude Desktop | Claude Desktop on 3P | | ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Model inference | Anthropic API | Your configured provider endpoint (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or gateway), or the Anthropic API | | Web application | Loaded from claude.ai | Bundled inside the desktop app | | User identity | Anthropic account | Local device identity only (Anthropic account when managed from the claude.ai admin console) | | Conversation storage | Anthropic backend | Local disk on the user's machine | | Code execution sandbox | Local VM | Local VM (identical) | | Configuration | Admin console at claude.ai | OS-native configuration (MDM-managed or per-user), a bootstrap server, or the claude.ai admin console | The desktop app detects 3P mode at launch from the configured inference provider. When a provider and its credentials are present, the sign-in screen offers the option to skip Anthropic authentication and start the app using your inference-provider configuration instead. ### Security posture * **Conversation content goes only to your configured endpoint.** The app sends prompts, responses, files, and tool outputs only to your configured inference endpoint and stores them only on the local machine. What happens to that content at the endpoint depends on the provider, as described under [Data handling by provider](#data-handling-by-provider). * **Sandboxed tool execution.** Shell commands run in the hardened Cowork VM; file access is scoped to your allowed folders and web fetches to your egress allowlist. * **Auditable telemetry.** Crash reports and product analytics are scrubbed of conversation and user data before being sent to Anthropic, and can be fully disabled via configuration keys. Independently, you can export session activity to your own OpenTelemetry collector. The export is metadata only by default, with prompt and tool content available as an explicit opt-in. * **Centrally managed.** Configuration is delivered through your existing MDM (Jamf, Intune, Workspace ONE, Group Policy), a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), or the [admin console](/docs/third-party/claude-desktop/admin-console). End users cannot override a configuration that MDM delivers. For a detailed treatment of the threat model, sandbox boundaries, and data flows, request access to the [Claude Cowork Desktop Security Architecture Overview](https://trust.anthropic.com/resources?s=2a7bbzo1lyymvdt551q7kl\&name=claude-cowork-desktop-security-architecture-overview) on Anthropic's Trust Center. For architecture, telemetry, and controls information specific to Claude Desktop on 3P, see the [Claude Desktop Security Overview (Third-party platforms)](https://trust.anthropic.com/resources?s=0c8rx4s7mm5ierz8ppetfs\&name=claude-cowork-security-overview-\(third-party-platforms\)) on the Trust Center. ## Data handling by provider Once conversation content reaches your inference endpoint, how it is handled depends on the provider you configured. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by [Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/data-governance) and [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html) respectively. Microsoft Foundry offers Claude models in two hosting options, Hosted on Azure and Hosted on Anthropic, and you choose one when you configure the model deployment in Microsoft Foundry. Under both options, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. Your use of Claude through Microsoft Foundry is subject to Anthropic's data use terms. Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details. For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](/docs/third-party/claude-desktop/claude-api) page. For an [LLM gateway](/docs/third-party/claude-desktop/gateway) you operate, data handling depends on the upstream provider your gateway routes each request to. ## Data residency and international deployment **Google Cloud's Agent Platform and Amazon Bedrock:** Inference requests go directly from the user's machine to the regional endpoint you configure. Conversation data goes only to that endpoint, to local disk, and optionally to your configured OpenTelemetry collector. Residency is determined by: 1. The cloud region you select for inference 2. The physical location of the user's device, where conversations are persisted For multi-region organizations, deploy distinct MDM configuration profiles per geography so each user population points at an in-region endpoint. Google Cloud's Agent Platform and Amazon Bedrock each offer Claude models in the EU, UK, and Asia/Pacific regions; consult your provider's model-availability documentation for the current list. **Microsoft Foundry:** Residency is set by the [hosting option and deployment type](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) you select when you deploy the model in Microsoft Foundry. Deployments hosted on Azure offer two deployment types: Global Standard, which may run inference in any available region, and US Data Zone Standard, which keeps inference within the United States. Deployments hosted on Anthropic offer Global Standard only. As with the other providers, conversation history is stored on the user's device. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details. ## Public sector and highly regulated environments This section applies when using Google Cloud's Agent Platform or Amazon Bedrock. Because inference runs in your cloud tenant, Claude Desktop on 3P operates inside whatever compliance boundary your provider and region give you. The desktop application itself contacts Anthropic-operated hosts only to download the VM workspace bundle and Claude CLI binary (always required), and for crash reporting, product analytics, non-essential services (connector favicons, artifact previews, and MCP Apps widgets), auto-updates, and the published model catalog that labels the model picker. Each of the latter five can be disabled independently via managed configuration. With Anthropic-bound telemetry, non-essential services, updates, and the [model catalog fetch](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM workspace bundle and Claude CLI binary at session start. An app managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still contacts `api.anthropic.com` at launch and at each configuration re-check, and `claude.ai` at sign-in. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code) sessions otherwise checks each fetched domain with `api.anthropic.com`. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the full set of network paths and how to lock them down. ## HIPAA For Google Cloud's Agent Platform and Amazon Bedrock, Claude Desktop on 3P does not send user data, prompts, or completions to Anthropic, so Anthropic does not interact with PHI a user may upload to Claude Desktop on 3P. Claude Desktop on 3P transmits that data only to your cloud service provider and to any remote MCP servers you choose to configure. For a HIPAA-compliant solution, ensure you have a BAA in place with your cloud service provider and review any MCP servers for HIPAA compliance before connecting them to Claude Desktop on 3P. You don't need to disable telemetry to meet HIPAA requirements, because Anthropic's telemetry carries only redacted crash reports and aggregated usage metrics, never user data, prompts, or completions. For Microsoft Foundry, HIPAA readiness is not available. Anthropic operates the Claude models in Microsoft Foundry and processes conversation data, as described under [Data handling by provider](#data-handling-by-provider), and Anthropic's HIPAA readiness arrangement (a signed BAA plus safeguards for processing PHI through the Claude API) does not cover Microsoft Foundry. See [What HIPAA readiness does not cover](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#what-hipaa-readiness-does-not-cover) in the Claude API documentation. If your deployment must handle PHI, configure Google Cloud's Agent Platform or Amazon Bedrock as the inference provider and put a BAA in place with that provider. ## Next steps Roll out Claude Desktop on 3P to your organization with MDM, or configure a single machine for evaluation. Every managed-configuration key, what it does, and recommended security profiles. Deploy MCP servers, plugins, skills, and hooks across your fleet. What the app sends to Anthropic, how to turn it off, and the firewall allowlist you'll need. # SSH remote sessions in Claude Desktop on 3P Source: https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions How Code sessions run on a remote host over SSH in Claude Desktop on 3P, the sshHostAllowlist key that enables them, which inference credentials work on a remote host, and what to check before turning them on An SSH remote session is a [Code](/docs/third-party/claude-desktop/code) session whose Claude Code engine runs on another machine that the user reaches over SSH, while the session's interface stays in Claude Desktop on the user's device. Claude Desktop connects to the host, places the engine there, and starts the session with the inference credential and policy from your managed configuration. Users can work on code that lives on a development server, a build box, or a cloud workstation without copying it to their device. In Claude Desktop on third-party (3P), SSH remote sessions are off until you set the [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) key, because enabling them sends your inference credential to the hosts users connect to. SSH remote sessions are in beta in Claude Desktop on 3P and require Claude Desktop 1.40609.0 or later. The in-app configuration window marks `sshHostAllowlist` with a **Beta** pill. ## How a remote session works 1. **Connect.** The user picks an SSH host from the environment picker in Code, or adds one by entering its address, port, and an identity file. Claude Desktop connects with its built-in SSH client, applies the host's entry from the device's `~/.ssh/config` (see [SSH configuration on the device](#ssh-configuration-on-the-device)), and prompts in the app if the host asks for a password or a one-time code. 2. **Deploy.** Claude Desktop places a remote server and the Claude Code engine under `~/.claude/remote/` in the SSH user's home directory on the host ([Host requirements](#host-requirements) lists every path) and reuses them on later connections. 3. **Run.** The remote server starts the engine on the host with the inference credential and policy from your managed configuration. Every file read, edit, shell command, and git operation runs on the host, in the working directory the user chose there. Claude Desktop connects to [managed MCP servers](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin) from the device and exposes them to the engine as tools. 4. **Stream.** Claude's responses and tool output stream back to Claude Desktop. Permission prompts appear in Claude Desktop, and the engine waits on the host until the user answers. The engine keeps running on the host through a dropped SSH link, device sleep, or the user quitting Claude Desktop. It finishes the current turn, or stops at a permission prompt, then idles until the user reopens the session. Reopening starts a fresh engine from the transcript stored on the host, so a turn that finished while the app was closed is shown in full; a turn still running at that moment is cut short and not continued automatically. While Claude Desktop is closed, no new turns run and the inference credential is not refreshed, so a turn that outlives the credential fails with an authentication error. An idle engine stays on the host, with the credential in its environment, until the user reopens, archives, or deletes the session, the host restarts, or a Claude Desktop update replaces the remote server on the host (deferred while a session on that host was active in the last 24 hours, for up to 7 days). ## Enable SSH remote sessions Set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) in your managed configuration. It appears in the **Code surface** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) while Code is enabled. | Value | Behavior | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Unset | Off, unless a Claude Code managed-settings `sshHostAllowlist` on the device allows hosts (see [Interaction with Claude Code managed settings](#interaction-with-claude-code-managed-settings-on-the-device)) | | `[]` | Off. Delivered by an administrator, `[]` also overrides a Claude Code managed-settings allowlist on the device | | `["*"]` | Users can connect to any host | | `["build01.corp.example.com", "*.dev.example.com"]` | Users can connect only to hosts that match an entry | While SSH remote sessions are off, the environment picker shows local sessions only, and any attempt to connect to a saved host is refused. Each entry is an exact hostname, an IP address, or a `*.` wildcard. * `*.dev.example.com` matches `dev.example.com` and any subdomain of it at any depth. * Matching is case-insensitive and ignores a `user@` prefix. * An IP address entry matches only that address. * Entries do not restrict the port. * A value that is not an array of strings counts as `[]`. Both the host the user entered and the `HostName` that the device's `~/.ssh/config` resolves it to must match an entry, so an alias that resolves to a host outside the list is refused. A `ProxyCommand` is permitted when the resolved hostname matches; the app does not inspect where the command itself connects. The allowlist limits which hosts Claude Desktop connects to. It does not limit what the device can reach over SSH from a terminal. Use network controls for that. For example, this Linux managed-settings file turns the feature on for one domain: ```json /etc/claude-desktop/managed-settings.json theme={null} { "sshHostAllowlist": ["*.dev.example.com"] } ``` In a `.mobileconfig` or registry policy, write the array as a JSON string as described under [Value types](/docs/third-party/claude-desktop/configuration#value-types). In a [bootstrap](/docs/third-party/claude-desktop/bootstrap) response, the key sits inside the `codeSurface` object. ### Interaction with Claude Code managed settings on the device Claude Code has its own `sshHostAllowlist` setting, which you can deploy on the device through a [Claude Code managed-settings file](https://code.claude.com/docs/en/settings#settings-files) or OS policy. The app resolves the two sources in this order: 1. `sshHostAllowlist` from the Claude Desktop configuration, when that configuration is delivered by an administrator: through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux), or by a bootstrap server the app trusts (a `bootstrapUrl` set through device management or covered by `trustBootstrapDelivery`; see [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent)). User-scope registry policy (`HKCU`) counts as applied locally. 2. `sshHostAllowlist` from Claude Code's managed settings on the device. 3. `sshHostAllowlist` from a Claude Desktop configuration the user applied locally in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#apply-locally-or-export-for-a-fleet). 4. Off. On devices where users applied the configuration locally, deploy `sshHostAllowlist` in Claude Code's managed settings. That restricts SSH without an MDM profile taking ownership of the whole configuration (see [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence)). ## Inference credentials on the remote host A remote session runs Claude Code on the SSH host with your organization's inference credential in its process environment, for as long as that process runs, including while Claude Desktop is closed. Anyone who can read that process's environment on the host, such as the same user account or a root user, can read the credential. List only hosts you trust with it, and prefer a credential that expires (single sign-on, or a credential helper that issues short-lived tokens) over a long-lived key. The remote engine uses only the credential Claude Desktop passes in its environment. It ignores credentials already on the host, such as an AWS profile or application default credentials, and Claude Desktop copies no credential files there. Credential kinds that live in a file on the device are refused at session start. | Provider | Works on a remote host | Refused at session start | | ------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [LLM gateway](/docs/third-party/claude-desktop/gateway) | Static API key, single sign-on, credential helper | | | [Claude API](/docs/third-party/claude-desktop/claude-api) | Static API key, Sign in with Claude Console, credential helper | | | [Microsoft Foundry](/docs/third-party/claude-desktop/foundry) | API key, in-app Entra ID sign-in, credential helper | | | [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock) | Bearer token, credential helper | In-app AWS sign-in (IAM Identity Center), named profile | | [Amazon Bedrock Mantle](/docs/third-party/claude-desktop/mantle) | Bearer token, credential helper | | | [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex) | In-app Workforce Identity sign-in, credential helper | In-app Google sign-in, service-account key or credentials file, application default credentials on the device | When the configured credential is a refused kind, the session fails before anything is deployed to the host, with the card [Remote sessions aren't available with this inference setup](#remote-sessions-aren%E2%80%99t-available-with-this-inference-setup). When the remote engine's credential expires during a turn, Claude Desktop obtains a new one on the device, by re-running a [credential helper](/docs/third-party/claude-desktop/credential-helper) or using a sign-in's refresh token, and sends it over the SSH connection. When the user signs out of the inference provider in the app, Claude Desktop ends the remote engine. The host needs its own network route to the inference endpoint and must trust the endpoint's certificate. Claude Desktop passes the endpoint address to the remote engine but not the device's proxy settings, CA certificates, or the user's shell variables such as `AWS_*` or `GOOGLE_*`. A gateway at `localhost` on the device is refused for remote sessions, because the host cannot reach it. ## Managed configuration on the remote host Most of the policy that Claude Desktop applies to a local Code session applies on the remote host too. The [Code page](/docs/third-party/claude-desktop/code#how-configuration-propagates) describes how each key reaches Claude Code. * `disableEssentialTelemetry` and `disableNonessentialTelemetry`. * `otlpEndpoint`, `otlpProtocol`, `otlpHeaders`, `otlpResourceAttributes`, and `otlpContentCapture`. Remote sessions appear in your collector under the same `service.name` as local Code sessions. A collector at `localhost` on the device is not forwarded. An `otlpHeadersHelper` runs on the device at session start, and the remote session keeps those headers for its lifetime. * `disabledBuiltinTools`, `builtinToolPolicy`, `autoModeEnabled`, and `disableBypassPermissionsMode`. * [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders), evaluated against the host's filesystem. `~` is the SSH user's home on the host, `%VAR%` entries are ignored, and Claude Desktop refuses to start a session in a directory outside every entry, so a fleet value such as `~/Documents/Claude` confines remote sessions to that path under the SSH user's home. A folder with `mode` set to `ro` is allowed on the host but not read-only there. * [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), evaluated on the host, so the working directories and the home directory it hides from shell commands are the SSH user's there. Hiding files from shell commands needs the host's sandbox dependencies (next item); on a host without them, or a Windows host, shell reads outside the working directories ask for approval instead, and the file-tool restriction applies regardless. Files a user attaches to a remote session stay readable, except on a Windows host, where the session's plugin files and attachments stay outside the file tools' reach under this key. * `coworkEgressAllowedHosts`, as Claude Code managed settings. The network and filesystem sandbox it produces with `allowedWorkspaceFolders` depends on the host having Claude Code's sandbox dependencies installed (see [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing)); without them, commands run unsandboxed and Claude Code shows a warning in the session. * `managedMcpServers`, as the Claude Code managed setting that keeps users from adding their own MCP servers. The managed servers themselves are reached from the device. * Plugins from your [allowed marketplaces](/docs/third-party/claude-desktop/extensions), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all. If the host has its own Claude Code managed settings, those take precedence over the policy Claude Desktop supplies, as described under [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions. ## Host requirements The host needs the following. * Linux or macOS on x86\_64 or arm64, or Windows on x64 or arm64. * An SSH server with the SFTP subsystem. On Windows, Microsoft's OpenSSH Server; with other SSH servers, the engine does not survive a dropped connection. * A POSIX shell, or PowerShell on Windows. * `git` on the path, for git features. * Up to about 700 MB of disk space in the SSH user's home directory, for the three Claude Code versions the app keeps. The Claude Code engine is a standalone executable with no runtime dependencies. The device needs the OpenSSH client (`ssh` and `ssh-keygen`). Claude Desktop runs the first `ssh` on the user's `PATH`; to pin a specific OpenSSH installation instead, set [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath) (beta, Claude Desktop 1.46388.1 or later) to the program's absolute path, and `ssh-keygen` is then taken from the same directory when present. If the pinned program is missing or cannot be run, SSH connections fail with an error that shows the configured path, rather than falling back to another `ssh`. By default, Claude Desktop makes the SSH connection with its built-in client and runs the device's OpenSSH tools only to evaluate the user's SSH configuration, look up host keys, and run the session's terminal. To have the device's OpenSSH client carry the connection itself, set [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) to `system-openssh` (beta, Claude Desktop 1.52386.0 or later). Your own OpenSSH build's Kerberos (GSSAPI), certificate, and `ssh_config` support then handles authentication. The program is the one `sshClientPath` names, or else the first `ssh` on the user's `PATH`, and it must be OpenSSH 7.6 or newer (on Windows, Win32-OpenSSH 9.4 or newer). On a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used instead. `builtin` selects the built-in client explicitly. A change applies to new connections, and sessions that are already connected keep their client. Claude Desktop writes the following into the SSH user's home directory on the host. Each user who connects gets their own copy. | Path on the host | Contents | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `~/.claude/remote/srv//` | The remote server that Claude Desktop talks to | | `~/.claude/remote/ccd-cli/` | The Claude Code engine, one file per version (the three most recent versions are kept) | | `~/.claude/remote/run//` | The server's socket, token, and log | | `~/.claude/remote/plugins//` | Plugins synced from the device | | `~/.claude/uploads//` | Files the user attached to a message. Not removed when the session ends | | `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](/docs/third-party/claude-desktop/data-storage) | Each side of a remote session needs its own network access. * Devices installed with the regular installer must reach `downloads.claude.ai`: Claude Desktop downloads the remote server there and uploads it to the host over SFTP. Devices installed with the [offline installer](/docs/third-party/claude-desktop/installation#offline-installation) don't: it bundles the remote server and the Claude Code engine for Linux x64 and arm64 hosts, and Claude Desktop uploads both over SFTP. Hosts on other platforms still need the download, so an offline-installed device that cannot reach `downloads.claude.ai` fails the session with a message saying the installer doesn't include remote components for that platform. * The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. With the regular installer, it downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it over SFTP. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry)). Blocking them does not affect the session. ### SSH configuration on the device Claude Desktop applies the host's entry in the user's `~/.ssh/config`: hostname, port, user, identity file, SSH agent, and `ProxyCommand`. * For hosts behind a bastion, configure a `ProxyCommand`. `ProxyJump` is not supported. * The host's key must already be in the device's `~/.ssh/known_hosts` as a plain entry; the app does not prompt to accept a new key and does not evaluate `@cert-authority` entries. Have users connect once from a terminal before adding the host in the app. * An identity file protected by a passphrase is skipped, not prompted for. Load it into the SSH agent, or use an unencrypted key. * For a host reached through a `ProxyCommand`, the app skips host key verification and relies on the command to authenticate the host. * The connection times out after 30 seconds. A larger `ConnectTimeout` in the host entry extends it. ## Troubleshoot ### SSH isn't allowed by your organization The `sshHostAllowlist` in effect on this device is unset, empty, or has no entry that matches the host; the card's details say which. Both the host as the user entered it and the `HostName` from the device's `~/.ssh/config` must match. Which configuration source supplies the key on a device follows [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). The connection test reports the same denial as "Your organization's settings do not allow this connection." ### SSH to this machine isn't available The host resolves to the device itself (`localhost`, `127.0.0.1`, or a tunnel or port forward that ends on the device) while `allowedWorkspaceFolders` restricts workspace folders. A session over SSH to the device reaches the same disk the policy restricts, so it is refused. Connect to a different host, or use a local session. ### Remote sessions aren't available with this inference setup The configured inference credential is one of the kinds listed as refused under [Inference credentials on the remote host](#inference-credentials-on-the-remote-host), or the inference endpoint is on the device itself. The card's details say which. Switch the deployment to a credential kind that works on a remote host, or point the app at an endpoint the host can reach. ### SSH host key verification failed The host's key is not in the device's `~/.ssh/known_hosts`, or it has changed. Connect to the host from a terminal on the device to record the current key, then retry. ## Related * [Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code) * [`sshHostAllowlist` in the configuration reference](/docs/third-party/claude-desktop/configuration#sshhostallowlist) * [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access) # Telemetry and egress Source: https://claude.com/docs/third-party/claude-desktop/telemetry What Claude Desktop on 3P sends to Anthropic, how to disable it, and the network paths your firewall needs to allow When Claude Desktop on third-party (3P) is configured with Google Cloud's Agent Platform, Amazon Bedrock, or Microsoft Foundry, the app sends conversation content only to your configured inference endpoint. The app does, by default, send a small amount of operational telemetry (crash reports and product analytics) that helps Anthropic diagnose issues and improve the product. Each category can be disabled independently via managed configuration. Data handling at the inference endpoint depends on the provider. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by the cloud provider. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page for each provider's data path. This page covers what each telemetry category contains, how to turn it off, and the complete set of outbound hostnames the app uses so you can configure your perimeter firewall. ## Telemetry categories ### Essential telemetry Crash reports, error stack traces, and performance timings. Contains diagnostic metadata (app version, OS, error type, redacted stack frames) but **never prompt or response content**. Attributed to your organization via `deploymentOrganizationUuid` so Anthropic support can find issues you report. | Setting | Default | Effect when `true` | | --------------------------- | ------- | ----------------------------------------- | | `disableEssentialTelemetry` | `false` | No crash or error data leaves the device. | Disabling essential telemetry opts you into a **manual support model**. Anthropic will have zero remote visibility into failures on your fleet, so to get help with an issue your team will need to collect application logs from affected machines and send them to Anthropic directly. Leave this enabled during initial rollout. ### Non-essential telemetry Product-usage analytics: feature adoption, session counts, UI interactions. Used to understand how Claude Desktop is used in aggregate. Contains no prompt or response content. Also gates the **Send** button in Help → Generate Diagnostic Report; with this disabled, diagnostic bundles can only be saved locally. | Setting | Default | Effect when `true` | | ------------------------------ | ------- | -------------------------------------- | | `disableNonessentialTelemetry` | `false` | No product analytics leave the device. | Leaving this enabled also adds `api.anthropic.com` to the [agent egress allowlist](#required-egress-paths) automatically, so Claude Code can deliver its usage telemetry from inside the sandbox. Allow that host at the perimeter too; it appears in the non-essential telemetry table below. ### Non-essential services Cosmetic third-party fetches: favicons for connectors shown in the UI, the sandboxed iframe that renders interactive artifact previews, and the sandboxed iframes that render [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can display. Disabling these degrades the UI (generic icons, static artifact previews, and connector tool results shown as text instead of widgets) but doesn't affect functionality. | Setting | Default | Effect when `true` | | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `disableNonessentialServices` | `false` | Favicon, artifact-preview, and MCP App widget fetches are blocked. Connectors that return MCP Apps show the tool's text result instead of the widget. | ### Auto-updates Checks Anthropic's update feed and downloads new builds. | Setting | Default | Effect when `true` | | -------------------- | ------- | ----------------------------------------------------------------------------------------- | | `disableAutoUpdates` | `false` | The app never checks for or downloads updates. Your IT team must redistribute new builds. | ## Sending telemetry to your own collector Independently of what's sent to Anthropic, you can export session activity to your own OpenTelemetry collector by setting `otlpEndpoint`. This is the recommended way to retain an audit trail in environments that disable Anthropic-bound telemetry. For third-party deployments, the export includes session metadata (event names, durations, token counts, result counts, errors) by default, but not message content. It also identifies the signed-in user; see [User attribution](#user-attribution). See [Monitoring](/docs/cowork/monitoring) for the event schema and the [`otlp*` keys](/docs/third-party/claude-desktop/configuration#otlpendpoint) in the configuration reference. The export carries logs and metrics. Cowork sessions, Code sessions, and the desktop application's own events arrive under the `service.name` values `cowork`, `claude-code-desktop`, and `claude-desktop` respectively. The app adds the collector host to the sandbox egress allowlist automatically, so `otlpEndpoint` does not need an entry in `coworkEgressAllowedHosts`; your perimeter firewall still needs to allow the host. For collector authentication headers, extra resource attributes, and the log level of the desktop application's own event stream, see [`otlpHeaders`, `otlpResourceAttributes`, and `otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpheaders) in the configuration reference. ### Collector endpoint and headers Set [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) to the base address of your collector's OTLP/HTTP receiver, for example `https://otel-collector.example.com:4318`. The app appends the OpenTelemetry request paths itself (`/v1/logs`, `/v1/metrics`, and `/v1/traces` when [traces](#traces-beta) are enabled), so enter the address without those suffixes. A path prefix in front of them, such as `https://observability.example.com/otlp`, is kept. The receiver must implement the OpenTelemetry protocol (OTLP) over HTTP in both its protobuf and JSON encodings, as an OpenTelemetry Collector does by default. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and set `otlpEndpoint` to the collector's address. Each device opens its own connection to the collector, so the collector must present a TLS certificate the operating system trusts. See [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy#tls-intercepting-proxies) if a TLS-intercepting proxy sits in between. [`otlpHeaders`](/docs/third-party/claude-desktop/configuration#otlpheaders) is a JSON object that maps each header name to its value, for example `{"Authorization":"Bearer ","X-Tenant":"agency"}`. As with the other object-typed keys described under [Value types](/docs/third-party/claude-desktop/configuration#value-types), write it as a JSON string. The app reads both keys at launch, so users must restart it after a change. If the collector refuses requests or cannot be reached, the app keeps working, shows no error, and drops the affected telemetry batches. Check the collector's own request logs to confirm data is arriving. For a collector credential that cannot be a static header, [`otlpHeadersHelper`](/docs/third-party/claude-desktop/configuration#otlpheadershelper) names a script on the device that prints the headers, and [`otlpAuthMode`](/docs/third-party/claude-desktop/configuration#otlpauthmode) set to `inference-credential` sends the user's own inference bearer token, which suits only a collector you operate. The configuration reference describes both. ### User attribution Every record sent to your collector carries the user's identity as two resource attributes, on all three `service.name` streams: * `enduser.id` — the signed-in user's identity. With an interactive sign-in flow (for example, Workforce Identity Federation or Google sign-in on Google Cloud's Agent Platform), this is the identity from the provider's claims, normally the user's email address. With credential methods that carry no identity claims (a static key, a credential helper, or an application default credentials file), it is the operating-system login name. * `process.owner` — the operating-system login name. `enduser.id` is the same identity the app shows in the sidebar and account menu, and is controlled by the [`endUserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) key: set it to `false` to remove the identity from both the app and the export. `process.owner` is not gated by that key — it is standard OpenTelemetry process metadata and is always present. A static value set under [`otlpResourceAttributes`](/docs/third-party/claude-desktop/configuration#otlpresourceattributes) overrides either attribute: a static `enduser.id` is always passed through — taking precedence over the signed-in identity, and surviving `endUserAttribution: false` — and a static `process.owner` replaces the login name. These attributes are attached only to the OpenTelemetry export; the Anthropic-bound telemetry described earlier on this page does not carry them. ### Exporter protocol The `otlpProtocol` key selects the transport for the telemetry export to your collector: `http/protobuf` (the default), `http/json`, or `grpc`. The protocol applies per session type: * [Code](/docs/third-party/claude-desktop/code) sessions export over the protocol as configured, including `grpc`. * Cowork and [Chat](/docs/third-party/claude-desktop/chat) sessions export over the protocol as configured, except that when `otlpProtocol` is `grpc` they export over `http/protobuf` instead on Windows, and on other platforms whenever the Claude Code engine is given an HTTP proxy (from the operating system's proxy settings, a [pinned proxy](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration), or `HTTPS_PROXY`/`HTTP_PROXY` in a Claude Code settings file). * The desktop application's own event stream (`claude-desktop`) always exports over `http/json`, whatever `otlpProtocol` is set to. These substitutions change the protocol only, not the endpoint. A stream that exports over HTTP while `otlpProtocol` is `grpc` still goes to the same `otlpEndpoint`; if that address is your collector's OTLP/gRPC receiver (conventionally port 4317), that telemetry never reaches the collector. To receive all three streams with one collector, set `otlpProtocol` to `http/protobuf` and point `otlpEndpoint` at the collector's OTLP/HTTP receiver (conventionally port 4318). ### Content capture To include content in the export, set `otlpContentCapture` to an array of categories: | Category | Captures | | -------------------- | --------------------------------------------------------------- | | `userPrompts` | User message text and conversation titles | | `assistantResponses` | Model response text | | `toolDetails` | Tool input arguments (for example, the web-search query string) | | `toolContent` | Tool output content | | `rawApiBodies` | Full inference request and response bodies | On Claude Desktop version 1.17377 or later, enabling `userPrompts` also captures model responses, even if `assistantResponses` is not listed. On those versions, no `otlpContentCapture` configuration captures user prompts without model responses. Conversation titles arrive on the desktop application's own stream (`claude-desktop`) as a `desktop_session_title_set` event that carries each Cowork and Code session's title and the Claude Code `session.id` to join on. The event is exported only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, and the title text is included only when `otlpContentCapture` includes `userPrompts`. Requires Claude Desktop 1.44121.1 or later. Content is exported only to your configured `otlpEndpoint`. Anthropic does not receive it. ### Traces (beta) The export carries logs (events) and metrics; it does not include traces unless you enable them. To export OpenTelemetry traces as well, set `otlpTracesEnabled` to `true`. Cowork and Code sessions then record a trace for each user interaction, with spans for model requests and tool executions, and every event emitted during a span carries that span's `trace_id` and `span_id`. This lets your backend correlate a prompt's events end-to-end natively, with no transformation on ingest. Traces use the same `otlpEndpoint` and `otlpProtocol` as the rest of the export, including the gRPC fallbacks described in [Exporter protocol](#exporter-protocol). Span and span-event content is gated by the same `otlpContentCapture` categories as events: with no categories enabled, traces carry metadata only (timing, tool names, durations, token counts). Captured content appears primarily on events; spans stay close to metadata. Two scope notes: * The metrics in this export don't carry trace context, so trace-based correlation covers traces and events. Correlate metrics with a session via the `session.id` attribute. * Trace export uses Claude Code's session-tracing beta, and the span structure may change while the feature is in beta. With `otlpEndpoint` set, `otlpTracesEnabled` alone decides whether Cowork and Code sessions export traces. Leaving it unset or `false` keeps traces off even when Claude Code's own settings on the device, including managed settings, turn tracing on (Claude Desktop 1.52386.0 or later). `otlpTracesEnabled` requires Claude Desktop **1.22209.0** or later. ## Required egress paths Claude Desktop on 3P has **two** independent network boundaries: 1. **Perimeter firewall:** your corporate network controls what the device can reach. The hostnames below are what you allowlist here. 2. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) key controls what the agent's web-fetch and shell tools can reach. This is independent of, and stricter than, the perimeter. The **Egress** section of the in-app configuration window is the authoritative source for your deployment. It computes the exact allowlist from your current settings, updates as you change them, and can export the list as a text file for your firewall team. Use the tables below as a static reference; defer to the configuration window for the precise set your build requires. All traffic is HTTPS on port 443. Allowlist by hostname (SNI); path-level rules aren't required. ### Always required | Host | Purpose | | --------------------- | ----------------------------------------------------------------------------- | | `downloads.claude.ai` | VM workspace bundle and Claude CLI binary, fetched at session start | | `downloads.claude.ai` | Claude Code model catalog (signed picker metadata), polled every 5–15 minutes | Without this host reachable, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. Devices installed with the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), which includes both components in the installer package, are not affected. The model catalog fetch is not needed to run the app: set [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false` to turn it off, or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) to fetch the catalog from a mirror inside your network. While the catalog is unreachable, sessions still start and the model picker keeps the names and effort options the app last fetched or shipped with. ### Inference provider The host(s) for your configured provider. These carry conversation content. | Host | Purpose | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-aiplatform.googleapis.com` | Model inference for single regions. The `global` region uses `aiplatform.googleapis.com`, and the `eu` / `us` multi-regions use `aiplatform.eu.rep.googleapis.com` / `aiplatform.us.rep.googleapis.com`. Replaced by the host of `inferenceVertexBaseUrl` if set. | | `oauth2.googleapis.com` | Google auth token exchange | | `sts.googleapis.com` | Google auth token exchange | | `accounts.google.com` | Google auth token exchange | | `iamcredentials.googleapis.com` | Google auth token exchange | | Host | Purpose | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bedrock-runtime..amazonaws.com` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. | | `bedrock..amazonaws.com` | Control plane (model discovery) | | `sts.amazonaws.com`, `sts..amazonaws.com` | STS token exchange (profile auth only) | | `portal.sso..amazonaws.com`, `oidc..amazonaws.com` | IAM Identity Center sign-in and token refresh, for [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock#in-app-aws-sign-in) and for named profiles that use IAM Identity Center. `` is `inferenceBedrockSsoRegion` (or the profile's `sso_region`) and can differ from the inference region. | With `inferenceBedrockBearerToken` set, the runtime and control-plane hosts are required. For AWS GovCloud regions (`us-gov-*`), the app automatically uses the FIPS endpoints instead: `bedrock-runtime-fips..amazonaws.com` and `bedrock-fips..amazonaws.com`. | Host | Purpose | | --------------------------------- | -------------------------------------------------------------------------- | | `bedrock-mantle..api.aws` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. | | Host | Purpose | | ---------------------------------- | -------------------------------------------------------------------------- | | `.services.ai.azure.com` | Model inference. Replaced by the host of `inferenceFoundryBaseUrl` if set. | | `login.microsoftonline.com` | Entra ID auth (interactive sign-in only) | | Host | Purpose | | --------------------------------- | --------------- | | Host of `inferenceGatewayBaseUrl` | Model inference | | Host | Purpose | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api.anthropic.com` | Model inference; token exchange and API-key creation during browser sign-in | | `platform.claude.com` | Browser sign-in page. Dialed only when no static key or credential helper is configured; the in-app Egress list includes it for every Claude API deployment. | ### Auto-updates (`disableAutoUpdates: false`) | Host | Purpose | | --------------------- | ------------------------------------------------------------------ | | `claude.ai` | Update feed | | `api.anthropic.com` | Update feed (releases.claude.com when updateViaUpdatesHost is set) | | `downloads.claude.ai` | Update binaries | With [`updateViaUpdatesHost`](/docs/third-party/claude-desktop/configuration#updateviaupdateshost) set to `true`, the app reads the update feed from `releases.claude.com` instead of `claude.ai` and `api.anthropic.com`, so those two hosts are no longer needed for updates. Update binaries still come from `downloads.claude.ai`. ### Essential telemetry (`disableEssentialTelemetry: false`) | Host | Purpose | | ---------------------------------- | ------------------------- | | `*.sentry.io` | Crash and error reporting | | `*.ingest.us.sentry.io` | Crash and error reporting | | `sentry.io` | Crash and error reporting | | `browser-intake-datadoghq.com` | Performance timing | | `browser-intake-us3-datadoghq.com` | Performance timing | | `browser-intake-us5-datadoghq.com` | Performance timing | | `browser-intake-ap1-datadoghq.com` | Performance timing | | `browser-intake-ap2-datadoghq.com` | Performance timing | | `browser-intake-datadoghq.eu` | Performance timing | | `browser-intake-ddog-gov.com` | Performance timing | The `sentry.io` apex is listed alongside the wildcards because some firewalls don't match it under `*.sentry.io`, and `*.ingest.us.sentry.io` is listed separately for firewalls that match wildcards one label deep. ### Non-essential telemetry (`disableNonessentialTelemetry: false`) | Host | Purpose | | --------------------- | --------------------------------------------------------------- | | `a-cdn.anthropic.com` | Analytics SDK | | `a-api.anthropic.com` | Analytics events | | `claude.ai` | Analytics events | | `api.anthropic.com` | Claude Code usage telemetry, sent from inside the agent sandbox | ### Non-essential services (`disableNonessentialServices: false`) | Host | Purpose | | --------------------------- | -------------------------------------- | | `www.google.com` | Connector favicons | | `*.gstatic.com` | Connector favicons | | `www.claudeusercontent.com` | Artifact preview iframe | | `cdnjs.cloudflare.com` | Artifact preview asset CDNs | | `fonts.googleapis.com` | Artifact preview asset CDNs | | `cdn.jsdelivr.net` | Artifact preview asset CDNs | | `*.claudemcpcontent.com` | MCP App widget iframe | | `assets.claude.ai` | Fonts loaded by MCP App widget iframes | `*.claudemcpcontent.com` serves [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can render. Each widget loads in a sandboxed iframe on its own generated subdomain, so allowlist the wildcard. ### Optional features | Host | Required when | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Host of `otlpEndpoint` | OpenTelemetry export is configured | | `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled | | Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured | | Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured | | Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured | | `api.anthropic.com` | [Code](/docs/third-party/claude-desktop/code) sessions can use Web Fetch and [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch)) | | `claude.ai`, `api.anthropic.com`, `storage.googleapis.com` | [Import from claude.ai](/docs/third-party/claude-desktop/import) is enabled (`claudeAiImport` with `enabled` set to `true`). Used only while a user signs in to claude.ai and fetches an export in the import wizard; importing a downloaded export file needs none of them | | `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set). With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](/docs/third-party/claude-desktop/ssh-remote-sessions#host-requirements)) | ## Disabling all Anthropic-bound connections With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, and [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) set to `false`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. Without `modelCatalogEnabled: false`, the app also fetches the signed model catalog from `downloads.claude.ai` at launch and then every 5 to 15 minutes, regardless of the four telemetry and update keys, and on devices installed with the offline installer too. A blocked catalog request affects nothing else, and the model picker keeps the names and effort options the app last fetched or shipped with. To keep the catalog without reaching `downloads.claude.ai`, set [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) to a mirror inside your network. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code) sessions otherwise checks each fetched domain with `api.anthropic.com`. The only required egress is `downloads.claude.ai` (for the VM workspace bundle and Claude CLI binary at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. Enabling [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) adds `downloads.claude.ai` back, except on devices installed with the offline installer that connect only to Linux x64 or arm64 hosts: that installer bundles the remote-session components for those hosts, and connections to hosts on other platforms still download them. Enabling [import from claude.ai](/docs/third-party/claude-desktop/import) likewise lets the app reach `claude.ai` and `api.anthropic.com` (and `storage.googleapis.com` for the export download), but only while a user runs a sign-in import from the wizard. An app that receives its configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still connects to Anthropic with all of these keys set. It never fetches the model catalog (its model names and options come from the console's settings), and it contacts `api.anthropic.com` at every launch and at each configuration check (every 10 minutes by default) to download its configuration. The app contacts `claude.ai` when the user signs in. While the organization's **Report desktop usage to this organization** switch is on, the app also sends [usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) counts to `api.anthropic.com` every few minutes during use. You turn the telemetry categories for these apps on and off on the console's **Telemetry & updates** page. These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete configuration. ## Proxy support Claude Desktop and the Claude Code engine it runs follow the operating system's proxy settings by default, including PAC files, and on macOS and Windows so does the Cowork sandbox. You can also pin a specific proxy for all three from managed configuration. See [Network proxy](/docs/third-party/claude-desktop/network-proxy) for the default behavior, the pinned-proxy keys, the traffic that bypasses the proxy, and [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy#tls-intercepting-proxies). # Deploy Claude Desktop on 3P with Google Cloud's Agent Platform Source: https://claude.com/docs/third-party/claude-desktop/vertex Set up Google Cloud, choose an authentication path for your organization, and configure Claude Desktop on 3P to use Claude models on Google Cloud's Agent Platform This page walks an IT administrator through a complete deployment on Google Cloud's Agent Platform (formerly Vertex AI): enabling Claude in your Google Cloud project, choosing the authentication path that fits your organization, preparing devices, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app). ## Choose an authentication approach Google Cloud's Agent Platform authenticates with Google Cloud Application Default Credentials, which can be supplied several ways. The right one depends on whether your users have Google identities and whether you need per-user attribution in Cloud Audit Logs. | Scenario | Use | Per-device prerequisite | Per-user Cloud Audit Logs identity | Notes | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Proof of concept, single team | [Service-account key](#credentials-file) (`inferenceVertexCredentialsFile`) | The key file on each device | No (shared service account) | A long-lived secret distributed to every device. Simplest to start; not recommended for broad rollout. | | Users have Google Workspace or Cloud Identity accounts | [In-app Google sign-in](#in-app-google-sign-in) (`inferenceVertexOAuth*`) | None | Yes | Users sign in with their Google account inside the app. See the session-control warning below. | | Users authenticate with a third-party IdP (Entra ID, Okta, Ping, …) and you don't want to provision Google identities | [In-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) (`inferenceVertexWorkforce*`) | None | Yes (workforce-pool principal) | Users sign in with their corporate identity inside the app. The app runs PKCE against your IdP and exchanges the ID token at Google STS. | | Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | The helper executable on each device | Depends on what the helper obtains | The helper's stdout is sent as the bearer on each inference request. | | You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway) instead of Google Cloud's Agent Platform | None | At your gateway | The proxy holds the Google Cloud credentials; the app authenticates only to the proxy. | If your Google Workspace or Cloud Identity organization enforces a **Google Cloud session length** of a few hours or less (Admin console → Security → Google Cloud session control), the in-app Google sign-in stores a refresh token that is subject to that policy, and users will be prompted to sign in again each time it expires. For short session policies, either mark your OAuth client as a [trusted app exempt from reauthentication](https://support.google.com/a/answer/9368756), or use a service-account key, Workforce Identity sign-in, or the gateway provider instead. ## How the two sign-in flows compare The [in-app Google sign-in](#in-app-google-sign-in) and [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approaches both open the system browser for a one-time consent and then renew in the background (or, for Workforce Identity, re-prompt in the browser when your IdP does not issue a refresh token). They differ in which party issues the refresh token, whether Google's Security Token Service is involved, and whether an Application Default Credentials file is written. The diagrams below show each flow end to end, and the table that follows summarizes the differences. ### Workforce Identity sign-in Claude Desktop runs authorization code with PKCE directly against **your** IdP. The IdP's ID token is then exchanged at Google's Security Token Service for a short-lived Google Cloud access token. Google STS is stateless and never issues a refresh token, so every renewal starts at your IdP. ```mermaid theme={null} sequenceDiagram autonumber participant App as Claude Desktop participant Browser as System browser participant IdP as Your IdP
(Entra ID, Okta, Ping, ...) participant GCP as Google Cloud
(STS and Vertex AI) App->>App: Generate PKCE verifier and challenge,
listen on http://127.0.0.1:PORT/callback App->>Browser: Open IdP /authorize
(client_id, redirect_uri, code_challenge, scope) Browser->>IdP: Authorization request IdP-->>Browser: Sign-in page (password, PIV/CAC, MFA) Browser->>IdP: User authenticates IdP-->>Browser: 302 to http://127.0.0.1:PORT/callback?code=... Browser->>App: Deliver authorization code on loopback App->>IdP: POST /token
(code, code_verifier, client_id, no client secret) rect rgba(235, 219, 188, 0.4) IdP-->>App: id_token (+ refresh_token if the
Refresh Token grant is enabled) Note over App,IdP: IdP-issued tokens.
The refresh_token, when present, belongs to your IdP. end App->>GCP: POST sts.googleapis.com/v1/token
(grant_type=token-exchange,
subject_token=id_token, subject_token_type=...:id_token,
audience=//iam.googleapis.com/.../workforcePools/POOL/providers/PROVIDER) rect rgba(191, 219, 254, 0.4) GCP-->>App: Google Cloud access_token
(the pool's session duration, 1 hour by default,
capped at the id_token's remaining lifetime, no refresh_token) Note over App,GCP: Google-issued token. STS is stateless and never returns a refresh_token. end App->>GCP: Vertex AI request (Authorization: Bearer access_token) GCP-->>App: Model response Note over App,GCP: No ADC file is written. The IdP tokens are stored encrypted with the
operating system's secure storage (Keychain on macOS, DPAPI on Windows). alt Silent renewal (IdP issued a refresh_token) App->>IdP: POST /token (grant_type=refresh_token) IdP-->>App: Fresh id_token App->>GCP: Repeat STS exchange for a fresh access_token else No IdP refresh_token App->>Browser: Repeat the full browser flow when the id_token expires end ``` ### Google sign-in (OAuth) Claude Desktop runs authorization code with PKCE against **Google's** OAuth endpoints. Google issues the refresh token, and the app writes it to an `authorized_user` Application Default Credentials file that the Google Cloud client library consumes. Your corporate IdP may appear inside Google's sign-in page (if Cloud Identity is federated via SAML), but the app never talks to it directly. ```mermaid theme={null} sequenceDiagram autonumber participant App as Claude Desktop participant Browser as System browser participant Goog as Google OAuth
(accounts.google.com,
oauth2.googleapis.com) participant Vertex as Vertex AI App->>App: Generate PKCE verifier and challenge,
listen on http://127.0.0.1:PORT/callback App->>Browser: Open accounts.google.com/o/oauth2/v2/auth
(client_id, redirect_uri, code_challenge,
scope=openid email cloud-platform,
access_type=offline, prompt=consent) Browser->>Goog: Authorization request opt Cloud Identity is SAML-federated to your IdP Goog-->>Browser: Redirect to your corporate IdP Browser->>Goog: Return with SAML assertion Note over Browser,Goog: Happens inside Google's page.
Claude Desktop never sees this hop. end Goog-->>Browser: 302 to http://127.0.0.1:PORT/callback?code=... Browser->>App: Deliver authorization code on loopback App->>Goog: POST oauth2.googleapis.com/token
(code, code_verifier, client_id, client_secret) rect rgba(191, 219, 254, 0.4) Goog-->>App: access_token + refresh_token Note over App,Goog: Google-issued tokens.
The refresh_token belongs to Google. end App->>App: Store authorized_user ADC
{client_id, client_secret, refresh_token}
encrypted with the operating system's secure storage
(Keychain on macOS, DPAPI on Windows) Note over App,Vertex: At each session start App->>App: Write the ADC JSON to a per-session file,
set GOOGLE_APPLICATION_CREDENTIALS App->>Goog: google-auth-library reads ADC and
POSTs oauth2.googleapis.com/token (grant_type=refresh_token) Goog-->>App: Fresh access_token App->>Vertex: Vertex AI request (Authorization: Bearer access_token) Vertex-->>App: Model response Note over App,Vertex: Silent renewal: google-auth-library refreshes against Google using the ADC file.
Your corporate IdP is not contacted on renewal. ``` ### Side by side | | Workforce Identity sign-in | Google sign-in (OAuth) | | ------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | OAuth peer the app talks to | Your IdP's OIDC endpoints | Google's OAuth 2.0 endpoints | | Where your corporate IdP appears | Directly (the app opens it) | Inside Google's sign-in page, via Cloud Identity SAML federation (optional) | | Refresh token issued by | Your IdP (when the Refresh Token grant is enabled on the client) | Google | | Google STS (`sts.googleapis.com`) involved | Yes, on every access-token renewal | No | | ADC file written | No | Yes (`authorized_user` JSON, pointed to by `GOOGLE_APPLICATION_CREDENTIALS`) | | Registered on the Google side | Workforce pool and OIDC provider (IAM & Admin) | Desktop-app OAuth 2.0 client (APIs & Services → Credentials) | | Per-user prerequisite | An account at your IdP | A Google Workspace or Cloud Identity account | | Client registered at your IdP | Public (native) OAuth client, PKCE required, loopback redirect URI | None (your IdP is federated to Cloud Identity, not to the app) | ## Set up Google Cloud These steps are performed once per Google Cloud project, regardless of which authentication approach you chose. You need a project with Owner or Editor access. In the [Google Cloud console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com), enable the **Vertex AI API** for your project. In the [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), locate the Claude models you intend to deploy and click **Enable** on each. Model availability varies by region; enable them in the region you will set as `inferenceVertexRegion`. Each authenticated principal needs permission to call the model. On the project's **IAM** page, grant the **Vertex AI User** role (`roles/aiplatform.user`) to: * the service account, if using a service-account key file * the Google group containing your users, if using in-app Google sign-in If your organization uses a narrower custom role, it must include at minimum `aiplatform.endpoints.predict`. If you chose in-app Google sign-in, create a Desktop-app OAuth client in your project. See [In-app Google sign-in](#in-app-google-sign-in) below for the full procedure, including consent-screen setup. If your users authenticate with Microsoft Entra ID, Okta, or another identity provider and do not already have Google accounts, you have two options: * **Workforce Identity Federation** (recommended). Create a workforce pool with an OIDC provider, and use the [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approach. Users sign in directly with their corporate identity; no Google identity is provisioned. * **Cloud Identity with SAML SSO.** Provision a free Cloud Identity tenant and configure SAML single sign-on to your IdP. Users then sign in through the in-app Google sign-in approach with a Google identity that is backed by your IdP. See [Set up SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) in the Cloud Identity documentation. ## Prepare devices What each end-user device needs depends on the authentication approach you chose. ### Credentials file Create a service account in your project, grant it the **Vertex AI User** role, and download its JSON key. Distribute the key file to a fixed path on each device through your device-management tooling and set `inferenceVertexCredentialsFile` to that path. `inferenceVertexCredentialsFile` accepts any Application Default Credentials JSON format, so if your environment already produces an `authorized_user` file (from `gcloud auth application-default login`) or an `external_account` Workforce Identity Federation configuration, you can point at that file instead. For `external_account` files, the `credential_source` must be of type `file` or `url` (`executable` sources are not supported), and separate tooling on the device must obtain the IdP token and write it to the configured location; Claude Desktop does not perform that step. ### In-app Google sign-in No per-device preparation is required. The sign-in experience uses a Google OAuth client that **you create in your own Google Cloud project**; Anthropic does not provide or operate an OAuth client for this flow. Distribute the OAuth client ID and secret in the managed configuration (see [Configure the app](#configure-the-app)). #### How it works When `inferenceVertexOAuthClientId` and `inferenceVertexOAuthClientSecret` are both set, the app shows a **Sign in with Google** page at first launch. Clicking the button opens the system browser for a standard Google consent flow, and the app listens on a loopback address for the redirect. On success, the app stores the user's Google refresh token encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows) and returns to Cowork. At the start of each Cowork session, the app writes an `authorized_user` Application Default Credentials file (the same format produced by `gcloud auth application-default login`) into the session sandbox and points `GOOGLE_APPLICATION_CREDENTIALS` at it. The Google Cloud client library inside the sandbox handles access-token minting and refresh automatically. If the stored refresh token is revoked or expires, the app shows a **Sign in again** prompt; clicking it reopens the Google consent flow in the browser. If you deploy a new OAuth client ID, the app clears the stored token and shows the sign-in page on next launch. #### Create the OAuth client In the Google Cloud Console, in the project where you enabled Claude models, open **APIs & Services → OAuth consent screen**. If your project belongs to a Google Workspace organization, select the **Internal** user type. Internal apps are limited to users in your Workspace and do not require Google verification, regardless of which scopes they request. If the project is not in a Workspace organization, you must use the **External** user type. Because this flow requests the `https://www.googleapis.com/auth/cloud-platform` scope, Google classifies the app as using a sensitive scope, and publishing it beyond test users requires Google's OAuth verification process. For that reason, Internal is strongly recommended for enterprise deployments. In **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type. Record the generated **Client ID** (ending in `.apps.googleusercontent.com`) and **Client secret**. For installed applications, Google does not treat the client secret as confidential; the flow is protected by PKCE and by the loopback redirect, so it is safe to distribute the secret in a managed configuration profile. You do not need to add redirect URIs. Desktop-app clients permit loopback (`http://127.0.0.1:`) redirects automatically. The sign-in flow and subsequent token refreshes reach `accounts.google.com` and `oauth2.googleapis.com` from the user's device. These hosts are already included in the standard egress requirements for Google Cloud's Agent Platform, so if you allowed egress based on the **Egress** section of the configuration window, no additional firewall changes are needed. #### Federate to a third-party identity provider The in-app sign-in always opens Google's authorization endpoint, because Google Cloud's Agent Platform only accepts Google-issued access tokens. To have users authenticate with your organization's own identity provider (Microsoft Entra ID, Okta, Ping, or an in-house SAML IdP) instead of a Google password, configure Cloud Identity as a broker: 1. In the Google Admin console, set up [SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) and assign the SSO profile to your Claude Desktop users' organizational unit. 2. Provision those users into Cloud Identity (via SCIM from your IdP, or Google Cloud Directory Sync) so IAM grants resolve. 3. Optionally set `inferenceVertexOAuthLoginHint` so Google skips its own account chooser and routes straight to your IdP with the user's identity pre-filled. With this in place, clicking **Sign in with Google** opens the browser, Google immediately redirects to your IdP, the user authenticates there (including smart-card or PIV authentication if your IdP supports it), and Google issues the tokens on return. Claude Desktop is unchanged; the federation is configured entirely in Google Admin and your IdP. #### Notes and limitations * **Precedence.** When both `inferenceVertexOAuthClientId` and `inferenceVertexCredentialsFile` are set and `inferenceCredentialKind` is not, Google sign-in takes precedence and the credentials file is ignored (the app logs a multi-credential warning). To force the credentials file, set `inferenceCredentialKind` to `vendor-profile` or remove the OAuth client keys. * **Both keys required.** If only one of `inferenceVertexOAuthClientId` or `inferenceVertexOAuthClientSecret` is set, the app logs a warning and falls back to standard Application Default Credentials discovery. * **Client rotation.** If you replace the OAuth client in Google Cloud and push the new client ID via MDM, existing users are automatically signed out and prompted to sign in again on next launch. ### In-app Workforce Identity sign-in No per-device preparation is required. In Google Cloud, create a [workforce pool](https://cloud.google.com/iam/docs/workforce-identity-federation) with an OIDC provider pointing at your organization's IdP, and grant the pool's principals the **Vertex AI User** role on the project. In your IdP, register a native OAuth client for the app. The app does not send a client secret in this flow, so the client must be public (no client authentication) with PKCE required. The sign-in redirect lands on `http://127.0.0.1:/callback`, where the operating system chooses `` on each sign-in: * If your IdP permits loopback redirect URIs on any port (the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) native-app pattern, supported by Microsoft Entra ID under the **Mobile and desktop applications** platform), register `http://127.0.0.1/callback` and leave `redirectPort` unset. * If your IdP requires an exact registered redirect URI (such as Okta or PingFederate), set the `redirectPort` field of `inferenceVertexWorkforceOidc` to a fixed port and register the resulting URI exactly, for example `http://127.0.0.1:53180/callback`. Register the redirect URI with `127.0.0.1` rather than `localhost`, because the app uses `127.0.0.1` by default and most IdPs do not treat the two as interchangeable. If your IdP accepts only `localhost` in a registered redirect URI, set the `redirectHost` field of [`inferenceVertexWorkforceOidc`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) to `localhost` and register `http://localhost/callback` instead, or `http://localhost:/callback` when you set `redirectPort`. Distribute the workforce-pool provider audience and the IdP OIDC client in the managed configuration; the app shows a **Sign in** page on first launch, runs an authorization-code-with-PKCE flow against your IdP in the system browser, exchanges the returned ID token for a Google Cloud access token at `sts.googleapis.com`, and stores the IdP refresh token encrypted with the operating system's secure storage. No `gcloud` CLI, helper script, or Google identity is required. The app always requests the `offline_access` scope so that the IdP returns a refresh token for silent renewal. If your IdP rejects `offline_access` on this client (for example, a PingFederate public client without the Refresh Token grant type enabled), set the `omitOfflineAccess` field of `inferenceVertexWorkforceOidc` to `true`. Without a refresh token the app cannot refresh silently, so users will be prompted to sign in again each time the IdP's ID token expires, typically about once an hour. When your IdP is Microsoft Entra ID, you can run this sign-in through the [OS identity broker](/docs/third-party/claude-desktop/entra-broker) on Windows and macOS instead of the system browser by setting `inferenceVertexWorkforceAuthFlow` to `broker`. The `issuer` in `inferenceVertexWorkforceOidc` must then be `https://login.microsoftonline.com/TENANT_ID/v2.0`, and no loopback redirect URI is needed. The token exchange at `sts.googleapis.com` is unchanged. ## Configure the app With Google Cloud set up and devices prepared, open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**) on an evaluation device. In the **Connection** section, set **Inference provider** to **Vertex AI** and fill in the **Vertex AI credentials** card with the values for whichever authentication approach you chose: | Field | Service-account key | In-app Google sign-in | | -------------------------- | ---------------------- | ---------------------------------------------- | | GCP project ID | `your-gcp-project` | `your-gcp-project` | | GCP region | e.g. `us-east5` | e.g. `us-east5` | | GCP credentials file path | `/path/to/sa-key.json` | *leave empty* | | Vertex OAuth client ID | *leave empty* | `1234567890-abc123.apps.googleusercontent.com` | | Vertex OAuth client secret | *leave empty* | `GOCSPX-xxxxxxxxxxxxxxxxxxxx` | | Vertex OAuth scopes | *leave empty* | *leave empty for the default* | | Vertex AI base URL | *optional* | *optional* | Under **Models**, add at least one **Model list** entry using the publisher model ID, for example `claude-sonnet-5`. Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow. ### Configuration keys The full set of `inferenceVertex*` keys is below. Set `inferenceProvider` to `vertex`, supply a project and region, and provide exactly one credential source. The region can be a single region such as `us-east5`, the `eu` or `us` multi-region, or `global`. The app routes inference to a different endpoint host for multi-regions and `global`; if you allowlist egress by hostname, see the [inference provider egress hosts](/docs/third-party/claude-desktop/telemetry#inference-provider). | Setting | Type | Availability | Default | Description | | ------------------------------------------------------------------------------------- | -------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | GCP project ID
`inferenceVertexProjectId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Google Cloud project ID for Vertex AI inference. | | GCP region
`inferenceVertexRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | GCP region where your Vertex AI Claude models are deployed. | | Vertex AI base URL
`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | PSC endpoint, if using one. | | Vertex OAuth client ID
`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. | | Vertex OAuth client secret
`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config. | | Vertex OAuth scopes
`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. | | Vertex OAuth login hint
`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap
Added in 1.12603.0 | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. | | Workforce Identity audience
`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap
Added in 1.10628.0 | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. | | Workforce Identity billing project
`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap
Added in 1.10628.0 | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. | | Workforce Identity sign-in flow
`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | | Workforce Identity IdP (OIDC)
`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap
Added in 1.10628.0 | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. | | GCP credentials file path
`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. | * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here. * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux. The GCP STS token-exchange step is unchanged in either flow; only how the Entra id\_token is acquired differs. | Field | Type | Default | Description | | --------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). | | `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. | | `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. | | `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. | | `scopes` | `string` | — | Space-separated scopes. Defaults to openid profile email offline\_access. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time. | | `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. | | `omitOfflineAccess` | `boolean` | — | Only enable if your IdP rejects the offline\_access scope on this client. Without it the app prompts for sign-in each time the token expires. | | `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. | If none of `inferenceVertexCredentialsFile`, the OAuth client keys, the Workforce Identity keys, or `inferenceCredentialHelper` is set, the Google client library falls back to the standard Application Default Credentials search path on the device (`~/.config/gcloud/application_default_credentials.json`, then the environment's metadata server). You must also set `inferenceModels` to a list of publisher model IDs, for example `claude-sonnet-5`. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels). ## What users experience The first-launch and re-authentication behavior depends on the authentication approach. | Approach | First launch | Re-authentication | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Credentials file (service-account key) | The app opens directly; no user action. | Never, until you rotate the key file. | | In-app Google sign-in | The app shows a **Sign in with Google** page. Clicking it opens Google's consent flow in the default browser. After approval, the app returns to Cowork. | When the refresh token is revoked, when you deploy a new OAuth client ID, or when your Google Cloud session-control policy expires it. | For in-app Google sign-in, the browser flow runs on the host (outside the Cowork sandbox), so it can use the user's existing Google session and any security keys or passkeys configured on the device. Users can sign out by revoking the app from their Google Account's [third-party connections page](https://myaccount.google.com/connections); the app detects the revoked token and shows a **Sign in again** prompt. ## Troubleshoot To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage). # Web search and web fetch Source: https://claude.com/docs/third-party/claude-desktop/web-tools How Claude Desktop on 3P reaches the internet, which providers support search, and how to control or disable web access Claude Desktop includes two built-in tools for reaching the web: * **Web Search** runs a search-engine query and returns ranked results. * **Web Fetch** retrieves the contents of a specific URL. In Claude Desktop on third-party (3P), both are subject to your configuration: search depends on your inference provider, and fetch is gated by the sandbox network allowlist. ## Web Search Web Search is a **server-side tool** executed by your inference provider, not by the desktop app. Availability depends on which provider you've configured: | Provider | Web Search | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Google Cloud's Agent Platform | Available | | Microsoft Foundry | Available on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) | | Amazon Bedrock | Not available natively; use the [built-in web search](#built-in-web-search) below | | Anthropic API | Available | | Gateway | Available if your gateway implements Anthropic's `web_search` server tool, passes it through to a provider that does, or runs the search itself; see [Gateway-side search](#gateway-side-search) | On Microsoft Foundry, Web Search works on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) with no additional configuration. Deployments hosted on Azure support only the basic web search tool version (`web_search_20250305`), which is the version Claude Desktop uses; see [features not supported when hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) in the Claude in Microsoft Foundry documentation for what else differs when hosted on Azure. On any provider you can configure the [built-in web search](#built-in-web-search) to choose the search backend yourself. Once it is configured, the app stops offering provider-side search and routes the model's search calls to the built-in server. If you want no web search at all, add `"WebSearch"` to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) instead. That entry also blocks the built-in web search tool, so do not combine the two. The [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) passes the `web_search` tool through to its upstream provider, so Web Search works in Claude Desktop behind that gateway when the upstream is Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API. Claude Desktop can't see which upstream the gateway routes to and offers the tool regardless, so if the gateway routes any model to Amazon Bedrock, configure the [built-in web search](#built-in-web-search), which replaces provider-side search on every route. To turn web search off instead, add `"WebSearch"` to `disabledBuiltinTools` in the gateway's [Claude Desktop overlay](https://code.claude.com/docs/en/claude-apps-gateway-config#claude-desktop-overlay). That entry also blocks the built-in web search tool if one is configured. Provider-side search runs on the provider's infrastructure, so queries and results travel over the same path as model inference and are subject to your provider's data-handling terms. It needs no additional firewall rules beyond the inference endpoint itself. `coworkEgressAllowedHosts` governs client-side egress (Web Fetch and in-sandbox shell network activity). The SDK Web Search tool in the table above executes server-side at your inference provider, so the allowlist does not apply to it. The built-in `websearch` server under [Web search options](#web-search-options) runs in the desktop app itself, outside the sandbox, and `coworkEgressAllowedHosts` does not apply to it either. Its search provider's host (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) does need to be reachable through your perimeter firewall and proxy, and the **Egress** section of the in-app configuration window lists that host. To let the agent fetch pages it finds via search, add the relevant hosts to `coworkEgressAllowedHosts` or set it to `["*"]`. Adding `"WebSearch"` to `disabledBuiltinTools` turns web search off entirely, both provider-side search and the built-in `websearch` server's tool. ### Web search options If your inference provider supports native search (Google Cloud's Agent Platform or Microsoft Foundry), that's the simplest path and no additional configuration is required. Use the built-in `websearch` server when your provider has no native search (Amazon Bedrock or a custom gateway), or with any provider when you want to choose the search backend. | Option | Best for | Where you configure it | Search backend | | ------------------------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------- | | [Provider-native](#provider-native-search) | Google Cloud's Agent Platform, Microsoft Foundry | Your cloud provider's console | The provider's | | [Built-in](#built-in-web-search) | Amazon Bedrock or a custom gateway; or any provider when you want to choose the search backend | `managedMcpServers` | Brave, Tavily, Exa, or your own server | | [Gateway-side](#gateway-side-search) | A custom gateway you already run | Your gateway's configuration | Whatever your gateway is wired to | | [Remote search MCP](#remote-search-mcp) | A search MCP you already run, or Amazon Bedrock AgentCore | `managedMcpServers` | Whatever that MCP exposes | #### Provider-native search Google Cloud's Agent Platform grounding and Microsoft Foundry both execute search inside the model call. There's nothing to configure in Claude Desktop. Any setup happens on the cloud provider's side. Amazon Bedrock has no native equivalent (Amazon Bedrock AgentCore is a remote MCP server; see [Remote search MCP](#remote-search-mcp)). #### Built-in web search Add the bundled `websearch` server to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers). Search runs in the desktop app itself, so it works on every inference provider, including Amazon Bedrock. You can add it from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): under **Connectors**, add a **Web search** server, choose the search provider, and supply the vendor key as a header or through a headers helper script. Web search server card in the in-app configuration window with fields for name, tool policy, headers, and headers helper script, and a search provider menu offering brave, tavily, exa, and custom. In the exported configuration, set `provider` to a hosted search vendor (`brave`, `tavily`, or `exa`) for the lowest setup, or to `custom` with `customUrl` to point at a search server you run. Hosted vendor: ```json theme={null} { "managedMcpServers": [ { "name": "Web search", "server": "websearch", "provider": "tavily", "headersHelper": "/opt/org/bin/tavily-headers", "toolPolicy": { "web_search": "allow" } } ] } ``` A hosted-vendor key configured in `headers` or returned by `headersHelper` is the same key on every device, and a local user can extract it. The exposure is limited to billing abuse on that key (it grants no data access). For regulated environments, set spend caps and rotate the key on a schedule, or have `headersHelper` fetch a per-user key: Tavily and Exa support per-user or per-team keys; see their key-management docs. Your own server: ```json theme={null} { "managedMcpServers": [ { "name": "Web search", "server": "websearch", "provider": "custom", "customUrl": "https://search.internal.example.com/v1/search", "headersHelper": "/opt/org/bin/search-headers", "toolPolicy": { "web_search": "allow" } } ] } ``` Set the per-entry `toolPolicy` to `"allow"` so users aren't prompted to approve each search. `headersHelper` is an executable that prints the auth header as a JSON object to stdout; it follows the same execution model as [`inferenceCredentialHelper`](/docs/third-party/claude-desktop/credential-helper) (run with no arguments, exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses. | Provider | Header your script should output | | -------- | ----------------------------------- | | `brave` | `{"X-Subscription-Token": ""}` | | `tavily` | `{"Authorization": "Bearer "}` | | `exa` | `{"x-api-key": ""}` | | `custom` | Whatever your search server expects | You can use a static `headers` object instead if you don't need a secrets manager. #### Gateway-side search If your inference gateway can execute search itself, the search key stays server-side and never reaches end-user devices. For LiteLLM proxy server, enable [`websearch_interception`](https://docs.litellm.ai/docs/tutorials/claude_code_websearch) in `callbacks` and configure a search backend in the proxy. The gateway intercepts the model's `web_search_20250305` request, runs the search, and returns results to Claude Desktop. If your gateway translates between API formats (for example, Anthropic to OpenAI chat completions), note that `web_search_20250305` is an Anthropic server tool with no chat-completions equivalent. The translation layer needs to handle it explicitly: run the search when the model requests it and emit `server_tool_use` and `web_search_tool_result` blocks in the response. Reach out to your account team for a reference implementation. #### Remote search MCP Connect a search MCP server as a remote `managedMcpServers` entry: either one you host, or Amazon Bedrock AgentCore Gateway with the Web Search target enabled (configure AgentCore for JWT authentication through your identity provider). Whether this stays inside your boundary depends on where the server is hosted; AgentCore is available in commercial AWS regions. #### Data handling Search queries go to whichever backend you configure. In every option, the query is also visible to your inference provider as part of the conversation, because the model emits the search call. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not receive search queries in any of these options. For Microsoft Foundry, the Anthropic API, or a gateway, the query is part of the conversation content covered under [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider). To keep the search backend itself inside your network, use `provider: "custom"` (or a self-hosted MCP) pointed at a search index that runs inside your boundary. For audit, each search the model runs is recorded in the Cowork or Code session telemetry sent to your [OTLP collector](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector) as a `tool_result` event, whichever option you choose (a `WebSearch` event for provider-side or gateway-side search, an MCP tool event for the built-in or a remote search server). Add `toolDetails` to [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) to include the tool input, which carries the query text (long values are truncated). The built-in `websearch` server also emits a `builtin_websearch_call` event on the desktop application's own stream with the search provider, query length, result count, duration, and status, never the query text. The app exports that event only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, not at the default `error` level. If you previously routed inference through a LiteLLM proxy to add search, the built-in `websearch` server with `provider: "custom"` is an alternative that removes the proxy from the search path; gateway-side interception remains a valid choice if you prefer the search key to stay server-side. ## Web Fetch Web Fetch runs in the Claude Desktop main process on the user's device. The model supplies only the target URL; it cannot set headers, a request body, or credentials. Every fetch, including redirect targets, is checked against `coworkEgressAllowedHosts` before the request is sent. By default, the sandbox can reach only your inference provider's endpoint, so Web Fetch will fail for any other host unless you've allowed it. To permit fetches: | Goal | Set `coworkEgressAllowedHosts` to | | -------------------------------------- | --------------------------------------------------- | | Allow specific domains | `["docs.example.com", "*.example.corp"]` | | Allow all hosts (no sandbox filtering) | `["*"]` | | Block all fetches | `[]` and add `"WebFetch"` to `disabledBuiltinTools` | Wildcards match one or more leading subdomain labels (`*.example.com` matches `a.example.com` and `a.b.example.com`, but not `example.com`). `coworkEgressAllowedHosts` controls what the agent's tools can reach. Your perimeter firewall is a separate, outer layer, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the distinction. The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool. In [Code](/docs/third-party/claude-desktop/code) sessions, Claude Code's Web Fetch tool also asks `api.anthropic.com` whether each domain is on Anthropic's blocklist before fetching, and refuses the fetch if that lookup cannot complete. If your devices cannot reach `api.anthropic.com`, or you do not want fetched hostnames sent there, set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true`. The key requires Claude Desktop 1.37937.0 or later. Cowork sessions do not perform this lookup. ## Disabling web tools To remove web tools entirely, add them to `disabledBuiltinTools`: ```json theme={null} ["WebSearch", "WebFetch"] ``` With both disabled and `coworkEgressAllowedHosts` empty, the agent has no path to the public internet from inside the sandbox. It can still read and write local files, run code against them, and call any MCP servers you've provisioned. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles).