@solinkify/mcp

@solinkify/mcp

MCP (Model Context Protocol) server that lets any AI agent — Claude Desktop, Claude Code, Cursor, or your own MCP host — pay for things on Solana through Solinkify, with hard spending caps. Agentic payments on the x402 standard, as a set of tools your agent already knows how to call:

• Gate (x402 paywalls): find priced endpoints in the public registry, preview prices, auto-pay HTTP 402 content, manage a pre-paid balance, buy subscriptions.
• DataHub: search the dataset marketplace and buy datasets (99% goes to the seller, download link returned).
• Pay: inspect and settle store checkout sessions (WooCommerce, OpenCart, PrestaShop, hosted checkout).
• Social Commerce: inspect and buy products from Blink links exactly as they circulate on X (share link, Actions URL, or raw id).

Quick start

Add to your MCP host config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "solinkify": {
      "command": "npx",
      "args": ["-y", "@solinkify/mcp"],
      "env": {
        "SOLINKIFY_WALLET_PATH": "/path/to/agent-keypair.json",
        "SOLINKIFY_MAX_PAYMENT_USD": "1",
        "SOLINKIFY_DAILY_CAP_USD": "10"
      }
    }
  }
}

The wallet is a standard Solana JSON keypair (solana-keygen new -o agent-keypair.json), funded with a little SOL for fees and the stablecoin you want to spend (USDC/USDT).

It is optional at startup: the server connects and lists its tools with no wallet configured, and the read-only tools (price preview, dataset search, checkout quotes) work as they are. Only the tools that spend ask for a keypair, and they say so in the tool result rather than failing at launch.

Docker

docker build -t solinkify-mcp .
docker run -i --rm solinkify-mcp                         # starts, tools listed
docker run -i --rm -v "$PWD/agent-keypair.json:/wallet.json:ro" \
  -e SOLINKIFY_WALLET_PATH=/wallet.json solinkify-mcp    # able to pay

-i is required: stdin and stdout carry the MCP protocol.

Tools

Tool	What it does
wallet_status	Address, SOL, stablecoin balances, prepaid balance, remaining budget
spend_authority_status	On-chain SpendAuthority (owner mode): caps, spent/left today, revoked
gate_find_endpoints	Browse the public registry of x402-priced endpoints (price, network, access modes, fits-your-cap)
gate_get_price	Preview an x402 paywall without paying
gate_fetch	Fetch gated content, auto-paying (prepaid preferred, escrow otherwise); files a signed delivery record when the gate keeps one
gate_check_delivery	Compare what the gate says it served with what the agent says it received
gate_prepaid_balance / gate_prepaid_deposit	Manage the pre-paid balance (no per-request signing)
gate_subscribe	Buy a creator's subscription plan (price read on-chain first)
datahub_search	Search the DataHub marketplace (results carry attested + quality_score)
datahub_buy	Buy a dataset and get the download link
datahub_review	Rate a dataset you bought (verified-purchase gated server-side)
datahub_subscribe	Time-based access to a recurring dataset (on-chain plan; renew extends expiry)
datahub_download	Fresh download link via purchase receipt or active subscription (no payment)
pay_get_session	Inspect a checkout session (accepts the full checkout URL)
pay_checkout	Pay a pending checkout session; the merchant's order is marked paid. With SOLINKIFY_OWNER_WALLET: spends the owner's funds under on-chain caps
social_get_blink	Inspect a Blink product link (title, price, seller) without paying
social_buy_blink	Buy from a Blink link; returns the receipt + download link

Authorization model

Moving money was never the hard part; scoped, revocable authority is. The agent never holds your main wallet: it runs on a dedicated keypair funded only with what it is allowed to spend (the outer bound), and the server enforces two hard caps before any funds move, on every tool:

• SOLINKIFY_MAX_PAYMENT_USD — max for a single payment (default 1)
• SOLINKIFY_DAILY_CAP_USD — max total per UTC day (default 10, persisted in ~/.solinkify/mcp-spend.json, fail-closed)

For Gate paywalls there is an on-chain scoped budget too: a prepaid balance is deposited once into a program-owned account and debited per request at on-chain prices; withdraw_prepaid pulls the remainder back at any time — the kill switch.

Owner mode (on-chain SpendAuthority)

Set SOLINKIFY_OWNER_WALLET to the base58 address of a funds owner and pay_checkout stops spending from the agent keypair: it settles through pay_spl_delegated, drawing from the owner's token account under a SpendAuthority the owner created on-chain — per-payment cap, daily ceiling, and revoke-as-kill-switch all enforced by the Solana program, not by this server. The agent wallet only signs and pays tx fees; it never holds the owner's funds or keys. Inspect the allowance with spend_authority_status.

The owner grants (and can instantly revoke) the allowance with the contract's create_spend_authority / update_spend_authority / revoke_spend_authority instructions, keyed to the agent's public key. One SpendAuthority covers one stablecoin mint. The local SOLINKIFY_MAX_PAYMENT_USD / SOLINKIFY_DAILY_CAP_USD caps still apply on top (defense in depth). Other paying tools (gate, DataHub, Blinks) still spend from the agent wallet.

Refusals come back as readable messages the agent can relay to the user. The server also self-identifies as an AI agent via User-Agent (override with SOLINKIFY_USER_AGENT), so Gate-protected sites answer with a clean 402 instead of being scraped.

Environment

Var	Default	Purpose
SOLINKIFY_WALLET_PATH / SOLINKIFY_WALLET_BS58	— (required)	Agent wallet
SOLANA_RPC_URL	devnet public RPC	Solana RPC
SOLINKIFY_NETWORK	devnet	mainnet-beta switches mints + default RPC
SOLINKIFY_API_URL	https://api.solinkify.com	Solinkify backend
SOLINKIFY_MAX_PAYMENT_USD	1	Per-payment cap
SOLINKIFY_DAILY_CAP_USD	10	Daily budget
SOLINKIFY_OWNER_WALLET	— (off)	Owner mode: pay_checkout spends the owner's funds via the on-chain SpendAuthority (ADR-008)

QA

scripts/qa-battery.mjs drives every tool through a real MCP stdio client against live devnet; scripts/qa-guard-probe.mjs proves both caps refuse.