Wie sich der Vorrang von MCP-Konfigurationen in Terminals und IDEs ändert

Konfigurationskonflikte bei MCP sind kein MCP-Problem. Sie sind ein Client-Problem, und diese Unterscheidung erspart viel erfolgloses Debugging.

Das Protokoll erklärt einem Client, wie er mit einem Server spricht, nachdem dieser gestartet wurde. Es sagt Claude Code, VS Code, Cursor, GitHub Copilot CLI oder einer Extension nicht, welche JSON-Datei zuerst gelesen wird, ob zwei gleichnamige Einträge zusammengeführt werden oder ob eine Extension nach dem Laden der dateibasierten Konfiguration einen Server registrieren kann. Wer von einer einheitlichen Hierarchie ausgeht, kann die falsche ausführbare Datei mit dem scheinbar richtigen Toolnamen starten.

Dieser Fehler bleibt leicht unbemerkt. Die Toolliste zeigt github, der Agent ruft github.search_code auf und der Aufruf funktioniert. Währenddessen hat dein Terminal-Agent vielleicht einen Projekt-Wrapper für ein Testkonto gestartet, während die IDE einen globalen Befehl für dein persönliches Konto verwendet. Der Name stimmte. Der Befehl nicht.

Das ist meine praktische Regel: Löse die MCP-Konfiguration für jeden Client, jeden Prozess und jeden Servernamen separat auf. Behandle Serverbefehl, Argumente, Umgebung, Arbeitsverzeichnis, Transport-URL und Quelle der Zugangsdaten als eine gemeinsame Startdefinition. Leite nichts davon aus der Bezeichnung in einem Agent-Panel ab.

MCP hat keine gemeinsame Vorranghierarchie

MCP standardisiert Nachrichten und Fähigkeiten zwischen Clients und Servern. Das Protokoll schreibt weder eine portable Dateistruktur noch vor, welche Quelle bei widersprüchlichen Konfigurationen gewinnt. Ein Client kann JSON-Dateien, eine Einstellungsdatenbank, eine Plugin-API, verwaltete Unternehmensrichtlinien, ein Befehlszeilenargument oder alles zusammen verwenden.

Deshalb sind vier Begriffe, die oft gleichbedeutend verwendet werden, tatsächlich verschieden:

• Eine Benutzerkonfiguration ist eine globale, clientspezifische Definition für ein Konto oder Profil.
• Eine Projektkonfiguration ist eine Definition, die zu einem Repository oder Workspace gehört.
• Eine Plugin-Konfiguration ist ein Server, der von einer installierten Extension oder einem Plugin registriert oder bereitgestellt wird.
• Eine Editor-Einstellung gehört zum Editor und steuert möglicherweise überhaupt nicht die MCP-Serverkonfiguration.

Die letzte Unterscheidung verursacht mehr Probleme als nötig. VS Code hat eine ausgereifte allgemeine Einstellungshierarchie: Workspace-Einstellungen überschreiben Benutzereinstellungen für gewöhnliche Einstellungen, und Objektwerte können zusammengeführt werden, während primitive Werte und Arrays überschrieben werden. Das gilt für settings.json. Daraus folgt nicht, dass .vscode/mcp.json dieselben Regeln für Zusammenführung und Konflikte verwendet. VS Code dokumentiert die MCP-Konfiguration als eigene mcp.json-Datei im Workspace oder Benutzerprofil. Übertrage keine Annahmen aus der Einstellungsengine auf ein separates Konfigurationsformat.

Die praktische Konsequenz ist eindeutig: «Der Workspace gewinnt» ist keine brauchbare Antwort, solange du nicht Clientname, Clientversion, Konfigurationsformat und den konkreten Konflikt nennst. Eine Workspace-Datei kann einen Server hinzufügen, einen gleichnamigen globalen Server verdecken, neben ihm bestehen oder wegen eines nicht vertrauenswürdigen Workspace nicht geladen werden. Das sind unterschiedliche Ergebnisse, die ein allgemeines Vorrangsdiagramm verschleiert.

Der Servername ist die Konflikteinheit

