Ask MCP

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

Draft capability

Ask is available in UCP draft. Your agent profile must use draft and declare dev.ucp.common.ask. Dated UCP releases don't include this capability.

Anchor to When to use AskWhen to use Ask

Use Ask when a buyer asks about 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 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 draft profile at https://{storedomain}/.well-known/ucp/draft 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 [object Object]`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 and optional buyer context.
`ask.query`	string	Yes	A natural-language question. Maximum: 10,000 characters.
`ask.context`	object	No	Buyer context. The serialized JSON object must not exceed 8,192 bytes.

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. 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 your return policy?",

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

}

Anchor to LimitationsLimitations

Each request contains one question. Multi-turn conversations aren't supported. Include the context needed for the current question.
The current response contains plain text in answer.plain. Don't depend on Markdown, source links, 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:

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.

Was this page helpful?