Shopify MCP returns 422? Token-tier read-only calls need the buyer's IP too

Read-only calls need the buyer's IP, but not every MCP request does

The Token tier identifies an agent using a credential issued by Shopify. Every tools/call it sends to a merchant's UCP MCP endpoint must include Shopify-Buyer-IP with the actual IPv4 or IPv6 address of the buyer it represents. Read-only calls such as get_cart and get_order are included.

The rule covers Storefront Catalog, Cart, Checkout and Order tools at the merchant endpoint. Global Catalog requests do not need the header. Neither do discovery requests such as initialize and tools/list, or Signed and Anonymous requests. Identify the endpoint and authentication tier before applying a rule to every request.

This article concerns server-side UCP MCP calls, not Checkout WebMCP in the buyer's current browser tab. The documentation does not announce new countries, plan charges or a universal changeover date for this header requirement. The October 9 documentation clarification does not mean every merchant underwent the same migration that day.

For a 422 response, inspect the actual HTTP request rather than only tool parameters

Step 1: confirm that the failed request is a Token-tier merchant tools/call, then inspect whether the outgoing HTTP headers actually contain Shopify-Buyer-IP. Buyer information in a tool parameter or higher-level object does not establish that this header was sent.

Step 2: check whether the value is a valid IPv4 or IPv6 address for the buyer. Shopify documents HTTP 422 for a missing or invalid IP, with AuthenticationFailed and Missing required buyer IP header in its example. Do not initially classify that rejection as rate limiting.

Step 3: after correcting the relevant request layer, continue distinguishing the returned error from the permissions required. Adding the header addresses one condition; it does not guarantee that cart, checkout or order calls will succeed. Avoid retaining access credentials or complete sensitive buyer information in troubleshooting records.

Without a buyer IP, the server's outbound address cannot replace it

The documentation explicitly says there is no placeholder value and Shopify does not fall back to the address the agent connects from. The requirement is the IP address of the buyer the agent represents, not an arbitrary address chosen to make the field look valid. Changing servers or network exits cannot supply missing buyer context.

Consider a hypothetical background scheduled task with no current buyer that intends to call a merchant tool using the Token tier. Shopify explicitly says that call fails. This example explains the boundary; no real request was executed. Reassess the task design rather than inventing a buyer IP for scheduled work.

The header, purchase permission and order permission are separate requirements

To call complete_checkout in the Token tier, the credential must also have permission to complete purchases. The get_order read requires the read_global_api_orders scope, and order access is restricted to orders placed through the agent. Having a buyer IP does not authorize reading every order in a shop.

The Signed tier identifies an agent through HTTP Message Signatures under the UCP specification; the Anonymous tier supplies neither credentials nor signatures. These tiers can use the corresponding catalog, cart and checkout build/edit tools, but cannot call complete_checkout or access Order tools. Not requiring buyer-IP does not mean broader permissions.

For 429, follow Retry-After; five requests per second is not a sitewide allowance

When traffic exceeds the allowance for its identification tier, Shopify returns HTTP 429 with Retry-After. Merchant MCP allowances vary by tier and tool and can change. Wait as instructed by the response, then use exponential backoff and jitter rather than hard-coding one request budget for every tool.

Authenticated Global Catalog traffic defaults to five requests per second per API client, shared by search_catalog, get_product and lookup_catalog. Storefront Catalog is rate limited separately for each merchant. Unauthenticated traffic is limited by IP and shares an allowance with other unauthenticated traffic, without guaranteed throughput. Shopify advises against using it for production traffic.

When retrying an operation that accepts an idempotency key, such as complete_checkout, reuse the original request's key so a retry does not become another action. Checkout MCP is more strictly limited than Cart MCP at every tier. Use Cart to refine line items and estimates, then move buyers who are ready to purchase into Checkout.

The October 9 documentation update does not establish that every error is fixed

Shopify community staff member Gil-Shopify replied on October 9, 2026 at 17:04:09 UTC that the documentation now covers the buyer-IP requirement, linking to Auth and rate limiting. The value is clearer request and authentication boundaries, not a promise that every historical error has disappeared.

Earlier in the same thread, one user reported success after adding the header to a POST request, while another still encountered a create_cart error and asked whether a password-protected shop could be involved. Those are individual results and questions, not a platform-wide repair or an established cause. Use the current documentation to identify the request first, then investigate any remaining error.