Die meisten Clients organisieren MCP-Konfigurationen als Zuordnung: links ein Servername, rechts eine Startdefinition. Der Schlüssel ist oft das, was der Client verwendet, um zwei kollidierende Deklarationen zu erkennen.

Betrachte diese beiden Dateien:

// user configuration
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["/Users/dev/bin/catalog-live.js"],
      "env": { "CATALOG_TARGET": "production" }
    }
  }
}

// project configuration
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["./tools/catalog-fixture.js"],
      "env": { "CATALOG_TARGET": "fixture" }
    }
  }
}

Ein Mensch sieht zwei Katalogdienste. Ein Client sieht zwei Werte unter dem Schlüssel catalog. Wenn er eine Definition auswählt, wählt er normalerweise die gesamte Definition. Ersetze nicht gedanklich den globalen Befehl durch Projektargumente oder den Projektbefehl durch die globale Umgebung. Einige Einstellungssysteme führen Objekte zusammen. Ein MCP-Client muss das nicht tun.

Darum sind partielle Überschreibungen ein schlechtes Design. Ein Projekt, das einen anderen Endpunkt benötigt, sollte seinen vollständigen beabsichtigten Befehl deklarieren. Wer ein persönliches Tool möchte, sollte einen anderen Namen verwenden. Bei einer Teilüberschreibung ist kaum zu erkennen, ob der Client das gesamte Serverobjekt ersetzt oder Felder auf eine Weise zusammenführt, die du nie getestet hast.

Verwende während der Fehlersuche Namen, die Zuständigkeit und Zweck sichtbar machen:

{
  "mcpServers": {
    "catalog-user-live": { "command": "node", "args": ["/Users/dev/bin/catalog-live.js"] },
    "catalog-repo-fixture": { "command": "node", "args": ["./tools/catalog-fixture.js"] }
  }
}

Diese Namen sind nicht elegant. Sie sind ehrlich. Sobald das Team eine einzige maßgebliche Definition hat, kannst du sie in catalog umbenennen. Davor verwandelt ein kurzer doppelter Name jeden Toolaufruf in ein Ratespiel.

Trenne außerdem einen doppelten Namen von einer doppelten Fähigkeit. Zwei Server können beide ein Tool namens search anbieten und trotzdem verschieden sein, weil sich ihre Servernamen unterscheiden. Der Agent kann durch ähnliche Beschreibungen verwirrt werden, aber die Clientkonfiguration enthält nicht zwingend einen Namenskonflikt. Kläre zuerst die Auflösung durch den Client und verbessere danach Toolbeschreibungen und Namen.

Claude Code hat eine ausdrückliche Reihenfolge für MCP-Bereiche

Claude Code ist der einfachste Fall, weil die MCP-Dokumentation die Reihenfolge gleichnamiger Servereinträge nennt. Der lokale Bereich hat Vorrang vor dem Projektbereich, der Projektbereich vor dem Benutzerbereich. Die aktuelle Terminologie ist wichtig: local ist die private, projektspezifische Standardeinstellung, project schreibt eine gemeinsam verwendete .mcp.json, und user gilt projektübergreifend. Anthropic hat früher teilweise andere Namen für diese Bereiche verwendet. Alte Notizen und Shell-Historien können deshalb irreführend sein.

Konkret bedeutet das: Enthalten alle drei Bereiche catalog, startet Claude Code die lokale Definition. Danach kommt die Definition aus .mcp.json, und die Benutzerversion dient als Rückfallebene.

# private to this checkout and this user
claude mcp add catalog --scope local -- node ./tools/catalog-fixture.js

# shared with the repository
claude mcp add catalog --scope project -- node ./tools/catalog-service.js

# available in all repositories for this user
claude mcp add catalog --scope user -- node ~/bin/catalog-personal.js

Das erwartete Prüfergebnis ist ein effektiver Server namens catalog, der bei vorhandenen drei Definitionen aus dem lokalen Bereich stammt. Führe nach jeder Änderung den Clientbefehl aus, der den Server auflistet oder abruft, statt der gerade bearbeiteten Datei zu vertrauen:

claude mcp get catalog

