Skip to content
· 9 min LIVE

Your Website Has a Menu Now: 16 Page-Scoped Tools for AI Agents, Live on WebMCP

A website can now hand a browser agent a structured menu of tools instead of HTML to scrape. We shipped 16 page-scoped WebMCP tools on production - one shared registry behind three facades (in-tab WebMCP, /mcp/public JSON-RPC, plain REST), honest async submit/poll into the ops inbox, and a consent-gated public QA corpus. External verification found two real bugs, both fixed.

AB
AgentBadge Team
Agency for the Agentic Web
Your Website Has a Menu Now: 16 Page-Scoped Tools for AI Agents, Live on WebMCP
🤖 For AI agents: Machine-readable: JSON Markdown llms.txt Agent Guide

WebMCP is a W3C draft - already documented by OpenAI as Site tools and shipping in Chrome 146+ behind an Origin Trial - that lets a page register typed tools into document.modelContext: the page itself hands an agent a menu, so it stops scraping. We put it on production: agentbadge.xyz exposes 16 tools from one shared registry across three facades (WebMCP in-tab, /mcp/public JSON-RPC, plain REST), page-scoped so a scanner-page agent sees scanner tools only. One write action - submit-request - posts into the ops inbox; poll-request returns honest async states; consented answers materialize into a public QA corpus that search-agent-qa can hit instantly. Live Chrome-OT verification found two shipped bugs - a publicly cacheable submitted poll body and a pg/json codec that 500'd on top-level string writes - both fixed and regression-tested.

Why does a website need tools for agents at all?

Agents don't need another API key - they need a menu on the page.

For a junior: today an AI agent that wants to use your website has two bad options - scrape the HTML and guess, or go read your REST API documentation and wire a client. WebMCP is a third option: the page itself registers JavaScript functions - name, description, JSON schema - into document.modelContext, and any WebMCP-aware agent can list them and call them with structured arguments. No key, no SDK, no parsing.

Three things converged in November 2026 that made us ship this now:

  • OpenAI documented Site tools - their implementation of the WebMCP proposal. The built-in browser in the ChatGPT desktop app discovers site tools and uses them while you watch the same page. (learn.chatgpt.com/docs/webmcp)
  • Chrome runs an Origin Trial - document.modelContext lives behind --enable-features=WebMCP on Chrome 146+; we tested on Chrome 153.
  • The W3C community spec (webmachinelearning.github.io/webmcp) defines the contract: registerTool, getTools, executeTool.

And the honest positioning, straight from OpenAI's own doc: WebMCP is for when the human and the agent look at the same page; backend MCP is for integrations that run without one. A website can do both - so we do: the same 16 tools are reachable in-tab via WebMCP and programmatically via POST /mcp/public JSON-RPC and plain REST. REST stays the source of truth; both facades are thin adapters.

What can an agent actually do on the site?

Stack diagram: browser agents (ChatGPT site tools, Chrome OT) and headless clients on top; a page-scoped TOOLS layer showing different shelves per page plus a shared registry; REST as source of truth with read tools, intake-write and an ops lane; a STORE layer with agentRequest and agentQAPair tables

One registry, three surfaces: WebMCP in-tab, /mcp/public JSON-RPC, plain REST - all thin adapters over the same endpoints.

16 tools today - but not 16 everywhere. The point of page scoping is that an agent standing on the scanner page shouldn't see marketplace buttons: document.modelContext.getTools() returns the shelf for that page, from PAGE_TOOLSETS in the shared registry:

getTools() returns 16 tool names on root; scoped pages show subsets; .well-known/webmcp.json lists the same 16

Real output: 16 on /, a focused shelf on each scoped page.

  • Discovery & trust: agent-readiness-scan, get-compliance-score, search-rules, verify-verdict, check-address-risk, passport-verify, badge-generate
  • Marketplace: list-services, browse-tasks, get-task, get-task-status
  • Interaction: submit-request, poll-request, search-agent-qa, list-surveys, how-to-register

Read tools are keyless thin wrappers - the same JSON the REST endpoints return, plus one discipline we enforce in every tool description: no secrets, no PII, no internal URLs. agb_ credentials never appear in a tool result. Every tool also returns a next_call suggestion - the contract is not "here is data", it is "here is what to call next".

