Does the Storefront MCP server (/api/mcp) honor and forward the Shopify-Storefront-Buyer-IP header for bot protection?

Hydrogen and Storefront APIs
1

Hello everyone,

We are currently building app using Shopify’s native Model Context Protocol (MCP) servers. Our architecture connects our backend (the MCP Client) to merchant stores via the Storefront MCP endpoint (https://{shop}.myshopify.com/api/mcp).

Because our agent makes these requests from the server-side, we want to ensure we’re following Shopify’s best practices for rate-limiting and bot protection, similar to what is documented for the direct Storefront GraphQL API.

The Storefront API documentation explicitly states that server-side integrations should include the Shopify-Storefront-Buyer-IP header set to the buyer’s original IP to prevent throttled API requests and properly attribute load.

However, the Storefront MCP Documentation only shows sending an unauthenticated JSON-RPC payload over HTTP POST without mentioning headers.

My question: If we attach the Shopify-Storefront-Buyer-IP (or X-Forwarded-For) HTTP header to our POST request to the /api/mcp endpoint, will the MCP server proxy/forward that IP to the underlying Storefront API layer?

We want to make sure our single backend IP doesn’t get flagged maliciously when managing carts and searching products on behalf of thousands of concurrent end-users.

Thanks,
Ferenc

Shopify-Storefront-Private-Token and Storefront MCP
3

Hi @ferenc! Good question - I looked into this internally and can confirm that the Shopify-Storefront-Buyer-IP header is specific to the Storefront GraphQL API (/api/{version}/graphql.json), not the MCP endpoint. The MCP docs only require Content-Type.

Your single backend IP hitting /api/mcp shouldn’t be a concern here, but if you do suspect it to be the cause of any issues do let us know and we can take a look!

4

Thanks for the quick answer! Two questions:

  1. The docs say not attaching the IP address could result in “unauthenticated flows at checkout as Shopify will not be able to differentiate requests from different buyers.”. Does this limitation apply to all MCP interactions then?
  2. Is it a problem if we attach the header anyway?
7

The warning about “unauthenticated flows at checkout” is specific to the Storefront GraphQL API when using private access tokens. That header lets Shopify differentiate buyers when your server proxies requests to /api/{version}/graphql.json. The MCP docs don’t include this requirement, and Storefront MCP isn’t restricted by the same kind of rate-limiting found in Catalog MCP for example

Attaching the header to your /api/mcp requests shouldn’t cause any problems. I tested cart creation via the MCP endpoint both with and without the Shopify-Storefront-Buyer-IP header and saw no difference in behavior or response.