Shopify merchants and developers rely on AI‑powered tools to answer buyer questions quickly. Starting now, the long‑standing Storefront MCP tool search_shop_policies_and_faqs is being deprecated in favor of the newer Unified Commerce Platform (UCP) Ask tool. This shift brings a more consistent ask capability across Shopify’s ecosystem, but it also means you need to update your integrations before the hard deadline of January 15, 2027. In this post we break down the change, identify who it impacts, and give you a step‑by‑step migration guide with code examples so you can keep your storefronts answering policy questions without interruption.
What’s Changing?
The Storefront MCP endpoint https://{shop}.myshopify.com/api/mcp currently hosts the tool search_shop_policies_and_faqs. Shopify is retiring that tool and introducing a new endpoint https://{shop-domain}/api/ucp/mcp that exposes the ask_business tool. The new tool implements the universal UCP ask capability (dev.ucp.common.ask) and returns answers in a structured format rather than raw policy snippets.
Who Is Affected?
search_shop_policies_and_faqs must update their request payloads, endpoint URLs, and response handling.The deprecated tool will still work until January 15, 2027, but all documentation and new store setups will reference the UCP Ask tool, so early migration is advisable.
Key Differences Between the Old and New Tools
| Feature | Storefront MCP (search_shop_policies_and_faqs) | UCP Ask (ask_business) |
|---|---|---|
| Endpoint | https://{shop}.myshopify.com/api/mcp | https://{shop-domain}/api/ucp/mcp |
| Tool name | search_shop_policies_and_faqs | ask_business |
| Required agent profile | Not required | Must declare dev.ucp.common.ask in ucp-agent.profile |
| Request payload | query (plain text) | ask.query with optional ask.context |
| Response format | Raw knowledge‑base facts or full policy text | Structured answer at result.structuredContent.answer.plain |
| Deprecation deadline | N/A | January 15, 2027 |
Understanding these differences helps you rewrite the request logic and adjust any parsing code that expects the old response shape.
Step‑by‑Step Migration Guide
Below is a practical checklist and code snippets (Node.js/Fetch) you can drop into your existing app. Adjust language as needed.
1. Update the endpoint
Replace the old MCP URL with the UCP endpoint.
js
// Old endpoint
const url = https://${shop}.myshopify.com/api/mcp;
// New endpoint
const url = https://${shopDomain}/api/ucp/mcp;
2. Add the required meta object
Every request must include a meta block that declares the agent profile and the dev.ucp.common.ask capability.
{
"meta": {
"ucp-agent": {
"profile": {
"capabilities": ["dev.ucp.common.ask"]
}
}
},
"ask": {
"query": "What is your return policy for US customers?",
"context": {
"buyerCountry": "US",
"language": "en"
}
}
}
3. Send the question using `ask.query`
The payload format changed from a flat query field to a nested ask.query. Optional buyer context (country, language, cart details) goes under ask.context.
js
const body = {
meta: {
"ucp-agent": {
profile: { capabilities: ["dev.ucp.common.ask"] }
}
},
ask: {
query: userQuestion,
context: {
buyerCountry: buyer.country,
language: buyer.locale
}
}
};
4. Parse the new response
ask_business returns a structured object. The answer text lives at result.structuredContent.answer.plain.
js
const response = await fetch(url, {method: "POST", headers, body: JSON.stringify(body)});
const data = await response.json();
const answer = data.result?.structuredContent?.answer?.plain;
console.log("Buyer answer:", answer);
5. Verify the tool is available for your agent
Use the tools/list endpoint to confirm the store offers ask_business for the declared profile.
js
const listUrl = https://${shopDomain}/api/ucp/mcp/tools/list;
// Include same meta object in the request
6. Test in a staging store
Before deploying to production, call the new endpoint with a variety of questions and contexts. Compare the answer quality to the old tool and adjust any UI formatting as needed.
7. Deploy and monitor
Once the migration is live, keep an eye on error logs for 404 or 422 responses – they often indicate a missing dev.ucp.common.ask capability or an incorrectly formatted payload.
What If You Can’t Migrate Immediately?
Shopify will keep the old search_shop_policies_and_faqs tool operational until the January 2027 cutoff, giving you a buffer of more than two years. However, consider these best practices:
Resources & Next Steps
ask_business.Conclusion
Deprecating the Storefront MCP policies tool is a clear signal that Shopify is consolidating AI‑driven merchant‑buyer interactions under the UCP Ask framework. By updating your endpoint, adding the required agent profile, and adjusting request/response handling, you’ll ensure your storefront continues to provide instant, policy‑compliant answers—now and into the future. Start the migration today, test thoroughly, and keep your clients informed. Need help with the transition? Reach out to our Shopify development team or schedule a consultation; we’re ready to make the move seamless for you.
