Toeverything·Veröffentlicht 20. Aug. 2026 · Aktualisiert 21. Aug. 2026
MCP Server zu Claude Code hinzufügen: Setup und Fehlersuche
Produktivität
Das Wichtigste in Kürze
Claude Code spricht MCP von Haus aus: Ein Remote-Server ist mit einem einzigen claude mcp add in wenigen Minuten angebunden.
Die Konfiguration landet in einem von drei Scopes (local, project, user). Team-Standards gehören in project, Zugangsdaten bleiben im persönlichen Scope.
Claude Desktop hat zwei Wege: Connectors für Remote-Server, Konfigurationsdatei für lokale. Die Einstellungen sind von Claude Code unabhängig.
Wenn ein Server nicht auftaucht: Der Befehl /mcp in der Sitzung zeigt den Verbindungsstatus — immer der erste Blick.
Dieser Leitfaden behandelt claude mcp add samt Scope-Logik, die Einrichtung in Claude Desktop, ein komplettes Praxisbeispiel mit einem AFFiNE-Workspace und eine Checkliste für die Fehlersuche. Wer noch beim Konzept ist, startet bei Was ist ein MCP Server.
MCP Server zu Claude Code hinzufügen
Für einen Remote-Server (HTTP) — der Normalfall bei gehosteten Diensten:
Für einen lokalen Server (stdio), den Claude Code auf Ihrem Rechner startet:
claude mcp add <name> -- <startbefehl-des-servers>
Die Verwaltung erledigen drei Unterbefehle: claude mcp list zeigt alle Server, claude mcp get die Details, claude mcp remove entfernt einen wieder. Liefert ein Produkt fertiges JSON, nimmt claude mcp add-json '' den Block unverändert entgegen. In der Sitzung zeigt /mcp Verbindungsstatus und verfügbare Tools — die erste Anlaufstelle, wenn etwas hakt. Alle Flags im Detail listet die offizielle MCP-Referenz.
Scopes: local, project, user
Wo die Konfiguration gespeichert wird, entscheidet, wer sie sieht:
local (Standard): dieses Projekt, dieser Rechner, nur Sie — abgelegt in ~/.claude.json unter dem Projektpfad. Richtig für Experimente und persönliche Zugangsdaten.
project: landet als .mcp.json im Repository-Root, versioniert und fürs ganze Team. Der Ort für Team-Standards wie die Wissensbasis; Kolleginnen und Kollegen bestätigen den Server bei der ersten Nutzung.
user (--scope user): gilt für Sie in allen Projekten des Rechners, ebenfalls in ~/.claude.json. Für persönliche Server im Dauereinsatz.
Definieren mehrere Scopes denselben Servernamen, gewinnt local vor project vor user — es zählt der komplette Eintrag des Gewinners, zusammengeführt wird nichts.
Die Faustregel für Teams: Geteilt wird nur die Server-Definition, nie das Token. Claude Code expandiert in .mcp.json Umgebungsvariablen — ${VAR}, mit ${VAR:-fallback} auch mit Standardwert — und zwar in url, headers, env, command und args. Eine teamtaugliche .mcp.json sieht so aus:
Die Datei wird eingecheckt, AFFINE_TOKEN setzt jede Person in der eigenen Shell — das Token landet nie im Repository.
In Claude Desktop hinzufügen
Remote-Server: Einstellungen → Connectors → benutzerdefinierten Connector hinzufügen, URL einfügen, autorisieren. Der Weg ohne Terminal — für gehostete Server wie den von AFFiNE oder Notion reicht das.
Lokale Server: claude_desktop_config.json bearbeiten (Einstellungen → Entwickler → Konfiguration bearbeiten), den Server unter mcpServers eintragen, dann Claude Desktop komplett beenden und neu starten — nur das Fenster zu schließen genügt nicht.
Dieselben Server laufen in Claude Code und Claude Desktop, aber jede Oberfläche verwaltet ihre eigene Konfiguration. Doppelt tippen muss trotzdem niemand: claude mcp add-from-claude-desktop übernimmt bestehende Desktop-Server per Auswahldialog nach Claude Code (auf macOS und WSL).
Schritt für Schritt: die eigene Wissensbasis anbinden
Der komplette Ablauf mit dem eingebauten MCP Server von AFFiNE, der Dokumente und Whiteboards des Workspace für jeden MCP Client durchsuchbar macht:
Zugangsdaten anlegen. In AFFiNE: Einstellungen → Integrations → MCP Server → Create credential. Als Label den Client-Namen vergeben („Claude Code") — ein Credential pro Client macht den Widerruf schmerzlos. Den Zugriff beim Standard schreibgeschützt belassen und ein Ablaufdatum setzen.
Konfiguration kopieren. Das Token erscheint genau einmal; daneben erzeugt Copy JSON die vollständige Konfiguration, Endpunkt-URL und Auth-Header inklusive. Der Endpunkt hat die Form https://app.affine.pro/api/workspaces//mcp; auf selbst gehosteten Instanzen steht dort Ihre eigene Serveradresse.
Nutzen. Sitzung öffnen und etwas fragen, das nur die eigenen Notizen beantworten können: „Such das Konzept zu fehlgeschlagenen Zahlungen und fasse die offenen Punkte zusammen." Claude Code ruft das Such-Tool auf (Stichwort- plus semantische Suche, Whiteboards eingeschlossen), liest gefundene Dokumente als Markdown im Rahmen Ihrer Berechtigungen und antwortet aus Ihren echten Inhalten.
Ohne Aufpreis: Das funktioniert auf AFFiNE Cloud ebenso wie auf selbst gehosteten Instanzen mit aktivierten KI-Funktionen.
Der Transport bestimmt, wo der Server ausgeführt wird; die Berechtigungen der Zugangsdaten bestimmen, auf welche Tools und Daten der Client zugreifen darf.
Dieselbe Konfiguration für Cursor und ChatGPT
Cursor liest ~/.cursor/mcp.json (projektbezogen .cursor/mcp.json). Die Copy-JSON-Ausgabe von AFFiNE entspricht dem Cursor-Format eins zu eins: einfügen, neu starten, fertig.
ChatGPT verbindet sich über Konnektoren mit Remote-MCP-Servern; benutzerdefinierte Server verlangen den Entwicklermodus (Einstellungen → Konnektoren → Erweitert). Derselbe Endpunkt, derselbe Header, keine Änderung. Ein Server, alle Assistenten — genau dafür ist MCP da.
Fehlersuche: der Server taucht nicht auf
Von oben nach unten prüfen — diese Liste deckt fast alle Fälle ab:
Zuerst /mcp. Dort steht, ob der Server verbunden ist, an der Authentifizierung scheitert oder gar nicht erst startet. Die angezeigte Fehlermeldung zu lesen schlägt jedes Raten.
Falscher Transport. Gehostete Server brauchen --transport http; ohne das Flag behandelt Claude Code die URL als lokalen Befehl. Entfernen und mit Flag neu hinzufügen.
Tippfehler im Header. Das Format ist Authorization: Bearer — ein fehlendes Bearer oder ein Leerzeichen zu viel ergibt ein stilles 401. Nicht abtippen, aus Copy JSON einfügen.
Der Server will OAuth statt Header. Manche gehosteten Server authentifizieren im Browser: /mcp öffnen, den Server auswählen, Anmeldung durchlaufen. Ein hinterlegter Authorization-Header, den der Server ablehnt, blockiert dabei den OAuth-Weg — erst den Header entfernen.
Abgelaufene oder widerrufene Zugangsdaten. Tokens mit Ablaufdatum laufen irgendwann ab. Neues Credential ausstellen und neu registrieren.
Scope verwechselt. Ein im local-Scope angelegter Server existiert in anderen Projekten nicht. claude mcp list im erwarteten Verzeichnis schafft Klarheit.
Fehlende Abhängigkeit beim lokalen Server. stdio-Server starten einen Befehl; fehlt die Laufzeitumgebung, stirbt er sofort. Den Befehl einmal von Hand ausführen und den echten Fehler lesen.
Verbunden, aber ungenutzt. Anfangs die Quelle im Prompt nennen („such in meinem AFFiNE-Workspace nach ..."). Sobald sich das eingespielt hat, greift Claude auch unaufgefordert zum richtigen Tool.
Sichere Defaults, die bleiben sollten
Schreibgeschützt, bis Schreiben nötig ist. Eine Wissensbasis-Anbindung braucht selten Schreibzugriff; AFFiNE-Zugangsdaten sind standardmäßig schreibgeschützt, Schreibzugriff wird schrittweise ausgerollt.
Ein Credential pro Client. Den Laptop widerrufen, ohne den Desktop zu treffen. Mit Ablaufdatum wird die Rotation zum Kalendertermin statt zum Feuerwehreinsatz.
Tool-Freigaben bewusst erteilen. Claude fragt vor dem ersten Einsatz eines neuen Tools; project-weite Server bestätigt jede Person beim ersten Mal. Diese Nachfrage für alles, was Daten ändern kann, eingeschaltet lassen. Die vollständige Checkliste steht in unserem MCP-Sicherheitsleitfaden (auf Englisch).
Häufige Fragen
Mit welchem Befehl füge ich einen MCP Server zu Claude Code hinzu?
Mit claude mcp add: für gehostete Server mit --transport http, Server-URL und Auth-Header, für lokale mit dem Startbefehl. Kontrolle per claude mcp list; in der Sitzung zeigt /mcp den Status sofort.
Unterstützt Claude Desktop MCP Server?
Ja. Remote-Server kommen über Einstellungen → Connectors als benutzerdefinierter Connector hinein, lokale in die claude_desktop_config.json unter mcpServers mit anschließendem Neustart. Claude Desktop und Claude Code verwalten getrennte Konfigurationen; claude mcp add-from-claude-desktop importiert bestehende Desktop-Server nach Claude Code (macOS und WSL).
Was unterscheidet die Scopes local, project und user?
local gilt für Sie in einem Projekt; project schreibt eine geteilte .mcp.json ins Repository fürs ganze Team; user gilt für Sie in allen Projekten des Rechners. Zugangsdaten bleiben persönlich — geteilt wird über project nur die Server-Definition, das Token kommt als ${VAR}-Platzhalter aus der Umgebung jeder Person.
Wie teilt ein Team eine MCP-Konfiguration, ohne Tokens zu committen?
Über den project-Scope plus Umgebungsvariablen: Die .mcp.json referenziert das Token als Platzhalter (etwa "Authorization": "Bearer ${AFFINE_TOKEN}"), Claude Code expandiert ${VAR} und ${VAR:-fallback} in url, headers, env, command und args. Die Datei wird versioniert, das Token setzt jede Person lokal in der eigenen Shell — es landet nie im Repository.
Kann Claude Code Remote-MCP-Server ansprechen?
Ja. Remote-Server über Streamable HTTP sind mit --transport http und Auth-Header offiziell unterstützt; Server mit OAuth autorisieren Sie über /mcp im Browser. Gehostete Endpunkte wie der AFFiNE-Workspace verbinden sich ohne lokalen Prozess, den man pflegen müsste.
Warum erscheint mein Server nicht in der Liste?
Erst den Status mit /mcp prüfen, dann die üblichen Verdächtigen: fehlendes --transport http bei einem Remote-Server, fehlerhafter Authorization-Header, abgelaufene Zugangsdaten oder ein Scope-Irrtum (local existiert nur im Projekt, in dem es angelegt wurde). Diese vier erklären fast alle Fälle.
Wie viele MCP Server sind sinnvoll?
So viele, wie Sie tatsächlich nutzen: Jeder verbundene Server lädt seine Tool-Beschreibungen in den Kontext und konkurriert dort um die Aufmerksamkeit des Modells. In der Praxis hat sich eine Handvoll bewährt — mit dem einen Server starten, der die tägliche Frage beantwortet, und erst bei echtem Bedarf ergänzen; /mcp zeigt jederzeit, was gerade verbunden ist.
Kostet MCP in Claude etwas?
Die MCP-Unterstützung ist in Claude Code und Claude Desktop ohne Aufpreis enthalten, das Protokoll ist ein offener Standard. Die Konditionen einzelner Server variieren; der eingebaute Server von AFFiNE etwa ist auf Cloud wie auf selbst gehosteten Instanzen mit aktivierten KI-Funktionen kostenlos.
Fazit
Nach dem ersten Server sitzt der Ablauf — er ist bei jedem weiteren derselbe. Am meisten bringt der Anfang dort, wo Sie ohnehin täglich nach Antworten suchen: im eigenen Workspace.