feat(skeleton): add Storefront MCP proxy by itsjustriley · Pull Request #3572 · Shopify/hydrogen

itsjustriley · 2026-03-11T19:20:55Z

WHY are these changes introduced?

Enables AI agents (Claude, ChatGPT, and other MCP clients) to interact with Hydrogen storefronts through the standardized Model Context Protocol. This allows AI assistants to help customers browse products, manage carts, and get store information in natural language.

Related: https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront

WHAT is this pull request doing?

Adds automatic MCP proxy support to Hydrogen's createRequestHandler. When requests are made to /api/mcp, Hydrogen now automatically forwards them to Shopify's centrally-hosted Storefront MCP server.

The implementation:

Detects MCP requests via the /api/mcp path pattern
Forwards requests to ${shopDomain}/api/mcp with proper headers
Preserves authentication (Storefront Access Token), cookies, and buyer IP for geolocalization
Works automatically for all Hydrogen storefronts without requiring route files

This approach mirrors how Hydrogen already proxies Storefront API GraphQL requests at /api/:version/graphql.json (which this PR also cleans up by removing the now-redundant manual route file).

Additional cleanup: Removes the api.$version.[graphql.json].tsx route from the skeleton template since createRequestHandler has automatically proxied these requests since December 2025 via proxyStandardRoutes: true (enabled by default).

HOW to test your changes?

Build and start the skeleton template:

cd templates/skeleton
pnpm install
pnpm build
pnpm preview

Test the tools/list endpoint:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Should return JSON with available MCP tools from Shopify's Storefront MCP server.

Test product search:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 2, "params": {"name": "search_shop_catalog", "arguments": {"query": "snowboard", "context": "customer looking for snowboard"}}}'

Should return product data from the store.

Verify the redundant Storefront API route was removed:
- Confirm templates/skeleton/app/routes/api.$version.[graphql.json].tsx no longer exists
- Test that /api/2024-10/graphql.json still works via the automatic proxy

Implementation Notes

Proxy Architecture

Similar to the existing Storefront API proxy (isStorefrontApiUrl + forwardStorefrontApi), this adds:

isMcpUrl() - Checks if request matches /api/mcp
forwardMcp() - Forwards request to Shopify's hosted MCP endpoint

The proxy forwards essential headers:

Request headers: accept, content-type, cookie, origin, referer, user-agent
Shop identification: Shopify-Storefront-Private-Token (from storefront config)
Geolocalization: x-forwarded-for with buyer IP for market/currency detection

Why Proxy Instead of Local Implementation?

Shopify's centrally-hosted MCP server provides:

Consistent tooling across all storefronts
Automatic updates to MCP capabilities
Reduced bundle size for Hydrogen apps
No need for merchants to maintain MCP implementation code

Checklist

I've read the Contributing Guidelines
I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've added a changeset if this PR contains user-facing or noteworthy changes
I've added tests to cover my changes
I've added or updated the documentation

shopify · 2026-03-11T19:22:34Z

Oxygen deployed a preview of your add-storefront-mcp-route branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 18, 2026 1:13 PM

Learn more about Hydrogen's GitHub integration.

.changeset/quiet-lemons-smile.md

templates/skeleton/app/routes/api.mcp.tsx

packages/hydrogen/src/storefront.ts

packages/hydrogen/src/utils/request.ts

packages/hydrogen/src/storefront.ts

- Add proper TypeScript types for JSON-RPC request handling - Use generated GraphQL types instead of 'as any' type assertions - Fix cart mutations to intelligently route between cartCreate/cartLinesAdd/cartLinesUpdate - Add null safety and input validation throughout

…GraphQL types

- Add null checks for all GraphQL query/mutation responses - Use consistent error messages that state observable facts - Add comment explaining policy search behavior returns all policies - Remove optional chaining where null checks are now explicit

- Add 'mcp' to ROUTE_MAP to include api.mcp.tsx when generating routes - Fixes failing tests that expect api.mcp to be copied with skeleton template

…refront MCP endpoint

kdaviduik

LGTM aside from a few comments. Feel free to merge tomorrow if you address them and get another ✅ since I'll be OOO. Also:

Stale cookbook references (non-blocking): Three files reference the deleted api.$version.[graphql.json].tsx route:

cookbook/llms/express.prompt.md (line 2602)
cookbook/recipes/express/README.md (line 2612)
cookbook/recipes/express/recipe.yaml (line 82)

I think these should be updated in this PR since the PR is the direct cause of the breakage.

kdaviduik · 2026-03-20T00:38:39Z

packages/hydrogen/src/storefront.ts

