SpyBara
Go Premium

managed-mcp.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 227 additions and 100 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Kontrollieren Sie den MCP-Serverzugriff für Ihre Organisation

Beschränken Sie, welche MCP-Server Benutzer hinzufügen oder verbinden können, oder stellen Sie Server für jeden Benutzer bereit, mit verwalteten Konfigurationsdateien, verwalteten Einstellungen, Zulassungslisten und Ablehnungslisten.

Standardmäßig kann jeder, der Claude Code ausführt, jeden beliebigen MCP-Server verbinden, den er wählt. Anthropic überprüft Konnektoren anhand seiner Auflistungskriterien, bevor sie zum Anthropic-Verzeichnis hinzugefügt werden, führt aber keine Sicherheitsprüfung durch und verwaltet keinen MCP-Server. Als Administrator können Sie einschränken, welche Server in Ihrer Organisation ausgeführt werden, von der Bereitstellung eines festen genehmigten Satzes bis zur vollständigen Deaktivierung von MCP, und Sie können Server für jeden Benutzer bereitstellen.

Diese Einschränkungen gelten für die Server, die Claude Code selbst lädt, einschließlich der Konnektoren, die es von claude.ai abruft. Konnektoren, die die Desktop-App an ihre lokalen und SSH-Sitzungen liefert, kommen prozessinternal an und werden stattdessen von Ihren claude.ai-Organisationseinstellungen aus gesteuert; Wie Konnektoren Claude Code erreichen zeigt, welche Kontrollen für Konnektoren in jeder Art von Sitzung gelten, einschließlich Cloud-Sitzungen.

Diese Seite behandelt, wie Sie:

Wählen Sie ein Muster

Claude Code unterstützt eine Reihe von Einschränkungsstufen. Jedes Muster verwendet einen oder mehrere der folgenden Mechanismen: managed-mcp.json zum Bereitstellen eines festen Satzes, die verwaltete Einstellung managedMcpServers zum Bereitstellen von Servern neben den von Benutzern hinzugefügten und allowedMcpServers/deniedMcpServers zum Filtern dessen, was Benutzer konfigurieren.

Muster Funktion Konfigurieren
MCP deaktivieren Keine Server werden geladen, außer In-Process-Servern, die die App registriert, die die Sitzung gestartet hat und alle, die Sie über managedMcpServers bereitstellen managed-mcp.json mit einer leeren Serverzuordnung
Feste Bereitstellung Jeder Benutzer erhält die gleichen Server und kann keine anderen hinzufügen managed-mcp.json mit den gewünschten Servern
Bereitgestellte Server Jeder Benutzer erhält die Remote-Server, die Sie auflisten, und behält seine eigenen managedMcpServers in verwalteten Einstellungen
Genehmigter Katalog Veröffentlichen Sie eine Liste genehmigter Server; Benutzer fügen die gewünschten hinzu, alles andere wird blockiert allowedMcpServers + allowManagedMcpServersOnly: true
Nur Plugin-Server Benutzer können keine Server über ~/.claude.json oder .mcp.json hinzufügen; Plugin-Server werden weiterhin geladen strictPluginOnlyCustomization mit mcp in der Liste
Soft-Allowlist Erzwingen Sie eine Allowlist, die Benutzer in ihren eigenen Einstellungen erweitern können allowedMcpServers ohne allowManagedMcpServersOnly
Nur Denylist Blockieren Sie bekannt schlechte Server, erlauben Sie alles andere deniedMcpServers
Keine Einschränkungen Benutzer fügen alles hinzu Stellen Sie keine verwaltete MCP-Konfiguration bereit

Exklusive Kontrolle mit managed-mcp.json

Wenn Sie eine managed-mcp.json-Datei bereitstellen, lädt Claude Code nur die Server, die diese Datei definiert, die Server, die Sie über managedMcpServers bereitstellen, sowie alle In-Process-Server, die die Anwendung registriert, die die Sitzung gestartet hat, wie beispielsweise der eigene Server der VS Code-Erweiterung oder die Konnektoren, die die Desktop-Anwendung bereitstellt. Benutzer können keine anderen MCP-Server hinzufügen, ändern oder verwenden, einschließlich Plugin-bereitgestellter Server und Server, die mit dem --mcp-config-CLI-Flag übergeben werden. Die Datei unterdrückt auch die claude.ai-Konnektoren, die Claude Code selbst abruft, es sei denn, Sie erlauben sie neben dem verwalteten Satz.

managed-mcp.json bereitstellen

managed-mcp.json ist eine eigenständige Datei und kann daher nicht über servergesteuerte Einstellungen bereitgestellt werden. Um Server stattdessen über verwaltete Einstellungen bereitzustellen, ohne exklusive Kontrolle, verwenden Sie managedMcpServers.

Jeder Prozess, der in einen Systempfad mit Administratorrechten schreiben kann, kann die Datei bereitstellen. Über eine Flotte hinweg geschieht dies normalerweise über Geräteverwaltungstools wie Jamf oder ein Konfigurationsprofil auf macOS, Gruppenrichtlinie oder Intune unter Windows oder Ihre Flottenverwaltung Ihrer Wahl unter Linux. Claude Code sucht die Datei unter einem dieser Pfade:

Plattform Pfad
macOS /Library/Application Support/ClaudeCode/managed-mcp.json
Linux und WSL /etc/claude-code/managed-mcp.json
Windows C:\Program Files\ClaudeCode\managed-mcp.json

Die Datei verwendet das gleiche Format wie eine Projekt-.mcp.json-Datei:

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

Mit benutzerspezifischen Anmeldedaten authentifizieren

Jeder Benutzer auf dem Computer kann diese Datei lesen, daher speichern Sie keine API-Schlüssel oder andere Anmeldedaten in env-Blöcken. Übergeben Sie stattdessen benutzerspezifische Anmeldedaten mit einer dieser Optionen:

Server, die mit `--mcp-config` oder `--strict-mcp-config` übergeben werden

Wenn eine Sitzung Server über --mcp-config erhält, während managed-mcp.json bereitgestellt wird, unterscheidet sich das, was der Benutzer sieht, zwischen einer Workstation und einer Cloud-Sitzung:

  • Auf einer Workstation beendet Claude Code beim Start mit You cannot dynamically configure MCP servers when an enterprise MCP config is present.
  • In Cloud-Sitzungen auf einem Host, auf dem die Datei bereitgestellt wird, wie beispielsweise einem selbstgehosteten Runner, startet Claude Code nur mit den verwalteten Servern und überspringt die claude.ai-Konnektoren und andere Server, die der Cloud-Host über --mcp-config bereitstellt. Nichts in der Sitzung teilt dem Benutzer mit, welche Server ausgelassen wurden. Claude Code benennt sie in einer Warnung auf stderr, die ein selbstgehosteter Runner auf der debug-Protokollebene aufzeichnet.

Wenn ein Benutzer --strict-mcp-config übergibt, beendet Claude Code beim Start sowohl auf einer Workstation als auch in einer Cloud-Sitzung, da dieses Flag auffordert, den verwalteten Satz zu ersetzen.

Wie Zulassungslisten und Ablehnungslisten auf den verwalteten Satz angewendet werden

Die Ablehnungsliste kann die Server in managed-mcp.json weiter filtern:

  • deniedMcpServers gilt auch für verwaltete Server, daher wird ein verwalteter Server, der einem Eintrag entspricht, nicht geladen.
  • Die eigene deniedMcpServers eines Benutzers wird aus seinen Einstellungen zusammengeführt, daher können Benutzer einen verwalteten Server für sich selbst blockieren.

allowedMcpServers gilt nicht für die Server in managed-mcp.json, mit einer Ausnahme: Claude Code überprüft immer noch einen Server, dessen Definition ${VAR}-Erweiterung verwendet, gegen die Zulassungsliste, da die effektive Konfiguration dieses Servers aus der Umgebung jedes Benutzers stammt und nicht nur aus der Datei. Vor v2.1.259 musste jeder verwaltete Server die Zulassungsliste passieren, wenn eine gesetzt war. Siehe Wie ein Server evaluiert wird für die Felder, die die ${VAR}-Überprüfung auslösen, und die vollständige Reihenfolge der Überprüfungen.

Wenn Sie allowedMcpServers verwendet haben, um zu verhindern, dass einige Ihrer eigenen managed-mcp.json-Server geladen werden, beginnen diese Server beim ersten Start jedes Benutzers von v2.1.259 oder später zu laden, es sei denn, sie verwenden ${VAR}-Erweiterung, ohne Aufforderung oder Benachrichtigung: nur deniedMcpServers wird weiterhin von diesen Servern subtrahiert. Fügen Sie Ablehnungslisteneinträge für sie hinzu, oder stellen Sie eine separate managed-mcp.json pro Gruppe bereit, bevor Ihre Benutzer ein Upgrade durchführen.

Konfiguration validieren

Um zu bestätigen, dass die Datei wirksam ist, führen Sie zwei Überprüfungen auf einem verwalteten Computer durch:

  1. claude mcp list zeigt nur die Server in managed-mcp.json plus alle, die Sie über managedMcpServers bereitstellen. Wenn die eigenen Server eines Benutzers immer noch angezeigt werden, wird die Datei nicht gelesen; überprüfen Sie den Pfad und die Berechtigungen.
  2. claude mcp add --transport http test https://example.com/mcp schlägt mit Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers fehl. Die URL muss kein echter Server sein, da die Richtlinienüberprüfung den Befehl ablehnt, bevor etwas kontaktiert wird.

MCP vollständig deaktivieren

Stellen Sie eine managed-mcp.json mit einer leeren Serverzuordnung bereit, um jeden MCP-Server außer In-Process-Servern, die die Anwendung registriert, die die Sitzung gestartet hat, zu blockieren:

{
  "mcpServers": {}
}

claude mcp add schlägt mit dem oben genannten Enterprise-Richtlinienfehler fehl. Server, die Benutzer zuvor konfiguriert hatten, werden beim nächsten Start einer Sitzung nicht mehr geladen, ohne Warnung, dass die Richtlinie der Grund ist. Server, die Sie über managedMcpServers bereitstellen, werden weiterhin unter einer leeren Zuordnung geladen, daher lassen Sie diesen Schlüssel auch ungesetzt, um MCP vollständig zu deaktivieren.

