🕹️ Merchant Demo MCP

Merchant Demo MCP is a sample Model Context Protocol (MCP) server that simulates a digital storefront (like Steam) and integrates with the Blockia Pay MCP for crypto-based payments using the X402 payment standard.

It exposes endpoints to search for games, view details, and purchase games securely through a decentralized payment flow powered by Blockia.

🚀 Features

• 🔍 Search games by title, region, or genre
• 🧾 View game details including price and availability
• 💳 Purchase games using Blockia Pay payment headers (X402 standard)
• 🔐 Secure 402 Payment Flow requiring payment authorization headers
• 📦 Returns license keys, transaction hashes, and receipts after successful purchase

🧩 Architecture Overview

This server is designed to work together with the blockia-pay-mcp server.

| Role | MCP Server | Responsibility | | ----------- | ------------------- | -------------------------------------------------------------- | | 💰 Payments | blockia-pay-mcp | Handles token balance checks and creates valid payment headers | | 🕹️ Merchant | merchant-demo-mcp | Exposes product data and enforces X402 payment requirements |

🧭 End-to-End Payment Flow

1. Search for a Game

search_games('Cyberpunk 2077');

→ Returns a list of matching games.

2. Prepare the Purchase

prepare_purchase('cyberpunk-2077');

→ Returns payment requirements (PaymentRequirements object).

3. Create Payment Headers (via Blockia Pay MCP)

create_payment_header({
  requirement: <PaymentRequirements>,
  x402Version: 1
})

→ Returns x-payment and x-payment-record-id headers.

4. Make the Purchase

make_purchase({
  gameId: 'cyberpunk-2077',
  paymentHeader: '<x-payment>',
  paymentHeaderRecordId: '<x-payment-record-id>',
});

→ Returns:

{
  "licenseKey": "CYBER-XYZ-123-KEY",
  "receiptUrl": "https://merchant.demo/receipts/abc123",
  "transactionHash": "0xabcde12345..."
}

⚙️ Tools Registered

search_games

Searches for games by name, with optional limit and region filters.

get_game_details

Retrieves detailed info about a game by ID.

prepare_purchase

Returns PaymentRequirements for a given game — used to generate a valid X402 payment header.

make_purchase

Completes a purchase using valid payment headers. Returns license key, transaction hash, and receipt URL.

🧩 Installation

npm install @blockia-pay/merchant-demo-mcp
npm run build

🧠 Notes

• This server does not require a blockchain wallet, but enforces payment via headers.
• Use together with the Blockia Pay MCP to simulate complete on-chain commerce flows.
• All data is mock/demo — replace endpoints with your backend to enable real purchases.

📜 License

MIT License © 2025 Blockia Labs