This guide walks through end-to-end testing of all three connection methods and every client tab in the backend module (T3AF > MCP Server). Use it for QA, demos, or first-time setup on a local DDEV instance.

Prerequisites

Environment TYPO3 ^13.4 || ^14.3, PHP >= 8.2, typo3/cms-workspaces installed, ns_t3af enabled. Local stack (example)

ddev start ddev composer install ddev exec typo3 cache:flush

Backend access Log in as an admin backend user (for example admin). Site URL

https://<project>.ddev.site/mcp The MCP module derives URLs from your first site configuration. On DDEV this is typically: replace <project> with your DDEV project name throughout this guide.

Optional tools Node.js 18+ — MCP Inspector and mcp-remote Claude Desktop — OAuth remote setup n8n — MCP Client node (self-hosted or cloud) Cursor / VS Code MCP — for CLI or mcp-remote configs

Step 0 — Pre-flight checks (backend module)

Open T3AF > MCP Server.

Workspace - Use the WORKSPACE dropdown (top right). - If you see a yellow “create workspace” notice, click Create MCP workspace (requires permission) or pick Live for read-only smoke tests.
Status bar (top card) Verify:

Server Status → Online
OAuth Endpoints → both oauth-authorization-server and oauth-protected-resource show green checks
Server URL → copy your https://…/mcp URL

Endpoint health (Remote MCP Setup tab) Under MCP endpoint status, all three rows should be green:

MCP endpoint (/mcp returns 401 without auth — that is expected and counts as online)
/.well-known/oauth-authorization-server/mcp
/.well-known/oauth-protected-resource/mcp

Quick curl smoke test # Replace with your site URL BASE=https://t3af.ddev.site

curl -sS -o /dev/null -w ”%{http_code}\n” “$BASE/mcp”

Expected: 401

curl -sS “

BASE/.well-known/oauth-authorization-server/mcp" | head -c 200 curl -sS "

BASE/.well-known/oauth-protected-resource/mcp” | head -c 200

Expected: JSON metadata (HTTP 200)

Enable MCP (if offline) Expand Show advanced → ensure Enable MCP Server is checked → Save.

Cursor IDE — two connection methods

Cursor can connect to the TYPO3 MCP server in two ways. Use one method per server entry — do not mix stdio and URL for the same logical connection. Project stdio (DDEV)

Config file: .cursor/mcp.json in the project root
Transport: stdio via DDEV
Auth: backend user and workspace
Best for: local development in this repository

Global remote URL (HTTP)

Config file: ~/.cursor/mcp.json in the user home directory
Transport: HTTP Streamable at /mcp
Auth: OAuth 2.1 with PKCE (browser)
Best for: any Cursor workspace, including production

Method A — Project stdio via DDEV

Create or edit .cursor/mcp.json in the project root (same directory as .ddev/). Cursor spawns ddev exec … nst3af:mcp:serve when you open this project. Important:

cwd must be the absolute path to the DDEV project root. Without it, ddev may fail with could not find a project.
Use the full command name nst3af:mcp:serve (alias mcp:server works only after TYPO3 caches are warm).
–no-startup-message keeps diagnostics off stdout (stdio MCP reserves stdout for JSON-RPC).
Adjust –user and `–workspace“ to match your backend user and workspace UID from the MCP module dropdown.

{
  "mcpServers": {
    "TYPO3 DDEV": {
      "command": "ddev",
      "args": [
        "exec",
        "php",
        "vendor/bin/typo3",
        "nst3af:mcp:serve",
        "--no-startup-message",
        "--user=admin",
        "--workspace=3"
      ],
      "cwd": "/absolute/path/to/aiuniverse"
    }
  }
}

Replace /absolute/path/to/aiuniverse with your checkout path (for example /Users/you/projects/aiuniverse). Verify in Cursor: Settings → MCP → TYPO3 DDEV shows Connected and lists Core tools from T3AF (for example table_schema, pages_get, content_list, write_table, plus many others in the Core catalog).

Method B — Global remote URL (OAuth)

For HTTP + OAuth without DDEV stdio, add the server URL to your user-level Cursor config: ~/.cursor/mcp.json. This works from any project; Cursor opens the OAuth flow in the browser on first connect.

{
  "mcpServers": {
    "typo3": {
      "url": "https://t3af.ddev.site/mcp"
    }
  }
}

Replace the host with your site URL from the MCP module Server URL field. Complete OAuth when Cursor prompts. The backend Active OAuth Tokens table should show a new token with an updated Last Used timestamp after tool calls.

Project .cursor/mcp.json (Method A) and global ~/.cursor/mcp.json (Method B) can coexist with different server names — for example TYPO3 DDEV (stdio) and typo3 (URL).

Terminal verification (stdio / DDEV)

Use these checks before relying on Cursor, or when debugging a broken stdio connection. 1. DDEV and TYPO3 CLI

cd /absolute/path/to/aiuniverse
ddev describe   # site should be running
ddev exec php vendor/bin/typo3 list nst3af

Expect nst3af:mcp:cleanup and nst3af:mcp:serve (alias mcp:server). If list nst3af fails, verify with:

ddev exec php vendor/bin/typo3 help nst3af:mcp:serve

2. One-shot initialize (pipe test — recommended) Sends a single JSON-RPC initialize request on stdin and prints the JSON response on stdout. This confirms the server speaks MCP without leaving a process running:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n' \
  | ddev exec typo3 nst3af:mcp:serve --no-startup-message -u admin -w 3

Expected output (one line of JSON on stdout):

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"logging":{},"completions":{},"tools":{}},"serverInfo":{"name":"T3AF MCP Server","version":"1.0.0"}}}

Adjust -u / -w (short for --user / --workspace) to match your config. If you see this JSON, the stdio transport is working; any Cursor issue is likely cwd, command name, or MCP panel cache (restart Cursor). 3. Interactive run (optional)

ddev exec php vendor/bin/typo3 nst3af:mcp:serve --no-startup-message --user=admin --workspace=3

The process waits on stdin after startup — that is normal. It is not “stuck”; it expects JSON-RPC from an MCP client. Diagnostics go to stderr (use -v or -vv for more detail). Stop with Ctrl+C.

A manual terminal session and Cursor each spawn their own process. A successful pipe test does not require a terminal server to stay open for Cursor — Cursor starts its own ddev exec … when the project loads.

Method 1 — Remote MCP Setup (HTTP + OAuth / Bearer)

Recommended for production-like clients. Transport: HTTP Streamable at {site}/mcp. Authentication options:

OAuth 2.1 + PKCE — Claude Desktop, MCP Inspector, generic OAuth clients
Bearer token — n8n, Manus (create token in the module UI)

Default scopes (advanced settings): mcp:read mcp:write mcp:tools

Claude Desktop (OAuth)

In the module: Remote MCP Setup → Claude Desktop tab. Steps:

Open Claude Desktop → Settings → Integrations.
Click Add Integration.
Name it (for example TYPO3 DDEV).
Paste Server URL from the module, e.g.: https://t3af.ddev.site/mcp
Save. Claude starts OAuth automatically (browser window / system prompt).
Approve access as your TYPO3 backend user.

Verify:

Ask Claude to list MCP tools or call table_schema with tableName: pages.
In the module, Active OAuth Tokens shows a new row; Last Used updates.

Example prompt:

Use the TYPO3 MCP tool table_schema for table "pages" and summarize the fields.

n8n (Bearer token)

In the module: Remote MCP Setup → n8n tab. Steps:

Click Create n8n token (if no active token is shown).
Copy the Bearer token immediately (full value is only shown once; the UI stores it in the browser session for copy).
In n8n, add an MCP Client node to a workflow.
Configure the MCP Client node:

Endpoint — https://t3af.ddev.site/mcp
Server Transport — HTTP Streamable
Authentication — Bearer Auth
Bearer Token — paste the token from step 2

Save and Execute workflow.

Verify:

Node connects without 401 errors.
Tool list includes Core tools such as table_schema, pages_get, content_list, and write_table (the Core catalog contains many more).
Active OAuth Tokens table shows client n8n token.

Manus (Bearer token)

In the module: Remote MCP Setup → Manus tab. Steps:

Click Create manus token and copy the Bearer token.
In Manus, add a new MCP server connection.
Configure the connection:

Server Name — your TYPO3 site name
Transport — HTTP
Server URL — https://t3af.ddev.site/mcp
Authorization — header Authorization: Bearer <token>

Save the connection.

Verify: Same as n8n — tool calls succeed and token appears in Active OAuth Tokens.

MCP Inspector (OAuth)

In the module: Remote MCP Setup → MCP Inspector tab. Steps:

Copy the pre-filled command (requires Node.js): npx @modelcontextprotocol/inspector —transport http —server-url https://t3af.ddev.site/mcp
Run it in your terminal.
Open the Inspector UI in the browser (URL printed in the terminal).
Complete OAuth when prompted.
Use the Tools panel to invoke table_schema: { “tableName”: “pages” }

Verify:

tools/list returns the Core tool catalog (many tools, not a short fixed set).
table_schema returns JSON with pages field metadata.

Other OAuth-capable clients

In the module: Remote MCP Setup → Other tab. Generic checklist:

Add a remote MCP server in your client.
Server URL: https://t3af.ddev.site/mcp
Transport: HTTP Streamable (when available).
Auth: OAuth 2.1 + PKCE if supported; otherwise create a Bearer token under the n8n or Manus tabs.

Cursor: see Cursor IDE — two connection methods for project stdio (DDEV) and global URL (OAuth) setup, plus terminal verification.

Method 2 — Local Setup (mcp-remote)

For MCP clients that only speak stdio (no native HTTP). The mcp-remote npm package bridges stdio ↔ your TYPO3 HTTP endpoint. Token in URL After creating a token, the server accepts: https://<host>/mcp?token=<64-char-hex> (recommended in UI) and the legacy form https://<host>/mcp/r/<64-char-hex>.

URL tokens are as sensitive as passwords. Do not commit them to git or share in screenshots.

In the module: click Local Setup (mcp-remote).

Step-by-step

Click Create mcp-remote Token (if none exists).
Copy Token URL (includes ?token=…).
Copy Example mcp-remote configuration or build manually: { “mcpServers”: { “New TYPO3 site”: { “command”: “npx”, “args”: [ “mcp-remote”, “https://t3af.ddev.site/mcp?token=YOUR_64_CHAR_TOKEN” ] } } }
Paste into your client’s MCP config:

Claude Desktop: claude_desktop_config.json → mcpServers
Cursor: .cursor/mcp.json
VS Code: MCP extension settings

Restart the client so it spawns npx mcp-remote ….

Verify:

# Optional: run bridge manually to see logs
npx mcp-remote "https://t3af.ddev.site/mcp?token=YOUR_TOKEN"

Client lists TYPO3 tools.
Active OAuth Tokens shows mcp-remote token with updated Last Used.

Method 3 — Local Setup (TYPO3 CLI)

Direct stdio transport — no HTTP, no OAuth. The MCP client must run on the same machine as TYPO3 (or inside the DDEV web container). In the module: click Local Setup (TYPO3 CLI).

Example configuration

Copy from the module or use:

{
  "mcpServers": {
    "New TYPO3 site": {
      "command": "php",
      "args": [
        "vendor/bin/typo3",
        "nst3af:mcp:serve",
        "--no-startup-message"
      ]
    }
  }
}

The short alias mcp:server also maps to nst3af:mcp:serve when TYPO3 command caches are up to date.

Step-by-step (DDEV)

For Cursor, prefer the full walkthrough in Cursor IDE — two connection methods.
For other MCP clients, use DDEV from the host with an absolute cwd: { “mcpServers”: { “TYPO3 DDEV”: { “command”: “ddev”, “args”: [ “exec”, “php”, “vendor/bin/typo3”, “nst3af:mcp:serve”, “—no-startup-message”, “—user=admin”, “—workspace=3” ], “cwd”: “/absolute/path/to/aiuniverse” } } }
Terminal verification: see Cursor IDE — two connection methods (pipe test and expected initialize JSON).
CLI options:

–user / -u — Backend username (default admin).
–workspace / -w — Workspace UID (0 = live).
–no-startup-message — Suppress stderr banner (recommended for MCP).
-v / -vv — Verbose stderr diagnostics.

Verify:

MCP client connects without HTTP/OAuth.
Invoke pages_get with uid: 1 (adjust to a page that exists).

Restart the CLI server after PHP code changes. Long-running processes may accumulate memory — restart periodically during heavy testing.

Step 4 — Test Core tools

Use MCP Inspector, Claude, or any connected client. The TYPO3 Core tab contains many tools — do not assume only four exist. Browse the full catalog in T3AF > MCP Tools, then smoke-test a few representative calls. Starter checks: table_schema Input: { "tableName": "pages" } Expect: JSON with field definitions. pages_get Input: { "uid": 1 } Expect: Page record (or error if uid missing). content_list Input: { "pid": 1, "limit": 5 } Expect: Array of tt_content rows for that page. write_table (workspace recommended)

{ “action”: “create”, “tableName”: “tt_content”, “data”: ”{“pid”: 1, “CType”: “text”, “header”: “MCP test”}” } Create (use a test page pid and workspace): Expect: JSON with uid, fields, and ignoredFields. Verify with content_list on the same pid. Use action: delete with the new uid to clean up.

Workspace testing Select a non-live workspace in the module dropdown before issuing tokens. Repeat content_list / pages_get — draft overlays should differ from live. See MCP Tools for the full Core catalog and MCP Server for connection details.

Step 5 — Active OAuth Tokens table

After each test, confirm in Active OAuth Tokens:

Client Name — n8n token, OAuth client name, and similar labels.
Created / Last Used — Updates on successful calls.
Expires — Reasonable future date.
Workspace — Matches dropdown selection.
Token — Preview plus Copy Token.
Action — Revoke removes access.

Header actions:

Refresh — reload table via AJAX
Revoke All — invalidates every token for your backend user (confirm dialog)

Quick test matrix

Use this checklist when regression-testing a release: Remote HTTP clients (Claude, n8n, Manus, MCP Inspector, other OAuth clients)

Endpoint health is green.
tools/list works.
table_schema works.
Token appears in the connections table.

mcp-remote bridge

Create token URL.
npx mcp-remote bridge connects.
Client stdio config lists tools.

TYPO3 CLI / Cursor stdio

nst3af:mcp:serve starts.
Pipe initialize test returns JSON.
Cursor project cwd is set.
--user and --workspace match your backend user.
Tool invocation succeeds.

Cursor URL (~/.cursor/mcp.json)

OAuth at /mcp completes.
Token appears in the connections table.

Troubleshooting

Server Status Offline Enable MCP in Show advanced. Run ddev exec typo3 cache:flush. /mcp returns 503 enableMcpServer is off (MCP Server → Advanced, or T3AF MCP settings). /mcp returns 401 without token Expected — proves middleware is reachable. Authenticate with OAuth or Bearer. OAuth metadata checks red Verify site base URL, HTTPS, and that config/sites/*/config.yaml routes exist. Flush caches. Bearer / URL token Authentication failed Token revoked, expired, or wrong workspace. Create a new token in the module. mcp-remote client shows no tools Confirm Node.js is installed, URL includes valid ?token=, restart client. CLI Backend user not found Pass --user= <../existing-be-username>. Tool returns empty / wrong data Check WORKSPACE dropdown and token workspace pin. Full token not copyable later Plaintext is only shown at issuance. Revoke and re-create, or use OAuth flow.

Cleanup after testing

Revoke test tokens in Active OAuth Tokens (or Revoke All).
Remove MCP entries from claude_desktop_config.json / .cursor/mcp.json.
Optional maintenance: ddev exec vendor/bin/typo3 nst3af:mcp:cleanup

Additional examples from live documentation

ddev
 
start
ddev
 
composer
 
install
ddev
 
exec
 
typo3
 
cache:flush

https://<project>.ddev.site/mcp

# Replace with your site URL

BASE
=
https://t3af.ddev.site

curl
 
-sS
 
-o
 
/dev/null
 
-w
 
"%{http_code}\n"
 
"
$BASE
/mcp"

# Expected: 401

curl
 
-sS
 
"
$BASE
/.well-known/oauth-authorization-server/mcp"
 
|
 
head
 
-c
 
200

curl
 
-sS
 
"
$BASE
/.well-known/oauth-protected-resource/mcp"
 
|
 
head
 
-c
 
200

# Expected: JSON metadata (HTTP 200)

{

"mcpServers"
:
 
{

"TYPO3 DDEV"
:
 
{

"command"
:
 
"ddev"
,

"args"
:
 
[

"exec"
,

"php"
,

"vendor/bin/typo3"
,

"nst3af:mcp:serve"
,

"--no-startup-message"
,

"--user=admin"
,

"--workspace=3"

],

"cwd"
:
 
"/absolute/path/to/aiuniverse"

}

}

}

{

"mcpServers"
:
 
{

"typo3"
:
 
{

"url"
:
 
"https://t3af.ddev.site/mcp"

}

}

}

{
"jsonrpc"
:
"2.0"
,
"id"
:
1
,
"result"
:{
"protocolVersion"
:
"2025-06-18"
,
"capabilities"
:{
"logging"
:{},
"completions"
:{},
"tools"
:{}},
"serverInfo"
:{
"name"
:
"T3AF MCP Server"
,
"version"
:
"1.0.0"
}}}

npx
 
@modelcontextprotocol/inspector
 
--transport
 
http
 
--server-url
 
https://t3af.ddev.site/mcp

{

"tableName"
:
 
"pages"

}

{

"mcpServers"
:
 
{

"New TYPO3 site"
:
 
{

"command"
:
 
"npx"
,

"args"
:
 
[

"mcp-remote"
,

"https://t3af.ddev.site/mcp?token=YOUR_64_CHAR_TOKEN"

]

}

}

}

{

"mcpServers"
:
 
{

"New TYPO3 site"
:
 
{

"command"
:
 
"php"
,

"args"
:
 
[

"vendor/bin/typo3"
,

"nst3af:mcp:serve"
,

"--no-startup-message"

]

}

}

}

{

"action"
:
 
"create"
,

"tableName"
:
 
"tt_content"
,

"data"
:
 
"{\"pid\": 1, \"CType\": \"text\", \"header\": \"MCP test\"}"

}

ddev
 
exec
 
vendor/bin/typo3
 
nst3af:mcp:cleanup

Home

Get Started

AI Extensions

Templates & Themes

TYPO3 Extensions

MCP Server — Testing guide

Prerequisites

Step 0 — Pre-flight checks (backend module)

Expected: 401

Expected: JSON metadata (HTTP 200)

Cursor IDE — two connection methods

Method A — Project stdio via DDEV

Method B — Global remote URL (OAuth)

Terminal verification (stdio / DDEV)

Method 1 — Remote MCP Setup (HTTP + OAuth / Bearer)

Claude Desktop (OAuth)

n8n (Bearer token)

Manus (Bearer token)

MCP Inspector (OAuth)

Other OAuth-capable clients

Method 2 — Local Setup (mcp-remote)

Step-by-step

Method 3 — Local Setup (TYPO3 CLI)

Example configuration

Step-by-step (DDEV)

Step 4 — Test Core tools

Step 5 — Active OAuth Tokens table

Quick test matrix

Troubleshooting

Cleanup after testing

Additional examples from live documentation

​Prerequisites

​Step 0 — Pre-flight checks (backend module)

​Expected: 401

​Expected: JSON metadata (HTTP 200)

​Cursor IDE — two connection methods

​Method A — Project stdio via DDEV

​Method B — Global remote URL (OAuth)

​Terminal verification (stdio / DDEV)

​Method 1 — Remote MCP Setup (HTTP + OAuth / Bearer)

​Claude Desktop (OAuth)

​n8n (Bearer token)

​Manus (Bearer token)

​MCP Inspector (OAuth)

​Other OAuth-capable clients

​Method 2 — Local Setup (mcp-remote)

​Step-by-step

​Method 3 — Local Setup (TYPO3 CLI)

​Example configuration

​Step-by-step (DDEV)

​Step 4 — Test Core tools

​Step 5 — Active OAuth Tokens table

​Quick test matrix

​Troubleshooting

​Cleanup after testing

​Additional examples from live documentation

Prerequisites

Step 0 — Pre-flight checks (backend module)

Expected: 401

Expected: JSON metadata (HTTP 200)

Cursor IDE — two connection methods

Method A — Project stdio via DDEV

Method B — Global remote URL (OAuth)

Terminal verification (stdio / DDEV)

Method 1 — Remote MCP Setup (HTTP + OAuth / Bearer)

Claude Desktop (OAuth)

n8n (Bearer token)

Manus (Bearer token)

MCP Inspector (OAuth)

Other OAuth-capable clients

Method 2 — Local Setup (mcp-remote)

Step-by-step

Method 3 — Local Setup (TYPO3 CLI)

Example configuration

Step-by-step (DDEV)

Step 4 — Test Core tools

Step 5 — Active OAuth Tokens table

Quick test matrix

Troubleshooting

Cleanup after testing

Additional examples from live documentation