Einstellungen, Sicherheitsprüfungen und Connector-Anleitungen genügen, um den MCP-Server zu betreiben. Für einen stabilen Produktivbetrieb kommen die Themen dieser Seite hinzu. Keines davon erzwingt der Code. Wird eines übersehen, zeigt sich das meist nicht als lauter Fehler, sondern als stiller Ausfall. Session-Daten gehen verloren, Tokens veralten, im Audit-Log entstehen Lücken.

HTTPS-Erkennung. Die MCP-Middleware akzeptiert neben dem Schema der Anfrage auch den Header X-Forwarded-Proto: https. Terminiert dein CDN oder Load Balancer TLS und leitet unverschlüsselt an den Origin weiter, muss der Proxy diesen Header setzen.

Vertrauensgrenze der HTTPS-Prüfung. Dieser Header wird von jeder Gegenstelle akzeptiert, die HTTPS-Prüfung zieht mcpTrustedProxies nicht zu Rate. Diese Einstellung regelt nur die IP-Auflösung im Audit-Log. Ein Client, der direkt auf den Origin zugreift und selbst X-Forwarded-Proto: https sendet, umgeht die Prüfung also. Sorge dafür, dass dein Proxy den Header aus eingehendem Verkehr entfernt, bevor er ihn selbst setzt, oder erlaube den Zugriff auf den Origin nur den Proxy-IPs, per Firewall oder VPC.

Client-IP im Audit-Log. OAuth-Ereignisse protokollieren die aufgelöste Client-IP. Standardmäßig ist das die IP der direkten Gegenstelle, hinter einem Proxy also die des Proxys und nicht die des Benutzers. Trägst du deine Proxy-IPs oder CIDR-Bereiche in mcpTrustedProxies ein, wird die Kette in X-Forwarded-For von rechts durchlaufen, vertraute Zwischenstationen werden übersprungen und die erste nicht vertraute Adresse protokolliert. Bleibt die Einstellung leer, wird der Header vollständig ignoriert. Damit kann sich niemand durch einen selbst gesetzten Header eine falsche IP ins Audit-Log schreiben.

Apache mit mod_php oder FCGI. Der MCP-Endpoint braucht den Authorization-Header, und Apache verwirft ihn ohne die passende Rewrite-Regel, bevor PHP ihn sieht. Die Token-Endpunkte funktionieren dann weiter, weil sie den Body auswerten, der MCP-Endpoint antwortet aber dauerhaft mit 401. Diese Regeln müssen entsprechend in der .htaccess-Datei vorhanden sein.

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]

Nginx mit php-fpm. Hier gehört die Entsprechung in den PHP-Location-Block.

location ~ \.php$ {
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
    # ... bestehendes include der fastcgi_params
}

Setze außerdem client_max_body_size mindestens auf die MCP-Grenze von 1 MB plus Reserve für Batch-Anfragen. 8m ist ein sicherer Wert.

Staging-Umgebungen, interne Instanzen und noch nicht veröffentlichte Seiten stehen oft hinter HTTP Basic Auth. Das kollidiert mit dem MCP-Server, denn beide nutzen denselben Header. Basic Auth sendet Authorization: Basic ..., der MCP-Endpoint erwartet Authorization: Bearer .... Eine Anfrage kann nur einen dieser Header tragen. Ein Connector hinter Basic Auth scheitert deshalb mit 401, noch bevor PHP läuft. Im MCP-Log steht dann nichts, weil die Anfrage die Middleware nie erreicht.

Betrieb hinter Basic Auth ist möglich, die MCP-Pfade müssen aber ausgenommen werden. Deren Schutz übernimmt dann die eigene OAuth- und Bearer-Token-Prüfung des Servers. Ohne Basic Auth erreichbar sein müssen:

