Skip to content
CommerceGeek home

Storefront MCP search_shop_policies_and_faqs deprecated: migrate to UCP ask_business by 15 January 2027

Shopify has deprecated the Storefront MCP search_shop_policies_and_faqs tool; migrate to UCP MCP's ask_business tool by 15 January 2027.

A question card goes into a shop counter and a written answer note comes back, beside a policy scroll.
Published
19 Nov 2026
Affects
Storefront MCP, UCP MCP

What changed

Shopify announced on 11 November 2026 that the search_shop_policies_and_faqs tool on the Storefront MCP server (https://{shop}.myshopify.com/api/mcp) is deprecated. Its replacement is the ask_business tool on UCP MCP, available at https://{shop-domain}/api/ucp/mcp.

UCP MCP implements the UCP ask capability, dev.ucp.common.ask. According to the changelog, ask_business answers a buyer's question about the store's policies and services, using the store's knowledge base and policies. The Ask MCP documentation also lists products among the topics it covers.

Shopify says the deprecated tool will be maintained until 15 January 2027, but all documentation will refer to Ask MCP only.

Who is affected

Anyone whose code calls search_shop_policies_and_faqs on the Storefront MCP server (https://{shop}.myshopify.com/api/mcp) is affected. The changelog flags this as action required.

The replacement has its own version requirement. Ask is available in UCP 2026-08-25 and draft. Your agent profile must use one of those two versions and declare dev.ucp.common.ask.

The sources do not state an Admin API or Storefront API version for this change, and the Shopify metadata lists no affected APIs. This is not tied to an API version upgrade, so the dates in the versioning page do not apply here.

What to do

Migrate each call to search_shop_policies_and_faqs so that it uses ask_business on the UCP MCP server. The steps below follow the changelog and the Ask MCP documentation.

  • Change the endpoint to https://{shop-domain}/api/ucp/mcp.

  • Call the ask_business tool instead of search_shop_policies_and_faqs.

  • Include a meta object carrying ucp-agent.profile in every request. The documentation places it in params.arguments.meta["ucp-agent"].profile. The profile must declare dev.ucp.common.ask. The /api/ucp/mcp endpoint requires an agent profile.

  • Send the buyer's question in ask.query. Send optional buyer context, such as country or preferred language, in ask.context.

  • Call tools/list to check whether the store offers ask_business for your agent profile. The tools returned depend on the capabilities your agent advertises.

The documentation also says you can check the store's UCP profile at https://{storedomain}/.well-known/ucp for dev.ucp.common.ask and the MCP endpoint. For testing, Shopify provides an example Ask profile at https://shopify.dev/ucp/agent-profiles/examples/draft/ask.json. Host your own profile for your integration.

For authentication and request limits, see Shopify's Auth and rate limiting page for agent profiles (https://shopify.dev/docs/agents/profiles/auth-and-rate-limiting). The response format change is covered in the next section.

Changes to the response and request limits

ask_business returns a written answer, not raw knowledge base facts or full policy text. The answer is in result.structuredContent.answer.plain. The result.content array also holds a text representation of the response. Any code that parses the old search_shop_policies_and_faqs response needs to change. The sources do not describe the old response format, so this article cannot say exactly what to replace.

Request limits

  • ask.query is a natural-language question of up to 10,000 characters.

  • ask.context must not exceed 8,192 bytes when serialised as JSON. It accepts additional properties, and the documentation advises sending only the context needed to answer the question.

  • Each request holds one question. Multi-turn conversations are not supported, so include the context needed for the current question every time.

  • The answer is plain text in answer.plain. Do not depend on Markdown or conversation identifiers in the response.

Errors to handle

Handle JSON-RPC errors and inspect the UCP messages in result.structuredContent.messages. A valid request can also return an answer that explains why Ask cannot help, so an answer does not always mean the store has information on the question. An empty question returns an answer asking for a question.

  • invalid_input: the question or context exceeds its limit, or the required ask object is missing. Correct the request before resending.

  • ask_unavailable: Ask could not complete the request. The response includes an unavailable answer and a recoverable message. Tell the buyer an answer is not available.

  • unsupported_id: the ID type or format is not supported. Use a supported GID from this store. This code uses type: "warning".

  • id_limit_exceeded: an ID is past the 10-ID limit, or not all cart items fit the product limit. Send fewer IDs, or pass explicit product or variant IDs. This code also uses type: "warning".

  • not_found: the resource is not available from this store, or the cart key does not match. Check the resource ID and cart key. This code uses type: "info".

Each ID message includes a path, such as $.ask.ids[2], that identifies the input ID concerned.

Before and after example

The sources do not show the request or response format of the old search_shop_policies_and_faqs tool, so there is no verified "before" request to reproduce here. Compare your existing calls against the new request below instead.

The Ask MCP documentation gives this tools/call request for ask_business. It is sent by POST to https://{storedomain}/api/ucp/mcp. The profile URL is Shopify's example Ask profile, intended for testing. Host your own profile for your integration.

{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"ask_business","arguments":{"meta":{"ucp-agent":{"profile":"https://shopify.dev/ucp/agent-profiles/examples/draft/ask.json"}},"ask":{"query":"What is the return policy for this product?","ids":["gid://shopify/ProductVariant/456"],"context":{"address_country":"US","language":"en"}}}}}
ask_business request from the Ask MCP documentationUnverified example.

The documentation's response excerpt carries the answer in answer.plain, which you read from result.structuredContent:

{"answer":{"plain":"You can return eligible items within 30 days of delivery. Items must be unused and in their original packaging."}}
Trimmed from the documented response excerpt, which also includes `ucp` and `links`Unverified example.

Deadline

The changelog gives 15 January 2027 as the date to migrate by. The deprecated search_shop_policies_and_faqs tool will be maintained until then.

The sources do not say what happens to the tool after 15 January 2027. They do not say whether it will be removed, stop returning results or be switched off, so treat the outcome as unknown. Shopify has also said that all documentation will refer to Ask MCP, so the old tool will not be documented in future.

The announcement date, 11 November 2026, is when the change was published. It is not a deadline.

Get the weekly digest

One email every Monday: what changed in Shopify, the deadlines coming up and what’s been announced, plus the week’s new guides. Free, and you can unsubscribe in one click.

Sources

  1. Storefront MCP policies and FAQs tool is being deprecated in favor of UCP MCP Ask tool · Shopify · accessed 11 Nov 2026
  2. Ask MCP · Shopify developer documentation · accessed 11 Nov 2026

AI-assisted, reviewed by Scott. Every claim is checked against the sources above.