Skip to content

Shopify Dude Fix

Shopify Storefront MCP Policy Search Is Deprecated: Move to UCP ask_business

Migrate Shopify AI store assistants from search_shop_policies_and_faqs to UCP MCP ask_business before January 15, 2027.

Quick answer: Replace Storefront MCP search_shop_policies_and_faqs with UCP MCP ask_business before January 15, 2027. Change the endpoint from /api/mcp to /api/ucp/mcp, declare the dev.ucp.common.ask capability in the agent profile, and update your parser to read result.structuredContent.answer.plain.
On this page

Why this is not a simple tool rename

Shopify announced the deprecation on November 11, 2026. The old Storefront MCP tool returned policy and FAQ search information. UCP Ask instead answers a buyer’s question using the store’s policies and knowledge base. That means the response is a generated plain-language answer, not necessarily the raw policy facts or full policy text an older integration expected. The old tool is maintained until January 15, 2027.

Migration map

OLD
Endpoint: https://{shop}.myshopify.com/api/mcp
Tool: search_shop_policies_and_faqs

NEW
Endpoint: https://{shop-domain}/api/ucp/mcp
Tool: ask_business
Agent capability: dev.ucp.common.ask
Question: ask.query
Optional buyer context: ask.context
Answer: result.structuredContent.answer.plain

Change discovery, requests, and parsing together

  1. Inventory every agent, storefront assistant, and middleware service that calls the old policy/FAQ search tool.
  2. Point its MCP client to the UCP endpoint on the relevant shop domain.
  3. Include the required meta object with ucp-agent.profile; the profile must declare dev.ucp.common.ask.
  4. Call MCP tools/list for that agent profile and confirm the store exposes ask_business.
  5. Pass the buyer question in ask.query and relevant country or preferred-language context in ask.context when appropriate.
  6. Read the returned answer from result.structuredContent.answer.plain. Stop parsing the old policy-search response shape.

Keep customer-facing answers grounded

Test refund eligibility, shipping regions, return windows, warranty questions, and ambiguous questions. Verify that answers reflect the correct store and buyer context. If your application needs an exact contractual policy passage rather than a conversational answer, do not assume ask_business supplies the underlying policy document; design a separate supported source-of-truth retrieval path for that requirement.

Common misunderstanding: Changing only the tool name will not work. The endpoint, agent capability metadata, request fields, and response shape all change. Also, a generated answer is not interchangeable with the full original policy text.

How to test this

  1. Connect a development agent to the UCP MCP endpoint and send the required agent profile metadata.
  2. Call tools/list and verify ask_business is available for that profile.
  3. Ask a known shipping-policy question and inspect result.structuredContent.answer.plain.
  4. Repeat with different buyer country and language contexts where supported.
  5. Test a question the store cannot answer confidently and ensure the assistant does not invent policy.
  6. Remove the old endpoint and tool name from production configuration and monitoring before January 15, 2027.