Controllare l'accesso ai server MCP per la vostra organizzazione

• Scegliere un modello che corrisponda a quanto controllo avete bisogno
• Distribuire un set di server fisso con managed-mcp.json, incluso come disabilitare MCP completamente
• Fornire server attraverso impostazioni gestite mentre gli utenti mantengono i propri
• Controllare i server con allowlist e denylists
• Comunicare agli utenti cosa aspettarsi quando una restrizione blocca un server
• Monitorare quali server la vostra organizzazione utilizza effettivamente

​

Scegliere un pattern

​

Controllo esclusivo con managed-mcp.json

• I server che il file definisce
• I server che fornisci attraverso managedMcpServers
• I server in-process che l’app che ha avviato la sessione registra, come il server proprio dell’estensione VS Code o i connettori che l’app desktop fornisce
• Il server integrato Claude in Chrome, se lo consenti insieme al set gestito

​

Distribuire 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"
      }
    }
  }
}

​

Autenticarsi con credenziali per utente

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

​

Server passati con --mcp-config o --strict-mcp-config

• Su una workstation, Claude Code esce all’avvio con You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• Nelle sessioni cloud su un host dove il file è distribuito, come un runner self-hosted, Claude Code si avvia solo con i server gestiti e salta i connettori claude.ai e gli altri server che l’host cloud fornisce attraverso --mcp-config. Nulla nella sessione comunica all’utente quali server sono stati omessi. Claude Code li nomina in un avviso su stderr, che un runner self-hosted registra al livello di log debug.

​

Come allowlist e denylists si applicano al set gestito

• deniedMcpServers si applica anche ai server gestiti, quindi un server gestito che corrisponde a una voce non verrà caricato.
• La propria deniedMcpServers di un utente si unisce dalle sue impostazioni, quindi gli utenti possono bloccare un server gestito per se stessi.

​

Convalidare la configurazione

1. claude mcp list mostra solo i server in managed-mcp.json, più quelli che fornisci attraverso managedMcpServers. Due altri risultati significano che qualcosa non va:
   • Se i server propri di un utente appaiono ancora, Claude Code non sta leggendo il file, quindi controlla il percorso e le autorizzazioni sulle sue directory padre.
   • Se i server del file non appaiono e la sezione MCP config diagnostics contrassegna la configurazione aziendale come non riuscita a analizzare, Claude Code non può leggere o analizzare il file. Correggi l’errore che quella sezione nomina, quindi fai riavviare Claude Code all’utente.
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 policy rifiuta il comando prima che qualsiasi cosa venga contattata.

​

Disabilitare MCP completamente

{
  "mcpServers": {}
}

​

Consentire i connettori claude.ai insieme al set gestito

​

Consentire Claude in Chrome insieme al set gestito

​

Fornire server tramite impostazioni gestite

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

​

Cosa può contenere una voce

• type è http o sse. Come in .mcp.json, streamable-http è accettato come alias per http.
• url è un URL https://. Claude Code rifiuta un URL http:// semplice, incluso uno che punta a localhost.
• La voce non ha un membro command, args, env o headersHelper, quindi un documento di impostazioni gestite non nomina mai un programma da eseguire sulla macchina di un utente.
• Nessun valore contiene un riferimento ${VAR}. Claude Code non espande le variabili di ambiente in queste voci, quindi scrivi valori letterali.
• Il nome del server contiene solo lettere, numeri, trattini e sottolineature, e nessuna chiave o valore contiene caratteri di controllo o formattazione invisibile.

​

Come si caricano i server forniti

• Un server fornito ha la precedenza su un server con lo stesso nome nell’ambito locale, di progetto o utente, e su un server plugin o connettore claude.ai che punta allo stesso URL.
• Se distribuisci anche managed-mcp.json, Claude Code carica i suoi server e i server forniti insieme, e la voce del file ha la precedenza quando entrambi definiscono un nome.
• I server forniti continuano a caricarsi quando strictPluginOnlyCustomization blocca la superficie mcp.
• deniedMcpServers si applica ai server forniti, incluse le voci dalle impostazioni personali di un utente, quindi un utente può bloccarne uno per se stesso. I server forniti non necessitano di una voce allowedMcpServers.

• Un server che un utente passa con --mcp-config con lo stesso nome sostituisce quello fornito per quella esecuzione ed è controllato rispetto a allowedMcpServers.
• --strict-mcp-config lascia fuori i server forniti insieme a ogni altro server configurato.

​

Cosa gli utenti possono vedere e modificare

• claude mcp remove segnala che il server è fornito dall’organizzazione.
• Quando non hai anche distribuito managed-mcp.json, una voce che un utente aggiunge con lo stesso nome viene salvata ma non utilizzata mentre la tua è presente.
• Gli utenti possono comunque disattivare un server fornito per se stessi in /mcp, che elenca i server forniti sotto Managed MCPs.

​

Dove si applica managedMcpServers

​

Quando i server forniti si connettono

