README

🚧 Under active development. This extension is in beta state and evolving fast. Tool signatures, settings keys, and the upcoming AbstractCustomTool API may still change between minor versions. Production deployments are possible (and encouraged for early feedback), but pin a version and review the changelog before upgrading. Join us on Slack: #ai-suite on TYPO3 Slack to follow development, raise issues, or shape the roadmap.

An MCP (Model Context Protocol) server for TYPO3. It connects Claude Desktop, Claude.ai, ChatGPT, MCP Inspector and other MCP-compatible clients directly to your TYPO3 backend, so the model can walk the page tree, read and search content, and create or edit records through DataHandler, as the logged-in backend user, with that user's permissions.

AI Suite is the technical foundation this builds on: it ships the extension infrastructure, the backend-group permission model, the TYPO3 version-compatibility layer and the shared services. It is a hard dependency (autodudes/ai-suite ^12.22.1 || ^13.16.1 || ^14.4.1) and Composer pulls it in for you.

What it is not is a paywall. The MCP server is useful on its own, with no AI Suite account, no API key and no credits: your MCP client already brings the model that does the thinking. AI Suite's own AI providers (OpenAI, Anthropic, Mittwald AI, IONOS AI Model Hub incl. Flux, DeepL, Google Translate, Midjourney, …) are an optional add-on for the twelve tools that generate, translate or audit server-side.

Do I need an AI Suite subscription?

For most of what this extension does, no.

34 of the 46 tools run entirely inside your TYPO3 installation and cost nothing beyond what your MCP client charges you: the whole page tree, content and file reads, searchContent, schema discovery, record CRUD through DataHandler, the safe-edit tools, localizeRecord, workspace review (compareWithLive), stored audit results (readAuditResults) and uploadMedia. Your client's model composes the content; TYPO3 stores it. These tools send no request to the AI Suite Server (tools/list only checks whether it is reachable), and the transport does not check for an API key.

12 tools do call the AI Suite Server and spend credits, because the generation, translation or audit happens there:

These twelve are the entire credit-costing surface; without an AI Suite account they are the only ones you lose. The tools that poll and persist their results are free: readTaskStatus, readTaskResults (mcp:read) and applyTaskResults (mcp:write). So is granting the mcp:workflow scope itself.

Translation is the one place where the distinction is easy to miss, and it depends on the model argument. Called without model, translateRecord and translatePage cost nothing: they create the translation records, hand the source fields back together with the site glossary, and your client's model translates them and writes the result with writeRecords. Called with a model, the work goes to a translation model on the server and is billed. translateFileMetadata and the batch* tools always need a model. localizeRecord creates an empty translation shell with TYPO3's own localization machinery and costs nothing.

What you can do with it

Once connected, your MCP client can drive the TYPO3 backend the same way an editor would, but without leaving the chat.

• 🧭 Walk the page tree, read pages, search content: the model gets first-class access to every page, content element and FAL file the BE user can see.
• ✍️ Create & rewrite content: the client model composes tt_content elements and page trees itself and persists them through DataHandler, honouring the editors' guidelines (readEditorialGuidelines). No credits are spent for that.
• 🌍 Translate anything: single records, complete pages, file metadata, or whole folders in one batch. (server-side translation costs credits; localizeRecord + your own model does not)
• 🏷️ Fill in metadata at scale: SEO titles, descriptions, OG / Twitter tags, alt texts, file metadata. Single record or bulk over a whole folder / page subtree. (costs credits)
• 🖼️ Generate images straight into FAL: the result lands as a real sys_file, ready to be referenced. (costs credits)
• 🧱 Edit records safely: every CRUD tool runs through DataHandler; approval comes from the MCP client's dialog (see Why the client asks for approval), and previewRecords offers an optional old→new diff. Reversibility is guaranteed by the workspace write mode (the default), which keeps every change in a reviewable draft.
• 🧰 Workspace-aware writes: defaults to routing changes through a TYPO3 draft workspace (auto-creating a per-user one when needed); tokens can even be pinned to a specific workspace.
• 🧩 Works with EXT:container and your custom records: container children, third-party tables (news, products, custom CTypes) are first-class.
• ⏱️ Background batch jobs: long-running translations / metadata generation get an async task ID; results come back as suggestions you approve. (costs credits)
• 🔐 Production-grade auth: OAuth 2.1 + PKCE with dynamic client registration, per-token rate limiting, full HTTPS enforcement, password-change revocation.
• 👤 Respects TYPO3 BE-user permissions: every tool call runs as the linked backend user; page mounts, file mounts, table/field access rights and AI Suite per-feature/per-model BE-group flags are enforced on every request.
• 🖥️ Managed from the backend: a dedicated MCP module issues and revokes tokens without the CLI, and an MCP entry in the AI Suite button bar leads there (both gated by enable_mcp_access).
• 📚 Resources and prompts: besides the tools, the server exposes the operating guidelines, a page's editorial instructions, the site configuration, the credit status and the usage dashboard as MCP resources, and the AI Suite prompt templates as MCP prompts.
• 📊 Reports + dedicated logs: TYPO3 Reports module flags misconfigurations; two log streams (verbose + WARNING-only) keep ops monitoring simple.

AI capabilities & available models

This section covers the optional part: the twelve tools listed above that route to the AI Suite Server. Skip it if your MCP client's own model is doing the work.

These tools delegate the actual generation / translation to the parent AI Suite extension, so every model you've licensed there is also available to your MCP client. Permissions are still gated per BE-group feature flag and per AI model.

The exact model list available to a given BE user depends on the AI-model permissions configured on their BE group in AI Suite. The model picks itself up automatically from the AI Suite settings; no extra config in MCP.

