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	First-party docs
Reference implementation	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

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

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

Research Shopify MCP servers
Evaluate capabilities
Compare implementation effort
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