Conectando o Rivo a ferramentas de IA e automação

O Rivo suporta o Model Context Protocol (MCP) — um padrão aberto que permite que ferramentas de inteligência artificial e automação conversem diretamente com seus dados financeiros, de forma segura e controlada.

Na prática, isso significa que você pode perguntar ao Claude:

"Quais contas vencem essa semana?" "Me dê um resumo financeiro de janeiro a março." "Crie uma conta a pagar de R$ 800 para o fornecedor X com vencimento em 30/04."

E ele vai buscar, interpretar e agir nos seus dados reais — sem você precisar abrir o sistema.

---

O que é MCP?

O Model Context Protocol é um protocolo criado pela Anthropic (empresa por trás do Claude) que padroniza a forma como modelos de linguagem se conectam a dados externos e ferramentas.

Antes do MCP, cada integração era manual e frágil. Com o MCP, existe um contrato único: o Rivo expõe suas funcionalidades como tools, e qualquer cliente compatível — Claude Code, n8n, Make, Zapier e outros — pode usá-las da mesma forma.

---

Passo 1 — Gere sua chave de API

Acesse Configurações → Integrações dentro do Rivo.

1. Digite um nome para identificar a chave — por exemplo, Claude Code pessoal ou n8n produção
2. Clique em Gerar chave
3. Copie a chave imediatamente — ela não será exibida novamente

A chave gerada tem o formato rivo_xxxxxxxxxxxxxxxx. Trate-a como uma senha: não compartilhe publicamente e não coloque em repositórios de código.

Cada chave está vinculada à sua empresa. Se alguém usar essa chave, ela só terá acesso aos dados da empresa onde foi gerada.

---

Passo 2 — Conectar ao Claude Code

O Claude Code é a interface de linha de comando do Claude, e é o cliente MCP mais direto de usar.

Instalação do Claude Code

Se ainda não tiver, instale via npm:

npm install -g @anthropic-ai/claude-code

Registrar o Rivo como servidor MCP

No terminal, rode o comando abaixo substituindo SUA_CHAVE pela chave gerada no passo anterior:

claude mcp add rivo -- npx -y mcp-remote https://app.rivo.business/api/mcp --header "x-api-key:SUA_CHAVE"

Em ambiente local (desenvolvimento): use http://localhost:3000/api/mcp no lugar de https://app.rivo.business/api/mcp.

Confirmar o registro

claude mcp list

Você deve ver rivo na lista de servidores registrados.

Reiniciar o Claude Code

Feche e abra novamente o Claude Code. As tools do Rivo estarão disponíveis automaticamente.

Testando

Na conversa com o Claude, escreva normalmente:

"Mostre as contas a pagar pendentes"

O Claude vai usar a tool buscar_contas_pagar automaticamente e trazer os dados.

---

Passo 3 — Conectar ao n8n

O n8n é uma ferramenta de automação no-code/low-code que permite criar workflows sem escrever código.

Configuração no n8n

No seu workflow do n8n, adicione um node HTTP Request com as seguintes configurações:

Exemplo: listar tools disponíveis

No Body do request, cole:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Exemplo: chamar uma tool

Para buscar o resumo financeiro do mês:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "resumo_financeiro",
    "arguments": {
      "data_inicio": "2025-01-01",
      "data_fim": "2025-01-31"
    }
  }
}

Automação prática com n8n

Um exemplo de workflow útil:

1. Trigger: Todo domingo às 18h
2. Node 1 — HTTP Request: Chama resumo_financeiro com o período da semana
3. Node 2 — Gmail / Slack: Envia o resumo formatado para o seu e-mail ou canal

---

Tools disponíveis

O Rivo expõe as seguintes tools via MCP:

resumo_financeiro

Retorna métricas do período: saldo bancário, receitas, despesas, resultado e projeção de caixa para 30 dias.

Parâmetros:

• data_inicio — Data inicial no formato YYYY-MM-DD
• data_fim — Data final no formato YYYY-MM-DD

---

buscar_transacoes

Lista transações da empresa com filtros opcionais.

Parâmetros:

• status — pending, reconciled ou all
• tipo — income, expense ou all
• data_inicio / data_fim — Intervalo de datas
• limite — Número máximo de registros (padrão: 50)

---

buscar_contas_pagar

Lista contas a pagar com filtros opcionais.

Parâmetros:

• status — pending, paid, overdue ou all
• vencimento_ate — Retorna apenas contas com vencimento até esta data
• limite — Número máximo de registros (padrão: 30)

---

criar_conta_pagar

Cria uma nova conta a pagar.

Parâmetros obrigatórios:

• descricao — Descrição da despesa
• valor — Valor em reais
• vencimento — Data de vencimento no formato YYYY-MM-DD

Parâmetros opcionais:

• fornecedor — Nome do fornecedor
• conta_contabil_id — ID da conta no plano de contas

---

buscar_contas_receber

Lista contas a receber com filtros opcionais.

Parâmetros:

• status — pending, received, overdue ou all
• vencimento_ate — Retorna apenas contas com vencimento até esta data
• limite — Número máximo de registros (padrão: 30)

---

criar_conta_receber

Cria uma nova conta a receber.

Parâmetros obrigatórios:

• descricao — Descrição da receita
• valor — Valor em reais
• vencimento — Data de vencimento no formato YYYY-MM-DD

Parâmetros opcionais:

• cliente — Nome do cliente
• conta_contabil_id — ID da conta no plano de contas

---

Segurança

• Cada chave está vinculada a uma empresa específica — não há acesso cruzado entre empresas
• Você pode revogar qualquer chave a qualquer momento em Configurações → Integrações
• Recomendamos criar uma chave separada para cada ferramenta (uma para Claude, outra para n8n, etc)
• Chaves não utilizadas devem ser revogadas

Nunca compartilhe sua chave publicamente. Se suspeitar de uso indevido, revogue e gere uma nova imediatamente.

---

Solução de problemas

Erro 401 — Unauthorized A chave não foi enviada no header. Verifique se o header x-api-key está presente na requisição.

Erro 403 — Forbidden A chave está incorreta ou foi revogada. Gere uma nova chave em Configurações → Integrações.

Erro 500 — Internal error Verifique se o servidor do Rivo está no ar. Se o problema persistir, entre em contato com o suporte.

Claude não encontra as tools Reinicie o Claude Code após registrar o servidor MCP. Use claude mcp list para confirmar o registro.