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 definiti nel file
• I server che fornisci tramite managedMcpServers
• I server in-process registrati dall’app che ha avviato la sessione, come il server proprio dell’estensione VS Code o i connettori forniti dall’app desktop
• 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 ciascun utente.
• OAuth o header per utente in modo che ogni utente si autentichi con la propria identità.
• headersHelper per generare le credenziali al momento della connessione.

​

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

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

​

Come si applicano allowlist e denylist al set gestito

• deniedMcpServers si applica anche ai server gestiti, quindi un server gestito che corrisponde a una voce non verrà caricato.
• Il deniedMcpServers di un utente viene unito tramite merge 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 tramite managedMcpServers. Altri due risultati indicano un problema:
   • Se compaiono ancora i server propri di un utente, Claude Code non sta leggendo il file, quindi controlla il percorso e i permessi delle directory padre.
   • Se i server del file non compaiono e la sezione MCP config diagnostics indica che l’analisi della configurazione enterprise non è riuscita, Claude Code non riesce a leggere o analizzare il file. Correggi l’errore indicato in quella sezione, quindi chiedi all’utente di riavviare Claude Code.
2. claude mcp add --transport http test https://example.com/mcp non riesce con Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. Non è necessario che l’URL corrisponda a un server reale, poiché il controllo della policy rifiuta il comando prima di contattare qualsiasi cosa.

​

Disabilitare completamente MCP

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

​

Come corrispondono le voci serverName

• 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 corrispondono le voci serverCommand

• I comandi corrispondono esattamente. Ogni argomento, in ordine. ["npx", "-y", "server"] non corrisponde a ["npx", "server"] o ["npx", "-y", "server", "--flag"].
• Il blocco env non viene confrontato. ["node", "server.js"] corrisponde a un server che esegue quel comando con qualsiasi valore env. Alcune variabili d’ambiente cambiano ciò che node carica all’avvio. Per impostare tu stesso i valori env, definisci il server in managed-mcp.json.

​

Come corrispondono le voci serverUrl

• Nome host scritto per intero: solo la porta predefinita, 443 per https e 80 per http
• Nome host contenente un *: ogni porta

• https://staging.example.com/*: blocca i server https su quell’host solo sulla porta 443, quindi non blocca un server su https://staging.example.com:8443/api
• https://staging.example.com:*/*: blocca i server https su quell’host su ogni porta
• *://staging.example.com:*/*: blocca quell’host con qualsiasi schema e su qualsiasi porta

​

Variabili d’ambiente nelle voci serverCommand e serverUrl

• Il valore configurato del server: si espande dall’ambiente del processo live, come il resto di .mcp.json
• Una voce della policy: si espande da un ambiente bloccato, quindi una variabile impostata da un file di impostazioni di progetto o utente non può cambiare cosa significa una voce di allowlist

​

Come viene valutato un server

1. Merge degli elenchi. Le voci di allowlist e denylist di ogni ambito di impostazioni si combinano in un’unica allowlist e un’unica denylist. Quando allowManagedMcpServersOnly è true, viene mantenuta solo l’allowlist gestita; per la denylist il merge avviene sempre da ogni ambito. Quando è presente più di una fonte gestita, Le chiavi lette da ogni fonte di amministrazione indica quali di esse forniscono gli elenchi dell’ambito gestito.
2. Controlla la denylist. Un server che corrisponde a qualsiasi voce della denylist, per URL, comando o nome, viene bloccato. Nulla ha la precedenza su una corrispondenza della denylist.
3. Controlla l’allowlist. Alcuni server saltano questo controllo. Se allowedMcpServers non è impostato da nessuna parte, ogni server che ha superato la denylist si carica. Se è impostato, ciò a cui il server deve corrispondere dipende dal suo tipo, mostrato nella tabella di seguito.

​

I server che saltano il controllo dell’allowlist

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

​

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