Die Ausgabe sollte den benannten Server identifizieren und Details zu seinem konfigurierten Transport oder Befehl zeigen. Vergleiche den tatsächlichen Befehl, die Argumente und die Umgebung mit der erwarteten Definition. Wenn der Befehl nicht dem bearbeiteten Eintrag entspricht, ändere nicht weiter Dateien, sondern finde heraus, welcher Bereich den Namen noch besitzt.

Verwechsle diese MCP-Regel nicht mit dem allgemeineren Vorrang von Claude-Code-Einstellungen. Anthropic dokumentiert für allgemeine Einstellungen verwaltete Unternehmensrichtlinien, Befehlszeilenargumente, lokale Projekteinstellungen, gemeinsam genutzte Projekteinstellungen und Benutzereinstellungen. Eine verwaltete Einstellung kann daher das Umfeld der MCP-Nutzung einschränken, ohne eine zweite MCP-Serverdefinition zu sein. Die beiden Hierarchien beantworten unterschiedliche Fragen.

Auch der Projektbereich birgt eine Falle. Claude Code bittet um Zustimmung, bevor ein von .mcp.json bereitgestellter Server verwendet wird. Diese Zustimmung betrifft die Nutzung des Projektservers. Sie ändert nicht, welche gleichnamige Serverkonfiguration Vorrang hat. Lies eine Zustimmungsabfrage daher nicht als Beweis dafür, dass der gemeinsame Befehl gewonnen hat.

VS Code trennt MCP-Dateien von gewöhnlichen Einstellungen

VS Code bietet zwei dokumentierte Speicherorte für die MCP-Serverkonfiguration: .vscode/mcp.json im Workspace und eine mcp.json im Benutzerprofil, die über den Befehl MCP: Open User Configuration geöffnet wird. Die Workspace-Datei ist für die Weitergabe über die Versionskontrolle gedacht, während die Profildatei dem Benutzer folgt und sich je nach VS-Code-Profil unterscheiden kann.

Diese Struktur legt eine vernünftige Erwartung nahe: Die Repository-Konfiguration definiert Repository-Tools, das Profil persönliche Tools. Sie dokumentiert jedoch keine vollständige Regel für doppelte Namen. Insbesondere sagt die öffentliche MCP-Referenz nicht, dass der normale Vorrang von VS-Code-Einstellungen feldweise auf servers-Einträge angewendet wird.

Hier machen erfahrene Benutzer einen falschen Kurzschluss. Sie wissen, dass Workspace-Einstellungen Benutzereinstellungen überschreiben. Dann tragen sie denselben MCP-Servernamen in Profil- und Workspace-Konfiguration ein, ändern den Projektbefehl und schließen daraus, dass der Workspace-Befehl starten muss. Das kann so sein. Eine Schlussfolgerung aus einem benachbarten Einstellungssystem bleibt aber eine Schlussfolgerung und ist kein dokumentierter Vertrag.

Behandle einen gleichnamigen Konflikt in VS Code als Testanforderung. Mache die beiden Kandidaten sichtbar verschieden und verwende einen harmlosen Befehl, der zeigt, welcher gestartet wurde:

{
  "servers": {
    "precedence-probe": {
      "type": "stdio",
      "command": "sh",
      "args": ["-lc", "printf 'workspace probe started\\n' >&2; exec node ./tools/probe-server.js"]
    }
  }
}

Setze in der Benutzerprofil-Konfiguration eine andere Markierung:

{
  "servers": {
    "precedence-probe": {
      "type": "stdio",
      "command": "sh",
      "args": ["-lc", "printf 'profile probe started\\n' >&2; exec node $HOME/bin/probe-server.js"]
    }
  }
}

Starte den Server anschließend vollständig über die MCP-Verwaltungsoberfläche von VS Code neu. Wenn die Oberfläche den Prozesszustand nicht eindeutig zeigt, starte den Editor neu. Prüfe die MCP-Ausgabe oder Protokolle auf die Markierung. Teste nicht gegen eine echte Datenbank oder ein echtes Deployment-Ziel. Ein Vorrangtest soll einen Startpfad nachweisen und keine Daten verändern.

