# Assistentes de IA (MCP)

> Venda pelo Claude Code, Cursor ou Codex com um só pedido: produtos, preços, links de pagamento e pagamentos de teste com um servidor MCP local e a sua chave.

`perly-pay-mcp` deixa o seu assistente configurar o Perly Pay por você: criar um produto e um preço, compartilhar um link de pagamento, pagá-lo no [modo de teste](https://pay.perly.io/docs/test-mode.md) e mostrar o que chegou. Ele roda na sua máquina e só fala com a API do Perly Pay, com a sua chave. Não há nada nosso no meio.

## Configuração

1. **Pegue uma chave de teste** — Dashboard → Developers → API keys: `sk_test_…`. Construa com ela: nenhum dinheiro real se move.
2. **Adicione o servidor** — Uma linha no Claude Code ou algumas na configuração do Cursor ou do Codex. Precisa do Node 20 ou mais recente.
3. **Peça** — “Venda uma consultoria de uma hora a $49 com um link de pagamento, depois pague no modo de teste e me mostre o 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_…" }
```

> **Atenção:** Não coloque a chave no git: o arquivo de configuração de um projeto costuma entrar nos commits.

| Variável | O que é |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | `sk_test_…` enquanto você constrói. `sk_live_…` só lê (veja abaixo). |
| `PERLY_PAY_API` | Por padrão, `https://pay.perly.io`. |
| `PERLY_PAY_WEBHOOK_SECRET` | Opcional: `whsec_…` para `verify_webhook_signature`. |

## Ferramentas

Geradas a partir da especificação da própria [API](https://pay.perly.io/docs/api.md), então cada argumento é o que a API aceita. Os valores são inteiros em centavos: `4900` é $49.00.

| Ferramentas | Para quê |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | produtos e preços |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | links de pagamento |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | faturas e checkout |
| `create_customer`, `list_customers`, `retrieve_customer` | clientes |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | assinaturas |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | acesso e créditos |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | pagamentos, recibos, eventos |
| `create_refund`, `list_refunds` | reembolsos |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | webhooks |
| `simulate_payment` | modo de teste |
| `verify_webhook_signature`, `pay_links` | na sua máquina |

`simulate_payment` paga uma fatura, ou compra com um link de pagamento e paga, então a entrega, os recibos e os [webhooks](https://pay.perly.io/docs/webhooks.md) disparam como com um comprador real. `pay_links` dá as páginas do painel para o que só você pode fazer.

## O que ele não faz

- **Com uma chave de produção, só lê.** Toda ferramenta que escreve é recusada: faturas, sessões de pagamento, produtos, preços, clientes, links e assinaturas novos, alterações, cancelamentos, reembolsos, gasto de créditos e webhooks. A ferramenta diz por quê; você faz isso no painel ou no código do seu app. Por quê: o texto digitado por um comprador pode chegar ao assistente, e nada do que o servidor recebe prova que foi você, e não o modelo, quem aprovou uma mudança real.
- **Carteiras, chaves de API, fatura, passagem para produção e login com dois fatores**: sem ferramentas. Isso você faz no painel; `pay_links` dá as páginas.
- **O que não pode ser desfeito** (cancelar uma fatura, abrir um reembolso, apagar um webhook) espera `confirm: true`, que o assistente só envia depois que você diz sim.
- **Sua chave secreta nunca é repetida** numa resposta nem num log.

## Ir para produção

1. **Conecte uma carteira** — A chave pública dela ou um endereço, no painel. Nunca pedimos uma frase semente nem uma chave privada. Veja [Carteiras](https://pay.perly.io/docs/wallets.md).
2. **Ative a produção** — No painel, depois de conectar a carteira.
3. **Troque a chave** — Coloque `sk_live_…` no lugar de `sk_test_…` no servidor do seu app. O assistente pode ficar com a chave de teste.