Settings, security checks, and connector instructions are sufficient to operate the MCP server. For stable production operation, the topics of this page are added. None of these are enforced by the code. If one is overlooked, it usually does not manifest as a loud error, but as a silent failure. Session data is lost, tokens become outdated, and gaps appear in the audit log.

HTTPS Detection. The MCP middleware accepts not only the request schema but also the header X-Forwarded-Proto: https. If your CDN or load balancer terminates TLS and forwards unencrypted to the origin, the proxy must set this header.

Trust Boundary of HTTPS Check. This header is accepted by every counterpart; the HTTPS check does not consider mcpTrustedProxies. This setting only regulates the IP resolution in the audit log. A client that accesses the origin directly and sends X-Forwarded-Proto: https itself bypasses the check. Ensure that your proxy removes the header from incoming traffic before setting it itself, or allow access to the origin only from proxy IPs, via firewall or VPC.

Client IP in the Audit Log. OAuth events log the resolved client IP. By default, this is the IP of the direct counterpart, so behind a proxy, it is that of the proxy and not the user’s. If you enter your proxy IPs or CIDR ranges in mcpTrustedProxies, the chain in X-Forwarded-For is traversed from the right, trusted intermediaries are skipped, and the first untrusted address is logged. If the setting is left empty, the header is completely ignored. This way, no one can write a false IP into the audit log through a self-set header.

Apache with mod_php or FCGI. The MCP endpoint needs the Authorization header, and Apache discards it without the appropriate rewrite rule before PHP sees it. The token endpoints continue to work because they evaluate the body, but the MCP endpoint permanently responds with 401. These rules must be present in the .htaccess file.

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

Nginx with php-fpm. Here, the equivalent belongs in the PHP location block.

location ~ .php$ {    fastcgi_param HTTP_AUTHORIZATION $http_authorization;    # ... existing include of fastcgi_params}

Also set client_max_body_size to at least the MCP limit of 1 MB plus reserve for batch requests. 8m is a safe value.

Staging environments, internal instances, and unpublished pages are often behind HTTP Basic Auth. This conflicts with the MCP server, as both use the same header. Basic Auth sends Authorization: Basic ..., while the MCP endpoint expects Authorization: Bearer .... A request can only carry one of these headers. A connector behind Basic Auth therefore fails with 401 before PHP runs. The MCP log will show nothing because the request never reaches the middleware.

Operation behind Basic Auth is possible, but the MCP paths must be excluded. Their protection is then taken over by the server's own OAuth and Bearer token check. The following must be accessible without Basic Auth:

• /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource for OAuth detection. The client calls these paths first.
• /aisuite-mcp/oauth/* for the OAuth flow. The login at /aisuite-mcp/oauth/authorize is the TYPO3 backend login itself and must not be obscured by Basic Auth.
• /aisuite-mcp along with subpaths, i.e., the endpoint itself. Each token is tied to a specific backend user with enforced rights.

1. Check THE_REQUEST, not Request_URI. In TYPO3, the front controller rewrites the request to index.php before the authorization phase runs. A condition on Request_URI therefore no longer sees the original path and silently does not apply. %{THE_REQUEST} is the unchanged request line and survives internal rewrites.

In the .htaccess in the web root, add your existing Basic Auth configuration with a RequireAny block and replace the previous line Require valid-user.

AuthType BasicAuthName "Restricted"AuthUserFile /path/to/.htpasswd<RequireAny>    Require expr %{THE_REQUEST} =~ m#s/.well-known/oauth-#    Require expr %{THE_REQUEST} =~ m#s/aisuite-mcp#    Require valid-user</RequireAny>

A request to an MCP path hits one of the Require expr lines and passes without Basic Auth; everything else falls back to Require valid-user. Do not use <Location> or <LocationMatch>. These directives are only allowed in the server or vHost configuration and will lead to a 500 in a .htaccess.

2. Check. The rest of the page remains behind Basic Auth; only the MCP interface is open and protected by OAuth. All three calls must return 200 and JSON.

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

A 403 means that a block via an environment variable or a host-side blockade of point paths is still in effect. A 401 with WWW-Authenticate: Basic means that the exception from step 1 does not fit; then check if it really checks against THE_REQUEST. And without the rewrite rule for the Authorization header, the endpoint responds with 401, even though detection and OAuth flow work.

PHP Runtime. The extension is designed for the classic flow of PHP-FPM or mod_php, i.e., one process per request. An internal process cache for readable page IDs assumes that the process ends with the request.

Multiple Nodes and Load Balancing. The transport sessions under var/aisuite_mcp_sessions/ and the results of background tasks under var/mcp_tasks/ reside in the local file system. Therefore, with multiple application nodes, you need either sticky sessions so that a client always lands on the same node, or a shared file system for these two directories. The OAuth state itself is in the database and is automatically shared.

The MCP tools that call external AI providers use the network configuration of the AI Suite. Outgoing HTTPS connections are required to the configured AI Suite server.

In isolated environments with strict firewalls, only allow this host that is actually configured in your AI Suite settings. The MCP endpoint itself does not bring any additional outgoing targets other than those already used by the AI Suite.

For ongoing maintenance, see CLI Commands, for logging and retention Security & Operation.