Dasselbe gilt für die Aktivierung. VS Code dokumentiert, dass der Aktivierungs- und Deaktivierungsstatus getrennt von der Serverkonfiguration gespeichert wird. Eine gemeinsame Konfigurationsdatei kann vorhanden sein, während der Server in einem Workspace nicht startet. «Ich sehe ihn in mcp.json» und «dieser Client hat ihn gestartet» sind verschiedene Tatsachen.

Multi-Root-Workspaces bieten eine weitere Quelle für falsche Gewissheit. VS Code kennt für allgemeine Einstellungen Workspace- und Workspace-Folder-Bereiche. Eine an einen Workspace gebundene MCP-Datei ist deshalb nicht automatisch eine Serverdeklaration pro Ordner. Wenn ein Tool einen repositoryrelativen Befehl benötigt, mache Workspace-Root und erwartetes Arbeitsverzeichnis in deinem Test ausdrücklich. Ein Befehl, der in einem Root funktioniert, kann fehlschlagen oder bei mehreren geöffneten Ordnern unbemerkt auf eine andere Datei zugreifen.

Cursor bietet Projekt-, globale und Extension-Registrierung

Cursor dokumentiert projektspezifische MCP-Konfiguration in .cursor/mcp.json und globale Konfiguration in ~/.cursor/mcp.json. Außerdem bietet es eine Extension-API, über die MCP-Server programmgesteuert registriert werden können. Das sind drei getrennte Quellen: Repository-Datei, Benutzerdatei und Code innerhalb einer Extension.

Die ersten beiden sind bei eindeutigen Namen leicht zu verstehen. Lege einen gemeinsamen Entwicklungsdienst des Repositorys in .cursor/mcp.json ab. Ein persönliches Tool, etwa einen lokalen Suchdienst für Notizen, legst du in die globale Datei. Die Cursor-CLI sagt, dass sie mcp.json erkennt und berücksichtigt. Das macht gemeinsame Konfigurationen nützlich, wenn IDE und Terminal-Agent tatsächlich in derselben Umgebung laufen.

Schwierig wird es bei einem doppelten Namen aus allen drei Quellen. Die öffentliche Cursor-Dokumentation sagt, wo Projekt- und globale Dateien liegen, veröffentlicht aber keinen vollständigen Vertrag für jeden Konflikt zwischen globaler Konfiguration, Projektkonfiguration und dynamisch registriertem Extension-Server. Erfinde keine Regel aus einem Forenbeitrag, einer alten Release-Note oder dem Verhalten eines einzelnen Rechners.

Das sichere Design vermeidet den Konflikt. Wenn eine Extension issue-tracker bereitstellt, lege keinen zweiten Eintrag issue-tracker in .cursor/mcp.json an und hoffe, dass der Repository-Befehl ihn ersetzt. Gib dem vom Repository verwalteten Server einen anderen Namen, etwa issue-tracker-fixture, und erkläre in Agent-Anweisungen oder Toolbeschreibungen, wann er verwendet werden soll.

Das ist besonders wichtig für Teams, die ein Plugin aus Bequemlichkeit und eine Datei zur Reproduzierbarkeit verwenden. Das Plugin kann Installation, OAuth, Updates oder Registrierung nach eigenem Zeitplan verwalten. Eine Repository-Datei ist im Code-Review sichtbar. Das sind unterschiedliche Modelle der Zuständigkeit. Entscheide, wer den Server besitzt, bevor du versuchst, beide zufällig aufeinander abzustimmen.

Umgebungsgrenzen lassen Cursor-Konflikte rätselhafter erscheinen, als sie sind. Ein Desktop-Editor kann unter einem Betriebssystem laufen, während Terminal, Remote-Workspace oder Entwicklungscontainer in einer anderen Umgebung ausgeführt werden. Eine globale Datei im Home-Verzeichnis kann in einer Umgebung existieren und in der anderen fehlen. Der Befehl in einer Projektdatei kann node, python oder eine relative ausführbare Datei über unterschiedliche PATH-Werte auflösen. Notiere vor der Diskussion über Vorrang, wo der Clientprozess und wo der Serverprozess laufen.

Für jeden Kandidaten solltest du dieses kurze Startprotokoll führen:

