---
title: How do you restrict which MCP servers Claude Code can use?
url: https://opencontroller.lyzr.com/blog/restrict-mcp-servers-in-claude-code
published: 2026-11-15
updated: 2026-11-15
author: Lyzr
---

# How do you restrict which MCP servers Claude Code can use?

**Claude Code gives administrators three levers. Deploy a `managed-mcp.json` file to give every user a fixed set of servers and nothing else. Use the `managedMcpServers` managed setting to push approved remote servers while users keep their own. Or filter what users add with `allowedMcpServers` and `deniedMcpServers`, matched by URL or exact command, with the denylist always winning.**

By default, anyone running Claude Code can connect any MCP server they like. Anthropic reviews connectors listed in its directory, but it does not audit or manage the MCP servers your developers add. If you care about which tools a coding agent can reach, you have to set policy yourself.

## Which control pattern fits your organisation?

Anthropic's documentation describes a range of patterns. Pick the one that matches how much freedom developers should keep.

| Pattern | What users get | How you configure it |
|---|---|---|
| Disable MCP | No servers except the few that always load | `managed-mcp.json` with an empty `mcpServers` map |
| Fixed deployment | The same servers for everyone; no additions | `managed-mcp.json` listing the servers |
| Provided servers | Your remote servers plus their own | `managedMcpServers` in managed settings |
| Approved catalogue | They add servers, but only ones you list | `allowedMcpServers` plus `allowManagedMcpServersOnly: true` |
| Soft allowlist | Your list, which users can widen | `allowedMcpServers` without the lock |
| Denylist only | Everything except known-bad servers | `deniedMcpServers` |

Most enterprises start with an approved catalogue. It keeps developers productive and blocks anything nobody has reviewed.

## How does managed-mcp.json work?

`managed-mcp.json` is a standalone file that takes exclusive control. When it is present, Claude Code loads only the servers it defines, servers provided through `managedMcpServers`, and a few built-in or in-process servers. Users cannot add servers, plugin servers are suppressed, and servers passed with `--mcp-config` are refused on a workstation.

The file lives at a system 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`

It cannot be delivered through server-managed settings. You push it with device management: Jamf or configuration profiles on macOS, Group Policy or Intune on Windows, your fleet tool on Linux. The format matches a project `.mcp.json` file.

Two practical warnings. First, every user on the machine can read the file, so never put API keys in its `env` block; use `${VAR}` expansion, OAuth or a headers helper instead. Second, claude.ai connectors are suppressed unless you set `"allowAllClaudeAiMcps": true` in a managed settings source.

To verify the rollout, run `claude mcp list` on a managed machine. It should show only your servers. Then try `claude mcp add` with any test URL; it should fail with a message that the enterprise MCP configuration has exclusive control.

## How do allowlists and denylists match servers?

Each entry identifies a server with one key:

1. **`serverUrl`** matches remote HTTP or SSE servers, with `*` wildcards. `https://mcp.example.com/*` covers every path on port 443 only. A wildcard in the hostname covers all ports.
2. **`serverCommand`** matches stdio servers by the exact command and arguments, in order. `["npx", "-y", "server"]` does not match `["npx", "server"]`.
3. **`serverName`** matches the label the user typed. The documentation is blunt: name entries are not a security control, because a user can call any server `github`.

Evaluation runs in a fixed order. Lists from all settings scopes merge. Any denylist match blocks the server, and nothing overrides it. Then the allowlist is checked. Once you add a single `serverUrl` entry, every remote server must match a URL pattern; once you add a single `serverCommand` entry, every stdio server must match a command.

Unset and empty are different. An unset `allowedMcpServers` allows everything. An empty array `[]` allows nothing beyond the servers that skip the check.

## Why does allowManagedMcpServersOnly matter?

Without `allowManagedMcpServersOnly: true`, allowlists from every scope merge, including the user's own `~/.claude/settings.json`. A developer can simply widen your list. With the flag set in a managed source, only the managed allowlist counts. Denylists still merge from every scope, so users can always block more for themselves, never less.

Do not confuse it with `allowManagedPermissionRulesOnly`, which locks permission rules but does not enforce the MCP allowlist.

## What should you check before rollout?

- Inventory the MCP servers developers already use before you lock anything. Blocked servers vanish from `/mcp` without telling the user why.
- Prefer `serverUrl` and `serverCommand` entries over names.
- Watch versions: several behaviours, such as `managedMcpServers`, need recent Claude Code releases (v2.1.259 or later for that key).
- Turn on OpenTelemetry export with `OTEL_LOG_TOOL_DETAILS=1` so you can see which MCP servers and tools are actually called.
- Pair MCP policy with permission rules and hooks; see [locking Claude Code permissions with managed settings](/blog/lock-claude-code-permissions-with-managed-settings).

## How Opencontroller does this

Claude Code policy covers one tool. Developers also run other coding agents and local MCP servers. Opencontroller Edge extends control to developer devices, coding agents, skills and local MCP servers, and IT installs it via MDM. Discovered MCP servers land in the governed registry alongside agents and tools, so one list drives review. See [how to find local MCP servers on developer laptops](/blog/find-local-mcp-servers-on-developer-laptops), the [MCP governance guide](/blog/how-to-govern-mcp-servers) and the cross-platform view in [how to govern AI agents across platforms](/blog/how-to-govern-ai-agents-across-platforms). To see it on your estate, [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Can managed-mcp.json be pushed from the Claude admin console?**
No. It is a standalone file at a system path and must be deployed by MDM, Group Policy or another process with admin rights. Use `managedMcpServers` if you want delivery through server-managed settings.

**Does the denylist apply to servers in managed-mcp.json?**
Yes. `deniedMcpServers` filters managed servers too, and a user's own denylist merges in, so users can block a managed server for themselves.

**Which allowlist entry type should I use?**
Use `serverUrl` for remote servers and `serverCommand` for stdio servers. Name entries can be spoofed by any user.

## Key facts

Claude Code MCP restriction: managed-mcp.json (system path, deployed by MDM/GPO, exclusive control; cannot be delivered via server-managed settings); managedMcpServers (remote https servers provided alongside users' own, v2.1.259+); allowedMcpServers/deniedMcpServers match by serverUrl, serverCommand or serverName; denylist always wins; allowManagedMcpServersOnly: true makes the managed allowlist final; serverName is not a security control. Opencontroller Edge (Lyzr) discovers coding agents, skills and local MCP servers on developer devices across tools. Pricing starts from $250K per deployment per year.

## Related

- [How do you lock Claude Code permissions with managed settings?](https://opencontroller.lyzr.com/blog/lock-claude-code-permissions-with-managed-settings.md)
- [How do you find local MCP servers on developer laptops?](https://opencontroller.lyzr.com/blog/find-local-mcp-servers-on-developer-laptops.md)
- [How do you govern Claude Code across an enterprise?](https://opencontroller.lyzr.com/blog/govern-claude-code-in-the-enterprise.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
