WebMCP — in-browser agent tools on public note pages

What WebMCP is, and how it differs from our server MCP

We already ship a server-side MCP server at POST /_system/mcp
(internal/case/mcp/endpoint.go:117), JSON-RPC 2.0 over HTTP. An external
MCP client (Claude Desktop, Cursor, a CLI) connects to it over the network and
authenticates with a personal token (t2g_*), an X-API-Key, or a federation
JWT (internal/case/mcp/endpoint.go:48, :71). The agent runs on the user's
machine or in the cloud; trip2g is a remote server it talks to.

WebMCP is the inverse. It is a W3C Web Machine Learning Community Group draft
(accepted Sept 2025; latest CG draft Apr 2026 — not a ratified standard) that
adds a browser API, navigator.modelContext. A web page registers tools in
JavaScript; an AI agent already running in the user's browser (Chrome's
built-in agent, an Edge agent, or an extension) discovers and calls them. The
agent reuses the page's own context and the user's already-authenticated browser
session — no token handshake, because the calls execute as page JavaScript in the
user's tab.

Browser status as of mid-2026: Chrome shipped navigator.modelContext in an
early preview behind a flag (Chrome 146, Feb 2026); Edge has begun shipping; broad
support is targeted for H2 2026. The API requires a secure context (HTTPS).
Therefore everything here must be a progressive enhancement: feature-detect,
and silently no-op when the API is absent.

The WebMCP API surface (current draft)

The API lives at navigator.modelContext. Two registration styles:

Imperative — register/unregister individual tools at runtime:

const reg = navigator.modelContext.registerTool({
  name: "search_notes",
  description: "Search this site's notes by query.",
  inputSchema: {
    type: "object",
    properties: { query: { type: "string", description: "Search query" } },
    required: ["query"],
  },
  async execute({ query }) {
    // ... do the work ...
    return { content: [{ type: "text", text: "..." }] };
  },
});
// later: reg.unregister?.() / navigator.modelContext.unregisterTool(...)

There is also navigator.modelContext.provideContext({ tools: [...] }) to set
the full tool list at once (older shape, still present in some builds), and a
declarative HTML-attribute form. For human-in-the-loop, the draft adds
agent.requestUserInteraction() so a tool can ask the browser to get explicit
user confirmation before a sensitive action.

Notes on the shape (verify against the shipping build at implementation time, the
draft is moving):