client: Cursor desktop / Cursor CLI
client environment: local macOS / WSL / remote host / container
config source: ~/.cursor/mcp.json / .cursor/mcp.json / extension registration
server name: issue-tracker
command: node ./tools/issue-mcp.js
working directory: repository root
credential source: OAuth / local environment / external gateway

Ein solches Protokoll dauert fünf Minuten und ist hilfreicher als ein Nachmittag mit Einstellungsdialogen.

GitHub Copilot CLI dokumentiert den Vorrang von Projekt vor Benutzer

GitHub Copilot CLI ist ausdrücklicher als viele andere Clients. Die Dokumentation sagt, dass eine MCP-Konfiguration auf Projektebene in .mcp.json oder .github/mcp.json Vorrang vor einer gleichnamigen Definition in ~/.copilot/mcp-config.json hat. Für MCP-Servernamen in der CLI gilt damit klar: Projekt vor Benutzer.

Verwende diese Regel als clientspezifische Regel und nicht als allgemeine Wahrheit für GitHub Copilot in jedem Editor. Copilot CLI besitzt ein eigenes Konfigurationsverzeichnis, Repository-Einstellungen, lokale Einstellungen, Plugin-Unterstützung, einen Berechtigungsspeicher und einen Befehlszeilenprozess. Eine Copilot-Sitzung in VS Code ist eine andere Client-Oberfläche mit eigener MCP-Dokumentation und eigenem Lebenszyklus.

Eine übersichtliche Copilot-CLI-Konfiguration kann so aussehen:

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/Users/dev/bin/company-docs-mcp.js"]
    },
    "catalog": {
      "command": "node",
      "args": ["/Users/dev/bin/catalog-live.js"]
    }
  }
}

// .mcp.json in the repository
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["./tools/catalog-fixture.js"]
    }
  }
}

In diesem Repository sollte Copilot CLI die Projektdefinition von catalog verwenden und die Benutzerversion von docs behalten, weil es für docs keinen konkurrierenden Projekteintrag gibt. Das ist das sinnvolle Modell: Überschreibe nur den Namen, für den das Projekt zuständig ist, und lasse unabhängige persönliche Tools unangetastet.

Plugins erschweren die Lage, weil sie eigenes Agent-Verhalten und einen eigenen MCP-Serverlebenszyklus mitbringen können. Die GitHub-Konfigurationsdokumentation beschreibt repositoryaktivierte Plugins als an das Repository gebunden und sagt, dass der Client den MCP-Server eines Plugins beendet, sobald das Repository das Plugin nicht mehr aktiviert. Das zeigt, dass der Server an die Plugin-Aktivierung gebunden ist und nicht bloß in deine Benutzerdatei kopiert wird.

Wenn ein Plugin-Server und ein dateibasierter Server denselben Namen verwenden, rate nicht, welcher Befehl gewinnt. Prüfe den sichtbaren Serverstatus der CLI, den Pluginstatus und die Startausgabe. Nennt die Dokumentation der installierten Version das Konfliktverhalten nicht, benenne eine Definition um oder entferne einen der beiden Erzeuger. Der beliebte Rat, den Plugin-Server einfach im Repository zu überschreiben, klingt attraktiv, weil er kurz ist. Er ist falsch, wenn das Plugin die Registrierung nach dem Laden der Dateien übernimmt oder zusätzlichen Lebenszyklusstatus liefert.

Editor und Terminal sind getrennte MCP-Clients

Ein Terminal innerhalb einer IDE fühlt sich wie ein Teil des Editors an. Es bleibt ein Shell-Prozess. Wenn du claude, copilot oder cursor-agent ausführst, kann dieser Befehl eigene Dateien, das aktuelle Verzeichnis, die Umgebung, das Home-Verzeichnis und Konfigurationsvariablen lesen. Die Chat-Extension des Editors ist ein anderer Prozess mit einer anderen Clientimplementierung.

Daraus entsteht die bekannte Meldung: «Der MCP-Server funktioniert in der IDE, aber nicht im Terminal.» Dafür gibt es mehrere gewöhnliche Erklärungen:

