Einen MCP-Server zur Selbstinstallation bringen: Drei Hosts, drei Mechanismen, Stolperfallen

Die Einrichtung von MCP-Servern bedeutet oft noch, eine JSON-Datei manuell zu bearbeiten – und jeder Host verwendet eine andere Datei und ein anderes Format. Diese Reibung hält Entwickler davon ab, Server auszuführen, die sie sonst nutzen würden. Dieser Beitrag analysiert drei Hosts, ihre Installationsmechanismen und die Fallstricke, die Ihnen den Weg versperren.

Drei Hosts, drei Mechanismen

• VS Code: Hat eine echte API – registerMcpServerDefinitionProvider. Deklarieren Sie einen Provider in package.json und geben Sie die Serverdefinition zur Laufzeit zurück. VS Code zeigt einen Zustimmungsdialog. Keine Bearbeitung von Konfigurationsdateien. Am saubersten, erfordert jedoch das Ausliefern einer VS Code-Erweiterung.
• Cursor: Keine native API. Schreiben Sie .cursor/mcp.json direkt mit dem Root-Key mcpServers.
• Claude Code: Verwenden Sie die CLI. Schreiben Sie die Datei nicht von Hand. Führen Sie z.B. aus:
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

Sechs Fallstricke, die Sie beachten sollten

1. Diese JSON-Datei gehört nicht Ihnen. Cursors mcp.json enthält die anderen Server des Benutzers. Lesen Sie die Datei, fügen Sie Ihren Eintrag hinzu, bewahren Sie nicht verwandte Schlüssel – überschreiben Sie nicht.
2. Überstehen Sie eine fehlerhafte Datei. Wenn die Datei existiert, aber ungültiges JSON enthält, behandeln Sie sie nicht als leer und überschreiben Sie sie nicht. Gleiches gilt für Lese-/Berechtigungsfehler – werfen Sie diese erneut. Die Annahme, dass „konnte nicht gelesen werden“ gleich „nichts vorhanden“ ist, wird Konfigurationen beschädigen.
3. Backup + atomares Schreiben. Kopieren Sie die vorhandene Datei, bevor Sie sie bearbeiten, schreiben Sie in eine temporäre Datei und verschieben Sie diese dann über das Ziel. Eine halb geschriebene mcp.json beschädigt den Editor.
4. Zweimalige Installation muss ein No-Op sein, kein Fehler. Die Claude CLI gibt einen Fehler aus, wenn der Eintrag bereits existiert – also führen Sie remove und dann add aus. Für Datei-Hosts identifizieren Sie den Server nach Namen und ersetzen Sie ihn an Ort und Stelle. Erneutes Ausführen sollte konvergieren, nicht duplizieren.
5. Scope ändert alles. Die Installation auf Benutzerebene vs. Projektebene ändert, wo die Konfiguration landet und was der Server benötigt (z.B. explizites Datenverzeichnis vs. Aufwärtssuche). Wählen Sie bewusst.
6. Sie sind für Aktualität verantwortlich. Die registrierte Version weicht von der ausgelieferten ab. Fügen Sie eine Prüfung hinzu: „Ist die installierte Version noch die, die ich bereitstelle?“ und einen sauberen Neuinstallationspfad. Ein Button zeigt den Status: installieren, aktualisieren oder aktuell.

Die übergeordnete Lektion: Manuelle Einrichtung scheitert, weil ein Mensch, der ein Snippet einfügt, den absoluten Pfad, den richtigen Scope, Umgebungsvariablen oder die sichere Zusammenführung nicht kennt. Der Installationscode tut es.