Guides

AI assistants (MCP)

Sell from Claude Code, Cursor or Codex in one prompt: products, prices, payment links and test payments, through a local MCP server with your key.

View as Markdown

perly-pay-mcp lets your coding assistant set up Perly Pay for you: make a product and its price, share a payment link, pay it in test mode, and read what came in. It runs on your machine and talks only to Perly Pay's API, with your key. Nothing of ours sits in between.

perly-pay-mcp goes up on npm shortly; the lines below work from the day it does. Until then, call the API or use the SDKs.

Set up

1
Get a test key
Dashboard → Developers → API keys: sk_test_…. Build with it; nothing real moves.
2
Add the server
One line in Claude Code, or a few in Cursor's or Codex's config. Node 20 or newer.
3
Ask
"Sell a one-hour consultation for $49 with a payment link, then pay it in test mode and show me the payment."

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

Keep the key out of git: a config file inside a project is often committed.

Variable	What
`PERLY_PAY_SECRET_KEY`	`sk_test_…` while you build. `sk_live_…` works too, with the limits below.
`PERLY_PAY_API`	Default `https://pay.perly.io`.
`PERLY_PAY_WEBHOOK_SECRET`	Optional `whsec_…`, the default for `verify_webhook_signature`.

Tools

Generated from the API's own description, so every argument is the API's. Amounts are integers in cents: 4900 is $49.00.

Tools	For
`create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price`	products and prices
`create_payment_link`, `list_payment_links`, `update_payment_link`	payment links
`create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session`	invoices and checkout
`create_customer`, `list_customers`, `retrieve_customer`	customers
`create_subscription`, `list_subscriptions`, `retrieve_subscription`	subscriptions
`check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage`	access and credits
`list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events`	payments, receipts, events
`create_refund`, `list_refunds`	refunds
`create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint`	webhooks
`simulate_payment`	test mode
`verify_webhook_signature`, `pay_links`	on your machine

simulate_payment pays an invoice, or buys from a payment link and pays that, so fulfilment, receipts and webhooks fire as for a real buyer. pay_links gives the dashboard pages for what only you can do.

What it will not do

With a live key, nothing that moves or redirects money, spends a buyer's credits or deletes: no simulated payments, refunds, credit spending, or new or deleted webhook endpoints. The tool says why and where you do it. Reading, and making products, prices, links and invoices, work as in test.
Wallets, API keys, your plan, going live and two-factor sign-in have no tool. You do 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 sends only after asking you.
Your secret key is never repeated in an answer or a log.

Go live

1
Connect a wallet
Its public key or address, in the dashboard. We never ask for a seed or a private key. See Wallets.
2
Turn on live mode
In the dashboard, once the wallet is connected.
3
Swap the key
Put sk_live_… where sk_test_… was, in your app's server. Your assistant can keep the test key.