Perly Pay

perly-pay-mcp

Sell your work for crypto from your AI coding assistant. perly-pay-mcp is a local MCP server for Perly Pay: your assistant can create products, prices, payment links and invoices, pay them in test mode, read payments and receipts, and check a buyer's access. Bitcoin, USDC and USDT land straight in your own wallet; Perly Pay never holds them. It costs 2.5¢ a payment, never more than 0.5% of it, and a month of up to 21 payments is free.

It runs on your machine over stdio and talks only to Perly Pay's public API with your key. There is no server of ours in between.

Set up

Get a test key in Perly Pay: Dashboard → Developers → API keys (sk_test_…).

Claude Code

claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp

Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

{
  "mcpServers": {
    "perly-pay": {
      "command": "npx",
      "args": ["-y", "perly-pay-mcp"],
      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
    }
  }
}

Codex: ~/.codex/config.toml

[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }

Keep the key out of git: a config file in a project is often committed. Node 20 or newer.

Variable
PERLY_PAY_SECRET_KEY	sk_test_… while you build. sk_live_… reads only (see below).
PERLY_PAY_API	Default https://pay.perly.io. A perly.io host or this machine; plain http only for localhost.
PERLY_PAY_ALLOW_ANY_API	1 sends your key to any other https host in PERLY_PAY_API, for a copy you run yourself.
PERLY_PAY_WEBHOOK_SECRET	Optional whsec_…, the default for verify_webhook_signature.

Try it

Sell a one-hour consultation for $49 with a payment link, then pay it in test mode and show me the payment.

The assistant calls create_product, create_price, create_payment_link, simulate_payment and list_payments.

Tools

Area	Tools
Products and prices	create_product, list_products, update_product, create_price, list_prices, update_price
Payment links	create_payment_link, list_payment_links, update_payment_link
Invoices and checkout	create_invoice, list_invoices, retrieve_invoice, cancel_invoice, create_checkout_session, retrieve_checkout_session
Customers	create_customer, list_customers, retrieve_customer
Subscriptions (renewed by invoice)	create_subscription, list_subscriptions, retrieve_subscription
Access and credits	check_entitlement, list_entitlements, consume_entitlement_credits, list_credit_usage
Money in, read only	list_payments, retrieve_payment, list_receipts, retrieve_receipt, list_events
Refunds	create_refund, list_refunds
Webhooks	create_webhook_endpoint, list_webhook_endpoints, delete_webhook_endpoint
Test mode	simulate_payment: pays an invoice, or buys from a payment link and pays that
On your machine	verify_webhook_signature checks a Perly-Signature; pay_links gives the dashboard pages only you can use: plan, wallet, go live, two-factor, keys

The tools are generated from Perly Pay's OpenAPI document, so their arguments are the API's own.

What it will not do

• With a live key, it only reads. Every tool that writes is refused: creating invoices, checkout sessions, products, prices, customers, payment links and subscriptions, cancelling, editing, refunds, credit spending, simulated payments and webhook endpoints. It says why, and you do it in the dashboard or in your app's own code. Lists and lookups work as in test. Why: text a buyer typed can reach the assistant, and nothing the server receives proves that you, not the model, approved a live change (confirm: true is written by the model; a client's approval prompt and an MCP elicitation answer both come back through the client). So the server never writes with a live key.
• Wallets, API keys, billing, live mode and two-factor have no tool at all. You set them in the dashboard; pay_links gives the pages.
• What cannot be undone (cancelling an invoice, opening a refund, deleting a webhook endpoint) waits for confirm: true, which the assistant should only send after asking you.
• Your secret key is never repeated in an answer or a log.
• Buyers' license keys never reach the assistant: an event that carries one comes back without its key; they stay in the dashboard.
• Text others wrote is marked as data. Customer names, emails, descriptions and metadata can come from buyers, or from anyone who opens a payment link; every API answer ends with a note telling the assistant not to follow them. Still read what a tool is about to change before you approve it.

Docs: https://pay.perly.io/docs/mcp. API reference: https://pay.perly.io/docs/api. MIT licence.