<div align="center">
# Shopify Agentic MCP Gateway
**The first tri-protocol commerce gateway for autonomous AI agents on Shopify.**
Let AI agents browse, negotiate, cart, pay, and track orders -- fully autonomously.
[](https://ucp.dev)
[](https://agentpayments.dev)
[](https://modelcontextprotocol.io)
[](https://typescriptlang.org)
[](LICENSE)
</div>
---
## 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
```bash
git clone https://github.com/kuro-tomo/shopify-agentic-mcp.git
cd shopify-agentic-mcp
npm install
```
### 2. Configure
```bash
cp .env.example .env
```
Edit `.env` with your Shopify credentials:
```env
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
```bash
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`):
```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)
```bash
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](docs/deployment.md) for the full deployment guide.
---
## Documentation
| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | System architecture, component responsibilities, data flow |
| [UCP Integration](docs/ucp-integration.md) | Profile discovery, capability negotiation, checkout state machine |
| [AP2 Mandates](docs/ap2-mandates.md) | Mandate types, signature chain, verification process |
| [Deployment Guide](docs/deployment.md) | AWS Lambda setup, CloudFront, monitoring |
| [Developer Kit](docs/developer-kit.md) | Pricing, support, what's included |
---
## Examples
- [`examples/claude-desktop.json`](examples/claude-desktop.json) -- Claude Desktop MCP configuration
- [`examples/autonomous-purchase.ts`](examples/autonomous-purchase.ts) -- Full autonomous purchase flow
- [`examples/mandate-flow.ts`](examples/mandate-flow.ts) -- AP2 mandate generation and verification
---
## License
MIT License. See [LICENSE](LICENSE) for details.
---
<div align="center">
**Built for the agentic commerce era.**
[Documentation](docs/) | [Examples](examples/) | [Issues](https://github.com/kuro-tomo/shopify-agentic-mcp/issues)
</div>
