Alle Beiträge
AFFiNE
Toeverything·Veröffentlicht 20. Aug. 2026 · Aktualisiert 21. Aug. 2026
Terminalfenster, über einen MCP-Anschluss mit einem Assistenten-Panel verbunden

MCP Server zu Claude Code hinzufügen: Setup und Fehlersuche

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:

claude mcp add --transport http <name> <server-url> \
  --header "Authorization: Bearer <token>"

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:

{
  "mcpServers": {
    "affine": {
      "type": "http",
      "url": "https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
      "headers": { "Authorization": "Bearer ${AFFINE_TOKEN}" }
    }
  }
}

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:

  1. 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.
  2. 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.
  3. Hinzufügen:
claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
  --header "Authorization: Bearer <token>"
  1. 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.

Client-Verbindung über lokalen oder entfernten Transport zu einem MCP-Server mit eingeschränkten Zugriffsrechten
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.