webmcp-user-interaction

WebMCP User Interaction (Human-in-the-Loop)

Before writing code

Fetch live docs:

1. Fetch https://webmachinelearning.github.io/webmcp/ for the ModelContextClient and requestUserInteraction specification
2. Web-search webmcp requestUserInteraction ModelContextClient specification for the callback API
3. Web-search site:developer.chrome.com webmcp user interaction confirmation for Chrome implementation guidance
4. Web-search webmcp human-in-the-loop agent confirmation for community patterns

Conceptual Architecture

What requestUserInteraction Does

client.requestUserInteraction(callback) is a method on the ModelContextClient object passed to every tool's execute callback. It pauses tool execution, hands control to the user (via a site-provided UI), and resumes when the user responds.

This is the primary mechanism for human-in-the-loop approval in WebMCP.

Why It Matters

AI agents can make mistakes — hallucinate, misinterpret instructions, or select the wrong option. For irreversible actions (purchases, account changes, data deletion), requiring user confirmation prevents costly errors. WebMCP's design explicitly accommodates shared-context interactions where the user and agent collaborate.

Flow

Agent calls tool → execute(input, client) starts
  → Tool calls client.requestUserInteraction(callback)
    → Browser pauses tool execution
    → Site shows UI to the user (modal, banner, etc.)
    → User approves or rejects
    → callback resolves with user's response
  → Tool resumes with user's answer
  → Tool returns result to agent

When to Use requestUserInteraction

| Action | User Interaction? | Rationale | |--------|:--:|-----------| | Search products | No | Read-only, no side effects | | View product details | No | Read-only | | Add to cart | Maybe | Low risk, but could confirm for expensive items | | Apply coupon | No | Easily reversible | | Place order / checkout | Yes | Irreversible, involves payment | | Delete account | Yes | Destructive, irreversible | | Change subscription plan | Yes | Financial commitment | | Initiate return | Yes | Starts a process that may be hard to undo | | Update shipping address | Maybe | Depends on timing relative to order |

Implementation Pattern

navigator.modelContext.registerTool({
  name: "placeOrder",
  description: "Complete the purchase with the items in the cart",
  inputSchema: { type: "object", properties: {} },
  annotations: { destructiveHint: true },
  async execute(input, client) {
    // 1. Gather order summary
    const summary = await fetch("/api/cart/summary").then(r => r.json());

    // 2. Ask user to confirm
    const approved = await client.requestUserInteraction((resolve) => {
      // Show a confirmation UI — this is your site's custom modal/dialog
      showOrderConfirmation(summary, (userApproved) => {
        resolve(userApproved);
      });
    });

    // 3. Proceed or cancel based on user response
    if (!approved) {
      return { status: "canceled", message: "User declined the order" };
    }

    // 4. Execute the order
    const result = await fetch("/api/orders", { method: "POST" });
    return await result.json();
  }
});

UI Design for Confirmation

The site controls how the confirmation UI looks. Common patterns:

• Modal dialog — "AI wants to place an order for $127.50. Allow?"
• Inline banner — Highlighted section showing pending agent action
• Slide-over panel — Side panel with order details and approve/reject buttons
• Toast with action — Brief notification with "Approve" / "Cancel" buttons

Multi-Step Interactions

A tool can call requestUserInteraction multiple times:

1. First interaction: "Select a shipping option" → user picks Express
2. Second interaction: "Confirm order total of $142.30?" → user approves
3. Tool proceeds with both choices

Best Practices

• Always show the user what the agent is about to do, not just "Allow action?"
• Include relevant details (amounts, item names, addresses) in the confirmation UI
• Provide a clear "Cancel" option that returns a structured cancellation response to the agent
• Keep the interaction UI accessible (keyboard navigable, screen reader compatible)
• Time out long-running interactions — if the user doesn't respond within a reasonable period, cancel gracefully
• Log user approvals and rejections for audit trails

Fetch the specification for exact requestUserInteraction callback signature, return types, and browser behavior before implementing.