Storefront MCP

storefront-mcp

An MCP server template for e-commerce storefronts. AI agents get your catalog; only you get your back office.

*(Español más abajo / Spanish below.)*

Quickstart (30 seconds)

npx storefront-mcp

That starts an MCP server over stdio serving a demo catalog (the bundled memory adapter) with 8 public tools — 6 read tools plus the two write tools, which start in dry mode: they run every check and then create nothing. Plug it into Claude Desktop or Claude Code by adding this to your MCP config (claude_desktop_config.json, or claude mcp add storefront -- npx storefront-mcp):

{

"mcpServers": { "storefront": { "command": "npx", "args": ["storefront-mcp"] } } }

Want the 5 back-office tools too? On stdio there is no HTTP header, so the gate is the presence of MCP_SECRET in the server process env — whoever launches the process owns the machine it runs on:

{

"mcpServers": { "storefront": { "command": "npx", "args": ["storefront-mcp"], "env": { "MCP_SECRET": "anything-non-empty" } } } }

Prefer curl? npx storefront-mcp --http 8787 serves the same JSON-RPC contract over plain HTTP on localhost, with the real Authorization: Bearer check (same behavior as the Next.js route below), plus the opt-in confirmation page at /api/stock-alert/confirm:

npx storefront-mcp --http 8787 &

curl -s http://127.0.0.1:8787/ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Pick the adapter with CATALOG_ADAPTER (memory by default, woocommerce for the Store API skeleton). To serve your own catalog, write an adapter (see below) — the CLI, the Next.js route and the registry entry (server.json) all reuse the same tool definitions and privilege boundary.

What is this

A Model Context Protocol server, packaged as a Next.js App Router route, that exposes an online store to AI agents (Claude, custom GPTs, agent frameworks — anything that speaks MCP over Streamable HTTP). It defines 13 tools, and announces the subset your adapter can actually answer:

Only search_products and get_product are always present. Everything else is a capability: implement the adapter method and the tool appears, skip it and the tool does not exist on your deployment — see guard rail 18.

The write tools are public on purpose — an agent buying on a human's behalf is the point — so their protection is behavioral, not a token. They start in dry mode. See the guard rails.

It is extracted from a production storefront server, with everything store-specific removed and replaced by a clean adapter interface.

Why

AI agents are becoming a sales channel. When someone asks their assistant "find me a warm gray alcohol marker in stock near me", the stores that win are the ones the agent can actually *query*: structured search, real availability, a quote with a payment link. A public MCP endpoint is how your store shows up in that conversation — on your own domain, with your own data, under your own rules.

The core design: privilege separation

An agent may browse the shop window; it never sees the operation.

Every tool is either *public* or *sensitive*, and the boundary is enforced twice in the protocol layer (src/lib/protocol.ts, shared by the Next.js route and the standalone CLI):

1. `tools/list` — without a valid Authorization: Bearer header, only the public tools are returned. Sensitive tools are not merely locked; they are invisible.
2. `tools/call` — a caller who guesses a sensitive tool's name anyway gets JSON-RPC error `-32001` before any data code runs.

The check is fail-closed: if the MCP_SECRET env var is not set, the sensitive tools are blocked for everyone. There is no "nothing-configured-so-everything-is-open" mode. Token comparison is constant-time.

Transport nuance: over HTTP (the Next.js route and --http mode) the gate is the Bearer header, because remote callers are untrusted. Over stdio (npx storefront-mcp) there is no header — the client and server share a machine — so the gate is whether MCP_SECRET exists in the server process env. Same boundary, enforced at the trust seam each transport actually has.

The same split exists at the data layer: the CatalogAdapter interface only knows public storefront data, and the optional OpsAdapter (orders, revenue, exact stock) is a separate contract you can simply not implement — in which case the sensitive tools are not announced at all, to anyone. Ops implementations must anonymize customer PII: line items carry name/qty/price, never emails, addresses or phone numbers, even behind auth.

The second design: what a write tool must refuse

A read tool that is wrong says something inaccurate. A write tool that is wrong sells stock you do not have, or points a mail cannon at a stranger — at machine speed, in a retry loop, with nobody in the room.

So the interesting part of create_checkout and subscribe_stock_alert is not what they do. It is what they refuse to do, and the refusals that protect a third party are not configurable. You can switch the effect off entirely (dry mode, kill switch); you cannot keep the effect and drop the check.

Each guard rail below is followed by *what breaks without it*. That is the part worth copying — the tools themselves are a few hundred lines you could write in an afternoon.

Checkout

