Shopify Agentic MCP Gateway
Enables autonomous AI agents to browse product catalogs, manage shopping carts, negotiate commerce terms, execute secure checkouts using AP2 mandate chains, and track order fulfillment on Shopify stores.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Shopify Agentic MCP Gateway Find wireless headphones under $50 and add the best one to my cart."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shopify Agentic MCP Gateway
A tri-protocol commerce gateway for autonomous AI agents on Shopify.
Let AI agents browse, negotiate, cart, pay, and track orders -- fully autonomously.
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 |
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 |
Related MCP server: shopify-store-mcp
Features
5 MCP Tools --
scout_inventory,manage_cart,negotiate_terms,execute_checkout,track_orderUCP Profile Discovery --
/.well-known/ucpendpoint with capability negotiation and transport advertisementAP2 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-detectionDual 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 install2. Configure
cp .env.example .envEdit .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_secret3. Build and Run
npm run build
npm startThe 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 |
| Search the Shopify catalog for products |
|
| Create, modify, or retrieve a shopping cart |
|
| Negotiate capabilities, discounts, and shipping between agent and merchant |
|
| Complete a purchase with AP2 mandate chain verification |
|
| Retrieve order status and fulfillment tracking |
|
All prices are in minor units (cents). A $29.99 product has price: 2999.
Environment Variables
Variable | Required | Description |
| Yes | Your Shopify store domain (e.g., |
| Yes | Storefront API access token |
| Yes | Admin API access token |
| Yes | Shopify app API key |
| Yes | Shopify app API secret |
| Yes | ES256 private key in JWK format for mandate signing |
| No | ES256 public key in JWK format (defaults to deriving from private key) |
| No | Public gateway URL (default: |
| No | Platform fee rate as decimal (default: |
| No | Wallet address for fee collection |
| No | Logging level (default: |
Deployment
AWS Lambda (Serverless)
npm run build
npm run deployThis 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 |
System architecture, component responsibilities, data flow | |
Profile discovery, capability negotiation, checkout state machine | |
Mandate types, signature chain, verification process | |
AWS Lambda setup, CloudFront, monitoring | |
Pricing, support, what's included |
Examples
examples/claude-desktop.json-- Claude Desktop MCP configurationexamples/autonomous-purchase.ts-- Full autonomous purchase flowexamples/mandate-flow.ts-- AP2 mandate generation and verification
License
MIT License. See LICENSE for details.
Built for the agentic commerce era.
Available Tools
5 toolsexecute_checkoutA
Execute a full checkout with AP2 mandate chain verification (intent, cart, payment mandates).
Inputs: checkout_id (required), cart_mandate (required), intent_mandate (required), payment_mandate (required).
manage_cartC
Create, modify, or retrieve a Shopify cart (create, add, remove, get).
Inputs: action (required), cart_id, quantity, variant_id.
negotiate_termsB
Negotiate capabilities, discounts, and shipping options between an agent and the merchant.
Inputs: cart_id (required), agent_profile_url (required), discount_code.
scout_inventoryB
Search the Shopify catalog for products matching query, category, and price filters.
Inputs: query (required), limit, category, price_max, +1 more.
track_orderA
Retrieve order status and fulfillment tracking information.
Inputs: order_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: checkout, cart management, negotiation, inventory search, and order tracking. No two tools overlap in purpose, making agent selection unambiguous.
All tool names follow a consistent verb_noun pattern (execute_, manage_, negotiate_, scout_, track_) with imperative verbs. No mixing of conventions.
With 5 tools, the server is well-scoped for a Shopify e-commerce agent. The count is neither too sparse nor overloaded, covering essential workflows without unnecessary complexity.
Covers core shopping lifecycle: cart, inventory, checkout, negotiation, and order tracking. Minor gaps like detailed product lookup by ID or order modification exist, but the surface supports primary agent tasks effectively.
Maintenance
Related MCP Connectors
The independent agent-commerce protocol for AI-agent checkout on any online store.
Autonomous commerce for AI agents: discover, quote, order, pay, verify.
Shopify product discovery and x402-paid offer verification for AI agents.
Agentic commerce + trust MCP: discover, verify, and transact across droplinked's merchant network.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically purchase physical and virtual goods from platforms like Amazon and Shopify using stablecoins, without the need for virtual debit cards or browser automation.1ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Shopify stores via natural language, with tools for products, orders, inventory, customers, and analytics.11 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to discover, check stock, and purchase products through your existing store APIs, with spend mandates, discount ceilings, and a full audit trail enforced in code.49,675 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI shopping agents to search products, check stock, apply promotions, manage cart sessions, and create cryptographically signed checkout sessions on e-commerce storefronts, while giving merchants analytics into agent intent and catalog demand gaps.MIT