> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pierre.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> Ferramentas disponíveis no servidor MCP da Pierre Finance

# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:
1. Usuário: "Crie um limite de R$ 10 diário para transporte"
2. createSpendingLimit retorna: "Você já gastou R$ 9.27... Recomendo criar para o próximo dia. Confirma?"
3. Usuário: "Sim" / "Confirmo" / "Pode ser"
4. 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:
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"
```

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

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

<Note>
  Todas as ferramentas requerem autenticação válida e assinatura ativa na Pierre Finance.
</Note>

<Warning>
  Mantenha suas API keys seguras e nunca as compartilhe publicamente.
</Warning>

## Autenticação

Você pode autenticar de duas formas ao chamar `https://pierre.finance/mcp`:

* Header Authorization (recomendado):

```bash theme={null}
Authorization: Bearer sk-your-api-key-here
```

* Via URL:

```bash theme={null}
https://pierre.finance/mcp?apiKey=sk-your-api-key-here
```

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