+      /**
+       * Checks if the request is targeting the Storefront MCP endpoint.
+       */
+      isMcpUrl(request) {


blocking: unit tests for isMcpUrl() and forwardMcp() are still missing.

This was blocking in the previous review and remains unaddressed. Test infrastructure already exists in storefront.test.ts (tests createStorefrontClient with mocked fetchWithServerCache, tests header forwarding) and request.test.ts (tests extractHeaders and getHeader). At minimum the test cases from the prior review should be covered:

isMcpUrl returns true for /api/mcp and false for other paths (e.g., /api/mcp/foo, /api/mcps, /api/2024-10/graphql.json)

isMcpUrl returns false for /api/mcp/ (trailing slash)

isMcpUrl returns true for full URLs with query parameters (e.g., https://store.com/api/mcp?session=abc) - getSafePathname strips query params before matching

forwardMcp forwards the correct headers to {shopDomain}/api/mcp

forwardMcp preserves x-forwarded-for from buyer IP

Integration with createRequestHandler routes MCP requests to the proxy

Note: the existing SFAPI proxy also lacks unit tests - that's pre-existing debt, but new code is the right time to establish the pattern.

kdaviduik · 2026-03-20T00:38:39Z

packages/hydrogen/src/storefront.ts

+          // Add headers for shop identification and geolocalization
+          ...extractHeaders(
+            (key) => defaultHeaders[key],
+            [


non-blocking: basically same comment as here.

I think forwardMcp should forward STOREFRONT_REQUEST_GROUP_ID_HEADER (and ideally SHOPIFY_STOREFRONT_ID_HEADER) for observability.

The existing SFAPI forward method includes both of these from defaultHeaders for tracing/debugging and storefront identification. Without the request group ID header, MCP requests are invisible in Hydrogen's request correlation/debugging story.

Re: content-length - you're right that it's a forbidden request header per the Fetch spec, so omitting it is appropriate.

kdaviduik · 2026-03-20T00:38:39Z

packages/hydrogen/src/storefront.ts

+
+        const mcpUrl = `${getShopifyDomain()}/api/mcp`;
+
+        const mcpResponse = await fetch(mcpUrl, {


non-blocking: I mentioned this in my previous review and it was marked as resolved but my agents brought it up again, and I don't see any "jsonrpc" stuff in the code.

If fetch(mcpUrl, ...) throws (DNS failure, connection refused, TLS error), the error propagates as an unhandled exception. MCP clients speak JSON-RPC and expect structured error responses ({"jsonrpc": "2.0", "error": {...}}). An unhandled exception produces an opaque 500 or HTML error page - the MCP client can't distinguish "the server crashed" from "the proxy is misconfigured" from "the upstream is down", and an AI assistant might silently break with no useful error message for the end user.

The existing SFAPI forward has the same gap (pre-existing), but for new code a try/catch returning a proper JSON-RPC error would be an improvement - and a natural test case to add alongside the other missing tests.

Also worth noting: if request.body has already been consumed by upstream middleware, fetch silently sends an empty body - another scenario where a clear error response would help debugging.

kdaviduik · 2026-03-20T00:38:39Z

packages/hydrogen/src/createRequestHandler.ts

        return response;
      }
+
+      if (storefront?.isMcpUrl(request)) {


non-blocking as long as you follow up: every Hydrogen merchant who upgrades gets this new publicly-accessible /api/mcp proxy endpoint. It's gated behind proxyStandardRoutes (defaults true), which is consistent with the SFAPI proxy - merchants who have accepted proxyStandardRoutes: true have implicitly accepted this class of auto-proxied endpoint, and the risk profile is comparable.

I think the changeset should clarify the gating mechanism. Suggested wording: "This feature is automatically available when proxyStandardRoutes is enabled (the default) - no code changes required."

i'm OOO; dismissing so others can approve and unblock this

itsjustriley force-pushed the add-storefront-mcp-route branch 2 times, most recently from da1d725 to 1f5a330 Compare March 11, 2026 21:08

itsjustriley marked this pull request as ready for review March 11, 2026 21:14

itsjustriley requested a review from a team as a code owner March 11, 2026 21:14

kdaviduik requested changes Mar 11, 2026

View reviewed changes

.changeset/quiet-lemons-smile.md Show resolved Hide resolved

templates/skeleton/app/routes/api.mcp.tsx Outdated Show resolved Hide resolved

itsjustriley changed the title ~~feat(skeleton): add Storefront MCP server endpoint~~ feat(skeleton): add Storefront MCP proxy Mar 12, 2026

itsjustriley requested a review from kdaviduik March 12, 2026 13:19

kdaviduik previously requested changes Mar 16, 2026

View reviewed changes

itsjustriley force-pushed the add-storefront-mcp-route branch from 824ff80 to 35c0000 Compare March 16, 2026 15:08

itsjustriley added 8 commits March 18, 2026 09:11

feat(skeleton): add Storefront MCP server endpoint

ce56a4d

fix(skeleton): remove redundant Storefront API proxy route

7bf29ee

fix(mcp): remove any type from shop policies mapping using generated …

0d9492a

…GraphQL types

fix(cli): include api.mcp route in template generation

71988a8

- Add 'mcp' to ROUTE_MAP to include api.mcp.tsx when generating routes - Fixes failing tests that expect api.mcp to be copied with skeleton template

Add automatic MCP proxy to forward /api/mcp requests to Shopify's Sto…

b5b4f91

…refront MCP endpoint

fix(changeset): correct package names in quiet-lemons-smile changeset

5135637

itsjustriley force-pushed the add-storefront-mcp-route branch from d72a35c to 5135637 Compare March 18, 2026 13:11

itsjustriley requested a review from kdaviduik March 18, 2026 14:51

kdaviduik reviewed Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skeleton): add Storefront MCP proxy#3572

feat(skeleton): add Storefront MCP proxy#3572
itsjustriley wants to merge 8 commits intomainfrom
add-storefront-mcp-route

itsjustriley commented Mar 11, 2026 •

edited

Loading

Uh oh!

shopify bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdaviduik left a comment

Uh oh!

kdaviduik Mar 20, 2026

Uh oh!

kdaviduik Mar 20, 2026

Uh oh!

kdaviduik Mar 20, 2026

Uh oh!

kdaviduik Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		const mcpUrl = `${getShopifyDomain()}/api/mcp`;

		const mcpResponse = await fetch(mcpUrl, {

Conversation

itsjustriley commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

HOW to test your changes?

Implementation Notes

Proxy Architecture

Why Proxy Instead of Local Implementation?

Checklist

Uh oh!

shopify bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdaviduik left a comment

Choose a reason for hiding this comment

Uh oh!

kdaviduik Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

kdaviduik Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

kdaviduik Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

kdaviduik Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

itsjustriley commented Mar 11, 2026 •

edited

Loading

shopify bot commented Mar 11, 2026 •

edited

Loading