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?"

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

{
  "message": "To use Pierre Finance API tools, you need to generate an API key.",
  "steps": [
    "1. Visit https://pierre.finance/api-key",
    "2. Sign in to your account",
    "3. Create a new API key or use the default one",
    "4. Copy the API key (starts with \"sk-\")",
    "5. Use this API key in your requests to other tools"
  ],
  "example": {
    "tool": "get-accounts",
    "endpoint": "GET /tools/api/get-accounts",
    "headers": {
      "Authorization": "Bearer sk-your-api-key-here",
      "Content-Type": "application/json"
    }
  },
  "note": "API keys are required for all financial data access. Keep your API key secure and never share it publicly.",
  "availableTools": [
    {
      "name": "get-accounts",
      "endpoint": "/tools/api/get-accounts",
      "method": "GET",
      "description": "Get all financial accounts for the user",
      "requiresAuth": true,
      "category": "Accounts"
    }
  ]
}

Exemplos de Uso

"Como gero uma API key para usar as ferramentas da Pierre?"
"Quais ferramentas estão disponíveis na API?"
"Preciso de ajuda para configurar minha chave de API"

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

{
  "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"
}

Retorna (format=structured)

{
  "success": true,
  "data": {
    "transactions": {
      "accounts": {
        "Nubank": {
          "credit_cards": {
            "Nubank Mastercard": {
              "payments": [
                {
                  "date": "2024-01-15",
                  "category": "Pagamento de Fatura",
                  "amount": 1523.75,
                  "currency": "BRL",
                  "transaction_type": "credit_card",
                  "transaction_subtype": "payment"
                }
              ],
              "purchases": [
                {
                  "date": "2024-01-10",
                  "category": "Alimentação",
                  "amount": 125.50,
                  "currency": "BRL",
                  "merchant": "Supermercado Exemplo",
                  "transaction_type": "credit_card",
                  "transaction_subtype": "purchase"
                }
              ],
              "total_payments": 1523.75,
              "total_purchases": 125.50
            }
          },
          "total_credit_card_payments": 1523.75,
          "total_credit_card_purchases": 125.50
        }
      }
    },
    "summary": {
      "total_spent": 625.50,
      "total_received": 5000.00,
      "total_bank_transfer": 500.00,
      "period": "3 meses",
      "by_category": {
        "Alimentação": {
          "total": 125.50,
          "count": 1
        }
      },
      "top_transactions": [
        {
          "date": "2024-01-05",
          "category": "Salário",
          "amount": 5000.00,
          "currency": "BRL",
          "transaction_type": "received"
        }
      ]
    }
  },
  "count": 4,
  "timestamp": "2024-01-15T10:30:00Z"
}

Exemplos de Uso

"Analise minhas transações do último mês e identifique os maiores gastos"
"Use o formato estruturado para criar um resumo dos meus gastos por categoria"
"Mostre minhas transações organizadas por conta com resumos automáticos"
"Mostre apenas transações de alimentação acima de 50 reais usando filtragem inteligente"
"Filtre transações pendentes dos últimos 30 dias"
"Use clientMessage para encontrar gastos com supermercados e farmácias"

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

"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"

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

{
  "success": true,
  "data": [
    {
      "id": "limit_123",
      "category": "Alimentação",
      "limitAmount": 1000.00,
      "period": "monthly",
      "isActive": true,
      "isRecurring": true,
      "currentSpending": 450.75,
      "remainingAmount": 549.25,
      "percentageUsed": 45.08,
      "status": "ok"
    }
  ],
  "count": 1,
  "quota": {
    "subscriptionType": "pro",
    "currentCount": 1,
    "limit": 10,
    "canCreate": true,
    "remaining": 9
  }
}

Exemplos de Uso

"Liste meus alertas de gastos"
"Quais limites de gastos eu tenho configurados?"
"Mostre todos os alertas incluindo os inativos"

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

{
  "success": true,
  "data": {
    "id": "limit_123",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly",
    "isActive": true,
    "isRecurring": false
  },
  "message": "Spending limit created successfully for Alimentação"
}

Exemplos de Uso

"Crie um limite de R$ 1000 por mês para alimentação"
"Quero um alerta recorrente de R$ 20 por mês para Netflix"
"Configure um limite diário de R$ 50 para transporte"

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

{
  "success": true,
  "message": "✅ Limite RECORRENTE de R$ 1000.00 criado para \"Alimentação\" (mensal) (começando no próximo mês)!...",
  "limit": {
    "id": "limit_123",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly",
    "isRecurring": true,
    "periodStart": "2024-12-01T00:00:00.000Z"
  }
}

Exemplos de Uso

