RetailAgentOS WebMCP Agent Storefront

RetailAgentOS uses WebMCP to let AI agents build valid carts and request quotes from a retailer’s real inventory, pricing, and policies—without guessing or taking control from shoppers.

Comment

Inspiration

I did not start RetailAgentOS to build another shopping demo. I started it because the next interface to commerce will increasingly be an AI agent—and small retailers should not be left behind.

My goal is to make agentic commerce accessible to every retailer, from a solo merchant to a global enterprise. Today, becoming "agent-ready" can require specialized engineers, custom integrations, and infrastructure that only large companies can afford. If that remains true, AI commerce will widen the gap between large platforms and the millions of independent retailers that make local commerce unique.

I have a direct view of that asymmetry. By day, I lead engineering for one of the largest retail storefronts in the United States, where I have spent years working on the kinds of systems I am describing here: eligibility rules, inventory truth, fulfillment feasibility, promotion stacking, and the pricing context that determines what a given shopper may actually buy.

At that scale, the reasoning layer exists—but it is distributed across backend services, much of it is enforced late in the journey, it is expensive to build, and it was designed for one company. Rebuilding another bespoke stack for another large retailer is not the interesting problem. Making these capabilities accessible to an independent merchant is.

RetailAgentOS is my independent work. It is informed by my professional experience and general retail-engineering patterns, but it uses no proprietary employer code, data, architecture, or confidential information and does not imply employer sponsorship or endorsement.

RetailAgentOS is my attempt to close that gap through an open-source platform. A retailer should be able to describe its products and selling rules once—inventory, pricing, eligibility, delivery, substitutions, customization, and quote policies—and let different AI agents interact with the business accurately and safely.

I released RetailAgentOS under the Apache 2.0 license. Its specifications are published as versioned RFCs with their open questions left intact, and the specifications ship alongside a runnable reference implementation—so the rules a retailer reads are the rules the engine actually executes.

That mission shaped the retailers I chose for this showcase.

Fresh Corner Market represents the neighborhood grocery store: the kirana store found throughout India and South Asia, the neighborhood shop found across Europe, or the independent corner market serving communities in the United States. These stores operate with changing local inventory, narrow delivery windows, substitutions, and close customer relationships. Their commerce rules may look simple on a webpage, but they are highly contextual. An AI agent must know when inventory cannot be trusted, offer an acceptable substitute, and preserve the shopper's control.

TheCustomHub represents another important small-retailer model: a specialized American business selling customized apparel. It is also the first real retailer working with me to explore how RetailAgentOS can support an operating business. Its transactions cannot always be reduced to "add item to cart." A request may include color, youth-size quantities, artwork, budget, and delivery requirements that a merchant must review before providing a price. The challenge demo uses an authorized controlled fixture—not a live production backend—but it reflects the real quote-first workflow RetailAgentOS is being designed to support.

These two retailers were chosen deliberately. One needs an agent to recover a simple grocery cart when inventory is uncertain. The other needs an agent to preserve a complex custom order without fabricating a price. Together, they demonstrate why agentic commerce needs to support the diversity of real retail—not force every retailer into the operating model of a large marketplace.

WebMCP made this vision tangible. It allows the retailer's own website to expose structured actions directly to an AI agent—no marketplace intermediary and no bespoke integration for every agent. RetailAgentOS determines what is valid; WebMCP exposes only the next action the retailer can safely honor; and the human shopper retains control over consequential decisions.

The long-term vision is universal access: an open foundation that lets any retailer participate in agentic commerce without surrendering its policies, customer relationships, or independence.

What it does

RetailAgentOS is the merchant-controlled reasoning layer. WebMCP is the browser action surface. An agent can invoke only the next commerce capability the retailer can safely honor at that moment—and which tools exist changes as the engine evaluates inventory, price, fulfillment, policy, and shopper approval.

The grocery mission. A shopper asks for a weekend breakfast cart under $30 from Fresh Corner Market, with Farm Eggs and Artisan Sourdough Bread. The eggs return STOCK_STALE, so cart preparation is not merely disabled in the interface—it is not registered as a tool at all. The engine proposes Cage-Free Eggs, explains the $0.50 difference and the equivalent local delivery, and stops. A human clicks Approve. Only then does prepare_validated_cart register, returning a $15.99 review cart. An optional revision to two loaves lands at $24.49, leaving $5.51 of the budget. Checkout is never registered anywhere in this showcase.

The custom-order mission. Twenty-five black robotics-team shirts—six Youth Small, eleven Youth Medium, and eight Youth Large—with a one-color front logo, requested within fifteen days against a $500 ceiling. The plan reaches QUOTE_REQUIRED, which dynamically exposes request_quote. The structured request preserves every constraint the shopper stated and returns fixedPrice: null and deliveryPromise: null. The agent does not get to invent a price the merchant never set. No cart, order, payment, or checkout is created.

That second mission matters most to me. Refusing to fabricate a price is not a limitation to apologize for—it is the feature that allows quote-first merchants to exist in an agentic world at all.

How I built it

The deterministic engine came first and predates this challenge. It runs a staged pipeline—visibility, then eligibility, then price, then fulfillment, then quote—through pure registered evaluators. The same inputs always produce byte-identical output; no model sits in the decision path; time is injected rather than read from the clock. That determinism is the entire basis for letting an agent act on a real store.