claude.ai-Konnektoren neben dem verwalteten Satz erlauben

Standardmäßig unterdrückt die Bereitstellung von managed-mcp.json die claude.ai-Konnektoren, die Claude Code selbst abruft, einschließlich Konnektoren, die ein Administrator für die Organisation in der claude.ai-Verwaltungskonsole konfiguriert hat. Um diese Konnektoren neben den Servern in managed-mcp.json zu laden, setzen Sie "allowAllClaudeAiMcps": true in einer verwalteten Einstellungsquelle.

Mit der aktivierten Einstellung lädt Claude Code die gleichen claude.ai-Konnektoren, die es laden würde, wenn managed-mcp.json nicht bereitgestellt würde. Zulassungslisten und Ablehnungslisten gelten weiterhin für diese Konnektoren, daher können Sie bestimmte mit deniedMcpServers blockieren. Die Einstellung betrifft nur die claude.ai-Konnektoren, die Claude Code selbst abruft; Plugin-bereitgestellte Server bleiben unterdrückt.

Cloud-Sitzungen und die lokalen und SSH-Sitzungen der Desktop-Anwendung erhalten Konnektoren auf andere Weise, wie in Wie Konnektoren Claude Code erreichen beschrieben. Eine managed-mcp.json auf dem Host, der eine Cloud-Sitzung ausführt, wie beispielsweise ein selbstgehosteter Runner-Host, unterdrückt die Konnektoren dieser Sitzung, unabhängig davon, ob Sie allowAllClaudeAiMcps setzen oder nicht. Keine managed-mcp.json erreicht die Konnektoren, die die Desktop-Anwendung an ihre lokalen und SSH-Sitzungen bereitstellt.

Claude Code liest allowAllClaudeAiMcps nur aus von Administratoren kontrollierten Richtlinienebenen: servergesteuerte Einstellungen, ein von MDM bereitgestellter plist- oder HKLM-Registrierungsschlüssel oder eine System-managed-settings.json-Datei. Das Platzieren in Benutzer- oder Projekteinstellungen hat keine Auswirkung, daher können Benutzer Konnektoren, die exklusive Kontrolle unterdrückt hat, nicht erneut aktivieren.

Server über verwaltete Einstellungen bereitstellen

Um jedem Benutzer einen Satz von Remote-MCP-Servern zur Verfügung zu stellen, ohne die ausschließliche Kontrolle über MCP zu übernehmen, listen Sie diese unter managedMcpServers in einer verwalteten Einstellungsquelle auf: servergesteuerte Einstellungen, eine Claude-Apps-Gateway-Richtlinie, ein MDM-Profil oder eine Registrierungsrichtlinie oder managed-settings.json. Benutzer behalten die Server, die sie selbst hinzufügen, und erhalten Ihre zusätzlich. Erfordert Claude Code v2.1.259 oder später. Frühere Clients ignorieren den Schlüssel.

Der Wert ist ein Objekt, das nach Servername verschlüsselt ist. Jeder Eintrag hat die gleiche Form wie ein HTTP- oder SSE-Server in einer Projekt-.mcp.json-Datei, einschließlich der optionalen headers- und oauth-Member, die in Authentifizierung mit Remote-MCP-Servern beschrieben sind. Dieses Beispiel stellt einen Suchserver bereit, bei dem sich jeder Benutzer mit OAuth anmeldet, und einen Datensatzserver, der einen Header sendet, den Ihre Organisation ausgibt:

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

Jeder, der die verwalteten Einstellungen auf einem Computer lesen kann, einschließlich des Benutzers, kann einen Header-Wert lesen, den Sie hier festlegen. Verwenden Sie eine Anmeldeinformation, die für diese gesamte Zielgruppe ausgestellt wurde, oder lassen Sie headers weg und lassen Sie jeden Benutzer sich mit OAuth anmelden.

Was ein Eintrag enthalten kann

Claude Code lädt einen Eintrag nur, wenn er alle folgenden Überprüfungen besteht. Es verwirft einen Eintrag, der eine nicht besteht, zeichnet einen Hinweis auf, den Sie mit /status lesen können, und lädt trotzdem die anderen Einträge:

  • type ist http oder sse. Wie in .mcp.json wird streamable-http als Alias für http akzeptiert.
  • url ist eine https://-URL. Claude Code lehnt eine einfache http://-URL ab, einschließlich einer, die auf localhost verweist.
  • Der Eintrag hat keinen command-, args-, env- oder headersHelper-Member, daher nennt ein verwaltetes Einstellungsdokument niemals ein Programm, das auf dem Computer eines Benutzers ausgeführt werden soll.
  • Kein Wert enthält einen ${VAR}-Verweis. Claude Code erweitert Umgebungsvariablen in diesen Einträgen nicht, daher schreiben Sie Literalwerte.
  • Der Servername enthält nur Buchstaben, Zahlen, Bindestriche und Unterstriche, und kein Schlüssel oder Wert enthält Steuerzeichen oder unsichtbare Formatierungszeichen.

