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 (AI Foundation → 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 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)

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

Note

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

Warning

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:

  1. Open Claude Desktop → Settings → Integrations.

  2. Click Add Integration.

  3. Name it (for example TYPO3 DDEV).

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

    https://t3af.ddev.site/mcp

  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 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:

  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 --transport http --server-url https://t3af.ddev.site/mcp

  2. Run it in your terminal.

  3. Open the Inspector UI in the browser (URL printed in the terminal).

  4. Complete OAuth when prompted.

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

  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)

Warning

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

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

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

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

Note

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

  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

See also Configuration and MCP Server.