WebMCP Consent Layer

Why this use case is a strong fit for WebMCP

WebMCP lets any website register tools that AI agents can discover and invoke. Some runtimes already gate risky calls behind their own native approval UIs — ChatGPT's built-in browser shows a "Site tools" review panel, and the MCP-B Agent Chrome extension has per-tool approval settings. But most WebMCP clients don't provide any consent mechanism at all: every registered tool runs silently, whether it's a read-only health check or an irreversible production rollback. This project closes that gap at the package level. It adds a consent and annotation layer to @mcp-b/react-webmcp that any site using WebMCP can adopt — one hook, one provider — without every site inventing its own approval flow from scratch.

How it creates a better user experience

The consent layer is deliberately selective. Every tool registration carries structured metadata — scope, reversibility, risk level — and only actions flagged as requiring approval actually interrupt the user with a consent card. Low-risk reads (fetching service health, listing deployments) execute immediately and are logged silently in the audit trail. When a high-risk call like rollbackDeployment fires, the consent card shows exactly what's at stake: which systems are affected, whether the action is reversible, and what the agent wants to do. The audit log records every tool call — approved, denied, or auto-approved — so users can review the full history of what an agent did, not just the decisions they were asked to make. Cross-tab attention cues (a favicon badge and title blink) ensure pending approvals aren't missed when the user is in a different tab. For irreversible, high-risk operations, an optional WebAuthn gate (Touch ID, Windows Hello, or a hardware key) raises the bar beyond a simple click.

What people and agents can do together that was difficult or impossible before

Without a consent layer, site authors face a binary choice: either don't register destructive tools with WebMCP (safe but crippled), or register them and hope the runtime provides its own gate (flexible but risky on runtimes that don't). With useGuardedWebMCP, an agent can be handed genuinely powerful tools — rollbackDeployment, deleteUser, revokeAccess — with a human gating only the specific calls that matter. The agent handles the routine reads autonomously; the human approves or denies only the irreversible, high-impact actions. The result is collaborative agentic work where the human's attention is spent on the decisions that actually need judgment, not on rubber-stamping every API call.

Brief implementation explanation

The core mechanism is a React hook, useGuardedWebMCP, that wraps the existing useWebMCP from @mcp-b/react-webmcp — it composes rather than forks it. Each tool registration includes a ConsentMetadata object (scope, reversible, riskLevel, requiresApproval, optionally requireUserPresence). The hook maps this metadata to standard MCP ToolAnnotations (readOnlyHint, destructiveHint, idempotentHint) via toMcpAnnotations(), so native runtimes that do have their own gates receive real behavioral hints. When requiresApproval is true and no native gate is detected, the call suspends in a framework-agnostic ConsentBroker, which manages a queue of pending requests, session preapproval for reversible tools, timeout/expiry, and decision event streams. The React layer (ConsentBrokerProvider, useConsentBroker, usePendingConsentRequests) lets any component render approval UI against the broker's state. The on-page card includes an isTrusted guard to reject script-dispatched synthetic clicks — a best-effort defense, not a tamper-proof boundary, which is why hasNativeConsentGate() exists as an escape hatch to defer to real browser/OS-level permission prompts where available. The upstream PR (link) adds only the hook, broker, types, annotations, WebAuthn presence verification, and tests to @mcp-b/react-webmcp — the demo app is a separate workspace member, not part of the package.

Built With

• react
• vite
• viteplus