P Link.io MCP Server: Solana HTTP 402 Payments

Overview

P Link.io MCP Server is a lightweight Model Context Protocol (MCP) server designed to implement HTTP 402 (Payment Required) flows using the Solana blockchain. It provides a deterministic, machine-readable way to demand and validate on-chain payments for metered services, agent invocations, or pay-per-use APIs. The server issues payment requests, verifies incoming Solana transactions, and triggers callbacks once a payment is confirmed.

This server is useful when you need reliable programmatic billing tied to Solana transfers — for example, enforcing paywalls on API endpoints, collecting micropayments for AI agents, or creating pay-to-claim flows. It supports configurable networks (devnet/testnet/mainnet), idempotent payment references, and webhook-style notifications so backend systems can react only after on-chain confirmation.

Features

• Issue HTTP 402 responses with structured Solana payment request payloads
• Validate incoming Solana transactions and confirm on-chain finality
• Configurable Solana RPC endpoint and network selection (devnet/testnet/mainnet)
• Idempotent references to map payments to requests or agents
• Webhook/callback notifications after successful confirmation
• Docker-friendly and local development support
• Simple REST API for integration with existing services
• Basic logging and retryable verification logic

Installation / Configuration

Clone the repository and install dependencies:

git clone https://github.com/paracetamol951/P-Link-MCP.git
cd P-Link-MCP
npm install

Create a .env file (example below) or set environment variables directly:

# .env
PORT=8080
RPC_URL=https://api.devnet.solana.com
NETWORK=devnet
WALLET_KEYPAIR=/path/to/keypair.json
CALLBACK_URL=https://example.com/payment-callback
CONFIRMATIONS=1
LOG_LEVEL=info

Common environment variables

Run locally:

npm start
# or in development
npm run dev

Docker:

# Build
docker build -t p-link-mcp:latest .

# Run
docker run -p 8080:8080 \
  -e RPC_URL="https://api.devnet.solana.com" \
  -e WALLET_KEYPAIR="/secrets/keypair.json" \
  -v /local/keypair.json:/secrets/keypair.json \
  p-link-mcp:latest

Available Resources

• Repository: https://github.com/paracetamol951/P-Link-MCP
• Solana docs and RPC reference: https://docs.solana.com
• solana-web3.js (client examples) for constructing and sending transactions
• Solana Explorer to inspect transactions and confirmations

Use Cases

1. Metered API endpoints

   • Protect an AI agent endpoint so clients must pay a small SOL amount before the server processes the request. The MCP server returns a 402 with a payment_request payload. After the server verifies the on-chain transfer with the embedded reference, it processes the original request.

2. Pay-Per-Action Agents

   • A chat bot charges per advanced response. On request, return a 402 with amount and reference. After confirmation, call the agent and deliver the result.

3. Micropayments and Tipping

   • Accept tips for content or utilities. Present a standardized payment request that wallets can parse and pay. On confirmation, trigger a webhook to credit the tip.

4. Escrow-like confirmation for supply chains

   • Use MCP to gate the release of a digital artifact until a Solana transfer is confirmed and verified.

Example: Typical Flow

1. Client requests a protected resource:
   • GET /protected
2. Server responds with HTTP 402 and JSON payload:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "payment_request": {
    "amount_sol": "0.01",
    "recipient": "RecipientPubkeyHere",
    "reference": "unique-reference-1234",
    "memo": "Access to /protected for request 987",
    "network": "devnet"
  }
}

3. Client builds and sends a Solana transfer including the reference account or memos as specified.
4. Client POSTs the transaction signature (optional) to /payments/verify or the server polls the RPC to confirm.
5. On confirmation, server sends a POST to CALLBACK_URL with status and signature, then allows access.

Example verify POST:

curl -X POST https://mcp.example.com/payments/verify \
  -H "Content-Type: application/json" \
  -d '{"reference":"unique-reference-1234","signature":"5n...abc"}'

Callback payload (delivered after confirmations):

{
  "reference": "unique-reference-1234",
  "signature": "5n...abc",
  "slot": 12345678,
  "status": "confirmed"
}

Security and Best Practices

• Use a dedicated receiving keypair and secure its file permissions or a secrets manager.
• Require a unique reference per payment to avoid replay or double-crediting.
• Enforce at least 1–2 confirmations in production; increase for mainnet.
• Validate that transactions send the correct amount and to the intended recipient before granting service.
• Log events for auditability and monitoring.

For implementation details and examples, see the repository on GitHub: https://github.com/paracetamol951/P-Link-MCP