• /.well-known/oauth-authorization-server und /.well-known/oauth-protected-resource für die OAuth-Erkennung. Der Client ruft diese Pfade zuerst auf.
• /aisuite-mcp/oauth/* für den OAuth-Ablauf. Die Anmeldung unter /aisuite-mcp/oauth/authorize ist die TYPO3-Backend-Anmeldung selbst und darf nicht von Basic Auth verdeckt werden.
• /aisuite-mcp samt Unterpfaden, also der Endpoint selbst. Jedes Token ist an einen konkreten Backend-Benutzer mit durchgesetzten Rechten gebunden.

1. Auf THE_REQUEST prüfen, nicht auf Request_URI. In TYPO3 schreibt der Front-Controller die Anfrage auf index.php um, bevor die Autorisierungsphase läuft. Eine Bedingung auf Request_URI sieht den ursprünglichen Pfad also nicht mehr und greift stillschweigend nicht. %{THE_REQUEST} ist die unveränderte Anfragezeile und übersteht interne Rewrites.

Ergänze in der .htaccess im Web-Root deine bestehende Basic-Auth-Konfiguration um einen RequireAny-Block und ersetze dabei die bisherige Zeile Require valid-user.

AuthType Basic
AuthName "Restricted"
AuthUserFile /pfad/zu/.htpasswd

<RequireAny>
    Require expr %{THE_REQUEST} =~ m#\s/\.well-known/oauth-#
    Require expr %{THE_REQUEST} =~ m#\s/aisuite-mcp#
    Require valid-user
</RequireAny>

Eine Anfrage auf einen MCP-Pfad trifft eine der Require expr-Zeilen und kommt ohne Basic Auth durch, alles andere fällt auf Require valid-user zurück. Verwende dabei kein <Location> oder <LocationMatch>. Diese Direktiven sind nur in der Server- oder vHost-Konfiguration erlaubt und führen in einer .htaccess zu einem 500.

2. Prüfen. Der Rest der Seite bleibt hinter Basic Auth, nur die MCP-Oberfläche ist offen und dort durch OAuth geschützt. Alle drei Aufrufe müssen 200 und JSON liefern.

curl -i [host]/.well-known/oauth-protected-resource
curl -i [host]/.well-known/oauth-authorization-server
curl -i [host]/aisuite-mcp/health

Ein 403 bedeutet, dass noch eine Sperre über eine Umgebungsvariable oder eine hostseitige Blockade von Punkt-Pfaden greift. Ein 401 mit WWW-Authenticate: Basic bedeutet, dass die Ausnahme aus Schritt 1 nicht passt, dann prüfe, ob sie wirklich auf THE_REQUEST prüft. Und ohne die Rewrite-Regel für den Authorization-Header antwortet der Endpoint mit 401, obwohl Erkennung und OAuth-Ablauf funktionieren.

PHP-Laufzeit. Die Erweiterung ist auf den klassischen Ablauf von PHP-FPM beziehungsweise mod_php ausgelegt, also einen Prozess pro Anfrage. Ein prozessinterner Cache für lesbare Seiten-IDs geht davon aus, dass der Prozess mit der Anfrage endet.

Mehrere Knoten und Load Balancing. Die Transport-Sessions unter var/aisuite_mcp_sessions/ und die Ergebnisse der Hintergrund-Tasks unter var/mcp_tasks/ liegen im lokalen Dateisystem. Bei mehreren Applikationsknoten brauchst du daher entweder Sticky Sessions, damit ein Client immer auf demselben Knoten landet, oder ein gemeinsames Dateisystem für diese beiden Verzeichnisse. Der OAuth-Zustand selbst liegt in der Datenbank und ist automatisch geteilt.

Die MCP-Tools, die externe KI-Anbieter aufrufen, nutzen die Netzwerkkonfiguration der AI Suite. Ausgehende HTTPS-Verbindungen werden benötigt zum konfigurierten AI Suite Server.

In abgeschotteten Umgebungen mit strenger Firewall gib genau diesen Host frei, der in deinen AI Suite-Einstellungen tatsächlich konfiguriert ist. Der MCP-Endpoint selbst bringt keine weiteren ausgehenden Ziele mit, als die AI Suite ohnehin nutzt.

Zur laufenden Wartung siehe CLI-Befehle, zu Logging und Aufbewahrung Sicherheit & Betrieb.