WebMCP: How AI Agents Will Interact with Web Pages

// How agents interact with the web today - fragile and blind
// browser-automation/checkout.ts
import { chromium } from 'playwright';
 
async function automatedCheckout(items: string[]) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://store.example.com');
 
  // Fragile: breaks if CSS class changes
  await page.click('.cart-button');
 
  // Guessing: no idea what fields are required
  await page.fill('#address-line-1', '123 Main St');
 
  // Blind: no structured error handling
  await page.click('[data-testid="submit-order"]');
 
  // Hope it worked?
  const confirmation = await page.textContent('.confirmation-message');
  return confirmation;
}

// How WebMCP changes the interaction model
// The website explicitly declares what it can do
 
// Before: Agent scrapes DOM, guesses functionality
// <button class="btn-primary" onclick="checkout()">Complete Purchase</button>
// Agent sees: "a button with text 'Complete Purchase'" - knows nothing about parameters
 
// After: Website registers a structured tool
if (navigator.modelContext) {
  navigator.modelContext.registerTool({
    name: "complete_purchase",
    description: "Process checkout with items in cart. Validates inventory, applies discounts, and charges payment method on file.",
    inputSchema: {
      type: "object",
      properties: {
        shippingSpeed: {
          type: "string",
          enum: ["standard", "express", "overnight"],
          description: "Shipping speed selection"
        },
        giftWrap: {
          type: "boolean",
          description: "Whether to add gift wrapping"
        },
        promoCode: {
          type: "string",
          description: "Optional promotional code"
        }
      },
      required: ["shippingSpeed"]
    },
    annotations: {
      destructiveHint: true,
      idempotentHint: false
    },
    execute: async (input) => {
      const result = await processCheckout(input);
      return [{ type: "text", text: JSON.stringify(result) }];
    }
  });
}

// store/product-page.ts
// Registering WebMCP tools on an e-commerce product page
 
function registerProductTools(product: Product) {
  if (!navigator.modelContext) return;
 
  // Tool 1: Search products with filters
  navigator.modelContext.registerTool({
    name: "search_products",
    description: "Search the store catalog with filters for category, price range, size, color, and availability",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query text" },
        category: {
          type: "string",
          enum: ["dresses", "tops", "pants", "shoes", "accessories"]
        },
        priceRange: {
          type: "object",
          properties: {
            min: { type: "number" },
            max: { type: "number" }
          }
        },
        size: {
          type: "string",
          enum: ["XS", "S", "M", "L", "XL"]
        },
        inStock: { type: "boolean", description: "Only show items in stock" }
      },
      required: ["query"]
    },
    annotations: {
      readOnlyHint: true
    },
    execute: async (input) => {
      const results = await searchProducts(input);
      return [{
        type: "text",
        text: JSON.stringify({
          count: results.length,
          products: results.map(p => ({
            id: p.id,
            name: p.name,
            price: p.price,
            sizes: p.availableSizes,
            rating: p.averageRating
          }))
        })
      }];
    }
  });
 
  // Tool 2: Get detailed product information
  navigator.modelContext.registerTool({
    name: "get_product_details",
    description: `Get full details for product: ${product.name}. Includes pricing, reviews, size guide, and material composition.`,
    inputSchema: {
      type: "object",
      properties: {
        includeReviews: {
          type: "boolean",
          description: "Include customer reviews in response"
        },
        reviewCount: {
          type: "number",
          description: "Number of reviews to include (max 10)"
        }
      }
    },
    annotations: {
      readOnlyHint: true
    },
    execute: async (input) => {
      const details = await getProductDetails(product.id);
      const response: Record<string, unknown> = {
        name: details.name,
        price: details.price,
        description: details.fullDescription,
        materials: details.materials,
        sizeGuide: details.sizeGuide,
        availability: details.stockStatus
      };
 
      if (input.includeReviews) {
        response.reviews = details.reviews.slice(0, input.reviewCount || 5);
      }
 
      return [{ type: "text", text: JSON.stringify(response) }];
    }
  });
 
  // Tool 3: Add to cart (destructive action)
  navigator.modelContext.registerTool({
    name: "add_to_cart",
    description: "Add the current product to the shopping cart with selected size and quantity",
    inputSchema: {
      type: "object",
      properties: {
        size: {
          type: "string",
          enum: product.availableSizes,
          description: "Selected size"
        },
        quantity: {
          type: "number",
          minimum: 1,
          maximum: 10,
          description: "Quantity to add"
        }
      },
      required: ["size", "quantity"]
    },
    annotations: {
      destructiveHint: false,
      idempotentHint: false
    },
    execute: async (input) => {
      const cartItem = await addToCart(product.id, input.size, input.quantity);
      return [{
        type: "text",
        text: JSON.stringify({
          added: true,
          cartTotal: cartItem.cartTotal,
          itemCount: cartItem.totalItems
        })
      }];
    }
  });
}