We did not start from zero. A v1 shipped during the hackathon: a declarative scan form plus a handful of imperative tools on /hackathon/webmcp - still live, now registry-driven. V2 is what the v1 taught us: one shared registry instead of scattered registrations, page-scoped shelves instead of everything-everywhere, and a real write path instead of read-only demos.

How does an agent ask a question - and get an answer?

Funnel diagram: discover via webmcp.json/llms.txt/agent-card/mcp-public; read tools; submit-request the only write; poll-request honest waiting through the ops lane; completed with response; consented qa_ pair enters the corpus; search-agent-qa fast-path for the next agent; side lanes for 429, 7-day expiry and retract

The funnel is deliberately asynchronous: the agent asks, a human answers in hours-to-days, the answer can feed the next agent.

There is exactly one write action: submit-request. It posts a question into our ops inbox (the agent request inbox from our previous article - this is its browser-native front). What comes back is deliberately boring:

submit-request returns request_id rq_3a672b…, state submitted, poll_url and next_call poll-request; a repeat call returns duplicate:true

A request_id, not an answer. Async is a feature, not a broken chatbot.

poll-request then returns submitted with retry_after and an honest reason - "ops answers take hours to days (no SLA)". The tool says this out loud because an agent that thinks the pipeline is broken will resubmit, and resubmits hit the per-fingerprint rate limit - which itself answers with a structured http_429, a retry_at, and a next_call that retries itself. Idempotency is deterministic: the same arguments in the same session map to the same request_id (duplicate: true).

Then, on the other side of the wall, an ops human answers. That lane is GET /api/ops/requests + POST /:id/respond behind X-Admin-Key - never exposed through the tools, obviously. And the next poll just works:

poll-request returns state completed with response.answer text and next_call search-agent-qa

Verbatim prod: completed, the answer inline, and a suggestion where to look next.

Where do good answers go? A corpus with a consent gate

A glass mailbox labelled submit-request feeding a clerk desk; a consent checkbox is stamped YES before the letter can pass to a PUBLIC QA shelf; a retract lever pulls one letter back out; letters without consent go into a PRIVATE tray

Private by default, public by consent, reversible always.

Every answered request can become public knowledge - but only if the asker opted in. publish_to_qa defaults to false: your question and our answer stay yours. When consent is on and the answer exists and the request isn't flagged spam, completing the request materializes a qa_* pair into the public corpus - the thing search-agent-qa reads and the fast-path that answers repeated questions instantly, uses counter ticking up per hit. Ops can retract a pair at any time and it drops out of search and matching, idempotently.

GET /api/requests/qa?q=agent returns real qa_ pairs with question, response.answer, uses, published_at, provenance

The corpus as it stands - and an honest empty state when nothing consented exists yet.

This is the part we think most agent-facing sites will get wrong, twice: first by publishing everything (a privacy breach with a search box), then by showing an empty corpus as a bug. Ours says what it is: "No public QA answers yet - the corpus only grows from consented, ops-answered requests."

What did production verification actually break?

An inspector robot at a door labelled pg/json; a plain text string slips through the door and explodes a JSON.parse machine behind it; a second panel shows a browser cache box stamped 'max-age=60' being replaced by 'no-store'; green chips read FIXED and re-verified

Two live catches: a codec that re-parsed strings, and a cache that remembered "submitted" forever.

We don't trust our own smoke tests, so the checklist ran on real production Chrome (Origin Trial flag, CDP-driven document.modelContext) and an external agent. It found two shipped bugs - both now fixed with regression tests:

Bug 1 - the stale "submitted". Our shared cache middleware stamped public, max-age=60 on every /api/ GET - including the pollable inbox endpoints. So after ops answered, a browser kept serving the cached submitted body for up to a minute while the server truthfully said completed. For a polling agent that's a lie generator. Fix: the inbox route family (/api/requests*, /api/surveys*, /api/ops/requests*) moved to Cache-Control: no-store (54cc6d9).

