MCP-Server in Claude Code und Codex einrichten

Ein Coding-Agent im Terminal ist nur so gut wie das, worauf er zugreifen kann. Über das Model Context Protocol, kurz MCP, bekommen Claude Code und Codex zusätzliche Werkzeuge: einen Browser, den sie selbst bedienen, die aktuelle Doku einer Bibliothek, Dein Ticketsystem oder Deine Datenbank. Ein MCP-Server ist dabei ein kleines Programm oder ein Webdienst, der diese Werkzeuge in einer einheitlichen Form anbietet, sodass jeder Agent sie nutzen kann.

Das Einbinden ist in beiden Werkzeugen ein Einzeiler. Trotzdem scheitern viele am ersten Versuch: Der Server startet nicht, der API-Schlüssel kommt nicht an, die Anmeldung fehlt oder die Antwort ist zu groß. Diese Anleitung zeigt den sauberen Weg für Claude Code und Codex CLI, erklärt, wo die Konfiguration landet, und geht die häufigsten Fehler durch. Grundlage sind die offiziellen Seiten zu MCP in Claude Code und zu MCP in Codex, Stand November 2026.

Erst fragen: Brauchst Du überhaupt einen MCP-Server?

MCP ist nicht immer die beste Lösung. Beide Agenten können Befehle im Terminal ausführen. Für alles, wofür es ein gutes Kommandozeilenwerkzeug gibt, etwa gh für GitHub, psql für Postgres oder docker, reicht oft ein Satz in der CLAUDE.md oder AGENTS.md, der dem Agenten sagt, dass er dieses Werkzeug nutzen soll. Das spart Kontext, denn jeder MCP-Server belegt mit der Beschreibung seiner Werkzeuge Platz im Gedächtnis des Modells.

Ein MCP-Server lohnt sich, wenn es kein gutes CLI gibt, wenn ein Dienst eine Anmeldung per OAuth braucht oder wenn der Agent etwas tun soll, was im Terminal umständlich ist, zum Beispiel eine Webseite im Browser durchklicken. Faustregel: Nimm so wenige Server wie möglich und nur die, die Du wirklich nutzt.

Die zwei Arten von MCP-Servern

Lokale Server laufen als Programm auf Deinem Rechner. Der Agent startet sie selbst und spricht über die Standardein- und -ausgabe mit ihnen. Das nennt sich stdio. Typisch sind Server, die per npx oder uvx gestartet werden, etwa der Browser-Server Playwright.

Entfernte Server laufen beim Anbieter und werden über eine Adresse wie https://mcp.notion.com/mcp angesprochen. Das nennt sich http. Die Anmeldung läuft meist über OAuth im Browser. Die ältere Variante sse gilt in Claude Code als veraltet.

MCP-Server in Claude Code hinzufügen

Falls Claude Code noch nicht installiert ist, hilft Anleitung: Claude Code auf dem Mac installieren & nutzen.

Einen lokalen Server

Als Beispiel bindest Du den offiziellen Playwright-Server von Microsoft ein. Mit ihm kann Claude Code einen Browser steuern, Seiten öffnen, klicken und Screenshots machen. Wechsle in Deinen Projektordner und führe aus:

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

Entscheidend ist der doppelte Bindestrich --. Alles davor sind Optionen für Claude Code, alles danach ist der Befehl, mit dem der Server gestartet wird. Fehlt das --, versucht Claude Code die Optionen des Servers selbst zu verstehen und bricht ab.

Braucht ein Server einen API-Schlüssel, übergibst Du ihn mit --env. Achte darauf, dass zwischen --env und dem Namen des Servers noch eine andere Option steht, sonst liest Claude Code den Namen als weitere Variable:

claude mcp add --env AIRTABLE_API_KEY=DEIN_SCHLUESSEL --transport stdio airtable -- npx -y airtable-mcp-server

Einen entfernten Server

Entfernte Server fügst Du mit ihrer Adresse hinzu:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Starte danach Claude Code und tippe /mcp. Die Liste zeigt alle Server und ihren Zustand. Bei Notion steht zunächst, dass eine Anmeldung nötig ist. Wähle den Server aus, und Claude Code öffnet den Browser für die Anmeldung per OAuth. Danach ist der Server verbunden, und das Token wird sicher gespeichert.

Wo die Konfiguration landet

Claude Code kennt drei Geltungsbereiche, die Du mit --scope wählst:

Für Server, die Du überall brauchst, etwa Playwright, nimmst Du --scope user. Für Server, die das ganze Team in einem Repository nutzen soll, nimmst Du --scope project. Claude Code fragt beim ersten Start in einem Projekt nach, ob es die Server aus .mcp.json verwenden darf, weil eine fremde .mcp.json sonst beliebige Programme starten könnte.

API-Schlüssel nicht ins Repository schreiben

In einer geteilten .mcp.json haben Schlüssel nichts zu suchen. Claude Code ersetzt dort Variablen aus Deiner Umgebung. Die Schreibweise ${VAR} setzt den Wert der Variable ein, ${VAR:-standard} nimmt einen Ersatzwert, falls sie fehlt:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Jeder im Team setzt API_KEY dann in seiner eigenen Shell, etwa in der ~/.zshrc, und die Datei im Repository bleibt frei von Geheimnissen.

