Skip to content

Index.rst

Latest commit

 

History

History
228 lines (162 loc) · 6.9 KB

Index.rst

File metadata and controls

228 lines (162 loc) · 6.9 KB
Raw

Installation

Requirements

  • TYPO3 v14
  • PHP 8.3+
  • TYPO3 backend access for the editors who will use MCP
  • TYPO3 Workspaces extension, installed as a dependency

Recommended prerequisites

Before you connect an MCP client, make sure TYPO3 is already configured with:

  • at least one backend user who can access the relevant page tree
  • table permissions for the records you want MCP to manage
  • a writable workspace, or permission for the extension to create one
  • a reachable base URL for remote clients

Composer installation

Install the extension with Composer:

composer require hn/typo3-mcp-server

Activate the extension:

vendor/bin/typo3 extension:activate mcp_server

The backend module will then be available under :guilabel:`User > MCP Server`.

The project requires logiscape/mcp-sdk-php:^2.0.0-beta3 and the committed lock file currently selects 2.0.0-beta3 while the locked 2026-07-28 protocol release candidate is validated. Test both protocol eras before updating that lock.

First backend check

Open the backend module and verify that you can see:

  • the MCP endpoint URL
  • the main connection setup tabs
  • the remote client setup tabs
  • the active token management area
  • endpoint status indicators for MCP and OAuth discovery URLs

Backend module setup

The backend module is designed around the most common connection flow first.

At the top of the page you get:

  • the remote MCP server URL
  • a copy button for the server URL
  • endpoint health checks for the MCP and OAuth discovery URLs

The client chooser then provides focused setup steps for:

  • Claude Desktop
  • n8n
  • Manus
  • MCP Inspector
  • other MCP clients

Separate top-level tabs also cover:

  • Remote MCP Setup
  • Local Setup (mcp-remote)
  • Local Setup (TYPO3 CLI)

The common path is:

  1. Open :guilabel:`User > MCP Server`.
  2. Copy the server URL.
  3. Choose your client tab.
  4. Follow the short client-specific setup.
  5. Complete OAuth in TYPO3, or create a direct-access token for clients such as n8n or Manus.

Connection options

Remote MCP over OAuth

This is the recommended setup for remote MCP clients.

  1. Open :guilabel:`User > MCP Server`.
  2. Copy the server URL shown in the module.
  3. Add the server URL to your MCP client.
  4. Complete the OAuth flow in TYPO3 when the client requests access.

The module includes setup instructions for multiple client types.

The endpoint serves MCP 2025-11-25 and the 2026-07-28 release candidate. Current Codex, Cursor, and Claude product documentation does not provide a dependable dated revision matrix, so leave stable fallback enabled and test the installed client version. See :doc:`../Architecture/ProtocolMigration`.

Local TYPO3 CLI server

For local development or shell-based MCP clients, use the TYPO3 CLI command.

Example MCP client configuration:

{
  "mcpServers": {
    "my-typo3-site": {
      "command": "php",
      "args": ["vendor/bin/typo3", "mcp:server"]
    }
  }
}

This is convenient for development, but it uses a different trust model than the remote OAuth endpoint.

Caution!

Local stdio and the host (guidance for this maintained distribution): The CLI server runs as the operating-system user that starts it. TYPO3 enforces editorial and table permissions for MCP tools, but it does not sandbox the underlying machine. If your MCP client also exposes a shell or terminal—or you launch the server via bash, sh, or other wrappers—the effective risk includes arbitrary host commands at that user’s privilege level (files, environment secrets, system changes beyond TYPO3). Use this setup only on trusted local or non-production systems, with least-privilege OS accounts and without mixing it with production secrets or unrestricted terminal access.

The same topic is covered technically under Local stdio and the host OS boundary in TECHNICAL_OVERVIEW.md (repository root).

CLI mirror (every tool, every shell)

Every bundled MCP tool is reachable from the TYPO3 CLI, so shell scripts, CI pipelines, and ddev exec can drive the same surface as the MCP endpoint. List what's available:

vendor/bin/typo3 list mcp

Run any registered tool by name:

vendor/bin/typo3 mcp:tool ReadTable --param table=pages --param pid=1 --json
vendor/bin/typo3 mcp:tool:list --schema=ReadTable
vendor/bin/typo3 mcp:prompt:list
vendor/bin/typo3 mcp:prompt:get typo3-content-edit --request='Edit page 42'

Or use one of the shipped per-tool shortcuts:

vendor/bin/typo3 mcp:read-table --table tt_content --pid 1
vendor/bin/typo3 mcp:write-table --action create --table pages --pid 1 --param data='{"title": "X"}'
vendor/bin/typo3 mcp:get-capabilities --json

Output modes:

  • --json — machine envelope {ok, result}
  • --plain or --no-ansi — plain text without decoration
  • (default) — pretty colored output

Use --param key=@payload.json to pass JSON from a file (constrained to the TYPO3 project root). Most dedicated shortcuts are GenericMcpToolCommand service entries in Configuration/Services.yaml; create a custom AbstractMcpToolCommand subclass only when a shortcut needs bespoke options or output formatting.

Bundled Abilities and opt-in REST projection

webconsulting/typo3-abilities and the TYPO3 v14 sg_apicore fork are production dependencies and install with this extension. The five governed abilities are therefore available to CLI after extension:setup. REST and generated OpenAPI remain an explicit operator choice: enable activateAbilitiesApi before exposing /api/abilities/v1. Follow :doc:`../Integration/SgApiCore` for the root-project VCS repository requirement, scopes, and post-install checks.

After installation

Continue with: