June 23, 2026•13 min read•OpenHermit Team

WebMCPDeclarative APIHTML FormsBrowser AIChrome 149

WebMCP Declarative API: Make Any HTML Form AI-Callable in 3 Minutes (No JavaScript Required)

WebMCP's Declarative API exposes HTML forms to AI agents using three attributes—toolname, tooldescription, tool-param-description. Zero JavaScript, instant agent compatibility.

📋 LLM ABSTRACT

WebMCP's Declarative API turns ordinary HTML forms into AI-callable tools using three HTML attributes: toolname, tooldescription, and tool-param-description. Chrome 149 ships this in a public origin trial (no longer Canary-only). The W3C spec published March 9, 2026 formalizes HTML-based tool registration as the zero-JavaScript path to agent readiness. Static sites, WordPress, Shopify—any CMS with form markup—gains instant agent compatibility without touching the event loop.

Note: OpenHermit bridges legacy HTML to the WebMCP standard so autonomous agents can discover and execute your site's capabilities. This post covers the Declarative API layer—the fastest path from static markup to agent-ready tools.

3 min

Implementation Time

Add three HTML attributes to an existing form. No build step, no JavaScript bundle.

Chrome 149

Origin Trial Status

Public origin trial running Chrome 149–156, replacing the earlier Canary flag requirement (Source: NoHacks.co, June 2026).

0 lines JS

Code Overhead

Forms register as tools at parse time. Agents discover them through the browser's native navigator.modelContext without custom scripts.

The Problem: Imperative APIs Lock Out Static Sites

WebMCP's imperative API—navigator.modelContext.registerTool()—is powerful but requires JavaScript execution. That excludes:

• Static site generators (Astro, Hugo, Jekyll) where the build output is pure HTML
• WordPress sites with minimal custom JS
• Marketing landing pages optimized for Core Web Vitals (every script hurts LCP)
• Forms embedded in CMS content blocks where developers don't control the page lifecycle

The Declarative API solves this by moving tool registration into HTML attributes that the browser parses when the DOM loads.

📘 The Two WebMCP APIs (W3C Draft, March 9, 2026)

Imperative API: navigator.modelContext.registerTool({...}) in JavaScript. Full control over tool lifecycle, input validation, async execute handlers. Best for SPAs and dynamic workflows.

Declarative API: toolname, tooldescription, and tool-param-description attributes on <form> and <input> elements. Browser auto-registers the form as a tool. Best for static sites, CMS pages, or any scenario where you want existing forms to become agent-accessible without JavaScript.

Both APIs expose tools through the same navigator.modelContext interface. Agents see no difference—they discover tools, read JSON Schemas, and invoke them via structured parameters.

How the Declarative API Works: Three HTML Attributes

The spec defines three new attributes recognized in secure contexts (HTTPS only):

1. `toolname` (on `<form>`)

Identifies the tool to AI agents. Use lowercase, hyphens, verb-first naming:

<form toolname="request-quote">

Best practice from the Chrome team: Use verbs that describe the action precisely. Distinguish executing vs. initiating a UI flow—e.g., create-event vs. start-event-creation-process (Source: DataCamp WebMCP Tutorial, 2026).

2. `tooldescription` (on `<form>`)

Natural language description of what the tool does. This text is passed to the AI model's tool-use prompt, so clarity matters:

<form 
  toolname="request-quote" 
  tooldescription="Submit a project quote request with service type, budget range, and contact details. Returns confirmation and estimated response time.">

3. `tool-param-description` (on `<input>`, `<select>`, `<textarea>`)

Describes each parameter. The browser builds a JSON Schema from the form's name attributes and these descriptions:

<input 
  type="text" 
  name="service_type" 
  tool-param-description="Type of service requested (web development, mobile app, AI integration)"
  required>

<input 
  type="number" 
  name="budget" 
  tool-param-description="Estimated project budget in USD"
  min="1000">

Generated JSON Schema (browser-internal, not visible in your markup):

{
  "type": "object",
  "properties": {
    "service_type": {
      "type": "string",
      "description": "Type of service requested (web development, mobile app, AI integration)"
    },
    "budget": {
      "type": "number",
      "description": "Estimated project budget in USD",
      "minimum": 1000
    }
  },
  "required": ["service_type"]
}

The required HTML attribute maps to required in the schema. Type inference uses HTML5 input types (number, email, url, date).

Complete Example: Agent-Ready Contact Form

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Agent-Ready Contact Page</title>
</head>
<body>