Claude Desktop hat eine verwaltete Einstellung mit dem gleichen Namen, deren Wert ein Array einer anderen Eintragform ist, daher kopieren Sie nicht eine in die andere. Claude Code akzeptiert die Array-Form nicht und zeichnet stattdessen einen Hinweis auf, anstatt sie zu laden.

Ein Claude-Apps-Gateway führt die gleichen Überprüfungen beim Starten durch; siehe MCP-Server in einer Richtlinie.

Wie bereitgestellte Server geladen werden

Diese Regeln entscheiden, was geladen wird, wenn ein bereitgestellter Server mit einer anderen Serverdefinition oder mit einer anderen Einstellung auf dieser Seite überlappt:

  • Ein bereitgestellter Server hat Vorrang vor einem Server mit dem gleichen Namen im lokalen, Projekt- oder Benutzerbereich und vor einem Plugin-Server oder claude.ai-Connector, der auf die gleiche URL verweist.
  • Wenn Sie auch managed-mcp.json bereitstellen, lädt Claude Code seine Server und die bereitgestellten Server zusammen, und der Eintrag der Datei hat Vorrang, wenn beide einen Namen definieren.
  • Bereitgestellte Server werden weiterhin geladen, wenn strictPluginOnlyCustomization die mcp-Oberfläche sperrt.
  • deniedMcpServers gilt für bereitgestellte Server, einschließlich Einträge aus den eigenen Einstellungen eines Benutzers, daher kann ein Benutzer einen für sich selbst blockieren. Bereitgestellte Server benötigen keinen allowedMcpServers-Eintrag.

Wenn Sie auch managed-mcp.json nicht bereitgestellt haben, behalten die Pro-Lauf-Flags ihre Bedeutung:

  • Ein Server, den ein Benutzer mit --mcp-config unter dem gleichen Namen übergibt, ersetzt den bereitgestellten für diesen Lauf und wird gegen allowedMcpServers überprüft.
  • --strict-mcp-config lässt bereitgestellte Server zusammen mit jedem anderen konfigurierten Server weg.

Mit bereitgestelltem managed-mcp.json verhalten sich beide Flags wie Ausschließliche Kontrolle mit managed-mcp.json beschreibt.

Was Benutzer sehen und ändern können

Benutzer können einen bereitgestellten Server nicht bearbeiten oder entfernen:

  • claude mcp remove meldet, dass der Server von der Organisation bereitgestellt wird.
  • Wenn Sie auch managed-mcp.json nicht bereitgestellt haben, wird ein Eintrag, den ein Benutzer unter dem gleichen Namen hinzufügt, gespeichert, aber nicht verwendet, während Ihrer vorhanden ist.
  • Benutzer können einen bereitgestellten Server für sich selbst in /mcp immer noch ausschalten, das bereitgestellte Server unter Managed MCPs auflistet.

claude mcp get und /mcp zeigen die URL eines bereitgestellten Servers nur als seinen Host an, zum Beispiel https://mcp.example.com/…, und claude mcp get zeigt seine Header-Namen ohne ihre Werte an.

Wo `managedMcpServers` gilt

Claude Code liest managedMcpServers aus der verwalteten Quelle, die es unter Wie Claude Code verwaltete Quellen kombiniert auswählt. Wenn diese Quelle managedSourcesBehavior auf "merge" setzt, stellt Claude Code stattdessen die Server von jeder Admin-Quelle bereit, und wenn zwei Quellen den gleichen Namen definieren, gilt der Eintrag der höher eingestuften Quelle vollständig. Es liest den Schlüssel niemals aus der benutzergeschriebenen HKCU-Registrierung, aus übergeordneten Einstellungen, die ein Embedding-Host bereitstellt, oder aus Benutzer-, Projekt- oder lokalen Einstellungsdateien, wo es den Schlüssel mit einer Warnung verwirft.

Claude Code liest den Schlüssel nicht in der Code-Registerkarte der Claude Desktop-App bei einer Drittanbieter-Bereitstellung oder in den Cowork-Sitzungen der App, da Claude Desktop die MCP-Server dieser Sitzungen selbst bereitstellt und sperrt. /status und claude doctor sagen so, wenn Ihre verwalteten Einstellungen den Schlüssel dort tragen.

Wenn bereitgestellte Server verbunden werden

Wenn managedMcpServers über servergesteuerte Einstellungen ankommt, folgt sein Timing Abruf- und Caching-Verhalten:

  • Auf einem Computer mit zwischengespeicherten Einstellungen hält Claude Code die zwischengespeicherte Kopie dieses Schlüssels zurück, bis der Server die Einstellungen für die Sitzung bestätigt, und wartet auf diese Bestätigung, bevor MCP-Server geladen werden. Wenn die Bestätigung fehlschlägt, wird die Sitzung ohne die bereitgestellten Server fortgesetzt und /status sagt, dass sie zurückgehalten werden.
  • Beim ersten Start eines Computers, wenn noch nichts zwischengespeichert ist, verbindet eine interaktive Sitzung, die vor dem Eintreffen der Einstellungen startet, die bereitgestellten Server, sobald sie eintreffen, und ein claude -p-Lauf, der bereits gestartet hat, kann ohne sie beendet werden.

