Home Docs Claude Documentation

One capture · claude-docs

One read of Claude Documentationclaude-docs-20261007T213710Z

4 pages moved out of 262 read.

Pages moved 4 significant first

Pages read 262 in this capture

Captured 7 Oct 2026 21:37 UTC

Corpus hash 8430a5f32335 corpus-hash

What this read moved

1-4 of 4

third-party/claude-desktop/connectors-m365 Changed · +94 / -3 lines

### Control write actions on the remote connector #### Revoke write scopes on the remote connector #### Limit remote connector write actions to specific users #### Require assignment on the connector app #### Block remote connector write tools in Claude Desktop

from line 10

1010

1111## Choose a connector

1212

13Both 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.

1414

15* **Remote connector**: an administrator approves the scopes on the Anthropic connector app. See [Control write actions on the remote connector](#control-write-actions-on-the-remote-connector).

16* **Local connector**: you [grant write scopes](#grant-write-scopes) on your own app registration and list them in the connector's configuration

18Use this table to pick a connector.

1520| | Remote connector | Local connector |

1621| - | - | - |

1722| Microsoft 365 data path | Transits Anthropic's infrastructure (no storage) | Stays between the user's device and Microsoft |

from line 25

2025| Allowlisting with Anthropic | Required (two to three business days) | Not needed |

2126| Device egress | `login.microsoftonline.com` and the connector host | `login.microsoftonline.com` and `graph.microsoft.com` |

2227| 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 |

23| Write actions | Contact your Anthropic representative | Available with [write scopes](#grant-write-scopes) |

28| Write actions | Available with [write scopes on the Anthropic connector app](#control-write-actions-on-the-remote-connector) | Available with [write scopes](#grant-write-scopes) |

2429| US Government clouds | Separate connector deployment; contact your Anthropic representative | Built in; set `azureCloud` |

2530

2631## Remote connector

from line 64

5964 https://login.microsoftonline.com/YOUR_TENANT_ID/adminconsent?client_id=07c030f6-5743-41b7-ba00-0a6e85f37c17

6065 ```

6166

62 The consent screen lists the delegated Microsoft Graph permissions the connector requests. All are read-only:

67 The consent screen lists the delegated Microsoft Graph permissions the connector requests. The read permissions include:

6368

6469 | Scope | Purpose |

6570 | - | - |

from line 76

7176 | `Chat.Read`, `ChatMessage.Read` | Read Teams chat messages the user can access |

7277 | `offline_access` | Allow the desktop to refresh its token without re-prompting |

7378

79 The screen also lists the write permissions, such as `Mail.Send` and `Files.ReadWrite.All`. Accepting approves the whole list for every user in your tenant, which makes write actions available to every remote connector user. To keep the connector read-only or limit write actions to specific users, accept, then revoke the write scopes before you deploy the configuration in step 4. See [Control write actions on the remote connector](#control-write-actions-on-the-remote-connector).

7481 Review the permissions and select **Accept**.

7582

7683 <Note>

from line 145

138145| - | - |

139146| `login.microsoftonline.com` | Microsoft Entra sign-in |

140147| `microsoft365.mcp.claude.com` | The connector service (substitute your deployment's hostname) |

148

149### Control write actions on the remote connector

150

151Claude can take a write action for a user through the remote connector once the matching write scope is approved for that user on the Anthropic connector app. The Entra admin center lists that app under **Enterprise applications** as **M365 MCP Server for Claude**.

152

153The write scopes are `Mail.Send`, `Mail.ReadWrite`, `MailboxSettings.ReadWrite`, `Calendars.ReadWrite`, `Files.ReadWrite.All`, `ChatMessage.Send`, `ChannelMessage.Send`, and `Chat.Create`. A tenant that approved the connector before Anthropic added the write scopes stays read-only until the write scopes are approved. To see which scopes your tenant has approved, open the app's **Permissions** page as described in [Revoke write scopes on the remote connector](#revoke-write-scopes-on-the-remote-connector).

154

155These controls apply to the connector service at `microsoft365.mcp.claude.com`. For write actions on a FedRAMP or GovCloud deployment, contact your Anthropic representative.

156

157<Warning>

158 The Microsoft 365 connector in claude.ai uses the same connector app. When an administrator approves the write scopes for the whole tenant, for either product, write actions become available to every remote connector user in that tenant. Both the admin consent link in [Set up the remote connector](#set-up-the-remote-connector) and **Grant admin consent for \{your organization}** on the **M365 MCP Server for Claude** app's **Permissions** page approve every permission the connector requests, including the write scopes.

159</Warning>

160

161Choose a control by who should have write actions:

162

163| Who gets write actions | What you do | Where it's enforced |

164| - | - | - |

165| Every remote connector user | Open the [admin consent link](#set-up-the-remote-connector) and select **Accept** | Microsoft Entra |

166| Specific users | Revoke the write scopes for the tenant, then [grant them user by user](#limit-remote-connector-write-actions-to-specific-users) | Microsoft Entra |

167| Nobody | [Revoke the write scopes](#revoke-write-scopes-on-the-remote-connector) | Microsoft Entra |

168| Users on devices you choose | [Block the write tools](#block-remote-connector-write-tools-in-claude-desktop) with `toolPolicy` on the other devices | Claude Desktop managed configuration |

169

170#### Revoke write scopes on the remote connector

171

172Revoking a write scope for the tenant turns off the matching write actions for remote connector users and for claude.ai users in the same tenant. Requires the Cloud Application Administrator or Application Administrator role in Microsoft Entra.

173

1741. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Enterprise applications** and remove the application type filter next to the search box.

1752. Search for **M365 MCP Server for Claude** and open it.

1763. Go to **Permissions** and open the **Admin consent** tab, which shows the permissions approved for the whole tenant. If no write scope is listed, none is approved for the tenant.

1774. For each write scope in the Microsoft Graph list, select the scope, select **…**, select **Revoke permission**, and confirm. The scope disappears from the tab.

1785. Open the **User consent** tab, which shows the permissions granted to individual users. The admin center can't revoke these grants. To remove a write scope listed here, use Microsoft Graph or PowerShell as described in Microsoft's [Review permissions granted to enterprise applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/manage-application-permissions).

1796. If your tenant allows user consent, [require assignment on the connector app](#require-assignment-on-the-connector-app) so that only an administrator can approve its permissions.

180

181Write tools still appear in Claude Desktop after the scopes are revoked, and calls to them fail. To remove the tools from sessions, also [block them in Claude Desktop](#block-remote-connector-write-tools-in-claude-desktop).

182

183#### Limit remote connector write actions to specific users

184

185Microsoft Entra can record consent for a single user instead of the whole tenant. Keep the read scopes approved for the tenant, and grant the write scopes only to the users who need them. Requires at least the Cloud Application Administrator role in Microsoft Entra.

186

1871. Follow [Revoke write scopes on the remote connector](#revoke-write-scopes-on-the-remote-connector) so that no write scope is approved for the tenant.

1882. For each user, follow Microsoft's [Grant consent on behalf of a single user](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-consent-single-user) procedure. Use `07c030f6-5743-41b7-ba00-0a6e85f37c17` as the client application, Microsoft Graph as the resource, and the write scopes the user needs as the permissions.

1893. If a user already has a grant for the connector app on the **User consent** tab, update that grant. Microsoft's script creates a new grant and assumes none exists.

190

191Keep the limit in place after you create the grants:

192

193* **Fix a failed write action with a per-user grant**: add the missing scope to that user's grant. The admin consent link and the **Grant admin consent for \{your organization}** button on the **M365 MCP Server for Claude** app's **Permissions** page approve the write scopes for every user, even when a permission error points you to them.

194* **Revoke again after tenant-wide consent**: if you use either control to approve a permission Anthropic adds later, repeat [Revoke write scopes on the remote connector](#revoke-write-scopes-on-the-remote-connector) afterward

195* **Script changes to who has write actions**: each grant covers one user and can't target a group. Create a grant when a user gains write actions, and delete it with Microsoft Graph or PowerShell when they lose them.

196

197#### Require assignment on the connector app

198

199When an app requires assignment, Microsoft Entra accepts only administrator consent for its permissions, even if your tenant's user consent settings would otherwise let users consent for themselves. Only assigned users can get a token for the app, so assign people before you turn the setting on.

200

2011. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Enterprise applications** and open **M365 MCP Server for Claude**.

2022. Under **Users and groups**, add every user or group that uses the connector in Claude Desktop or claude.ai, including people who only read.

2033. Go to **Properties** and set **Assignment required?** to **Yes**.

204

205If people in your tenant also use the connector in claude.ai, make the same change on the **M365 MCP Client for Claude** app, as described in [Set up the Microsoft 365 connector](https://support.claude.com/en/articles/12542951-set-up-the-microsoft-365-connector).

206

207#### Block remote connector write tools in Claude Desktop

208

209Set each write tool to `"blocked"` in the `toolPolicy` of the `m365` entry in [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#tool-permissions-for-managed-mcp-servers). Find each write tool's name and the scope it needs in the [Microsoft 365 connector security guide](https://support.claude.com/en/articles/12684923-microsoft-365-connector-security-guide). For example, this entry blocks three of the write tools:

210

211```json theme={null}

212{

213 "name": "m365",

214 "url": "https://microsoft365.mcp.claude.com/mcp",

215 "transport": "http",

216 "oauth": {

217 "clientId": "APPLICATION_CLIENT_ID_FROM_STEP_2",

218 "tenantId": "DIRECTORY_TENANT_ID",

219 "scope": "api://07c030f6-5743-41b7-ba00-0a6e85f37c17/access_as_user offline_access"

220 },

221 "toolPolicy": {

222 "outlook_send_mail": "blocked",

223 "outlook_create_event": "blocked",

224 "sharepoint_upload_file": "blocked"

225 }

226}

227```

228

229Claude Desktop removes a blocked tool from Claude's session, and connector settings show the tool as blocked by your organization. To allow write tools for one group, deploy the entry without the blocks to that group's devices through your device-management tool.

230

231A block doesn't change the scopes approved in Microsoft Entra. On a device without the block, the same user can still take write actions, so also use one of the Entra controls to limit the user's account.

141232

142233### Troubleshoot sign-in errors

143234

third-party/claude-desktop/ssh-remote-sessions Changed · +25 / -1 lines

### Sandbox status on the remote host

from line 108

108108* `disabledBuiltinTools`, `builtinToolPolicy`, `autoModeEnabled`, and `disableBypassPermissionsMode`.

109109* [`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.

110110* [`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.

111* `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.

111* `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. See [Sandbox status on the remote host](#sandbox-status-on-the-remote-host) for the message the session shows.

112112* `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.

113113* 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.

114114

115115If 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.

116

117### Sandbox status on the remote host

118

119Claude Desktop asks Claude Code on the host whether the [sandbox](/docs/third-party/claude-desktop/code#applied-as-managed-policy) from your Claude Desktop policy is turned on and running there. The answer is Claude Code's own report, and it doesn't compare each allowed host or folder. Your policy includes the sandbox, and Claude Desktop asks, unless `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset. Requires Claude Desktop 2.26454.0 or later.

120

121When the sandbox isn't confirmed, the session continues and shell commands can run outside the sandbox. To keep Claude Code from starting on a host whose operating system has no sandbox or that lacks a dependency, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/sandboxing#enforce-sandboxing-with-managed-settings) to `true` and [`parentSettingsBehavior`](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) to `"merge"` in the host's Claude Code managed settings. With `"merge"`, that setting applies together with your policy.

122

123Find the message, or the `reason` your collector received, for the cause and the fix.

124

126| - | - | - | - |

127| Shell commands on `<host>` are running outside your organization's sandbox, which couldn't start | `cannot_start` | The sandbox is turned on but isn't running, for example because a Linux host lacks the sandbox dependencies | Install the [dependencies](https://code.claude.com/docs/en/sandboxing#set-up-linux-and-wsl2) on the host, then start a new session |

128| Your organization's sandbox isn't running on `<host>`. Claude Code has no sandbox for that operating system | `unsupported` | The host runs an operating system that Claude Code reports no sandbox for, such as Windows | Use a macOS or Linux host |

129| Your organization's sandbox policy isn't fully applied on `<host>`, so shell commands there may run outside it | `overridden` | Claude Code managed settings on the host replace your policy, even when they say nothing about the sandbox, or they turn the sandbox off or loosen it | Set `parentSettingsBehavior` to `"merge"` in the host's managed settings, and remove `sandbox` values there that conflict with your policy |

130| No message | `unknown` | Claude Code gives no answer that Claude Desktop can read | In a session on that host, ask Claude to run the two commands under [Confirm commands run inside the sandbox](https://code.claude.com/docs/en/sandboxing#confirm-commands-run-inside-the-sandbox) |

131

132With [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) set, your collector receives a `desktop_ssh_sandbox_check_failed` event under the `service.name` value `claude-desktop`, unless [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `off`. A session can send the event more than once, for example when the reason changes or after Claude Desktop restarts, so count distinct `session_id` values rather than events. The event carries these attributes:

133

134* **`reason`**: `cannot_start`, `unsupported`, `overridden`, or `unknown`

135* **`sandbox_on`**: `false` when Claude Code reports no sandbox running, `true` when it reports one that Claude Desktop can't match to your policy, and absent when Claude Code doesn't say

136* **`session_id`**: Claude Desktop's ID for the session

137* **`backend_kind`**: `ssh`

138

139The event doesn't name the host. To find the host, ask the user that the [user attribution](/docs/third-party/claude-desktop/telemetry#user-attribution) attributes identify.

116140

117141## Host requirements

118142

third-party/claude-desktop/code Changed · +1 / -1 lines

from line 45

4545| `allowedPluginMcpServers` | `strictPluginOnlyCustomization` set to `["mcp"]` together with an `allowedMcpServers` list holding your entries and `allowManagedMcpServersOnly`, whether or not `managedMcpServers` is set. MCP servers bundled in plugins from marketplaces, or in plugins users install themselves, connect only when their URL matches an entry; no such plugin's local (stdio) server is admitted, and an empty list admits none. Your managed servers and the servers from the organization plugins directory still load. |

4646| `deniedPluginMcpServers` | The app sets a `deniedMcpServers` list holding your entries, whether or not `allowedPluginMcpServers` is set. When the key is unset or its list is empty, the app sets no `deniedMcpServers` list. When the value is not a list, or holds an entry that the app can't read, the app sets a list whose one entry is `*`, a pattern that matches every URL. See the [`deniedPluginMcpServers` reference](/docs/third-party/claude-desktop/configuration#deniedpluginmcpservers) for what the setting does and what an entry matches. |

4747

48The 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.

48The network and filesystem sandboxes apply on macOS, and on Linux devices and [SSH hosts](/docs/third-party/claude-desktop/ssh-remote-sessions#managed-configuration-on-the-remote-host) with Claude Code's [sandbox dependencies](https://code.claude.com/docs/en/sandboxing) installed. Claude Code doesn't sandbox shell commands on Windows devices, and on a Linux device or SSH host without the dependencies commands run unsandboxed. In those cases, and when `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset, `blockReadsOutsideWorkingDirectories` still confines Claude's file tools but can only ask the user to approve shell commands that read outside the working directories or that Claude Code can't verify. For what a remote session shows, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).

4949

5050Under `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.

5151

third-party/claude-desktop/telemetry Changed · +1 / -1 lines

from line 58

5858

5959The 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.

6060

61For 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. Events on the `claude-desktop` stream include `desktop_ssh_sandbox_check_failed`, described under [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).

6262

6363### Collector endpoint and headers

6464