• Su una macchina con impostazioni memorizzate nella cache, Claude Code trattiene la copia memorizzata nella cache di questa chiave fino a quando il server non conferma le impostazioni per la sessione, e attende quella conferma prima di caricare i server MCP. Se la conferma fallisce, la sessione continua senza i server forniti e /status dice che sono trattenuti.
• Al primo avvio di una macchina, senza nulla memorizzato nella cache ancora, una sessione interattiva che inizia prima dell’arrivo delle impostazioni connette i server forniti non appena arrivano, e un’esecuzione claude -p che è già iniziata può terminare senza di loro.

• Aggiungere un server: Claude Code lo connette quando arrivano le impostazioni aggiornate, senza un riavvio.
• Modificare la voce di un server: quelle sessioni si riconnettono ad esso con la nuova definizione.
• Rimuovere un server: una sessione interattiva in esecuzione lo disconnette una volta che legge le impostazioni modificate. Un’esecuzione non interattiva (-p) lo mantiene fino alla fine.

​

Controllo basato su policy con allowlist e denylist

​

Abbinare server per URL, comando o nome

• In deniedMcpServers, serverName accetta qualsiasi stringa non vuota senza spazi iniziali o finali, quindi puoi bloccare i connettori claude.ai per il loro nome visualizzato. Ad esempio, { "serverName": "claude.ai Slack" } blocca il connettore Slack. Preferisci una voce serverUrl quando hai bisogno che il deny sia robusto rispetto ai cambi di nome, o quando un nome di connettore collide e ottiene un suffisso (N).
• In allowedMcpServers, serverName è limitato a lettere, numeri, trattini e sottolineature. Utilizza serverUrl per aggiungere all’allowlist un connettore claude.ai che Claude Code recupera da solo; per i connettori che un host cloud fornisce alle sessioni self-hosted, utilizza invece le voci elencate in Il traffico dei connettori esce dalla tua rete.

​

Come viene valutato un server

1. Unisci gli elenchi. Le voci di allowlist e denylist da ogni ambito di impostazioni si combinano in un allowlist e un denylist. Quando allowManagedMcpServersOnly è true, viene mantenuto solo l’allowlist gestito; il denylist si unisce sempre da ogni ambito. Quando è presente più di una fonte gestita, Le chiavi lette da ogni fonte admin dice quali di esse forniscono gli elenchi dell’ambito gestito.
2. Controlla il denylist. Un server che corrisponde a qualsiasi voce del denylist, per URL, comando o nome, viene bloccato. Nulla sostituisce una corrispondenza del denylist.
3. Controlla l’allowlist. Se allowedMcpServers non è impostato da nessuna parte, ogni server che ha superato il denylist si carica. Se è impostato, ciò a cui il server deve corrispondere dipende dal suo tipo, mostrato nella tabella di seguito. Tre gruppi di server saltano questo controllo:
   • I server dell’organizzazione: ogni voce managedMcpServers e qualsiasi voce managed-mcp.json i cui valori non utilizzano l’espansione ${VAR}.
   • Server integrati, come Claude in Chrome, il server ide a cui Claude Code si connette in un IDE VS Code o JetBrains in esecuzione, e i server che la CLI stessa configura.
   • I tool Slack di una sessione Claude Tag: i server che utilizza per leggere il thread e pubblicare le sue risposte si caricano senza una voce di allowlist.
   Un server managed-mcp.json che utilizza l’espansione ${VAR} nel suo comando, argomenti, env, URL o intestazioni viene comunque controllato. Lo stesso vale per ogni server che un utente, un plugin, o claude.ai aggiunge, e ogni server che un utente passa con --mcp-config.

• I comandi corrispondono esattamente. Ogni argomento, in ordine. ["npx", "-y", "server"] non corrisponde a ["npx", "server"] o ["npx", "-y", "server", "--flag"].
• I valori serverCommand e serverUrl si espandono prima della corrispondenza. Sia la voce della policy che il valore configurato del server passano attraverso l’espansione ${VAR} e ${VAR:-default}, quindi una voce scritta come ["${HOME}/bin/server"] corrisponde a una configurazione del server che utilizza lo stesso riferimento o il percorso espanso. Su Windows, fai riferimento a una variabile di ambiente impostata lì, come ${USERPROFILE} invece di ${HOME}. I valori serverName corrispondono letteralmente e non si espandono mai. I due lati leggono ambienti diversi; Come si espandono le voci della policy copre quale e come differiscono le voci di allowlist e denylist.
• Gli URL supportano wildcard * 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 e minuscole.

​

Come si espandono le voci della policy

​

Configurazione di esempio

{
  "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 nel denylist. Le voci del denylist si applicano sempre, quindi qualsiasi server denominato dangerous-server viene bloccato indipendentemente dal suo URL o comando.

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

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

​

Come le restrizioni appaiono agli utenti

​

Monitorare l’utilizzo di MCP

​

Riepilogo della configurazione

​

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