Configuration 

All settings are managed via Admin Tools > Settings > Extension Configuration > nr_mcp_agent.

LLM connection 

llmTaskUid

llmTaskUid
Type
int
Default
0

UID of an nr-llm Task record. This Task defines which LLM provider and model to use (e.g. OpenAI GPT-4, Anthropic Claude). Required -- the extension will not work without a valid Task UID.

Create the Task record in the nr-llm backend module first, then enter its UID here.

Processing 

processingStrategy

processingStrategy
Type
string
Default
exec

How chat messages are processed in the background:

exec
Forks a CLI process per request (ai-chat:process). Simple, no extra setup. Best for development and low-traffic sites.
worker
Uses a long-running worker process (ai-chat:worker) that polls for new messages. Better for production -- lower latency, no process forking overhead.

Access control 

allowedGroups

allowedGroups
Type
string
Default
(empty)

Comma-separated list of backend user group UIDs that are allowed to use the AI Chat module. Leave empty to allow all backend users with module access.

MCP integration 

enableMcp

enableMcp
Type
boolean
Default
false

Enable MCP (Model Context Protocol) server integration.

When enabled, the AI assistant can call tools exposed by any configured MCP server. When disabled, it works as a plain chat without tool access.

MCP servers are configured as records in the TYPO3 List module (see MCP server records below).

MCP server records 

MCP servers are configured as database records, not via extension settings. After enabling MCP:

  1. Open the TYPO3 List module and navigate to pid = 0 (the root page).
  2. Create a new record of type MCP Server.

  3. Fill in the fields:

    Name
    Human-readable label (e.g. TYPO3 MCP Server).
    Server key
    Machine identifier used to namespace tools (e.g. typo3). Lowercase letters, digits, and underscores only. Must be unique.
    Transport
    stdio (subprocess via stdin/stdout) or sse (HTTP SSE endpoint — not yet implemented).

    For stdio transport:

    Command
    Path to the MCP server binary. Defaults to vendor/bin/typo3 in the project root.
    Arguments
    One argument per line (e.g. mcp:server).
  4. Save the record. The tool cache is flushed automatically.

Tool names are prefixed with the server key to avoid collisions between servers. For example, a tool named ReadTable on a server with key typo3 becomes typo3__ReadTable in the LLM context.

The connection status fields (read-only) show the last known state of each server connection.

Chat panel 

When llmTaskUid is configured, a chat button appears automatically in the TYPO3 backend toolbar (top right). Clicking it opens a floating bottom panel that stays visible across module navigation.

The panel supports four states:

  • Hidden -- Default. Only the toolbar button is visible.
  • Collapsed -- Minimal header bar showing the active conversation title and status.
  • Expanded -- Resizable panel with chat messages, input, and a compact conversation switcher.
  • Maximized -- Full-height panel with a sidebar for conversation management (search, pin, archive).

The panel height and state are persisted per user in the browser's localStorage.

System prompt 

The system prompt sent to the LLM is not configured in the extension configuration itself, but in the nr-llm records:

Configuration record (tx_nrllm_configuration.system_prompt)

The primary system prompt. Set this to define the AI assistant's persona, language, and behavior. Also use this field for tool usage instructions when MCP is enabled.

Example for MCP usage:

Du bist ein TYPO3-Assistent.

## Tool-Nutzung
- Bei WriteTable gehören Record-Felder IMMER in den
  "data" Parameter als Objekt.
- Beispiel: {"action": "create", "table": "pages",
  "pid": 1, "data": {"title": "Meine Seite"}}
Copied!
Task record (tx_nrllm_task.prompt_template)
Additional instructions appended after the Configuration prompt. Use this for task-specific context.

When both fields are set, they are combined (separated by a blank line). If neither is set, a locale-based default prompt is used. A per-conversation system_prompt field can override everything (set programmatically, not via UI).

User interface 

maxConversationsPerUser

maxConversationsPerUser
Type
int
Default
50

Maximum number of conversations to keep per user. Set to 0 for unlimited. When the limit is reached, the oldest non-pinned conversations are archived automatically.

autoArchiveDays

autoArchiveDays
Type
int
Default
30

Automatically archive conversations that have been inactive for this many days. Set to 0 to disable auto-archiving.

Auto-archiving runs via the ai-chat:cleanup command.

File attachments 

File attachments are always available — no special provider configuration required. Text is extracted server-side for document formats, so they work with any LLM provider.

Always supported (server-side text extraction):

  • PDF: application/pdf — requires smalot/pdfparser (hard dependency)
  • DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document — requires phpoffice/phpword (hard dependency)
  • TXT: text/plain — no dependencies
  • XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — requires phpoffice/phpspreadsheet (optional; install via composer require phpoffice/phpspreadsheet:^3.0)

Additionally available for vision-capable providers (Claude 3+, Gemini, GPT-4o, etc.):

  • Images: image/png, image/jpeg, image/webp

When the provider natively handles a document format (e.g. Claude natively processes PDFs via DocumentCapableInterface), the file is sent as binary instead of being extracted. The file picker automatically restricts to formats the active provider can process.

Storage: Uploaded files are stored in TYPO3 FAL under fileadmin/ai-chat/<be_user_uid>/. They are read at LLM call time and sent as Base64-encoded multimodal content. Each file is stored in a user-specific subfolder; the API enforces that users can only attach their own files (cross-user access attempts return 404).

Limits:

  • Maximum 5 files per conversation.
  • Maximum file size: 20 MB per file.
  • File count is enforced both in the frontend (before upload) and in the backend API.

Security: The fileadmin/ai-chat/ directory should be protected from direct HTTP access. Add the following to your web server configuration or deploy a .htaccess file to fileadmin/ai-chat/:

# fileadmin/ai-chat/.htaccess
Require all denied
Copied!

Security 

maxMessageLength

maxMessageLength
Type
int
Default
10000

Maximum length of a single user message in characters. Set to 0 for unlimited (not recommended).

Messages exceeding this limit are rejected with an error.

maxActiveConversationsPerUser

maxActiveConversationsPerUser
Type
int
Default
3

Maximum number of simultaneously active (processing) conversations per user. Prevents a single user from overloading the system. Set to 0 for unlimited.

Worker mode production setup 

For production use with processingStrategy = worker, set up a systemd service to keep the worker running:

# /etc/systemd/system/typo3-ai-chat-worker.service
[Unit]
Description=TYPO3 AI Chat Worker
After=mysql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/html
ExecStart=/var/www/html/vendor/bin/typo3 \
    ai-chat:worker --poll-interval=200
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
Copied!

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable typo3-ai-chat-worker
sudo systemctl start typo3-ai-chat-worker
Copied!

Scheduled cleanup 

Add the cleanup command to your cron or TYPO3 scheduler to handle stuck conversations, auto-archiving, and deletion of old data:

# Run cleanup daily at 3:00 AM
0 3 * * * /var/www/html/vendor/bin/typo3 \
    ai-chat:cleanup --delete-after-days=90
Copied!