---
title: Shopify Integration Research
---
# Shopify Integration Research

## ✅ Final Decision: Use Shopify's Official Storefront MCP

**Decision**: Use `@shopify/dev-mcp` as the primary Shopify integration layer.

**Why**: Shopify released an official first-party MCP server with Storefront-scoped tools (cart, checkout, product search, orders) built in. Community MCP servers are all Admin-scoped and unsafe for shoppers. The official one is customer-safe and complete.

## What Exists

| Resource | URL | Description |
|----------|-----|-------------|
| **Official Storefront MCP docs** | [shopify.dev/docs/apps/build/storefront-mcp](https://shopify.dev/docs/apps/build/storefront-mcp) | First-party docs |
| **Reference implementation** | [github.com/Shopify/shop-chat-agent](https://github.com/Shopify/shop-chat-agent) | Complete chat agent template (136★) |
| **MCP Server package** | `@shopify/dev-mcp` (npm) | The actual MCP server |

## Available MCP Tools

| Tool | Purpose | Example Query |
|------|---------|---------------|
| `search_shop_catalog` | Natural-language product search | "find me red shoes under $50" |
| `update_cart` | Add/remove/update cart items | "add the Nike Air Max to my cart" |
| `get_cart` | View current cart | "what's in my cart?" |
| `search_shop_policies_and_faqs` | Store policies & FAQ | "what's your return policy?" |
| `get_most_recent_order_status` | Recent order tracking | "show me my recent orders" |
| `get_order_status` | Specific order details | "details about order #1234" |

## Architecture with Official MCP

```mermaid
graph TB
    subgraph "Rivet Actor"
        PI[Pi Agent Core]
        MCP_CLIENT[MCP Client Extension]
    end

    subgraph "Shopify"
        MCP_SERVER["@shopify/dev-mcp<br/>(Official)"]
        SF[Storefront API]
    end

    PI --> MCP_CLIENT
    MCP_CLIENT -->|MCP protocol| MCP_SERVER
    MCP_SERVER --> SF

    style MCP_SERVER fill:#c8e6c9,stroke:#388e3c,stroke-width:3px
    style MCP_CLIENT fill:#bbdefb,stroke:#1976d2
```

## Reference Implementation

The `Shopify/shop-chat-agent` repo shows:
- Backend: React Router (Node.js) — we use Python + Rivet instead
- LLM: Claude — we use Claude via Pi Agent Core
- MCP: `@shopify/dev-mcp` — **we use the same**
- UI: Shopify theme extension chat widget — we use WhatsApp instead

**What we adapt:**
- Reference uses web chat → we use WhatsApp Cloud API
- Reference uses Claude directly → we use Pi Agent Core (multi-LLM)
- Reference uses in-process state → we use Rivet durable actors
- Reference uses single agent → we use per-user actors

## Community MCP Servers (Obsolete for Our Use Case)

| Repo | Stars | Issue |
|------|-------|-------|
| `@akson/mcp-shopify` | 17 | Admin-scoped (unsafe) |
| `best-shopify-mcp` | 2 | Admin-scoped (unsafe) |
| BridgeAPI | 4 | Interesting pattern but Admin-scoped |
| Botify (shop-assist-mcp) | 1 | Proof-of-concept, Admin-scoped |

These are **not used** — the official MCP server supersedes them.

## Decision Matrix

```mermaid
quadrantChart
    title Why Official MCP Wins
    x-axis "More Custom Work" --> "Less Custom Work"
    y-axis "Less Capable" --> "More Capable"

    "Custom Tool Layer (old plan)": [0.7, 0.7]
    "Official @shopify/dev-mcp": [0.2, 0.9]
    "Community MCP (Admin)": [0.4, 0.4]
```

## Next Steps

- [x] Research Shopify MCP servers
- [x] Evaluate capabilities
- [x] Compare implementation effort
- [x] Select official `@shopify/dev-mcp`
- [ ] Clone `Shopify/shop-chat-agent` reference
- [ ] Test `@shopify/dev-mcp` tools directly
- [ ] Build MCP Client extension inside Rivet actor
- [ ] Integrate with Pi Agent

## See Also

- [Building Pi Extensions](/building-pi-extensions) — MCP Client extension implementation
- [Integration Guide](/integration-guide) — End-to-end wiring
- [Rivet Actor Model](/rivet-actor-model) — Actor that contains the MCP client