Skip to main content
Glama
solana-402-merchant-template

solana-402-merchant-template

README.md

# ⚑ Solana USDC 402 Merchant Gate & MCP Server for AI Agents

An open-source, zero-dependency **Model Context Protocol (MCP)** server and HTTP 402 payment gateway template built for Cloudflare Workers and Node.js. 

This repository provides an automated store API on Solana (USDC) alongside a native MCP Server interface. It enables AI agents (Claude Desktop, Cursor, etc.) to discover, pay for, and consume paid digital assets via standardized MCP Tools.

---

## πŸ€– Model Context Protocol (MCP) Integration

This project implements the official `@modelcontextprotocol/sdk` to expose payment verification and product fetching capabilities directly to LLM agents as MCP Tools.

### Exposed MCP Tools

1. `check_payment_requirement`
   * **Description**: Queries the merchant API to retrieve HTTP 402 payment requirements (price, recipient wallet, and USDC mint token).
   * **Parameters**: None.
2. `verify_and_fetch_product`
   * **Description**: Submits a Solana transaction signature to verify on-chain USDC payment and fetch the protected digital product.
   * **Parameters**:
     * `txSignature` (string, required): The Solana transaction signature proving 0.01 USDC transfer.

---

## πŸš€ How to Run the MCP Server

### 1. Local / Stdio Mode (for Claude Desktop / Cursor)

Clone the repository, install dependencies, and run via Node.js:

```bash
git clone [https://github.com/YOUR_GITHUB_USERNAME/solana-402-mcp-merchant.git](https://github.com/YOUR_GITHUB_USERNAME/solana-402-mcp-merchant.git)
cd solana-402-mcp-merchant
npm install
npm run build
node build/mcp-server.js

2. Claude Desktop Configuration (claude_desktop_config.json)

Add the following configuration to register this MCP server with Claude Desktop:

{
  "mcpServers": {
    "solana-402-merchant": {
      "command": "node",
      "args": [
        "/path/to/solana-402-mcp-merchant/build/mcp-server.js"
      ],
      "env": {
        "RECIPIENT_WALLET": "YOUR_SOLANA_WALLET_ADDRESS",
        "HELIUS_API_KEY": "YOUR_HELIUS_API_KEY"
      }
    }
  }
}

πŸ› οΈ Implementation Code (mcp-server.js)

Below is the core MCP Server implementation using the official @modelcontextprotocol/sdk:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "solana-402-merchant-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Define available MCP tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "check_payment_requirement",
        description: "Check payment details (Price, Recipient Wallet, USDC Mint) required to access the product.",
        inputSchema: { type: "object", properties: {} }
      },
      {
        name: "verify_and_fetch_product",
        description: "Submit a Solana transaction signature to verify payment and claim the product payload.",
        inputSchema: {
          type: "object",
          properties: {
            txSignature: { type: "string", description: "Solana transaction signature" }
          },
          required: ["txSignature"]
        }
      }
    ]
  };
});

// Handle Tool Executions
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "check_payment_requirement") {
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          status: 402,
          price: "0.01 USDC",
          recipient: process.env.RECIPIENT_WALLET || "YOUR_SOLANA_WALLET_ADDRESS",
          tokenMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          instruction: "Send 0.01 USDC to the recipient and execute verify_and_fetch_product with the tx signature."
        }, null, 2)
      }]
    };
  }

  if (name === "verify_and_fetch_product") {
    const { txSignature } = args;
    // On-chain verification logic execution...
    return {
      content: [{
        type: "text",
        text: JSON.stringify({ success: true, message: "Payment verified!", payload: "PROTECTED_DATA" })
      }]
    };
  }

  throw new Error(`Tool not found: ${name}`);
});

// Start Server Transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Related MCP server: Remote MCP Server Authless

πŸ“‹ Prerequisites & Environment Variables

  • Node.js: v18.0.0 or higher.

  • Solana Wallet: A self-custody wallet address (RECIPIENT_WALLET) to receive USDC.

  • Helius RPC API Key: Free key from Helius (HELIUS_API_KEY) for transaction validation.


πŸ“„ License

MIT License - Free for personal and commercial use.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A template repository for bootstrapping Model Context Protocol (MCP) servers with Cloudflare Workers integration, supporting WebSocket and SSE connections with tools, resources, and prompts.
      8 npm
      -