Fluxo típico:
Usuário: "Crie um limite de R$ 10 diário para transporte"
createSpendingLimit retorna: "Você já gastou R$ 9.27... Recomendo criar para o próximo dia. Confirma?"
Usuário: "Sim" / "Confirmo" / "Pode ser"
Use confirmSpendingLimit automaticamente

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

{
  "success": true,
  "data": {
    "id": "limit_123",
    "category": "Alimentação",
    "limitAmount": 1200.00,
    "period": "monthly",
    "isActive": true
  },
  "message": "Spending limit updated successfully"
}

Exemplos de Uso

"Aumente o limite de alimentação para R$ 1200"
"Desative o alerta de transporte"
"Mude o período do limite de alimentação para semanal"

deleteSpendingLimit

Deleta permanentemente um alerta de gastos.

Parâmetros

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

Retorna

{
  "success": true,
  "message": "Spending limit for \"Alimentação\" deleted successfully",
  "deletedLimit": {
    "id": "limit_123",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly"
  }
}

Exemplos de Uso

"Delete o alerta de alimentação"
"Remova o limite de gastos de transporte"

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

{
  "success": true,
  "data": {
    "limit": {
      "id": "limit_123",
      "category": "Alimentação",
      "limitAmount": 1000.00,
      "period": "monthly",
      "periodText": "neste mês",
      "isActive": true
    },
    "spending": {
      "currentSpent": 450.75,
      "percentage": 45.1,
      "remaining": 549.25,
      "transactionCount": 12
    },
    "status": {
      "level": "ok",
      "nextAlert": "50%",
      "alerts": {
        "alertHistory": []
      }
    }
  }
}

Exemplos de Uso

"Como está meu limite de alimentação?"
"Quanto já gastei do meu limite de transporte este mês?"
"Mostre detalhes do alerta de alimentação"

Casos de Uso Avançados

Análise de Gastos

"Analise meus gastos dos últimos 3 meses e crie um relatório com:
Categorias com maior despesa
Padrões de gasto por dia da semana
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:
Estratégias para pagar dívidas
Melhores práticas de uso
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"

Gestão de Alertas de Gastos

"Crie limites de gastos inteligentes baseados no meu histórico:
- Analise meu padrão de gastos dos últimos 3 meses
- Sugira limites realistas por categoria
- Configure alertas que me ajudem a economizar sem comprometer meu estilo de vida"

"Monitore meus gastos recorrentes:
- Liste todas as assinaturas e serviços recorrentes
- Crie alertas para cada categoria de gasto recorrente
- Me notifique quando algum gasto recorrente aumentar"

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.

Getting Started

Accounts & Balance

Transactions

Credit Cards

Spending Limits

Payment Reminders

Analytics

Memories

Open Finance

Synchronization

MCP Server

​MCP Tools

​getAccounts

​Retorna

​Exemplos de Uso

​getApiKeyInfo

​Parâmetros

​Retorna

​Exemplos de Uso

​getBalance

​Retorna

​Exemplos de Uso

​getBalanceByAccount

​Parâmetros

​Retorna

​Exemplos de Uso

​getTransactions

​Parâmetros

​Retorna (format=raw, padrão)

​Retorna (format=structured)

​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

​listSpendingLimits

​Parâmetros

​Retorna

​Exemplos de Uso

​createSpendingLimit

​Parâmetros

​Comportamento

​Retorna

​Exemplos de Uso

​confirmSpendingLimit

​Parâmetros

​Retorna

​Exemplos de Uso

​updateSpendingLimit

​Parâmetros

​Retorna

​Exemplos de Uso

​deleteSpendingLimit

​Parâmetros

​Retorna

​Exemplos de Uso

​getSpendingLimitTransactions

​Parâmetros

​Retorna

​Exemplos de Uso

MCP Tools

getAccounts

Retorna

Exemplos de Uso

getApiKeyInfo

Parâmetros

Retorna

Exemplos de Uso

getBalance

Retorna

Exemplos de Uso

getBalanceByAccount

Parâmetros

Retorna

Exemplos de Uso

getTransactions

Parâmetros

Retorna (format=raw, padrão)

Retorna (format=structured)

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

listSpendingLimits

Parâmetros

Retorna

Exemplos de Uso

createSpendingLimit

Parâmetros

Comportamento

Retorna

Exemplos de Uso

confirmSpendingLimit

Parâmetros

Retorna

Exemplos de Uso

updateSpendingLimit

Parâmetros

Retorna

Exemplos de Uso

deleteSpendingLimit

Parâmetros

Retorna

Exemplos de Uso

getSpendingLimitTransactions

Parâmetros

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

Autenticação