tions and dynamic interfaces over static document models.

Step 1: Define Strict Tool Schemas

Agent invocation fails predictably when parameter types are ambiguous. Define input schemas using JSON Schema validation principles. Include required fields, type constraints, and descriptive enums. Avoid optional parameters unless they have explicit default behaviors.

Step 2: Register at Runtime with Feature Detection

Do not assume browser support. Wrap registration in a capability check. Use the current navigator.modelContext.registerTool() API. The deprecated window.agent pattern (removed from spec in August 2025) must be avoided entirely.

Step 3: Implement Execution Context & Error Boundaries

Tools execute in the same origin as the page. They inherit session cookies, local storage, and user state. Handle failures gracefully. Return structured error objects that agents can parse without hallucinating recovery steps.

Step 4: Manage Lifecycle & Cleanup

Single-page applications navigate without full page reloads. Tools registered on initial load must be unregistered when routes change or components unmount. Orphaned registrations cause agent confusion and memory leaks.

Architecture Decisions & Rationale

Runtime Registration Over Manifests: The spec intentionally omits static discovery files. This reduces deployment complexity and allows tools to be conditionally registered based on user role, feature flags, or A/B test variants. It also aligns with modern frontend frameworks that hydrate dynamically.

Session-Bound Execution: WebMCP tools run in the active tab context. This eliminates the need for OAuth token exchange or API key management for public-facing interactions. Agents inherit the user's authenticated session automatically. The trade-off is that tools cannot perform cross-origin requests without proper CORS configuration.

Schema Versioning: Tool definitions should include a version field. When parameter structures change, increment the version. Agents can inspect versions before invocation, preventing runtime type mismatches. This is a production best practice not explicitly mandated by the draft spec but critical for long-term stability.

Graceful Degradation: Since agent clients do not yet consume WebMCP tools, maintain fallback UI patterns. Ensure forms, buttons, and navigation remain fully operable via traditional DOM interaction. WebMCP should augment, not replace, standard user interfaces.

Implementation Example (TypeScript)

interface ToolParameter {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object';
  required: boolean;
  description: string;
}

interface WebMCPToolDefinition {
  name: string;
  version: string;
  description: string;
  parameters: ToolParameter[];
  execute: (args: Record<string, unknown>) => Promise<ToolResult>;
}

interface ToolResult {
  success: boolean;
  data?: unknown;
  error?: string;
}

class AgentToolRegistry {
  private registeredTools: Set<string> = new Set();

  public isSupported(): boolean {
    return typeof navigator !== 'undefined' && 
           'modelContext' in navigator && 
           typeof (navigator as any).modelContext.registerTool === 'function';
  }

  public registerTool(tool: WebMCPToolDefinition): void {
    if (!this.isSupported()) {
      console.warn('[WebMCP] Browser does not support navigator.modelContext');
      return;
    }

    if (this.registeredTools.has(tool.name)) {
      console.warn(`[WebMCP] Tool ${tool.name} already registered. Skipping.`);
      return;
    }

    const registrationPayload = {
      name: tool.name,
      version: tool.version,
      description: tool.description,
      parameters: tool.parameters,
      handler: tool.execute
    };

    try {
      (navigator as any).modelContext.registerTool(registrationPayload);
      this.registeredTools.add(tool.name);
      console.log(`[WebMCP] Registered tool: ${tool.name}@${tool.version}`);
    } catch (err) {
      console.error('[WebMCP] Registration failed:', err);
    }
  }

  public unregisterTool(toolName: string): void {
    if (!this.isSupported()) return;
    
    try {
      (navigator as any).modelContext.unregisterTool(toolName);
      this.registeredTools.delete(toolName);
      console.log(`[WebMCP] Unregistered tool: ${toolName}`);
    } catch (err) {
      console.error(`[WebMCP] Unregistration failed for ${toolName}:`, err);
    }
  }

  public cleanup(): void {
    this.registeredTools.forEach(name => this.unregisterTool(name));
  }
}

// Usage Example
const registry = new AgentToolRegistry();

const inventoryQueryTool: WebMCPToolDefinition = {
  name: 'query_availability',
  version: '1.0.0',
  description: 'Check real-time inventory for a specific product category and date range.',
  parameters: [
    { name: 'category', type: 'string', required: true, description: 'Product category identifier' },
    { name: 'start_date', type: 'string', required: true, description: 'ISO 8601 start date' },
    { name: 'end_date', type: 'string', required: true, description: 'ISO 8601 end date' },
    { name: 'include_sold', type: 'boolean', required: false, description: 'Include sold-out items in response' }
  ],
  execute: async (args) => {
    try {
      const response = await fetch(`/api/inventory?category=${args.category}&from=${args.start_date}&to=${args.end_date}`);
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const data = await response.json();
      return { success: true, data };
    } catch (err) {
      return { success: false, error: err instanceof Error ? err.message : 'Unknown failure' };
    }
  }
};

registry.registerTool(inventoryQueryTool);

// Cleanup on SPA route change or component unmount
window.addEventListener('beforeunload', () => registry.cleanup());

Pitfall Guide

1. Legacy API Reliance

Explanation: Codebases still referencing window.agent or custom window.mcp.tools.push() patterns are operating against deprecated specifications. These patterns were removed from the draft in August 2025 and will never be recognized by browser aggregators. Fix: Audit all registration calls. Replace with navigator.modelContext.registerTool(). Implement a feature detection wrapper to prevent runtime errors in unsupported environments.

2. Manifest/Endpoint Assumption