Mit Gateway-Anmeldung lädt Claude Code die Richtlinie vor dem Start der Sitzung, daher verzögert oder überspringt keiner der Fälle die bereitgestellten Server.

Interaktive Sitzungen, die bereits ausgeführt werden, wenden Ihre Änderungen am Schlüssel an:

  • Server hinzufügen: Claude Code verbindet ihn, wenn die aktualisierten Einstellungen eintreffen, ohne einen Neustart.
  • Eintrag eines Servers ändern: Diese Sitzungen verbinden sich mit der neuen Definition erneut.
  • Server entfernen: Eine laufende interaktive Sitzung trennt ihn, sobald sie die geänderten Einstellungen liest. Ein nicht-interaktiver (-p)-Lauf behält ihn bis zum Ende.

Richtlinienbasierte Kontrolle mit Zulassungs- und Sperrlisten

Zulassungs- und Sperrlisten filtern, welche konfigurierten Server geladen werden dürfen. Sie sind keine Registrierung: Ein Server muss immer noch von einem Benutzer, einem Plugin oder Ihrer Organisation hinzugefügt werden, bevor eine der beiden Listen auf ihn angewendet wird.

Server, die Ihre Organisation über managedMcpServers bereitstellt, werden ohne einen Zulassungslisten-Eintrag geladen, und Wie ein Server bewertet wird behandelt managed-mcp.json-Server. Die Sperrliste gilt für jeden Server, unabhängig davon, woher er kommt, mit Ausnahme von In-Process-type: "sdk"-Einträgen.

Um Server an Benutzer bereitzustellen, verwenden Sie managed-mcp.json oder managedMcpServers. Beide Listen filtern auch Server, die mit dem --mcp-config CLI-Flag übergeben werden, mit Ausnahme von In-Process-type: "sdk"-Einträgen; --strict-mcp-config begrenzt, welche Konfigurationsdateien geladen werden, und umgeht keine der beiden Listen.

Um die Zulassungsliste verbindlich zu machen, setzen Sie allowedMcpServers und allowManagedMcpServersOnly: true zusammen in einer verwalteten Einstellungsquelle, z. B. servergesteuerte Einstellungen oder eine bereitgestellte managed-settings.json-Datei. Beschränken Sie die Zulassungsliste auf verwaltete Einstellungen nur zeigt die Konfiguration. Ohne allowManagedMcpServersOnly werden Zulassungslisten aus jedem Einstellungsbereich zusammengeführt, einschließlich der eigenen ~/.claude/settings.json eines Benutzers, sodass ein Benutzer das, was Ihre Zulassungsliste erlaubt, erweitern kann. Sperrlisten werden unabhängig davon aus jedem Bereich zusammengeführt.

Server nach URL, Befehl oder Name abgleichen

allowedMcpServers und deniedMcpServers sind Listen von Einträgen. Jeder Eintrag ist ein Objekt mit einem einzelnen Schlüssel, der Server nach ihrer URL, ihrem Befehl oder ihrem Namen identifiziert:

Schlüssel Gleicht ab Verwenden für
serverUrl Eine Remote-Server-URL, exakt oder mit *-Platzhaltern HTTP- und SSE-Server
serverCommand Der genaue Befehl und die Argumente, die einen Stdio-Server starten Stdio-Server
serverName Die vom Benutzer zugewiesene Bezeichnung. Nur exakte Übereinstimmung; Platzhalter werden nicht erweitert Beide Typen, aber siehe die Warnung unten

Das Belassen von allowedMcpServers ungesetzt unterscheidet sich vom Setzen auf ein leeres Array:

Einstellung Ungesetzt (Standard) Leeres Array [] Gefüllt
allowedMcpServers Alle Server erlaubt Keine Server erlaubt, außer den eigenen der Organisation Nur übereinstimmende Server erlaubt, außer den eigenen der Organisation
deniedMcpServers Keine Server blockiert Keine Server blockiert Übereinstimmende Server blockiert

Siehe Ungültige Einträge in verwalteten Einstellungen für das, was passiert, wenn ein Eintrag die Schemavalidierung nicht besteht.

Die serverName-Validierung unterscheidet sich zwischen den beiden Listen:

  • In deniedMcpServers akzeptiert serverName jede nicht leere Zeichenkette, sodass Sie claude.ai-Konnektoren nach ihrem Anzeigenamen blockieren können. Zum Beispiel blockiert { "serverName": "claude.ai Slack" } den Slack-Konnektor. Bevorzugen Sie einen serverUrl-Eintrag, wenn die Sperre robust gegen Umbenennungen sein muss, oder wenn ein Konnektor-Name kollidiert und ein (N)-Suffix erhält.
  • In allowedMcpServers ist serverName auf Buchstaben, Zahlen, Bindestriche und Unterstriche beschränkt. Verwenden Sie serverUrl, um einen claude.ai-Konnektor auf die Zulassungsliste zu setzen, den Claude Code selbst abruft; für Konnektoren, die ein Cloud-Host an selbstgehostete Sitzungen liefert, verwenden Sie stattdessen die unter Konnektor-Datenverkehr verlässt Ihr Netzwerk aufgelisteten Einträge.

Um alle claude.ai-Konnektoren auszuschalten, die Claude Code selbst abruft, siehe disableClaudeAiConnectors.

