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).

• 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.

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

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "[typo3-url]/aisuite-mcp",
        "--header",
        "Authorization: Bearer [token]"
      ]
    }
  }
}

Why a command and not a URL? The claude_desktop_config.json accepts stdio servers only, which means command, args and env. An entry with url and headers makes Claude Desktop report the MCP servers as misconfigured. The mcp-remote bridge therefore runs locally and forwards to the HTTP endpoint with the bearer token attached. It requires Node.js version 18 or newer on the machine that runs Claude Desktop. If you want to work without the bridge, there are two alternatives: the custom connector via OAuth (see below) and the local stdio transport.

2. Paste the snippet. Add the snippet to the Claude Desktop configuration file. Do not overwrite existing entries under mcpServers, merge into them. Then quit Claude Desktop completely and restart it (closing the window is not enough).

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

3. Verify the connection. Open a new conversation and the tools/connector menu below the input field. The AI Suite tools should appear under the server entry typo3-ai-suite (readServerInfo, listTables, readPageTree and so on). The tools have to be enabled per chat.

This is the most common stumbling block in local setups using DDEV or mkcert. mkcert -install writes the CA into the operating system trust store, which is enough for browsers and curl. Node.js ignores that store and ships its own CA bundle. The bridge therefore fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE even though the same URL answers with 200 in the browser.

The fix is an env block in the same server entry that points Node.js at the mkcert root. mkcert -CAROOT prints the directory.

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "[typo3-url]/aisuite-mcp", "--header", "Authorization: Bearer [token]"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "[mkcert -CAROOT]/rootCA.pem"
      }
    }
  }
}

Best check this outside Claude Desktop first:

NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" \
  node -e "require('https').get('[typo3-url]/aisuite-mcp/health', r => console.log(r.statusCode))"

This is exactly why a *.ddev.site host can seem unreachable to Claude Desktop. No tunnel through cloudflared or ngrok is needed, the bridge resolves local hostnames without trouble.

• Server missing from the tools list: The claude_desktop_config.json has a JSON syntax error or sits in the wrong path. Check the file (e.g. python -m json.tool) and compare the path against the list above.
• Claude Desktop reports the MCP servers as misconfigured: The server entry contains url, transport or headers instead of command and args. Older versions of the MCP dashboard emitted the HTTP form here. Create a new token to get the current snippet, or switch to the custom connector or the local stdio transport.
• npx: command not found, or the entry stays grey in the tools list: The mcp-remote bridge needs Node.js on the machine running Claude Desktop, and GUI applications start with a very short PATH. Install Node.js 18 or newer, or replace "npx" with its absolute path, for example /usr/local/bin/npx. Test the bridge by hand first.
• 401 or “Authentication required”: Token invalid, expired or revoked, or the URL contains a site prefix. Create a new token and use the root URL [typo3-url]/aisuite-mcp.
• SSL certificate errors such as UNABLE_TO_VERIFY_LEAF_SIGNATURE: Self-signed certificate. Running mkcert -install alone is not enough for the bridge, because Node.js ships its own CA bundle and ignores the OS trust store. See the section on self-signed certificates.
• Model reports “no MCP access”: The AI Suite tools are not enabled in the chat. Switch them on in the tools/connector menu.

General sources of error (Authorization header, empty tools list, disabled endpoint) are described under Security & Operation. The detailed guide is in the connector guide in the repository.

Claude Desktop can also reach a remote MCP server without any configuration file, through Settings, Connectors, Add custom connector. Enter the server URL [typo3-url]/aisuite-mcp there and confirm. Claude Desktop then runs the OAuth 2.1 flow against the MCP server, including dynamic client registration, and manages the tokens itself.

Two differences compared with the token route:

• No custom headers. The connector interface has no header field, so the static bearer token cannot be used here. Authentication is OAuth only, which is why mcpAllowedRedirectUris and mcpAllowedOrigins have to be filled in. The values are the same as for Claude.ai.
• No Node.js required, because nothing is launched locally.

The connection is still made from your machine, so localhost, *.ddev.site and internal hosts remain reachable.