Claude Code is Anthropics 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 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.

There are three ways to log in:

• Way A, static token. The easiest and without a browser. Generate a token in the AI Suite backend, store it with a command in the command line. Suitable for CI, scripts, and computers without a GUI.
• Way B, OAuth 2.1 with localhost callback. On first contact, Claude Code opens a browser and performs the full OAuth flow against a short-lived local port. Suitable for work computers if you want short-lived tokens with automatic renewal.
• Way C, local stdio transport. If TYPO3 runs on the same machine, you need neither a token nor OAuth nor an accessible 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, as there is no browser-side call from a foreign origin.
• mcpAllowHttp only set to 1 if your 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).
• Claude Code is installed, claude --version works.

Check in the same terminal where you start Claude Code that the host is reachable. The call must return 200:

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

With a self-signed certificate, such as 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).

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

The configuration is stored in ~/.claude.json, with --scope project instead in the project-local .claude/mcp.json. You can check the result with claude mcp list, where typo3-ai-suite should appear.

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

1. Register server without token. The missing --header is exactly the signal that triggers the OAuth flow:

2. First connection. On the next contact with the server, i.e., at session start or the first tool call, Claude Code registers at [typo3-url]/aisuite-mcp/oauth/register, opens a local listener on a free port, and calls the authorization page in the browser. After logging into TYPO3 and agreeing to the scopes, the browser redirects back to the local listener, and Claude Code exchanges the code for tokens, which it stores in ~/.claude.json. After that, the tokens are automatically reused and renewed.

3. Check connection. In an active session, the command /mcp shows all configured servers along with their status. typo3-ai-suite should report 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, or the URL contains a site prefix. Reissue the token and use the root URL [typo3-url]/aisuite-mcp.

/mcp reports the server as failed, without further specification. The connection fails before the protocol handshake, usually due to TLS, DNS, or an incorrect path. Check curl [typo3-url]/aisuite-mcp/health in the same terminal, and for self-signed certificates, run mkcert -install.

The browser shows a certificate warning on redirect (Way B). The CA is not known to the browser. Trust the CA at the operating system level and restart the browser.

For detailed logging, claude --debug writes extensively to stderr, and /mcp logs typo3-ai-suite shows the last traffic. Other client-independent cases are collected under Clients connect.