Skip to main content Skip to page footer

Claude Desktop

Claude Desktop runs locally on macOS, Windows, or Linux. The connection to the MCP server is established from your computer, not from Anthropics infrastructure. Therefore, the MCP server does not need to be publicly accessible. Localhost, *.ddev.site, internal DNS names, and self-signed certificates work as long as your operating system trusts the issuing CA.

For authentication, a static bearer token generated in the AI Suite backend is recommended for Claude Desktop. This is the easiest way and does not require OAuth setup. Alternatively, the OAuth flow is possible (identical to Claude.ai). If TYPO3 is running on the same machine, there is also a local stdio mode (see full guide).

Requirements

  • enableMcp is enabled (see Configuration).
  • mcpAllowHttp only set to 1 if the TYPO3 URL is pure HTTP (local development without TLS). In production, the value remains 0.
  • The backend group has enable_mcp_access and the required feature rights (see Permissions & Scopes).
  • The TYPO3 host is reachable from your computer. A call to [typo3-url]/aisuite-mcp/health must return 200. For self-signed certificates (e.g., DDEV), the CA must be installed in the system (mkcert -install).
  • Claude Desktop is installed. Local MCP servers also work in the free plan.

Set Up Connection

1. Create Token. Open the AI Suite backend module, go to the MCP tab, and click on Create Token. A token bound to your backend user will be generated with all scopes you are authorized for. Copy the provided claude_desktop_config.json snippet. The validity is controlled by mcpTokenLifetimeDays (default 30).

{  "mcpServers": {    "typo3-ai-suite": {      "url": "[typo3-url]/aisuite-mcp",      "transport": "http",      "headers": {        "Authorization": "Bearer [token]"      }    }  }}

2. Insert Snippet. Enter the snippet into the configuration file of Claude Desktop. Do not overwrite existing entries under mcpServers, but add to them. Then completely close and restart Claude Desktop (just closing the window is not enough).

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%Claudeclaude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

3. Check Connection. Open a new conversation and the Tools-Connector menu under the input field. Under the server entry typo3-ai-suite, the AI Suite tools should appear (readServerInfo, listTables, readPageTree, etc.). The tools must be activated per chat.

Troubleshooting

  • Server missing in the tool list: The claude_desktop_config.json has a JSON syntax error or is in the wrong path. Check the file (e.g., python -m json.tool) and compare the path against the list above.
  • 401 or “Authentication required”: Token invalid, expired, or revoked, or the URL contains a site prefix. Regenerate the token and use the root URL [typo3-url]/aisuite-mcp.
  • SSL certificate error: Self-signed certificate whose CA is not recognized by your system. For DDEV, run mkcert -install once, otherwise import the CA into the system trust store.
  • Model reports “no MCP access”: The AI Suite tools are not activated in the chat. Enable them in the Tools-Connector menu.

Common sources of errors (Authorization header, empty tool list, disabled endpoint) are described under Security & Operation. The detailed guide is available in the Connector Guide in the repository.