Claude Desktop

Claude Desktop runs locally on macOS, Windows or Linux. How your MCP server has to be reachable depends on the route. Via the mcp-remote bridge or the local stdio transport, your computer establishes the connection, not Anthropic's infrastructure. The MCP server then does not need to be publicly reachable. localhost, *.ddev.site, internal DNS names and self-signed certificates work as long as your operating system trusts the issuing CA. For the mcp-remote bridge, Node.js additionally needs the CA, see section on self-signed certificates. A custom connector (see below), on the other hand, runs through Anthropic's infrastructure just like Claude.ai and needs a server that is publicly reachable via HTTPS.

For authentication with Claude Desktop, a static bearer token generated in the AI Suite backend is recommended. This is the simplest way and requires no OAuth setup. Alternatively, the OAuth flow is possible (identical to Claude.ai). If TYPO3 runs on the same machine, there is also a local stdio mode, see Local stdio transport.

• enableMcp is enabled (see Configuration).
• Only set mcpAllowHttp to 1 if your TYPO3 URL is plain HTTP and the host is neither localhost, 127.0.0.1, [::1] nor *.ddev.site. These hosts are exempt anyway. In production, the value stays 0. For HTTP outside of localhost, the mcp-remote bridge additionally needs the --allow-http argument, see mcp-remote documentation.
• The backend group has enable_mcp_access and the required feature permissions (see Permissions & Scopes).
• The TYPO3 host is reachable from your computer. A call to [typo3-url]/aisuite-mcp/health must return 200. With a self-signed certificate (e.g. DDEV), add the CA to the system (mkcert -install) and set NODE_EXTRA_CA_CERTS for the bridge (see section on self-signed certificates).
• Claude Desktop is installed.

1. Create a token. In the backend module “AI Suite”, open 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 days).

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

The header value is stored in an environment variable because Claude Desktop on Windows splits arguments containing spaces. The snippet from the MCP dashboard still writes the header directly into args. Take the token from it, but use the notation above. Alternatively, mcp-remote reads the headers from a file with --header-file, see mcp-remote documentation.

Why a command and not a URL? The claude_desktop_config.json only accepts locally started stdio servers, i.e. command, args and env. Claude Desktop does not load an entry with url and headers and reports a configuration error instead. The mcp-remote bridge therefore runs locally and forwards to the HTTP endpoint with the bearer token attached. It needs a current LTS version of Node.js on the machine running Claude Desktop. If you want to work without the bridge, you have two alternatives: the custom connector via OAuth (see below) or the local transport, see Local stdio transport.

2. Paste the snippet. Add the snippet to the Claude Desktop configuration file claude_desktop_config.json. Where the file is located and how to open it from within Claude Desktop is described in the guide to local MCP servers in Claude Desktop. Back up the file first. Do not overwrite existing entries under mcpServers, add to them instead. Then quit Claude Desktop completely and restart it (closing the window is not enough).

3. Verify the connection. Open a new conversation and check in the connector selection at the input field whether the entry typo3-ai-suite appears with the AI Suite tools (readServerInfo, listTables, readPageTree etc.). The tools must be switched on per conversation.

This is the most common stumbling block in local environments with DDEV or mkcert. mkcert -install puts the CA into the operating system's certificate store, which is enough for browsers and curl. Node.js ignores this 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 solution is an additional entry in the env block of the same server entry that points Node.js to the mkcert root. mkcert -CAROOT tells you the directory.

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

Ideally, check this outside of 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 the cause when a *.ddev.site host seems unreachable for Claude Desktop. A tunnel via cloudflared or ngrok is not needed, the bridge resolves local host names without any problems.

• Server missing from 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 with the guide linked above.
• Claude Desktop reports an error in the MCP configuration: The server entry contains url, transport or headers instead of command and args. Older versions of the MCP dashboard output the HTTP form here. Create a new token and transfer it into the notation with env (see above), or switch to the custom connector or the local transport, see Local stdio transport.
• npx: command not found or the entry stays grey in the tool list: The mcp-remote bridge needs Node.js on the machine running Claude Desktop, and GUI programs start with a very short PATH. Install a current LTS version of Node.js system-wide so that it is in the system PATH, or replace "npx" with the absolute path, e.g. /usr/local/bin/npx. Test the bridge by hand first.
• 401 or “Authentication required”: Token invalid, expired or revoked. Create a new token.
• 404: The URL contains a site prefix. Use the root URL [typo3-url]/aisuite-mcp.
• SSL certificate errors such as UNABLE_TO_VERIFY_LEAF_SIGNATURE: Self-signed certificate. mkcert -install alone is not enough for the bridge, because Node.js ships its own CA bundle and ignores the system certificate store. See the section on self-signed certificates.
• Model reports “no MCP access”: The AI Suite tools are not switched on in the conversation. Switch them on in the connector selection at the input field.
• Narrowing down the cause: Claude Desktop writes a separate log for each MCP server. Where it is located is described in the guide to debugging MCP servers.

Further client-independent cases (Authorization header, missing tools, disabled endpoint) are collected under Connecting Clients. The detailed guide is in the connector guide in the repository.

Claude Desktop can also reach a remote MCP server without any configuration file, as a custom connector. Create a custom connector in Claude and enter [typo3-url]/aisuite-mcp as the URL. Under Authentication, choose “Sign in now” and under OAuth client “Register automatically”. The preselected option “Use Claude's published identity” requires Client ID Metadata Documents, which AI Suite MCP does not offer. Where to find this in your plan, who may create the connector in an organization and which fields the dialog shows is described in Anthropic's guide to custom connectors. 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:

• OAuth instead of headers. Claude offers custom request headers, which could be used to send the static bearer token, only to a limited extent, and a token stored there applies to all members of the organization (see Anthropic's guide linked above). Therefore, use OAuth. For this, mcpAllowedRedirectUris and mcpAllowedOrigins must be filled in. The values are the same as for Claude.ai.
• No Node.js required, because nothing is started locally.

Like Claude.ai, a custom connector runs through Anthropic's infrastructure and therefore needs a server that is publicly reachable via HTTPS. For local hosts, use the local transport (see Local stdio transport) or the mcp-remote bridge.