Wie ein Server bewertet wird

Vor dem Laden eines Servers, einschließlich eines aus managed-mcp.json, führt Claude Code die drei folgenden Überprüfungen in Reihenfolge durch. Es führt sie erneut durch, wenn ein Benutzer einen Server erneut verbindet oder einen deaktivierten in /mcp wieder aktiviert. In-Process-type: "sdk"-Server, die die App registriert, die die Sitzung gestartet hat, überspringen alle drei.

  1. Listen zusammenführen. Zulassungs- und Sperrlisten-Einträge aus jedem Einstellungsbereich werden in eine Zulassungsliste und eine Sperrliste kombiniert, wobei die Listen des verwalteten Bereichs von der verwalteten Quelle oder den Quellen stammen, die Claude Code anwendet. Wenn allowManagedMcpServersOnly true ist, wird nur die verwaltete Zulassungsliste beibehalten; die Sperrliste wird immer aus jedem Bereich zusammengeführt.

  2. Sperrliste überprüfen. Ein Server, der einem Sperrlisten-Eintrag entspricht, nach URL, Befehl oder Name, wird blockiert. Nichts überschreibt eine Sperrlisten-Übereinstimmung.

  3. Zulassungsliste überprüfen. Wenn allowedMcpServers nirgendwo gesetzt ist, wird jeder Server, der die Sperrliste bestanden hat, geladen. Wenn es gesetzt ist, hängt das, dem der Server entsprechen muss, von seinem Typ ab, wie in der folgenden Tabelle gezeigt.

    Die eigenen Server der Organisation überspringen diese Überprüfung: jeder managedMcpServers-Eintrag und jeder managed-mcp.json-Eintrag, dessen Werte keine ${VAR}-Erweiterung verwenden. Integrierte Server überspringen sie auch, z. B. Claude in Chrome, der ide-Server, mit dem Claude Code sich in einer laufenden VS Code- oder JetBrains-IDE verbindet, und Server, die die CLI selbst konfiguriert.

    Ein managed-mcp.json-Server, der ${VAR}-Erweiterung in seinem Befehl, seinen Argumenten, env, URL oder Headern verwendet, wird immer noch überprüft, ebenso wie jeder Server, den ein Benutzer, ein Plugin, --mcp-config oder claude.ai hinzufügt.

Servertyp Erlaubt, wenn es übereinstimmt
Remote (HTTP oder SSE) Ein serverUrl-Eintrag. Eine serverName-Übereinstimmung zählt nur, wenn die Zulassungsliste keine serverUrl-Einträge enthält
Stdio Ein serverCommand-Eintrag. Eine serverName-Übereinstimmung zählt nur, wenn die Zulassungsliste keine serverCommand-Einträge enthält

Drei Abgleichsregeln gelten innerhalb dieser Überprüfungen:

  • Befehle stimmen genau überein. Jedes Argument, in Reihenfolge. ["npx", "-y", "server"] stimmt nicht mit ["npx", "server"] oder ["npx", "-y", "server", "--flag"] überein.
  • serverCommand- und serverUrl-Werte werden vor dem Abgleich erweitert. Sowohl der Richtlinieneintrag als auch der konfigurierte Wert des Servers durchlaufen ${VAR}- und ${VAR:-default}-Erweiterung, sodass ein Eintrag, der als ["${HOME}/bin/server"] geschrieben ist, mit einer Serverkonfiguration übereinstimmt, die entweder die gleiche Referenz oder den erweiterten Pfad verwendet. Unter Windows verweisen Sie auf eine Umgebungsvariable, die dort gesetzt ist, z. B. ${USERPROFILE} statt ${HOME}. serverName-Werte stimmen wörtlich überein und werden nie erweitert. Die beiden Seiten lesen unterschiedliche Umgebungen; Wie Richtlinieneinträge erweitert werden behandelt, welche und wie sich Zulassungs- und Sperrlisten-Einträge unterscheiden.
  • URLs unterstützen *-Platzhalter überall im Muster, einschließlich des Schemas. Der Hostname-Abgleich ist nicht case-sensitiv und ignoriert einen nachgestellten FQDN-Punkt, sodass https://Mcp.Example.com/* mit https://mcp.example.com/api übereinstimmt. Pfade bleiben case-sensitiv.
Muster Erlaubt
https://mcp.example.com/* Alle Pfade auf einer bestimmten Domain
https://mcp.example.com Auch alle Pfade auf dieser Domain. Ein Muster ohne Pfad stimmt mit jedem Pfad überein
https://*.example.com/* Jede Subdomain von example.com
http://localhost:*/* Jeden Port auf localhost
*://mcp.example.com/* Jedes Schema zu einer bestimmten Domain

Wie Richtlinieneinträge erweitert werden

Der konfigurierte Wert des Servers wird aus der Live-Prozessumgebung erweitert, wie der Rest von .mcp.json. Ein Richtlinieneintrag wird stattdessen aus einer angehefteten Umgebung erweitert, sodass eine Variable, die von einer Projekt- oder Benutzereinstellungsdatei gesetzt wird, nicht ändern kann, was ein Zulassungslisten-Eintrag bedeutet. Da ein Richtlinieneintrag immer noch von der Umgebungsvariable der startenden Shell abhängt, verwenden Sie wörtliche URLs und Befehle für Einträge, auf die Sie sich für die Durchsetzung verlassen.

Eintragsliste Erweitert aus Erweiterung, die das Schema, den Host oder den Pfadbereich eines URL-Eintrags ändern würde
allowedMcpServers Die Umgebung, mit der Claude Code gestartet wurde, plus env-Werte aus verwalteten Einstellungen Claude Code ignoriert den Eintrag
deniedMcpServers Das gleiche, und eine Variable ohne Startwert und ohne :-default wird aus Einstellungsdateien außerhalb des Repositorys gefüllt, z. B. Benutzer- oder verwaltete Einstellungen, die nur jemals das erweitern, dem der Eintrag entspricht Der Eintrag stimmt immer noch überein

Erfordert Claude Code v2.1.219 oder später.

Beispielkonfiguration

Die folgende Konfiguration richtet eine strikte Zulassungsliste mit einer Sperrliste ein. Die hervorgehobenen Zeilen ändern, wie der Rest der Liste bewertet wird, und die Callouts nach dem Block erklären jeweils eine:

{
  "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/*" }
  ]
}
  • Zeile 3: der erste serverUrl-Eintrag. Sobald einer existiert, muss jeder Remote-Server einem URL-Muster entsprechen, sodass ein Benutzer keinen nicht aufgelisteten Remote-Server durch Vergabe eines erlaubten Namens erhalten kann.
  • Zeile 5: der erste serverCommand-Eintrag. Gleicher Effekt für Stdio-Server, sodass jeder lokale Server genau einem aufgelisteten Befehl entsprechen muss.
  • Zeile 11: ein serverName-Eintrag in der Sperrliste. Sperrlisten-Einträge gelten immer, sodass jeder Server namens dangerous-server unabhängig von seiner URL oder seinem Befehl blockiert wird.

Ein serverName-Eintrag in dieser Zulassungsliste würde nie etwas abgleichen, da beide Transporttypen bereits strengere Einträge haben.

Die Akkordeons unten gehen durch, wie ein Server gegen andere Zulassungs- und Sperrlisten-Kombinationen bewertet wird.