• Der Editor hat eine Workspace-Datei geöffnet, während das Terminal in einem Unterverzeichnis oder einem anderen Checkout gestartet wurde.
• Der Editor nutzt einen Remote-Host oder Container, während der Terminalbefehl lokal läuft.
• Das Terminal übernimmt ein Shell-spezifisches PATH, HOME, eine Proxy-Einstellung oder eine Zugangsdatenvariable.
• Der Editor hat einen Plugin-Server aktiviert, den die CLI nie lädt.
• Die CLI hat einen Projektserver mit demselben Namen gefunden und den Eintrag auf Benutzerebene ersetzt.

Beginne nicht damit, jede Konfigurationsdatei an jeden Ort zu kopieren. Dadurch vergrößerst du die Konfliktfläche und verbirgst die eigentliche Ursache.

Führe stattdessen jeweils nur einen Client aus und sammle Belege. Verwende bei Terminal-Clients den integrierten Befehl zum Auflisten oder Abrufen von MCP-Servern. Bei Editor-Clients nutze die MCP-Serververwaltung und ihre Ausgabe oder Protokolle. Notiere Servername, Befehl, Argumente, Prozessumgebung und Startzeit. Wenn Terminal und Editor denselben Namen, aber unterschiedliche Befehle zeigen, hast du ein Problem bei der Konfigurationsauflösung gefunden. Wenn sie denselben Befehl zeigen, sich aber unterschiedlich verhalten, prüfe Arbeitsverzeichnis, Zugangsdaten, Netzwerkzugriff oder den Server selbst.

Ein nützlicher Test besteht darin, den vorgesehenen Serverbefehl vorübergehend durch einen Wrapper zu ersetzen, der vor dem echten Server eine eindeutige Markierung nach Standardfehlerausgabe schreibt. Der Wrapper sollte schreibgeschützt sein und nach dem Test entfernt werden.

#!/bin/sh
printf '%s client=%s cwd=%s\\n' \
  "MCP probe started" \
  "${MCP_CLIENT_LABEL:-unknown}" \
  "$PWD" >&2
exec node "$(dirname "$0")/real-server.js"

Gib keine Tokens, Header, Zugangsdaten, vollständigen Umgebungsvariablen oder Request-Inhalte aus. Protokolle bleiben oft länger bestehen als die Terminalsitzung. Ein Vorrangtest sollte keine Geheimnisse offenlegen, während er ein anderes Problem erklärt.

Eine Plugin-Registrierung ist keine Überschreibung einer Konfigurationsdatei

Ein Plugin erzeugt Serverkonfiguration. Es ist nicht bloß ein weiterer Ordner mit JSON-Dateien. Es kann einen Server dynamisch registrieren, Authentifizierung verwalten, eine Version auswählen, auf Workspace-Änderungen reagieren oder den Server beim Deaktivieren des Plugins beenden.

Dadurch werden zwei verbreitete Empfehlungen unsicher.

Die erste lautet: «Trage denselben Namen in die Projektdatei ein, um das Plugin zu überschreiben.» Das funktioniert nur, wenn der Client dokumentiert, dass Dateien nach Plugins geladen werden und ein Namenskonflikt die Plugin-Registrierung ersetzt. Ohne diesen Vertrag kann der doppelte Eintrag einen Fehler, eine verdeckte Ersetzung, zwei ähnlich beschriebene Tools oder ein Verhalten erzeugen, das sich nach einem Update ändert.

Die zweite lautet: «Deaktiviere den Server in der Oberfläche, dann ist das Projekt sauber.» Der Aktivierungsstatus kann außerhalb der gemeinsamen Datei liegen. VS Code trennt den Aktivierungs- und Deaktivierungsstatus ausdrücklich von der MCP-Konfiguration. Ein Teammitglied kann das Repository klonen, dieselbe Datei erhalten und trotzdem eine andere Gruppe aktiver Server haben.

Verwende stattdessen eines dieser Zuständigkeitsmuster:

