---
title: "Configuration"
manual: "WebMCP tool for TYPO3"
version: "0.4"
permalink: "https://docs.typo3.org/permalink/neoblack/webmcp:configuration@0.4"
source: "Configuration/Index.rst"
rendered: "2026-10-07T22:31:54+00:00"
---

> [!WARNING]
> **Experimental.** This extension is experimental and not yet ready for
> production use. It is built on top of
> [WebMCP](https://github.com/webmachinelearning/webmcp), which is itself
> an experimental, early-stage proposal. Both the underlying specification
> and this extension's API may change or break at any time without notice.
> Use at your own risk.

# Configuration {#configuration}

## Extension configuration {#extension-configuration}

Set these in the TYPO3 backend under **Admin Tools > Settings >
Extension Configuration > neoblack_webmcp** (the defaults live in
[`ext_conf_template.txt`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/ExtConfTemplate.html#file-extension-ext-conf-template-txt)).

-   **analyticsEnabled**

    -   *Type:* boolean
    -   *Default:* 1

    Log each WebMCP tool call (tool name + coarse client hint, no PII) to
    `tx_neoblackwebmcp_event` and expose the backend module. Turn off to
    disable the ingest endpoint (`/webmcp-event` is then passed through).

-   **analyticsRateLimit**

    -   *Type:* integer
    -   *Default:* 60

    Maximum accepted ingest calls per client IP per minute (0 = unlimited).
    Protects the public endpoint against flooding and statistics pollution;
    excess calls are answered with `429 Too Many Requests`. The limiter uses
    the extension's own cache and only stores a hashed, short-lived counter —
    no plaintext IP.

## Wiring the manifest into your site {#wiring-the-manifest-into-your-site}

Three pieces connect the tools to the page. All of them live in your site
package / TypoScript, so you stay in control of *where* the tools are exposed.

### 1\. Emit the manifest {#1-emit-the-manifest}

Add the data processor to the page's `FLUIDTEMPLATE` (or `PAGEVIEW`).

**Page TypoScript — register the data processor**

```typoscript
page.10.dataProcessing {
    # optional: a menu a navigate tool can build on
    35 = menu
    35 {
        entryLevel = 0
        levels = 1
        as = webmcpTopics
    }
    40 = Neoblack\Webmcp\DataProcessing\ToolManifestProcessor
    40 {
        endpoint = /webmcp-event
        # optional, shown with their defaults
        legacyNavigatorFallback = 1
        outputLimit = 1500
        as = webmcpConfigJson
    }
}
```

> [!IMPORTANT]
> If a tool provider relies on an earlier data processor (e.g. a
> `MenuProcessor`), make sure that processor has a lower key so it runs
> *before* the `\Neoblack\Webmcp\DataProcessing\ToolManifestProcessor`.

-   **endpoint**

    -   *Type:* string
    -   *Default:* /webmcp-event

    Analytics beacon target written into the manifest.

-   **legacyNavigatorFallback**

    -   *Type:* boolean
    -   *Default:* 1

    Whether the runtime may fall back to the deprecated
    `navigator.modelContext` when `document.modelContext` is not
    available. The specification only defines `document.modelContext`;
    the navigator location is still served by older Chrome origin trial builds
    and by polyfills. Set to `0` to register against
    `document.modelContext` only.

    > [!NOTE]
    > The default is planned to change to `0` — and the fallback to be
    > removed — once Chrome and the common polyfills drop the navigator
    > alias. Any console warning about `navigator.modelContext` comes
    > from the browser or a polyfill, never from this extension.

-   **outputLimit**

    -   *Type:* integer
    -   *Default:* 1500

    Maximum number of characters of text a single tool call returns to the
    agent. Longer text is cut and ends with a visible
    `[Output truncated to … characters.]` marker (the marker counts towards
    the limit). `0` disables the cap. The default follows Chrome's
    [Secure tools](https://developer.chrome.com/docs/ai/webmcp/secure-tools)
    recommendation. `structuredContent` is never cut, because truncated JSON
    would be invalid; keep it small via the primitive's own options (e.g. the
    search `limitDefault`).

-   **as**

    -   *Type:* string
    -   *Default:* webmcpConfigJson

    Variable the JSON manifest is assigned to.

### 2\. Render the JSON block {#2-render-the-json-block}

Output the manifest once per page inside a `<script>` tag with the id
`webmcp-config` (the id the runtime looks for):

**Fluid page template — render the JSON block**

```html
<f:if condition="{webmcpConfigJson}">
    <script type="application/json" id="webmcp-config"><f:format.raw>{webmcpConfigJson}</f:format.raw></script>
</f:if>
```

### 3\. Include the runtime {#3-include-the-runtime}

**Page TypoScript — include the runtime**

```typoscript
page.includeJSFooter {
    webmcp = EXT:neoblack_webmcp/Resources/Public/JavaScript/webmcp.js
    webmcp.defer = 1
}
```

## Where tools are registered {#where-tools-are-registered}

The runtime registers tools **only in the top-level document**. When a page is
shown inside an iframe — same-origin or cross-origin — nothing is registered.
This is not configurable: agents such as ChatGPT's built-in browser do not
discover tools in iframes anyway, and a third-party page embedding yours must
not receive its tools.

The extension never sets the specification's `exposedTo` registration option,
so tools are not exposed to other origins.

## Backend module {#backend-module}

When analytics is enabled, the **System > WebMCP** module visualises tool
usage.

> [!NOTE]
> **See also**
>
> [Analytics](https://docs.typo3.org/permalink/neoblack/webmcp:analytics@0.4) describes the module's data model, retention and the
> hardening of the public ingest endpoint.