Controllare l'accesso ai server MCP per la vostra organizzazione

Limitare quali server MCP gli utenti possono aggiungere o connettere con file di configurazione gestiti, allowlist e denylist.

Per impostazione predefinita, chiunque esegua Claude Code può connettere qualsiasi server MCP desideri. Anthropic esamina i connettori rispetto ai suoi criteri di elenco prima di aggiungerli alla Directory Anthropic, ma non esegue audit di sicurezza né gestisce alcun server MCP. Come amministratore, potete limitare quali server vengono eseguiti nella vostra organizzazione, da un set fisso approvato alla disabilitazione completa di MCP.

Questa pagina spiega come:

• Scegliere un modello che corrisponda al livello di controllo di cui avete bisogno
• Distribuire un set di server fisso con managed-mcp.json, incluso come disabilitare completamente MCP
• Controllare i server con allowlist e denylist
• Comunicare agli utenti cosa aspettarsi quando una restrizione blocca un server
• Monitorare quali server la vostra organizzazione utilizza effettivamente

Scegliere un modello

Claude Code supporta una gamma di livelli di restrizione. Ogni modello utilizza uno o entrambi i meccanismi descritti di seguito: managed-mcp.json per distribuire un set fisso, e allowedMcpServers/deniedMcpServers per filtrare ciò che gli utenti configurano.

Controllo esclusivo con managed-mcp.json

Se distribuite un file managed-mcp.json, Claude Code carica solo i server che quel file definisce. Gli utenti non possono aggiungere, modificare o utilizzare alcun altro server MCP, inclusi i server forniti da plugin. Il file sopprime anche i connettori di claude.ai a meno che non li consentiate insieme al set gestito.

Due altre impostazioni possono filtrare ulteriormente il set gestito:

• allowedMcpServers e deniedMcpServers si applicano anche ai server gestiti, quindi un server gestito che non li supera non verrà caricato.
• Il proprio deniedMcpServers di un utente si unisce dalle sue impostazioni, quindi gli utenti possono bloccare un server gestito per se stessi.

Vedere Come viene valutato un server per l'ordine completo dei controlli.

managed-mcp.json è un file autonomo, quindi non può essere consegnato attraverso impostazioni gestite dal server. Qualsiasi processo che possa scrivere in un percorso di sistema con privilegi di amministratore può distribuirlo. Su larga scala, di solito avviene attraverso strumenti di gestione dei dispositivi, come Jamf o un profilo di configurazione su macOS, Criteri di gruppo o Intune su Windows, o la gestione della flotta di vostra scelta su Linux. Claude Code cerca il file in uno di questi percorsi:

Il file utilizza lo stesso formato di un file di progetto .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"
      }
    }
  }
}

Autenticarsi con credenziali per utente

Qualsiasi utente sulla macchina può leggere questo file, quindi non archiviate chiavi API o altre credenziali nei blocchi env. Passate le credenziali per utente con uno di questi:

• Espansione ${VAR} per leggere i segreti dall'ambiente di ogni utente.
• OAuth o intestazioni per utente in modo che ogni utente si autentichi come se stesso.
• headersHelper per generare credenziali al momento della connessione.

Convalidare la configurazione

Per confermare che il file è in vigore, eseguite due controlli su una macchina gestita:

1. claude mcp list mostra solo i server in managed-mcp.json. Se i server personali di un utente appaiono ancora, il file non viene letto; controllate il percorso e i permessi.
2. claude mcp add --transport http test https://example.com/mcp fallisce con Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. L'URL non deve essere un server reale, poiché il controllo della politica rifiuta il comando prima che qualsiasi cosa venga contattata.

Disabilitare MCP interamente

Distribuite un managed-mcp.json contenente una mappa di server vuota per bloccare ogni server MCP:

{
  "mcpServers": {}
}

Gli utenti non vedono alcun server MCP in /mcp, e claude mcp add fallisce con l'errore di politica aziendale di cui sopra. I server che gli utenti avevano precedentemente configurato smettono di caricarsi la prossima volta che avviano una sessione, senza alcun avviso che la politica è il motivo.

