@voidly/pay-mcp

MCP server exposing Voidly Pay primitives to Claude Code, Cursor, Windsurf, and any MCP-compatible client. 27 tools across wallet, transfer, batch, escrow, streams, subscriptions, x402 (server + client), webhooks, and observability.

Install (one line)

Add to your client's MCP config (Claude Code's .mcp.json, Cursor's ~/.cursor/mcp.json, Windsurf's ~/.codeium/windsurf/mcp_config.json, etc.):

{
  "mcpServers": {
    "voidly-pay": {
      "command": "npx",
      "args": ["-y", "@voidly/pay-mcp"]
    }
  }
}

On first run the server mints + persists an Ed25519 keypair to ~/.voidly-pay/keypair.json (mode 0600). The DID derived from that key is your agent's identity.

What you can do (27 tools)

# Wallet
agent_pay_self                    Show this agent's DID, pubkey, balance.
agent_wallet_balance              Read any wallet (defaults to self).
agent_wallet_ensure               Idempotent wallet creation.

# Transfers
agent_pay                         Send N credits to a DID.
agent_pay_batch                   Multi-recipient atomic transfer (≤100).
agent_pay_get                     Look up a transfer by id.
agent_payment_history             Paginated history.

# Escrow
agent_escrow_open / release / refund

# Streams (per-token billing)
agent_stream_open / meter / finalize

# Subscriptions (recurring)
agent_subscribe / agent_subscription_cancel

# x402 (server + client)
agent_x402_quote                  Server: issue a 402 quote.
agent_x402_verify                 Server: verify + consume X-Payment.
agent_x402_fetch                  Client: pay-on-402, returns final response.

# Webhooks
agent_webhook_subscribe / agent_webhook_delete

# Observability (read-only)
agent_pay_health / manifest / stats / activity / leaderboard / feed / trust

Configuration

Environment variables (set in your MCP client config under env):

{
  "mcpServers": {
    "voidly-pay": {
      "command": "npx",
      "args": ["-y", "@voidly/pay-mcp"],
      "env": {
        "VOIDLY_PAY_API_URL": "https://api.voidly.ai"
      }
    }
  }
}

Or pass --api-url <url> as a CLI arg.

First-run quickstart

1. Add the config above and restart your MCP client.
2. The server prints your DID to stderr on startup. Copy it.
3. In a chat, ask: "Use voidly-pay to claim a sandbox wallet for me".
4. The tool registers a 1,000-credit test wallet via POST /v1/pay/test/wallet/create.
5. Now ask: "Send 0.1 credits to did:voidly:example".

Build a paid MCP server: registerPaidTool (v0.2.0+)

Want to ship your own MCP server that gets paid per call? registerPaidTool is a drop-in middleware that wraps any tool with a Voidly Pay x402 paywall. First call returns a quote; second call (with the quote ID passed back) verifies on-chain and runs the tool.

This mirrors Stripe's registerPaidTool pattern in @stripe/agent-toolkit, but settles in Voidly Pay credits (Stage 1) or USDC on Base (Stage 2) instead of Stripe Checkout — no merchant-of-record requirement, no 2-day rolling settlement, no card-processing fees.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { VoidlyPay } from "@voidly/pay";
import { registerPaidTool } from "@voidly/pay-mcp";

const pay = await VoidlyPay.create();
const server = new Server(
  { name: "my-paid-server", version: "1.0.0" },
  { capabilities: { tools: {} } },
);

registerPaidTool(server, {
  name: "summarize_pdf",
  description: "Summarize a PDF document.",
  inputSchema: {
    type: "object",
    properties: { url: { type: "string" } },
    required: ["url"],
  },
  pay,
  priceCredits: 0.01,        // $0.01/call in Stage 2
  reason: "PDF summarization (Llama 3.1 8B)",
  handler: async ({ url }) => {
    const summary = await summarizePdf(url);
    return { summary };
  },
});

// Optional: register more paid tools on the same server.
// registerPaidTool(server, { name: "...", ... });

await server.connect(new StdioServerTransport());

What the LLM sees on the first call:

{
  "status": "payment_required",
  "quote_id": "q_…",
  "pay_url": "https://api.voidly.ai/v1/pay/x402/quote/q_…",
  "amount_credits": 0.01,
  "recipient_did": "did:voidly:…",
  "reason": "PDF summarization (Llama 3.1 8B)",
  "instructions": "Pay this quote, then re-invoke \"summarize_pdf\" with x_voidly_quote: \"q_…\"."
}

A Voidly-Pay-aware client (any using @voidly/pay, voidly-pay-langchain, voidly-pay-crewai, @voidly/pay-vercel-ai, or another MCP server with registerPaidTool) will pay the quote automatically and re-invoke. The wrapped handler runs only after the quote is verified.

License

MIT