MCP, plugins, skills, and hooks

​

Managed MCP servers (admin)

[
  {
    "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
  }
]

​

OAuth sign-in

http://127.0.0.1:53280/callback

​

How OAuth sign-in works

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. When the server publishes protected-resource metadata, Claude Desktop sends the metadata’s resource value as the OAuth resource parameter on this request. With oauth.omitResource set to true, Claude Desktop sends no resource parameter for that server.
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.

​

Short-lived credentials with a headers helper

​

Supported MCP servers

​

Productivity suites

​

Plugin marketplaces (admin)

​

Create the marketplace repository

{
  "name": "acme-internal",
  "owner": { "name": "Acme IT" },
  "plugins": [
    {
      "name": "expense-policy",
      "source": "./plugins/expense-policy",
      "description": "Answers questions about Acme travel and expense policy"
    }
  ]
}

​

Host the marketplace over HTTPS instead of git

{
  "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)"
      }
    }
  ]
}

​

Configure the marketplace

<key>allowedPluginMarketplaces</key>
<string>[{"source":"github","repo":"acme-corp/claude-plugins","ref":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0","credentialKind":"userGit","installationPreference":"auto_install"}]</string>

[{"source":"url","url":"https://plugins.acme.example.com/claude/marketplace.json","credentialKind":"inferenceCredential","installationPreference":"available"}]

​

Marketplace installation preferences

​

Per-plugin auto-install from a trusted origin

{
  "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"
      }
    }
  ]
}

​

Marketplace credentials

​

Roll out marketplace updates

​

Move a marketplace to a new source

• If a device can’t fetch the new source or rejects it: the plugins from that marketplace stop loading on that device, and the Directory shows the reason in a banner on the Organization tab. That device also uninstalls a plugin that a Claude Desktop version before 1.44121.0 installed outside the marketplace’s folder on the device. Once the device loads the new source, the plugins that stayed installed load again without a reinstall, and the user can install the uninstalled plugin again if the Organization tab lists it.
• If Claude Desktop drops an entry in allowedPluginMarketplaces as invalid: the move waits, and the plugins already installed from the old source keep loading, until you fix the entry.

​

Organization plugins (admin)

​

Plugin directory location

​

Plugin structure

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

​

Auto-installing organization plugins

{
  "name": "code-reviewer",
  "version": "1.0.0",
  "description": "Internal code review assistant",
  "installationPreference": "required"
}

​

Updating organization plugins

1. Update the plugin contents in org-plugins/<name>/ via your software-distribution tool
2. Bump the version string in version.json
3. Users pick up the change on their next app launch

​

Remote MCP servers in plugins

​

Sign in to a plugin server

• 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. 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. This sign-in has requirements.
• 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”.

​

Requirements for plugin server sign-in outside Code

• Claude Desktop opens claude:// links: the browser returns the user to Claude Desktop through a claude:// link. Leave disableDeepLinkRegistration unset or false, and let users’ browsers open claude:// links.
• The plugin doesn’t name its own OAuth client: the server’s entry in .mcp.json doesn’t set oauth.clientId
• The server’s entry uses no placeholder or headers helper: its url and headers hold no ${…} placeholder, and it doesn’t set headersHelper
• 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.

• 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, 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. If either list of plugin servers is set, a skipped entry’s panel reads the message for a blocked server instead.
• 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.”
• 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.”
• 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.”

• 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.
• 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.

​

Replace a plugin server with a managed MCP server

​

Limit plugin servers and end sign-ins

• 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.
• 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.
• 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.

​

Plugin hooks

• 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), 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, 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.

​

Hooks on Windows devices without Git for Windows

