MCP

Toda a API do motor é acessível por MCP (Model Context Protocol). Na prática: conecte o seu agente (Claude, ou qualquer cliente MCP) e diga “cria um plano semestral com a Caixa do Clube e 20% nos dois primeiros ciclos” — ele faz.

Conectando

Endpoint MCP: https://motor.revtriever.com/mcp (transporte Streamable HTTP), autenticado com a mesma API key do REST — crie uma em Cobrança → Integração ou via POST /v1/integration/api-keys.

Claude Code

claude mcp add --transport http revtriever-motor https://motor.revtriever.com/mcp \
  --header "Authorization: Bearer rk_sua_api_key"

Claude Desktop e outros clientes

No arquivo de configuração de MCP do cliente:

{
  "mcpServers": {
    "revtriever-motor": {
      "type": "http",
      "url": "https://motor.revtriever.com/mcp",
      "headers": { "Authorization": "Bearer rk_sua_api_key" }
    }
  }
}

O servidor é stateless: cada chamada é independente, não há sessão para expirar. 401 significa API key ausente, errada ou revogada.

Confirme que funcionou

1. Pelo agente — pergunte: “qual o estado da integração do motor?”. Ele deve chamar integration_status e responder com os últimos 4 caracteres do seu secret e o webhook de alertas. Depois: “lista meus produtos” (product_list).
2. Sem agente, por curl — o handshake responde na hora:

curl -s https://motor.revtriever.com/mcp \
  -H "Authorization: Bearer rk_sua_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}'

Esperado: "serverInfo":{"name":"revtriever-motor"...} na resposta. Com 401, confira a API key; sem resposta, confira a rede.

3. Primeiro fluxo real por conversa — o mesmo onboarding do quickstart, sem escrever uma linha: “cria o produto Caixa do Clube por R$ 249,90/mês, monta um plano semestral com 20% nos dois primeiros ciclos e vincula a cliente [email protected] com primeira cobrança dia 5”. Confira o resultado com “simula a próxima fatura dela” (subscription_preview — dry-run, zero efeitos).

Tools disponíveis

Tool	Faz	Tipo
product_create	Cria produto (preço fixo mensal ou variável via endpoint)	escrita
product_list	Lista o catálogo	leitura
product_get	Detalha um produto	leitura
product_update	Altera nome/preço/endpoint — o nome reflete no gateway	escrita
product_archive	Arquiva (novas assinaturas bloqueadas; as vivas seguem)	escrita
plan_create	Plano completo com régua de desconto por produto	escrita
plan_list	Lista as ofertas	leitura
plan_get	Detalha um plano com a versão base vigente	leitura
plan_release_version	Nova versão base — só assinantes novos entram nela	escrita
plan_archive	Arquiva um plano	escrita
subscription_create	Vincula um cliente a um plano (com firstChargeDate opcional)	escrita
subscription_list	Assinaturas com plano, ciclo e status	leitura
subscription_get	Detalha uma assinatura	leitura
subscription_customize	Condições próprias de UM assinante (fork de versão)	escrita
subscription_cancel	Cancela, devolvendo o estado da fidelidade	escrita
invoice_list	Faturas por status (retidas em destaque)	leitura
invoice_get	Fatura com itens e histórico cru de pricing	leitura
invoice_retry_pricing	Re-chama seu endpoint de preço fora do cronograma	escrita
invoice_set_item_value	Destrava fatura retida com valor manual	escrita
event_list	Replay dos eventos, com cursor e filtros	leitura
integration_status	Secret vigente e webhook de alertas	leitura
pricing_test	Chamada mode: test assinada no seu endpoint	escrita

Nas tools de criação (product_create, plan_create, subscription_create) você pode passar idempotencyKey — repita a mesma chave para re-tentar sem duplicar; omitida, geramos uma por chamada.

As tools de escrita respeitam as mesmas validações e idempotência do REST — é a mesma implementação por baixo, não um atalho.