Connecting Clients
Every supported AI client is connected via the MCP endpoint of your TYPO3 installation. The shared basics are summarized here, and you can find the specific steps for each client on the respective subpages. The clients' menus, plans and dialogs change frequently. The subpages therefore only describe the steps that concern TYPO3 and link to the vendor's guide for operating the client. Detailed, always up-to-date step-by-step guides are also available in the repository under Connectors/.
Two things fundamentally distinguish the clients: how they sign in and from where they reach your server. Clients that run on third-party infrastructure need a publicly reachable server with a trusted certificate. Local clients can also reach internal hosts and self-signed certificates.
| Client | Sign-in | Reachability |
|---|---|---|
| Claude Desktop | Static token (default), OAuth 2.1 or stdio | Via mcp-remote or stdio locally, also reaches localhost, *.ddev.site and internal hosts. As a custom connector only public HTTPS, runs at Anthropic |
| Claude.ai | OAuth 2.1 with Dynamic Client Registration | Only public HTTPS, runs at Anthropic |
| ChatGPT | OAuth 2.1 with Dynamic Client Registration | Only public HTTPS, runs at OpenAI |
| Claude Code | Static token, OAuth 2.1 or stdio | Local, also reaches private hosts |
| MCP Inspector | Static token or OAuth 2.1 via 127.0.0.1:6274 | Local debugging tool in the browser |
| Open WebUI | OAuth 2.1 with Dynamic Client Registration | Wherever your Open WebUI instance runs |
If TYPO3 runs on the same machine as the client, it also works entirely without HTTP, token and OAuth, see Local stdio transport.
Endpoint and authentication
The MCP endpoint is always located at the root of your domain under [typo3-url]/aisuite-mcp, without a site prefix. A URL with a site prefix is not recognized and leads to a 404.
The prerequisite is that the endpoint is enabled (enableMcp, see Configuration) and that the backend user in use has the permission Enable MCP Access (enable_mcp_access) (see Permissions & Scopes).
Depending on the client, there are two ways to authenticate: a static bearer token (e.g. Claude Desktop, Claude Code, MCP Inspector) or the OAuth 2.1 flow (e.g. Claude.ai, ChatGPT, Open WebUI, MCP Inspector).
Since version 0.9.0, the server supports MCP revision 2026-07-28 alongside the older protocol revisions. This means connectors that previously failed can now connect as well. An unauthenticated request now receives a 401 response with the hint to the OAuth discovery instead of a 400.
Callback URLs for OAuth
For clients with an OAuth flow, the matching redirect URI and, if needed, the browser origin must be stored in the extension configuration (mcpAllowedRedirectUris and mcpAllowedOrigins). Redirect URIs are compared by prefix, localhost, 127.0.0.1 and [::1] are always allowed. In a development environment, an empty allowlist is open, in production it is restrictive.
| Client | Redirect URI | Origin |
|---|---|---|
| Claude with a custom connector (web, desktop, mobile and Cowork) | claude.ai/api/mcp/auth_callback | claude.ai |
| ChatGPT | chatgpt.com/connector_platform_oauth_redirect. ChatGPT uses this fixed address because AI Suite MCP returns the iss parameter according to RFC 9207. | chatgpt.com |
| MCP Inspector | 127.0.0.1/oauth/callback, covered by the localhost exception, no entry required | 127.0.0.1, also exempt |
| Claude Code (CLI) | http://localhost:[port]/callback, covered by the localhost exception, no entry required | no browser |
| Open WebUI | [openwebui-url]/oauth/clients/, as a prefix it covers the callback address [openwebui-url]/oauth/clients/[connection-id]/callback. For this, WEBUI_URL must be set to the public address of Open WebUI | [openwebui-url] |
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
[typo3-url]/aisuite-mcp, not with a language or prefix URL. - Missing
enable_mcp_access: The OAuth sign-in ends with an access denial, requests with a static token are rejected with 403 (access_denied). If individual tools are missing from the tool list, the matching feature permission is missing. - Endpoint disabled: With
enableMcp = 0, the endpoint responds with 404. - Authorization header: With Apache (mod_php/FCGI) or behind HTTP Basic Auth, the Authorization header can get lost, and the sign-in then fails with 401. The necessary .htaccess adjustments are described under Production Operation.
- Error message about the state parameter: If the server reports that the state parameter must be at least 32 characters long, an outdated version of the extension is running. Current versions accept 22 characters or more (OAuth 2.1 recommendation). Update the extension.
- No entry in the MCP log: If the connector behaves oddly but there is nothing in
var/log/aisuite_mcp.log(withmcpLogVerboseactive, the default), the request never reached the MCP middleware. The web server's access log helps in that case. Typical causes are a site prefix in the URL,enableMcp = 0or a rejection by TLS or a firewall. - License error on a tool call: A tool is visible, but calling it ends with a license error. In that case, 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 permission. A missing permission already removes the tool from the tool list, so the model never sees it. If a tool stays visible and only fails when called, check the license, not the backend group.