1. Availability is checked against the inventory source, not the catalog. "Published and purchasable" and "there are units" are two different questions, and almost every e-commerce stack answers them in two different systems (CMS vs. ERP/POS). *Without it:* the tool resolves each line against the sellable-catalog index, hands it to the pricing code — which only knows prices — and no inventory query happens anywhere on the path. An agent orders 50 units of something you have 2 of and gets a real order plus a payable link.

2. "I don't know" blocks exactly like "there is none". Availability is tri-state: {units: n, verified: true}, {units: 0, verified: true}, {units: null, verified: false}. *Without it:* the result gets modeled as a number, so every failure degrades to either 0 (silently blocking real sales) or "assume it's fine" (selling air). The three real "I don't know" cases — variant not mapped in the inventory system, no row in the stock snapshot, backend down — are none of them zero. Before charging a human, unknown and unavailable are worth the same.

3. Lines are consolidated before any limit or stock check — by UNIT POOL, not by spelling. *Without the first half:* a per-line cap of 50 units is decorative, because twenty lines of the same SKU at qty 50 is 1,000 units and each one "fits". *Without the second half* — and this is the version that survives a naive dedupe — {slug: "notebook-a4", qty: 50} and {sku: "NB-A4", qty: 50} are two different keys for one product with one pile of units. Each line is checked against the same 60 units, each one passes, and the store sells 100. Only the inventory adapter can resolve that identity, so AvailabilityRow carries a pool field and every aggregate limit is measured per pool. When an adapter does not return one, the response says so instead of pretending the two lines were proven distinct.

4. An invalid quantity is rejected, never repaired. Math.min(Math.max(Math.floor(Number(qty) || 1), 1), 50) reads like input sanitizing. *Without it:* {qty: 0} — which from an agent means "remove this" — becomes one unit billed to a human, and negatives, NaN and fractions become invented sales. In a tool that takes money, sanitizing means rejecting and explaining; rewriting input into something plausible is fabricating intent.

5. Prices are never accepted from the caller, and the quote is reconciled against the request. There is no price field in the input schema at all, and before an order is created the server checks that the catalog priced *the quantity that was asked for* and that unit_price × qty == line_total. *Without the first half:* your discount policy is whatever the caller types. *Without the second half:* the quantity travels from the cart and the money travels from the quote, and nothing compares them — so a pricing source that "helpfully" clamps 40 units to 10 produces an order for 40 units charged as 10, with every other guard rail green. A quote is allowed to reject a line; it is not allowed to answer a different question than the one asked.

6. Units are HELD before the order exists — or live checkout refuses. This is the guard rail that a stateless check cannot be. Points 1–3 all describe the past: they read a number. Ten concurrent calls each read "4 units left", each pass every check, and each create an order — 40 sold against 4, no rule broken. Only an atomic decrement at the inventory source can prevent that, so InventoryAdapter.reserve() runs between the checks and the order, and a deployment whose adapter cannot reserve does not create live orders unless the operator sets CHECKOUT_UNRESERVED=allow and accepts the risk in writing. *Without it:* every claim about "preventing overselling" holds for exactly one request at a time, which is not what the phrase means. If createCheckout then fails, the hold is released.

7. The refusal ships with its evidence. Every line comes back with stock_available and stock_verified, success or failure. *Without it:* the tool that reports exact stock is token-gated (it is back-office data), so the public agent cannot diagnose anything, retries blindly, and tells the human a made-up reason. If your privilege boundary denies the agent the diagnostic tool, the write tool owes it the diagnosis.

8. One bad line blocks the whole cart. *Without it:* the human receives an order for "the items that happened to pass", which is a cart nobody asked for.

9. The number you read to the customer is the number they will pay. Tax, shipping and discounts belong to the adapter, so CheckoutReceipt.total may differ from the line subtotal — and when it does, the response says which is which (amount_to_pay, charges) instead of returning two contradictory figures. *Without it:* a money contract that stops at subtotal silently assumes tax-inclusive pricing and free delivery. An implementer in the EU or the US either adds tax in their backend, so the total no longer matches the subtotal the same response just reported, or does not, and undercharges.

Back-in-stock alerts

10. An outward effect needs a server-side business precondition. The email only goes out if the product is really unavailable — verified zero, or the catalog independently saying out of stock when units cannot be verified. *Without it:* a public tool that emails an address chosen by the caller is a mail cannon aimed at third parties. Loop tools/call with {email: victim@company.com, slug: } and thousands of perfectly legitimate-looking messages leave your domain, burning credits and sender reputation, hitting someone who never contacted the store. (Bonus: it also kills the false "it's back!" alert about a product that never left.)

11. Dedupe on the SEND, not only on the subscription — failing closed. Two different questions: "is this mailbox already subscribed?" and "did we already mail this mailbox about this product and hear nothing