Agent Discovery & WebMCP
How automated agents find, understand, and operate this site — the machine-readable surfaces (well-known files, llms.txt, OpenAPI) and the WebMCP tool layer that lets an in-browser agent drive the site directly.
What /.well-known/ is
/.well-known/ is a reserved path prefix defined by RFC 8615. Applications register a name (for example security.txt or change-password) and publish site-wide metadata at a predictable location so a client can discover it before interacting with the origin.
Two rules matter here:
- Well-known URIs are rooted at the domain root.
/.well-known/exampleis well-known;/app/.well-known/exampleis not. The prefix only counts at the top of the path. - A missing file is allowed. Clients must not assume one exists.
This site's Cloud app is mounted at /app, while the domain root is the Webflow marketing site. So the app serves its copies at /app/.well-known/… — reachable and useful, but technically app-relative metadata, not an RFC 8615 well-known URI. Publishing the true root-level files is a Webflow-site task.
Discovery surfaces
| Path | What it is | Served by |
|---|---|---|
/app/.well-known/webmcp | WebMCP tool catalogue (static mirror of the live registry) | Cloud app |
/app/.well-known/webmcp.json | Same catalogue at the filename the WebMCP registry convention expects | Cloud app |
/app/.well-known/agent-manifest.json | Provider manifest — endpoints, tools, data attribution | Cloud app |
/app/.well-known/agent-card.json | Tool definitions with parameters and endpoints | Cloud app |
/app/.well-known/agents.txt | Intent tiers, rate limits, human-gated submission policy | Cloud app |
/app/llms.txt | Short machine-readable site summary | Cloud app |
/app/llms-full.txt | Complete corpus (listings, guides, team) | Cloud app |
/app/openapi.yaml | OpenAPI 3.1 spec for the REST endpoints | Cloud app |
/app/robots.txt | Crawl rules (the authoritative file is at the domain root) | Cloud app |
Every app response also carries a Link header advertising these surfaces, so a client that only issues a HEAD request can find them without parsing HTML:
Link: </app/.well-known/webmcp>; rel="webmcp", </app/.well-known/agent-card.json>; rel="service-desc", …WebMCP
WebMCP is an emerging W3C Web Machine Learning Community Group proposal. It lets a page register structured tools — named functions with JSON Schema inputs — that an AI agent running in the same browser can call directly. The agent calls execute(); the tool runs on the page with the user watching. It mirrors the Model Context Protocol tool shape, but the transport is the JavaScript heap instead of HTTP.
Runtime surfaces
- Imperative API —
document.modelContext.registerTool({ name, title, description, inputSchema, annotations, execute }). - Declarative API — annotate an ordinary
<form>withtoolname,tooldescription,toolautosubmit, and per-fieldtoolparamdescription. The browser synthesises the schema from the controls, andSubmitEvent.agentInvokedtells the submit handler an agent (rather than a human) triggered it. - Live registry —
public/shared/webmcp-tools.js, loaded on every page. - Static manifest —
src/lib/webmcp-manifest.ts, served at/app/.well-known/webmcp. Keep it in sync with the live registry when tools change.
Discovery wiring
<link rel="webmcp" href="/app/.well-known/webmcp" />in the document head.Link: …; rel="webmcp"on every response (seenext.config.ts).
Annotations
Tools declare intent so an agent can decide when to confirm or sanitise:
| Annotation | Meaning |
|---|---|
readOnlyHint | No state change; confirmation may be skipped. |
consequentialHint | Significant / non-reversible — the agent or browser can force user confirmation. |
untrustedContentHint | Output contains user-generated or third-party content; apply heightened scrutiny. |
Human in the loop
Form tools are readable and fillable by any agent, but submission is designed to keep a human present. When an agent activates an intake tool, the page switches to that form so the visitor can watch it happen; a missing required answer is returned to the model as a message to ask the user for it, never invented.
Verify
# The catalogue
curl -s https://www.jamesfinelliteam.com/app/.well-known/webmcp | head
# Discovery link header on any response
curl -sI https://www.jamesfinelliteam.com/app | grep -i '^link:'
# Registered tools in the page console (Chrome 149+, WebMCP enabled)
await document.modelContext.getTools()Related
- Access policy and rate tiers:
/app/.well-known/agents.txt - Provider manifest:
/app/.well-known/agent-manifest.json - Developer documentation:
/app/docs