Claude Code

Claude Code is Anthropic's agent for the terminal and runs locally on macOS, Windows or Linux. The connection to the MCP server is established from your computer. The server therefore 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.

There are three ways to sign in:

• Way A, static token. The simplest way, without an OAuth flow. Create a token in the backend module “AI Suite” or with ai-suite-mcp:create-token (see CLI Commands) and store it with one command on the command line. Suitable for CI, scripts and machines without a graphical interface.
• Way B, OAuth 2.1 with localhost callback. You trigger the sign-in once in Claude Code, after which Claude Code runs the OAuth flow in the browser via a local callback port. Suitable for workstations if Claude Code is to manage the token itself and renew it automatically.
• Way C, local stdio transport. If TYPO3 runs on the same machine, you need neither a token nor OAuth nor a reachable URL. See Local stdio transport.

• enableMcp is enabled (see Configuration).
• mcpAllowedRedirectUris is not needed. Claude Code uses http://localhost:[port]/callback, and localhost is always allowed.
• mcpAllowedOrigins is not needed, there is no browser-side call from a foreign origin.
• 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.
• The backend group has enable_mcp_access and the required feature permissions (see Permissions & Scopes).
• Claude Code is installed, claude --version works.

In the same terminal in which you start Claude Code, check that the host is reachable. The call must return 200:

curl -sS [typo3-url]/aisuite-mcp/health

With a self-signed certificate, e.g. from DDEV, the CA must be in the operating system's certificate store (mkcert -install).

1. Create token. Open the AI Suite backend module, go to the MCP tab, and click on Create Token. The token is bound to your backend user and contains all scopes you are authorized for. The validity is controlled by mcpTokenLifetimeDays (default 30 days).

2. Register server. Enter your TYPO3 URL and the copied token:

Without any further option, the scope local applies: the server is only available to you and only in the current project directory. With --scope user, it applies to all your projects, with --scope project it ends up in the .mcp.json in the project root directory and is shared with the project. Details on the scopes are described in Anthropic's guide to MCP in Claude Code. You can check the result with claude mcp list, where typo3-ai-suite must appear.

Instead of the command, you can also paste the Claude Code snippet that the MCP dashboard offers next to the token into the .mcp.json, or take over the content of typo3-ai-suite (without the mcpServers wrapper) with claude mcp add-json typo3-ai-suite '<json>'. Note: the transport key here is called type, not transport. The snippet from the MCP dashboard contains the token in plain text. If the .mcp.json is in a shared project, replace the token with a reference to the environment variable TYPO3_MCP_TOKEN and set it before starting Claude Code:

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

This HTTP form is intended for Claude Code. How to add AI Suite MCP to the claude_desktop_config.json is described on the page Claude Desktop.

When the token expires, create a new one and register the server again:

1. Register the server without a token. Without --header, AI Suite MCP responds with 401, and Claude Code then offers to sign in via OAuth:

2. Sign in. In a running session, call /mcp, select typo3-ai-suite and then “Authenticate”. Alternatively, sign in on the command line with claude mcp login typo3-ai-suite. In the process, Claude Code registers itself at [typo3-url]/aisuite-mcp/oauth/register, opens the authorization page in the browser and receives the response via a local callback on localhost. After the TYPO3 sign-in and consent to the scopes, Claude Code stores the tokens itself and renews them automatically. You can sign out with claude mcp logout typo3-ai-suite. Details are described in Anthropic's guide to MCP in Claude Code.

3. Verify the connection. In a running session, /mcp shows all configured servers including their status, on the command line claude mcp get typo3-ai-suite returns the details. typo3-ai-suite should appear as connected, and the tools are available to the model.

The server appears in claude mcp list, but every call ends with 401 or “Authentication required” (Way A). The token is invalid, expired or revoked. Issue a new token.

/mcp reports 404. The URL contains a site prefix. Use the root URL [typo3-url]/aisuite-mcp.

/mcp reports a connection error for the server without further details. The connection fails before the protocol handshake, usually because of TLS, DNS or a wrong path. claude mcp get typo3-ai-suite shows details of the configuration. Check curl [typo3-url]/aisuite-mcp/health in the same terminal, with self-signed certificates run mkcert -install.

The browser shows a certificate warning during the redirect (Way B). The browser does not know the CA. Trust the CA at operating system level and restart the browser.

For a detailed log, start Claude Code with claude --debug-file <file> and read the file afterwards. Further ways of diagnosis are described in Anthropic's guide to MCP in Claude Code. Further client-independent cases are collected under Connecting Clients.