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. Menüs, Tarife und Dialoge der Clients ändern sich häufig. Die Unterseiten beschreiben deshalb nur die Schritte, die TYPO3 betreffen, und verlinken für die Bedienung des Clients auf die Anleitung des Herstellers. 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), OAuth 2.1 oder stdio | Über mcp-remote oder stdio lokal, erreicht auch localhost, *.ddev.site und interne Hosts. Als eigener Connector nur öffentliches HTTPS, läuft bei Anthropic |
| Claude.ai | OAuth 2.1 mit dynamischer Client-Registrierung (Dynamic Client Registration) | Nur öffentliches HTTPS, läuft bei Anthropic |
| ChatGPT | OAuth 2.1 mit dynamischer Client-Registrierung | Nur öffentliches HTTPS, läuft bei OpenAI |
| Claude Code | Statisches Token, OAuth 2.1 oder stdio | Lokal, erreicht auch private Hosts |
| MCP Inspector | Statisches Token oder OAuth 2.1 über 127.0.0.1:6274 | Lokales Debug-Werkzeug im Browser |
| Open WebUI | OAuth 2.1 mit dynamischer Client-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 [typo3-url]/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 MCP-Zugriff aktivieren (Enable MCP Access, 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, MCP Inspector) oder den OAuth-2.1-Flow (z. B. Claude.ai, ChatGPT, Open WebUI, MCP Inspector).
Seit Version 0.9.0 unterstützt der Server die MCP-Revision 2026-07-28 neben den älteren Protokoll-Revisionen. Damit verbinden sich auch Connectors, die zuvor scheiterten. Eine Anfrage ohne Authentifizierung erhält jetzt eine 401-Antwort mit dem Hinweis auf die OAuth-Discovery statt einer 400.
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, 127.0.0.1 und [::1] sind immer erlaubt. In einer Entwicklungsumgebung ist eine leere Allowlist offen, in der Produktion restriktiv.
| Client | Redirect-URI | Origin |
|---|---|---|
| Claude mit eigenem Connector (Web, Desktop, Mobile und Cowork) | claude.ai/api/mcp/auth_callback | claude.ai |
| ChatGPT | chatgpt.com/connector_platform_oauth_redirect. ChatGPT nutzt diese feste Adresse, weil AI Suite MCP den iss-Parameter nach RFC 9207 liefert. | chatgpt.com |
| MCP Inspector | 127.0.0.1/oauth/callback, durch die localhost-Ausnahme abgedeckt, kein Eintrag nötig | 127.0.0.1, ebenfalls ausgenommen |
| Claude Code (CLI) | http://localhost:[port]/callback, durch die localhost-Ausnahme abgedeckt, kein Eintrag nötig | kein Browser |
| Open WebUI | [openwebui-url]/oauth/clients/, deckt als Präfix die Callback-Adresse [openwebui-url]/oauth/clients/[connection-id]/callback ab. WEBUI_URL muss dazu auf die öffentliche Adresse von Open WebUI gesetzt sein | [openwebui-url] |
Häufige Stolpersteine
- Site-Präfix in der URL: Der Endpoint wird nur an der Domain-Wurzel erkannt. Lege den Connector immer mit der Wurzel-URL
[typo3-url]/aisuite-mcpan, nicht mit einer Sprach- oder Präfix-URL. - Fehlendes
enable_mcp_access: Die OAuth-Anmeldung endet mit einer Zugriffsverweigerung, Anfragen mit statischem Token werden mit 403 (access_denied) abgewiesen. Fehlen dagegen einzelne Tools in der Tool-Liste, fehlt das zugehörige Feature-Recht. - 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, der state-Parameter müsse mindestens 32 Zeichen lang sein, läuft eine veraltete Version der Extension. Aktuelle Versionen akzeptieren ab 22 Zeichen (OAuth-2.1-Empfehlung). Aktualisiere die Extension.
- Kein Eintrag im MCP-Log: Verhält sich der Connector auffällig, steht aber nichts in
var/log/aisuite_mcp.log(bei aktivemmcpLogVerbose, Standard), 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 Modell sieht es also nie. Bleibt ein Tool sichtbar und scheitert erst beim Aufruf, ist die Lizenz zu prüfen und nicht die Backend-Gruppe.