MCP, plugins, skills, and hooks changedthird-party/claude-desktop/extensions
Nearest release: v2.1.319, published 6 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 5 Nov 2026 18:33 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 5 Nov 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+65added
Lines−16removed
From line
122
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits39to this page, all time
### Sign in to a plugin server ### Requirements for plugin server sign-in outside Code ### Replace a plugin server with a managed MCP server ### Limit plugin servers and end sign-ins
The whole hunk
from line 122, old and new numbered
/
from line 122
122122
123123> [!NOTE]
124124>
125> Some connectors return [MCP Apps](https://claude.com/docs/connectors/building/mcp-apps/getting-started.md), 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`](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) at your perimeter firewall.
125> Some connectors return [MCP Apps](https://claude.com/docs/connectors/building/mcp-apps/getting-started.md), 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`](https://claude.com/docs/third-party/claude-desktop/configuration#disablenonessentialservices) to `true` blocks that origin, so the conversation shows an error in place 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](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) at your perimeter firewall.
126126
127127### Productivity suites
128128
from line 351
351351| - | - |
352352| `.claude-plugin/plugin.json` | Plugin manifest (name, description, version). Required unless a top-level `SKILL.md` serves as the manifest; see the note below this table. A directory with neither is ignored. |
353353| `version.json` | `{"version": "1.2.3"}`. When this string changes, Claude Desktop re-syncs the plugin on next launch. There's no semver ordering, so a downgrade also triggers a re-sync. If absent, the directory's modification time is used instead. |
354| `.mcp.json` | MCP servers bundled with this plugin. A JSON object keyed by server name: `{"mcpServers": {"<name>": {"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` aren't read from this file. The form `"oauth": true` is for plugins in `org-plugins/`. In a [marketplace plugin or a user-added plugin](#remote-mcp-servers-in-plugins), leave `oauth` out or make it an object, as [MCP in Claude Code](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers) shows. In such a plugin, Claude Code skips a server whose entry says `"oauth": true`. 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`](https://claude.com/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.<key>}` is skipped, because per-user plugin settings aren't available to organization plugins. The diagnostic report's **MCP servers** section lists each server, with the reason for any it skipped. |
354| `.mcp.json` | MCP servers bundled with this plugin. A JSON object keyed by server name: `{"mcpServers": {"<name>": {"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` aren't read from this file. The form `"oauth": true` is for plugins in `org-plugins/`. For a marketplace plugin or a user-added plugin, see [Remote MCP servers in plugins](#remote-mcp-servers-in-plugins). 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`](https://claude.com/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.<key>}` is skipped, because per-user plugin settings aren't available to organization plugins. The diagnostic report's **MCP servers** section lists each server, with the reason for any it skipped. |
355355| `agents/` | Sub-agent definitions. |
356356| `commands/` | Slash-command definitions. |
357357| `skills/` | [Skill](https://claude.com/docs/skills/overview.md) directories. |
from line 404
404404
405405## Remote MCP servers in plugins
406406
407A plugin can declare remote MCP servers in its `.mcp.json` file. Claude Desktop connects to the servers in [`managedMcpServers`](#managed-mcp-servers-admin) and to the servers of plugins in the [`org-plugins/` directory](#organization-plugins-admin). For a plugin from one of your [marketplaces](#plugin-marketplaces-admin), or a plugin that a user added, a session that loads the plugin connects to the plugin's servers when the session starts:
407A plugin can declare remote MCP servers in its `.mcp.json` file, and Claude Desktop shows each one as a connector. For a plugin from one of your [marketplaces](#plugin-marketplaces-admin), or a plugin that a user added, Claude can use these servers in the Cowork sessions, Chat conversations, and Code sessions that load the plugin. If a server requires OAuth sign-in, Claude can use it in Cowork sessions, Chat conversations, and local Code sessions after the user [signs in](#sign-in-to-a-plugin-server). The user signs in once for **Code** and once for the rest of Claude Desktop.
408408
409* **If the server needs no sign-in**: Claude can use it in the Cowork sessions, Chat conversations, and Code sessions that load the plugin
410* **If the server requires OAuth sign-in**: Claude can use it in local Code sessions that load the plugin, once the user has signed in, but not in Cowork sessions or Chat conversations
409In a marketplace plugin or a user-added plugin, a remote server's entry in `.mcp.json` needs no `oauth` field, even if the server requires OAuth sign-in. If you set `oauth`, make it an object, as [MCP in Claude Code](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers) shows, and not `true` as in the `org-plugins/` directory. Claude Code skips a server whose entry says `"oauth": true`. If users sign in outside **Code**, leave `clientId` out of the object, as described under [Requirements for plugin server sign-in outside Code](#requirements-for-plugin-server-sign-in-outside-code).
411410
412To make a plugin's server that requires OAuth sign-in available in Cowork sessions and Chat conversations, add a [`managedMcpServers`](#managed-mcp-servers-admin) entry with a `transport`, the same `url` as the plugin's server, and [OAuth sign-in](#oauth-sign-in) set up. Claude Desktop then connects to the server through your entry. Each user clicks **Connect** next to your entry's name under **Customize > Connectors** and signs in, whether [Code is on or off](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code). After that, Claude can use the server in Cowork sessions, Chat conversations, and Code sessions.
411Claude Code reads this `.mcp.json` file and skips a server whose entry it can't read. Claude Desktop still shows a skipped server as a connector, but Claude can't use it. To check a plugin's entries before you publish it, run [`claude plugin validate <plugin-folder>`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-validate) in your terminal, on the plugin's own folder and not the marketplace's folder. The command checks the entries against the version of Claude Code that runs it, so it can pass an entry that the version in your users' Claude Desktop skips.
413412
414Without a `managedMcpServers` entry for the server, users sign in to it from **Code**, and the sign-in applies to local Code sessions. In **Code**, the user starts a local session that loads the plugin, goes to **Customize > Plugins**, selects the plugin, selects the server on the **Connectors** tab, clicks **Connect**, and completes the sign-in in the browser. With Code on, while no local Code session that loads the plugin is running, the **Connect** button is unavailable, and its tooltip reads "Open a Code session that loads this connector, then try again". With Code turned off, users can't sign in this way, so Claude can't use the server.
413> [!NOTE]
414>
415> For the servers of plugins in the `org-plugins/` directory, see [Organization plugins](#organization-plugins-admin).
415416
416To limit plugin-bundled servers, see [Controlling user extensions](#controlling-user-extensions).
417### Sign in to a plugin server
417418
419Users sign in to a server of a marketplace plugin or a user-added plugin separately for **Code** and for the rest of Claude Desktop:
420
421* **Outside Code**: anywhere in Claude Desktop other than **Code**, the user goes to **Customize > Connectors**, selects the server's row, clicks **Connect** in the panel that opens, and completes the sign-in in the browser. One sign-in covers the user's Cowork sessions, Chat conversations, and scheduled Cowork tasks on the device, and it works where [Code is turned off](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code). A scheduled task's run asks for approval of the server's tools as it does for other MCP tools that have no `toolPolicy` entry, as described under [Tool approvals on scheduled tasks](https://claude.com/docs/third-party/claude-desktop/configuration.md#tool-approvals-on-scheduled-tasks). This sign-in has [requirements](#requirements-for-plugin-server-sign-in-outside-code).
422* **In Code**: with **Code** open, the user goes to **Customize > Plugins**, selects the plugin, selects the server on the plugin's **Connectors** tab, clicks **Connect**, and completes the sign-in in the browser. The sign-in covers local Code sessions. While no local Code session that loads the plugin is running, the **Connect** button in **Code** is unavailable, and its tooltip reads "Open a Code session that loads this connector, then try again".
423
424Outside **Code**, the server's row reads "Check status" until Claude Desktop knows whether the user is signed in, and then "Connected" or "Not connected". Claude Desktop checks the sign-in when the user selects the row and the panel opens.
425
426Outside **Code**, the server's rows under **Settings > Connectors**, under **Connectors** in the message box's **+** menu, and on the plugin's **Connectors** tab under **Customize > Plugins** open the same panel. In a Cowork session or Chat conversation that needs the sign-in, a banner that reads "Claude can't access `<server-name>`." can also offer **Connect**.
427
428To end a sign-in made outside **Code**, the user goes to **Customize > Connectors**, selects the server's row, and clicks **Disconnect**. Claude Desktop removes the sign-in from the device and revokes it at the authorization server, if that server supports revocation.
429
430### Requirements for plugin server sign-in outside Code
431
432A sign-in outside **Code** has these main requirements:
433
434* **Claude Desktop opens `claude://` links**: the browser returns the user to Claude Desktop through a `claude://` link. Leave [`disableDeepLinkRegistration`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeeplinkregistration) unset or `false`, and let users' browsers open `claude://` links.
435* **The plugin doesn't name its own OAuth client**: the server's entry in `.mcp.json` doesn't set `oauth.clientId`
436* **The server's entry uses no placeholder or headers helper**: its `url` and `headers` hold no `${…}` placeholder, and it doesn't set `headersHelper`
437* **The authorization server supports dynamic client registration**: it offers a registration endpoint and accepts the redirect URI `claude://claude.ai/mcp-auth-callback/sdk`. The registration request names the client `Claude Code (plugin:<plugin-name>:<server-name>)`, where `<plugin-name>` is the `name` in the plugin's `.claude-plugin/plugin.json` file and `<server-name>` is the server's key in `.mcp.json`. If the authorization server registers only the client names that you list, add this name for each plugin server. Each user's first sign-in on a device registers a new client, and so does a sign-in after the user clicks **Disconnect**, so allow for any limit that the authorization server sets on registrations, for example per network address and hour.
438
439When a requirement isn't met, users see one of the following:
440
441* **No Connect button**: if `disableDeepLinkRegistration` is `true`, the operating system doesn't open `claude://` links with Claude Desktop, the plugin names its own OAuth client, or [Claude Code skipped the server's entry](#remote-mcp-servers-in-plugins), the server's panel reads "Claude can't sign you in to `<server-name>` through this plugin. Ask your admin to set it up as a managed connector." A managed connector is a [`managedMcpServers` entry that replaces the plugin server](#replace-a-plugin-server-with-a-managed-mcp-server). If either [list of plugin servers](#limit-plugin-servers-and-end-sign-ins) is set, a skipped entry's panel reads the message for a blocked server instead.
442* **No Connect button, because of a placeholder or headers helper**: the panel reads "This connector is provided by a plugin, and you cannot sign in to it here. If it needs no sign-in, it connects by itself. If Claude cannot use it, ask your admin to set it up as a managed connector."
443* **A message after Connect**: if the authorization server offers no registration endpoint, or refuses the redirect URI when Claude Desktop registers, the panel offers **Connect**. After the click, the panel reads "Claude couldn't sign you in to `<server-name>` through this plugin. Ask your admin to set it up as a managed connector."
444* **A time-out**: if the `claude://` link doesn't reach Claude Desktop within five minutes, a message reads "Sign-in for `<server-name>` timed out. Select Connect to try again."
445
446A sign-in times out when something keeps the `claude://` link from reaching Claude Desktop, for example:
447
448* **The browser doesn't open the link**: a browser policy blocks `claude://` links, or the user doesn't let the browser open Claude Desktop. In Microsoft Edge, for example, a `URLBlocklist` entry such as `claude://*` blocks the link, and an `AutoLaunchProtocolsFromOrigins` entry with the protocol `claude` and the authorization server's origin opens it without asking the user.
449* **The consent page's Content Security Policy blocks the link**: the consent page is the authorization server's page where the user approves the sign-in. If it carries a `Content-Security-Policy` header whose `form-action` directive doesn't allow `claude:`, Google Chrome, for example, blocks the link and shows no error on the page. Check any such header that a proxy or web application firewall in front of the authorization server sets.
450
451### Replace a plugin server with a managed MCP server
452
453If a [`managedMcpServers`](#managed-mcp-servers-admin) entry has the same `url` or the same name as a plugin server, Claude Desktop uses your entry in place of the plugin server. Give the entry a `transport`, the plugin server's `url`, and `oauth`, as described under [OAuth sign-in](#oauth-sign-in). Each user clicks **Connect** next to your entry's name under **Customize > Connectors** and signs in once for Cowork sessions, Chat conversations, and Code sessions.
454
455### Limit plugin servers and end sign-ins
456
457To choose which plugin servers sessions connect to, set [`allowedPluginMcpServers`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedpluginmcpservers) or [`deniedPluginMcpServers`](https://claude.com/docs/third-party/claude-desktop/configuration#deniedpluginmcpservers). Users can't sign in to a server that these lists keep out. Outside **Code**, its row keeps reading "Check status", and its panel reads "Your organization may have blocked `<server-name>`. Ask your admin to allow it." While either list is set, the panel reads the same for a server whose entry Claude Code skipped, so also check the entry as described under [Remote MCP servers in plugins](#remote-mcp-servers-in-plugins).
458
459The lists and the sign-ins have these limits:
460
461* **OAuth hosts aren't checked**: both lists match the server's own `url`. They don't check the hosts that sign-in, registration, and token requests go to. The server's OAuth metadata or the plugin's `.mcp.json` file can point those requests at other hosts.
462* **Blocking doesn't revoke**: after you block a server or remove its plugin, new sessions don't connect to it. Sign-ins that users already made stay on their devices and aren't revoked. To end them, revoke them at the server's authorization server.
463* **Storage**: on Windows and Linux, sign-ins to plugin servers are stored in a file that isn't encrypted. For where sign-ins to plugin servers and to managed MCP servers are stored, see [Credentials](https://claude.com/docs/third-party/claude-desktop/data-storage.md#credentials).
464
418465## Plugin hooks
419466
420467[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:
421468
422469* **Cowork sessions** run hooks from marketplace plugins, from plugins in the `org-plugins/` directory, and from plugins users add themselves.
423* **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](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#managed-configuration-on-the-remote-host), hooks from the plugins Claude Desktop copies to the host do not run.
470* **Code sessions** run hooks from marketplace plugins (Claude Desktop 1.32352.0 or later), from plugins users upload in the app, 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](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#managed-configuration-on-the-remote-host), hooks from the plugins Claude Desktop copies to the host do not run.
424471* **Chat conversations** run hooks from the same plugins as Cowork sessions, on Claude Desktop 1.52386.0 or later.
425472
426473With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen runs the same hooks as any other Cowork session.
from line 506
459506* **Skills:** create and upload their own [skills](https://claude.com/docs/skills/overview.md), including by asking Claude to save one in a conversation
460507* **Local MCP servers:** add local MCP server processes from **Settings → Developer**
461508
462End users cannot add remote MCP servers from the app's settings or install desktop extension files (`.mcpb`) themselves. Remote servers come from admin-provisioned `managedMcpServers`, from organization plugins, and from other plugins that bundle them, including plugins users install. If a marketplace plugin or a user-added plugin bundles a remote MCP server that requires OAuth sign-in, Claude can't use that server in Cowork sessions or Chat conversations. To make it available there, add a `managedMcpServers` entry with the same `url`, as described under [Remote MCP servers in plugins](#remote-mcp-servers-in-plugins). A Code session can also load the servers a user defines in Claude Code's own configuration (`~/.claude.json`, a project's `.mcp.json`, or `claude mcp add`). To limit plugin-bundled servers, see [Controlling user extensions](#controlling-user-extensions). To limit the servers a Code session loads, see [Applied as managed policy](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy).
509End users cannot add remote MCP servers from the app's settings or install desktop extension files (`.mcpb`) themselves. Remote servers come from admin-provisioned `managedMcpServers`, from organization plugins, and from other plugins that bundle them, including plugins users install (see [Remote MCP servers in plugins](#remote-mcp-servers-in-plugins)). A Code session can also load the servers a user defines in Claude Code's own configuration (`~/.claude.json`, a project's `.mcp.json`, or `claude mcp add`). To limit plugin-bundled servers, see [Controlling user extensions](#controlling-user-extensions). To limit the servers a Code session loads, see [Applied as managed policy](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy).
463510
464User-added extensions are stored in the user's [local data directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md) and apply only to that device.
511User-added extensions are stored in the user's [local data directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md) and apply only to that device. A plugin that a user uploads loads in Cowork sessions, Chat conversations, scheduled tasks, and Code sessions, whichever part of the app they upload it from. It doesn't load where a plugin of the same name from your organization does. One uploaded with an earlier version of Claude Desktop stays where it was until they upload it again. A marketplace that a user adds, and the plugins they install from it, stay in the part of the app where they added it: **Code** or the rest of Claude Desktop.
512
513In the app, when a user installs, uploads, or turns on a plugin that your organization didn't provide, Claude Desktop first asks whether to continue, because the plugin may run code on the device. The user clicks **Continue** to go ahead, or **Cancel** to leave the plugin as it was. Claude Desktop doesn't save the answer, so it asks at each install, upload, and turn-on, in **Cowork** and in **Code**. It doesn't ask when a session starts, when a plugin updates, or about a plugin that is already on. Plugins from your [marketplaces](#plugin-marketplaces-admin) and from the [`org-plugins/` directory](#organization-plugins-admin) install and turn on without the question.
465514
466515> [!NOTE]
467516>
No line in this hunk matches that.