Beyond the AI-powered tools above, MCP also ships discovery and editing tools (no model calls): readRenderedPage (the page as a visitor sees it, including plugin output; needs the enable_mcp_rendered_page_read flag, see Per-tool permissions), readEditorialGuidelines (the tone / target audience / style the editors configured for a page subtree), listTables, readRecordSchema (with per-field content kind, read-only and relation metadata), listContentTypes, readChildren (list a record's container/IRRE children), readPageContent, readRecords, searchContent (sweeps every page-bound table with a searchable text field, see Which tables searchContent sweeps; optional rootPageId to search one page subtree, single-field / matchHtml search), previewRecords (shows an old→new diff when editing), writeRecords (with optional atomic:true all-or-nothing batches), copyRecords, moveRecords, deleteRecords, localizeRecord, and the safe-edit tools patchText / bulkReplaceText for small text corrections without resending whole fields (they locate the match ignoring line-ending and spacing differences by default, since stored rich text keeps CRLF that no read shows verbatim; pass normalizeWhitespace:false to require a byte-exact match). Media references can be reused/swapped with copyMediaReference / replaceMediaReference.

Requirements

• TYPO3 12.4.11 to 14.3.99
• PHP 8.2+
• autodudes/ai-suite ^12.22.1 || ^13.16.1 || ^14.4.1 (ext_emconf: 12.22.1-14.99.99): required, and installed automatically. It provides the extension infrastructure, the BE-group permission model, the TYPO3 version-compatibility layer and shared services. An AI Suite account, API key or credits are a separate matter and only needed for the twelve server-side tools listed above.
• typo3/cms-reports ^12.4.11 || ^13.4.1 || ^14.3.0
• logiscape/mcp-sdk-php ^2.0 (bundled for classic mode, see below)
• symfony/clock ^6.4 || ^7.0 || ^8.0 (shipped by the TYPO3 core)
• typo3/cms-workspaces ^12.4.11 || ^13.4.1 || ^14.3.0: required; powers the workspace write modes (the default), including on-demand per-user workspace provisioning
• PHP extensions curl and json

Installation

composer require autodudes/ai-suite-mcp
vendor/bin/typo3 extension:setup

Also available on the TYPO3 Extension Repository: extensions.typo3.org/extension/ai_suite_mcp.

Then make sure the webserver passes the Authorization header on to PHP, see Webserver setup. Without it every request to the MCP endpoint ends in 401, even with a valid token.

Classic mode (no Composer)

The extension also runs in TYPO3 12, 13 and 14 installations without Composer. The one library TYPO3 does not ship, logiscape/mcp-sdk-php, is bundled in Resources/Private/PHP/ComposerVendor. TYPO3 v14 loads it through providesPackages in composer.json, v12 and v13 through the autoload section of ext_emconf.php. Nothing has to be copied by hand.

1. Activate the system extensions workspaces and reports.
2. Install and activate ai_suite, then ai_suite_mcp (Extension Manager upload or TER), in that order.
3. Open System → Reports → Status Report. AI Suite MCP Environment names missing PHP extensions and an SDK that cannot be loaded, which is what an incompletely uploaded extension looks like.
4. Wherever this README calls vendor/bin/typo3, use typo3/sysext/core/bin/typo3 from the TYPO3 root instead. Without a system cron, run ai-suite-mcp:cleanup through the Scheduler task Execute console commands.

What differs from a Composer installation:

• Paths: var/ is typo3temp/var/, so sessions live in typo3temp/var/aisuite_mcp_sessions/, task results in typo3temp/var/mcp_tasks/ and the logs in typo3temp/var/log/. TYPO3's .htaccess denies web access to that directory on Apache. On nginx add a rule yourself, e.g. location ^~ /typo3temp/var/ { deny all; }, or the session files are publicly readable.
• Host root only: the MCP endpoint, the OAuth endpoints and the /.well-known/ documents are answered at the root of the host. A TYPO3 installed in a sub directory (https://example.com/cms/) is not supported.
• Webserver: the Authorization header rules from Webserver setup apply unchanged.

Configuration

All settings live under Admin Tools → Settings → Extension Configuration → ai_suite_mcp.

Logging settings (mcpLogVerbose, mcpLogRedactionPatterns) are documented under Logging & retention; the media-upload settings (mcpMediaDefaultFolder, mcpMediaMaxSizeMb, mcpMediaAllowedExtensions, mcpMediaAllowUrlFetch, mcpMediaHostDenylist) under the uploadMedia tool.

ChEddi inherits these settings. The editor assistant ChEddi (cheddi) runs the same tools in-process and follows mcpWriteMode, mcpAllowRawHtmlWrite, mcpExcludedTables, mcpLogVerbose and mcpLogRedactionPatterns unless ChEddi sets its own value: chatWriteMode, chatAllowRawHtmlWrite and chatLogVerbose default to inherit, the list settings default to empty and are added on top of the MCP lists. chatAllowRawHtmlWrite, chatExcludedTables and chatLogRedactionPatterns can only tighten the MCP value. Two settings are ChEddi's own decision instead: chatWriteMode replaces mcpWriteMode for ChEddi (so live there writes live even while MCP writes to a workspace), and chatLogVerbose switches ChEddi's own log independently of mcpLogVerbose. ChEddi hands its values to SurfaceSettingOverrides, which stays empty for calls arriving over the MCP transport.

Backend links in tool results

A call that touched records reports them back as UIDs, which is precise but unusable; nobody wants to look up page 99934 by hand. Every tool result therefore also carries links to what it touched, in two channels: structuredContent.links for hosts that render them themselves, and a 🔗 Open in TYPO3 block appended to the result text, which is what makes them clickable in a chat client. The targets come from the UIDs the tools reported, so they point at what was actually written; the label is the record's own title where it has one. The block asks the assistant to pass the links on, so an editor gets them with the answer instead of having to ask for them.

Links are grouped by table, because a page and the content elements on it are different destinations:

"links": [
  {"table": "pages", "label": "Page", "targets": [{"label": "Landing page", "url": "https://…"}], "omitted": 0},
  {"table": "tt_content", "label": "Page Content", "targets": [{"label": "Header", "url": "https://…"}], "omitted": 2}
]

pages comes first, the remaining tables in the order they were touched. The cap of six is per group, so a written page is never pushed out of the list by the content elements written onto it; omitted reports how many the cap dropped, so a truncated group cannot be mistaken for a complete one.

The URLs are absolute and carry no route token. A token belongs to the session that generated it, the MCP session and not the editor's browser, so it would be worthless in a link that leaves the process.

They do not point at the backend directly but at /aisuite-mcp/open on the backend host, carrying the backend path and a signature. TYPO3's backend session cookie is not sent along when a link is followed from another site such as claude.ai or ChatGPT, so a direct link ends on the login screen even for an editor who is logged in. The bounce page is served by the backend host itself and continues to the backend from there, a navigation the browser does send the cookie with: an editor with a live session lands directly on the record, one without passes through the login first. The page holds no data and answers even while enableMcp is off, so links in older chats keep opening. It forwards only same-host absolute paths signed with this installation's encryptionKey, which keeps it from being used as an open redirect; the links do not expire, and changing the key invalidates every link handed out before. mcpBackendLinkBounce = 0 returns to direct links.

Host resolution, first hit wins: mcpBackendBaseUrl → current request → site configuration (Site::getBase()). If none of them yields a scheme and host (the stdio transport has no request, and an installation may have no site configured), the link is dropped rather than emitted broken, with a warning in aisuite_mcp_warnings.log.

Which tables searchContent sweeps

searchContent always searches pages and tt_content. Beyond those it sweeps every table whose records can live on a page and that carries a searchable text column: no configuration, no allowlist. That covers standalone record tables (tx_news_domain_model_news and friends), Content Blocks collections, Bootstrap Package accordion/card items and any hand-written equivalent.

Three kinds of table are dropped structurally, each on its own TCA declaration: a table with rootLevel = 1 (pid 0 only, so it can never sit inside a webmount; note that rootLevel = -1 means both and those tables, sys_category among them, are swept), a table that declares the page tree does not apply to it (the core sets this on the FAL tables, so sys_file_reference drops out by its own declaration rather than by name), and a table without a searchable text column. hideTable is deliberately not a criterion: it means "no entry in the list module", not "secret", and every Content Blocks collection carries it.

Because nothing has to be listed to be searched, the denylist is the only gate, and it ships filled. These tables are blocked out of the box:

mcpExcludedTables adds to that list and cannot remove an entry, so no configuration mistake can expose fe_users through search. A table you do not want swept but do want readable has no separate switch any more; block it entirely or leave it.

The user's own backend permissions apply on top: a table the BE user cannot tables_select is skipped silently and does not appear in the response's searchedTables, which always names exactly the tables that were searched.

Earlier versions worked the other way round, with two settings (mcpSearchAdditionalTables, mcpExcludeAdditionalTablesFromSearch) and auto-detection limited to IRRE children. Both settings are gone. If you had listed a table under the first, it is now found automatically and the entry can be dropped. If you had used the second to silence a noisy child table, move that table to mcpExcludedTables: it is no longer possible to exclude a table from search while keeping it readable.

Known MCP client callback URLs

Copy these into mcpAllowedRedirectUris / mcpAllowedOrigins for every client you want to support.

Notes

• Entries in mcpAllowedRedirectUris are matched by prefix, so e.g. https://claude.ai/ covers any sub-path Claude may send (see AuthorizationEndpoint::validateRedirectUri).
• Outside the Production context an empty mcpAllowedRedirectUris permits any redirect_uri; in Production an empty list allows only the localhost redirect URIs. The origin check is relaxed in the Development context only (see mcpAllowedOrigins).
• mcpAllowedOrigins only affects browser-based clients (CORS). CLI and desktop-native clients ignore it.

Write modes

mcpWriteMode controls how every write-capable tool (writeRecords, copyRecords, moveRecords, localizeRecord, deleteRecords, savePageTree, …) persists its changes. It is set globally in the extension configuration; a token can additionally be bound to a workspace when it is issued, and that binding always wins.

A third mode, auto (draft if one happened to be available, else live), was removed: its soft fallback made the write target depend on the user's workspace assignment rather than on a decision. A configuration still carrying the value resolves to workspace.

Resolution order (see McpBackendUserInitializer):

1. Token-bound workspace (set when issuing the token), always wins.
2. mcpWriteMode = live → live (0).
3. Every other value, workspace included → BE user's default workspace → else an existing per-user MCP workspace → else a freshly auto-created per-user draft workspace (never silently live). Only live sends a write to the live site.

The auto-created workspace is not stored as the user's TYPO3 default (be_users.workspace_id is left untouched), so it only affects MCP writes; the user's normal backend session stays on whatever workspace they had.

Read tools transparently follow whatever workspace the request resolved to, so previews show what the model would see after the write lands.

⚠️ Two tools are not workspace-contained and write to live in every mode: uploadMedia and generateImage. They create a sys_file record plus the physical file through FAL, which has no versioningWS: so their writes cannot land in a draft and no write mode undoes them. Both are gated behind their own scope (mcp:media / mcp:image) and BE-group feature flag (default off), and the MCP client's approval dialog is the only pre-write gate. Separately, the credits spent by the generate* / batch* tools are never refundable; those tools return suggestions and spend credits even though they write no database row.

Why the client asks for approval

Nothing in this server asks a user to confirm a call. When a client shows an approval dialog, or reports something like No approval received, that decision was made entirely on the client side. There is no server-side approval gate, no confirmation parameter and, in particular, no batch-size threshold: deleting one record and deleting eleven in one call take the identical code path. If single calls go through while a batch does not, that is a property of the client, not of this server.

What the server does contribute are the MCP tool annotations, which is what a client typically bases its dialog on:

idempotentHint is the one hint that matters on a writing tool: it tells a client that a retry of the identical call needs no second approval. It is deliberately not set on copyMediaReference, which creates a new reference every time, nor on writeRecords, whose batch may contain creates.

writeRecords, copyRecords, moveRecords and savePageTree are deliberately not marked destructive: under the default mcpWriteMode = workspace they land in a draft and are undone by discarding it. Marking them destructive would add approval friction for changes that are already reversible.

If a client asks too often or too rarely, the setting to change is in the client. previewRecords is available for a read-only look at what a write would do, and dryRun on bulkReplaceText reports the blast radius of a bulk edit without writing.

Protocol revisions

The server speaks two eras of the Model Context Protocol and picks per request, so no connector has to be configured for one or the other:

A modern client that asks for a revision this server does not implement gets 400 with JSON-RPC error -32600 and the supported list in error.data.supported. That is the spec's signal for "legacy-capable server": a dual-era client falls back to initialize on it.

Server identity, icons and the operating guidelines ride the initialize result on the legacy path and the server/discover result on the modern one.

Connectors

Each supported MCP client has its own dedicated setup guide under Connectors/. The guides cover prerequisites (extension settings, BE-group permissions, host reachability), the per-client UI / CLI / config-file steps to register the connector, smoke-test prompts, and a troubleshooting matrix.

For a quick reference of the OAuth redirect_uri and browser origin values each client expects, see the Known MCP client callback URLs table above.

Connector setup essentials

The per-client guides under Connectors/ all share a few foundational requirements and common failure modes. They are documented once here to avoid repetition; each connector guide cross-references this section.

BE-group permissions

The TYPO3 backend user the token / OAuth consent is issued for needs the following feature flags on their BE group:

• enable_mcp_access: mandatory; the master gate for MCP and the backend dashboard, checked directly on every request (no OAuth scope maps to it)
• enable_metadata_generation: for batchGenerateMetadata, generateFileMetadata, batchGenerateFileMetadata (any of enable_metadata_generation, enable_content_element_generation or enable_pages_generation satisfies the mcp:generate scope)
• enable_translation: for all translation tools
• enable_image_generation: for generateImage
• enable_massaction_generation: for the four batch* tools (readTaskStatus, readTaskResults and applyTaskResults need no flag)
• enable_mcp_media_upload: for uploadMedia (mcp:media scope)
• enable_mcp_rendered_page_read: for readRenderedPage (see "Per-tool permissions" below)
• enable_audit: for the three audit* tools (see "Per-tool permissions" below)

Without enable_mcp_access every request to the MCP endpoint is rejected with 403 access_denied, and the OAuth consent is refused. Without the feature-specific flags the affected tools simply don't appear in the model's tool list.

Per-tool permissions

Most flags gate a whole scope (see the table under OAuth scopes). Two flags gate individual tools instead, because those tools reach further than the rest of their scope:

readRenderedPage renders the page through a backend preview session of the MCP user, so it also returns hidden pages, unpublished pages and workspace drafts: content a plain HTTP fetch of the public URL could never reach. The other mcp:read tools return stored records and need no flag, so the gate sits on the tool rather than on the scope: putting it on mcp:read would revoke every read tool and change which scopes OAuth grants.

The audit tools (auditSeo, auditAccessibility, auditContent) follow the same pattern: they send the page URL to the AutoDudes audit infrastructure (AI Suite Server → Tool Gateway), resolved from pageId when the caller names a page rather than a URL, so page URL and, transitively, public page content leave the TYPO3 instance. They stay read-only towards TYPO3, hence mcp:read plus the dedicated enable_audit flag instead of an own OAuth scope.

When the audited URL resolves to a page of this installation that the user may see, the result is stored for that page and language exactly like an audit started in the Audit module: it shows up there, in the page module tile and in readAuditResults, and a newer audit of the same type replaces it. The tool result then ends with Stored in the AI Suite audit module for page <uid>. and carries structuredContent.auditStored. Audits of foreign URLs (a competitor's site) and audits that could not reach the page are not stored.

The user's own page permissions still apply on top. Without the flag the tool does not appear in tools/list, and a forced call returns a permission error.

Common troubleshooting

Issues that can happen with any client, regardless of transport:

Calling tools manually

When using a debug client like the MCP Inspector, tools can be invoked directly with hand-built JSON arguments instead of going through an LLM. The right-hand pane shows the raw JSON-RPC request and response for every call, invaluable for diagnosing schema mismatches and permission issues.

A useful starter sequence:

OAuth scopes

Each tool requires a scope, and each scope is only granted to users whose BE group has at least one of the matching AI Suite feature flags. See PermissionService::SCOPE_PERMISSION_MAP.

These seven are the complete list. In particular there is no mcp:glossary, no mcp:easy-language and no mcp:manage scope; those appeared in an outdated document and have never existed in any released version. Glossary handling rides along with mcp:translate, Easy Language is not exposed over MCP, and there is no management scope at all. An unknown scope is ignored: the consent screen offers only scopes from this list that the user's groups allow.

Tools

Context (mcp:read)

Records: discovery (mcp:read) and CRUD (mcp:write / mcp:read)

Code editor fields

Write tools do not store markup a field cannot hold: a value going into a plain TCA text or input field has its tags removed and its whitespace normalised, so a model that answers in HTML does not put <p> into a page title. Two kinds of field are exempt, because there the markup is the value:

• Rich text fields (enableRichtext, e.g. bodytext of textmedia) are stored as sent. They pass through TYPO3's own RteHtmlParser + HTML sanitizer on save, exactly like manual backend editing.
• Code editor fields: TCA text with a code editor renderType/format, the prominent one being tt_content.bodytext of CType html. TYPO3 renders those unfiltered, so they are gated by mcpAllowRawHtmlWrite (default off): with the setting on the source round-trips byte for byte, with it off a write carrying markup is rejected with unsupported_html and the stored value is left alone.

readRecordSchema reports the distinction per field as kind:rte, kind:html, kind:text, kind:relation or, where a format hint applies, kind:lines. When editing such a field, read it with readRecords(raw: true) (a normal read returns a tag-stripped preview) or, better, change it in place with patchText.

Writing translations

A record entry may carry a translations object next to fields, keyed by ISO language code:

{
  "records": [{
    "table": "tt_content",
    "pid": 354,
    "fields": { "CType": "text", "header": "Einstellungen" },
    "translations": { "en": { "header": "Settings" } }
  }]
}

The translation shell is created with TYPO3's own localize command, the same path the backend takes, so the language field, the translation parent, l10n_source, l10n_state, l10n_mode: exclude and any inline children are handled by the core. The given fields are then written into that shell. It is created hidden, as TYPO3 does it; send hidden: 0 among the translated fields to make it visible in the same call. translateRecord, translatePage and localizeRecord take hidden: false for the same purpose.

Calling the same payload twice updates the existing translation instead of creating a second one, so re-sending a batch after a partial failure is safe. translations also works on an entry that carries a uid: that record is the origin. Nested inline children cannot be translated in the same call; write them first, then translate them by uid.

Writes over the MCP transport do not trigger the automatic translation on save (enableAutoTranslateOnSave): that hook only runs inside a backend request, and MCP requests are not one. Translate explicitly with translations, translateRecord or translatePage. ChEddi runs its tools inside a backend request, so the hook does apply to what ChEddi writes.

Field name aliases

tt_content kept the legacy l18n_parent, while pages and most hand-written child tables use l10n_parent. Both spellings are accepted on read and on write and mapped onto whatever the table really calls it (same for l10n_source / l18n_source); the result says when it happened. A name the table genuinely has is never rewritten.

Generation (mcp:generate)

Translation (mcp:translate)

Images (mcp:image)

Media upload (mcp:media)

uploadMedia takes a media array; each item carries exactly one source (url or content) plus optional fileName, targetFolder and metadata (title, alternative, description). Items are processed independently; one failing item does not abort the batch.

Security. Remote URL fetching is the sensitive part and is SSRF-guarded by RemoteMediaService: only http/https, every resolved IP must be public (private, loopback, link-local incl. the 169.254.169.254 cloud-metadata endpoint, and reserved ranges are rejected, IPv4 + IPv6), redirects are followed manually and re-validated per hop, and the download is streamed with a hard size cap. Blocked targets are logged at WARNING. Beyond the OAuth scope + enable_mcp_media_upload flag, FAL filemount permissions on the target folder still apply. Tunables (ext_conf): mcpMediaDefaultFolder (default 1:/user_upload/), mcpMediaMaxSizeMb (50), mcpMediaAllowedExtensions (jpg,jpeg,png,gif,webp,avif,mp4,webm,ogg; SVG excluded by default, XSS risk), mcpMediaAllowUrlFetch (1, kill-switch for URL downloads), mcpMediaHostDenylist (empty). Large videos should be supplied via url or an online-media link rather than base64.

Workflow (mcp:workflow; polling mcp:read, applying mcp:write)

Batch tools run asynchronously and return a task ID. Poll via readTaskStatus, retrieve results via readTaskResults.

The page-batch tools (batchGenerateMetadata and batchTranslatePage) take their targets one of two ways, and exactly one of them: pageIds (an explicit UID array) or rootPageId (a page and everything below it, resolved server-side). Passing both is an error rather than a guess about which one wins; passing neither is an error too. Neither selection parameter is therefore marked as required, because "exactly one of two" is only expressible as a top-level oneOf, which no provider loads reliably as a tool. batchGenerateMetadata marks nothing as required at all, while batchTranslatePage still requires targetLanguage. recursive (default true) decides whether a rootPageId walks the subtree (up to 20 levels) or stops at its direct children; the root page itself is always included.

Cost cap. A rootPageId expands to at most 50 pages, for both tools. Beyond that the call is refused before anything is billed, naming the number of pages it found. The reason is asymmetric: these tools spend credits per page, and a subtree is a quantity the caller never counted: "everything below the site root" is one short sentence away from a four-figure charge. An explicit pageIds list is a quantity the caller did state, so it is not capped. To work within the cap, pick a deeper root, set recursive to false, or pass the UIDs explicitly.

Tools removed in this version

Seven tool names no longer exist. A saved prompt or a connector configuration that still calls one gets an "unknown tool" error, so repoint it:

• auditQuestions → auditContent with type: "questions"
• auditContentGap → auditContent with type: "gap"
• auditTopicCluster → auditContent with type: "cluster"
• auditCompetitors → auditContent with type: "competitors"
• batchGenerateFolderMetadata → batchGenerateFileMetadata with folderIdentifiers
• batchTranslateFolderMetadata → batchTranslateFileMetadata with folderIdentifiers
• replaceText → patchText with a single-entry replacements list

The four audit tools shared their parameters and their verdict shape and differed only in the angle they asked from, which is a type enum rather than four tools; the enum values are the stored audit types, so results written by the old names stay readable through readAuditResults. The two folder tools only resolved a folder to file UIDs and then delegated. replaceText was the one-entry case of patchText. Every tool carries its schema on every turn, so the count is what costs context: the catalogue went from 52 tools to 46.

translateRecord also changed shape rather than name: its result now reports translation.records where it used to report translation.fields, because the tool carries the inline children of a record along with the record itself.

Operating guidelines

Classes/Mcp/Utility/OperatingGuidelines.php is the single source of the normative text the server sends to the model. It ships as initialize.instructions (once per session, cached by the provider alongside the tool definitions) and is also readable as the aisuite://guidelines resource. Tool descriptions never repeat it: a section is sent once per session, a description on every turn.

Nine sections are sent, in this order:

Approval is the host's job, not the model's. The guidelines deliberately contain no rule telling the model to wait for confirmation before writing: measured against a benchmark, gpt-5.4-nano and gpt-oss-120b obeyed such a rule literally: they previewed, then waited forever for a human who was not there. Confirmation happens outside the model: MCP clients raise their own approval dialog, and ChEddi stops write/destructive calls with needsConfirm. previewRecords is offered as a read-only old→new diff, but nothing enforces it server-side; what guarantees reversibility is the write mode (see Write modes).

Batch tools never auto-persist: they return suggestions, which applyTaskResults (translation batches) or writeRecords (metadata batches) persists only when called.

Custom tools

Need a tool that doesn't exist yet: pulling data from a project-specific table, kicking off a domain workflow, exposing a sitepackage helper to the model? You can extend the MCP server from your own extension.

Anatomy of a tool

Every tool implements AutoDudes\AiSuiteMcp\Mcp\Tool\ToolInterface:

public function getName(): string;           // unique tool name, used by the LLM
public function getDescription(): string;    // shown to the model when picking tools
public function getSchema(): array;          // JSON Schema for the input arguments
public function getAnnotations(): array;     // MCP behavioural hints (readOnlyHint, destructiveHint, …)
public function execute(array $params): CallToolResult;
public function getRequiredScope(): ?string; // informational; the enforced scope comes from TOOL_SCOPE_MAP
public function getCreditCost(): ?int;       // fixed credit cost per call if known; null = no fixed cost (not necessarily free)

ToolInterface carries #[AutoconfigureTag('aisuite.mcp.tool')], so any service implementing it is picked up automatically by ToolRegistry: no manual Services.yaml wiring needed, just make sure your extension's Configuration/Services.php autowires + autoconfigures the namespace.

Trust boundary

ToolRegistry::validateToolOrigin() enforces a hard rule: a tool is only registered when its class lives under one of the allowed namespaces AutoDudes\AiSuiteMcp\, AutoDudes\AiSuite\ or AutoDudes\Cheddi\. Every other tool is rejected at boot time and logged as a warning to aisuite_mcp_warnings.log, whether it extends AbstractTool or implements ToolInterface directly.

Third-party tools are meant to extend AbstractCustomTool once it ships: its final doExecute() will route calls through the AI Suite Server so credit accounting and the central security policy stay in place. Don't bypass the boundary; it's there to prevent custom code from siphoning AI provider calls outside the credits pipeline.

⚠️ Status: AbstractCustomTool is the planned public extension API. It does not exist yet: Classes/Mcp/CustomTool/ is an empty placeholder directory, and until the class ships, third-party tools cannot register. If you have a use case that doesn't fit any of the built-in tools, open a feedback issue, we'd like to know what shape the API needs to take before we freeze it.

Adding a tool inside this extension

For tools that legitimately belong here (built-in tools), the pattern is:

1. Create a class under Classes/Mcp/Tool/<Category>/MyNewTool.php extending AbstractTool (or AbstractAiTool / AbstractTranslateTool for AI-powered tools that need credit accounting and model routing).
2. Add #[AutoconfigureTag('aisuite.mcp.tool')] if your class doesn't pick it up via ToolInterface (in practice it does automatically).
3. Implement getName(), getDescription() and getSchema(), set $requiredScope, and implement doExecute(): never execute(), which is final on AbstractTool and runs the validation / permissions / error-handling pipeline.
4. Inject any extra services through your own constructor; the bundled context (ToolContext) already covers the common ones (McpUserContext, PermissionService, logger, LocalizationService, BackendUserService, …).
5. Add the tool name to PermissionService::TOOL_SCOPE_MAP (mandatory: the map is fail-closed, a tool missing there is hidden from tools/list, fails when called and breaks ToolScopeMapCompletenessTest), and to TOOL_PERMISSION_MAP if it needs its own flag.
6. Map your scope to the right BE-group flag in PermissionService::SCOPE_PERMISSION_MAP if you introduce a new scope.

Verify the tool shows up in tools/list, for example in the MCP Inspector.

Console commands

# Create a test token (bypasses OAuth flow, development only)
vendor/bin/typo3 ai-suite-mcp:create-token --user=1
vendor/bin/typo3 ai-suite-mcp:create-token --user=admin --scopes="mcp:read mcp:write mcp:generate"
vendor/bin/typo3 ai-suite-mcp:create-token --user=1 --client=mcp-inspector
# Bind the token to a workspace, or set the RFC 8707 resource when the CLI host differs from the public URL
vendor/bin/typo3 ai-suite-mcp:create-token --user=1 --workspace=3
vendor/bin/typo3 ai-suite-mcp:create-token --user=1 --audience="<canonical resource URI>"

# Clean up expired OAuth state, session files and completed task files
vendor/bin/typo3 ai-suite-mcp:cleanup

# Run a local MCP server over stdio (trusted local CLI clients only, see "Local stdio transport")
vendor/bin/typo3 ai-suite-mcp:server --user=1
vendor/bin/typo3 ai-suite-mcp:server --user=editor --scopes="mcp:read mcp:write"

ai-suite-mcp:cleanup removes:

• authorization codes older than 10 min
• access tokens that expired more than 37 days ago (a fixed cutoff, independent of mcpTokenLifetimeDays)
• revoked tokens created more than 30 days ago (hard delete)
• session files under var/aisuite_mcp_sessions/ older than twice mcpSessionTimeoutSeconds, at least one hour (one hour at the default of 1800 s)
• background task files under var/mcp_tasks/ older than 30 days

Schedule it via the TYPO3 Scheduler or cron. How many session files are lying around is reported by readServerInfo and, for admins, as the MCP Session Store entry in the Reports module.

Local stdio transport

ai-suite-mcp:server exposes the same tools as the HTTP endpoint, but over stdio (JSON-RPC on stdin/stdout) instead of HTTP. It is intended for local, trusted CLI clients (Claude Desktop / Claude Code on the same host) that prefer launching a command over an OAuth connector.

# The client launches this command and talks JSON-RPC over the pipe:
vendor/bin/typo3 ai-suite-mcp:server --user=<uid|username>
#   --scopes="mcp:read mcp:write …"   # default: all scopes the BE user is entitled to
#   --workspace=<uid>                 # default: resolved from mcpWriteMode

No wrapper script is needed; command + args do everything inline. GUI clients (Claude Desktop) launch the command from their own working directory with a minimal PATH, so use absolute paths to the launcher.

Composer install (TYPO3 reachable directly, no DDEV):

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

<project-root> contains composer.json; the bin dir defaults to vendor/bin/ (relocatable via config.bin-dir).

DDEV install: the typo3 binary lives inside the web container, so reach it through ddev exec. Two things break a bare ddev exec when launched by the client, both solved inline: cd into the project first (DDEV resolves its project from the cwd), and use the absolute ddev path (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"]
    }
  }
}

exec replaces bash with ddev so the pipe is passed through cleanly. Docker Desktop / OrbStack must be running and ddev start run once. A bare-docker exec -i ddev-<project>-web … variant also works (-i required, never -t: a TTY corrupts JSON-RPC framing). For the full Claude-Desktop walkthrough see Connectors/claude-desktop.md.

Security model. stdio runs the tools as the given backend user; the per-tool scope and feature-flag checks apply as over HTTP, but the enable_mcp_access master flag is not checked. And because the transport is a local pipe, it bypasses OAuth, the HTTPS gate, per-token rate limiting, the request-body cap and the per-token credit budget (mcpMaxCreditsPerSession is tracked per OAuth token, so over stdio it never applies): those are HTTP-surface protections. Run it only as a locally launched process, never wired to a network socket. Anyone who can run the command can act as the chosen --user, so treat command access as equivalent to that user's backend credentials. For remote / multi-user access, use the OAuth HTTP endpoint instead.

Diagnostics are written to stderr (stdout is reserved for the JSON-RPC channel); tool calls are logged to var/log/aisuite_mcp.log as usual.

Database tables

Security

Enforced by McpServerMiddleware and the OAuth endpoints:

• HTTPS required in production (localhost + *.ddev.site exempted; override with mcpAllowHttp=1: not for production).
• Request-body cap of 1 MB per MCP request.
• Rate limiting: 100 requests / minute per Bearer token (responds 429 with Retry-After: 60).
• OAuth rate limiting: /aisuite-mcp/oauth/token and /aisuite-mcp/oauth/register are limited per client IP with the same limiter (429 rate_limit_exceeded).
• OAuth 2.1 with PKCE, no implicit / password grants.
• Dynamic Client Registration is permitted but constrained by mcpAllowedClientIds / mcpAllowedRedirectUris.
• Password change revokes all tokens for that BE user (PasswordChangeHook on processDatamapClass).
• Live backend-user status check on every request: disabled / deleted users are rejected even if their token is still valid.
• Scope + permission double check: an OAuth scope alone is not sufficient; the BE user group must also carry the matching AI Suite feature flag.
• Raw markup is refused by default: a write that would put HTML/JavaScript into an unfiltered code editor field fails unless mcpAllowRawHtmlWrite is enabled.
• Reports module surfaces misconfigurations: HTTP allowed, empty allowlists in production. Check System → Reports → AI Suite MCP Security.

Production deployment

The settings, security gates, and connector flows above are sufficient to run the MCP server. Operating it stably in production additionally requires getting the topics in this section right; none of them are enforced by the code, but ignoring any one of them tends to cause silent failures (lost session state, stale tokens, audit-log gaps, …) rather than loud errors.

Reverse proxy & load balancer

• HTTPS detection: McpServerMiddleware::enforceHttps() honors X-Forwarded-Proto: https in addition to the request scheme. If your CDN or load balancer terminates TLS and forwards plain HTTP to the origin, set this header on the proxy.
• HTTPS-gate trust boundary: X-Forwarded-Proto is accepted from any upstream; the HTTPS gate does not consult the mcpTrustedProxies list (that setting only governs audit-log IP resolution, see below). A direct client that sends X-Forwarded-Proto: https would bypass the HTTPS gate. Make sure your proxy strips the header from inbound traffic before re-setting it, or restrict access to the origin to the proxy IPs only (firewall / VPC).
• Client IP in audit logs: OAuth audit entries (token issued, token revoked, …) record the client IP resolved by ClientIpService. By default that is the peer IP (REMOTE_ADDR), which behind a proxy is the proxy IP, not the end-user IP. Set mcpTrustedProxies to your proxy IPs / CIDRs and the service walks the X-Forwarded-For chain from the right, skipping trusted hops, and logs the first untrusted address (the real client). When mcpTrustedProxies is empty, X-Forwarded-For is ignored entirely, so a client cannot spoof its IP in the audit log by sending the header itself.

Webserver setup

The MCP endpoint authenticates every request with an Authorization: Bearer <token> header. Several PHP setups do not hand that header on to PHP. The endpoint then answers 401 although the token is valid, while discovery and the OAuth token endpoints (which read the request body) keep working.

Apache (.htaccess, mod_php / FCGI): the web-root .htaccess needs this rewrite, next to TYPO3's other rewrite rules after RewriteEngine On:

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]

