See all services → Shopify Plus Partner
Action Required Developer

Migrate Storefront MCP Policy Lookups to UCP Ask

Shopify is deprecating the Storefront MCP policies and FAQs tool in favour of ask_business on the UCP MCP endpoint. Support ends January 15, 2027, and the response contract changes.

Executive summary

What changed

The deprecated tool lived on the Storefront MCP server at https://{shop}.myshopify.com/api/mcp. Its replacement, ask_business, is exposed at https://{shop-domain}/api/ucp/mcp and implements the Universal Commerce Protocol ask capability, dev.ucp.common.ask. Ask is available in UCP version 2026-08-25 and draft.

Three things change beyond the URL. Every request must carry a meta object with ucp-agent.profile, and that agent profile has to declare dev.ucp.common.ask. The question goes in ask.query, with optional buyer context such as country or preferred language in ask.context. Most consequentially, the response is different in kind: ask_business returns a written answer at result.structuredContent.answer.plain rather than raw knowledge base facts or full policy text. Code that parsed the old response and assembled its own reply will need rework, not a find and replace.

The old tool keeps working until January 15, 2027, but all documentation now points at Ask MCP.

Why it matters

The shift from returning source material to returning a composed answer moves a piece of your brand voice inside Shopify. For enterprise merchants that is a governance question as much as a technical one: the answer a buyer receives about returns or warranty terms is now generated against your knowledge base and policies, so the quality of that content directly determines the quality of the response. Thin or contradictory policy pages used to produce thin retrieval results that your own layer could paper over. Now they produce a confident answer you did not write.

Scoping also matters. Ask answers questions and nothing more. It does not modify carts, place orders, or start returns, and product, price, and availability lookups still belong to Storefront Catalog MCP. Teams building toward broader agentic commerce should treat these as separate capabilities with separate discovery, which fits the wider pattern we describe in how Shopify Plus enables AI-driven customer experiences.

Role-specific impact

Use-case example

Real-world scenario

A B2B distributor runs a support assistant that fielded about 2,400 policy questions a month through search_shop_policies_and_faqs, stitching retrieved fragments into a reply with its own prompt layer. Migrating to ask_business let the team delete roughly 300 lines of that assembly logic, but their first test pass showed the generated answers were quietly wrong about freight terms for one region, because two shipping pages disagreed. Fixing the source content took longer than the migration. Budget for both, and run a sample of real historical questions against the new tool before you cut over.

Implementation checklist

  1. Inventory every caller of search_shop_policies_and_faqs across storefronts, apps, and internal tools.
  2. Confirm your agent profile uses UCP 2026-08-25 or draft and declares dev.ucp.common.ask.
  3. Repoint calls to https://{shop-domain}/api/ucp/mcp and switch the tool name to ask_business.
  4. Add the meta object with ucp-agent.profile to every request, and move buyer context into ask.context.
  5. Rewrite response parsing to read result.structuredContent.answer.plain.
  6. Call tools/list as a capability check instead of assuming availability per store.
  7. Replay a representative set of past buyer questions, review the answers for factual accuracy, and correct the underlying policy content.
  8. Complete the cutover ahead of January 15, 2027.

FAQ

Q: Can we keep using the old tool until the deadline?

A: Yes, it is maintained until January 15, 2027. Since documentation has already moved and the response contract differs substantially, there is little value in waiting.

Q: Does this replace product search as well?

A: No. Ask covers policies, services, and product questions in answer form. Structured product, price, and availability lookups remain the job of Storefront Catalog MCP.

Resources

Ask MCP documentation

Need guidance? Talk to Makro.