Insight UI WebMCP — make your website agent-ready

Bring WebMCP to your Django website with an extension designed for Insight UI. Expose public content, navigation and reviewed actions as explicit tools, while your application keeps control of content, permissions and execution.

DE: Die WebMCP-Erweiterung für Insight UI: Machen Sie die Inhalte und Aktionen Ihrer Django-Webseite für KI-Agenten verständlich und gezielt nutzbar.

Packages at a glance

One browser runtime, register.js from the ais-webmcp core, delivered three ways; this package is the Django adapter and uses the installed core instead of shipping its own copy.

flowchart LR
  Core["ais-webmcp (PyPI)<br/>manifest, CLI, register.js"]
  Django["insight-ui-webmcp (PyPI)<br/>Django adapter"]
  NPM["@alpininsightsolutions/webmcp (npm, not yet published)<br/>register.js only"]
  CDN["cdn.alpininsight.ai/ais-webmcp/vX.Y.Z/<br/>register.js"]
  Core --> Django
  Core --> NPM
  Core --> CDN
  Django --> S1["Django sites"]
  NPM --> S2["other websites (bundlers)"]
  CDN --> S3["script tag"]

Documentation: https://insight-ui-webmcp.alpininsight.ai/

Status: early preview. insight-ui-webmcp has been published on PyPI since 20.10.2026 (0.1.x); interfaces may still change. WebMCP is a draft of the W3C Web Machine Learning Community Group (draft specification), not a W3C Standard. This package targets the document.modelContext API only.

The npm package @alpininsightsolutions/webmcp is not yet published. The ais-webmcp core owns register.js. The unscoped npm package webmcp is unrelated.

uv add insight-ui-webmcp
uv run python manage.py webmcp_prepare --profile webpage --dry-run
uv run python manage.py webmcp_prepare --profile webpage
uv run python manage.py webmcp_validate webmcp.manifest.json

Add insight_ui_webmcp to INSTALLED_APPS, then load {% webmcp_assets %} from webmcp_tags once in your site shell. The tag emits the helper only. It adds <meta http-equiv="origin-trial"> only when WEBMCP_ORIGIN_TRIAL_TOKEN is set, and status never prints that value. In the page, InsightUiWebmcp.status() reports ok, no-origin-trial-meta or no-model-context. Commit the host manifest; webmcp_prepare keeps an existing file unless --force is passed. subscribe_newsletter is written enabled: false and this package does not register a submit handler. Explicit host profiles bind the shared manifest to your own content and handlers. Read-only webpage tools declare an outputSchema (a JSON Schema object beside inputSchema), our optional extension that is not part of the WebMCP specification. See Output schemas. Local staticfiles are the default; CDN use requires an immutable matching version and your host's CSP approval.

Settings

{% webmcp_attribution %} renders a small <small> element, Insight UI WebMCP · Apache-2.0 · © Alpin Insight Solutions GmbH & Co. KG, linking to alpininsight.ai. It has no script and no inline style; place it in your footer and style it with css_class="...". To turn it off for one template, use {% webmcp_attribution show=False %}. We are a startup, and we appreciate it if you keep the notice, which costs you nothing and stays out of the way. It is optional and can be switched off. Redistribution requirements for the LICENSE and NOTICE files shipped in the package remain separate; see Apache-2.0 section 4.

Python 3.12+, Django 6.0.4–6.x. Insight UI is an optional ui extra: existing websites retain their own Core pin. Note that insight-ui-webmcp[ui] pulls in insight-ui, which is licensed under AGPL-3.0; this package itself stays Apache-2.0. The framework-independent ais-webmcp command is included as a dependency, with no private host requirements.

The framework-independent ais-webmcp core owns the shared schema and browser runtime. This repository contains the Django adapter and has its own version; it exposes the installed Core asset without copying it into the adapter distribution.

Output schemas

outputSchema is an optional extension by Alpin Insight Solutions, modelled on MCP Tool.outputSchema. It is not part of the WebMCP specification yet: adding it is an open proposal (webmachinelearning/webmcp#9, specification PR webmachinelearning/webmcp#254). Browsers currently ignore the field; our validation uses it.

outputSchema is optional on each tool. It is a JSON Schema object (Draft 2020-12), the same kind of object as inputSchema, describing what a successful call returns. Leaving the key off means the result shape is not declared. Read-only tools should set it. This package fills it for the shipped webpage profile, using only values the tool contract already returns.

go_to_section, open_legal, and start_conversation do not publish a result shape here. subscribe_newsletter stays enabled: false and has no output schema.

webmcp_prepare --profile webpage writes these schemas. A schema already stored on a tool is kept. Any other profile is written unchanged.

{% webmcp_assets %} serves the installed Core register.js byte-for-byte. Core validates declared output schemas and forwards them to document.modelContext.registerTool; browsers currently ignore the field. The adapter adds no validator monkey patch, startup hook, copied runtime, or browser bridge. Standalone ais-webmcp validate and ais-webmcp doctor accept the generated manifests without importing Django or this adapter first.

The adapter installs the released Core from PyPI (ais-webmcp>=0.1.0,<0.2); no private Git override is needed. CDN delivery remains separate.

Host tools (insight-ui-docs and others)

A host declares the schema on its own tool in the committed manifest, or on the dict returned by build_manifest().to_dict(). webmcp_prepare does not invent one for a custom profile. Use set_output_schema or set the key directly, and include only values the handler returns:

from insight_ui_webmcp.output_schemas import set_output_schema

tool = set_output_schema(
    {
        "id": "search_components",
        "name": "Search components",
        "description": "Search public components.",
        "inputSchema": {"type": "object", "properties": {}},
        "annotations": {"readOnlyHint": True},
    },
    {"description": "JSON Schema for the value this handler returns."},
)

The same object in a committed webmcp.manifest.json:

{
  "id": "search_components",
  "name": "Search components",
  "description": "Search public components.",
  "inputSchema": {"type": "object", "properties": {}},
  "outputSchema": {
    "description": "JSON Schema for the value this handler returns."
  },
  "annotations": {"readOnlyHint": true}
}

Staticfiles configuration

Add the Core finder to your host's existing STATICFILES_FINDERS. For hosts using Django's default finders:

from django.conf.global_settings import STATICFILES_FINDERS as DEFAULT_FINDERS

STATICFILES_FINDERS = [
    *DEFAULT_FINDERS,
    "insight_ui_webmcp.finders.CoreRuntimeFinder",
]

Keep any host-specific finders in the list. collectstatic continues to expose insight_ui_webmcp/js/register.js, including hashed production filenames. The finder reads the installed ais-webmcp package. CDN mode pins its version at https://cdn.alpininsight.ai/ais-webmcp/vX.Y.Z/register.js.

Development and release

uv sync --locked --all-groups
uv run --locked python -m django check --settings=tests.settings
uv run --locked pytest
uv run --locked pre-commit run --all-files

The adapter installs the stable compatible Core from PyPI. Core and adapter versions are independent.

Early preview on PyPI (0.1.x); the npm package and native-browser activation follow separately.

The documentation and guide cover both packages. Cloudflare's optional edge integration complements origin registration and does not replace it (details).

Debug staticfiles compatibility

CoreRuntimeFinder.list() accepts the optional None ignore-pattern value as well as collectstatic's list. Post-merge audit of #64: installed-distribution and production collectstatic checks passed, but debug asset discovery exercised this untested input and raised TypeError. Regression probes cover both caller forms and assert that enumeration still exposes only installed Core bytes. When adding finders, verify debug discovery as well as production collection; a successful container build covers only the latter runtime configuration.