Nur URL-Zulassungsliste 
{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.example.com/*" },
{ "serverUrl": "https://*.internal.example.com/*" }
]
}
Server Ergebnis
HTTP-Server unter https://mcp.example.com/api Erlaubt: stimmt mit URL-Muster überein
HTTP-Server unter https://api.internal.example.com/mcp Erlaubt: stimmt mit Wildcard-Subdomain überein
HTTP-Server unter https://external.example.com/mcp Blockiert: stimmt mit keinem URL-Muster überein
Stdio-Server mit beliebigem Befehl Blockiert: keine Name- oder Befehlseinträge zum Abgleichen
Nur Befehl-Zulassungsliste 
{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}
Server Ergebnis
Stdio-Server mit ["npx", "-y", "approved-package"] Erlaubt: stimmt mit Befehl überein
Stdio-Server mit ["node", "server.js"] Blockiert: stimmt nicht mit Befehl überein
HTTP-Server namens my-api Blockiert: keine Name-Einträge zum Abgleichen
Gemischte Name- und Befehl-Zulassungsliste 
{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}
Server Ergebnis
Stdio-Server namens local-tool mit ["npx", "-y", "approved-package"] Erlaubt: stimmt mit Befehl überein
Stdio-Server namens local-tool mit ["node", "server.js"] Blockiert: Befehlseinträge existieren, aber stimmt nicht überein
Stdio-Server namens github mit ["node", "server.js"] Blockiert: Stdio-Server müssen Befehlen entsprechen, wenn Befehlseinträge existieren
HTTP-Server namens github Erlaubt: stimmt mit Name überein
HTTP-Server namens other-api Blockiert: Name stimmt nicht überein
Nur Name-Zulassungsliste 
{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}
Server Ergebnis
Stdio-Server namens github mit beliebigem Befehl Erlaubt: keine Befehlsbeschränkungen
Stdio-Server namens internal-tool mit beliebigem Befehl Erlaubt: keine Befehlsbeschränkungen
HTTP-Server namens github Erlaubt: stimmt mit Name überein
Beliebiger Server namens other Blockiert: Name stimmt nicht überein
Zulassungsliste mit Sperrlisten-Überschreibung 
{
"allowedMcpServers": [
{ "serverUrl": "https://*.example.com/*" }
],
"deniedMcpServers": [
{ "serverUrl": "https://staging.example.com/*" }
]
}
Server Ergebnis
HTTP-Server unter https://mcp.example.com/api Erlaubt: stimmt mit Zulassungslisten-URL-Muster überein, keine Sperrlisten-Übereinstimmung
HTTP-Server unter https://staging.example.com/api Blockiert: stimmt mit beiden überein, aber die Sperrliste hat Vorrang
HTTP-Server unter https://other.com/mcp Blockiert: stimmt nicht mit der Zulassungsliste überein

Beschränken Sie die Zulassungsliste auf verwaltete Einstellungen nur

Um die verwaltete Zulassungsliste zur einzigen anzuwenden, setzen Sie allowManagedMcpServersOnly in der verwalteten Einstellungsdatei:

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

Wenn allowManagedMcpServersOnly true ist, werden Zulassungslisten aus Benutzer-, Projekt- und lokalen Einstellungen ignoriert. Die Sperrliste wird immer noch aus jedem Einstellungsbereich zusammengeführt, sodass Benutzer Server immer für sich selbst blockieren können.

Wie Einschränkungen für Benutzer angezeigt werden

Informationen dazu, was Benutzer beim Start sehen, wenn managed-mcp.json bereitgestellt wird und die Sitzung auch --mcp-config-Server hat, finden Sie unter Exklusive Kontrolle mit managed-mcp.json. Verwenden Sie diese Tabelle, um die anderen Berichte zu erkennen und Benutzern mitzuteilen, was sie erwarten können, bevor Sie eine Änderung einführen:

Einschränkung Was der Benutzer sieht
managed-mcp.json ist vorhanden und der Benutzer führt claude mcp add aus Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers
Der Server befindet sich auf einer Ablehnungsliste und der Benutzer führt claude mcp add aus Cannot add MCP server "<name>": server is explicitly blocked by enterprise policy
Der Server befindet sich nicht auf der Zulassungsliste und der Benutzer führt claude mcp add aus Cannot add MCP server "<name>": not allowed by enterprise policy
Der Benutzer führt claude mcp remove auf einem Server aus managedMcpServers aus MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.
Ein zuvor konfigurierter Server wird jetzt durch eine Richtlinie blockiert Der Server verschwindet stillschweigend aus /mcp und claude mcp list ohne Warnung
Ein Server wird blockiert, während eine Sitzung ausgeführt wird, und der Benutzer wählt Reconnect oder aktiviert ihn in /mcp erneut MCP server <name> is blocked by enterprise managed policy

Wenn ein Server stillschweigend verschwindet, erhält der Benutzer kein Signal dafür, dass die Richtlinie der Grund ist. Teilen Sie betroffenen Benutzern daher mit, welche Server blockiert sind, wenn Sie eine neue Einschränkung einführen.

Überwachen Sie die MCP-Nutzung

Wenn OpenTelemetry-Export konfiguriert ist, kann Claude Code aufzeichnen, welche MCP-Server und Tools Benutzer aufrufen. Setzen Sie OTEL_LOG_TOOL_DETAILS=1, um MCP-Server- und Tool-Namen in Tool-Events einzubeziehen, und aggregieren Sie sie dann in Ihrem Collector, um zu sehen, welche Server Ihre Benutzer tatsächlich verbinden. Siehe Überwachung, um den Exporter einzurichten und das vollständige Event-Schema zu erhalten.

Konfigurationszusammenfassung

Jede Datei und Einstellung, die diese Seite behandelt, was sie kontrolliert und wie man sie bereitstellt:

Oberfläche Was es kontrolliert Wo es sich befindet Wie man es bereitstellt
managed-mcp.json Fester Serversatz, exklusive Kontrolle Systempfad: /Library/Application Support/ClaudeCode/, /etc/claude-code/ oder C:\Program Files\ClaudeCode\ MDM, GPO, Fleet-Verwaltung oder jeder Prozess mit Administratorrechten. Kann nicht über serververwaltete Einstellungen gesetzt werden
managedMcpServers Remote-Server, die jedem Benutzer neben seinen eigenen bereitgestellt werden Nur verwaltete Einstellungsquellen; die Einstellung hat keine Auswirkung anderswo Eine verwaltete Einstellungsquelle: serververwaltete Einstellungen, eine Gateway-Richtlinie, managed-settings.json, MDM-Profil oder HKLM-Registrierung
allowedMcpServers Zulassungsliste zulässiger Server Jede Einstellungsbereich; Claude Code führt die Listen aus jedem Bereich zusammen, es sei denn, allowManagedMcpServersOnly ist gesetzt, und nimmt die verwaltete Bereichsliste aus der einen verwalteten Quelle, die es auswählt oder zusammensetzt Zur Durchsetzung eine verwaltete Einstellungsquelle: serververwaltete Einstellungen, managed-settings.json, MDM-Profil oder Registrierung
deniedMcpServers Sperrliste blockierter Server Jede Einstellungsbereich; Claude Code führt die Listen aus jedem Bereich zusammen und über verwaltete Quellen hinweg, wie wie Claude Code verwaltete Quellen kombiniert beschreibt Gleich wie allowedMcpServers
allowManagedMcpServersOnly Sperrt die Zulassungsliste auf verwaltete Quellen nur Nur verwaltete Einstellungsquellen; die Einstellung hat keine Auswirkung anderswo Gleich wie allowedMcpServers
allowAllClaudeAiMcps Lädt die claude.ai-Konnektoren, die Claude Code selbst abruft, neben managed-mcp.json. Eine managed-mcp.json auf dem Host, der eine Cloud-Sitzung ausführt, unterdrückt immer noch die Konnektoren dieser Sitzung Nur verwaltete Einstellungsquellen; die Einstellung hat keine Auswirkung anderswo Gleich wie allowedMcpServers