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.

Ask implements the UCP Ask capability (dev.ucp.common.ask). For the protocol specification, refer to Ask and the Ask MCP binding.

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.

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

Send JSON-RPC 2.0 requests to https://{storedomain}/api/ucp/mcp. Every request must include your agent profile in params.arguments.meta["ucp-agent"].profile.

For testing, you can use Shopify's example Ask profile. It declares the draft version and the Ask capability. Host your own profile for your integration.

Use tools/list to confirm that ask_business is available for the store and your agent profile. Availability can differ between stores.

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"

}

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.

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?