• The handler key is execute in the W3C draft; some libraries (@mcp-b/*) use
  handler. Target execute.
• The return value mirrors MCP CallToolResult: { content: [{ type: "text", text }] }. This is the same content shape our server already produces
  (internal/case/mcp/types.go:61 CallToolResult, :67 Content) — a clean fit.

Tool inventory to expose (public, read-only)

All of these already exist server-side and are already safe for anonymous public
access (the open-KB anonymous path: /_system/mcp serves public KBs with no
token, see the GET info page internal/case/mcp/endpoint.go:136 "Public access:
no token required for open knowledge bases", and the anonymous branch in
authenticateAnonymousRequest returning ctx, nil at :93). Server-side access
control still applies on every call — private/subscriber notes are filtered by
canReadMCPNote (internal/case/mcp/resolve.go:481) and
filterSearchResults (:409), so an unauthenticated browser agent sees exactly
what an anonymous visitor may see. This is the core reason the public surface is
safe: we are not bypassing any check, we are surfacing the anonymous tool set.

Tools, with their server schemas (source: handleToolsList,
internal/case/mcp/resolve.go:171):

The dynamic-method tools come from notes with mcp_method frontmatter
(internal/case/rendernotepage/model MCPMethod); they are discovered
server-side and filtered by readability. To keep the browser tool list correct,
the page must learn which dynamic tools are available — fetch the list at
runtime (see "Reuse /_system/mcp" below) rather than hardcoding it.

Out of scope (do not register): graphql_introspection and graphql_request
(resolve.go:285–:307). These are gated behind an API key with
EnableMcpAdminTools and must never appear in the public browser surface.

note_path: "...",
note_path_id: <PathID>,
note_lang: "...",
note_version_id: "...",

Auth / session strategy

The whole public surface is anonymous. The browser agent runs in the
visitor's tab; whatever cookies the visitor has are sent automatically by the
browser on same-origin requests. We do not add any token. Concretely:

• If the tool handler proxies to /_system/mcp (recommended, below), the
  fetch is same-origin and the browser attaches the visitor's session cookies
  automatically. A logged-in subscriber's agent therefore transparently sees
  their subscriber content; an anonymous visitor sees only public content —
  exactly mirroring what they'd see by browsing. No special handling needed.
• No Authorization header, no X-API-Key. We never expose t2g_* tokens to
  page JS.

Security posture for this scope is simple because the server is the trust
boundary and it already enforces per-note access on every call. The browser
tools are a thin presentation layer over endpoints a visitor can already hit.
The one rule: never register the admin GraphQL tools, never send admin
credentials from page JS. (A future admin surface would need its own session
gating and confirmation design — deliberately not addressed here.)

Reuse /_system/mcp vs call backends directly

Recommendation: proxy to the existing /_system/mcp endpoint. Each WebMCP
tool's execute builds a JSON-RPC tools/call request and fetches
/_system/mcp same-origin.

Trade-offs:

Proxying wins decisively: the server is already the access-control and formatting
authority, and the response is already in WebMCP's content shape. The browser
layer becomes a small adapter:

1. On load, fetch('/_system/mcp', {method:'POST', credentials:'same-origin'})
   with {jsonrpc:"2.0", id, method:"tools/list"} to get the live tool list
   (built-ins + readable dynamic methods, with admin tools absent for anonymous).
2. For each returned tool, registerTool({ name, description, inputSchema, execute }).
3. execute(args) POSTs {method:"tools/call", params:{name, arguments:args}}
   and returns the result (already {content:[...]}), or maps a JSON-RPC
   error to { content:[{type:"text", text}], isError:true }.

Page-context tools (get_current_page etc.) are registered locally without a
server round trip (or compose the proxy call, e.g. find_related_to_this_page
forwards to the similar proxy).

This also keeps the WebMCP list automatically in sync with the server: filter a
note to subscribers and it disappears from both surfaces with no client change.

Where / how to inject the JS

Follow the mermaid per-note widget pattern (docs/dev/mermaid.md): a small
committed glue bundle under assets/, embedded via assets/embed.go, emitted as
a <script defer> in the rendered page.

• New bundle: assets/webmcp/src/index.ts → built artifact assets/webmcp.js
  (mirrors assets/mermaid/ → assets/mermaid.js).
• Embed it: add webmcp.js to the //go:embed list in assets/embed.go:8.
• Serve + cache-bust: already handled by the asset FS and AssetURL()
  (cache-busting hash), same as mermaid.

Injection point — unconditional on note pages, not per-note. Mermaid is
per-note because only some notes have diagrams; WebMCP tools (search, federation,
page-context) make sense on every rendered note page. Two clean options:

• Option A (preferred): add it to the core bootstrap list UserJSURLs()
  (cmd/server/main.go, the core scripts returned for note pages) so every
  default-template page loads it. The template already iterates ctx.JSURLs
  into <script defer> tags (internal/defaulttemplate/views.html:89–:91).
• Option B: append it in buildDefaultTemplateCtx
  (internal/case/rendernotepage/endpoint.go:495–:502), next to the mermaid
  line, but without the HasCodeLanguage guard (i.e. always). Use this if we
  want it on note pages only and not other default-template pages.

The script's first action is feature detection:

if (!('modelContext' in navigator) || typeof navigator.modelContext?.registerTool !== 'function') {
  return; // WebMCP unsupported — silent no-op, page works as before
}

It must also tolerate non-secure contexts (the API simply won't exist over
plain HTTP, so the guard above covers it).

The admin $mol app (/admin) is not a target of this plan; do not inject
the WebMCP bundle there.

Feature-detection & graceful degradation

• Guard on navigator.modelContext and registerTool before any call.
• Wrap registration in try/catch; a draft-API mismatch must never break the
  page.
• If tools/list fetch fails, fall back to registering the static built-in
  tools only (search/similar/note_html/federated_*), skipping dynamic discovery.
• Unregister on pagehide/beforeunload if the API exposes unregister, to avoid
  stale tools in SPA-like navigations (note pages are full reloads today, so this
  is defensive).

Build commands

Mirror the mermaid widget build (docs/dev/mermaid.md "Build"):

assets/webmcp.js is a committed artifact, like mermaid.js / chart.js.

Story-by-story breakdown

Written TDD-first (Red → Green → Refactor), matching docs/dev/mcp.md style.

Optional: feature-flag gating

The public read-only surface is low-risk (it only re-exposes anonymous,
access-controlled endpoints), so a flag is optional. If desired, gate injection
behind a config/feature flag (the project has a feature-flags system, see
docs/dev/features.md) so an operator can disable the WebMCP script per
instance. A flag becomes mandatory the day any admin/write tool is added —
but that is out of scope here.

Files (anticipated)

References (WebMCP spec, mid-2026)

• W3C WebML CG — WebMCP Community Group Draft (navigator.modelContext,
  registerTool/unregisterTool/provideContext, agent.requestUserInteraction).
• Chrome 146 early preview behind a flag (Feb 2026); Edge shipping; broad support
  targeted H2 2026. Requires a secure context (HTTPS).
• Verify the exact execute vs handler key and the descriptor shape against the
  shipping browser build at implementation time — the draft is still moving.