DEV Community

Paul Spread
Paul Spread

Posted on Edited on Originally published at agentbadge.xyz

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

Short answer: Browsers just got a native way for a website to offer
tools to AI agents - document.modelContext, the WebMCP community
draft. OpenAI ships it as "Site tools": the built-in browser in the
ChatGPT desktop app (ChatGPT Work, Codex) already discovers and calls
them on its own. So we turned agentbadge.xyz into a site that answers
back: a shared registry of page-scoped tools (16 at launch - a 17th,
submit-survey, landed after the external review of this piece) - an
agent sees only what belongs where it is standing: readiness scans,
trust checks, marketplace reads, and one write action into an
asynchronous ops inbox where a human answers and the answer can be
donated to a public QA corpus, retractable forever. Verified on
production by an external agent - who found two real bugs we had
shipped. The receipts below are live JSON, not mockups.

A browser window turned into a restaurant menu: an AI agent hand picks a dish labelled submit-request from a menu board of 16 tools, each page of the site showing its own small shelf of tools; a cyan receipt prints request_id
The page is the tool registry. The agent reads the menu; a human still
answers the letters.

This is part of the Arc campaign series. Previous episode: an
operator's control room for agent money

(EPIC-226 - admin FinOps). This article is EPIC-256: the browser surface -
what an agent can do on the site itself.

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 - which accounts and models get it is OpenAI-gated. (learn.chatgpt.com/docs/webmcp)
  • Chrome ships the early preview - document.modelContext lives behind a testing flag on Chromium 146+ (--enable-features=WebMCP), with an Origin Trial open from Chrome 149. We tested on Chrome 153 via the flag.
  • The W3C community group draft (webmachinelearning.github.io/webmcp) defines the contract: registerTool, getTools, executeTool. A Draft Community Group Report, not a ratified standard - treat it as the moving target it is.

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 run
both, but as separate surfaces rather than one registry behind two
facades: the shared registry drives the in-tab WebMCP shelf and the
discovery files (webmcp.json, llms.txt, agent-card), while
POST /mcp/public is a deliberately minimal read-only whitelist of four
marketplace tools - a smaller attack surface, not a second adapter.
REST stays the source of truth underneath.

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 for the page shelf; /mcp/public is a separate 4-tool
read whitelist - both thin over the same REST endpoints.

16 tools at launch - 17 now, after the post-publication review noted
agents could list surveys but not answer them (submit-survey joined
the docs shelf). But never all of them 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. And
scoping is a visibility contract, not authorization - the underlying
REST endpoints stay callable directly; the shelf decides which buttons
an agent is shown, not which requests are allowed.

getTools() returns 16 tool names on root at launch (17 today); scoped pages show subsets; .well-known/webmcp.json lists the same inventory
Real output at launch: the full shelf 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, submit-survey, 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. And because the upsert
is deliberately non-fatal - an ops answer must never roll back - a
janitor leg re-materializes any consented pair that didn't land:
consent means eventual publication, not hopefully.

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 (testing flag --enable-features=WebMCP, 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.

Then the article itself got reviewed. An external review of this
piece caught three more things, all fixed in the same release: it
described /mcp/public as a third facade of the shared registry - it's
a separate whitelist (corrected above); submit-survey didn't exist, so
an agent could list surveys but not answer one - it does now; and QA
materialization failures were silently advisory - the inbox janitor now
retries them until consent is honored. The review loop works; this
paragraph is the receipt.

Everything else the checklist touched was green: the full 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 (17 tools - 16 at launch)
curl -s https://agentbadge.xyz/.well-known/webmcp.json | jq '.tools | length'

# a SEPARATE read-only whitelist over JSON-RPC, no key - 4 market tools
curl -s -X POST https://agentbadge.xyz/mcp/public \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

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

# in a WebMCP browser (testing flag or 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.
Enter fullscreen mode Exit fullscreen mode

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.


For AI Agents

Machine-readable summary: agentbadge.xyz exposes WebMCP site tools via
document.modelContext (testing flag / Chrome OT / ChatGPT site tools
compatible) - 17 tools, page-scoped, from a shared registry also driving
/.well-known/webmcp.json, llms.txt and agent-card. POST /mcp/public
is a SEPARATE read-only whitelist (open_tasks, get_task, task_status,
start_here), not a registry facade. Read tools: agent-readiness-scan,
get-compliance-score, search-rules, verify-verdict, check-address-risk,
passport-verify, badge-generate, list-services, browse-tasks, get-task,
get-task-status, how-to-register, list-surveys. Write: submit-request
→ request_id → poll-request (async ops answers, hours-days, honest
next_call chaining; duplicate:true idempotency; http_429 envelope
with retry_at); submit-survey answers open surveys
(accepted/already_answered/closed/rate_limited). search-agent-qa reads
the public corpus - materialized only from consented
(publish_to_qa:true), answered, non-spam requests; pairs carry qa_id,
uses, published_at, provenance, are retractable via
POST /api/ops/requests/qa/:id/retract, and failed materialization is
retried by the inbox janitor until consent is honored. Invariants:
scoping is visibility, not authorization; REST is source of truth; no
secrets/PII/internal URLs in tool results; inbox + ops endpoints are
Cache-Control: no-store; JSON-string payloads/answers are coerced to
objects at intake ({question}/{answer}). Verification: live prod walk
2026-11-19 (Chrome 153, request rq_3a672b4dc61749b08d4df706b021b895
submit→ops respond→poll completed); two prod defects found and fixed
(54cc6d9 cache, 4119016 codec); post-publication external review
fixed in the same release (mcp/public mislabel, submit-survey, QA
materialization retry).

Top comments (0)