1. Dateiverwalteter Server: Das Repository versioniert die Serverdefinition. Alle verwenden die Datei, und kein Plugin registriert denselben Dienst.
2. Pluginverwalteter Server: Das Plugin verwaltet Registrierung und Authentifizierung. Das Repository deklariert keinen doppelten Server.
3. Getrennte Serverrollen: Ein Plugin besitzt tracker-live, eine Projektdatei besitzt tracker-fixture. Namen, Beschreibungen und Berechtigungen machen die Ziele eindeutig.

Die dritte Option ist oft die unspektakulärste und sicherste. Teams benötigen häufig gleichzeitig einen persönlichen Live-Dienst und ein Repository-Fixture. So zu tun, als wäre das ein Server, weil beide mit einem Issue-Tracker sprechen, erhöht nur die Wahrscheinlichkeit eines unbeabsichtigten Live-Aufrufs.

So weist du den siegreichen Befehl reproduzierbar nach

Du kannst die Konfigurationsauflösung nachweisen, ohne dich auf das Verhalten des Agenten zu verlassen. Die folgende Methode verwendet einen harmlosen stdio-Server oder Wrapper und funktioniert sowohl bei lokalen Befehlen als auch bei einem Remote-Service.

Eine Probe aus zwei Quellen erstellen

Wähle einen Servernamen, etwa precedence-probe. Definiere ihn genau in den zwei Quellen, die du vergleichen möchtest. Jeder Kandidat soll vor dem Start desselben harmlosen Testservers eine andere Markierung ausgeben.

Bei einem befehlsbasierten Server musst du jeden relevanten Bestandteil unterscheiden:

{
  "mcpServers": {
    "precedence-probe": {
      "command": "sh",
      "args": ["-lc", "printf 'SOURCE=PROJECT CWD=%s\\n' \"$PWD\" >&2; exec node ./tools/probe.js"],
      "env": { "MCP_PROBE_SOURCE": "project" }
    }
  }
}

Der Benutzerkandidat sollte SOURCE=USER ausgeben und auf eine andere, bekannte Datei verweisen. Verlasse dich nicht nur auf eine Umgebungsvariable, falls der Client sie ausblendet, filtert oder einen veralteten Prozess startet. Verwende zusätzlich eine sichtbare Markierung im Befehlspfad und in der Ausgabe.

Den Server neu starten, nicht nur den Chat

MCP-Server sind oft langlebige untergeordnete Prozesse. Das Bearbeiten von JSON, während der Server weiterläuft, sagt nichts über die nächste Anfrage aus. Verwende die Clientsteuerung, die den Server stoppt und neu startet. Wenn diese Steuerung unklar ist, schließe den betreffenden Client vollständig und öffne den Workspace erneut.

Prüfe anschließend zuerst die clientseitigen Protokolle. Die erwarteten Belege sehen so aus:

MCP probe started
SOURCE=PROJECT
CWD=/path/to/repository

Wenn keine Markierung erscheint, hat der Client die Konfiguration möglicherweise vor dem Prozessstart abgelehnt, einen Remote-Transport verwendet oder einen alten Server weiterlaufen lassen. Auch dieses Ergebnis ist nützlich. Es grenzt die Frage von «Welche Konfiguration gewinnt?» auf «Wurde diese Konfiguration geladen und hat dieser Client einen Prozess gestartet?» ein.

Immer nur eine Grenze ändern

Führe die Probe zuerst im Terminal-Client und danach im IDE-Client aus. Ändere das aktuelle Arbeitsverzeichnis erst nach einer Ausgangsmessung. Deaktiviere das Plugin erst, nachdem du das Verhalten ohne Plugin gemessen hast. Teste Benutzer- und Projektquellen, bevor du lokale Überschreibungen oder verwaltete Einstellungen hinzufügst.

Führe im Repository-Issue oder in den Teamnotizen eine kleine Ergebnistabelle:

Die Tabelle soll beobachtetes und nicht erwartetes Verhalten wiedergeben. Mit beobachtetem Verhalten kann ein Team arbeiten. Ein Diagramm aus einem anderen Client ist nur eine Hypothese.

Zugangsdaten aus dem Vorrangkonflikt heraushalten

Ein Befehlskonflikt ist ein Ausführungsproblem. Ein Zugangsdatenkonflikt ist ein Sicherheitsproblem. Löse das erste nicht dadurch, dass du Geheimnisse auf Projekt-, Plugin-, Benutzer- und Editor-Konfigurationen verteilst, bis etwas funktioniert.

