agentbadge.xyz 透過 WebMCP 上線 16 個按頁面提供的 AI 智能體工具
Your Website Has a Menu Now: 16 Page-Scoped Tools for AI Agents, Live on WebMCP
agentbadge.xyz 透過 WebMCP 上線 16 個按頁面提供的工具,讓兼容的 AI 智能體可在瀏覽器內發現並呼叫。唯一寫入工具會將提問送入營運團隊的收件匣並返回 request_id,答覆需時數小時至數日;只有提問者同意後,答覆才會加入可撤回的公開 QA 資料集。作者以 Chrome 153 和外部 Agent 在正式環境驗證,並修復了過時快取及 JSON 字串解碼兩項問題。
Short answer: Browsers just got a native way for a website to offer
tools to AI agents -document.modelContext, the proposed WebMCP
standard. 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: 16 tools in a shared registry, scoped per page so an agent sees
only what belongs where it is standing - readiness scans, trust checks,
marketplace reads, and one write action: 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.

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.
(
learn.chatgpt.com/docs/webmcp) -
Chrome runs an Origin Trial -
document.modelContextlives behind--enable-features=WebMCPon 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?

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:

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?

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:

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:

Verbatim prod: completed, the answer inline, and a suggestion where
to look next.
Where do good answers go? A corpus with a consent gate

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.

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?

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.
For AI Agents
Machine-readable summary: agentbadge.xyz exposes WebMCP site tools via
document.modelContext (Chrome OT / ChatGPT site tools compatible) -
16 tools, page-scoped, from a shared registry also driving
/.well-known/webmcp.json, llms.txt, agent-card and POST /mcp/public
(JSON-RPC tools/list, keyless). 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). 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, and are retractable via POST /api/ops/requests/qa/:id/retract.
Invariants: 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).
來源:DEV Community · dev.to