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:

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

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

Environment Variables

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

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.