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

{
  "success": true,
  "data": [
    {
      "accountId": "acc_123456789",
      "providerCode": "NUBANK",
      "accountName": "Conta Corrente",
      "accountType": "BANK",
      "accountSubtype": "CHECKING_ACCOUNT",
      "accountBalance": 1500.50,
      "accountCurrencyCode": "BRL",
      "accountMarketingName": "Nubank Conta"
    }
  ],
  "count": 1,
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Liste minhas contas financeiras"
"Quais cartões de crédito eu tenho conectados?"

getBalance

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

Retorna

{
  "success": true,
  "data": {
    "total_balance": 2500.75,
    "accounts": [
      {
        "name": "Conta Corrente",
        "balance": 1500.50,
        "account_type": "BANK",
        "account_subtype": "CHECKING_ACCOUNT"
      },
      {
        "name": "Conta Poupança",
        "balance": 1000.25,
        "account_type": "BANK",
        "account_subtype": "SAVINGS_ACCOUNT"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Qual é o meu saldo total em contas bancárias?"

getBalanceByAccount

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

Parâmetros

accountId (string, obrigatório)

Retorna

{
  "success": true,
  "data": {
    "name": "Conta Corrente",
    "balance": 1500.50,
    "account_type": "BANK",
    "account_subtype": "CHECKING_ACCOUNT"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Qual é o saldo da minha conta corrente?"

getTransactions

Transações financeiras com filtros por período, categoria e tipo de conta.

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)

Retorna

{
  "success": true,
  "data": [
    {
      "id": "txn_123456789",
      "description": "Pagamento de conta",
      "category": "Contas",
      "currency_code": "BRL",
      "amount": -150.00,
      "balance": 1350.50,
      "date": "2024-01-15",
      "type": "DEBIT",
      "status": "POSTED",
      "account_name": "Conta Corrente",
      "account_type": "BANK",
      "account_subtype": "CHECKING_ACCOUNT"
    }
  ],
  "count": 1,
  "filters": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Analise minhas transações do último mês e identifique os maiores gastos"

getInstallments

Informações sobre compras parceladas e suas parcelas.

Parâmetros

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

Retorna

{
  "success": true,
  "data": {
    "summary": {
      "totalAmount": 5000.00,
      "totalInstallments": 12,
      "totalPurchases": 3,
      "installmentDistribution": [
        {
          "totalInstallments": 12,
          "count": 1,
          "totalAmount": 3000.00
        }
      ]
    },
    "purchases": [
      {
        "purchaseDate": "2024-01-10",
        "totalAmount": 3000.00,
        "installments": [
          {
            "description": "Compra parcelada",
            "amount": 250.00,
            "installmentNumber": 1,
            "totalInstallments": 12,
            "dueDate": "2024-02-10",
            "category": "Compras",
            "status": "POSTED"
          }
        ]
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Liste todas as minhas compras parceladas e quando terminam de pagar"

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

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

"Quanto está minha fatura atual do cartão acc_abc?"
"Use o dia 12 como fechamento e calcule minha fatura do acc_abc"
"Qual meu limite disponível e o valor aproximado da fatura no mês atual?"

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

"Liste minhas faturas de cartão vencidas"
"Quais faturas vencidas tenho no cartão com id acc_abc?"

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

"Liste minhas contas de cartão e mostre quais já têm data de fechamento configurada"
"Defina a data de fechamento do cartão acc_abc para dia 10 e deixe ativo"
"Atualize a data de fechamento do cartão acc_abc para dia 12 e adicione a nota 'sincronizado com banco'"
"Remova a configuração de data de fechamento com id cld_123"
"Mostre a minha configuração de fechamento para o cartão acc_abc"

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

{
  "success": true,
  "message": "Manual sync initiated",
  "connectedAccounts": 3,
  "note": "The sync process will run in the background. Check your dashboard for updates.",
  "timestamp": "2024-01-15T10:30:00Z"
}

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

"Atualize meus dados financeiros para ter as informações mais recentes"

Casos de Uso Avançados

Análise de Gastos

"Analise meus gastos dos últimos 3 meses e crie um relatório com:
1. Categorias com maior despesa
2. Padrões de gasto por dia da semana
3. Sugestões para economia"

Planejamento Financeiro

"Com base nos meus dados financeiros, sugira um plano de economia considerando:
- Minhas receitas mensais
- Gastos fixos e variáveis
- Metas de economia
- Investimentos atuais"

Análise de Crédito

"Analise meu uso de cartão de crédito e sugira:
1. Estratégias para pagar dívidas
2. Melhores práticas de uso
3. Oportunidades de economia"

Análise de Fluxo de Caixa

"Analise meu fluxo de caixa dos últimos 6 meses e identifique:
- Padrões sazonais
- Picos de gasto
- Oportunidades de otimização
- Projeções para os próximos meses"

Análise de Parcelas

"Liste todas as minhas compras parceladas e analise:
- Cronograma de pagamentos
- Impacto no fluxo de caixa
- Estratégias de antecipação
- Oportunidades de economia"

Configuração de Ferramentas

Arquivo de Configuração MCP

{
  "mcpServers": {
    "Pierre Finance": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://pierre.finance/mcp",
        "--header",
        "Authorization:${TOKEN}"
      ],
      "env": {
        "TOKEN": "Bearer sk-your-api-key-here"
      }
    }
  }
}

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):

Authorization: Bearer sk-your-api-key-here

Via URL:

https://pierre.finance/mcp?apiKey=sk-your-api-key-here

Evite inserir esse endereço em navegadores/logs públicos.

REST API

MCP Server

​MCP Tools

​getAccounts

​Retorna

​Exemplos de Uso

​getBalance

​Retorna

​Exemplos de Uso

​getBalanceByAccount

​Parâmetros

​Retorna

​Exemplos de Uso

​getTransactions

​Parâmetros

​Retorna

​Exemplos de Uso

​getInstallments

​Parâmetros

​Retorna

​Exemplos de Uso

​getBillSummary

​Parâmetros

​Comportamento e Fallbacks

​Avisos Importantes

​Exemplos de Uso

​getBills

​Parâmetros

​Comportamento

​Retorno

​Exemplos de Uso

​manageClosingDate

​Operações e Parâmetros

​Observações

​Exemplos de Uso

​manualUpdate

​Descrição

​Parâmetros

​Retorna

​Uso Específico

​Exemplo 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

​Configuração de Ferramentas

​Arquivo de Configuração MCP

​Autenticação

MCP Tools

getAccounts

Retorna

Exemplos de Uso

getBalance

Retorna

Exemplos de Uso

getBalanceByAccount

Parâmetros

Retorna

Exemplos de Uso

getTransactions

Parâmetros

Retorna

Exemplos de Uso

getInstallments

Parâmetros

Retorna

Exemplos de Uso

getBillSummary

Parâmetros

Comportamento e Fallbacks

Avisos Importantes

Exemplos de Uso

getBills

Parâmetros

Comportamento

Retorno

Exemplos de Uso

manageClosingDate

Operações e Parâmetros

Observações

Exemplos de Uso

manualUpdate

Descrição

Parâmetros

Retorna

Uso Específico

Exemplo 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

Configuração de Ferramentas

Arquivo de Configuração MCP

Autenticação