What Does Shopify's Catalog MCP Actually Return? A Field Guide for Commerce Engineers in 2026

Definition

Shopify's Catalog MCP is a Model Context Protocol endpoint that exposes product, variant, inventory, and metafield data from a Shopify store to AI shopping agents in a structured, queryable JSON format.

Shopify's Catalog MCP exposes your product data to AI shopping agents. When an agent queries it, you get back a JSON payload. That payload either contains enough signal for the agent to evaluate and act on a product, or it doesn't. Most engineers haven't looked at the raw output. This guide shows you exactly what's in it, what's missing, and what that means for whether agents buy from you or move on.

What the Catalog MCP Is and Why It Matters Now

The Model Context Protocol (MCP) is the emerging standard for giving AI agents structured access to external systems. Shopify's implementation exposes catalog data, inventory state, and variant structure to any MCP-compatible client — including LLM-based shopping agents built on GPT-4o, Claude, or Gemini.

When a consumer delegates a purchase task to an AI agent, that agent doesn't browse your storefront the way a human does. It queries structured endpoints. It reads fields. It runs logic. If a required field is absent or ambiguous, the agent either makes a bad decision or skips the product entirely.

The Catalog MCP is not a future concern. Agents are querying it now. The question is whether your data passes.

What the Catalog MCP Actually Returns, Field by Field

Here's what a typical Catalog MCP response looks like for a Shopify product — the actual fields, not an idealized version.

Product-Level Fields

The top-level object returns:

• id — the Shopify global ID (GID), e.g., gid://shopify/Product/123456789
• title — plain text product name
• description — raw HTML or plain text depending on query configuration
• productType — often blank or inconsistently populated
• vendor — brand name, useful for agent brand filtering
• tags — freeform array; quality varies wildly
• onlineStoreUrl — the canonical PDP URL
• featuredImage — a single image URL with optional alt text
• seo — title and description fields, often duplicating the main title

Variant-Level Fields

Each product returns a variants edge with nodes containing:

• id — variant GID
• title — typically the option combination, e.g., "Medium / Black"
• sku — present only if you've populated it; frequently blank on smaller catalogs
• price — the current selling price as a string
• compareAtPrice — the "was" price, null if not on sale
• availableForSale — boolean
• inventoryQuantity — integer, but only returned if your storefront API access scope includes inventory read permissions
• selectedOptions — an array of {name, value} pairs for each option axis

What's Notably Absent

This is where most guides stop. Here's what the Catalog MCP does not return by default:

• Shipping estimates or fulfillment lead times — no field for this
• Return policy — not present at the product or variant level
• Warranty or condition information — absent unless you've embedded it in metafields and explicitly exposed them
• Substitution rules — not a native concept in the Shopify data model
• Pricing conditions — volume discounts, subscription pricing, and B2B tiered pricing are not surfaced in the standard catalog response
• Rich variant attributes — material composition, fit notes, care instructions — these live in metafields and won't appear unless you've added them to your storefront API configuration

An agent trying to answer "is this the right product to buy on behalf of this user" needs most of those absent fields to make a confident decision.

The Five Signals Agents Use to Make Buy/Skip Decisions

From working with commerce teams on agentic readiness, five signals consistently determine whether an agent acts on a product or moves on. Think of these as the evaluation criteria running in the agent's decision loop.

1. Offer Completeness

Can the agent fully specify what it's buying? This requires a populated SKU, a clear variant title, a price, and an availableForSale: true signal. If any of these are missing, the agent can't construct a valid add-to-cart action. A blank SKU is the most common failure point. Agents need a stable, unambiguous identifier to reference the specific offer.

2. Variant Clarity

Are the option axes machine-readable? selectedOptions returns name/value pairs, but the values are whatever you typed into Shopify admin. "S", "Small", "SM", and "size-small" all mean the same thing to a human. To an agent matching against a user's stated preference of "size small," only an exact or near-exact string match works reliably. Inconsistent option naming across your catalog creates silent mismatches.

3. Inventory Signal

availableForSale is a boolean and almost always present. inventoryQuantity is more useful but requires the right API scope. Agents use inventory signal to avoid recommending out-of-stock products and, in more sophisticated implementations, to flag low-stock urgency. Without inventoryQuantity, the agent falls back to the boolean — which loses nuance.

4. Price Legibility

The price field returns a string like "89.00". Currency is inferred from the storefront's context, not embedded in the field. For agents operating across multi-currency storefronts, that creates ambiguity. compareAtPrice is useful for agents filtering on sale status, but it's only populated when you've explicitly set a compare-at price. If your sale pricing runs through Shopify Scripts or discount codes rather than compare-at prices, agents won't read it as a sale.

