WebMCP Tool Schema Generator

Understanding WebMCP: Connecting AI Agents to the Web

The Web Model Context Protocol (WebMCP) is a revolutionary standard that bridges the gap between Large Language Models (LLMs), AI browser assistants, and web pages. It defines how websites can expose local capabilities—known as "tools"—to AI agents crawling, interacting with, or assisting users within a browser environment. By providing a clean interface, developers can let AI agents search products, add items to a shopping cart, fill forms, and run computations securely on behalf of the user.

WebMCP establishes a standardized communication layer that operates directly inside the browser's execution context. With security rules such as SecureContext enforcement (HTTPS or localhost) and explicit user approval constraints, it represents the future of browser automation and user assistance. To integrate tools on your site, you must provide either a declarative markup structure or imperative JavaScript registration scripts. Our WebMCP Tool Schema Generator helps you draft, validate, and preview these specifications.

Declarative API vs. Imperative API: Which Should You Use?

WebMCP supports two core execution modes depending on how your website is architected. Choosing the right mode ensures smooth AI agent integration:

• Declarative API (HTML Form Generator): Exposes tools using standard HTML <form> elements decorated with WebMCP-specific attributes. This approach requires zero JavaScript to register, rendering schemas directly in the document object model (DOM). The browser scans the page for form tags containing attributes like toolname and tooldescription and automatically registers them. It is highly recommended for server-rendered web pages, CMS platforms, and traditional multi-page web setups.
• Imperative API (JS/TS Code Generator): Registers custom functions programmatically on the client side using the navigator.modelContext.registerTool interface. This gives developers granular, code-level control over inputs, schema parameters, validations, and callback executions. It is perfect for Single Page Applications (SPAs) built with modern frameworks (such as React, Vue, Svelte, or Next.js) where pages change dynamically without full reload cycles.

Mode 1: The Declarative HTML Specification

In Declarative mode, a tool is represented by a standard web form. The form and its inputs map to the tool's properties and variables. Let's break down the key attributes used in this setup:

• toolname: A unique, camelCase identifier for the tool. This is what the LLM recognizes as the action to trigger (e.g., searchProducts).
• tooldescription: A clear description explaining what the tool does, who it is for, and what it returns. The AI uses this description to determine if and when it should execute the tool.
• toolautosubmit: A boolean flag. If present, it instructs the browser agent to automatically submit the form once the LLM fills out the parameter fields, bypassing the need for manual button clicks.
• action and method: Standard HTML form parameters directing where parameters should be sent via HTTP request (e.g. GET or POST).

Form fields use standard input tags like <input> or <select> mapping to parameters. Every parameter should contain a toolparamdescription attribute to tell the AI what format and content the parameter expects. If you are writing React components, you can use our HTML to JSX Converter to easily turn this declarative HTML markup into interactive JSX forms.

Mode 2: The Imperative JavaScript/TypeScript Specification

In Imperative mode, developers register tools dynamically. The navigator.modelContext.registerTool method accepts an object with the following schema details:

1. name: The identifier string for the tool.
2. description: Explaining the function to the LLM agent.
3. inputSchema: A JSON schema string defining input parameters, their types, required status, boundaries, and list options. Use our JSON to TS Interface Converter if you need to convert typescript definitions into compatible JSON formats.
4. execute: An asynchronous callback function where the actual tool action takes place. This function receives the inputs validated against the JSON Schema and runs client-side logic.
5. annotations.readOnlyHint: A boolean flag that hints to the agent whether the execution is safe to call without risk of mutating server-side data, allowing faster execution flows.

Building and Validating Parameters Correctly

One of the most critical aspects of designing WebMCP schemas is defining strict input guidelines. If parameter formats are ambiguous, the AI agent may generate invalid payload values, resulting in errors.

For instance, when designing search criteria, always use enumerations for fixed categorical values (such as product categories like "electronics" or "clothing"). In Declarative mode, this is achieved with <select> and <option> tags. In Imperative mode, this translates into an enum array constraint within the property definition of the JSON Schema. If you are managing complex time constraints, check our Cron Job Generator for detailed scheduling integrations.

Security Considerations and Local Testing

WebMCP runs directly in the user's browser, meaning it has access to active sessions, cookies, and local data. Security is paramount:

• Secure Context Required: The protocol is exclusively active in Secure Contexts. Your tool pages must be served over https:// or http://localhost/. Production URLs without SSL will fail to load the WebMCP agent.
• Browser Execution Consent: When an AI agent attempts to invoke a registered tool, the browser prompts the user for explicit authorization unless the action is completely sandboxed and safe.
• Local Testing Flags: To test your WebMCP integration locally before publishing it live, you must enable the WebMCP support in your browser. For Google Chrome, navigate to chrome://flags/#enable-webmcp-testing, enable the flag, and restart the browser.

Step-by-Step Tutorial: Creating a Product Search Tool

Walk through these steps to generate and run your first WebMCP tool:

1. Select Mode: Choose between Mode 1 (Declarative) or Mode 2 (Imperative) depending on your application structure.
2. Define Identity: Enter the name (e.g., searchCatalog) and a thorough description (e.g., "Search store inventory by query and category filter").
3. Add Parameters: Add a required string/text parameter for the search term (e.g., query) and an optional dropdown/enum parameter for categories (e.g., category with options all, books, apparel).
4. Review Warnings: Check the validator section to ensure there are no camelCase errors, missing parameter descriptions, or excessively long titles.
5. Copy and Integrate: Copy the code using the single-click copy button and place it into your HTML index page or frontend codebase. Verify the Chrome flag is enabled, and try querying the page using a WebMCP-compatible browser agent.