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.

Você vai precisar de uma API key (rk_…), a mesma do REST — crie uma em Cobrança → Integração ou via POST /v1/integration/api-keys. Ela vale para REST e MCP ao mesmo tempo.

Skills para o seu agente

O MCP dá as mãos (tools); as skills dão o procedimento — convenções da API, o endpoint de preço com a verificação HMAC certa, webhooks com dedupe e replay, a régua de recuperação, a política de negociação. Instale as duas coisas juntas:

# qualquer agente com suporte a Agent Skills (Claude Code, Cursor, Codex…)
npx skills add Revtriever/revtriever-skills

No Claude Code, o plugin instala as skills e já configura o servidor MCP do motor. Ele lê a API key da variável de ambiente REVTRIEVER_API_KEY, que precisa existir no shell antes de abrir o Claude Code:

export REVTRIEVER_API_KEY=rk_sua_api_key   # no mesmo terminal em que você vai abrir o claude
claude

Dentro do Claude Code:

/plugin marketplace add Revtriever/revtriever-skills
/plugin install revtriever@revtriever-skills

Exportou a variável com o Claude Code já aberto, ou em outro terminal? O servidor aparece como failed to connect em /mcp. Feche e abra o Claude Code de novo no terminal onde a variável existe — ela é lida no momento em que o servidor conecta. Para não repetir o export a cada terminal, deixe a linha no seu ~/.bashrc ou ~/.zshrc.

Fonte: github.com/Revtriever/revtriever-skills. Com o plugin instalado, a seção Conectando abaixo já está feita — pule para Confirme que funcionou.

Conectando

Endpoint MCP: https://motor.revtriever.com/mcp, transporte Streamable HTTP, autenticado com o header Authorization: Bearer rk_sua_api_key.

Claude Code

Pelo terminal, uma linha:

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

• --scope user deixa o servidor disponível em qualquer pasta. Sem ele o padrão é local, e o motor só aparece no projeto em que o comando foi rodado.
• A key fica gravada em texto puro no ~/.claude.json. Se preferir não deixá-la ali, use um .mcp.json na raiz do projeto lendo a variável de ambiente — é exatamente o que o plugin faz:

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

Com o .mcp.json, vale a mesma regra do plugin: REVTRIEVER_API_KEY precisa estar no shell antes de abrir o Claude Code. Depois de adicionar por qualquer um dos dois caminhos, abra o Claude Code na pasta e rode /mcp — revtriever-motor deve aparecer como conectado, e as tools aparecem para o agente com o prefixo revtriever-motor.

Cursor, Codex e outros clientes com arquivo de config

A forma exata varia por cliente, mas o que muda é só onde o JSON mora. No Cursor, em .cursor/mcp.json (projeto) ou ~/.cursor/mcp.json (global):

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

Para outros clientes, procure na documentação deles como registrar um servidor MCP remoto por HTTP com header de autenticação — são esses três dados: a URL acima, o header Authorization e o valor Bearer rk_sua_api_key.

Claude Desktop

O Claude Desktop não lê servidor HTTP com header de autenticação direto do arquivo de configuração. O caminho é um proxy stdio que repassa o header, como o mcp-remote, no claude_desktop_config.json:

{
  "mcpServers": {
    "revtriever-motor": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://motor.revtriever.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer rk_sua_api_key" }
    }
  }
}

O valor vai numa variável de ambiente, e não direto no argumento, porque o Claude Desktop quebra argumentos com espaço. Reinicie o Claude Desktop depois de salvar. O servidor é stateless: cada chamada é independente, não há sessão para expirar.

Confirme que funcionou

1. No Claude Code — rode /mcp. revtriever-motor deve aparecer como conectado. Se aparecer failed to connect, veja Deu errado? abaixo.
2. 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).
3. 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.

4. 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 ana@exemplo.com.br com primeira cobrança dia 5”. Confira o resultado com “simula a próxima fatura dela” (subscription_preview — dry-run, zero efeitos).

Deu errado?

