ShopMate — Agent-Native Shopping with WebMCP

An agent-native e-commerce experience where AI agents discover products, compare options, check stock, and manage carts through browser-native WebMCP tools.

Comment

Inspiration## Inspiration

Traditional e-commerce websites are designed primarily for humans. Users have to search through pages, apply filters, compare products, check availability, and manually manage their carts.

We wanted to explore a different model:

What if an AI agent could interact with an e-commerce website through structured, browser-native tools instead of relying on brittle UI automation?

That question led us to build ShopMate, an agent-native shopping experience powered by WebMCP.

What we built

ShopMate exposes the core capabilities of an e-commerce application as WebMCP tools through document.modelContext.

The application currently exposes 10 tools:

  • search_products
  • filter_products
  • get_product_details
  • compare_products
  • check_stock
  • calculate_cart_total
  • add_to_cart
  • remove_from_cart
  • update_cart
  • build_bundle

Read-only operations can be performed autonomously, while state-changing operations require human approval.

This creates a human-in-the-loop shopping experience where an agent can perform useful work while the user remains in control of consequential actions.

For example, an agent can:

  1. Search for laptops.
  2. Filter them by price, brand, category, or stock.
  3. Retrieve detailed specifications.
  4. Compare multiple products.
  5. Check inventory.
  6. Ask the user for approval.
  7. Add the selected product to the cart.
  8. Calculate the resulting cart total.

How we built it

ShopMate was built with:

  • Next.js 16
  • React 19
  • TypeScript
  • Tailwind CSS
  • React Context for application state
  • Browser-native WebMCP APIs through document.modelContext

A major part of the implementation was making WebMCP registration reliable inside React's rendering lifecycle.

We designed the registration system to be idempotent so that React re-renders and Strict Mode do not create duplicate tool registrations.

We also added a diagnostics and activity system so that WebMCP availability, registered tools, tool changes, and agent activity can be observed directly inside the application.

Challenges

One of our biggest challenges was that WebMCP registration interacts with the React lifecycle in ways that are easy to get wrong.

Our initial browser implementation encountered a Maximum update depth exceeded error. The underlying problem was not duplicate WebMCP registration itself, but the interaction between registration, diagnostics state updates, effects, and event listeners.

We investigated the lifecycle, added dedicated React lifecycle tests, and fixed the ownership of the WebMCP toolchange listener. We also eliminated a race involving the approval state reference.

Another interesting issue was the browser-generated toolchange event during initial registration. Since the browser emits a tool-change event for each registered tool, registering 10 tools produced unnecessary activity-panel noise. We kept the listener but suppressed those expected initialization events and retained logging for genuine post-registration tool changes.

What we learned

This project taught us that making an application "agent-compatible" is more than exposing a list of functions.

The tools need:

  • Clear schemas and descriptions.
  • Predictable inputs and outputs.
  • Safe boundaries around state-changing actions.
  • Idempotent registration.
  • Correct lifecycle management.
  • Human approval for consequential actions.
  • Observability so developers can understand what the agent is doing.

We also learned how important it is to test both the tool layer and the actual React/browser lifecycle. Our standalone WebMCP tests passed while the real browser initially exposed a lifecycle issue, which led us to add dedicated React and Strict Mode tests.

Final result

ShopMate now exposes all 10 intended WebMCP tools, supports human approval for cart mutations, and has automated tests covering registration, discovery, execution, approval, diagnostics, Strict Mode behavior, and listener lifecycle.

The project demonstrates how existing web applications can evolve from interfaces that humans click into interfaces that AI agents can understand and operate through structured browser-native capabilities.

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for ShopMate — Agent-Native Shopping with WebMCP

Built With

Share this project:

Updates

Submission history