Claude Code

Claude Code ist Anthropics Agent für das Terminal und läuft lokal auf macOS, Windows oder Linux. Die Verbindung zum MCP-Server wird von deinem Rechner aus aufgebaut. Der Server muss also nicht öffentlich erreichbar sein. Es funktionieren localhost, *.ddev.site, interne DNS-Namen und selbstsignierte Zertifikate, solange dein Betriebssystem der ausstellenden CA vertraut.

Es gibt drei Wege, sich anzumelden:

• Weg A, statisches Token. Am einfachsten und ohne OAuth-Ablauf. Token im Backend-Modul „AI Suite“ oder per ai-suite-mcp:create-token (siehe CLI-Befehle) erzeugen, mit einem Befehl auf der Kommandozeile hinterlegen. Passend für CI, Skripte und Rechner ohne Oberfläche.
• Weg B, OAuth 2.1 mit localhost-Callback. Du stößt die Anmeldung einmal in Claude Code an, danach führt Claude Code den OAuth-Ablauf im Browser über einen lokalen Callback-Port durch. Passend für Arbeitsplatzrechner, wenn Claude Code das Token selbst verwalten und automatisch erneuern soll.
• Weg C, lokaler stdio-Transport. Läuft TYPO3 auf demselben Rechner, brauchst du weder Token noch OAuth noch eine erreichbare URL. Siehe Lokaler stdio-Transport.

• enableMcp ist aktiviert (siehe Konfiguration).
• mcpAllowedRedirectUris ist nicht nötig. Claude Code nutzt http://localhost:[port]/callback, und localhost ist immer erlaubt.
• mcpAllowedOrigins ist nicht nötig, es findet kein browserseitiger Aufruf von fremder Herkunft statt.
• mcpAllowHttp setzt du nur dann auf 1, wenn deine TYPO3-URL reines HTTP ist und der Host weder localhost, 127.0.0.1, [::1] noch *.ddev.site ist. Diese Hosts sind ohnehin ausgenommen. Produktiv bleibt der Wert 0.
• Die Backend-Gruppe besitzt enable_mcp_access und die benötigten Feature-Rechte (siehe Berechtigungen & Scopes).
• Claude Code ist installiert, claude --version funktioniert.

Prüfe im selben Terminal, in dem du Claude Code startest, dass der Host erreichbar ist. Der Aufruf muss 200 liefern:

curl -sS [typo3-url]/aisuite-mcp/health

Bei einem selbstsignierten Zertifikat, etwa aus DDEV, muss die CA im Zertifikatsspeicher des Betriebssystems liegen (mkcert -install).

1. Token erstellen. Öffne im Backend-Modul „AI Suite“ den Reiter MCP und klicke auf Token erstellen. Das Token ist an deinen Backend-Benutzer gebunden und enthält alle Scopes, zu denen du berechtigt bist. Die Gültigkeit steuert mcpTokenLifetimeDays (Standard 30 Tage).

2. Server registrieren. Setze die eigene TYPO3-URL und das kopierte Token ein:

Ohne weitere Angabe gilt der Scope local: Der Server steht nur dir und nur im aktuellen Projektverzeichnis zur Verfügung. Mit --scope user gilt er für alle deine Projekte, mit --scope project landet er in der .mcp.json im Projektwurzelverzeichnis und wird mit dem Projekt geteilt. Einzelheiten zu den Scopes beschreibt die Anleitung von Anthropic zu MCP in Claude Code. Prüfen lässt sich das Ergebnis mit claude mcp list, dort muss typo3-ai-suite auftauchen.

Statt des Befehls kannst du auch das Claude-Code-Snippet, das das MCP-Dashboard neben dem Token anbietet, in die .mcp.json einfügen oder den Inhalt von typo3-ai-suite (ohne die Hülle mcpServers) mit claude mcp add-json typo3-ai-suite '<json>' übernehmen. Achtung: Der Transport-Schlüssel heißt hier type, nicht transport. Das Snippet aus dem MCP-Dashboard enthält das Token im Klartext. Liegt die .mcp.json in einem geteilten Projekt, ersetze das Token durch einen Verweis auf die Umgebungsvariable TYPO3_MCP_TOKEN und setze sie vor dem Start von Claude Code:

{
  "mcpServers": {
    "typo3-ai-suite": {
      "type": "http",
      "url": "[typo3-url]/aisuite-mcp",
      "headers": {
        "Authorization": "Bearer ${TYPO3_MCP_TOKEN}"
      }
    }
  }
}

Diese HTTP-Form ist für Claude Code gedacht. Wie du AI Suite MCP in der claude_desktop_config.json einbindest, beschreibt die Seite Claude Desktop.

Läuft das Token ab, erzeugst du ein neues und registrierst den Server erneut:

1. Server ohne Token registrieren. Ohne --header antwortet AI Suite MCP mit 401, und Claude Code bietet daraufhin die Anmeldung per OAuth an:

2. Anmelden. Rufe in einer laufenden Sitzung /mcp auf, wähle typo3-ai-suite und dann „Authenticate“. Alternativ meldest du dich auf der Kommandozeile mit claude mcp login typo3-ai-suite an. Claude Code registriert sich dabei unter [typo3-url]/aisuite-mcp/oauth/register, ruft im Browser die Autorisierungsseite auf und nimmt die Antwort über einen lokalen Callback auf localhost entgegen. Nach der TYPO3-Anmeldung und der Zustimmung zu den Scopes speichert Claude Code die Tokens selbst und erneuert sie automatisch. Abmelden kannst du dich mit claude mcp logout typo3-ai-suite. Einzelheiten beschreibt die Anleitung von Anthropic zu MCP in Claude Code.

3. Verbindung prüfen. In einer laufenden Sitzung zeigt /mcp alle konfigurierten Server samt Status, auf der Kommandozeile liefert claude mcp get typo3-ai-suite die Details. typo3-ai-suite sollte als verbunden erscheinen, und die Tools stehen dem Modell zur Verfügung.

Der Server erscheint in claude mcp list, aber jeder Aufruf endet mit 401 oder „Authentication required“ (Weg A). Das Token ist ungültig, abgelaufen oder widerrufen. Token neu ausstellen.

/mcp meldet 404. Die URL enthält ein Site-Präfix. Verwende die Wurzel-URL [typo3-url]/aisuite-mcp.

/mcp meldet für den Server einen Verbindungsfehler ohne weitere Angabe. Die Verbindung scheitert vor dem Protokoll-Handshake, in der Regel an TLS, DNS oder einem falschen Pfad. Details zur Konfiguration zeigt claude mcp get typo3-ai-suite. Prüfe curl [typo3-url]/aisuite-mcp/health im selben Terminal, bei selbstsignierten Zertifikaten mkcert -install ausführen.

Der Browser zeigt beim Redirect eine Zertifikatswarnung (Weg B). Die CA ist dem Browser nicht bekannt. CA auf Betriebssystemebene vertrauen und den Browser neu starten.

Für ein ausführliches Protokoll startest du Claude Code mit claude --debug-file <datei> und liest die Datei anschließend. Weitere Diagnosewege beschreibt die Anleitung von Anthropic zu MCP in Claude Code. Weitere clientunabhängige Fälle sind unter Clients verbinden gesammelt.