Clients verbinden
Jeder unterstützte KI-Client wird über den MCP-Endpoint deiner TYPO3-Installation angebunden. Die gemeinsamen Grundlagen sind hier zusammengefasst, die konkreten Schritte je Client findest du auf den jeweiligen Unterseiten. Ausführliche, stets aktuelle Schritt-für-Schritt-Anleitungen liegen zusätzlich im Repository unter Connectors/.
Zwei Dinge unterscheiden die Clients grundlegend, nämlich wie sie sich anmelden und von wo aus sie deinen Server erreichen. Clients, die in fremder Infrastruktur laufen, brauchen einen öffentlich erreichbaren Server mit anerkanntem Zertifikat. Lokale Clients kommen auch an interne Hosts und selbstsignierte Zertifikate heran.
| Client | Anmeldung | Erreichbarkeit |
|---|---|---|
| Claude Desktop | Statisches Token (Standard) oder OAuth 2.1 | Lokal, erreicht auch localhost, *.ddev.site und interne Hosts |
| Claude.ai | OAuth 2.1 mit dynamischer Registrierung | Nur öffentliches HTTPS, läuft bei Anthropic |
| ChatGPT | OAuth 2.1 mit dynamischer Registrierung | Nur öffentliches HTTPS, läuft bei OpenAI |
| Claude Code | Statisches Token, OAuth 2.1 oder stdio | Lokal, erreicht auch private Hosts |
| MCP Inspector | OAuth 2.1 über localhost:6274 | Lokales Debug-Werkzeug im Browser |
| Open WebUI | OAuth 2.1 mit dynamischer Registrierung | Dort, wo deine Open-WebUI-Instanz läuft |
Läuft TYPO3 auf demselben Rechner wie der Client, geht es auch ganz ohne HTTP, Token und OAuth, siehe Lokaler stdio-Transport.
Endpoint und Authentifizierung
Der MCP-Endpoint liegt immer an der Wurzel deiner Domain unter [deine-domain]/aisuite-mcp, ohne Site-Präfix. Eine URL mit Site-Präfix wird nicht erkannt und führt zu einem 404.
Voraussetzung ist, dass der Endpoint aktiviert ist (enableMcp, siehe Konfiguration) und der verwendete Backend-Benutzer das Recht enable_mcp_access besitzt (siehe Berechtigungen & Scopes).
Für die Authentifizierung gibt es je nach Client zwei Wege, nämlich ein statisches Bearer-Token (z. B. Claude Desktop, Claude Code) oder den OAuth-2.1-Flow (z. B. Claude.ai, ChatGPT, Open WebUI, MCP Inspector). Lokale Clients erreichen auch interne Hosts, die Cloud-Dienste Claude.ai und ChatGPT benötigen eine öffentlich per HTTPS erreichbare Installation.
Callback-URLs für OAuth
Für Clients mit OAuth-Flow müssen die passende Redirect-URI und gegebenenfalls die Browser-Origin in der Extension-Konfiguration hinterlegt werden (mcpAllowedRedirectUris und mcpAllowedOrigins). Redirect-URIs werden per Präfix verglichen, localhost ist immer erlaubt. In einer Entwicklungsumgebung ist eine leere Allowlist offen, in der Produktion restriktiv.
| Client | Redirect-URI | Origin |
|---|---|---|
| Claude.ai / Claude Desktop (Remote-Connector) | claude.ai/api/mcp/auth_callback | claude.ai |
| ChatGPT | chatgpt.com/connector_platform_oauth_redirect | chatgpt.com |
| MCP Inspector | localhost/oauth/callback und localhost/oauth/callback/debug | localhost |
| Claude Code (CLI) | http://localhost:[Port]/callback, durch die localhost-Ausnahme abgedeckt, kein Eintrag nötig | kein Browser |
| Open WebUI | [dein-openwebui-host]/oauth/, deckt als Präfix sowohl /oauth/clients/ als auch /oauth/oidc/callback ab. Welche URI deine Version sendet, zeigt das Log beim Registrieren | [dein-openwebui-host] |
Häufige Stolpersteine
- Site-Präfix in der URL: Der Endpoint wird nur an der Domain-Wurzel erkannt. Lege den Connector immer mit der Root-URL
[deine-domain]/aisuite-mcpan, nicht mit einer Sprach- oder Präfix-URL. - Fehlendes
enable_mcp_access: Der Client verbindet sich, aber alle Tool-Aufrufe werden abgewiesen oder die Tool-Liste bleibt leer. - Endpoint deaktiviert: Bei
enableMcp = 0antwortet der Endpoint mit 404. Authorization-Header: Bei Apache (mod_php/FCGI) oder hinter einer HTTP-Basic-Auth kann der Authorization-Header verloren gehen, dann scheitert die Anmeldung mit 401. Die nötigen.htaccess-Anpassungen sind unter Produktivbetrieb beschrieben.- Fehlermeldung zum
state-Parameter: Meldet der Server, derstate-Parameter müsse mindestens 32 Zeichen lang sein, verwendet der Client einen kürzeren Wert. Betroffen sind alle OAuth-Clients, deren Standardlänge unter 32 Zeichen liegt. Die Mindestlänge stammt aus einer historischen Vorgabe und lässt sich im Autorisierungs-Endpoint auf 22 Zeichen senken, was der aktuellen OAuth-2.1-Empfehlung entspricht. - Fehler zum
RateLimiter-Konstruktor: Meldet PHP zu wenige Argumente fürRateLimiter::__construct, ist der Cache des Dependency-Injection-Containers nach einem Code-Update veraltet. TYPO3-Caches und den DI-Container leeren. - Kein Eintrag im MCP-Log: Verhält sich der Connector auffällig, steht aber nichts in
var/log/aisuite_mcp.log, hat die Anfrage die MCP-Middleware nie erreicht. Dann hilft das Access-Log des Webservers. Typische Ursachen sind ein Site-Präfix in der URL,enableMcp = 0oder eine Abweisung durch TLS beziehungsweise Firewall. - Lizenzfehler beim Tool-Aufruf: Ein Tool ist sichtbar, sein Aufruf endet aber mit einem Lizenzfehler. Dann fehlt der gültige API-Key der AI Suite, oder das Lizenzpaket deckt die Funktion nicht ab. Das ist etwas anderes als ein fehlendes Feature-Recht. Ein fehlendes Recht entfernt das Tool bereits aus der Tool-Liste, das Model sieht es also nie. Bleibt ein Tool sichtbar und scheitert erst beim Aufruf, ist die Lizenz zu prüfen und nicht die Backend-Gruppe.