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
- Inventory every agent, storefront assistant, and middleware service that calls the old policy/FAQ search tool.
- Point its MCP client to the UCP endpoint on the relevant shop domain.
- Include the required
metaobject withucp-agent.profile; the profile must declaredev.ucp.common.ask. - Call MCP
tools/listfor that agent profile and confirm the store exposesask_business. - Pass the buyer question in
ask.queryand relevant country or preferred-language context inask.contextwhen appropriate. - 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.
How to test this
- Connect a development agent to the UCP MCP endpoint and send the required agent profile metadata.
- Call
tools/listand verifyask_businessis available for that profile. - Ask a known shipping-policy question and inspect
result.structuredContent.answer.plain. - Repeat with different buyer country and language contexts where supported.
- Test a question the store cannot answer confidently and ensure the assistant does not invent policy.
- Remove the old endpoint and tool name from production configuration and monitoring before January 15, 2027.

