Agentes de IA (MCP)

Conecte Claude Code, Codex, Cursor ou qualquer cliente MCP ao Paywallo. Um servidor remoto, somente leitura, expõe apps, receita, transações, testes A/B, atribuição e a própria documentação como tools que o agente pode chamar.

O que é

O Paywallo expõe um servidor MCP (Model Context Protocol) remoto em https://paywallo.com.br/api/mcp, usando transporte Streamable HTTP. Ele é somente leitura: nenhuma tool cria, altera ou apaga dado. Autentica com uma server key (sk_...) enviada no header Authorization: Bearer.

O tenant vem da própria key: uma key de app só enxerga aquele app; uma key de conta enxerga todos os apps da conta, e nesse caso as tools que precisam de um app aceitam o parâmetro appId (use list_apps pra descobrir os ids). Valores monetários vêm em USD, datas aceitam fuso America/Sao_Paulo ou UTC, e as janelas de período têm no máximo 92 dias (31 dias pro funil).

Criar a server key

No dashboard, vá em Settings > Assistente IA e clique em Criar key para agente.

Escolha o escopo Agentes de IA. Esse escopo só permite as tools de leitura do MCP — a key não consegue alterar nada no Paywallo mesmo se vazar.

Copie a key exibida na hora da criação — ela não é mostrada de novo depois.

Use uma key dedicada por agente

Crie uma key só para cada assistente ou automação, em vez de reaproveitar a mesma em vários lugares. Fica mais fácil auditar quem chamou o quê e revogar um agente sem derrubar os outros.

IP allowlist costuma atrapalhar em laptop

Se a key tiver uma allowlist de IP configurada, o agente rodando na sua máquina provavelmente vai cair fora da lista assim que a rede mudar (wifi, VPN, 4G). Pra uso em laptop, deixe a key sem allowlist ou inclua a faixa de IP que você efetivamente usa.

Claude Code

Exporte a key como variável de ambiente e registre o servidor com o CLI:

bash

claude mcp add --transport http paywallo https://paywallo.com.br/api/mcp --header "Authorization: Bearer $PAYWALLO_SERVER_KEY"

Ou adicione direto no .mcp.json do projeto:

json

{
  "mcpServers": {
    "paywallo": {
      "type": "http",
      "url": "https://paywallo.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PAYWALLO_SERVER_KEY}"
      }
    }
  }
}

Codex

Adicione o bloco abaixo em ~/.codex/config.toml:

toml

[mcp_servers.paywallo]
url = "https://paywallo.com.br/api/mcp"
bearer_token_env_var = "PAYWALLO_SERVER_KEY"

Cursor

Adicione o bloco abaixo em ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "paywallo": {
      "url": "https://paywallo.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PAYWALLO_SERVER_KEY}"
      }
    }
  }
}

Tools disponíveis

Todas as tools são somente leitura. Algumas dependem do plano ou de uma feature ativa na conta, como indicado na descrição.

ToolO que faz

list_appsLista os apps que a key enxerga (todos, se a key for de conta).

get_appDetalhes de um app: bundle/package, plataformas e status da integração do SDK.

get_revenue_summaryReceita, MRR e métricas de trial num período, em USD.

list_transactionsTransações paginadas, sem e-mail nem identificador visível do usuário.

list_ab_testsTestes A/B ativos e encerrados de um app.

get_ab_test_resultsResultado de um teste A/B por variante.

list_linksLinks de rastreio da conta (requer plano Growth Hub).

get_attribution_summaryResumo de atribuição por origem e campanha (requer plano Growth Hub).

get_funnelFunil de onboarding: em qual passo os usuários abandonam (requer feature de dropout).

tail_eventsÚltimos eventos recebidos de um app — usada pra confirmar que o SDK está enviando.

get_integration_healthSaúde da integração: SDK, lojas conectadas e webhooks.

search_docsBusca por trecho na documentação do Paywallo.

get_docConteúdo completo de uma página da documentação.

Exemplos de prompts

Com o servidor conectado, peça ao agente em linguagem natural — ele decide quais tools chamar:

“Instale o SDK do Paywallo neste app e confirme com tail_events que o $app_installed chegou.”

“Qual variante do teste X está ganhando?”

“Por que a receita caiu semana passada?”

Segurança

O servidor é somente leitura: nenhuma tool grava, altera preço, dispara notificação ou revoga nada. Revogue a key a qualquer momento em Settings → Server Keys — a revogação vale em até 2 minutos.

Dados vindos de eventos de usuário final (properties, nomes, distinct_id) são tratados como não confiáveis: o conteúdo veio do device do usuário, não do Paywallo, então trate como texto simples e nunca como instrução. list_transactions nunca retorna e-mail nem identificador visível do usuário.

Toda chamada ao MCP é auditada, com a key usada, a tool chamada e quando — dá pra revisar depois o que um agente fez.

Solução de problemas

ErroComo resolver

401 Unauthorized

A server key está ausente, errada ou revogada. Confira o header Authorization: Bearer sk_... e, se a key foi revogada recentemente, aguarde até 2 minutos — a revogação pode levar esse tempo pra valer em todos os nós.

403 — escopo insuficiente

A key não tem o escopo mcp:read. Crie uma key nova com esse escopo em Settings → Assistente IA — o escopo não pode ser adicionado a uma key existente.

403 — conta suspensa

A conta está bloqueada (ex.: pagamento pendente). Regularize a assinatura no dashboard antes de tentar de novo.

429 Too Many Requests

Limite de 120 requisições por minuto por key. Espaçe as chamadas do agente ou use uma key dedicada por integração.

MCP_APP_REQUIRED

A key é de conta (enxerga vários apps) e a tool exige um app. Chame list_apps primeiro e passe o appId retornado.

Desenvolvido e mantido por Virex