• The hook fails or times out: a PreToolUse or PermissionRequest command hook that has no args and no onFailure field blocks the tool call when it fails or times out, whatever shell it sets. A hook written for Bash that was given "shell": "powershell" can block every tool call that it matches. Under Windows PowerShell 5.1, which Claude Code uses when PowerShell 7 isn’t installed, a program that writes to stderr under a redirect in the command, such as 2>&1, can make the hook count as failed although the program exits with 0. The hook error that Claude receives includes blocking because Git Bash wasn't found.
• The command is only a quoted path: a PreToolUse or PermissionRequest hook that sets none of shell, args, and "onFailure": "continue" blocks the tool call when its command is only a quoted path, as in "command": "\"C:\\path\\guard.exe\"". Bash runs that program, but PowerShell only prints the path. Adding "onFailure": "continue" or "shell": "powershell" stops the blocking, but the program still doesn’t start, so the hook checks nothing.
• The hook ends with exit code 2: a PreToolUse hook that ends with exit code 2 blocks the tool call whatever onFailure says, and the error that Claude then receives is the hook’s own error output. In PowerShell a PreToolUse hook ends with 2 when its command ends with a program that exits with 2. That reaches a hook written for Bash such as python $CLAUDE_PROJECT_DIR/check.py, even with "onFailure": "continue". A bare $CLAUDE_PROJECT_DIR is empty in PowerShell, so Python can’t open its script and exits with 2.

• Keep a hook written for Bash: install Git for Windows in its default location (C:\Program Files\Git) on each device, remove "shell": "powershell" from the hook if it has it, then quit and reopen Claude Desktop
• Run the hook without a shell: write the hook in exec form, with an executable such as an .exe (not a .cmd or .bat file) in command and its arguments in args ("args": [] if it has none). Write the path without quotes of its own, even when it has spaces, as in "command": "C:\\Program Files\\Guard\\guard.exe". Write the project folder as ${CLAUDE_PROJECT_DIR}, braces included, since no shell expands $CLAUDE_PROJECT_DIR there. A Bash script can’t run this way without Git.
• Keep a hook written for PowerShell: set "shell": "powershell" and "onFailure": "block" on it, and start its program with the call operator, as in "command": "& \"C:\\path\\guard.exe\"". Make the program the last thing that the command runs, and in a PreToolUse hook have it exit with 0 to let the tool call go on and with 2 to block it. A .ps1 script does so through its own exit 0 or exit 2. A script whose last line runs a program ends with 0 even when that program exits with 2, so start the program from the command and not from inside a script. Don’t redirect the program’s stderr in the command, and don’t end the command with exit $LASTEXITCODE. If the program can’t start, exit $LASTEXITCODE exits with 0 and the tool call goes ahead, even with "onFailure": "block".

​

User extensions

• 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, including by asking Claude to save one in a conversation
• Local MCP servers: add local MCP server processes from Settings → Developer

​

Controlling user extensions

​

Skill scanning

​

Turn on skill scanning

1. In Organization settings, go to the Capabilities page under Desktop 3P.
2. Under General restrictions, turn on the Scan user-created skills switch.
3. Click Save changes.

• Set skillScanningEnabled to true in the MDM profile or the bootstrap response. A device that the console or a bootstrap server manages ignores the MDM profile’s value for this setting.
• Turn on the same switch under Capabilities in the in-app configuration window, then click Apply Changes. The change takes effect after the app relaunches.

​

How a scan works

• Pass: the user can use the skill.
• Caution: the scan found something that could be unsafe but couldn’t confirm that the skill is unsafe. The user can use the skill.
• Blocked: the skill failed the scan, and the user can’t use it. The user can correct the skill and upload it again, which starts a new scan.
• Not reviewed: the scan didn’t produce a result, and the user can’t use the skill. This happens, for example, when the provider returns an error or the user is over their token limit. Once the cause is fixed, the user can click Retry on the skill’s page.

​

Changes to skill files after a scan

• Windows batch files: cmd.exe can fail to find a goto or call label in a file that has Unix line endings.
• Signed or hashed files: a changed PowerShell script doesn’t match its signature, and a changed file doesn’t match a stored hash.
• Mentions of the skill’s own files: if a file name contains a changed character, as in What’s New.md, a mention of the file in SKILL.md changes but the name doesn’t, so the two don’t match.

​

What skill scanning doesn’t cover

• Skills that users saved before you turned on scanning. The app scans such a skill the next time the user saves it.
• Changes that someone makes directly to a skill’s files on disk.
• Files inside a skill that the scan skips because of their file names, for example PNG and JPEG images, PDFs, and dependency lock files such as package-lock.json. The scan doesn’t look at what is in these files, so it doesn’t read a script that is saved as logo.png.
• Skills that aren’t saved in the app at all, for example Claude Code skills in .claude/skills folders on the device. A Code session in Claude Desktop loads those skills too.

​

Related topics