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

```typescript
// 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.