MCP Server — Testing guide

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 The MCP module derives URLs from your first site configuration. On DDEV this is typically:

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

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 the v1 tools (table_schema, pages_get, content_list, write_table).

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 table_schema, pages_get, content_list, write_table.
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 four v1 tools.
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)
https://<host>/mcp/r/<64-char-hex> (legacy path form)

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 all v1 tools

Use MCP Inspector, Claude, or any connected client. 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) Create (use a test page pid and workspace):

{
  "action": "create",
  "tableName": "tt_content",
  "data": "{\"pid\": 1, \"CType\": \"text\", \"header\": \"MCP test\"}"
}

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 Server for parameter 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 in extension configuration. /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

Home

Get Started

AI Extensions

Templates & Themes

TYPO3 Extensions

MCP Server — Testing guide

Prerequisites

Step 0 — Pre-flight checks (backend module)

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 all v1 tools

Step 5 — Active OAuth Tokens table

Quick test matrix

Troubleshooting

Cleanup after testing

​Prerequisites

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

​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 all v1 tools

​Step 5 — Active OAuth Tokens table

​Quick test matrix

​Troubleshooting

​Cleanup after testing

Prerequisites

Step 0 — Pre-flight checks (backend module)

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 all v1 tools

Step 5 — Active OAuth Tokens table

Quick test matrix

Troubleshooting

Cleanup after testing