WebMCP Implementation Guide

WebMCP Implementation Guide

This document outlines the implementation strategy for integrating WebMCP (Web Model Context Protocol) into our website. WebMCP allows AI agents to interact with our site reliably and efficiently, moving beyond screen scraping.

Status: Early Preview (Chrome 146+) Goal: Make the site “agent-ready” for future sessions.

Why WebMCP?

How It Works

WebMCP introduces navigator.modelContext. We can expose capabilities via two methods:

1. Declarative API (HTML Attributes)

Best for simple interactions like form submissions or button clicks. Add tool-name attributes to existing elements.

Example:

<!-- Expose a flight booking action -->
<button 
  tool-name="book_flight" 
  tool-description="Books the currently selected flight"
>
  Book Now
</button>

<!-- Expose a search form -->
<form tool-name="search_articles">
  <input name="query" type="text" placeholder="Search..." />
  <button type="submit">Go</button>
</form>

2. Imperative API (JavaScript)

Best for complex logic or when no direct UI element exists. Use the mcp global object (available via navigator.modelContext or a polyfill).

Example:

if (navigator.modelContext) {
  // Register a tool for an agent to call
  navigator.modelContext.registerTool('delete_task', {
    description: 'Deletes a task by ID',
    parameters: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'The ID of the task to delete' }
      },
      required: ['id']
    },
    execute: async ({ id }) => {
      console.log(`Agent requested to delete task: ${id}`);
      // await performDelete(id);
      return { result: 'success' };
    }
  });
}

Implementation Strategy

We will treat WebMCP as a progressive enhancement.

Phase 1: Core Actions (SaaS / App context)

• Identify critical workflows (e.g., “Create Ticket”, “Export Data”).
• Apply Declarative API attributes to primary buttons.

Phase 2: Content Capabilities (Blog / Content context)

• Expose “Summarize Article” or “Search Archive” tools via Imperative API if they don’t map 1:1 to UI buttons.
• Ensure tool-name attributes are unique and descriptive.

Best Practices for AI Consumption

To ensure AI coding agents can interact flawlessly with your tools:

1. Use Verb-Noun Naming: Tool names should be actions on objects (e.g., book_flight, delete_task, search_articles). Avoid ambiguous names like submit or click.
2. Explicit Input Names: For declarative forms, every <input>, <select>, and <textarea> MUST have a name attribute. This name becomes the parameter key in the tool schema.
   • Bad: <input type="text" /> (Agent sees: parameter: unknown)
   • Good: <input name="search_query" type="text" /> (Agent sees: parameter: search_query)
3. Descriptive Tool Descriptions: Use tool-description attributes for any button or form where the action isn’t 100% obvious from the text content alone.

Testing & Verification

1. Enable Flag: In Chrome, enable #experimental-web-platform-features.
2. Verify via Console: Check if the browser supports WebMCP logic (or if polyfills are active).
3. Agent Simulation: Use browser tools or specific agent debuggers to ensure tools are discoverable.

For a full walkthrough, refer to the WebMCP Demo Video.