# Asistentes de IA (MCP)

> Vende desde Claude Code, Cursor o Codex con una sola petición: productos, precios, enlaces de pago y pagos de prueba con un servidor MCP local y tu clave.

`perly-pay-mcp` deja que tu asistente configure Perly Pay por ti: crear un producto y un precio, compartir un enlace de pago, pagarlo en [modo de prueba](https://pay.perly.io/docs/test-mode.md) y mostrar lo que llegó. Se ejecuta en tu equipo y solo habla con la API de Perly Pay, con tu clave. No hay nada nuestro en medio.

## Configuración

1. **Obtén una clave de prueba** — Dashboard → Developers → API keys: `sk_test_…`. Construye con ella: no se mueve dinero real.
2. **Añade el servidor** — Una línea en Claude Code o unas pocas en la configuración de Cursor o Codex. Necesita Node 20 o posterior.
3. **Pídeselo** — «Vende una consulta de una hora a $49 con un enlace de pago, luego págala en modo de prueba y muéstrame el pago».

**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_…" }
```

> **Atención:** No pongas la clave en git: el archivo de configuración de un proyecto suele subirse en los commits.

| Variable | Qué es |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | `sk_test_…` mientras construyes. `sk_live_…` solo lee (ver abajo). |
| `PERLY_PAY_API` | Por defecto `https://pay.perly.io`. |
| `PERLY_PAY_WEBHOOK_SECRET` | Opcional: `whsec_…` para `verify_webhook_signature`. |

## Herramientas

Generadas a partir de la especificación de la propia [API](https://pay.perly.io/docs/api.md), así que cada argumento es el que acepta la API. Los importes son enteros en centavos: `4900` es $49.00.

| Herramientas | Para qué |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | productos y precios |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | enlaces de pago |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | facturas y pago |
| `create_customer`, `list_customers`, `retrieve_customer` | clientes |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | suscripciones |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | acceso y créditos |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | pagos, recibos, eventos |
| `create_refund`, `list_refunds` | reembolsos |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | webhooks |
| `simulate_payment` | modo de prueba |
| `verify_webhook_signature`, `pay_links` | en tu equipo |

`simulate_payment` paga una factura, o compra con un enlace de pago y lo paga, así que la entrega, los recibos y los [webhooks](https://pay.perly.io/docs/webhooks.md) se disparan como con un comprador real. `pay_links` da las páginas del panel para lo que solo puedes hacer tú.

## Qué no hace

- **Con una clave real, solo lee.** Toda herramienta que escribe se rechaza: facturas, sesiones de pago, productos, precios, clientes, enlaces y suscripciones nuevos, cambios, cancelaciones, reembolsos, gasto de créditos y webhooks. La herramienta explica por qué; lo haces en el panel o en el código de tu app. Por qué: el texto que escribe un comprador puede llegar al asistente, y nada de lo que recibe el servidor prueba que fuiste tú, no el modelo, quien aprobó un cambio real.
- **Billeteras, claves de API, tu factura, paso a modo real y acceso con dos factores**: sin herramientas. Eso lo haces tú en el panel; `pay_links` da las páginas.
- **Lo que no se puede deshacer** (cancelar una factura, abrir un reembolso, borrar un webhook) espera a `confirm: true`, que el asistente solo envía después de que digas que sí.
- **Tu clave secreta nunca se repite** ni en una respuesta ni en un registro.

## Pasar a real

1. **Conecta una billetera** — Su clave pública o una dirección, en el panel. Nunca pedimos una frase semilla ni una clave privada. Ver [Billeteras](https://pay.perly.io/docs/wallets.md).
2. **Activa el modo real** — En el panel, una vez conectada la billetera.
3. **Cambia la clave** — Pon `sk_live_…` en lugar de `sk_test_…` en el servidor de tu app. El asistente puede quedarse con la clave de prueba.