---

Why This Exists

AI agents are learning to shop. But today, there is no standard way for an agent to discover a merchant's capabilities, negotiate terms, build a cart, authorize payment, and complete a purchase -- all without a human clicking buttons.

Shopify Agentic MCP Gateway solves this by implementing three emerging protocols in a single, deployable gateway:

Protocol	Role	What It Does
UCP (Universal Commerce Protocol)	Discovery + Capabilities	Agents discover your store at /.well-known/ucp, negotiate capabilities, and interact via a standard shopping service API
AP2 (Agent Payment Protocol)	Authorization + Security	Three-mandate signature chain (Intent, Cart, Payment) ensures agents can only spend what the user authorized
MCP (Model Context Protocol)	Agent Interface	Five tool registrations that Claude, GPT, and other LLM agents call directly via stdio or HTTP transport

---

Features

• 5 MCP Tools -- scout_inventory, manage_cart, negotiate_terms, execute_checkout, track_order
• UCP Profile Discovery -- /.well-known/ucp endpoint with capability negotiation and transport advertisement
• AP2 Mandate Chain -- Cryptographic ES256 signature chain (Intent -> Cart -> Payment) with full verification
• Guardrails -- AI hallucination guard validates prices, inventory, mandate amounts, and checkout state transitions
• Fee Collection -- Automatic platform fee calculation (configurable rate) with ledger tracking
• Checkout State Machine -- Three-state machine (incomplete -> requires_escalation -> ready_for_complete) with auto-detection
• Dual Runtime -- Runs locally as stdio MCP server for Claude Desktop, or deploys to AWS Lambda with API Gateway
• DynamoDB-Ready -- In-memory stores with annotated DynamoDB migration paths for mandates, sessions, and ledger

---

Quick Start

Prerequisites

• Node.js >= 22.0.0
• A Shopify store with Storefront API access
• (Optional) AWS account for Lambda deployment

1. Install

git clone https://github.com/kuro-tomo/shopify-agentic-mcp.git
cd shopify-agentic-mcp
npm install

2. Configure

cp .env.example .env

Edit .env with your Shopify credentials:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_STOREFRONT_TOKEN=your_storefront_token
SHOPIFY_ACCESS_TOKEN=your_access_token
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

3. Build and Run

npm run build
npm start

The MCP server starts in stdio mode, ready for Claude Desktop or any MCP client.

4. Connect to Claude Desktop

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "shopify-agentic": {
      "command": "node",
      "args": ["/absolute/path/to/shopify-agentic-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_STOREFRONT_TOKEN": "your_token"
      }
    }
  }
}

Now ask Claude: "Search for wireless headphones under $50 and add the best one to my cart."

---

Architecture

                          +------------------+
                          |   AI Agent       |
                          | (Claude / GPT)   |
                          +--------+---------+
                                   |
                          MCP (stdio / HTTP)
                                   |
                          +--------v---------+
                          |  MCP Server      |
                          |  5 Tool Handlers |
                          +--------+---------+
                                   |
              +--------------------+--------------------+
              |                    |                     |
     +--------v-------+  +--------v--------+  +---------v--------+
     | UCP Layer       |  | AP2 Layer       |  | Middleware        |
     | - Profile       |  | - Signer        |  | - Guardrail      |
     | - Negotiate     |  | - Verifier      |  | - Fee Collector  |
     | - Checkout SM   |  | - Mandate Store |  | - Rate Limiter   |
     | - Discovery     |  |                 |  | - Auth           |
     +--------+--------+  +-----------------+  +------------------+
              |
     +--------v--------+
     | Shopify APIs     |
     | - Storefront GQL |
     | - Admin REST     |
     +------------------+

---

Tool Reference

Tool	Description	Key Parameters
scout_inventory	Search the Shopify catalog for products	query (string), category?, price_min?, price_max?, limit?
manage_cart	Create, modify, or retrieve a shopping cart	action (create/add/remove/get), cart_id?, variant_id?, quantity?
negotiate_terms	Negotiate capabilities, discounts, and shipping between agent and merchant	cart_id (string), agent_profile_url (string), discount_code?
execute_checkout	Complete a purchase with AP2 mandate chain verification	checkout_id, intent_mandate, cart_mandate, payment_mandate
track_order	Retrieve order status and fulfillment tracking	order_id (string)

All prices are in minor units (cents). A $29.99 product has price: 2999.

---

Environment Variables

Variable	Required	Description
SHOPIFY_STORE_DOMAIN	Yes	Your Shopify store domain (e.g., store.myshopify.com)
SHOPIFY_STOREFRONT_TOKEN	Yes	Storefront API access token
SHOPIFY_ACCESS_TOKEN	Yes	Admin API access token
SHOPIFY_API_KEY	Yes	Shopify app API key
SHOPIFY_API_SECRET	Yes	Shopify app API secret
AP2_SIGNING_PRIVATE_KEY	Yes	ES256 private key in JWK format for mandate signing
AP2_VERIFICATION_PUBLIC_KEY	No	ES256 public key in JWK format (defaults to deriving from private key)
GATEWAY_BASE_URL	No	Public gateway URL (default: http://localhost:3000)
FEE_RATE	No	Platform fee rate as decimal (default: 0.005 = 0.5%)
FEE_WALLET_ADDRESS	No	Wallet address for fee collection
LOG_LEVEL	No	Logging level (default: info)

---

Deployment

AWS Lambda (Serverless)

npm run build
npm run deploy

This deploys via the Serverless Framework with:

• Runtime: Node.js 22.x on ARM64 (Graviton2)
• Routes: /.well-known/ucp (GET), /ucp/v1/* (ANY), /mcp (POST), /a2a (POST)
• DynamoDB: Three tables auto-provisioned (mandates, ledger, sessions) with PAY_PER_REQUEST billing

See docs/deployment.md for the full deployment guide.

---

Documentation

Document	Description
Architecture	System architecture, component responsibilities, data flow
UCP Integration	Profile discovery, capability negotiation, checkout state machine
AP2 Mandates	Mandate types, signature chain, verification process
Deployment Guide	AWS Lambda setup, CloudFront, monitoring
Developer Kit	Pricing, support, what's included

---

Examples

• examples/claude-desktop.json -- Claude Desktop MCP configuration
• examples/autonomous-purchase.ts -- Full autonomous purchase flow
• examples/mandate-flow.ts -- AP2 mandate generation and verification

---

License

MIT License. See LICENSE for details.

---