5. Policy Pointer

This is the field that doesn't exist yet in the standard response. Agents making purchase decisions on behalf of users need to know: what happens if this is wrong? Return window, return method, restocking fees, final-sale flags. None of it is in the Catalog MCP response. Agents designed to protect the user's interests will either ask for confirmation, skip the product, or hallucinate a policy based on brand reputation. None of those outcomes help conversion.

Common Data Gaps That Cause Agents to Skip Your Products

Across catalog assessments, these are the patterns that show up most often:

• Blank SKUs on variants. Shopify doesn't require SKUs. Many merchants never fill them in. Agents that need a stable offer identifier to complete a transaction can't proceed without one.
• HTML in description fields. The description field often returns raw HTML — <p> tags, <br> elements, inline styles. LLMs can parse it, but it adds noise and can cause truncation in context windows. Plain text or clean markdown is better.
• Missing or inconsistent metafields. Product-level metafields for material, fit, or care instructions are only returned if you've explicitly added them to your storefront API configuration. Most haven't been. Agents that need attribute data to match user preferences can't see what isn't exposed.
• Variant titles that are option combinations, not descriptions. "Medium / Black / Regular Fit" is readable. "M / BLK / REG" is not reliably parseable across agents. Standardize your option values.
• No policy linkage. There's no standard field for a policy pointer at the product level. The closest approximation is a metafield. Without it, agents have no structured way to surface return or warranty information during evaluation.
• Unpopulated productType. This is the primary categorical signal for agents doing product classification. If it's blank or inconsistently used — "Tops", "top", "Women's Tops" across different products — category-based filtering breaks.

A Concrete Checklist: What to Fix Before Agents Evaluate Your Catalog

Work through these in order. The first four have the highest impact on agent decision quality.

1. Populate SKUs on every variant. No exceptions. A SKU is the offer's stable identifier. If you're generating them programmatically, use a consistent schema: [BRAND]-[PRODUCT-CODE]-[SIZE]-[COLOR].
2. Standardize option values across your catalog. Pick one naming convention per option axis and enforce it. Size: "XS", "S", "M", "L", "XL". Color: full words, title case. Run a catalog audit to find deviations.
3. Add inventoryQuantity to your storefront API scope. Enable the read_inventory scope in your Storefront API configuration. It's a one-line change with meaningful impact on agent decision quality.
4. Clean your description fields. Strip HTML from product descriptions before they reach the API, or configure your storefront to return descriptionHtml only where you need it and plain description for agent-facing endpoints.
5. Expose key metafields in your storefront API configuration. Identify the five to ten metafields carrying the most decision-relevant attribute data — material, fit, care, condition, warranty. Add them to your storefront API configuration so they appear in catalog responses.
6. Create a policy metafield namespace. Add a commerce_policy metafield namespace at the product level with fields for return_window, return_method, final_sale, and warranty_months. Populate them. This gives agents a structured policy pointer even before a standard field exists.
7. Normalize productType values. Define a controlled vocabulary for your product taxonomy and apply it consistently. This is the primary categorical signal for agent filtering.
8. Audit compareAtPrice coverage. If you run sales, confirm that sale pricing is reflected in compareAtPrice rather than only in discount codes. Agents can't see discount codes.

The Policy Layer Is the Hardest Part

Your engineering team can fix SKUs, clean descriptions, and normalize option values in a sprint. The policy layer is harder because it requires coordination across product, legal, and operations to translate policies written for humans into fields a machine can read.

Return policies are a useful example. Your current policy is probably a paragraph of prose on a CMS page. An agent needs structured fields: return_window: 30, return_method: "mail_or_in_store", restocking_fee: false, final_sale: false. Getting there is a design problem, not just a data entry problem. It requires deciding what the canonical policy fields are, how exceptions are handled, and how the data stays in sync when policies change.

This is the work most catalog readiness guides don't address. It's also where the biggest competitive gap exists. Brands that solve the policy layer give agents enough confidence to complete transactions without prompting the user for confirmation. That's a real conversion advantage — and it compounds as agent-assisted shopping grows.

At CTO.LA, we work with commerce teams to design exactly this layer: structuring policies, fulfillment rules, and pricing conditions as machine-readable inputs alongside the catalog and API work.

See exactly what AI shopping agents see when they query your store — blank SKUs, missing metafields, policy gaps — in about two minutes.

Frequently Asked Questions

Related Topics