TYPO3's default .htaccess ships these two lines, but they get lost easily when the file is customised or replaced by a hosting template, so check for them.

Nginx (php-fpm): nginx reads no .htaccess. Forward the header explicitly in the location that passes requests to PHP:

location ~ \.php$ {
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
    # ... your existing fastcgi_params include
}

Also raise client_max_body_size to at least the MCP body cap (1 MB) plus margin for batch payloads; 8m is a safe default.

Systems behind HTTP Basic Auth

Sites are often shielded with HTTP Basic Auth (.htaccess / AuthType Basic), staging environments, internal instances, not-yet-launched sites, and so on. This collides with the MCP server, because Basic Auth and the MCP endpoint both use the same Authorization request header: Basic Auth sends Authorization: Basic …, while the MCP endpoint requires Authorization: Bearer <token>. A request can carry only one Authorization header, so a connector placed behind Basic Auth fails: the webserver answers 401 before PHP ever runs (the request never reaches McpServerMiddleware, so there is also no entry in aisuite_mcp.log).

You can run MCP on a Basic-Auth-protected system, but the MCP paths must be carved out. The server's own OAuth 2.1 + Bearer-token auth then provides the protection on those paths.

Which paths must be reachable without Basic Auth:

• /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource: OAuth discovery (RFC 8414 / 9728); the client fetches these first.
• /.well-known/openid-configuration: the RFC 8414 §5 fallback path, serving the same document as oauth-authorization-server. Several clients probe it first, so it needs the same exemption.
• /aisuite-mcp/oauth/*: the OAuth flow. The interactive login on /aisuite-mcp/oauth/authorize is the TYPO3 backend login (the actual "log in" step), so Basic Auth must not mask it.
• /aisuite-mcp (and sub-paths), the MCP endpoint itself; its Bearer-token auth already protects it (every token is bound to a concrete BE user with enforced permissions).

Apache (.htaccess)

⚠️ Do not use <Location> / <LocationMatch> for this; they are only valid in the server / vhost configuration. Placing them in .htaccess triggers 500 Internal Server Error (<Location> not allowed here in the Apache error log). Use the Require expr / SetEnvIf forms below.

1. Match on %{THE_REQUEST}, not Request_URI. On TYPO3, the front-controller rewrite rewrites the request to index.php before the authorization phase runs, so SetEnvIf Request_URI … / <If "%{REQUEST_URI} …"> no longer see the original path and silently fail to match. %{THE_REQUEST} is the verbatim original request line (e.g. GET /.well-known/oauth-authorization-server HTTP/1.1) and stays stable across internal rewrites, so always key the exemptions off it.

In the web-root .htaccess, combine your existing Basic Auth with <RequireAny> and exempt the MCP paths via Require expr. Adjust AuthUserFile to your setup and replace your current Require valid-user line with this block:

AuthType Basic
AuthName "Restricted"
AuthUserFile /path/to/.htpasswd

<RequireAny>
    Require expr %{THE_REQUEST} =~ m#\s/\.well-known/(oauth-|openid-configuration)#
    Require expr %{THE_REQUEST} =~ m#\s/aisuite-mcp#
    Require valid-user
</RequireAny>

A request to an MCP path matches one of the Require expr lines and passes without Basic Auth; everything else falls back to Require valid-user.

2. If the host gates access via an env flag (e.g. Deny from env=SECURED), exempt the MCP paths from that flag too. Some managed hosts (and TYPO3's own staging recipe) protect the site with a pattern like:

SetEnvIf Host staging\.example\.com$ SECURED=yes
# … later, inside the auth block:
Order allow,deny
Allow from all
Deny from env=SECURED

This host-based Deny is evaluated independently of the <RequireAny> above and will still 403 the MCP/discovery paths (often only the dot-paths visibly fail, while /aisuite-mcp appears to work, an artifact of mixing legacy Satisfy/Order/Allow/Deny with Require). Unset the flag for the MCP paths, right after it is set:

SetEnvIf Host staging\.example\.com$ SECURED=yes
# Exempt OAuth discovery + MCP endpoint from the staging guard:
SetEnvIfExpr "%{THE_REQUEST} =~ m#\s/(\.well-known/(oauth-|openid-configuration)|aisuite-mcp)#" !SECURED

(Again THE_REQUEST, not Request_URI: and SetEnvIfExpr because SetEnvIf cannot match THE_REQUEST.)

3. Make sure the Authorization-header rewrite is present (see Webserver setup above):

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]

TYPO3's default .htaccess ships it, but verify it survived customisation; without it the Bearer header never reaches PHP and the MCP endpoint returns 401 even though discovery and the OAuth flow work.

Nginx

Nginx has no per-directory configuration, so the exemption is expressed as a map that switches the realm off for the MCP paths. Define it at http level and reference it from the server block:

map $request_uri $auth_realm {
    default                              "Restricted Area";
    ~^/aisuite-mcp                       "off";
    ~^/\.well-known/oauth-               "off";
    ~^/\.well-known/openid-configuration "off";
}

server {
    # ...
    auth_basic           $auth_realm;
    auth_basic_user_file /etc/nginx/.htpasswd;
}

auth_basic accepts a variable, and the literal value off disables the check for that request. That is the only way to relax Basic Auth per URI without rebuilding the location structure.

Use prefix regexes, not exact paths. $request_uri is the raw request target including the query string, so an exact key such as "/aisuite-mcp/oauth/authorize" never matches: the authorize call always arrives as /aisuite-mcp/oauth/authorize?response_type=code&client_id=…&state=…. This fails in a way that reads as partial success, because discovery and /aisuite-mcp/health are requested without a query string and do match, so the connector completes discovery and then dies at the login step. ~^/aisuite-mcp covers the transport endpoint, /health and all four /oauth/… endpoints in one line.

Also confirm that the Authorization header reaches PHP (see Webserver setup above). Both problems produce a 401, and the response tells them apart:

The rest of the site stays behind Basic Auth; only the MCP surface is opened up, and it remains protected by OAuth. To verify, curl the discovery URLs and the endpoint:

curl -i "https://<host>/.well-known/oauth-protected-resource"     # expect 200 JSON
curl -i "https://<host>/.well-known/oauth-authorization-server"   # expect 200 JSON
curl -i "https://<host>/.well-known/openid-configuration"         # expect 200 JSON
curl -i "https://<host>/aisuite-mcp/health"                       # expect 200 JSON
curl -i "https://<host>/aisuite-mcp/oauth/authorize?response_type=code&client_id=x&state=aaaaaaaaaaaaaaaaaaaaaa"
curl -i "https://<host>/typo3/"                                   # expect 401 WWW-Authenticate: Basic

The authorize call is the one that must not be skipped: it is the only request here carrying a query string, which is what an exact-match exemption fails on. What it answers does not matter, the dummy client_id will be rejected; what matters is that the response carries no WWW-Authenticate: Basic. The last call proves the rest of the site is still protected.

A 403 here means an env-flag guard (Apache step 2) or a host-level dot-path block is still catching the path; a 401 with WWW-Authenticate: Basic means the Basic-Auth exemption is not matching: on Apache, check that it keys off THE_REQUEST, on nginx that the map uses prefix regexes.

Scheduled maintenance

ai-suite-mcp:cleanup is required in production, not optional. Run it via TYPO3 Scheduler or system cron at least hourly. It removes:

• authorization codes older than 10 min
• access tokens that expired more than 37 days ago (a fixed cutoff, independent of mcpTokenLifetimeDays)
• revoked tokens created more than 30 days ago: hard-deleted from tx_aisuite_oauth_tokens to meet GDPR right-to-erasure expectations. Until then revoked entries (deleted = 1) stay, so refresh-token reuse detection can still recognise a rotated token; after that window the signal is moot
• session files under var/aisuite_mcp_sessions/ older than twice mcpSessionTimeoutSeconds, at least one hour (one hour at the default of 1800 s)
• background-task files under var/mcp_tasks/ older than 30 days

Watch the session directory in particular: a stateless MCP client leaves one file behind per request, so the count climbs quickly on a busy site. The Reports module shows it as MCP Session Store and turns to a warning above 500 files; readServerInfo reports the same number and logs a warning at WARNING level once the threshold is crossed.

Without it, the authorization-code table grows unbounded, on-disk session and task directories balloon, and revoked or expired tokens accumulate in tx_aisuite_oauth_tokens. For high-volume sites (>100 concurrent users) monitor row counts in tx_aisuite_oauth_tokens and tighten mcpTokenLifetimeDays if growth outpaces the cleanup cycle.

Runtime & scaling

• PHP runtime: the extension targets a classic PHP-FPM / mod_php request lifecycle (one request per process). It is not validated on persistent-worker runtimes such as FrankenPHP or RoadRunner: an in-process, per-instance cache (AbstractTool::$readablePageIdsCache) assumes the process ends with the request, and reusing it across users in a long-lived worker could leak read-access decisions between backend users. Do not run the MCP server on a persistent-worker SAPI until that cache is moved to request scope.
• Multi-host / load-balanced setups: MCP transport sessions (var/aisuite_mcp_sessions/) and background-task results (var/mcp_tasks/) live on the local filesystem. Across multiple app nodes you therefore need either sticky sessions (pin a client to one node) or a shared filesystem for those two directories. OAuth state itself lives in the database and is shared automatically; only the on-disk session/task state needs this treatment.

Logging & retention

Two dedicated log files are configured for the AutoDudes.AiSuiteMcp namespace in ext_localconf.php:

• var/log/aisuite_mcp.log: INFO+ (verbose, full trace). Useful for forensic debugging and per-request audit replay. Toggleable via the mcpLogVerbose extension setting (default: on). Disable in mature production deployments to reduce I/O and PII surface; the WARNING+ alert log stays active either way.
• var/log/aisuite_mcp_warnings.log: WARNING+ only. Always active. Stays small; if it is non-empty, something is worth investigating (rate-limit hits, tool execution failures, OAuth misconfigurations). Designed for monitoring / paging; point your log shipper or tail -F here in production.

What gets logged:

• OAuth events (token issued, refreshed, revoked) with client_id, BE-user UID, and (real) client IP
• MCP responses: status code, response headers and the first 500 characters of the response body, plus the request method, JSON-RPC method, tool name and the first 500 characters of the tool arguments (the raw first 300 characters when the body is not JSON). Arguments and responses routinely contain user prompts, page content snippets, file metadata, etc.
• Tool execution errors with full exception traces

Before an entry is written, Bearer tokens become Bearer [REDACTED], 64-character hex hashes [REDACTED-HASH64] and email addresses [REDACTED-EMAIL]. mcpLogRedactionPatterns (default empty) adds your own patterns on top, replaced with [REDACTED]: comma-separated regular expressions without delimiters. Each pattern is wrapped in /…/, so escape a / inside it; an invalid pattern is skipped silently. ChEddi's log applies them as well.

Outbound network egress

MCP tools that use AI (generate*, translate*, batch*, audit*) inherit the network configuration of the parent autodudes/ai-suite extension. Outbound HTTPS is required to:

• the AI Suite Server configured in AI Suite (aiSuiteServer); it reaches the AI providers, also with your own keys, so TYPO3 itself does not call provider hosts
• every remote URL uploadMedia is asked to download, unless mcpMediaAllowUrlFetch = 0

In hardened environments with strict egress firewalls, allowlist the AI Suite Server host, and decide deliberately whether uploadMedia may fetch from the internet.

Feedback

We're actively shaping this extension and the upcoming public custom-tool API. If you try it out, especially against a real editorial workflow, we'd love to hear from you:

• 🐛 Bugs / regressions → please file an issue with the relevant aisuite_mcp_warnings.log excerpt and the connector you used.
• 💡 Tool gaps → if you reached for a tool that doesn't exist (a third-party table you'd like discoverable, a workflow not covered by the built-ins), tell us what the LLM should have been able to do. This is the most valuable feedback for the AbstractCustomTool API design.
• 🔌 New connectors → if your favourite MCP client isn't in Connectors/, share the redirect URI / origin / auth flow it expects and we'll add a guide.
• 🔒 Security findings → please contact us directly rather than opening a public issue.

The fastest way to reach us is the #ai-suite channel on TYPO3 Slack. You can also reach us via service@autodudes.de.

License

GPL-2.0-or-later