Claude Code MCP einrichten: Server hinzufügen, verwalten

Um MCP in Claude Code einzurichten, führst du claude mcp add im Terminal aus. Ein lokaler Server ist claude mcp add <name> -- <befehl>, ein Remote-Server claude mcp add --transport http <name> <url>, und --scope legt fest, ob der Server nur für dich in diesem Projekt gilt (local, Standard), über eine .mcp.json für das ganze Team (project) oder für dich in jedem Projekt (user). Danach tippst du in einer Session /mcp, um die Verbindung zu prüfen und dich bei OAuth-Servern anzumelden.

Dieser Leitfaden geht jeden Schritt durch: Transports, den Trenner --, Umgebungsvariablen und Header, Scopes, .mcp.json von Hand schreiben, die Befehle list, get und remove, OAuth, den Import aus Claude Desktop, Timeouts und Output-Limits und was du prüfen solltest, bevor du den Servern eines Projekts vertraust. Die Befehle stammen aus Anthropics MCP-Dokumentation für Claude Code, Stand Oktober 2026. Ist MCP neu für dich, lies zuerst was ein MCP-Server ist; welche Server sich lohnen, steht in die besten MCP-Server fürs Programmieren.

Kurzreferenz

Kurze Flags gehen auch: -t für --transport, -s für --scope, -e für --env und -H für --header.

Transport wählen: stdio, HTTP oder SSE

Ein MCP-Server erreicht Claude Code auf einem von drei Wegen:

--transport sse brauchst du kaum noch. Seit Claude Code 2.1.265 versucht claude mcp add --transport http zuerst HTTP und wechselt von selbst zu SSE, wenn der Server kein HTTP annimmt. In älteren Versionen gibst du --transport sse ausdrücklich an.

Lokalen stdio-Server hinzufügen

Die Regel, über die die meisten stolpern: Die Optionen von Claude Code (--transport, --scope, --env) stehen vor dem Servernamen, und alles nach -- ist der Befehl des Servers und wird unverändert durchgereicht.

# Grundform
claude mcp add [optionen] <name> -- <befehl> [argumente...]

# Playwright, gestartet mit npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Ein Server, der einen API-Key in seiner Umgebung braucht
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Ohne -- würde ein Server-Flag wie --port 8080 als Option von Claude Code gelesen, und der Befehl schlägt fehl. Noch ein Haken aus der Doku: --env nimmt mehrere KEY=value-Paare an. Folgt der Servername direkt danach, wird er als weiteres Paar gelesen und abgelehnt. Setz eine andere Option wie --transport stdio dazwischen, wie im Beispiel oben.

Claude Code setzt CLAUDE_PROJECT_DIR in der Umgebung jedes stdio-Servers, damit ein Server das Projekt-Root findet, ohne vom Arbeitsverzeichnis abzuhängen.

Remote-HTTP-Server hinzufügen

Remote-Server bekommen statt eines Befehls eine URL. Header ergänzt du mit --header, wenn der Server einen API-Key oder ein Bearer-Token verlangt:

# Ein gehosteter Server mit OAuth-Anmeldung
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Ein Server mit statischem Token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Ein Header, den du hier eintippst, landet im Klartext in der Konfigurationsdatei. Für alles Geteilte sind OAuth oder eine ${VAR}-Referenz in der .mcp.json die bessere Wahl, mehr dazu unten.

Hast du schon eine JSON-Definition aus der README eines Servers, spar dir die Flags und füge sie mit add-json ein. Der Befehl nimmt das Objekt, das in mcpServers stehen würde, nicht die ganze Datei:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Scope wählen

Jedes claude mcp add schreibt in einen von drei Scopes:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Faustregel: Persönliche Tools und alles mit deinen eigenen Zugangsdaten gehört in user oder local; Server, die das ganze Team für die Arbeit am Repo braucht, gehören in project.

„Local“ meint hier übrigens nicht .claude/settings.local.json. Lokale MCP-Server liegen in ~/.claude.json in deinem Home-Verzeichnis.

Ist derselbe Name an mehreren Stellen definiert, nimmt Claude Code den obersten Eintrag und führt keine Felder zusammen: zuerst local, dann project, dann user, dann Plugin-Server, dann claude.ai-Connectors. Zeigen zwei Scopes mit demselben Namen auf unterschiedliche Endpunkte, warnen claude mcp list und /mcp dich.

.mcp.json von Hand schreiben

