# 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.

`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](https://pay.perly.io/docs/test-mode.md) 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 Code**

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

**Cursor**

```json
// ~/.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**

```toml
# ~/.codex/config.toml
[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }
```

> **Attenzione:** 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](https://pay.perly.io/docs/api.md) 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](https://pay.perly.io/docs/webhooks.md) 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](https://pay.perly.io/docs/wallets.md).
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.