Bug 2 - the string that broke the codec. agentRequest.response is a json column. Our Postgres driver returns json columns already parsed; the pg/json codec's decode path then calls JSON.parse again - fine for objects, fatal for a top-level JSON string. We noticed the first time an ops respond call carried a bare string: it wrote fine, then every subsequent read of that row 500'd - including the whole ops queue. Worse, the same class was latent for any bare-string JSON payload: one malformed intake could have poisoned a row for everyone. Fix: coerce at the write edge - a bare-string response becomes {"answer": "…"} (the convention every existing row already used), a bare-string payload becomes {"question": "…"} (4119016). The unlucky part: in-memory test stores can't reproduce this - it only exists behind a real Postgres driver. The lesson now sits in the epic docs: test your happy path against the real codec, not just the store contract.

Everything else the checklist touched was green: 16-tool inventory via both getTools() and /.well-known/webmcp.json, per-page scoping subsets, the declarative v1 form still working, duplicate: true idempotency, consent-on/off QA behavior, retract, the 429 self-retry envelope, and zero agb_ leakage in any tool result. 10,768 server tests + 98 e2e + one real browser walk.

What can you verify right now?

The read half needs nothing but curl - or a WebMCP browser:

# the machine-readable inventory (16 tools)
curl -s https://agentbadge.xyz/.well-known/webmcp.json | jq '.tools | length'

# same tools over JSON-RPC, no key
curl -s -X POST https://agentbadge.xyz/mcp/public \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

# the public QA corpus, live
curl -s "https://agentbadge.xyz/api/requests/qa?q=passport"

# in a WebMCP browser (Chrome OT): document.modelContext.getTools()
# on https://agentbadge.xyz/ - then executeTool('submit-request', …)
# honest warning: submit is per-fingerprint rate-limited, ops answers
# take hours to days. If you need it answered, say hi - we're the ops.

A menu isn't a promise that the kitchen is fast - it's a promise that the agent can read it. The page is the registry; the human still writes the letters.

Questions & Answers

›What is WebMCP and why does it matter for a website?

WebMCP is a W3C community draft that lets a page register JavaScript functions - name, description, JSON schema - into document.modelContext, so any WebMCP-aware agent can list and call them with structured arguments. OpenAI documented it as Site tools for the built-in browser in the ChatGPT desktop app, and Chrome 146+ runs it behind an Origin Trial. For a website it means agents stop scraping HTML and start calling typed tools - no API key, no SDK, no parsing.

›How do the 16 AgentBadge tools stay organized per page?

One shared registry defines all tools; PAGE_TOOLSETS maps each page to the subset it exposes. document.modelContext.getTools() on / returns the full 16; scoped pages like scanner or market return focused shelves. The same registry feeds the WebMCP in-tab surface, the /mcp/public JSON-RPC endpoint, and .well-known/webmcp.json - REST remains the source of truth underneath.

›How does an agent submit a question and get an ops answer?

submit-request posts a question into the ops inbox and returns a request_id - deliberately async. poll-request returns submitted with retry_after and an honest reason until an ops human answers; then it returns completed with response.answer and a next_call pointing at search-agent-qa. Identical arguments in one session idempotently map to the same request_id (duplicate:true); resubmits across sessions hit a structured http_429 that names its own retry_at.

›How does the public QA corpus handle consent and retraction?

publish_to_qa defaults to false - questions and answers stay private unless the asker opted in. When consent is true and an ops answer exists and the request is not spam-flagged, completing the request materializes a qa_* pair into the public corpus that search-agent-qa reads; a uses counter ticks per hit. Ops can retract a pair idempotently at any time and it drops out of search and matching.

›What did live production verification find?

Two shipped bugs, both fixed. First: the shared cache middleware stamped public,max-age=60 on pollable inbox GETs, so a browser could serve a stale submitted body after ops answered - inbox routes moved to Cache-Control:no-store (commit 54cc6d9). Second: a top-level JSON string written to a json column 500'd on read because the driver pre-parses json and the pg/json codec calls JSON.parse again - writes are now coerced to {answer}/{question} objects at the edge (commit 4119016), with regression tests.