Ein Server mit Scope project ist einfach eine .mcp.json, die du bearbeiten und in Pull Requests reviewen kannst:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} wird zu einer Umgebungsvariable aufgelöst, ${VAR:-default} fällt auf einen Standardwert zurück. Das funktioniert in command, args, env, url und headers, und so committest du die Datei, ohne Tokens zu committen: Jede Entwicklerin und jeder Entwickler setzt API_KEY in der eigenen Shell. Fehlt eine Variable ohne Standardwert, warnen claude mcp list und /mcp und lassen den Text unaufgelöst.

Ein "timeout" pro Server in Millisekunden setzt ein festes Limit für die Tool-Aufrufe dieses Servers.

Server verwalten: list, get, remove und /mcp

In der Shell:

claude mcp list          # alle Server mit Verbindungsstatus
claude mcp get notion    # Details zu einem Server, auch warum er fehlschlug
claude mcp remove notion # aus seinem Scope löschen

list und get zeigen die Fehlerdetails mit geschwärzten Zugangsdaten. Ein Projekt-Server, den du noch nicht freigegeben hast, steht als ausstehend da, bis du claude interaktiv startest und zustimmst.

In einer Session ist /mcp die Schaltzentrale. Es zeigt Status und Anzahl der Tools jedes Servers, und im Menü eines Servers kannst du dich anmelden, neu anmelden, die Anmeldung löschen, neu verbinden oder den Server abschalten, ohne seine Konfiguration zu löschen. /mcp reconnect all versucht alle fehlgeschlagenen Server auf einmal neu (ab Claude Code 2.1.284).

Verbundene Server bringen mehr als Tools mit. Mit @ verweist du neben deinen Dateien auf Ressourcen eines Servers, und mit / siehst du seine Prompts als /servername:promptname (MCP). Die Tools selbst heißen mcp__<server>__<tool>; diesen Namen verwendest du in Berechtigungsregeln und in Hook-Matchern.

Bei OAuth-Servern anmelden

Viele gehostete Server wie Sentry, Notion oder Linear nutzen OAuth statt eines statischen Tokens. Füge den Server mit --transport http und ohne Header hinzu und melde dich dann an:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Führe in Claude Code /mcp aus, wähle den Server und dann Authenticate. Dein Browser öffnet sich, du meldest dich an, und Claude Code speichert das Token und erneuert es. Das geht auch aus der Shell, ohne eine Session zu öffnen:

claude mcp login sentry               # öffnet den Browser
claude mcp login sentry --no-browser  # gibt die URL aus, für SSH-Sessions
claude mcp logout sentry              # gespeicherte Zugangsdaten vergessen

Headless-Läufe (claude -p) können keine Anmeldung anzeigen, also melde dich vorher einmal interaktiv an. Manche Server brauchen einen festen Callback-Port oder eine vorab registrierte OAuth-App; dafür gibst du beim Hinzufügen --callback-port, --client-id und --client-secret an. Das Secret wird maskiert abgefragt oder in CI aus MCP_CLIENT_SECRET gelesen.

Server aus Claude Desktop importieren

Hast du Server schon in der Claude-Desktop-App eingerichtet, musst du sie nicht neu eintippen:

claude mcp add-from-claude-desktop

Ein Dialog lässt dich die zu importierenden Server auswählen. Stand Oktober 2026 funktioniert das nur unter macOS und in WSL. Mit --scope user importierst du in deine User-Konfiguration. Servernamen dürfen nur Buchstaben, Ziffern, Bindestriche und Unterstriche enthalten; ein Desktop-Server mit Leerzeichen im Namen wird übersprungen und gemeldet, und ein bereits vorhandener Name bekommt ein Suffix wie server_1.

Fehlerbehebung

Für lange Textergebnisse gibt es ein zweites Limit: Ein Ergebnis über 50.000 Zeichen wird in einer Datei gespeichert, statt direkt in den Kontext zu gehen.

Remote-Server, die mitten in der Session wegbrechen, werden bis zu fünfmal mit wachsendem Abstand neu versucht. stdio-Server werden nicht automatisch neu gestartet; ein abgestürzter lokaler Server braucht ein Reconnect über /mcp.

Der Kontext ist die andere Kostenstelle. Claude Code nutzt auf aktuellen Modellen standardmäßig Tool Search: Beim Start werden nur Tool-Namen und Server-Anweisungen geladen, die vollständigen Tool-Definitionen erst, wenn Claude sie braucht. Das hält eine lange Serverliste günstig, aber jeder Server ist eine weitere Stelle, die ausfallen oder missbraucht werden kann, also halte die Liste kurz. Für Skripte lädt --mcp-config <datei> zusätzliche Server für einen Lauf, und --strict-mcp-config sorgt dafür, dass Claude Code nur diese nutzt.

