webmcp-development-guide

name	webmcp-development-guide
description	Use when designing, implementing, reviewing, testing, or documenting browser-side WebMCP tools. Covers document.modelContext, Imperative and Declarative APIs, tool schemas, page state, API/MCP boundaries, security, and Inspector/Evals verification. It is not a replacement for a server-side MCP implementation guide.

WebMCP Development Guide

This skill turns the project's four-day course and the official Chrome WebMCP documentation into an actionable development workflow. First determine whether the user needs a website to expose tools, an Agent to invoke tools, a backend MCP implementation, or a comparison of the three. Do not describe WebMCP as a traditional MCP Server, and do not assume the browser supports the current preview API.

Respond in the user's language unless requested otherwise. Preserve API identifiers and official links in English.

Choose the operating mode

• Add WebMCP to an existing website: read "Integrating WebMCP into an existing website" in Implementation recipes. Inventory existing forms, JavaScript or TypeScript domain functions, APIs, authentication state, and SPA lifecycles before choosing Declarative or Imperative. Do not create a parallel workflow.
• Requirements analysis, tool strategy, or API/MCP selection: read Four-day course context. Also read Official baseline when current browser limitations, exact API fields, or official status matter.
• HTML form integration: read the Declarative API section in Implementation recipes.
• SPA queries, navigation, page state, or existing JavaScript function integration: read the Imperative API section in the implementation recipes.
• Persistence, authentication, transactions, ERP, or cross-application reuse: read the backend-boundary section in the implementation recipes and explicitly state that WebMCP is an entry point, not a database or authorization system.
• Security review, cross-origin behavior, cancellation, regression testing, or pre-release checks: read the Verification and security checklist.

If the current project contains docs/01-webmcp-can-do.md through docs/04-webmcp-api-mcp-difference.md, a README.md, or an existing demo, inspect their naming and workflows first. Reuse existing domain functions for new tools; do not rewrite unrelated UI or backend code for demonstration purposes.

Existing-site integration principles

Integrate WebMCP as progressive enhancement. Existing buttons, forms, routes, validation, APIs, and authorization flows must continue to work. WebMCP adds a structured entry point that an Agent can understand and invoke. Do not reverse-engineer business logic by simulating DOM clicks, and do not let a WebMCP execute handler become a second set of business rules.

Use this minimum integration sequence:

1. Select one Critical User Journey and list its current UI entry point, frontend handler, backend API, authentication and authorization requirements, and success state.
2. Organize validation, API calls, and state updates into domain functions shared by the UI and WebMCP. Reuse an adequate existing function instead of rewriting it solely for integration.
3. Prefer Declarative attributes for an existing semantic <form>. Use Imperative registerTool() for non-form actions, queries, navigation, or dynamic SPA state.
4. Use document.modelContext?.registerTool for feature detection. When the API is absent, skip tool registration without affecting the human workflow.
5. Manage SPA and conditional-capability lifecycles. Register a tool only while it is valid for the current page state, and unregister it when the route changes, the component unmounts, or the state becomes invalid.
6. Verify separately that the human UI and Agent tool paths use the same validation, APIs, permissions, and state updates. Then use Inspector and Evals to verify tool discovery and the complete journey.

If the request is only to let an Agent operate any unmodified third-party website, do not claim that WebMCP can do this directly. The website must expose WebMCP tools itself; otherwise evaluate conventional browser automation.

Required design sequence

1. Start with one Critical User Journey, such as "find availability, create a booking, cancel the booking," and split it into a small number of single-responsibility tools. Do not turn every button into a tool.
2. Decide whether the current page can actually execute each tool. Register or unregister dynamic tools as page state changes; prefer static registration when dynamic management is unnecessary.
3. Choose the API. Prefer Declarative for an existing semantic HTML form; use Imperative for non-form queries, navigation, and state changes.
4. Define the name, purpose, and JSON Schema before connecting the tool to an existing frontend function. Schema guides an Agent but is not a security boundary; execute and the backend must validate again.
5. Update the UI when tool execution finishes. Return a short, stable structured result and actionable errors. The human workflow must still work in browsers without WebMCP.
6. Decide whether to call a backend API based on data risk. Formal persistence, multi-user sharing, authorization, transactions, and secrets belong on the backend. Frontend-only handling is appropriate only for UI state or instructional demos.

Implementation invariants

• Use document.modelContext?.registerTool for feature detection. WebMCP remains a proposal and early preview; the page must not fail when the API is unavailable.
• An Imperative tool must include at least name, description, inputSchema, and execute. Add title and annotations when useful. The application creates an AbortController and passes { signal: controller.signal } to registerTool for lifecycle management. Pass the second execute argument, { signal }, to cancellable fetch calls and long-running work.
• A Declarative form must preserve normal label, name, browser validation, and submission behavior before adding toolname, tooldescription, and toolparamdescription. Add toolautosubmit only when the Agent should submit directly.
• readOnlyHint: true only states that a tool does not mutate state; it is not access control. Consider untrustedContentHint: true when returning user-generated or external data.
• Use explicit schema types, required, and appropriate enum, format, or pattern constraints. Validate strictly in code, and make errors tell the Agent how to correct the request.
• Preserve user confirmation for sensitive actions such as writes, payments, deletions, and submissions. Never place passwords, private keys, or privileged tokens in a web tool.
• Design cross-origin tools only for an explicit trust relationship. An iframe requires allow="tools"; the provider lists trusted origins in exposedTo; the caller requests them explicitly with getTools({ fromOrigins }). Do not use wildcard origins.

Verification and delivery

Verify in this order: deterministic function and input tests, tool registration and unregistration plus cancellation, UI state and API or persistence behavior, manual Model Context Tool Inspector inspection, and Evals that verify the Agent selects the right tools, passes the right arguments, and completes the journey. Do not infer persistence merely because the page displays success.

Delivery notes must include the API mode, whether a backend is required, browser and Origin Trial or local-flag prerequisites, test commands and results, fallback behavior for unsupported browsers, and any preview fields that may still change. Preserve required English API names and official links.

Official entry points

• WebMCP overview
• WebMCP and AI agents
• Imperative API
• Declarative API
• When to use WebMCP and MCP
• Best practices
• Tool security
• WebMCP Evals
• WebMCP explainer and implementation status