# Poupa AI — how to use (mcp.ai)

Finanças pessoais do Poupa AI. Leia saldo agrupado por banco/categoria/cartão/mês, transações por intervalo e palavra-chave, lista de bancos, cartões e categorias; registre, atualize ou apague transações (uma a uma ou em lote) e movimente entre suas contas. Autentique com a sua API key do Poupa AI.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_poupa?ms=1781685780000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `poupa_add_transaction`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/poupa`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/poupa/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/poupa/add/transaction` — Cria uma transação. value e date são obrigatórios; demais campos opcionais. Para parcelar, use installments; para recorrer, use expense_recurrency (dias) OU recurrency_array_dates (lista de datas).
  - body: { value: number, date: string, description?: string, category?: string, payment_bank?: string, card_name?: string, installments?: number, expense_recurrency?: number, recurrency_array_dates?: string[] }
- `POST https://api.mcp.ai/api/poupa/add/transactions` — Cria várias transações de uma vez (bulk). transactions[] é obrigatório; cada item segue o mesmo shape de poupa_add_transaction.
  - body: { transactions: object[] }
- `POST https://api.mcp.ai/api/poupa/banks` — Lista os bancos/contas do usuário.
- `POST https://api.mcp.ai/api/poupa/cards` — Lista os cartões de crédito do usuário.
- `POST https://api.mcp.ai/api/poupa/category` — Lista as categorias do usuário.
- `POST https://api.mcp.ai/api/poupa/defaults` — Categorias e métodos de pagamento padrão do usuário.
- `POST https://api.mcp.ai/api/poupa/delete/transactions/by/filter` — Deleta transações por filtro. O filtro precisa ser não vazio (a tool se recusa a deletar tudo). Aceita ids, intervalo de datas, descrição, categoria, etc.
  - body: { ids?: string[], start_date?: string, end_date?: string, description?: string, category?: string }
- `POST https://api.mcp.ai/api/poupa/get/balance` — Saldo do usuário, agrupado por banco, categoria, método de pagamento, cartão, tipo (entrada/saída) e mês. start_date/end_date (YYYY-MM-DD) limitam a janela; sem datas, traz tudo.
  - body: { start_date?: string, end_date?: string }
- `POST https://api.mcp.ai/api/poupa/memories` — Memórias/notas do usuário gravadas no Poupa AI.
- `POST https://api.mcp.ai/api/poupa/preferences` — Preferências do usuário (idioma, moeda, etc.).
- `POST https://api.mcp.ai/api/poupa/retrieve/transactions` — Lista transações no intervalo (YYYY-MM-DD), opcionalmente filtradas por palavras-chave (match parcial case-insensitive na descrição), cartão e/ou banco/pagador.
  - body: { start_date?: string, end_date?: string, keywords?: string[], card_name?: string, payment_bank?: string }
- `POST https://api.mcp.ai/api/poupa/transfer/between/banks` — Registra uma transferência entre dois bancos/contas do PRÓPRIO usuário (movimento contábil — não executa transferência bancária real). value é o valor; date opcional (default = hoje).
  - body: { from_bank: string, to_bank: string, value: number, date?: string }
- `POST https://api.mcp.ai/api/poupa/update/transactions` — Atualiza uma ou mais transações existentes. Informe os ids alvo no filtro e os campos a alterar (passthrough).
  - body: { ids?: string[], filter?: object, changes?: object }

## Example prompts
- "Qual o saldo deste mês por categoria?"
- "Lista todas as transações com a palavra Uber nos últimos 30 dias"
- "Registra uma despesa de R$150 hoje no cartão Nubank em alimentação"

## More
- Page: https://mcp.ai/poupa
- Agent spec (llms.txt): https://mcp.ai/poupa/llms.txt
- Postman collection: https://mcp.ai/poupa/postman.json