// components/ProductPage.tsx
import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';
 
interface ProductPageProps {
  productId: string;
  product: Product;
}
 
function ProductPage({ productId, product }: ProductPageProps) {
  const [cartCount, setCartCount] = useState(0);
 
  // Register tool tied to this component's lifecycle
  useWebMCP({
    name: 'add_to_cart',
    description: `Add ${product.name} to shopping cart. Price: $${product.price}. Available sizes: ${product.availableSizes.join(', ')}`,
    inputSchema: {
      quantity: z.number().min(1).max(10).default(1),
      size: z.enum(product.availableSizes as [string, ...string[]])
    },
    handler: async ({ quantity, size }) => {
      const result = await addToCart(productId, size, quantity);
      setCartCount(prev => prev + quantity);
      return {
        success: true,
        quantity,
        size,
        newCartTotal: result.total
      };
    }
  });
 
  useWebMCP({
    name: 'check_size_availability',
    description: 'Check which sizes are currently in stock for this product',
    inputSchema: {},
    handler: async () => {
      const availability = await checkStock(productId);
      return {
        product: product.name,
        sizes: availability
      };
    }
  });
 
  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <p>Cart items: {cartCount}</p>
      {/* Regular UI rendering */}
    </div>
  );
}

// security/url-shielding.ts
// Tool definition uses symbolic API references
navigator.modelContext.registerTool({
  name: "process_payment",
  description: "Process payment for current order",
  inputSchema: {
    type: "object",
    properties: {
      paymentMethodId: { type: "string" }
    },
    required: ["paymentMethodId"]
  },
  // Internal API endpoint is never exposed to the agent
  // @PAYMENT_API resolves server-side after token validation
  execute: async (input) => {
    // The agent never sees the actual URL
    // Internally this calls: POST /api/v3/payments/charge
    // But the mapping happens server-side with wmcp-token validation
    const result = await fetch('/wmcp/resolve/@PAYMENT_API', {
      method: 'POST',
      headers: {
        'X-WMCP-Token': await getWMCPToken(),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        action: 'charge',
        paymentMethodId: input.paymentMethodId
      })
    });
 
    return [{ type: "text", text: await result.text() }];
  }
});

// security/scopes.ts
navigator.modelContext.registerTool({
  name: "update_profile",
  description: "Update user profile information",
  scopes: ["read:profile", "write:profile"],
  inputSchema: {
    type: "object",
    properties: {
      displayName: { type: "string", maxLength: 50 },
      bio: { type: "string", maxLength: 500 }
    }
  },
  // Auto-throttle prevents abuse
  throttle: {
    rate: "5/min",
    burst: 2
  },
  execute: async (input) => {
    // Scope validation happens before execute is called
    // If agent doesn't have write:profile scope, this never runs
    const updated = await updateProfile(input);
    return [{ type: "text", text: JSON.stringify(updated) }];
  }
});

// The AI agent's interaction flow with WebMCP
// Agent receives structured tool list from the store page:
 
// Step 1: Search with precise filters
const searchResult = await tools.search_products({
  query: "summer dress",
  category: "dresses",
  priceRange: { min: 0, max: 100 },
  size: "M",
  inStock: true
});
 
