Text of code.claude.com › docs › en › managed-mcp as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Control MCP server access for your organization - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. By default, anyone running Claude Code can connect any MCP server they choose. Anthropic reviews connectors against its listing criteria before adding them to the Anthropic Directory , but doesn’t security-audit or manage any MCP server.

As an administrator, you can restrict which servers run in your organization, from deploying a fixed approved set to disabling MCP entirely, and you can provide servers to every user. These restrictions cover the servers Claude Code loads itself, including the connectors it fetches from claude.ai. Connectors the desktop app delivers to its local and SSH sessions arrive in-process and are governed from your claude.ai organization settings instead; How connectors reach Claude Code shows which controls apply to connectors in each kind of session, including cloud sessions.

This page covers how to: Choose a pattern that matches how much control you need Deploy a fixed server set with managed-mcp.json , including how to disable MCP entirely Provide servers through managed settings while users keep their own Control servers with allowlists and denylists Tell users what to expect when a restriction blocks a server Monitor which servers your organization actually uses The Security page covers the MCP threat model and how to evaluate a server before approving it.

Decide what to enforce covers MCP restrictions alongside the other administrative controls. Choose a pattern Claude Code supports a range of restriction levels. Each pattern uses one or more of the mechanisms covered below: managed-mcp.json for deploying a fixed set, the managedMcpServers managed setting for providing servers alongside the ones users add, and allowedMcpServers / deniedMcpServers for filtering what users configure.

Pattern What it does Configure Disable MCP No servers load except the few that load under exclusive control managed-mcp.json with an empty server map Fixed deployment Every user gets the servers you list, and servers they configure don’t load managed-mcp.json with the servers you want Provided servers Every user gets the remote servers you list and keeps their own managedMcpServers in managed settings Approved catalog Publish a list of approved servers; users add the ones they want, anything else is blocked allowedMcpServers + allowManagedMcpServersOnly: true Plugin servers only Users can’t add servers through ~/.claude.json or .mcp.json ; skills-directory plugins stop loading as plugins, and servers from other plugins still load strictPluginOnlyCustomization with mcp in the list Soft allowlist Enforce an allowlist that users can broaden in their own settings allowedMcpServers without allowManagedMcpServersOnly Denylist only Block known-bad servers, allow everything else deniedMcpServers No restrictions Users add anything Don’t deploy any managed MCP configuration Claude Code doesn’t have a built-in MCP server registry that users can browse and install from.

For the approved-catalog pattern, share the approved list and its claude mcp add commands somewhere your users will find them, such as an internal wiki, or distribute the servers as plugins through a managed plugin marketplace so users can browse and install them from /plugin . Exclusive control with managed-mcp.json When you deploy a managed-mcp.json file, Claude Code loads only these MCP servers: The servers the file defines Servers you provide through managedMcpServers In-process servers that the app that started the session registers, such as the VS Code extension’s own server or the connectors the desktop app delivers The server that Claude Code creates when a mod adds tools .

To block the tools that your users’ mods add, stop user-installed mods from loading . The built-in Claude in Chrome server, if you allow it alongside the managed set Users can’t add, modify, or use any other MCP servers, including plugin-provided servers and servers passed with the --mcp-config CLI flag . The file also suppresses the claude.ai connectors Claude Code fetches itself unless you allow them alongside the managed set .

Deploy managed-mcp.json managed-mcp.json is a standalone file, so it cannot be delivered through server-managed settings . To deliver servers through managed settings instead, without exclusive control, use managedMcpServers . Any process that can write to a system path with administrator privileges can deploy the file. Across a fleet, that’s usually through device management tooling, such as Jamf or a configuration profile on macOS, Group Policy or Intune on Windows, or your fleet management of choice on Linux.

Claude Code looks for the file at one of these paths: Platform Path macOS /Library/Application Support/ClaudeCode/managed-mcp.json Linux and WSL /etc/claude-code/managed-mcp.json Windows C:\Program Files\ClaudeCode\managed-mcp.json The file uses the same format as a project .mcp.json file: { "mcpServers" : { "github" : { "type" : "http" , "url" : "https://api.githubcopilot.com/mcp/" }, "sentry" : { "type" : "http" , "url" : "https://mcp.sentry.dev/mcp" }, "company-internal" : { "type" : "stdio" , "command" : "/usr/local/bin/company-mcp-server" , "args" : [ "--config" , "/etc/company/mcp-config.json" ], "env" : { "COMPANY_API_URL" : "https://internal.example.com" } } } } Authenticate with per-user credentials Any user on the machine can read this file, so don’t store API keys or other credentials in env blocks.

Pass per-user credentials with one of these instead: ${VAR} expansion to read secrets from each user’s environment. OAuth or per-user headers so each user authenticates as themselves. headersHelper to generate credentials at connection time. Servers passed with --mcp-config or --strict-mcp-config When a session receives servers through --mcp-config while a managed-mcp.json that Claude Code can read and parse is deployed, what the user sees differs between a workstation and a cloud session: On a workstation, Claude Code exits at startup with You cannot dynamically configure MCP servers when an enterprise MCP config is present .

In cloud sessions on a host where the file is deployed, such as a self-hosted runner , Claude Code starts with the managed servers only and skips the claude.ai connectors and other servers the cloud host delivers through --mcp-config . Nothing in the session tells the user which servers were left out. Claude Code names them in a warning on its stderr, which a self-hosted runner records at the debug log level. The --strict-mcp-config flag asks to replace the managed set.

If a user passes it while such a file is deployed, Claude Code exits at startup on a workstation and in a cloud session alike. How allowlists and denylists apply to the managed set The denylist can further filter the servers in managed-mcp.json : deniedMcpServers applies to managed servers too, so a managed server that matches an entry won’t load. A user’s own deniedMcpServers merges in from their settings, so users can block a managed server for themselves.

The servers in managed-mcp.json need no allowedMcpServers entry, with one exception: Claude Code checks a server against the allowlist when it uses ${VAR} expansion outside env . Before v2.1.305, it also checked a server that used ${VAR} expansion only in env , and before v2.1.259, every managed server whenever an allowlist was set. See How a server is evaluated for which fields trigger the ${VAR} check and the full order of checks.

If you used allowedMcpServers to keep some of your managed-mcp.json servers from loading, add deniedMcpServers entries for them, or deploy a separate managed-mcp.json per group, before your users upgrade. Unless they use ${VAR} expansion outside env , these servers start loading on each user’s first launch of a version that doesn’t c

The rest of this page is on the live site.