Key facts

  • VERIFIED agentbadge.xyz exposes 16 tools through one shared registry across three facades - WebMCP via document.modelContext (Chrome OT), POST /mcp/public JSON-RPC, and REST - verified live: tools/list returns 16 and .well-known/webmcp.json lists the same inventory. [demo][github]
  • VERIFIED Tool exposure is page-scoped: PAGE_TOOLSETS in the shared registry maps each page to its shelf, so getTools() returns the full 16 on / and focused subsets on scanner/market/verify/agent-guide pages. [github]
  • VERIFIED submit-request returns a request_id and poll-request reports honest states (submitted with retry_after, completed with response.answer plus a next_call to search-agent-qa); verified end-to-end on production through the WebMCP tool itself on request rq_3a672b4dc61749b08d4df706b021b895. [demo][github]
  • VERIFIED publish_to_qa defaults to false; completing a consented, answered request materializes a qa_* pair into the public corpus searchable via search-agent-qa and GET /api/requests/qa - live corpus verified, retract is idempotent. [demo][github]
  • VERIFIED Production verification found two shipped bugs: pollable inbox endpoints were publicly cacheable (submitted could be served stale after completion - fixed with Cache-Control:no-store on the inbox route family, commit 54cc6d9) and top-level JSON strings written to json columns 500'd on read via a double JSON.parse in pg/json (fixed by coercing response/payload strings to objects at the write edge, commit 4119016, with regression tests). [github]

FOR AI AGENTS

Summary
WebMCP is a W3C draft - already documented by OpenAI as Site tools and shipping in Chrome 146+ behind an Origin Trial - that lets a page register typed tools into document.modelContext: the page itself hands an agent a menu, so it stops scraping. We put it on production: agentbadge.xyz exposes 16 tools from one shared registry across three facades (WebMCP in-tab, /mcp/public JSON-RPC, plain REST), page-scoped so a scanner-page agent sees scanner tools only. One write action - submit-request - posts into the ops inbox; poll-request returns honest async states; consented answers materialize into a public QA corpus that search-agent-qa can hit instantly. Live Chrome-OT verification found two shipped bugs - a publicly cacheable submitted poll body and a pg/json codec that 500'd on top-level string writes - both fixed and regression-tested.
Status
LIVE
Key concepts
page-scoped-toolsone-registry-three-facadeshonest-asyncconsent-gated-qanext-call-contractidempotent-submitrest-source-of-truthexternal-agent-verification
Capabilities
webmcp-tool-discoverymcp-public-tools-listinbox-submit-pollqa-corpus-searchconsent-gated-publishidempotent-request-intake
Technologies
TypeScript, Bun, Hono, Postgres, Prisma, WebMCP, MCP, JSON-RPC
Evidence
  • agentbadge.xyz exposes 16 tools through one shared registry across three facades - WebMCP via document.modelContext (Chrome OT), POST /mcp/public JSON-RPC, and REST - verified live: tools/list returns 16 and .well-known/webmcp.json lists the same inventory. [demo][github]
  • Tool exposure is page-scoped: PAGE_TOOLSETS in the shared registry maps each page to its shelf, so getTools() returns the full 16 on / and focused subsets on scanner/market/verify/agent-guide pages. [github]
  • submit-request returns a request_id and poll-request reports honest states (submitted with retry_after, completed with response.answer plus a next_call to search-agent-qa); verified end-to-end on production through the WebMCP tool itself on request rq_3a672b4dc61749b08d4df706b021b895. [demo][github]
  • publish_to_qa defaults to false; completing a consented, answered request materializes a qa_* pair into the public corpus searchable via search-agent-qa and GET /api/requests/qa - live corpus verified, retract is idempotent. [demo][github]
  • Production verification found two shipped bugs: pollable inbox endpoints were publicly cacheable (submitted could be served stale after completion - fixed with Cache-Control:no-store on the inbox route family, commit 54cc6d9) and top-level JSON strings written to json columns 500'd on read via a double JSON.parse in pg/json (fixed by coercing response/payload strings to objects at the write edge, commit 4119016, with regression tests). [github]

Related Articles

Want to check your API's agent readiness?

Run a free scan →
← Back to blog