// Step 2: Get details on top matches
for (const product of searchResult.products.slice(0, 3)) {
  const details = await tools.get_product_details({
    productId: product.id,
    includeReviews: true,
    reviewCount: 5
  });
  // Agent can now compare products with full context
}
 
// Step 3: Present options to user with rich data
// The user sees results in the store's own UI
// Agent and user share the same visual context

// insurance-application/tools.ts
navigator.modelContext.registerTool({
  name: "fill_application_section",
  description: "Fill a section of the insurance application. Validates inputs against policy requirements.",
  inputSchema: {
    type: "object",
    properties: {
      section: {
        type: "string",
        enum: ["personal_info", "vehicle_info", "coverage_selection", "payment"],
        description: "Which section to fill"
      },
      data: {
        type: "object",
        description: "Section-specific data matching the form fields"
      }
    },
    required: ["section", "data"]
  },
  annotations: {
    destructiveHint: false,
    idempotentHint: true
  },
  execute: async (input) => {
    const validation = await validateAndFill(input.section, input.data);
    return [{
      type: "text",
      text: JSON.stringify({
        filled: validation.success,
        errors: validation.errors,
        nextSection: validation.nextRequired,
        completionPercent: validation.progress
      })
    }];
  }
});
 
navigator.modelContext.registerTool({
  name: "get_form_requirements",
  description: "Get required fields and validation rules for a form section",
  inputSchema: {
    type: "object",
    properties: {
      section: {
        type: "string",
        enum: ["personal_info", "vehicle_info", "coverage_selection", "payment"]
      }
    },
    required: ["section"]
  },
  annotations: { readOnlyHint: true },
  execute: async (input) => {
    const requirements = getFieldRequirements(input.section);
    return [{ type: "text", text: JSON.stringify(requirements) }];
  }
});

// 1. Install the polyfill
// npm install @mcp-b/global
 
// 2. Initialize in your app entry point
// app/layout.tsx or index.ts
import '@mcp-b/global';
 
// 3. Register tools anywhere in your application
// lib/webmcp-tools.ts
 
export function registerSiteTools() {
  if (!navigator.modelContext) {
    console.log('WebMCP not available');
    return;
  }
 
  navigator.modelContext.registerTool({
    name: "site_search",
    description: "Search all content on this website including blog posts, documentation, and projects",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
        contentType: {
          type: "string",
          enum: ["all", "blog", "docs", "projects"],
          description: "Filter by content type"
        },
        limit: {
          type: "number",
          description: "Max results to return",
          maximum: 20
        }
      },
      required: ["query"]
    },
    annotations: { readOnlyHint: true },
    execute: async (input) => {
      const results = await fetch(
        `/api/search?q=${encodeURIComponent(input.query)}&type=${input.contentType || 'all'}&limit=${input.limit || 10}`
      );
      return [{ type: "text", text: await results.text() }];
    }
  });
 
  navigator.modelContext.registerTool({
    name: "get_page_info",
    description: "Get information about the current page including title, description, and navigation context",
    inputSchema: {
      type: "object",
      properties: {}
    },
    annotations: { readOnlyHint: true },
    execute: async () => {
      return [{
        type: "text",
        text: JSON.stringify({
          title: document.title,
          url: window.location.href,
          description: document
            .querySelector('meta[name="description"]')
            ?.getAttribute('content'),
          headings: Array.from(document.querySelectorAll('h1, h2'))
            .map(h => h.textContent)
        })
      }];
    }
  });
}

// components/BlogPost.tsx
import { useWebMCP } from '@mcp-b/react-webmcp';
 
function BlogPost({ post }: { post: BlogPostType }) {
  useWebMCP({
    name: 'get_blog_post_summary',
    description: `Get a structured summary of the blog post: "${post.title}"`,
    inputSchema: {},
    handler: async () => ({
      title: post.title,
      author: post.author,
      publishDate: post.publishDate,
      category: post.category,
      tags: post.tags,
      readingTime: post.readingTime,
      excerpt: post.description
    })
  });
 
  return <article>{/* post rendering */}</article>;
}