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.

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 
    document.getElementById('webmcp-config')?.textContent
    Copied!

    Empty or missing → the manifest was not rendered. Verify the Fluid snippet (Step 2 in Quickstart) is in your template and that the variable name matches the data processor's as (default webmcpConfigJson).

  2. Does the block contain your tool?

    Console — list the registered tools 
    JSON.parse(document.getElementById('webmcp-config').textContent).tools
    Copied!

    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.

  3. Is the runtime loaded? Confirm webmcp.js is included in the page footer (the includeJSFooter TypoScript).

  4. Is there a ModelContext to register against?

    Console — check for an agent surface 
    document.modelContext || navigator.modelContext
    Copied!

    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 off → nothing is registered by design.

  5. Is the page inside an iframe? Tools are only registered in the top-level document.

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:

[webmcp] Tool "search_articles" was not registered: InvalidStateError: …
Copied!

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.

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

In regular Chrome builds the API is not enabled yet (status as of 2026-10-07, see Standards and browser support). To test locally:

  1. Use Chrome 149 or newer and enable chrome://flags/#enable-webmcp-testing, then restart.
  2. Install the 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.

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 for the current requirements. Each call additionally goes through a safety review on OpenAI's side, which may block it.

The text output exceeded outputLimit (default 1,500 characters). Return less text — e.g. lower a search limitDefault or shorten the line template — or raise the limit.

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

  • Confirm your extension enables autoconfiguration in 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).
  • Clear the TYPO3 caches after adding a new service.

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

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

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.