Architecture & boundaries
A practical guide to exposing website capabilities to AI agents without confusing discoverability with authority. This document describes design principles and candidate patterns; it is not a statement that every capability is implemented or that WebMCP is a ratified part of the MCP specification.
1. Purpose and scope
WebMCP concerns the browser/page boundary: how a website can describe and expose structured actions to compatible agent experiences. MCP is the broader protocol for connecting AI applications to tools and context. The two are related but not interchangeable. This site is an independent Tech 4 Humanity project, not an official Chrome or MCP project.
2. Design principles
A tool description helps a client understand an operation. It does not grant the user’s authority, bypass site policy, or make page content trustworthy.
Expose the smallest useful operation, validate all inputs server-side or at the trusted execution boundary, scope identity and permissions, and deny unknown capabilities.
Writes, publication, external communications, purchases, account changes and destructive operations need explicit approval bound to the exact action and payload.
A screenshot, static page, API-presence check or unit test alone does not prove end-to-end execution. Record target, action, before/after state, receipt, denial path and recovery result.
3. Integration patterns
- Browser-native WebMCP: use where the target site and browser genuinely support the interface. Detect capability and handle absence gracefully.
- Remote MCP: use for reusable agent-facing tools across compatible clients, with deliberate authentication, authorisation, transport and retention controls.
- Extension-mediated capture: possible fallback for permitted pages, subject to browser permissions and user-mediated access. Do not assume this is required for the first release.
- Connectors and files: appropriate for SaaS APIs, exports and documents where scoped access is available.
- Manual paste/upload: broad, low-integration baseline; preserve source URL, capture time and user-provided provenance where available.
The preferred first step is one low-risk end-to-end use case with a defined fallback, not implementing every adapter in parallel.
4. Safety and trust model
- Treat page text, retrieved documents and model output as untrusted input, not as privileged instructions.
- Keep credentials and privileged connector tokens out of public website bundles and logs.
- Validate origin, schema, size, timeout and allowed action at the execution boundary.
- Separate read-only actions from writes and require exact-payload approval for consequential operations.
- Redact sensitive values from logs and receipts; record enough metadata to audit outcomes without retaining unnecessary content.
- Make failure, timeout and uncertain outcomes explicit; do not silently replay writes.
5. Proposed context-plane relationship
A shared context engine may normalise permitted inputs, preserve provenance, classify freshness and sensitivity, link duplicates and contradictions, create task-specific context packs, validate the pack, and emit receipts. Candidate interfaces such as context.capture, context.inspect and context.pack.validate remain proposals until the owners agree schemas, permissions and lifecycle policy. They are not existing endpoints merely because they are documented.
6. Verification requirements
- Official primary-source links and status labels are current.
- Browser capability detection makes no stronger claim than presence/absence.
- At least one agreed read-only workflow succeeds on the actual target.
- Invalid input, denial, origin boundary, timeout, redaction and recovery tests pass.
- Mobile/desktop navigation, keyboard access and outbound links are checked.
- Production URL and deployed commit are matched; rollback path is documented.