Kai Ole Hartwig
Zwei präzisionsgefertigte gebürstete Aluminium-Stücke treffen sich an einem ingenieurmäßig gefügten Saum auf Eichentisch, weiches Tageslicht von links.
Extension · koh/webmcp

webmcp — the browser MCP for your TYPO3.

Web Model Context Protocol server that exposes tools like search, navigation and page content directly via navigator.modelContext. AI agents use them straight in the browser, with SecureContext checks and a CSRF nonce — no external API needed.

Das Problem

When the AI agent gets stuck because it can't see anything.

With webmcp

  • Standardised navigator.modelContext API directly in the browser
  • Built-in tools: search, navigation, page-content
  • Custom tools registerable via ToolProviderInterface
  • SecureContext + CSRF nonce, FE group-aware

Until now

  • AI agents have to learn external REST/GraphQL APIs
  • Auth tokens, rate limits, caching problems
  • Tools aren't available in the current browser context
  • Every site implements its own tool vocabulary

Four building blocks

Optional: form tool

With typo3/cms-form as an optional dependency, form submission is also exposed as a tool — AI agents can submit enquiries directly.

Secure by default

SecureContext required (HTTPS), CSRF nonce in every tool request, access control via TYPO3 FE groups respected.

Custom tool provider

Register your own tools via ToolProviderInterface — e.g. to expose shop-specific search functions or custom forms.

Built-in tools

search, navigation, page-content — ready to use straight after installation.

Available on Packagist — MIT, source on GitHub

TYPO3: 13.4 – 14.0 · PHP: 8.2+ · Optional: typo3/cms-form (form tool)

composer require koh/webmcp. For help integrating it into your TYPO3 platform, use the contact form.

Configuration

Enable the site set

Include the site set koh/webmcp in your site configuration.

Settings

In config/sites/<site>/settings.yaml:

 

webmcp:
  enabled: true
  apiBasePath: '/_webmcp/api'
  tools:
    search:
      enabled: true
      maxResults: 20
    navigation:
      enabled: true
      maxDepth: 4
    page-content:
      enabled: true

Built-in tools

All tools respect TYPO3 access restrictions (fe_group, starttime, endtime, hidden). Only content visible to the current visitor (anonymous or logged-in) is returned.

ToolDescriptionInput
searchFull-text search across pages and content elements{ query: string, limit?: int }
navigationPage tree as structured JSON{ rootPageId?: int, maxDepth?: int }
page-contentStructured content of a specific page{ pageId?: int, slug?: string }

Building custom tools

1. Implement a ToolProvider

 

<?php

use Koh\WebMcp\Domain\Contract\ToolProviderInterface;
use Koh\WebMcp\Domain\Model\ToolAnnotations;
use Koh\WebMcp\Domain\Model\ToolDefinition;

final class ShopToolProvider implements ToolProviderInterface
{
    public function getIdentifier(): string
    {
        return 'shop';
    }

    public function getTools(): array
    {
        return [
            new ToolDefinition(
                name: 'product-search',
                description: 'Search products in the shop',
                inputSchema: [
                    'type' => 'object',
                    'properties' => [
                        'query' => ['type' => 'string'],
                        'category' => ['type' => 'string'],
                    ],
                    'required' => ['query'],
                ],
                annotations: new ToolAnnotations(readOnlyHint: true),
            ),
        ];
    }
}

 

2. Implement a ToolHandler

 

<?php

use Koh\WebMcp\Domain\Contract\ToolHandlerInterface;
use Koh\WebMcp\Domain\Model\ToolResult;
use Psr\Http\Message\ServerRequestInterface;

final class ProductSearchHandler implements ToolHandlerInterface
{
    public function getToolName(): string
    {
        return 'product-search';
    }

    public function execute(array $input, ServerRequestInterface $request): ToolResult
    {
        // Implement product search ...
        return ToolResult::success(['products' => $results]);
    }
}

 

Both classes are auto-registered via _instanceof tags in Services.yaml — no extra configuration required.

How it works

  1. When a page is rendered, the extension injects JavaScript via AssetCollector.
  2. The JavaScript registers all enabled tools through navigator.modelContext.registerTool().
  3. When an AI agent invokes a tool, the browser sends a POST request to /_webmcp/api/{toolName}.
  4. The PSR-15 middleware validates the request (CSRF nonce, input) and delegates to the matching ToolHandler.
  5. The result is returned as JSON.

Requirements

Source code & documentation

Composer package

composer require koh/webmcp – on Packagist, source on GitHub.

On GitHub
Composer package

Repository

Source code and issues on GitHub. Pull requests are welcome.

ohartwig/webmcp
Repository

Mirror

Development happens on a private GitLab instance. GitHub is the public mirror: every release appears there with its tag, and Packagist reads it from there.

Next step

Help with integration?

webmcp is open source and meant for self-integrators. If you want to integrate webmcp for your specific use case (custom tools, commercial AI agent integration, custom permissions), I'll help on a day rate or as part of my CMS as a Service.

Discuss the integration →

Or email me directly: mail@ole-hartwig.eu