Server verwalten

Diese drei Befehle brauchst Du regelmäßig:

claude mcp list
claude mcp get playwright
claude mcp remove playwright

claude mcp list zeigt für jeden Server den Zustand: verbunden, Anmeldung nötig, Verbindung fehlgeschlagen oder Freigabe ausstehend. Das ist der erste Blick bei jedem Problem.

MCP-Server in Codex hinzufügen

Codex nutzt fast dieselbe Logik. Ein lokaler Server kommt ebenfalls mit -- hinter den Optionen:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Context7 liefert dem Agenten die aktuelle Dokumentation von Bibliotheken, damit er nicht mit veralteten Funktionsnamen arbeitet. Umgebungsvariablen übergibst Du mit --env VAR=WERT, ebenfalls vor dem --. Ob alles angekommen ist, zeigt:

codex mcp list

Anders als Claude Code speichert Codex alles in der Datei ~/.codex/config.toml. Jeder Server ist dort ein eigener Abschnitt. Du kannst ihn auch direkt von Hand anlegen:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120

Ein entfernter Server bekommt statt command eine url. Den Namen einer Umgebungsvariable mit dem Token trägst Du in bearer_token_env_var ein, dann landet der Schlüssel selbst nicht in der Datei:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Für Server mit OAuth meldest Du Dich mit codex mcp login <name> an. Einen Server, den Du gerade nicht brauchst, schaltest Du mit enabled = false ab, ohne ihn zu löschen.

Wenn Du Claude Code und Codex parallel nutzt, musst Du jeden Server in beiden Werkzeugen eintragen. Ein gemeinsames Format gibt es nicht. Wie Du wenigstens Skills in beiden Welten nutzt, zeigt Claude Code Skills in Codex nutzen.

Die häufigsten Fehler

„Failed to connect“ direkt nach dem Hinzufügen. Starte den Befehl hinter dem -- einmal von Hand im Terminal, also zum Beispiel npx @playwright/mcp@latest. Erscheint dort eine Fehlermeldung, liegt das Problem am Server und nicht am Agenten. Häufig fehlt Node.js oder uv, oder npx lädt beim ersten Start so lange herunter, dass der Agent aufgibt.

Der Server braucht zu lange zum Starten. Claude Code wartet standardmäßig nur kurz. Starte es mit längerer Wartezeit, der Wert ist in Millisekunden:

MCP_TIMEOUT=30000 claude

In Codex erhöhst Du startup_timeout_sec im Abschnitt des Servers. Der Standard dort sind 10 Sekunden.

Ein Werkzeug bricht mitten in der Arbeit ab. Das ist der Timeout für einzelne Aufrufe. In Codex setzt Du tool_timeout_sec hoch, Standard sind 60 Sekunden. In Claude Code gibst Du dem Server in der .mcp.json ein Feld "timeout" in Millisekunden.

„Needs authentication“ in der Liste. Der Server erwartet eine OAuth-Anmeldung. In Claude Code öffnest Du /mcp und wählst den Server, in Codex nutzt Du codex mcp login. Läuft die Anmeldung ab, wiederholst Du diesen Schritt.

Die Variable kommt nicht an. Steht in der .mcp.json ${API_KEY}, ist die Variable aber in Deiner Shell nicht gesetzt, lädt Claude Code den Server trotzdem und schickt den Text ${API_KEY} wörtlich mit. Die Fehlermeldung des Dienstes lautet dann meist „unauthorized“. Prüfe mit echo $API_KEY, ob die Variable gesetzt ist, und starte das Terminal nach Änderungen an der ~/.zshrc neu.

Warnung wegen zu großer Ausgabe. Claude Code warnt ab 10.000 Token Ausgabe eines Werkzeugs und schneidet standardmäßig bei 25.000 ab. Wenn ein Server legitimerweise viel liefert, etwa Datenbankabfragen, erhöhst Du die Grenze:

MAX_MCP_OUTPUT_TOKENS=50000 claude

Besser ist meist, den Agenten zu bitten, die Abfrage enger zu fassen.

Der Server taucht nach dem Hinzufügen nicht auf. Du hast ihn vermutlich in einem anderen Projektordner mit dem Standard-Scope local angelegt. local gilt nur für den Ordner, in dem Du den Befehl ausgeführt hast. Lege ihn mit --scope user neu an, wenn er überall verfügbar sein soll.

Sicherheit nicht vergessen

Ein MCP-Server läuft mit Deinen Rechten. Ein lokaler Server kann alles lesen, was Du lesen kannst, und ein entfernter Server sieht alles, was der Agent ihm schickt. Installiere deshalb nur Server aus offiziellen Quellen der jeweiligen Anbieter oder aus Repositories, die Du Dir angesehen hast. Gib Tokens nur die Rechte, die der Agent wirklich braucht, also lieber ein Token mit Lesezugriff als einen Administratorschlüssel. Und entferne Server, die Du nicht mehr nutzt: Vor dem Entfernen eines entfernten Servers in Claude Code meldest Du ihn mit claude mcp logout <name> ab. Das bloße Entfernen löscht das Token nur lokal, gültig bliebe es beim Anbieter trotzdem.