---
title: "Troubleshooting"
manual: "WebMCP tool for TYPO3"
version: "0.4"
permalink: "https://docs.typo3.org/permalink/neoblack/webmcp:troubleshooting@0.4"
source: "Troubleshooting/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.

# Troubleshooting {#troubleshooting}

Everything in the extension degrades silently on purpose — a missing manifest,
an absent `ModelContext` or a malformed config simply registers nothing. That
is good for visitors but means failures are quiet. Expand the symptom that
matches and work through the checks in order.

**No tools are registered**

Check, from the outside in:

1.  **Is the JSON block on the page?** View source and look for
    `<script type="application/json" id="webmcp-config">`. In the
    console:

    **Console — read the config block**

    ```javascript
    document.getElementById('webmcp-config')?.textContent
    ```

    Empty or missing → the manifest was not rendered. Verify the Fluid
    snippet (Step 2 in [Quickstart](https://docs.typo3.org/permalink/neoblack/webmcp:quickstart@0.4)) is in your template and that the
    variable name matches the data processor's `as` (default
    `webmcpConfigJson`).
1.  **Does the block contain your tool?**

    **Console — list the registered tools**

    ```javascript
    JSON.parse(document.getElementById('webmcp-config').textContent).tools
    ```

    Empty array → no provider yielded a manifest. Either the provider is
    not registered (see the next item) or its `manifest()` returned
    `null` for this request.
1.  **Is the runtime loaded?** Confirm `webmcp.js` is included in
    the page footer (the `includeJSFooter` TypoScript).
1.  **Is there a ModelContext to register against?**

    **Console — check for an agent surface**

    ```javascript
    document.modelContext || navigator.modelContext
    ```

    `undefined` in both → the browser has no agent surface. This is
    expected in a normal browser; the runtime intentionally does nothing.
    See "The WebMCP API is not available in Chrome" below. Only
    `navigator.modelContext` set and
    [legacyNavigatorFallback](https://docs.typo3.org/permalink/neoblack/webmcp:confval-dataprocessor-legacynavigatorfallback@0.4) off → nothing is
    registered by design.
1.  **Is the page inside an iframe?** Tools are only registered in the
    top-level document.

**A tool is missing / "duplicate name" error in the console**

The runtime registers each tool on its own. If one registration fails,
only that tool is skipped and the console shows **one** warning naming
it, for example:

```text
[webmcp] Tool "search_articles" was not registered: InvalidStateError: …
```

Common causes:

-   **Another script already registered the same name.** The
    specification rejects a duplicate name. Check other WebMCP scripts
    on the page (a second copy of `webmcp.js`, a chatbot or
    consent widget, a polyfill demo) and rename one of the tools.
-   **Invalid name or description.** Names must be 1–128 characters
    from `A-Z a-z 0-9 _ - .` and the description must not be empty.
    The TYPO3 log contains a warning from the manifest validator when a
    name does not match.
-   **The entry could not be built** (e.g. `options` of a
    `navigate` tool is not a list). Fix the provider's `data`.

Duplicates *within* the manifest are dropped silently: the first entry
with a given name wins.

**A console warning mentions navigator.modelContext**

This warning does **not** come from this extension — the runtime never
logs about it. It is emitted by the browser or by a WebMCP polyfill,
because `navigator.modelContext` is the deprecated location of the
API. The runtime prefers `document.modelContext` and only falls back
to the navigator when the document variant is missing. To avoid the
fallback altogether, set [legacyNavigatorFallback](https://docs.typo3.org/permalink/neoblack/webmcp:confval-dataprocessor-legacynavigatorfallback@0.4) to `0`.

**The WebMCP API is not available in Chrome**

In regular Chrome builds the API is not enabled yet (status as of
2026-10-07, see [Standards and browser support](https://docs.typo3.org/permalink/neoblack/webmcp:standards@0.4)). To test locally:

1.  Use Chrome 149 or newer and enable
    **chrome://flags/#enable-webmcp-testing**, then restart.
1.  Install the [Model Context Tool Inspector](https://github.com/beaufortfrancois/model-context-tool-inspector)
    extension to list and call the tools the page registered.

Visitors only get the API with that flag or when the site takes part in
the Chrome (or Edge) origin trial.

**Tools do not show up in ChatGPT**

According to OpenAI's documentation, site tools are only used by the
**built-in browser of the ChatGPT desktop app**, only for tools of the
**top-level document** (not iframes), and only with specific plans and
models. Check OpenAI's
[WebMCP documentation](https://learn.chatgpt.com/docs/webmcp) for the
current requirements. Each call additionally goes through a safety
review on OpenAI's side, which may block it.

**Tool output ends with "\[Output truncated …\]"**

The text output exceeded [outputLimit](https://docs.typo3.org/permalink/neoblack/webmcp:confval-dataprocessor-outputlimit@0.4) (default 1,500 characters). Return less
text — e.g. lower a search `limitDefault` or shorten the `line`
template — or raise the limit.

**My provider is never called**

The provider is a service tagged `webmcp.tool`. If it is not picked up:

-   Confirm your extension enables autoconfiguration in
    [`Configuration/Services.yaml`](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.html#file-extension-configuration-services-yaml) (`_defaults` with
    `autoconfigure: true`). The tag is inherited from the interface's
    `#[AutoconfigureTag('webmcp.tool')]` only when autoconfiguration is
    on.
-   Otherwise tag the service manually (see the note in [Quickstart](https://docs.typo3.org/permalink/neoblack/webmcp:quickstart@0.4)).
-   Clear the TYPO3 caches after adding a new service.

**A tool depends on an earlier data processor**

Providers receive `$processedData` from data processors that ran
**before** the
`\Neoblack\Webmcp\DataProcessing\ToolManifestProcessor` in the same
content object. If your provider builds on, say, a `MenuProcessor`
output, that processor must have a lower key so it runs first (see the
ordered example in [Configuration](https://docs.typo3.org/permalink/neoblack/webmcp:configuration@0.4)).

**Analytics events are not recorded**

-   **Is analytics enabled?** Check `analyticsEnabled` in the extension
    configuration. When off, `/webmcp-event` is passed through and
    nothing is stored.
-   **Is the tool name whitelisted?** Only names returned by a registered
    provider's `name()` are logged, and `name()` must equal the
    `Manifest` name. A mismatch silently drops the event.
-   **Getting 429s?** You are hitting the rate limit
    (`analyticsRateLimit` calls per IP per minute). Raise it or set
    `0` to disable — see [Analytics](https://docs.typo3.org/permalink/neoblack/webmcp:analytics@0.4).
-   **Getting 204 but no row?** A `204` is also returned for cross-site
    posts rejected by the `Sec-Fetch-Site` guard and for the normal
    success path. Confirm the beacon is a genuine same-origin `POST` to
    `/webmcp-event`.

**The manifest looks corrupted or cut off**

Tool values are embedded verbatim inside a `<script>` block. The
processor escapes `< > & ' "` as `\uXXXX` (`JSON_HEX_*`), so a
`</script>` inside an editor-controlled value cannot break out.

> [!WARNING]
> If you see raw HTML entities where you expected characters, do
> **not** disable those flags — decode on read instead.

> [!NOTE]
> **See also**
>
> -   [Quickstart](https://docs.typo3.org/permalink/neoblack/webmcp:quickstart@0.4) – the intended end-to-end setup.
> -   [Configuration](https://docs.typo3.org/permalink/neoblack/webmcp:configuration@0.4) – the exact TypoScript and settings.
> -   [Architecture](https://docs.typo3.org/permalink/neoblack/webmcp:architecture@0.4) – how the pieces connect.