mcp.md +99 −8
671* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`671* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`
672* **Linux**: `/etc/claude-code/managed-settings.json`672* **Linux**: `/etc/claude-code/managed-settings.json`
673 673
674#### Restriction options
675
676Each entry in the allowlist or denylist can restrict servers in two ways:
677
6781. **By server name** (`serverName`): Matches the configured name of the server
6792. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers
680
681**Important**: Each entry must have **either** `serverName` **or** `serverCommand`, not both.
682
683#### Example configuration
684
674```json theme={null}685```json theme={null}
675{686{
676 "allowedMcpServers": [687 "allowedMcpServers": [
688 // Allow by server name
677 { "serverName": "github" },689 { "serverName": "github" },
678 { "serverName": "sentry" },690 { "serverName": "sentry" },
679691 { "serverName": "company-internal" }
692 // Allow by exact command (for stdio servers)
693 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
694 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] }
680 ],695 ],
681 "deniedMcpServers": [696 "deniedMcpServers": [
682697 { "serverName": "filesystem" } // Block by server name
698 { "serverName": "dangerous-server" },
699
700 // Block by exact command (for stdio servers)
701 { "serverCommand": ["npx", "-y", "unapproved-package"] }
683 ]702 ]
684}703}
685```704```
686 705
687706**Allowlist behavior (`allowedMcpServers`)**:#### How command-based restrictions work
707
708**Exact matching**:
709
710* Command arrays must match **exactly** - both the command and all arguments in the correct order
711* Example: `["npx", "-y", "server"]` will NOT match `["npx", "server"]` or `["npx", "-y", "server", "--flag"]`
712
713**Stdio server behavior**:
714
715* When the allowlist contains **any** `serverCommand` entries, stdio servers **must** match one of those commands
716* Stdio servers cannot pass by name alone when command restrictions are present
717* This ensures administrators can enforce which commands are allowed to run
718
719**Non-stdio server behavior**:
720
721* Remote servers (HTTP, SSE, WebSocket) always match by name only
722* Command restrictions do not apply to remote servers
723
724<Accordion title="Example: Command-only allowlist">
725 ```json theme={null}
726 {
727 "allowedMcpServers": [
728 { "serverCommand": ["npx", "-y", "approved-package"] }
729 ]
730 }
731 ```
732
733 **Result**:
734
735 * Stdio server with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)
736 * Stdio server with `["node", "server.js"]`: ❌ Blocked (doesn't match command)
737 * HTTP server named "my-api": ❌ Blocked (no name entries to match)
738</Accordion>
739
740<Accordion title="Example: Mixed name and command allowlist">
741 ```json theme={null}
742 {
743 "allowedMcpServers": [
744 { "serverName": "github" },
745 { "serverCommand": ["npx", "-y", "approved-package"] }
746 ]
747 }
748 ```
749
750 **Result**:
751
752 * Stdio server named "local-tool" with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)
753 * Stdio server named "local-tool" with `["node", "server.js"]`: ❌ Blocked (command entries exist but doesn't match)
754 * Stdio server named "github" with `["node", "server.js"]`: ❌ Blocked (stdio servers must match commands when command entries exist)
755 * HTTP server named "github": ✅ Allowed (matches name)
756 * HTTP server named "other-api": ❌ Blocked (name doesn't match)
757</Accordion>
758
759<Accordion title="Example: Name-only allowlist">
760 ```json theme={null}
761 {
762 "allowedMcpServers": [
763 { "serverName": "github" },
764 { "serverName": "internal-tool" }
765 ]
766 }
767 ```
768
769 **Result**:
770
771 * Stdio server named "github" with any command: ✅ Allowed (no command restrictions)
772 * Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)
773 * HTTP server named "github": ✅ Allowed (matches name)
774 * Any server named "other": ❌ Blocked (name doesn't match)
775</Accordion>
776
777#### Allowlist behavior (`allowedMcpServers`)
688 778
689* `undefined` (default): No restrictions - users can configure any MCP server779* `undefined` (default): No restrictions - users can configure any MCP server
690* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers780* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers
691781* List of server names: Users can only configure the specified servers* List of entries: Users can only configure servers that match by name or command
692 782
693783**Denylist behavior (`deniedMcpServers`)**:#### Denylist behavior (`deniedMcpServers`)
694 784
695* `undefined` (default): No servers are blocked785* `undefined` (default): No servers are blocked
696* Empty array `[]`: No servers are blocked786* Empty array `[]`: No servers are blocked
697787* List of server names: Specified servers are explicitly blocked across all scopes* List of entries: Specified servers are explicitly blocked across all scopes
698 788
699789**Important notes**:#### Important notes
700 790
701* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`791* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`
702792* **Denylist takes absolute precedence**: If a server appears in both lists, it will be blocked* **Denylist takes absolute precedence**: If a server matches a denylist entry (by name or command), it will be blocked even if it's on the allowlist
793* Name-based and command-based restrictions work together: a server passes if it matches **either** a name entry **or** a command entry (unless blocked by denylist)
703 794
704<Note>795<Note>
705 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations.796 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations.