Skip to main content

MCP Tools

O servidor MCP da Pierre Finance oferece as seguintes ferramentas para acessar dados financeiros.

getAccounts

Obtém todas as contas (banco, cartão, investimentos, empréstimos). Útil para descobrir accountId e detalhes antes de usar outras ferramentas.

Retorna

Exemplos de Uso

getApiKeyInfo

Obtém informações sobre como gerar e usar chaves de API para Pierre Finance, incluindo lista de todas as ferramentas disponíveis.

Parâmetros

Nenhum

Retorna

Exemplos de Uso

getBalance

Saldo consolidado de contas bancárias do usuário.

Retorna

Exemplos de Uso

getBalanceByAccount

Saldo e detalhes de uma conta bancária específica por accountId.

Parâmetros

  • accountId (string, obrigatório)

Retorna

Exemplos de Uso

getTransactions

Transações financeiras com filtros por período, categoria e tipo de conta. Suporta dois formatos de resposta: ‘raw’ (padrão) para dados brutos, e ‘structured’ para dados organizados com agrupamentos e resumos. Inclui filtragem inteligente via linguagem natural e categorização automática.

Parâmetros

  • startDate (YYYY-MM-DD, opcional)
  • endDate (YYYY-MM-DD, opcional)
  • categories (string[], opcional)
  • minAmount (number, opcional)
  • maxAmount (number, opcional)
  • accountType (BANK | CREDIT | INVESTMENT | LOAN, opcional)
  • accountSubtype (CHECKING_ACCOUNT | SAVINGS_ACCOUNT | CREDIT_CARD | PAYMENT_ACCOUNT, opcional)
  • includeStatus (string[], opcional): lista de status de transações a incluir (POSTED, PENDING)
  • format (raw | structured, opcional) - Formato da resposta
  • clientMessage (string, opcional): mensagem em linguagem natural para filtragem inteligente usando LLM (ex: “mostre gastos com alimentação”, “transações acima de 100 reais”, “pagamentos para supermercados”)

Retorna (format=raw, padrão)

Retorna (format=structured)

Exemplos de Uso

getInstallments

Informações sobre compras parceladas e suas parcelas.

Parâmetros

  • startDate (YYYY-MM-DD, opcional)
  • endDate (YYYY-MM-DD, opcional)

Retorna

Exemplos de Uso

getBillSummary

Resumo da fatura atual do cartão de crédito. Retorna limite total, limite disponível, período corrente e valor aproximado da fatura (soma de transações DEBIT com status PENDING entre a última e a próxima data de fechamento).

Parâmetros

  • accountId (string, opcional): se informado, retorna apenas dessa conta
  • closingDay (number 1–31, opcional): dia de fechamento manual para cálculo quando usado com accountId
  • startDate (string ISO 8601, opcional): data de início do período para cálculo da fatura. Sobrescreve o cálculo automático baseado no closing day
  • endDate (string ISO 8601, opcional): data de fim do período para cálculo da fatura. Sobrescreve o cálculo automático baseado no closing day

Comportamento e Fallbacks

  • Se closingDay e accountId forem informados, usa o dia manual no cálculo
  • Se não houver data de fechamento cadastrada para o cartão solicitado, usa-se 7 dias antes do próximo vencimento como fechamento e informa essa suposição
  • Se não houver closingDay nem accountId, e houver somente um cartão de crédito sem fechamento, usa-se 7 dias antes do vencimento e avisa ausência de fechamento cadastrado
  • Se houver múltiplos cartões e nenhum possuir fechamento, retorna recomendação para cadastrar (sem calcular)

Avisos Importantes

  • Sempre avise que o valor é aproximado (transações podem não ter sido lançadas; bancos podem demorar a sincronizar)
  • Para faturas já fechadas (vencidas), use getBills em vez de getBillSummary

Exemplos de Uso

getBills

Obtém faturas de cartão de crédito já vencidas do usuário (somente faturas fechadas com dueDate no passado). Útil para entender obrigações em aberto e planejar pagamentos.

Parâmetros

  • accountId (string, opcional): ID da conta de cartão de crédito para filtrar. Use a ferramenta getAccounts para descobrir os accountId disponíveis. Se omitido, retorna faturas vencidas de todas as contas do usuário.

Comportamento

  • Retorna apenas faturas cujo dueDate seja menor ou igual à data atual.
  • As faturas são ordenadas por dueDate (mais recentes primeiro).

Retorno

Array de faturas com, no mínimo:
  • id (string)
  • accountId (string)
  • dueDate (string ISO 8601)
  • totalAmount (number)
  • totalAmountCurrencyCode (string)
  • minimumPaymentAmount (number | null)
  • allowsInstallments (boolean)

Exemplos de Uso

manageClosingDate

Gerencia a data de fechamento de faturas de cartões de crédito (definir/atualizar/desativar/remover e consultar). Recomendado para manter coerência entre data de fechamento percebida e o comportamento do provedor.

Operações e Parâmetros

  • LIST_ACCOUNTS
    • Parâmetros: nenhum
    • Retorno: lista de contas de cartão com indicadores se já possuem data configurada e, quando aplicável, closingDay, isActive, notes.
  • INSERT
    • Parâmetros obrigatórios: accountId (string), closingDay (number 1–31)
    • Parâmetros opcionais: isActive (boolean, padrão true), notes (string)
    • Validações: a conta deve pertencer ao usuário e ser do subtipo CREDIT_CARD.
  • UPDATE
    • Parâmetros obrigatórios: accountId (string)
    • Parâmetros opcionais: closingDay (number 1–31), isActive (boolean), notes (string)
    • Validações: deve existir uma data de fechamento para a conta e pertencer ao usuário.
  • DELETE
    • Parâmetros obrigatórios: closingDateId (string)
    • Validações: o registro deve pertencer ao usuário.
  • GET
    • Parâmetros opcionais: accountId (string)
    • Com accountId: retorna a configuração daquela conta (ou null se inexistente).
    • Sem accountId: retorna todas as configurações do usuário.

Observações

  • closingDay deve ser um inteiro de 1 a 31.
  • isActive indica se a configuração está em uso; útil para desativar temporariamente sem apagar.
  • Utilize LIST_ACCOUNTS antes de INSERT/UPDATE para guiar a escolha do accountId correto.

Exemplos de Uso

manualUpdate

Força uma sincronização manual dos dados financeiros.

Descrição

Executa uma sincronização manual de todos os dados financeiros conectados, buscando as informações mais recentes das instituições financeiras.

Parâmetros

Nenhum

Retorna

Uso Específico

Execute imediatamente quando:
  • O usuário pedir para “atualizar meus dados”
  • O usuário pedir para “sincronizar minhas contas”
  • O usuário mencionar que os dados parecem desatualizados
  • O usuário pedir sobre transações recentes que não aparecem
  • O usuário quiser garantir que tem as informações mais atuais
  • O usuário reportar problemas com dados incompletos ou desatualizados
NÃO peça confirmação - execute a ferramenta imediatamente quando qualquer uma dessas condições for atendida.

Exemplo de Uso

listSpendingLimits

Lista todos os alertas de gastos configurados com informações sobre gasto atual, percentual utilizado e quota disponível.

Parâmetros

  • includeInactive (boolean, opcional): se true, retorna também alertas inativos. Padrão: false

Retorna

Exemplos de Uso

createSpendingLimit

Cria um novo alerta de gastos para monitorar uma categoria específica. O usuário será notificado quando atingir 50%, 75% e 100% do limite configurado (ou apenas 100% se for recorrente).

Parâmetros

  • category (string, obrigatório): nome da categoria (ex: “Alimentação”, “Transporte”)
  • limitAmount (number, obrigatório): valor limite em BRL
  • period (string, obrigatório): período do alerta - daily, weekly, biweekly, monthly
  • isRecurring (boolean, opcional): se true, envia alertas toda vez que atingir o limite. Padrão: false
  • forceCreate (boolean, opcional): se true, pula avisos. Padrão: false

Comportamento

  • Se o usuário já excedeu o limite proposto no período atual, retorna aviso/recomendação
  • Após aviso, se usuário confirmar, use confirmSpendingLimit ao invés de criar novamente
  • Alertas padrão: 50%, 75% e 100% (uma vez por período)
  • Alertas recorrentes: apenas 100% (toda vez que atingir)

Retorna

Exemplos de Uso

confirmSpendingLimit

Confirma e cria um alerta de gastos após aviso/recomendação. Use esta ferramenta quando o usuário confirmar positivamente após receber um aviso de createSpendingLimit.

Parâmetros

  • category (string, obrigatório): nome da categoria
  • limitAmount (number, obrigatório): valor limite em BRL
  • period (string, obrigatório): período do alerta - daily, weekly, biweekly, monthly
  • isRecurring (boolean, opcional): se é alerta recorrente. Padrão: false
  • startNextPeriod (boolean, opcional): se true, inicia no próximo período. Padrão: true

Retorna

Exemplos de Uso

updateSpendingLimit

Atualiza um alerta de gastos existente.

Parâmetros

  • limitId (string, obrigatório): ID do alerta
  • limitAmount (number, opcional): novo valor limite em BRL
  • period (string, opcional): novo período - daily, weekly, biweekly, monthly
  • isActive (boolean, opcional): ativa ou desativa o alerta
  • isRecurring (boolean, opcional): define se é recorrente

Retorna

Exemplos de Uso

deleteSpendingLimit

Deleta permanentemente um alerta de gastos.

Parâmetros

  • limitId (string, obrigatório): ID do alerta a ser deletado

Retorna

Exemplos de Uso

getSpendingLimitTransactions

Obtém status detalhado de um alerta específico, incluindo gasto atual, transações e histórico de notificações.

Parâmetros

  • limitId (string, obrigatório): ID do alerta

Retorna

Exemplos de Uso

Casos de Uso Avançados

Análise de Gastos

Planejamento Financeiro

Análise de Crédito

Análise de Fluxo de Caixa

Análise de Parcelas

Gestão de Alertas de Gastos

Configuração de Ferramentas

Arquivo de Configuração MCP

Todas as ferramentas requerem autenticação válida e assinatura ativa na Pierre Finance.
Mantenha suas API keys seguras e nunca as compartilhe publicamente.

Autenticação

Você pode autenticar de duas formas ao chamar https://pierre.finance/mcp:
  • Header Authorization (recomendado):
  • Via URL:
Evite inserir esse endereço em navegadores/logs públicos.