Sicherheit: Projekt-Server sind Code aus dem Repo

Eine .mcp.json im Repo kann jeden lokalen Befehl starten oder auf jede URL zeigen. Genau das macht sie für Teams nützlich, und genau deshalb geht Claude Code vorsichtig damit um:

• Erst die Freigabe. In einer interaktiven Session fragt Claude Code, bevor es Server mit Scope project nutzt. claude mcp reset-project-choices setzt deine bisherigen Antworten zurück.
• Ein Repo kann sich nicht selbst freigeben. Einstellungen wie enableAllProjectMcpServers, die in die .claude/settings.json des Projekts committet sind, werden ignoriert, bis du dem Ordner vertraust, und der Server bleibt ausstehend. Freigaben aus deinen eigenen User-Einstellungen gelten weiterhin.
• Headless-Läufe fragen nicht. In claude -p und Agent-SDK-Läufen gibt es keine Rückfrage, also laden Projekt-Server ohne. Um einen Server in jedem Modus zu sperren, trag ihn in disabledMcpjsonServers ein.
• Zugangsdaten bleiben zu Hause. In url und headers eines Remote-Servers werden sensible Variablen wie ANTHROPIC_API_KEY leer aufgelöst, selbst wenn sie gesetzt sind. So kann ein Projekt deinen Anthropic-Key nicht still an seinen Server schicken.
• Trau dem, was ein Server zurückgibt, so wenig wie dem, was er ausführt. Anthropics Doku warnt, dass Server, die fremde Inhalte abrufen, dich für Prompt Injection angreifbar machen können. Bevorzuge Read-only-Modi und eng begrenzte Tokens.

Lies vor der Freigabe command, args und url jedes Servers so, wie du ein postinstall-Skript lesen würdest. Das größere Bild findest du unter Sicherheit von KI-Coding-Agenten.

Wenn du mehr als Claude Code nutzt

Alles oben gilt pro CLI. Codex hält seine Server in ~/.codex/config.toml, Gemini CLI in einer eigenen settings.json, und jedes Tool hat eigene Befehle. Ist Claude Code dein einziger Agent, reichen claude mcp add und eine committete .mcp.json völlig aus, und nichts hier verlangt ein weiteres Tool.

Nutzt du mehrere Coding-CLIs, laufen die Listen auseinander. Genau dafür ist der MCP-Manager in AgentVera gedacht, der Desktop-App, die diesen Blog herausgibt:

• Einmal hinzugefügt, beim Start verbunden. Du registrierst stdio-, HTTP- und SSE-Server in AgentVera, und sie verbinden sich beim Start der Agenten: mit allen Agenten, mit ausgewählten, mit den Agenten einer Gruppe oder mit einer Team-Rolle. Claude Code, Codex und die anderen CLI-Agenten mit MCP-Unterstützung bekommen sie.
• Im Einklang mit der Konfiguration von Claude Code. Server aus den Einstellungen von Claude Code und Codex werden mit ihrem Zustand aufgelistet; du kannst sie in AgentVera importieren oder aus der CLI entfernen, und die Server von AgentVera lassen sich auch in die CLI-Einstellungen schreiben.
• Eine Anmeldung, keine Tokens in Dateien. Remote-Server laufen über das Gateway von AgentVera, du meldest dich einmal in der App bei einem OAuth-Server an, und die CLI des Agenten hält weder Header noch Token. Geheime Umgebungsvariablen und Header liegen im Schlüsselbund deines Betriebssystems.
• Kosten, die du siehst. Ein Verbindungstest listet Tools, Prompts und Ressourcen eines Servers mit ungefähren Token-Kosten pro Tool.

Fazit

Fang mit einem Server an, den du wirklich brauchst, hinzugefügt mit claude mcp add im engsten Scope, der funktioniert. Prüf ihn mit claude mcp list oder /mcp, melde dich mit /mcp oder claude mcp login an und verschieb ihn erst dann in eine committete .mcp.json, wenn das ganze Team ihn braucht, mit Tokens in ${VAR}-Referenzen. Wenn etwas hakt, lösen claude mcp get, MCP_TIMEOUT und MAX_MCP_OUTPUT_TOKENS das meiste.

Mehr dazu:

• Was ist ein MCP-Server?
• Die besten MCP-Server für Coding-Agenten
• MCP-Manager
• Claude Code als Agent