Shopify Global Catalog REST to MCP Migration Checker
Check a legacy Global Catalog REST request and get its UCP MCP tool mapping, JSON-RPC starting point, and a manual review checklist.
Announced cutoff: . Shopify’s October 9 announcement says requests to discover.shopifyapps.com/global/… stop being served on that date, including saved catalogs.
For integrations calling that host directly. This retirement does not mean that every Shopify REST API or merchant admin stops working. Verified and updated .
Check your old request
Runs locally in your browser. No requests are sent to Shopify. Do not paste tokens or authorization headers. Inputs are not saved or collected by this tool.
Your migration starting point
Unofficial migration aid. Generated examples require review and testing against Shopify's current documentation. Not an automatic production migration.
- Detected legacy call
- Replacement MCP tool
- New endpoint (POST)
https://catalog.shopify.com/api/ucp/mcp
JSON-RPC example
Structurally complete means required values and local checks passed. It does not establish semantic equivalence, authentication, or production readiness. Missing values are omitted in templates.
Auto-converted
Manual review required · REVIEW_REQUIRED
Every unprocessed parameter is listed with its old value. These values are excluded from the MCP example; preserve their intended behavior manually.
Migration checklist
What the four routes become
The destination is Global Catalog MCP implementing UCP Catalog. GraphQL Admin’s catalog query and a single store’s Storefront Catalog MCP serve different purposes.
| Legacy call | MCP tool | Verified starting point |
|---|---|---|
GET /global/v2/search | search_catalog | Search query; explicitly supplied valid limit and shipping countries. |
GET /global/v2/p/{upid} | get_product | catalog.id = gid://shopify/p/{upid} |
GET /global/v2/p/by-variant/{vid} | get_product | catalog.id = gid://shopify/ProductVariant/{vid} |
POST /global/v2/lookup | lookup_catalog | Preserve the body’s 1–50 ids strings; confirm supported formats. |
Shopify’s official route mappings.
Use this as an audit, then test your integration
- Locate old Global Catalog calls in your code, scheduled jobs, workers, and saved-catalog integrations. Select their legacy method and paste one URL.
- For lookup, expand settings and supply the old JSON body. Search values are edited in the URL; supply a saved catalog ID only when you know the Dev Dashboard value.
- Read every unprocessed field, validate your agent profile and authentication, and test the new request in your own environment. This page never executes generated requests.
Why some parameters stay in review
Only query, legacy limit (1–10), ships_to, and ships_from have automatic search mappings here. Unsupported filters, prices, extra product context, and repeated parameters need review. A missing input is not replaced with a made-up production value.
For example, available_for_sale=0 is not assumed equivalent to filters.available=false. Decimal legacy prices require a currency-aware minor-unit conversion; multiplying every amount by 100 would be unsafe. Unknown parameters remain visible in the review list. Compare omitted defaults too: the legacy search reference defaults ships_to to US, whereas a migration should explicitly confirm the new filter and buyer context.
What still needs end-to-end verification
An agent profile is distinct from a bearer token. Shopify’s announcement says existing Dev Dashboard client-credential bearer tokens can continue to be used; a production agent still needs a valid UCP profile declaring the relevant base capabilities and Shopify’s extension. The checker validates URL syntax only. See profile setup and authentication rules.
Check the new response envelope, field availability, price representation, pagination behavior, and your consumers with real authenticated tests. Consult the Global Catalog extension for enriched fields. A local request draft proves neither a successful Shopify call nor a completed migration.
When the official tools are enough
Shopify already provides comprehensive examples and a UCP CLI through its AI Toolkit. If you are building a new integration, start with Shopify’s Global Catalog documentation. This limited checker is intended for auditing an existing old request and surfacing fields that could otherwise disappear during migration.
Official references
- Retirement announcement and route mappings
- Global Catalog MCP tools and JSON-RPC examples
- Authentication and shared rate limits
- Global Catalog extension and response fields
- Legacy search parameter reference
- Legacy bulk lookup reference
- Define your UCP agent profile
Related: Shopify scriptTagCreate permission errors concern a separate API change.