Guide

Assistenti AI (MCP)

Vendi da Claude Code, Cursor o Codex con una sola richiesta: prodotti, prezzi, link di pagamento e pagamenti di test con un server MCP locale e la tua chiave.

Vedi come Markdown

perly-pay-mcp lascia che il tuo assistente configuri Perly Pay per te: creare un prodotto e un prezzo, condividere un link di pagamento, pagarlo in modalità test e mostrare cosa è arrivato. Gira sulla tua macchina e parla solo con l’API di Perly Pay, con la tua chiave. Niente di nostro in mezzo.

Configurazione

1
Prendi una chiave di test
Dashboard → Developers → API keys: sk_test_…. Costruisci con questa: non si muove denaro reale.
2
Aggiungi il server
Una riga in Claude Code o poche righe nella configurazione di Cursor o Codex. Serve Node 20 o successivo.
3
Chiediglielo
«Vendi una consulenza di un’ora a $49 con un link di pagamento, poi pagala in modalità test e mostrami il pagamento».

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

Non mettere la chiave in git: il file di configurazione di un progetto finisce spesso nei commit.

Variabile	Cos’è
`PERLY_PAY_SECRET_KEY`	`sk_test_…` mentre costruisci. `sk_live_…` legge soltanto (vedi sotto).
`PERLY_PAY_API`	Di default `https://pay.perly.io`.
`PERLY_PAY_WEBHOOK_SECRET`	Facoltativa: `whsec_…` per `verify_webhook_signature`.

Tool

Generati dalla specifica dell’API stessa, quindi ogni argomento è quello che l’API accetta. Gli importi sono interi in centesimi: 4900 è $49.00.

Tool	A cosa servono
`create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price`	prodotti e prezzi
`create_payment_link`, `list_payment_links`, `update_payment_link`	link di pagamento
`create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session`	fatture e checkout
`create_customer`, `list_customers`, `retrieve_customer`	clienti
`create_subscription`, `list_subscriptions`, `retrieve_subscription`	abbonamenti
`check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage`	accesso e crediti
`list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events`	pagamenti, ricevute, eventi
`create_refund`, `list_refunds`	rimborsi
`create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint`	webhook
`simulate_payment`	modalità test
`verify_webhook_signature`, `pay_links`	sulla tua macchina

simulate_payment paga una fattura, oppure acquista tramite un link di pagamento e lo paga, così la consegna, le ricevute e i webhook scattano come con un acquirente reale. pay_links dà le pagine della dashboard per ciò che puoi fare solo tu.

Cosa non fa

Con una chiave live, legge soltanto. Ogni tool che scrive viene rifiutato: nuove fatture, sessioni di checkout, prodotti, prezzi, clienti, link e abbonamenti, modifiche, annullamenti, rimborsi, consumo di crediti e webhook. Il tool spiega perché; lo fai nella dashboard o nel codice della tua app. Perché: il testo scritto da un acquirente può arrivare all’assistente, e niente di ciò che arriva al server prova che sei stato tu, e non il modello, ad approvare una modifica reale.
Wallet, chiavi API, la tua fattura, passaggio alla modalità live e accesso con due fattori: nessun tool. Queste cose le fai tu nella dashboard; pay_links dà le pagine.
Ciò che non si può annullare (annullare una fattura, aprire un rimborso, eliminare un webhook) aspetta confirm: true, che l’assistente invia solo dopo che hai detto di sì.
La tua chiave segreta non viene mai ripetuta, né in una risposta né in un log.

Andare live

1
Collega un wallet
La sua chiave pubblica o un indirizzo, nella dashboard. Non chiediamo mai una seed phrase o una chiave privata. Vedi Wallet.
2
Attiva la modalità live
Nella dashboard, una volta collegato il wallet.
3
Cambia la chiave
Metti sk_live_… al posto di sk_test_… sul server della tua app. L’assistente può restare con la chiave di test.