Local stdio transport

Besides the HTTP endpoint, there is a second way to connect a client: the console command ai-suite-mcp:server. It provides the same tools, but speaks JSON-RPC over stdin and stdout instead of HTTP. It is intended for local, trusted clients on the same machine, such as Claude Desktop or Claude Code, if you prefer to start a command rather than set up an OAuth connector.

Neither a token nor OAuth nor a reachable URL is required for this. The client starts the command itself and talks to it through the pipe.

Start MCP server via stdio

vendor/bin/typo3 ai-suite-mcp:server --user=[uid-or-username]

Optional parameters

The command accepts three parameters, all of them optional. If --user is missing, the backend user with UID 1 is used. --scopes="mcp:read mcp:write" limits the scopes, by default all scopes the backend user is authorized for apply. --workspace=[uid] sets the target workspace, by default it is resolved from mcpWriteMode.

Because there is no request over stdio, the server takes backend links in tool results from the site configuration. If that does not fit, set mcpBackendBaseUrl (see Configuration).

Client configuration

You do not need a wrapper script, command and args handle everything directly. Keep in mind that GUI clients such as Claude Desktop start the command with an undefined working directory and only part of your environment variables, often without your usual PATH. Therefore, use absolute paths and change to the project directory within the command itself. Where the configuration lives in each client is described in the guide to connecting local MCP servers.

Composer installation, TYPO3 directly reachable.

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "/bin/bash",
      "args": ["-c", "cd '[project-root]' && exec ./vendor/bin/typo3 ai-suite-mcp:server --user=1"]
    }
  }
}

The project root is the directory containing the composer.json. The bin directory is located under vendor/bin/ by default and can differ via config.bin-dir.

Installation without Composer. Instead of ./vendor/bin/typo3, call '[php-path]' typo3/sysext/core/bin/typo3 ai-suite-mcp:server --user=1 from the TYPO3 root.

DDEV installation. The typo3 binary lives in the web container, so the call has to run via ddev exec. The line solves two typical problems: it first changes to the project directory, because DDEV determines its project from the working directory, and it calls ddev with an absolute path (determine it with which ddev, e.g. /opt/homebrew/bin/ddev).

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "/bin/bash",
      "args": ["-c", "cd '[project-root]' && exec '[ddev-path]' exec vendor/bin/typo3 ai-suite-mcp:server --user=1"]
    }
  }
}

The exec replaces the shell with ddev, so the pipe is passed through unchanged. Docker Desktop or OrbStack must be running, and ddev start must have been run once. A variant with docker exec -i ddev-[project]-web also works. The -i switch is mandatory, -t must never be included, because a TTY destroys the framing of the JSON-RPC messages.

Claude Code. In Claude Code, you register the same command with claude mcp add typo3-ai-suite -- /bin/bash -c "cd '[project-root]' && exec ./vendor/bin/typo3 ai-suite-mcp:server --user=1" or add one of the blocks above to the .mcp.json in the project root directory. Details are described in Anthropic's guide to MCP in Claude Code.

If the server does not start in the client, check the client's logs. Claude Desktop writes the stderr output of each server to its own log file. Where the logs are located and how to inspect the connection is described in the guide to debugging MCP servers.

Security model

Over stdio, the tools run as the specified backend user. The check of scope and feature permission applies just as over HTTP, but the main permission enable_mcp_access is not checked. Since the transport is a local pipe, all protection mechanisms of the HTTP interface do not apply, namely OAuth, the HTTPS requirement, the rate limit per token, the request size limit and the credit budget per token (mcpMaxCreditsPerSession).

Therefore, run the command exclusively as a locally started process and never attach it to a network socket. Whoever can run the command acts as the chosen user. Access to this command is therefore equivalent to that user's backend credentials. For remote access or multiple users, the OAuth-protected HTTP endpoint is the right way.

Diagnostic output goes to stderr because stdout belongs to the JSON-RPC channel. Tool calls end up in var/log/aisuite_mcp.log as usual, provided mcpLogVerbose is active (the default).