Explanation: Developers frequently attempt to expose tools via /well-known/mcp.json or static configuration files. WebMCP explicitly rejects this model. Discovery happens exclusively through runtime JavaScript execution. Fix: Remove static discovery endpoints. Shift tool registration to application initialization hooks, framework lifecycle methods, or route guards. Ensure registration occurs after DOM hydration but before agent interaction windows.

3. Protocol Conflation

Explanation: Treating WebMCP as a drop-in replacement for server-side MCP leads to architectural mismatches. Server MCP uses JSON-RPC over HTTP/WebSocket with explicit authentication. WebMCP runs in-browser, inherits session state, and lacks cross-origin capabilities by default. Fix: Maintain clear boundaries. Use server MCP for backend service orchestration. Use WebMCP for browser-tab interactions. Do not attempt to tunnel WebMCP calls through backend proxies unless implementing a custom bridge extension.

4. Flag-State Complacency

Explanation: Assuming WebMCP is universally available because Chrome 146 shipped it. The implementation remains behind enable-webmcp-testing. Production users will not enable it until it ships by default, projected late 2026. Fix: Always wrap registration in capability checks. Log support status to telemetry. Maintain full fallback UI for traditional interaction. Treat WebMCP as an enhancement layer, not a dependency.

5. Schema Drift & Type Ambiguity

Explanation: Agents fail predictably when tool parameters lack strict typing or when optional fields have implicit defaults. Unvalidated inputs cause execution failures that agents cannot recover from autonomously. Fix: Define explicit JSON Schema structures. Include type constraints, required flags, and descriptive enums. Validate inputs server-side before execution. Version tool definitions and expose version metadata in registration payloads.

6. Orphaned Registrations

Explanation: Single-page applications navigate without full page reloads. Tools registered on initial load persist across route changes, causing duplicate registrations, memory leaks, and agent confusion when stale handlers execute. Fix: Implement unregisterTool() calls on route transitions, component unmounts, or session expiration. Use framework lifecycle hooks (React useEffect cleanup, Vue onUnmounted, Angular ngOnDestroy) to guarantee cleanup.

7. Agent Readiness Overestimation

Explanation: Building critical user flows exclusively around WebMCP tools before agent clients support them. This creates broken experiences for traditional users and false confidence in automation metrics. Fix: Maintain parallel interaction paths. Ensure all WebMCP-exposed functionality remains accessible via standard HTML forms, buttons, and navigation. Use feature flags to gradually roll out agent-specific enhancements. Monitor actual agent invocation rates before prioritizing WebMCP over traditional UX.

Production Bundle

Action Checklist

• Verify browser support: Wrap all navigator.modelContext calls in runtime capability detection
• Migrate legacy patterns: Replace window.agent or custom window.mcp registrations with spec-compliant API
• Define strict schemas: Include type constraints, required flags, and version metadata for every tool
• Implement lifecycle management: Register on mount, unregister on unmount/route change
• Maintain fallback UI: Ensure all exposed functionality remains operable via traditional DOM interaction
• Add telemetry hooks: Log registration success, invocation attempts, and execution failures
• Test in flag-enabled environments: Validate tool discovery and execution in Chrome 146+ with enable-webmcp-testing active
• Document versioning strategy: Establish schema change protocols and backward compatibility windows

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal enterprise tools with authenticated APIs	Server-Side MCP	Mature ecosystem, explicit auth, broad agent support	Medium (backend infrastructure, OAuth setup)
Public-facing booking/search interfaces	WebMCP + Fallback UI	Low maintenance, session inheritance, forward-compat	Low (frontend registration, schema definition)
Legacy web applications with rigid layouts	DOM Scraping / Computer Use	No code changes required, works immediately	High (continuous monitoring, selector maintenance)
High-security portals with strict CORS	Server-Side MCP or Custom Bridge	Browser-native tools cannot bypass origin restrictions	High (proxy infrastructure, token management)
Marketing sites with static content	WebMCP (lightweight)	Minimal overhead, prepares for future agent indexing	Low (static registration, simple schemas)

Configuration Template

// webmcp.config.ts
export const WEBMCP_CONFIG = {
  api: {
    register: 'navigator.modelContext.registerTool',
    unregister: 'navigator.modelContext.unregisterTool',
    deprecated: ['window.agent', 'window.mcp.tools']
  },
  lifecycle: {
    autoCleanup: true,
    cleanupTriggers: ['routeChange', 'beforeunload', 'sessionExpire'],
    maxRetries: 2,
    retryDelayMs: 500
  },
  telemetry: {
    enabled: true,
    endpoints: {
      registration: '/telemetry/webmcp/register',
      invocation: '/telemetry/webmcp/invoke',
      error: '/telemetry/webmcp/error'
    },
    samplingRate: 0.1
  },
  fallback: {
    strategy: 'parallel',
    uiPreservation: true,
    agentDetection: false // Do not gate UI on agent presence
  }
};

Quick Start Guide

1. Install capability wrapper: Add a feature detection module that checks for navigator.modelContext.registerTool before any registration attempt. Log support status to your analytics pipeline.
2. Define tool schema: Create a TypeScript interface for your tool parameters. Include name, version, description, and parameters with strict typing. Avoid optional fields unless they have explicit defaults.
3. Register at initialization: Call registerTool() during application bootstrap or route activation. Pass the schema and an async execution handler that returns structured { success, data, error } objects.
4. Implement cleanup: Attach unregisterTool() calls to framework unmount hooks or navigation events. Verify cleanup executes before route transitions complete.
5. Validate in flag environment: Open Chrome 146+, enable enable-webmcp-testing in chrome://flags, and verify tool discovery using browser devtools or a test agent client. Confirm fallback UI remains fully functional.