Shopify Hydrogen
Mount xmcp in a React Router app that uses Shopify Hydrogen and share its server-side Storefront API client with MCP tools.
For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.Mount an xmcp server inside a React Router app that uses Hydrogen commerce primitives. Your storefront routes and MCP tools share one server-only Storefront client. The runnable example runs on Node against Shopify's tokenless mock.shop catalog.
Mount /mcp
Use the React Router adapter:
Check a bearer token on every request in the route module. isBearer compares it in constant time:
Register it with route("mcp", "routes/mcp.ts") in app/routes.ts. Existing routes are unchanged.
Share the Storefront client
Create the client in a .server.ts module so private tokens never reach the browser bundle. Catalog reads need no buyer context, so the MCP token and caller cookies are never forwarded to Shopify:
Query it from both loaders and tools. Bound tool inputs so clients cannot request unbounded pages:
searchProducts and getProduct in the example return handles, titles, availability, and minimum prices with currency. GraphQL errors become tool errors without upstream details.
Connect a real store
Set PUBLIC_STORE_DOMAIN to your *.myshopify.com domain and PRIVATE_STOREFRONT_API_TOKEN to a token from the Headless or Hydrogen sales channel. Without a token, the client uses tokenless access, which mock.shop supports. Real stores need a token for some fields.
Oxygen deployment, cart mutations, checkout, and Customer Account API access are out of scope.
Tested versions
@shopify/hydrogen 2026.10.3 with React Router 8.4 and Vite 8 on Node.
