Querying Shopify's Global Catalog MCP: A Developer's Guide

Most of the writing about agentic commerce stays at the strategy altitude. This post goes the other way. If you are a developer who wants to query Shopify's Global Catalog directly, the surface is real, documented, and reachable today. Here is how it works and what bit me along the way.

The endpoint

The Global Catalog speaks the Universal Commerce Protocol's catalog capability, bound to an MCP endpoint at https://catalog.shopify.com/api/ucp/mcp. You talk to it with JSON-RPC 2.0 tools/call. There are three tools: search_catalog for natural-language discovery, lookup_catalog to resolve known IDs, and get_product for the full option matrix of one product.

The one requirement that trips people up: every request must carry a meta.ucp-agent.profile URL pointing to an agent profile. You can host your own, but for getting started Shopify publishes a fixture you can reference directly, and search works keyless against it. A minimal search looks like this:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": { "ucp-agent": { "profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json" } },
      "catalog": {
        "query": "organic cold brew concentrate",
        "context": { "address_country": "US", "currency": "USD" },
        "filters": { "available": true },
        "pagination": { "limit": 10 }
      }
    }
  }
}

POST that with Content-Type: application/json and an Accept that allows both JSON and event-stream, and you get back products under result.structuredContent.products.

The shape of a result, and the gotchas

A few things are worth knowing before you build on the response.

Products cluster by Universal Product ID. Results are grouped by a UPID, and each product carries variants whose seller may differ. That is how multiple merchants selling the same item show up as one product with competing offers.

Seller identity is two fields, not one. seller.domain is the *.myshopify.com domain and seller.url is the public storefront. If you are matching results to a known merchant, check both, and do not trust the brand name in the title. A product titled for a famous brand sold by an unrelated myshopify.com domain is third-party resale, not the brand.

Money is in minor units. A price of 1195 is $11.95. Always read the paired currency.

Some fields are inferred. Attributes, top features, and similar metadata are produced by Shopify's models and vary in accuracy with the underlying product data. Treat them as helpful, not authoritative.

You may not cache results or images. The usage guidelines are explicit: results and images reflect live merchant state and must not be stored. If you are deriving analytics, persist your own derived metrics, not the payload.

What you can build

Keyless access is rate-limited and fine for experimentation; for production volume you authenticate with an API key and a trust tier. Even within the keyless tier there is a lot you can do: cross-merchant discovery, comparison tooling, and the kind of measurement we have been writing about, where you query the catalog the way an assistant does and read back where a store actually ranks.

The protocol goes further than search, into carts, checkout, and orders, with capability negotiation through the profile you advertise. Search is the easy front door, and it is enough to learn the shape of the thing.

Where we land

The Global Catalog is not a future promise you have to wait for. It is a documented endpoint you can query this afternoon, and reading its responses honestly teaches you more about agentic commerce than any amount of strategy writing. The gotchas above are most of what stands between a first call and a useful tool.

This is the foundation we build on inside AgentReady, querying the catalog the way assistants do so we can show merchants where they stand. If you are building in this space, the front door is open, and it is worth walking through.