Consentire i connettori di claude.ai insieme al set gestito

La distribuzione di managed-mcp.json sopprime i connettori di claude.ai per impostazione predefinita, inclusi i connettori che un amministratore ha configurato per l'organizzazione nella console di amministrazione di claude.ai. Per caricare quei connettori insieme ai server in managed-mcp.json, impostate "allowAllClaudeAiMcps": true in una fonte di impostazioni gestite. Richiede Claude Code v2.1.149 o successivo.

Con l'impostazione abilitata, Claude Code carica gli stessi connettori di claude.ai che caricherrebbe se managed-mcp.json non fosse distribuito. Elenchi consentiti e elenchi negati si applicano ancora a quei connettori, quindi potete bloccare quelli specifici con deniedMcpServers. L'impostazione influisce solo sui connettori di claude.ai; i server forniti da plugin rimangono soppressi.

Claude Code legge questa impostazione solo dai livelli di politica controllati dall'amministratore: impostazioni gestite dal server, una chiave di registro plist distribuita da MDM o HKLM, o un file managed-settings.json di sistema. Inserirla nelle impostazioni utente o di progetto non ha alcun effetto, quindi gli utenti non possono riabilitare i connettori che il controllo esclusivo ha soppresso.

Controllo basato su politica con allowlist e denylist

Le allowlist e le denylist filtrano quali server configurati sono autorizzati a caricarsi. Non sono un registro: un server deve comunque essere aggiunto da un utente, un plugin o managed-mcp.json prima che l'allowlist o la denylist si applichino ad esso. Per distribuire server agli utenti, utilizzate managed-mcp.json.

Per rendere l'allowlist autorevole, impostate allowedMcpServers e allowManagedMcpServersOnly: true insieme in una fonte di impostazioni gestite, come impostazioni gestite dal server o un file managed-settings.json distribuito. Limitare l'allowlist solo alle impostazioni gestite mostra la configurazione. Senza allowManagedMcpServersOnly, le allowlist da ogni fonte di impostazioni si uniscono, incluso il ~/.claude/settings.json personale di un utente, quindi un utente può ampliare ciò che la vostra allowlist consente. Le denylist si uniscono da ogni fonte indipendentemente.

Abbinare i server per URL, comando o nome

allowedMcpServers e deniedMcpServers sono elenchi di voci. Ogni voce è un oggetto con una singola chiave che identifica i server per il loro URL, il loro comando o il loro nome:

Lasciare allowedMcpServers non impostato è diverso dall'impostarlo su un array vuoto:

La validazione di serverName differisce tra i due elenchi:

• {/* min-version: 2.1.182 */}In deniedMcpServers, serverName accetta qualsiasi stringa non vuota, quindi potete bloccare i connettori claude.ai per il loro nome visualizzato. Ad esempio, { "serverName": "claude.ai Slack" } blocca il connettore Slack. Preferite una voce serverUrl quando avete bisogno che il blocco sia robusto rispetto ai cambi di nome, o quando un nome di connettore collide e guadagna un suffisso (N).
• In allowedMcpServers, serverName è limitato a lettere, numeri, trattini e sottolineature. Utilizzate serverUrl per aggiungere un connettore claude.ai all'allowlist.

Per disattivare tutti i connettori claude.ai, vedere disableClaudeAiConnectors.

Come viene valutato un server

Prima di caricare un server, incluso uno da managed-mcp.json, Claude Code esegue tre controlli in ordine:

1. Unire gli elenchi. Le voci di allowlist e denylist da ogni fonte di impostazioni si combinano in un allowlist e una denylist. Quando allowManagedMcpServersOnly è true, viene mantenuto solo l'allowlist gestito; la denylist si unisce sempre da ogni fonte.
2. Controllare la denylist. Un server che corrisponde a qualsiasi voce di denylist, per URL, comando o nome, viene bloccato. Nulla sostituisce una corrispondenza di denylist.
3. Controllare l'allowlist. Se allowedMcpServers non è impostato da nessuna parte, ogni server che ha superato la denylist viene caricato. Se è impostato, ciò a cui il server deve corrispondere dipende dal suo tipo, mostrato nella tabella di seguito.

