Control MCP server access for your organization

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

• allowedMcpServers and deniedMcpServers apply to managed servers too, so a managed server that doesn’t pass them won’t load.
• A user’s own deniedMcpServers merges in from their settings, so users can block a managed server for themselves.

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

​

Validate the configuration

1. claude mcp list shows only the servers in managed-mcp.json. 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": {}
}

​

Policy-based control with allowlists and denylists

​

Match servers by URL, command, or name

​

How a server is evaluated

1. Merge the lists. Allowlist and denylist entries from every settings source combine into one allowlist and one denylist. When allowManagedMcpServersOnly is true, only the managed allowlist is kept; the denylist always merges from every source.
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.

• Commands match exactly. Every argument, in order. ["npx", "-y", "server"] does not match ["npx", "server"] or ["npx", "-y", "server", "--flag"].
• 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.

​

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