Control MCP server access for your organization

• 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

​

Choose a pattern

​

Exclusive control with managed-mcp.json

​

Deploy managed-mcp.json

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

• ${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

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

​

How allowlists and denylists apply to the managed set

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

​

Validate the configuration

1. claude mcp list shows only the servers in managed-mcp.json, plus any you provide through managedMcpServers. If a user’s own servers still appear, the file isn’t being read; check the path and permissions.
2. claude mcp add --transport http test https://example.com/mcp fails with Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. The URL doesn’t need to be a real server, since the policy check rejects the command before anything is contacted.

​

Disable MCP entirely

{
  "mcpServers": {}
}

​

Allow claude.ai connectors alongside the managed set

​

Provide servers through managed settings

{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    },
    "records": {
      "type": "http",
      "url": "https://records.example.com/mcp",
      "headers": {
        "X-Records-Key": "key-issued-for-all-claude-code-users"
      }
    }
  }
}

​

What an entry can contain

• type is http or sse. As in .mcp.json, streamable-http is accepted as an alias for http.
• url is an https:// URL. Claude Code refuses a plain http:// URL, including one that points at localhost.
• The entry has no command, args, env, or headersHelper member, so a managed settings document never names a program to run on a user’s machine.
• No value contains a ${VAR} reference. Claude Code doesn’t expand environment variables in these entries, so write literal values.
• The server name contains only letters, numbers, hyphens, and underscores, and no key or value contains control or invisible formatting characters.

​

How provided servers load

• A provided server takes precedence over a server with the same name in local, project, or user scope, and over a plugin server or claude.ai connector that points at the same URL.
• If you also deploy managed-mcp.json, Claude Code loads its servers and the provided servers together, and the file’s entry takes precedence when both define a name.
• Provided servers keep loading when strictPluginOnlyCustomization locks the mcp surface.
• deniedMcpServers applies to provided servers, including entries from a user’s own settings, so a user can block one for themselves. Provided servers need no allowedMcpServers entry.

• A server a user passes with --mcp-config under the same name replaces the provided one for that run and is checked against allowedMcpServers.
• --strict-mcp-config leaves provided servers out along with every other configured server.

​

What users can see and change

• claude mcp remove reports that the server is provided by the organization.
• When you haven’t also deployed managed-mcp.json, an entry a user adds under the same name is saved but not used while yours is present.
• Users can still turn a provided server off for themselves in /mcp, which lists provided servers under Managed MCPs.

​

Where managedMcpServers applies

​

When provided servers connect

• On a machine with cached settings, Claude Code withholds the cached copy of this key until the server confirms the settings for the session, and waits for that confirmation before it loads MCP servers. If the confirmation fails, the session continues without the provided servers and /status says they are withheld.
• On a machine’s first launch, with nothing cached yet, an interactive session that starts before the settings arrive connects the provided servers as soon as they do, and a claude -p run that has already started can finish without them.

• Add a server: Claude Code connects it when the updated settings arrive, without a restart.
• Change a server’s entry: those sessions reconnect to it with the new definition.
• Remove a server: a running interactive session disconnects it once it reads the changed settings. A non-interactive (-p) run keeps it until it ends.

​

Policy-based control with allowlists and denylists

​

Match servers by URL, command, or name

• In deniedMcpServers, serverName accepts any non-empty string, so you can block claude.ai connectors by their display name. For example, { "serverName": "claude.ai Slack" } blocks the Slack connector. Prefer a serverUrl entry when you need the deny to be robust to renames, or when a connector name collides and gains a (N) suffix.
• In allowedMcpServers, serverName is limited to letters, numbers, hyphens, and underscores. Use serverUrl to allowlist a claude.ai connector Claude Code fetches itself; for connectors a cloud host delivers to self-hosted sessions, use the entries listed under Connector traffic leaves your network instead.

​

How a server is evaluated

1. Merge the lists. Allowlist and denylist entries from every settings scope combine into one allowlist and one denylist, with the managed scope’s lists coming from the managed source or sources Claude Code applies. When allowManagedMcpServersOnly is true, only the managed allowlist is kept; the denylist always merges from every scope.
2. Check the denylist. A server that matches any denylist entry, by URL, command, or name, is blocked. Nothing overrides a denylist match.
3. Check the allowlist. If allowedMcpServers isn’t set anywhere, every server that passed the denylist loads. If it is set, what the server must match depends on its type, shown in the table below. The organization’s own servers skip this check: every managedMcpServers entry, and any managed-mcp.json entry whose values use no ${VAR} expansion. Built-in servers skip it too, such as Claude in Chrome, the ide server Claude Code connects to in a running VS Code or JetBrains IDE, and servers the CLI itself configures. A managed-mcp.json server that uses ${VAR} expansion in its command, arguments, env, URL, or headers is still checked, as is every server a user, a plugin, --mcp-config, or claude.ai adds.

• Commands match exactly. Every argument, in order. ["npx", "-y", "server"] does not match ["npx", "server"] or ["npx", "-y", "server", "--flag"].
• serverCommand and serverUrl values expand before matching. Both the policy entry and the server’s configured value go through ${VAR} and ${VAR:-default} expansion, so an entry written as ["${HOME}/bin/server"] matches a server config that uses either the same reference or the expanded path. On Windows, reference an environment variable that is set there, such as ${USERPROFILE} instead of ${HOME}. serverName values match literally and never expand. The two sides read different environments; How policy entries expand covers which, and how allowlist and denylist entries differ.
• URLs support * wildcards anywhere in the pattern, including the scheme. Hostname matching is case-insensitive and ignores a trailing FQDN dot, so https://Mcp.Example.com/* matches https://mcp.example.com/api. Paths stay case-sensitive.

​

How policy entries expand

​

Example configuration

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

• Line 3: the first serverUrl entry. Once one exists, every remote server must match a URL pattern, so a user can’t get an unlisted remote server through by giving it an allowed name.
• Line 5: the first serverCommand entry. Same effect for stdio servers, so every local server must match a listed command exactly.
• Line 11: a serverName entry in the denylist. Denylist entries always apply, so any server named dangerous-server is blocked regardless of its URL or command.

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

{
  "allowedMcpServers": [
    { "serverUrl": "https://*.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://staging.example.com/*" }
  ]
}

​

Restrict the allowlist to managed settings only

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

​

How restrictions appear to users

​

Monitor MCP usage

​

Configuration summary

​

Related resources

• Decide what to enforce: MCP restrictions alongside permission rules, sandboxing, and the other admin controls
• Connect Claude Code to tools via MCP: the full MCP reference, including transports, scopes, and authentication
• Settings: the settings hierarchy and how managed settings take precedence
• Server-managed settings: deliver allowedMcpServers and deniedMcpServers from the Claude.ai admin console
• Security: the threat model these controls defend against
• Claude Enterprise Administrator Guide: SSO, SCIM, seat management, and rollout playbook