Due regole di corrispondenza si applicano all'interno di questi controlli:

• I comandi corrispondono esattamente. Ogni argomento, in ordine. ["npx", "-y", "server"] non corrisponde a ["npx", "server"] o ["npx", "-y", "server", "--flag"].
• Gli URL supportano caratteri jolly * ovunque nel modello, incluso lo schema. La corrispondenza del nome host non distingue tra maiuscole e minuscole e ignora un punto FQDN finale, quindi https://Mcp.Example.com/* corrisponde a https://mcp.example.com/api. I percorsi rimangono sensibili alle maiuscole.

Configurazione di esempio

La configurazione di seguito configura un allowlist rigido con una denylist. Le righe evidenziate cambiano il modo in cui il resto dell'elenco viene valutato, e i callout dopo il blocco spiegano ognuno:

{
  "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/*" }
  ]
}

• Riga 3: la prima voce serverUrl. Una volta che ne esiste una, ogni server remoto deve corrispondere a un modello di URL, quindi un utente non può ottenere un server remoto non elencato dandogli un nome consentito.
• Riga 5: la prima voce serverCommand. Lo stesso effetto per i server stdio, quindi ogni server locale deve corrispondere esattamente a un comando elencato.
• Riga 11: una voce serverName nella denylist. Le voci di denylist si applicano sempre, quindi qualsiasi server denominato dangerous-server viene bloccato indipendentemente dal suo URL o comando.

Una voce serverName in questo allowlist non corrisponderebbe mai a nulla, poiché entrambi i tipi di trasporto hanno già voci più rigorose.

Gli accordion di seguito illustrano come un server viene valutato rispetto ad altre combinazioni di allowlist e denylist.

{
"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/*" }
]
}

Limitare l'allowlist solo alle impostazioni gestite

Per rendere l'allowlist gestito l'unico che si applica, impostate allowManagedMcpServersOnly nel file di impostazioni gestite:

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

Quando allowManagedMcpServersOnly è true, le allowlist dalle impostazioni di utente, progetto e locale vengono ignorate. La denylist si unisce comunque da tutte le fonti, quindi gli utenti possono sempre bloccare i server per se stessi.

Come le restrizioni appaiono agli utenti

Quando una restrizione blocca un server, l'utente vede un errore da claude mcp add o il server smette silenziosamente di caricarsi. Utilizzate questa tabella per riconoscere questi rapporti e per comunicare agli utenti cosa aspettarsi prima di implementare una modifica:

Nell'ultimo caso, l'utente non riceve alcun segnale che la politica è il motivo per cui il suo server è scomparso, quindi comunicate agli utenti interessati quali server sono bloccati quando implementate una nuova restrizione.

Monitorare l'utilizzo di MCP

Quando l'esportazione OpenTelemetry è configurata, Claude Code può registrare quali server MCP e strumenti gli utenti invocano. Impostate OTEL_LOG_TOOL_DETAILS=1 per includere i nomi dei server MCP e degli strumenti negli eventi degli strumenti, quindi aggregateli nel vostro collector per vedere quali server i vostri utenti effettivamente connettono. Vedere Monitoraggio per configurare l'esportatore e per lo schema completo degli eventi.

Riepilogo della configurazione

Ogni file e impostazione che questa pagina copre, cosa controlla e come consegnarlo:

Risorse correlate

• Decidere cosa applicare: restrizioni MCP insieme alle regole di autorizzazione, sandboxing e agli altri controlli di amministrazione
• Connettere Claude Code agli strumenti tramite MCP: il riferimento MCP completo, inclusi trasporti, ambiti e autenticazione
• Impostazioni: la gerarchia delle impostazioni e come le impostazioni gestite hanno la precedenza
• Impostazioni gestite dal server: consegnare allowedMcpServers e deniedMcpServers dalla console di amministrazione di Claude.ai
• Sicurezza: il modello di minaccia che questi controlli difendono
• Guida dell'amministratore Claude Enterprise: SSO, SCIM, gestione dei posti e playbook di implementazione