webmcp-dev-patterns

WebMCP Development Patterns

Before writing code

Fetch live docs:

1. Fetch https://developer.chrome.com/blog/webmcp for the latest developer guidance and patterns
2. Web-search webmcp development best practices patterns for community patterns
3. Web-search webmcp SPA single page application routing for SPA-specific patterns
4. Web-search webmcp SEO agent discovery for discoverability patterns

Conceptual Architecture

SPA Tool Lifecycle

In single-page applications, tools must be managed across route changes:

// React example: register/unregister tools on route change
useEffect(() => {
  const tools = getToolsForRoute(currentRoute);
  tools.forEach(tool => navigator.modelContext.registerTool(tool));

  return () => {
    // Cleanup on route change
    tools.forEach(tool => navigator.modelContext.unregisterTool(tool.name));
  };
}, [currentRoute]);

Key principles:

• Clear context on navigation (clearContext() or selective unregisterTool)
• Register tools relevant to the current view only
• Handle async data loading — don't register tools until data is available
• Consider preregistering common tools (search) that are always relevant

Error Handling

Tools should handle errors at multiple levels:

Network errors:

async execute(input) {
  try {
    const res = await fetch(`/api/products?q=${input.query}`);
    if (!res.ok) {
      return { status: "error", code: res.status, message: "Server error" };
    }
    return await res.json();
  } catch (err) {
    return { status: "error", code: "network_error", message: "Unable to reach server" };
  }
}

Business logic errors:

async execute(input) {
  const product = await fetchProduct(input.productId);
  if (!product) {
    return { status: "error", code: "not_found", message: "Product not found" };
  }
  if (!product.inStock) {
    return { status: "error", code: "out_of_stock", message: "Product is out of stock" };
  }
  // proceed...
}

Consistent error format:

{ status: "error", code: "error_code", message: "Human-readable message" }

Performance Optimization

WebMCP tools are inherently faster than UI scraping, but optimize further:

• Avoid redundant fetches — Cache API responses within a tool session
• Batch operations — Combine related API calls in a single tool
• Lightweight responses — Return only what the agent needs, not entire page data
• Async registration — Register tools after the critical rendering path
• Lazy tool loading — Load tool execute logic only when the tool is invoked

Multi-Site Agent Patterns

Agents may navigate across multiple sites, each with WebMCP:

Agent Journey:
1. Open site-a.com → discovers tools [searchA, addToCartA, checkoutA]
2. Call searchA("wireless headphones") → get results
3. Open site-b.com → discovers tools [searchB, addToCartB, checkoutB]
4. Call searchB("wireless headphones") → get results
5. Agent compares results and recommends best option to user
6. User picks site-a → agent calls addToCartA and checkoutA

Design implications:

• Tool names should be descriptive enough to distinguish across sites
• Return standardized response formats (product name, price, currency, availability)
• Include site identity in tool descriptions ("Search products on ExampleStore")

Accessibility

WebMCP tools should support accessible interactions:

• User interaction prompts (confirmations) must be keyboard-navigable
• Screen readers should announce agent actions and confirmation dialogs
• ARIA labels on confirmation UI elements
• Focus management — return focus appropriately after user interaction
• High-contrast support for confirmation dialogs

SEO and AI Discovery

WebMCP enhances AI discoverability:

• Agents prefer sites with structured tools over sites requiring scraping
• Tool names and descriptions are effectively "agent SEO" — write them clearly
• Consider how AI search engines (Google AI Mode) discover and rank your tools
• Declarative form annotations make your site instantly agent-ready for crawlers
• WebMCP may become a ranking factor — early adoption is a competitive advantage

Versioning

As tools evolve:

• Version tool schemas when making breaking changes
• Consider tool name versioning (searchProductsV2) for backward compatibility
• Document tool changes in a changelog
• Deprecate old tools gracefully before removing them

Production Deployment Checklist

• [ ] All tools tested with at least one AI agent
• [ ] Schemas validated with a JSON Schema validator
• [ ] Annotations (destructiveHint, etc.) set on all tools
• [ ] User interaction flows tested for sensitive actions
• [ ] Error handling covers network failures, auth expiration, and business logic
• [ ] Server-side rate limiting on all APIs called by tools
• [ ] Audit logging for tool invocations
• [ ] Feature detection with polyfill fallback
• [ ] Performance tested under concurrent agent load
• [ ] Accessibility verified for confirmation dialogs
• [ ] CSRF protection on all state-changing endpoints
• [ ] Monitoring/alerting for tool invocation errors

Monitoring and Observability

Track agent interactions in production:

• Tool invocation count — Which tools are used most?
• Tool success/failure rate — Which tools fail frequently?
• Agent conversion rate — Do agent-assisted sessions convert better?
• Latency percentiles — How fast are tool responses?
• User interaction outcomes — How often do users approve vs decline?

Commerce Platform Integration

Commerce platforms will likely add built-in WebMCP support:

• Shopify — May add toolname attributes to Liquid templates
• Magento — Custom modules for tool registration
• WooCommerce — WordPress plugins for WebMCP
• Headless CMS — API-first platforms can provide tool definitions

Monitor your platform's announcements for native WebMCP support.

Best Practices Summary

• Treat tool descriptions as a first-class UX concern — they are the agent's interface
• Start with read-only tools, add transactional tools incrementally
• Test every tool with a real AI agent before shipping
• Monitor tool usage in production and iterate on descriptions/schemas
• Keep tools focused — one action per tool, not multi-step wizards
• Document your tool surface for other developers and future agents

Fetch the latest community patterns, Chrome DevTools features, and platform integration announcements before architecting.