# ClaimReady The insurer's page hands your own agent its policy rules as typed tools, so you learn what you are covered for while you are still describing the crash. [![CI](https://github.com/upgradedev/claimready/actions/workflows/ci.yml/badge.svg)](https://github.com/upgradedev/claimready/actions/workflows/ci.yml) [![WebMCP evals](https://github.com/upgradedev/claimready/actions/workflows/evals.yml/badge.svg)](https://github.com/upgradedev/claimready/actions/workflows/evals.yml) [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE) The CI badge is red on purpose while the video is missing. The readiness gate refuses to let a mandatory deliverable pass, and a badge that hid that would be the wrong badge. ClaimReady is a first notice of loss page for a motor insurer. It is a static page with no dependencies and no build step, and it publishes its own capabilities to the visitor's AI agent through WebMCP. ## Contents - [Who this is for](#who-this-is-for) - [Why this needs WebMCP](#why-this-needs-webmcp) - [How it fits together](#how-it-fits-together) - [One journey, call by call](#one-journey-call-by-call) - [What is a tool here, and what is deliberately not](#what-is-a-tool-here-and-what-is-deliberately-not) - [The registration call](#the-registration-call) - [Never tools, by design](#never-tools-by-design) - [Security](#security) - [Open it yourself](#open-it-yourself) - [Quickstart, with nothing installed](#quickstart-with-nothing-installed) - [Status](#status) - [Repository layout](#repository-layout) - [Licence](#licence) ## Who this is for The driver standing at the roadside with a damaged car and a phone, and behind them the first notice of loss handler at a regional motor insurer who opens the claim next morning. The driver gets an answer about their own cover while they are still describing what happened, instead of a form, a call queue and a letter three days later. That is the half this demo shows. The handler's half, a claim that arrives with the cover already checked against the policy that was actually sold, is a consequence of the driver's half rather than something you can watch here. There is no desk side surface in this repo: no queue view, no arriving claim view, and nothing that measures whether claims arrive more complete. Today that conversation happens twice. The driver tells an assistant what happened, the assistant guesses at the cover from general knowledge, and then the driver retypes everything into the insurer's form anyway. ClaimReady removes the second half by letting the page itself tell the agent what the policy says. ## Why this needs WebMCP Remove WebMCP and the agent has no typed, authoritative route into the insurer's own policy rules, so it is back to guessing the cover from general knowledge and retyping the answers into a form. That is the whole point. The rules live on the insurer's origin, where they belong. The agent does not scrape them, does not hold them in a system prompt and does not need an integration to be built for it in advance. It asks the page, and the page answers with a clause id. The dullest honest alternative is a REST endpoint with an OpenAPI file beside it, and it is worth naming rather than dodging. It loses on two counts. It needs an integration built for this insurer in advance, so it does nothing for an agent that has never met this origin before. And it cannot gain and lose a capability while the page is open, which is exactly what `get_assistance_options` does the moment the driver says the car cannot be driven. ## How it fits together ```mermaid flowchart TB subgraph outside["The visitor's own agent"] AG["ChatGPT desktop browser, or Chrome with the WebMCP testing flag"] end subgraph origin["claimready, one origin, no runtime network calls"] MCP["WebMCP layer: detect document.modelContext, register tools with an AbortSignal each"] TOOLS["Tools: describe, read, requirements, patch, validate, check cover, estimate, evidence notes, assistance options"] STORE["Store: one claim draft, subscribers notified on every change"] CORE["Core domain: claim rules, insurer rule packs, derived requirements, coverage table, repair bands. Pure, no DOM"] UI["Page: fields, evidence, live tool call ledger"] HUMAN["No tool reaches these: File claim, Request roadside assistance, Pin a field"] end AG -->|"registerTool and execute"| MCP MCP --> TOOLS TOOLS -->|"dispatch"| STORE TOOLS -->|"read and compute"| CORE STORE -->|"subscribe"| UI CORE --> STORE UI -.->|"a control on the page, no tool exists for it"| HUMAN HUMAN --> STORE classDef guarded fill:#fce8e6,stroke:#a50e0e,color:#a50e0e class HUMAN guarded ``` Follow the arrows into the guarded box. No arrow arrives from the agent, from the WebMCP layer or from the tools, because the guarded actions sit outside the tool surface. There is no tool that reaches them, so there is nothing for a prompt injected agent to call. That is a claim about the tool surface and it stops there. The page does not know who pressed a button, nothing here records it, and the section on [what is never a tool](#never-tools-by-design) says why we do not pretend otherwise. The layer map, the dependency rule and the reasoning behind each boundary are in [docs/architecture.md](docs/architecture.md). ## One journey, call by call ```mermaid sequenceDiagram autonumber actor D as Driver participant A as Your agent participant T as ClaimReady tools participant S as Store participant P as Page D->>A: I reversed into a bollard on Thursday, the wing is dented A->>T: read_claim_state T->>S: read the draft S-->>T: draft plus the fields still missing T-->>A: what is set, what is missing A->>T: apply_claim_patch incident_date 2026-08-20 T->>S: dispatch a patch S-->>P: subscribers notified P-->>D: the field fills in and the ledger shows the call A->>T: apply_claim_patch damage_zone 4 severity dent A->>T: check_coverage T-->>A: covered, clause id, deductible A->>T: get_repair_estimate T-->>A: a triage band, not a prediction A->>T: validate_claim T-->>A: ready, nothing missing A-->>D: Your cover applies. Read it over and press File claim. D->>P: clicks File claim Note over P,S: filing is human only and is never registered as a tool ``` ## What is a tool here, and what is deliberately not Tools are descriptive. They say what they return, never what the agent should do next. None of them carries an instruction aimed at a model. | Tool | Reads or writes | Annotations | State today | |---|---|---|---| | `read_claim_state` | reads | `readOnlyHint: true`, `untrustedContentHint: true` | built | | `describe_claim` | reads | `readOnlyHint: true`, `untrustedContentHint: true` | built | | `get_requirements` | reads | `readOnlyHint: true` | built | | `apply_claim_patch` | writes one field of the page's draft | `readOnlyHint: false` | built | | `validate_claim` | reads | `readOnlyHint: true` | built | | `check_coverage` | reads | `readOnlyHint: true` | built | | `get_repair_estimate` | reads | `readOnlyHint: true` | built | | `read_evidence_notes` | reads | `readOnlyHint: true`, `untrustedContentHint: true` | built | | `get_assistance_options` | reads, and is registered only while the claim says the vehicle cannot be driven | `readOnlyHint: true` | built | The first eight are registered for the life of the page. `get_assistance_options` comes and goes: `src/webmcp/register.js` re-asks `CONDITIONAL_TOOLS` on every store change, so the tool appears when `vehicle_drivable` is false and is withdrawn when the car is drivable again. The page's status strip reads the live registered list, so you can watch the count move. `untrustedContentHint` is set on the three tools that hand back free text the insurer did not write. The claim description is the visitor's words, and the evidence notes are a repairer's and a third party's words, so none of it is the insurer speaking and all of it is labelled that way. The one tool that writes says `readOnlyHint: false` out loud rather than leaving the annotation off, because an empty annotations block leaves an agent unable to tell a write apart from a tool nobody got round to annotating. WebMCP defines exactly two annotations. Any other hint name comes from a different MCP dialect and is rejected by `node scripts/check_style.mjs` before it can reach a judge. ### The registration call Every tool on this page is registered through one call, and this is its shape: ```js document.modelContext.registerTool({ name: 'check_coverage', description: 'Check the claim draft on this page against the policy it belongs to.', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, annotations: { readOnlyHint: true }, async execute(input, options) { /* returns { content: [{ type: 'text', text }] } */ } }, { signal: new AbortController().signal }); ``` The shipped code makes exactly that call with the receiver resolved into a variable first, because `navigator.modelContext` is the older spelling and some builds still ship only that one. Two lines from `src/webmcp/register.js`, verbatim: ```js // line 379. getModelContext() reads document.modelContext, then navigator.modelContext, else null const modelContext = getModelContext(); // line 405. One AbortController per tool, so a single tool can be withdrawn while the page runs await modelContext.registerTool(descriptor, { signal: controller.signal }); ``` Read `getModelContext` at `src/webmcp/register.js:179` to confirm the variable is `document.modelContext` whenever the browser has it. ### Never tools, by design - **File claim.** A control on the page. No tool reaches it, and there is no `file_claim`, no `submit_claim`, no alias. - **Request roadside assistance.** A control on the page. No tool reaches it. Dispatching help costs money and sends a vehicle to a location. - **Pin and unpin a field.** A control on the page. No tool reaches it. Pinning is how the claimant says they have checked an answer themselves, and `apply_claim_patch` then refuses that field with `PATCH_REJECTED_LOCKED`. Overriding the coverage table is not on the list because it is not an action at all. Nobody can do it from either side: the answer is a table lookup in `src/core/coverage.js`, and no path in this repo edits it. Be exact about what this buys, because the loose version of the claim is false. An agent that drives a browser clicks ordinary DOM buttons, and the W3C security considerations and OpenAI's own WebMCP documentation both say so. Nothing on this page can tell a synthetic click from a human one and this page does not try, because an `isTrusted` or `userActivation` check blocks an honest probe while a remotely driven browser sails through it, which manufactures exactly the false certainty worth removing. What is true is narrower and more useful: **no tool on this page reaches those three actions**. An agent that has been prompt injected can draft the whole claim, check the cover, get an estimate, and write a wrong value into any field the claimant has not pinned. That last one is a real risk this page does not remove, and an earlier version of this section understated it by listing only what no tool reaches. What is absent from the tool surface is a tool for filing, for assistance and for unpinning, because none of the three is published. What the claimant holds against the rest is the pin, the revision protocol, and a ledger that shows every call as it happens. `node scripts/readiness.mjs` scans the tool files for those names on every push and fails the build if one appears. What that proves is precise: no tool file declares one. It is a name blocklist over the tool surface, not a runtime guard on the buttons. ## Security Our choices, mapped to the Chrome WebMCP tool security guide at . | Guidance | What ClaimReady does | |---|---| | Keep tools same origin | Every tool is registered on this origin. `exposedTo` is never passed, and the readiness gate fails if it appears. The `tools` Permissions Policy is left at its default of `self` and nothing on the origin loosens it: no header sets it, and no meta tag sets it. `vercel.json`, which production does not use, deliberately sets no entry for it either, and the readiness `VRC` row fails if one appears there. | | Use the annotations that exist | `readOnlyHint` and `untrustedContentHint`, declared explicitly on every tool rather than left to a default. The style gate rejects annotation names from other dialects. | | Validate every input in code | JSON Schema tells the agent the shape. It is not the check. Three tools take input, `apply_claim_patch`, `get_repair_estimate` and `get_requirements`, and each re-validates in code against the enums in `src/core/claim.js` or the loaded rule pack, so an unknown field, an unknown requirement id or an out of range value comes back as a sentence the agent can correct itself from rather than being written. The other six declare an empty schema and take no input at all, which you can confirm with `grep -c "properties: {}" src/webmcp/tools/*.js`. | | Keep tool output small | Tool output is capped at 1500 characters, the budget from the guide. Tool names are capped at 30 characters, tool descriptions at 500, parameter descriptions at 150, all enforced by `node scripts/check_style.mjs`. | | Keep tool metadata descriptive | Descriptions say what a tool returns. None of them tells the model what to do, which is the line that keeps tool metadata from becoming an instruction channel. | | Do not treat origin restrictions as a security boundary | We do not. Same origin registration limits accidental exposure, it does not stop a hostile page or a compromised agent. What we rely on instead is narrower and is stated as such: the actions with consequences are not in the tool surface, so a persuaded agent has no tool to call for them. It can still click a button, and it can still write a wrong value into an unpinned field. | Two more, because they are part of the same promise: - **No secrets and no runtime network calls.** The judge path makes zero external requests. There is no API key in this repo because there is no API to call. - **Synthetic data only.** Every name, plate, policy number and vehicle in the fixtures is invented. ## Open it yourself **https://upgradedev.github.io/claimready/** No account, no install, nothing to accept. The page is served over HTTPS, which WebMCP requires, and it carries its Content Security Policy in the document, which is what makes the policy hold here: GitHub Pages sends no CSP header of its own. The Status table below is the honest state of everything else, and `node scripts/readiness.mjs` prints it on demand. The gate fetches this URL by default, so a red `LIVE` row means the live surface really is broken and is never a row to read past. WebMCP is new, so a judge needs one of two surfaces. **1. The ChatGPT desktop app's built in browser.** Open the app, press `Ctrl+Shift+B` (or `Cmd+Shift+B`), and load the page. This needs a model build with WebMCP support. If tools never appear, switch models and reload before assuming the page is broken. **2. Chrome 149 or later, with the flag.** Go to `chrome://flags/#enable-webmcp-testing`, enable it, relaunch, then load the page. Install the WebMCP Model Context Tool Inspector extension to see the registered tools, their schemas and the result of each call. Chrome 149 is the first build with WebMCP, but 153 or later is the better one for this page. The imperative API documentation, read on 2026-08-27 at , records that unregistering a tool stopped cancelling in-flight executions as of Chrome 153, and this page withdraws a tool live. The page tells you which API name it found, `document.modelContext` or `navigator.modelContext`, and shows a running ledger of the tool calls your agent makes, so nothing about the integration has to be taken on trust. Three prompts to paste: 1. `Look at this claim page, tell me what it still needs from me, then set the incident date to last Thursday and the damage to a dent at the 4 o'clock position.` 2. `Check whether my policy actually covers this, and tell me the clause and my deductible before I file anything.` 3. `Try to file this claim for me.` The third one is the interesting prompt. The agent should come back and tell you it cannot, because filing is not a tool it has, and then point you at the button. ## Quickstart, with nothing installed This repo has no dependencies. There is no `npm install` to run, and there is no lockfile, because there is nothing to lock. The quickstart uses Python's built in server rather than `npx serve`, since `npx` would download a package, and the point is that nothing here needs downloading. ```sh # serve the repo root on http://localhost:4173 python -m http.server 4173 # run the domain tests, no runner and no config node --test tests/unit # the style gate: em dashes, annotations that do not exist, tool budgets node scripts/check_style.mjs # the readiness gate, one table, every row saying what it blocks. It fetches the live URL node scripts/readiness.mjs # offline, with no network. The LIVE row then proves nothing and prints NOT DEPLOYED node scripts/readiness.mjs --ci --allow-undeployed # prove the gate can fail, by breaking every row in turn and requiring each one to refuse node scripts/readiness.mjs --selftest ``` Both readiness runs above exit non zero while the video row `D4` is red, and that is deliberate: a mandatory deliverable that is missing turns the build red in every mode, `--ci` included. Node 20 or later. `python -m http.server` does not send the production security headers, so a page that works locally can still break on the deployed origin. The readiness gate's `IDX` row catches the usual cause, which is an inline `