Configuration
All settings of the TYPO3 AI Suite MCP are located in the extension configuration under Admin Tools → Settings → Extension Configuration → ai_suite_mcp. They can be edited directly in the backend and take effect immediately.
The most important switch is enableMcp, which activates the MCP endpoint (see Installation). The following options control the ongoing operation.
Main Settings
| Setting | Default | Function |
|---|---|---|
enableMcp | 0 | Main switch for the MCP endpoint. When disabled, TYPO3 responds to all requests to /aisuite-mcp with 404. |
mcpWriteMode | workspace | Determines how writing tools store data (Draft workspace, Live). Details see below. |
mcpTokenLifetimeDays | 30 | Validity period of the OAuth access tokens in days. |
mcpMaxCreditsPerSession | 0 | Credit budget per token, since version 0.8.0. 0 means no budget and matches the behaviour before that. Details see below. |
mcpSessionTimeoutSeconds | 1800 | Idle timeout for MCP sessions in seconds. 0 = SDK default (3600). |
mcpAllowedOrigins | (empty) | CORS origin allowlist for browser-based clients. In production, empty means “same origin only”, in development “any origin allowed”. |
mcpAllowedClientIds | (empty) | Allowlist of permitted OAuth client IDs. Empty = all clients allowed. |
mcpAllowedRedirectUris | (empty) | Allowlist of external OAuth redirect URIs (prefix comparison). localhost is always allowed. |
mcpBackendBaseUrl | (empty) | Scheme and host for the backend links in tool results, for example www.example.com. Empty means the address is taken from the current request, and without a request, as with the stdio transport, from the site configuration. Set the value when the backend is reached under a different domain than the site. Since version 0.7.0. |
mcpSearchAdditionalTables | (empty) | Additional tables that searchContent sweeps on top of the automatically detected ones. Since version 0.6.0, the AI Suite MCP finds IRRE child tables in the TCA by itself, so this is for standalone record tables such as tx_news_domain_model_news. |
mcpExcludeAdditionalTablesFromSearch | (empty) | Tables to remove from the automatically detected set, for example to silence noisy child tables. It only affects the automatic detection, a table listed under mcpSearchAdditionalTables is searched regardless. |
Which redirect URIs and origins a particular client needs is listed under Connecting clients. Further security-related options (allow HTTP, exclude tables, trusted proxies, logging, media upload) are described under Security & operation.
Write Mode (mcpWriteMode)
The write mode controls how all writing tools store their changes. It can be set globally in the extension configuration and overridden when issuing a token per token. A token-bound workspace always takes precedence.
| Mode | Behavior | Use |
|---|---|---|
| workspace (default, labelled “Draft workspace” in the select field) | Forces every write operation into a draft workspace. The standard workspace of the backend user is used, otherwise an existing MCP workspace of this user, otherwise one is automatically created (title AI Suite MCP [#<uid>], user as member). Write operations never go live unnoticed. Since version 0.6.0, the AI Suite MCP refuses the call when no draft workspace can be resolved or created, instead of falling back to live. | The safe default. AI changes are always available as verifiable drafts. |
| live (labelled “Live” in the select field) | Bypasses workspaces and writes directly into the live records. | Non-critical automation where a review is not worth the effort. |
The extension typo3/cms-workspaces is a mandatory dependency and is installed with the installation. The target workspace is resolved in this order:
- A token-bound workspace, set when issuing the token. It always takes precedence.
- mcpWriteMode = live writes live.
- Every other value, workspace included, takes the standard workspace of the user, otherwise an existing MCP workspace, otherwise a newly created draft workspace. If none can be resolved or created, the call aborts with an error since version 0.6.0 and nothing is written.
An automatically created workspace is not saved as the TYPO3 standard of the user (be_users.workspace_id remains untouched). It only affects MCP write operations, while the normal backend session remains on the usual workspace. Reading tools automatically follow the resolved workspace, so previews show the state after the write operation.
Two tools are not workspace-capable and write live in every mode, namely uploadMedia and generateImage. They create a sys_file record plus a physical file via FAL, and FAL does not know versioning. No write mode can undo this. Both are therefore tied to their own scope (mcp:media and mcp:image) and their own feature rights, both disabled by default. Also not recoverable are consumed credits of the generate*- and batch*-tools, even if they only return suggestions.
Change in version 0.6.0: no more fallback to live
Up to version 0.5.0, the workspace mode fell back to a live write when no draft workspace could be provided. Since version 0.6.0 the call aborts with an error in that case, nothing is written and the existing state stays untouched. If your installation relies on the former fallback, switch mcpWriteMode to auto or live. Also clear all caches after the update.
Change in version 0.7.0: auto mode removed
The auto mode was removed in version 0.7.0. It was the only mode in which a write could silently go live, because the target depended on the user's workspace assignment rather than on a deliberate decision. An installation that still has auto configured now writes into a draft workspace. If you want to keep writing directly to live, set the write mode explicitly to “Live”. The select field now offers only “Draft workspace” and “Live”. Clear all caches after the update.