<form 
  toolname="submit-contact" 
  tooldescription="Send a contact inquiry with name, email, and message. Returns confirmation ID and expected response window."
  action="/api/contact" 
  method="POST">
  
  <label for="name">Name</label>
  <input 
    type="text" 
    id="name" 
    name="name" 
    tool-param-description="Full name of the person contacting"
    required>
  
  <label for="email">Email</label>
  <input 
    type="email" 
    id="email" 
    name="email" 
    tool-param-description="Email address for response"
    required>
  
  <label for="message">Message</label>
  <textarea 
    id="message" 
    name="message" 
    tool-param-description="Inquiry details or question"
    rows="5"
    required></textarea>
  
  <button type="submit">Send</button>
</form>

</body>
</html>

What the agent sees (via navigator.modelContext):

• Tool name: submit-contact
• Description: "Send a contact inquiry with name, email, and message. Returns confirmation ID and expected response window."
• Input schema: three required string parameters (name, email, message) with descriptions
• Execute handler: submits the form's action URL via POST

When an agent invokes this tool, the browser fills the form programmatically and triggers submission. The SubmitEvent.agentInvoked flag (added in the March 2026 spec) lets your backend differentiate agent submissions from human ones—useful for rate limiting or analytics.

⚠️ Security: HTTPS + Same-Origin Enforcement

WebMCP tools only register in secure contexts (window.isSecureContext === true). This means:

• HTTPS in production (HTTP fails silently—tools don't register)

• Localhost or 127.0.0.1 for local dev (browsers treat these as secure)

• iframes are excluded: only top-level browsing contexts can be Model Context Providers. An agent cannot invoke tools in an embedded iframe.

The W3C spec identifies two trust boundaries: (1) when a website registers tools (exposes capabilities to the browser), and (2) when an agent calls a tool (site receives untrusted input from the agent). The browser prompts user consent for specific web app + agent pairs (Source: Bug0.com Chrome 146 Guide, 2026).

Visual Feedback: CSS Pseudo-Classes for Agent Interactions

Chrome applies two pseudo-classes during agent tool invocation:

• :tool-form-active — applied to the <form> while an agent is filling it
• :tool-submit-active — applied to the <button type="submit"> during invocation

Use these to provide visual feedback even when the agent operates headlessly or in the background:

form:tool-form-active {
  outline: 2px solid #00CED1;
  background: rgba(0, 206, 209, 0.05);
}

button[type="submit"]:tool-submit-active {
  background: #00CED1;
  color: #000;
}

(Source: DataCamp WebMCP Tutorial, 2026)

When to Use Declarative vs. Imperative

Use Declarative API	Use Imperative API
Existing HTML forms (contact, quote request, newsletter signup)	Multi-step workflows with client-side state
Static site generators (Astro, Hugo, 11ty)	API calls that don't map to form submission (search, filter, add-to-cart in SPAs)
CMS pages (WordPress, Contentful, Sanity) where you control markup but not page JS	Custom validation logic beyond HTML5 constraints
Zero-JS requirement (Core Web Vitals optimization, accessibility)	Dynamic tool registration (tools appear/disappear based on auth state)

Both APIs can coexist on the same page. A WordPress site might use Declarative for contact forms and Imperative for a custom product search widget.

Browser Compatibility: Chrome 149 Origin Trial + Polyfill Fallback

As of June 2026, WebMCP is in a public origin trial in Chrome 149, having moved from the earlier Chrome 146 Canary flag preview. Microsoft co-authored the spec through the W3C, but WebMCP is not listed in Microsoft Edge's official 147 release notes, so treat Edge support as unconfirmed.

To enable in production:

Register your origin at the Chrome Origin Trials console
Add the Origin-Trial HTTP header or <meta> tag to your pages

For cross-browser compatibility today:

A polyfill is available at docs.mcpb.ai, which provides a JavaScript shim that parses toolname attributes and registers tools via a fallback mechanism.

Feature detection (always check before relying on WebMCP):

if ('modelContext' in navigator && window.isSecureContext) {
  // Native WebMCP available
  console.log('WebMCP tools registered via Declarative API');
} else {
  // Polyfill or fallback (e.g., JSON-LD structured data)
  console.log('WebMCP not supported—using fallback layer');
}

✅ Production Checklist: Declarative API Deployment

• HTTPS in production: WebMCP requires secure context. Test with window.isSecureContext.

• Origin trial token: Register at chrome://origintrials and add the token via HTTP header or meta tag.

• Descriptive toolname: Use verb-first, lowercase-hyphenated names (e.g., book-appointment, not Booking).

• Clear tooldescription: This text is passed to the AI model's tool-use prompt—be specific about what the tool does and what it returns.

• Meaningful param descriptions: The agent reads these to understand how to construct valid inputs. Don't just repeat the field name.

• HTML5 validation: Use required, type="email", min, max, pattern—these map to JSON Schema constraints.

• SubmitEvent.agentInvoked check: On your backend, use this flag to track agent vs. human submissions for analytics or rate limiting.

• Polyfill for non-Chrome browsers: Load the mcp-b polyfill conditionally to ensure cross-browser graceful degradation.

How WebMCP Relates to Other AI Agent Standards

The WebMCP Declarative API is one layer in the agent-ready web stack:

llms.txt: Static identity file describing who you are and what content you offer. Google's John Mueller called llms.txt "purely speculative for now" in June 2026, noting that none of the AI systems use it, and pointed developers toward WebMCP because "they have clear goals & processes".

JSON-LD / Schema.org: Semantic metadata for search engines and AI summarization. Describes entities and relationships, not executable actions.

WebMCP Declarative API: Makes your forms callable. Agents can discover submit-contact, book-appointment, request-quote and invoke them with structured parameters.

WebMCP Imperative API: JavaScript-based tool registration for dynamic, multi-step, or API-driven actions.

MCP (Model Context Protocol): Backend server-to-server protocol. Traditional MCP requires a backend server (Python or Node.js), separate authentication, and server-to-server communication. WebMCP runs entirely in the browser tab.

Think of it as layers: JSON-LD provides static context, WebMCP Declarative exposes forms as tools, WebMCP Imperative handles complex interactions, and MCP connects agents to backend services.

Real-World Use Cases

Service Booking Sites

A hair salon's existing appointment form becomes agent-callable:

<form 
  toolname="book-haircut" 
  tooldescription="Book a haircut appointment with preferred stylist, date, and time"
  action="/api/appointments" 
  method="POST">
  
  <select name="stylist" tool-param-description="Preferred stylist name">
    <option value="alex">Alex</option>
    <option value="jordan">Jordan</option>
  </select>
  
  <input type="date" name="date" tool-param-description="Appointment date (YYYY-MM-DD)" required>
  
  <input type="time" name="time" tool-param-description="Preferred time slot" required>
  
  <button type="submit">Book</button>
</form>

An agent (Claude, ChatGPT, Gemini) visiting this page discovers the book-haircut tool, reads the schema, and can execute bookings on behalf of the user.

E-Commerce Product Filtering

A product catalog with filter controls:

<form 
  toolname="filter-products" 
  tooldescription="Filter product catalog by category, price range, and availability"
  action="/products" 
  method="GET">
  
  <select name="category" tool-param-description="Product category">
    <option value="shoes">Shoes</option>
    <option value="bags">Bags</option>
  </select>
  
  <input type="number" name="min_price" tool-param-description="Minimum price in USD">
  <input type="number" name="max_price" tool-param-description="Maximum price in USD">
  
  <input type="checkbox" name="in_stock" value="true" tool-param-description="Show only in-stock items">
  
  <button type="submit">Apply Filters</button>
</form>

This becomes a zero-JS agent-ready filtering tool that works in Chrome 149+ with origin trial enabled.

Lead Generation Landing Pages

A marketing agency's quote request form:

<form 
  toolname="request-marketing-quote" 
  tooldescription="Request a custom marketing campaign quote with project type, budget, and timeline"
  action="/api/leads" 
  method="POST">
  
  <select name="project_type" tool-param-description="Type of marketing project" required>
    <option value="seo">SEO</option>
    <option value="ppc">PPC Ads</option>
    <option value="content">Content Marketing</option>
  </select>
  
  <input type="number" name="budget" tool-param-description="Monthly budget in USD" min="500" required>
  
  <input type="text" name="timeline" tool-param-description="Desired start timeline (e.g., 'immediately', 'next month')">
  
  <button type="submit">Get Quote</button>
</form>

Debugging: Model Context Tool Inspector Extension

The Model Context Tool Inspector extension lists all registered tools on the current page with full schema, lets you execute any tool with a JSON input editor, view execution output in real time, and optionally chain calls through Gemini for agent-style testing.

Install it from the Chrome Web Store, open DevTools, and navigate to the "WebMCP Inspector" panel. You'll see every tool registered via both Declarative and Imperative APIs, along with their input schemas and descriptions.

Manual tool execution:

// DevTools console
const tools = await navigator.modelContextTesting.getTools();
console.log(tools.map(t => t.name));
// → ["submit-contact", "book-appointment", "filter-products"]

const result = await navigator.modelContextTesting.executeTool("submit-contact", {
  name: "Test User",
  email: "test@example.com",
  message: "Testing WebMCP Declarative API"
});
console.log(result);

(Source: WebFuse WebMCP Cheat Sheet, 2026)

Does the Declarative API work in Firefox or Safari?

As of March 2026, Chrome 146 Canary is the only browser with a working implementation. Edge will almost certainly follow quickly since it shares Chrome's engine. Firefox and Safari are engaged in the W3C spec process but haven't committed to timelines. Use the @mcp-b/global polyfill for cross-browser support today.

Will WebMCP attributes affect my SEO or page rank?

WebMCP attributes are ignored by search crawlers and the manifest lives at /.well-known/ (excluded from rankings). It can indirectly help you because agent-accessible sites get cited more in AI answer engines.

Can I use Declarative API on a WordPress site without custom code?

Yes, if you can edit the form HTML in your page builder or theme. Add the three attributes (toolname, tooldescription, tool-param-description) to any existing form. No plugin required. WordPress's official MCP Adapter (released February 2026) focuses on the Imperative API for dynamic content, but Declarative works on static forms out of the box.

How do I know if an agent or a human submitted my form?

The spec includes a requestUserInteraction() mechanism that pauses agent execution to ask for explicit user confirmation before sensitive actions. The browser prompts user consent for specific web app and agent pairs. On the backend, check SubmitEvent.agentInvoked (added in the March 2026 spec draft) to differentiate agent vs. human submissions.

What's the difference between WebMCP and Anthropic's MCP?

MCP (Model Context Protocol) runs server-side, requiring developers to deploy tools on backend infrastructure. WebMCP runs client-side in the browser, using JavaScript functions or annotated HTML forms. Your website becomes the MCP server, with tools defined and executed right in the browser tab, no separate server required.

Can I mix Declarative and Imperative APIs on the same page?

Yes. The browser merges tools from both sources into a single navigator.modelContext registry. A typical pattern: use Declarative for static contact/quote forms, and Imperative for dynamic search or multi-step checkout flows. Agents see one unified tool list.

Do I need to register a .well-known/webmcp manifest?

The .well-known/webmcp manifest is optional. Most sites only need the Declarative API (HTML attributes on forms) and the Imperative API (navigator.modelContext). The manifest is for discovery before the agent visits your site—think of it as robots.txt for agents.

The Competitive Window: Early Adopter Advantage

As of mid-2026, very few websites are optimized for AI agents—barely AI-ready. This is the opportunity for early adopters, reminiscent of the early days of SEO in 2005 when "search engine optimization" was a foreign concept. Those who invested then dominate search results today.

Google and Microsoft aren't backing this specification to make websites prettier—but because their AI products need it. The question is not whether WebMCP is coming. It's here. The question is whether your website is ready.

The Declarative API removes the last technical barrier: if you have an HTML form, you can be agent-ready in three minutes. No JavaScript bundle. No build step. No backend changes (beyond reading the agentInvoked flag if you want analytics).

The first batch of agent-ready sites will capture disproportionate value as autonomous browsing becomes standard. Like Mobile-First in 2015 and Core Web Vitals in 2020, WebMCP readiness will separate winners from laggards—but the window to act first is still open.

Sources & Methodology

All claims sourced from W3C documentation, Chrome team announcements, and production implementations verified as of June 2026:

W3C Web Machine Learning Community Group: WebMCP Draft Specification (March 9, 2026)
NoHacks.co: WebMCP overview and Chrome 149 origin trial status (June 9, 2026)
DataCamp: WebMCP Tutorial with Declarative API examples (2026)
WebFuse: WebMCP Cheat Sheet and Model Context Tool Inspector guide (2026)
Bug0.com: Chrome 146 DevTrial analysis (2026)
Zuplo: WebMCP adoption and declarative vs. imperative comparison (2026)

Data verified June 23, 2026. Chrome 149 origin trial timeline confirmed via official Chrome release notes and community testing reports.

MAKE YOUR WEBSITE
AGENT-READY

Add one script tag. Be discoverable by AI agents in 2 minutes.

Get Started Free →