Connecting Clients
Every supported AI client is connected via the MCP endpoint of your TYPO3 installation. The common foundations are summarized here, and the specific steps for each client can be found on their respective subpages. Detailed, always up-to-date step-by-step instructions are also available in the repository under Connectors/.
Two things fundamentally differentiate the clients: how they log in and from where they reach your server. Clients running on foreign infrastructure need a publicly accessible server with a recognized certificate. Local clients can also access internal hosts and self-signed certificates.
| Client | Login | Accessibility |
|---|---|---|
| Claude Desktop | Static token (default) or OAuth 2.1 | Local, also reaches localhost, *.ddev.site and internal hosts |
| Claude.ai | OAuth 2.1 with dynamic registration | Only public HTTPS, runs at Anthropic |
| ChatGPT | OAuth 2.1 with dynamic registration | Only public HTTPS, runs at OpenAI |
| Claude Code | Static token, OAuth 2.1 or stdio | Local, also reaches private hosts |
| MCP Inspector | OAuth 2.1 via localhost:6274 | Local debugging tool in the browser |
| Open WebUI | OAuth 2.1 with dynamic registration | Where your Open-WebUI instance is running |
If TYPO3 runs on the same machine as the client, it can also work entirely without HTTP, tokens, and OAuth, see Local stdio transport.
Endpoint and Authentication
The MCP endpoint is always located at the root of your domain under [your-domain]/aisuite-mcp, without a site prefix. A URL with a site prefix will not be recognized and will lead to a 404.
The prerequisite is that the endpoint is activated (enableMcp, see Configuration) and the backend user used has the right enable_mcp_access (see Permissions & Scopes).
For authentication, there are two ways depending on the client: a static bearer token (e.g., Claude Desktop, Claude Code) or the OAuth 2.1 flow (e.g., Claude.ai, ChatGPT, Open WebUI, MCP Inspector). Local clients can also reach internal hosts, while the cloud services Claude.ai and ChatGPT require a publicly accessible installation via HTTPS.
Callback URLs for OAuth
For clients with OAuth flow, the appropriate redirect URI and possibly the browser origin must be stored in the extension configuration (mcpAllowedRedirectUris and mcpAllowedOrigins). Redirect URIs are compared by prefix, localhost is always allowed. In a development environment, an empty allowlist is open, while in production it is restrictive.
| 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 and localhost/oauth/callback/debug | localhost |
| Claude Code (CLI) | http://localhost:[Port]/callback, covered by the localhost exception, no entry needed | no browser |
| Open WebUI | [your-openwebui-host]/oauth/, covers both /oauth/clients/ and /oauth/oidc/callback as a prefix. The URI your version sends is shown in the log during registration | [your-openwebui-host] |
Common Pitfalls
- Site prefix in the URL: The endpoint is only recognized at the domain root. Always set up the connector with the root URL
[your-domain]/aisuite-mcp, not with a language or prefix URL. - Missing
enable_mcp_access: The client connects, but all tool calls are rejected or the tool list remains empty. - Endpoint disabled: With
enableMcp = 0, the endpoint responds with 404. Authorizationheader: With Apache (mod_php/FCGI) or behind HTTP Basic Auth, the Authorization header may be lost, causing the login to fail with 401. The necessary.htaccessadjustments are described under Production Operation.- Error message regarding the
stateparameter: If the server reports that thestateparameter must be at least 32 characters long, the client is using a shorter value. This affects all OAuth clients whose default length is below 32 characters. The minimum length comes from a historical requirement and can be reduced to 22 characters in the authorization endpoint, which corresponds to the current OAuth 2.1 recommendation. - Error with
RateLimiterconstructor: If PHP reports too few arguments forRateLimiter::__construct, the cache of the dependency injection container is outdated after a code update. Clear TYPO3 caches and the DI container. - No entry in the MCP log: If the connector behaves unusually but nothing is in
var/log/aisuite_mcp.log, the request never reached the MCP middleware. Then the access log of the web server helps. Typical causes are a site prefix in the URL,enableMcp = 0, or a rejection by TLS or firewall. - License error when calling the tool: A tool is visible, but its call ends with a license error. Then the valid API key of the AI Suite is missing, or the license package does not cover the function. This is different from a missing feature right. A missing right removes the tool from the tool list, so the model never sees it. If a tool remains visible and fails only upon calling, the license must be checked, not the backend group.