MCP Server — Testing guide 

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

Copied!

Backend access

Log in as an admin backend user (for example admin).

Site URL

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

Copied!

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 AI Foundation > MCP Server.

1. 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.

2. 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

3. 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

4. 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)

   Copied!
5. 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 AI Foundation (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.

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":"AI Foundation 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.

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 and Manus (create the token in that client's setup tab). Other clients use Create personal token on the Connect screen. Opening that screen does not create a token. See Personal bearer token.

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

Claude Desktop (OAuth) 

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

Steps:

1. Open Claude Desktop → Customize → Connectors.
2. Click Add connector.
3. Name it (for example TYPO3 DDEV).

4. Paste Server URL from the module, e.g.:

   https://t3af.ddev.site/mcp

   Copied!
5. Save. Claude starts OAuth automatically (browser window / system prompt).
6. 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:

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

4. 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
5. 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:

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

3. Configure the connection:

   • Server Name — your TYPO3 site name
   • Transport — HTTP
   • Server URL — https://t3af.ddev.site/mcp
   • Authorization — header Authorization: Bearer <token>
4. 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:

1. Copy the pre-filled command (requires Node.js):

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

   Copied!
2. Run it in your terminal (Node.js 18+). On DDEV with HTTPS, export NODE_EXTRA_CA_CERTS to your mkcert root CA if needed.
3. Open the Inspector v2 URL printed in the terminal (connect → authenticate).
4. Complete OAuth when prompted.

5. Use Tools or Prompts to invoke table_schema:

   {
     "tableName": "pages"
   }

   Copied!

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:

1. Add a remote MCP server in your client.
2. Server URL: https://t3af.ddev.site/mcp
3. Transport: HTTP Streamable (when available).
4. 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)

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

Step-by-step 

1. Click Create mcp-remote Token (if none exists).
2. Copy Token URL (includes ?token=…).

3. 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"
         ]
       }
     }
   }

   Copied!

4. Paste into your client’s MCP config:

   • Claude Desktop: claude_desktop_config.json → mcpServers
   • Cursor: .cursor/mcp.json
   • VS Code: MCP extension settings
5. 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) 

1. For Cursor, prefer the full walkthrough in Cursor IDE — two connection methods.

2. 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"
       }
     }
   }

   Copied!
3. Terminal verification: see Cursor IDE — two connection methods (pipe test and expected initialize JSON).

4. 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).

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 AI Foundation > 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\"}"
}

Copied!

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 AI Foundation 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 

1. Revoke test tokens in Active OAuth Tokens (or Revoke All).
2. Remove MCP entries from claude_desktop_config.json / .cursor/mcp.json.

3. Optional maintenance:

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

   Copied!

See also Configuration and MCP Server.