Ask MCP

Use Ask MCP to answer buyer questions about a store's products, policies, and services. The ask_business tool returns an answer from the store's knowledge base, policies, and product information.

Supported versions

Ask is available in UCP 2026-08-25 and draft. Your agent profile must use one of these versions and declare dev.ucp.common.ask.

Anchor to When to use AskWhen to use Ask

Use Ask when a buyer asks about specific products, a store's return policy, shipping options, warranties, or services. Include relevant buyer context, such as their country or preferred language, with the question.

Ask answers questions. It doesn't change carts, place orders, or start returns. To look up products, prices, and availability, use Storefront Catalog MCP.

Anchor to Available toolsAvailable tools

Ask provides one tool:

ask_business: Answer questions about the store's products, policies, and services.

Replace {storedomain} with the store's actual domain. The /api/ucp/mcp endpoint requires an agent profile. Every JSON-RPC 2.0 request must include the profile URL in params.arguments.meta["ucp-agent"].profile. The returned tools depend on the capabilities your agent advertises.

UCP Ask specification

This tool implements the Universal Commerce Protocol Ask specification and its MCP binding. Refer to the UCP specification for the complete request and response schemas.

Check the store's UCP profile at https://{storedomain}/.well-known/ucp for dev.ucp.common.ask and the MCP endpoint under the dev.ucp.common service.

Use tools/list to check whether the store offers ask_business for your agent profile.

For authentication and request limits, refer to Auth and rate limiting.

POST

https://{storedomain}/api/ucp/mcp

{

"jsonrpc": "2.0",

"method": "tools/list",

"id": 1,

"params": {

"arguments": {

"meta": {

"ucp-agent": {

"profile": "https://shopify.dev/ucp/agent-profiles/examples/draft/ask.json"

}

For testing, use Shopify's example Ask profile. Host your own profile for your integration.

Anchor to ask_business`ask_business`

Ask a question about the store. The response contains the answer in result.structuredContent.answer.plain. The result.content array also contains a text representation of the response.

Anchor to ParametersParameters

Parameter	Type	Required	Description
`meta`	object	Yes	UCP metadata, including `ucp-agent.profile` for capability negotiation.
`ask`	object	Yes	The question, with optional resource IDs and buyer context.
`ask.query`	string	Yes	A natural-language question. Maximum: 10,000 characters.
`ask.ids`	string[]	No	Resource GIDs from this store. Ask uses up to 10 supported IDs.
`ask.context`	object	No	Buyer context. The serialized JSON object must not exceed 8,192 bytes.

Anchor to Resource IDsResource IDs

For questions about specific products, include the relevant IDs in ask.ids so Ask can use the store's product information. Use product or variant IDs from Storefront Catalog MCP. Global Catalog product IDs in the format gid://shopify/p/... aren't supported.

ID type	Example	Information used
`Product`	`gid://shopify/Product/123`	Product details.
`ProductVariant`	`gid://shopify/ProductVariant/456`	The variant's selected options, price, and availability.
`Collection`	`gid://shopify/Collection/789`	The first products in collection order.
`Cart`	`gid://shopify/Cart/{token}?key={key}`	Variants from the cart's line items.

Use the full cart ID returned by create_cart, including its key query parameter. Ask reads the cart without changing it.

Ask uses at most 10 product or variant IDs to answer the question. Explicit product and variant IDs take priority. Cart and collection contents fill the remaining slots in request order.

Anchor to Buyer contextBuyer context

The following string fields are available in ask.context:

Field	Description
`address_country`	The buyer's country, for example, `US`.
`address_region`	The buyer's state or region, for example, `CA`.
`postal_code`	The buyer's postal code.
`language`	The preferred language, for example, `en`.
`currency`	The preferred currency, for example, `USD`.
`intent`	Additional context about what the buyer wants to do.

The context object also accepts additional properties. Send only the context needed to answer the question.

The example response uses an illustrative return policy and product URL. It shows result.structuredContent and omits other UCP metadata and the MCP text representation.

POST

https://{storedomain}/api/ucp/mcp

{

"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"

}

Response excerpt

{

"ucp": {

"version": "draft"

"answer": {

"plain": "You can return eligible items within 30 days of delivery. Items must be unused and in their original packaging."

"links": [

{

"type": "product",

"url": "https://store.example.com/products/example-product?variant=456",

"title": "Example product - Blue / Large",

"id": "gid://shopify/ProductVariant/456"

}

]

}

Anchor to Response linksResponse links

The response can include result.structuredContent.links for product, variant, and collection IDs provided in ask.ids. Each link contains type, url, title, and the resource GID in id. The type is product for products and variants, or collection for collections.

Links are available only for resources with an online store URL. Variant URLs select the referenced variant on the product page. Cart IDs don't get links. Products added through carts or collections don't get links unless you also pass their product or variant IDs.

Anchor to LimitationsLimitations

Each request contains one question. Multi-turn conversations aren't supported. Include the context needed for the current question.
The answer text is plain text in answer.plain. Don't depend on Markdown or conversation identifiers in the response.

Anchor to ErrorsErrors

A valid request can return an answer that explains why Ask can't help. An answer doesn't always mean that the store has information for the question. An empty question also returns an answer that asks for a question.

Handle JSON-RPC errors and inspect UCP messages in result.structuredContent.messages:

The unsupported_id and id_limit_exceeded codes use type: "warning". The not_found code uses type: "info". Each ID message includes a path, such as $.ask.ids[2], that identifies the input ID.

Code	Meaning	Action
`invalid_input`	The question or context exceeds its limit, or the required `ask` object is missing.	Correct the request before sending it again.
`ask_unavailable`	Ask couldn't complete the request. The response includes an unavailable answer and a recoverable message.	Tell the buyer that an answer isn't available.
`unsupported_id`	The ID type or format isn't supported.	Use a supported GID from this store.
`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 for the items needed.
`not_found`	The resource isn't available from this store, or the cart key doesn't match.	Check the resource ID and cart key.

Was this page helpful?