Storefront MCP server

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 (claudedesktopconfig.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 searchproducts and getproduct 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):

Shortened. The full README is on GitHub.