Eine versionierte Projektkonfiguration sollte normalerweise einen Serverbefehl, nicht sensible Endpunktinformationen und Hinweise zum Abrufen der Zugangsdaten enthalten. Sie sollte kein langlebiges Bearer-Token in env, keinen SSH-Privatschlüsselpfad, der Teammitgliedern fehlt, und keinen benutzerdefinierten Header mit Produktionszugriff enthalten. Eine Projektdatei wird für jeden Checkout und jeden Agenten, dem der Client die Nutzung erlaubt, zu einer Ausführungseinladung.

Wenn ein Server ein Geheimnis benötigt, wähle eine zum Arbeitsablauf passende Grenze für Zugangsdaten:

• OAuth passt, wenn Server und Client es unterstützen und der Benutzer den Zugriff interaktiv gewähren soll.
• Ein lokaler Secret-Manager oder das Einfügen über die Umgebung passt zu einer persönlichen Serverdefinition.
• Ein Repository-Fixture sollte nicht produktive Zugangsdaten mit eingeschränkten Berechtigungen verwenden.
• Ein Aktions-Gateway passt, wenn ein Agent eine Aktion anfordern soll, ohne die zugrunde liegenden API- oder SSH-Zugangsdaten zu erhalten.

Hier kann ein Serverbefehl harmlos aussehen und trotzdem gefährlich sein. npx some-mcp-server kann auf verschiedenen Rechnern eine andere installierte Version auflösen. node ./tools/server.js kann AWS_PROFILE, GH_TOKEN oder einen Unternehmensproxy vom übergeordneten Prozess übernehmen. Eine Projekterklärung kann geprüft werden, während ihre tatsächliche Quelle für Zugangsdaten unsichtbar bleibt.

Wenn Agenten HTTP- oder SSH-Zugriff benötigen, kann Sallyport die API- oder SSH-Zugangsdaten in seinem verschlüsselten Tresor halten. Der Agent verbindet sich über den sp mcp-Shim und erhält nur Aktionsergebnisse. Das entscheidet nicht, welche Clientkonfiguration gewinnt, verhindert aber, dass ein siegreicher Befehl zugleich rohe Zugangsdaten an den Agenten weitergibt.

Behandle Konfigurationsvorrang nicht als Berechtigungssystem. Eine Projektdefinition kann einen Befehl auswählen, beweist aber nicht, dass dieser Befehl ohne Prüfung handeln darf. Halte Genehmigung, Speicherung der Zugangsdaten und Auditnachweise als getrennte Kontrollen.

Den maßgeblichen Befehl eindeutig machen

Teams brauchen eine klare Antwort auf eine einfache Frage: Welchen Befehl soll der Agent dieses Repositorys für diesen Dienst starten? Wenn die Antwort zwischen Benutzerdateien, Pluginverhalten, README-Ausschnitten und Editoreinstellungen verborgen ist, ist die Einrichtung bereits zu locker.

Schreibe die maßgebliche gemeinsame Definition an einen einzigen Ort. Gib ihr einen stabilen Servernamen. Nenne die unterstützten Clients und die zuständige Quelle. Persönliche Varianten sollten andere Namen tragen. Wenn ein Plugin den Dienst besitzen muss, dokumentiere das Plugin als maßgeblich und liefere keine konkurrierende Dateidefinition aus.

Halte anschließend einen kleinen Prüf- oder Probe-Befehl im Repository bereit. Konfigurationsänderungen verdienen Tests, genau wie Deployment-Skripte. Ein Server, der den falschen Befehl startet, kann falsche Dateien lesen, den falschen Endpunkt aufrufen oder die falschen Zugangsdaten übernehmen, bevor ein Agent überhaupt etwas sagt.

Das nützliche Ergebnis ist keine universelle Vorrangtabelle. Es ist eine Einrichtung, in der jeder Client einen beobachtbaren Startpfad besitzt, jeder Servername genau einen Besitzer hat und niemand raten muss, welchen Befehl sein Agent ausführt.