---
title: Storefront MCP server
description: >-
  Learn how to use the Storefront MCP server tools to help shoppers browse
  products, manage carts, and checkout from a specific Shopify store.
source_url:
  html: 'https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront'
  md: 'https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront.md'
---

# Storefront MCP server

Connect your AI agent to a specific Shopify store's catalog, shopping cart, and policies. The Storefront MCP server helps customers browse and buy with their selected merchant.

**UCP catalog capability:**

Storefront MCP implements the [UCP Catalog capability](https://ucp.dev/latest/specification/catalog/) and its [MCP binding](https://ucp.dev/latest/specification/catalog/mcp/). The `search_catalog`, `lookup_catalog`, and `get_product` tools conform to the UCP specification. Refer to the [UCP catalog spec](https://ucp.dev/latest/specification/catalog/) for the authoritative schema reference.

***

## How it works

The Storefront MCP server lets your AI agent handle shopping tasks for the selected store:

1. A shopper asks about products while browsing a store.
2. Your agent searches the store's catalog and manages carts.
3. The shopper adds items and completes checkout.

***

## Connect to the server

Each Shopify store has its own MCP server endpoint that exposes storefront features. This endpoint handles all server calls for product search, cart operations, and policy questions:

```text
https://{shop}.myshopify.com/api/mcp
```

This endpoint is unique to each store and gives access to all storefront commerce capabilities. Your app needs to configure this endpoint based on which store the customer is shopping with.

**Caution:**

By using the Shopify MCP servers, you agree to the [Shopify API License and Terms of Use](https://www.shopify.com/legal/api-terms).

***

## Create an API request to the Storefront MCP server

Storefront MCP servers don't require authentication:

1. Replace `{shop}.myshopify.com` with the store's actual domain.
2. Send requests to the store's MCP endpoint.
3. Include the Content-Type header.

Here's how to set up a request:

```js
// Basic setup for Storefront MCP server requests
const storeDomain = 'your-store.myshopify.com';
// Standard Storefront MCP endpoint (cart, policies)
const mcpEndpoint = `https://${storeDomain}/api/mcp`;


// UCP catalog endpoint (search_catalog, lookup_catalog, get_product)
const ucpMcpEndpoint = `https://${storeDomain}/api/ucp/mcp`;


// UCP catalog tools require an agent profile in every request
const agentProfile = 'https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json';


// Example: search for products using UCP catalog tools
fetch(ucpMcpEndpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    id: 1,
    params: {
      name: 'search_catalog',
      arguments: {
        meta: {
          'ucp-agent': { profile: agentProfile }
        },
        catalog: {
          query: 'coffee'
        }
      }
    }
  })
});
```

**Note:**

Note: Some stores may restrict access. Always test with your specific store.

***

## Tool endpoints

### UCP catalog tools

The UCP catalog tools (`search_catalog`, `lookup_catalog`, and `get_product`) are available on a separate endpoint from the standard Storefront MCP tools:

```text
https://{shop}.myshopify.com/api/ucp/mcp
```

These tools implement the [Universal Commerce Protocol (UCP) catalog capability](https://ucp.dev/specification/catalog/) and use a `catalog` wrapper object in their request arguments. Refer to the [UCP catalog specification](https://ucp.dev/specification/catalog/) for the full reference.

### Standard tools

The standard Storefront MCP tools (`get_cart`, `update_cart`, and `search_shop_policies_and_faqs`) are available on a separate endpoint from the UCP-conforming tools:

```text
https://{shop}.myshopify.com/api/mcp
```

***

## Available tools

### search\_​catalog

Searches the store's product catalog to find items that match your customer's needs.

**Key parameters** (inside `catalog` object):

* `query`: Free-text search query
* `context`: Buyer signals for relevance and localization (country, language, currency, intent)
* `filters`: Filter by categories or price range (in minor currency units)
* `pagination`: Cursor-based pagination (cursor, limit)

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "query": "organic coffee beans",
        "context": {
          "address_country": "US",
          "intent": "Customer prefers fair trade products"
        }
      }
    }
  }
}
```

### lookup\_​catalog

Retrieves products or variants by identifier. Use this when you already have product or variant IDs from search results, saved lists, or deep links.

**Key parameters** (inside `catalog` object):

* `ids`: Array of product or variant identifiers (required, up to 10)
* `context`: Buyer signals for localization
* `filters`: Post-resolution filters (categories, price)

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "lookup_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "ids": ["gid://shopify/Product/123", "gid://shopify/ProductVariant/456"],
        "context": {
          "address_country": "US"
        }
      }
    }
  }
}
```

### get\_​product

Retrieves full details for a single product, with optional interactive variant selection. Use this when a customer has selected a product and needs detailed information for a purchase decision.

**Key parameters** (inside `catalog` object):

* `id`: Product or variant identifier (required)
* `selected`: Option selections for variant narrowing (e.g., `[{"name": "Color", "label": "Blue"}]`)
* `preferences`: Option names in relaxation priority order
* `context`: Buyer signals for localization
* `filters`: Post-resolution filters (categories, price)

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "id": "gid://shopify/Product/123",
        "selected": [
          {"name": "Color", "label": "Blue"}
        ],
        "context": {
          "address_country": "US"
        }
      }
    }
  }
}
```

**Note:**

These catalog tools conform to the [UCP catalog specification](https://ucp.dev/specification/catalog/). Refer to the UCP spec for the complete request/response schema, including product, variant, and pagination shapes.

### search\_​shop\_​policies\_​and\_​faqs

Answers questions about the store's policies, products, and services to build customer trust.

**Key parameters**:

* `query`: The question about policies or FAQs (required)
* `context`: Additional context like current product (optional)

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_shop_policies_and_faqs",
    "arguments": {
      "query": "What is your return policy for sale items?",
      "context": "Customer is looking at discounted winter jackets"
    }
  }
}
```

**Note:**

Tip: Use only the provided answer to form your response. Don't include external information that might be inaccurate. For better store policy management, consider using the [Knowledge Base app](https://apps.shopify.com/shopify-knowledge-base) to configure store policies.

### get\_​cart

Retrieves the current contents of a cart, including item details and checkout URL.

**Key parameters**:

* `cart_id`: ID of an existing cart

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_cart",
    "arguments": {
      "cart_id": "gid://shopify/Cart/abc123def456"
    }
  }
}
```

### update\_​cart

Updates quantities of items in an existing cart or adds new items. Creates a new cart if no cart ID is provided. Set quantity to 0 to remove an item.

**Key parameters**:

* `cart_id`: ID of the cart to update. Creates a new cart if not provided.
* `lines`: Array of items to update or add (required, each with`quantity` and optional `line_item_id` for existing items)

**Example use**:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "update_cart",
    "arguments": {
      "cart_id": "gid://shopify/Cart/abc123def456",
      "add_items": [
        {
          "line_item_id": "gid://shopify/CartLine/line2",
          "merchandise_id": "gid://shopify/ProductVariant/789012",
          "quantity": 2
        }
      ]
    }
  }
}
```

***