---
title: Ask MCP
description: >-
  Use UCP Ask to answer buyer questions about a store's policies and services
  with the ask_business tool.
source_url:
  html: 'https://shopify.dev/docs/agents/ask'
  md: 'https://shopify.dev/docs/agents/ask.md'
---

# 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](https://ucp.dev/draft/specification/common/ask/) and the [Ask MCP binding](https://ucp.dev/draft/specification/common/ask/mcp/).

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

***

## When 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](https://shopify.dev/docs/agents/catalog/storefront-catalog).

***

## Available tools

Ask provides one tool, [`ask_business`](#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](https://shopify.dev/docs/agents/profiles) in `params.arguments.meta["ucp-agent"].profile`.

For testing, you can use Shopify's [example Ask profile](https://shopify.dev/ucp/agent-profiles/examples/draft/ask.json). 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](https://shopify.dev/docs/agents/profiles/auth-and-rate-limiting).

POST

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

```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1,
  "params": {
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/draft/ask.json"
        }
      }
    }
  }
}
```

### `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.

#### Parameters

| 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

```json
{
  "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

```json
{
  "ucp": {
    "version": "draft"
  },
  "answer": {
    "plain": "You can return eligible items within 30 days of delivery. Items must be unused and in their original packaging."
  }
}
```

***

## Limitations

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

***

## Errors

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

***