Sintoma	Causa provável
failed to connect no /mcp do Claude Code	REVTRIEVER_API_KEY não existia no shell que abriu o Claude Code (plugin ou .mcp.json), ou a key está errada. Confira com o curl acima e reabra o Claude.
401 no curl	API key ausente, errada ou revogada. Gere outra em Cobrança → Integração.
O motor aparece num projeto e some em outro	claude mcp add sem --scope user — o servidor ficou só na pasta onde foi rodado.
429 com type: engine.rate_limited	Limite de 300 requisições por minuto por conta, somando REST e MCP. Respeite o Retry-After.
billing.editable_flows_plan_required em flow_apply/flow_edit	Sua conta não tem o plano com régua editável. A leitura da régua continua liberada.
As tools negotiation_* não aparecem	Sua conta não contratou a negociação assistida, ou a API key foi criada sem o escopo negotiation. Gere outra chave com o escopo depois de contratar.
Sem resposta nenhuma no curl	Rede: proxy ou firewall bloqueando motor.revtriever.com.

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_preview	Simula a próxima fatura (dry-run, zero efeitos)	leitura
subscription_change_gateway	Troca o gateway da assinatura — vale do próximo ciclo	escrita
subscription_cancel	Cancela, devolvendo o estado da fidelidade	escrita
customer_list	Clientes finais — com externalRef, acha o cliente pelo seu id	leitura
customer_get	Cliente com documento, telefone e endereço	leitura
customer_update	Corrige os dados do cliente — reflete no gateway que aceita	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 (transições e ciclo de vida), com filtros	leitura
integration_status	Secret vigente e webhook de alertas	leitura
pricing_test	Chamada mode: test assinada no seu endpoint	escrita

Régua de recuperação

O mesmo servidor traz a régua da empresa — o fluxo que age sobre a cobrança recusada. A leitura é livre; as duas tools de escrita exigem o plano com régua editável (sem ele voltam billing.editable_flows_plan_required). Para o passo a passo de montar e publicar, instale a skill revtriever-regua (veja o topo desta página).

Tool	Faz	Tipo
flow_context	Tudo que montar régua exige, numa chamada: o manual dos passos, cada régua como documento, o que o gateway executa, modelos e conexões	leitura
flow_manual	Como a régua funciona: cada tipo de passo, os campos que exige, as pegadinhas e a forma que a árvore precisa ter	leitura
flow_tree	A régua como está no rascunho, com o id real de cada passo — chame antes de flow_edit	leitura
flow_message_templates	Modelos de e-mail publicados e de WhatsApp aprovados que um passo pode citar em templateKey	leitura
flow_gateways	Conexões de gateway ativas e o que cada uma sabe fazer; é daqui que sai o connectionId para emitir por outro gateway	leitura
flow_apply	Publica um documento de régua como versão nova, tudo-ou-nada; régua já ligada passa a valer para os pagadores na hora	escrita
flow_edit	Edita o rascunho passo a passo, em lote e tudo-ou-nada; publicar e ligar continuam sendo ato humano no painel	escrita
flow_step_conversion	Quantos casos alcançaram cada passo na janela e quanto cada um recuperou — onde a régua perde gente	leitura
flow_stuck_cases	Casos parados: passo que já passou da hora e não rodou, com o valor preso	leitura

Os tipos de passo (espera, condição, e-mail, WhatsApp, Pix, boleto, formas de pagamento, retentar cartão, outro cartão, todos os cartões, tarefa humana, encerrar) e os campos de cada um vêm de flow_manual, sempre atualizados com o que o motor executa — não há lista paralela para decorar.

Negociação assistida

Quando a conta contrata a negociação assistida, o servidor traz também a política de negociação: o que o assistente pode ceder pelo WhatsApp para receber uma cobrança que falhou (formas, desconto máximo, parcelas, desistência em loja, como ele se apresenta). A política é de cada conexão de gateway. As tools só são registradas com o produto contratado e a API key criada com o escopo negotiation. Para o passo a passo, instale a skill revtriever-negociacao.

Tool	Faz	Tipo
negotiation_context	Tudo numa chamada: o manual, a política de cada conexão como está no rascunho, o que a conexão consegue, repetição, excedente e cota	leitura
negotiation_manual	As perguntas na ordem, as operações com exemplo, as regras e como o desconto acontece em cada gateway	leitura
negotiation_policy	A política de uma conexão: documento, o que falta responder, problemas, avisos e a prosa do que ficou combinado	leitura
negotiation_edit	Operações tipadas sobre o rascunho, em lote e tudo-ou-nada, validadas contra o que a conexão consegue	escrita
negotiation_simulate	Um turno do assistente contra o rascunho, fazendo o papel do pagador — nada é emitido nem enviado; consome uma simulação do mês	escrita
negotiation_publish	Publica o rascunho: sobe a versão e passa a valer para as conversas que abrirem daí em diante	escrita
negotiation_settings	Repetição por pagador e política de excedente, que são da empresa e valem para todas as políticas	escrita
negotiation_dashboard	Acordos liquidados no período, recuperado líquido da concessão e distribuição por faixa de desconto	leitura

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.