# ⚡ 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 built for Cloudflare Workers and Node.js.

This project enables AI agents (Claude Desktop, Cursor, etc.) to natively discover, negotiate, and autonomously pay for digital resources over Solana USDC using standardized MCP tools and standard `HTTP 402 Payment Required` headers.

---

## 🤖 Model Context Protocol (MCP) Integration

This repository natively implements the official `@modelcontextprotocol/sdk` to expose agentic payment verification capabilities as standard MCP Tools.

### Exposed MCP Tools

1. **`check_payment_requirement`**
   * **Description**: Queries the merchant endpoint to fetch required payment metadata (Price in USDC, Recipient Wallet Address, and Token Mint ID).
   * **Input Schema**: None.
   * **Returns**: Standardized HTTP 402 payment requirements for LLM evaluation.

2. **`verify_and_fetch_product`**
   * **Description**: Submits a Solana transaction signature (`X-SOLANA-TX`) to verify on-chain USDC transfer and retrieve the protected payload.
   * **Input Schema**:
     * `txSignature` (`string`, **required**): The Solana transaction signature proving 0.01 USDC transfer to the recipient wallet.
   * **Returns**: Protected digital asset or API payload upon successful verification.

---

## 💻 MCP Server Implementation Code

This MCP Server connects via `StdioServerTransport` using `@modelcontextprotocol/sdk`:

```javascript
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: {} } }
);

// Register MCP Tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "check_payment_requirement",
        description: "Returns price, recipient wallet, and token details required to unlock this product.",
        inputSchema: { type: "object", properties: {} }
      },
      {
        name: "verify_and_fetch_product",
        description: "Verifies a Solana transaction signature and unlocks the paid content.",
        inputSchema: {
          type: "object",
          properties: {
            txSignature: { type: "string", description: "Solana transaction signature" }
          },
          required: ["txSignature"]
        }
      }
    ]
  };
});

// Handle Tool Requests
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",
          instructions: "Send 0.01 USDC on Solana and submit the signature via verify_and_fetch_product."
        }, null, 2)
      }]
    };
  }

  if (name === "verify_and_fetch_product") {
    const { txSignature } = args;
    // On-chain verification logic via Helius RPC...
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: true,
          tx: txSignature,
          data: "PROTECTED_DIGITAL_CONTENT"
        }, null, 2)
      }]
    };
  }

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

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

main().catch(console.error);

git clone [https://github.com/YOUR_USERNAME/solana-402-mcp-merchant.git](https://github.com/YOUR_USERNAME/solana-402-mcp-merchant.git)
cd solana-402-mcp-merchant
npm install
npm run build

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