The WebMCP layer was built during the challenge window on top of it:

  • packages/webmcp is a framework-independent browser adapter owning one canonical catalog of seven Phase 1 descriptors: get_storefront_capabilities, search_catalog, evaluate_shopping_plan, find_valid_alternatives, apply_plan_repair, prepare_validated_cart, and request_quote. Three planning tools register at load; the others appear and disappear as the engine permits. revise_validated_cart is an optional post-cart extension. No state ever exposes every tool at once.
  • Registration runs through document.modelContext.registerTool(tool, { signal }), owned by an AbortSignal lifecycle so capabilities are revoked on reset, scenario switch, and unmount. Revocability is what makes "safe next action" an enforced guarantee rather than a convention.
  • A controlled gateway validates input, injects time, calls the real engine, and maps its decision record into compact tool results. WebMCP never recalculates a decision—it can only surface one.
  • Guided replay remains available as a clearly labelled fallback and walkthrough in every browser. It invokes the identical descriptors and handlers, with per-invocation telemetry marking native versus replay so the two paths cannot be confused.

Challenges I ran into

A registration race surfaced by cross-agent testing. A native run in Codex's in-app browser completed the post-approval journey, while a separate ChatGPT browser-agent run stopped after the shopper clicked Approve. The problem was not the approval itself: the SDK deferred the phase transition, allowing apply_plan_repair to resolve before prepare_validated_cart had necessarily finished registering. The second agent therefore received a valid repair result but did not continue automatically.

I reproduced the timing window with a controllable fake ModelContext and fixed it by awaiting every next-phase registration before the triggering tool's execute() returns. Generation-scoped cleanup prevents an older registration from later removing a newer tool with the same name. Two agent sessions exposed different behavior around the same timing window—a valuable lesson when building dynamic capabilities on an emerging browser standard.

Telling the truth about what is native. Guided replay looks almost identical to a native run in the interface. It would have been easy, and dishonest, to let a button click read as an agent invocation. Invocation source is now attributed per call, the guided path is always labelled, and a fallback that a human clicks is never described as native WebMCP.

Idempotency across two racing callers. A native agent and a guided fallback could each prepare a cart under different idempotency keys and produce two different carts. Cart preparation now carries a second, trusted server-side layer keyed by the decision itself, with a canonical order-independent line fingerprint, so both converge on exactly one cart.

Keeping the engine pure. Browser state, wall-clock reads, network calls, or duplicated policy logic in React would have weakened the deterministic boundary. Commerce policy is calculated once in the engine; the WebMCP adapter, gateway, and interface consume that authoritative result rather than recreating it.

Accomplishments that I'm proud of

A quote-first merchant is a first-class citizen here, not an edge case. Checkout, payment, and order placement are never registered as tools in this showcase—the mission deliberately ends at a cart the shopper completes themselves.

The platform is released under the Apache 2.0 license with published specifications and a runnable reference implementation, so a retailer can inspect, adopt, and extend it without purchasing a proprietary platform.

The implementation is supported by 610 passing automated tests across 32 test files, including tests that hold the truthfulness, lifecycle, idempotency, and human-approval invariants in place.

What I learned

Constraint is the product. I spent most of this build deciding what an agent may not do, and every one of those refusals—no fabricated price, no cart built on stale inventory, no checkout, and no auto-approved substitution—is what makes the system safe enough for a real merchant to switch on.

I also learned that the human gate is a feature rather than friction. The shopper approving the egg substitution is the moment the demonstration turns from automation into collaboration: the agent does the searching, planning, and revalidating; the person keeps the judgment.

That division is what was genuinely difficult before. An agent scraping a webpage cannot ask permission on behalf of a merchant's actual policy because it never knew the policy in the first place.

What's next for RetailAgentOS WebMCP Agent Storefront

The showcase proves the native browser interaction model. The next stage is turning that working model into something real retailers can adopt without assembling their own agentic-commerce engineering teams.

The roadmap includes:

  • Zero-code catalog and policy onboarding
  • Shopify, WooCommerce, Square, and other commerce connectors
  • Managed retailer storefront configuration
  • Merchant-controlled agent permissions and guardrails
  • Agent-traffic, failed-cart, and customer-intent analytics
  • Authentication, persistence, rate limits, and multi-tenant infrastructure
  • Readiness tooling that shows retailers what AI agents can safely understand and do
  • A generalized remote MCP layer for client applications and agents operating beyond the browser
  • Continued work with small retailers such as TheCustomHub

The goal is for a retailer to connect once, describe its commercial truth once, and make that truth safely usable across agent channels.

A solo merchant should not need to understand WebMCP, MCP, schemas, policy engines, or agent orchestration. They should be able to connect their store, describe how their business operates, choose what agents may do, and remain in control of the customer relationship.

RetailAgentOS is intended to become an open foundation for that future—so agentic commerce does not become a capability reserved for the world’s largest retailers.

Transparency

Fresh Corner Market is a fictional controlled retailer fixture representing the inventory, substitution, and local-delivery realities of a neighborhood grocery or kirana store.

TheCustomHub is the first real retailer working with me to explore how RetailAgentOS can support an operating small business. The challenge showcase uses an authorized controlled demonstration based on its quote-first workflow; it is not connected to TheCustomHub’s live production catalog, quoting, cart, payment, or order systems.

The current showcase prepares a review cart but does not expose checkout, payment, or order placement. Production authentication, persistence, rate limiting, multi-tenant infrastructure, live merchant connectors, and a generalized hosted MCP server remain roadmap work and are not presented as shipped.

RetailAgentOS is my independent open-source work. It is informed by my professional experience and general retail-engineering patterns, but it does not use proprietary employer code, data, architecture, or confidential information, and it does not imply employer sponsorship or endorsement.

Links

Built With

Share this project:

Updates

Submission history