Planilha de gastos você já tentou. O problema nunca foi o layout — foi ter que alimentar na mão. Com o Banco MCP, os dados do banco chegam prontos por API; o que falta é uma tela em cima deles.
Neste guia você constrói esse app no Lovable, do zero, com prompts. O resultado: um painel que mostra entradas e saídas, evolução mês a mês, maiores gastos e faturas de cartão — lendo direto das suas contas.
Escopo: este guia monta um gestor pessoal — o seu dinheiro, as suas contas, conectadas por você em
app.mcp.ai. Um produto multiusuário, onde cada cliente conecta o próprio banco, usa o fluxo de conexão embarcada do Banco MCP e é outro assunto — não tente adaptar este guia pra isso.
Passo 0 — Preparar o acesso aos dados
Antes de escrever uma linha:
- Em app.mcp.ai, instale o Banco MCP e conecte suas contas e cartões.
- Em Configurações → API keys, crie uma Workspace API key (
sk_live_…). - Confira que os dados vêm. Um
curlresolve:
curl -X POST https://api.mcp.ai/api/openfinance/accounts/list \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{}'A resposta tem o formato { "ok": true, "tool": "...", "result": { ... } }.
Guarde os account_id que aparecerem — são eles que o app vai consultar.
🔒 A key nunca vai pro navegador. sk_live_… dá acesso total ao seu
workspace. No Lovable, ela vive como secret do backend e é o backend que fala
com o MCP.AI. É o primeiro requisito da arquitetura, não um detalhe de segurança
pra depois.
Passo 1 — Definir a arquitetura
Abra um projeto novo no Lovable e comece pelo desenho, não pela tela:
Quero construir um gestor financeiro pessoal.
Fonte de dados: a REST API do Banco MCP (MCP.AI), em https://api.mcp.ai/api/openfinance.
Autenticação: header "Authorization: Bearer <WORKSPACE_API_KEY>".
Todos os endpoints são POST e recebem JSON.
Requisito inegociável de arquitetura: a WORKSPACE_API_KEY NUNCA pode aparecer no
frontend. Toda chamada ao MCP.AI passa por uma edge function no backend, que lê
a chave de um secret do servidor.
Antes de gerar código, me proponha:
1. A estrutura de pastas do projeto
2. Quais tabelas eu preciso pra guardar contas, transações e faturas
3. Quais edge functions vou precisar
4. Como faço o sync (quando busco dados novos e o que fica em cache)
Só o plano por enquanto. Não escreva código ainda.Ler o plano antes vale mais do que parece: é onde você corrige "ele entendeu errado" por R$ 0 em vez de por três telas refeitas.
Passo 2 — O schema
Com o plano aprovado, peça o banco de dados:
Aprovado. Agora crie o schema no Supabase com estas tabelas:
- accounts: id (uuid do Banco MCP), bank, name, type (BANK ou CREDIT), number,
balance, currency, item_id, updated_at
- transactions: id (uuid do Banco MCP), account_id (FK), date, description,
merchant_name, amount, type (entrada/saida), category, created_at
- credit_card_bills: id, account_id (FK), due_date, close_date, total_amount,
paid, created_at
- sync_log: id, ran_at, accounts_synced, transactions_synced, error
Regras:
- transactions.id e accounts.id são os ids que vêm do Banco MCP — use como
chave primária pra o sync ser idempotente (upsert, nunca duplicar)
- índice em transactions(account_id, date desc)
- RLS ligado em todas as tabelasO ponto que evita a dor de cabeça número um: usar o id do Banco MCP como chave primária. Sem isso, cada sync duplica o extrato inteiro.
Passo 3 — A edge function que fala com o MCP.AI
Aqui é onde a arquitetura vira código:
Crie uma edge function chamada "mcp-proxy" no Supabase.
O que ela faz:
- Recebe { tool, args } do frontend
- Valida `tool` contra uma allowlist (só leitura):
accounts/list, accounts/balance, transactions/list, transactions/by-item,
credit-card-bills/list, categories/list
- Chama POST https://api.mcp.ai/api/openfinance/<tool> com o body `args`
- Header: Authorization: Bearer ${MCP_AI_API_KEY} (secret do Supabase)
- Devolve o campo `result` da resposta pro frontend
- Se a resposta vier com `error`, propaga { code, message } com o status HTTP
original
Importante:
- A API do Banco MCP limita a 2 requisições por segundo (burst de 10). Implemente
uma fila com no máximo 2 chamadas concorrentes e retry com backoff no 429.
- Nunca logue o valor de MCP_AI_API_KEY.
Depois me diga como eu configuro o secret MCP_AI_API_KEY.A allowlist não é paranoia: sem ela, qualquer um que abra o DevTools consegue usar a sua edge function como proxy livre pra API do seu workspace.
Passo 4 — O sync
Crie uma edge function "sync" que:
1. Chama accounts/list e faz upsert em `accounts`
2. Para cada conta, chama transactions/list com { account_id, from, to } —
`from` = a data da transação mais recente que eu já tenho daquela conta
(ou 90 dias atrás, se a tabela estiver vazia) e `to` = hoje
3. Faz upsert em `transactions` (chave = id do Banco MCP)
4. Para contas do tipo CREDIT, chama credit-card-bills/list e faz upsert em
`credit_card_bills`
5. Grava uma linha em `sync_log` com o resultado
Adicione um botão "Sincronizar agora" no app que dispara essa função e mostra
o progresso.O from incremental é o que mantém isso barato: o primeiro sync puxa 90 dias, os
seguintes puxam só o que é novo.
Passo 5 — As telas
Agora sim, a parte visível:
Construa o dashboard com estas seções, lendo do Supabase (não da API direto):
1. Topo: saldo somado das contas BANK + total de fatura em aberto dos cartões
2. Cards do mês atual: total de entradas, total de saídas, saldo do mês
3. Gráfico de barras: entradas vs saídas dos últimos 12 meses
4. Gráfico de pizza: gastos do mês por categoria
5. Lista dos 10 maiores gastos do mês, com estabelecimento e data
6. Tabela de transações com filtro por conta, período e busca por descrição
Design: claro, tipografia legível, números tabulares alinhados à direita.
Valores em BRL formatados como R$ 1.234,56. Saídas em vermelho, entradas em verde.
Deve funcionar bem no celular.Repare que as telas leem do Supabase, não do MCP.AI. Isso é de propósito: o app abre instantâneo, funciona offline e não gasta chamada de API a cada navegação. O MCP.AI é a fonte; o Supabase é a cópia local.
Passo 6 — Refino
Com o básico rodando, itere. Alguns prompts que valem:
Adicione uma tela de "Recorrentes": detecte cobranças que se repetem no mesmo
estabelecimento em 3+ meses com valor variando menos de 10%, e mostre o custo
anual projetado de cada uma.Adicione um filtro "Só cartão de crédito" e, na tela de faturas, mostre a fatura
aberta com as transações que caem nela, agrupadas por categoria.Agende a edge function "sync" pra rodar todo dia às 6h da manhã via pg_cron.
Se falhar, grave o erro em sync_log e me mostre um aviso no topo do dashboard.Antes de publicar
Três checagens que separam protótipo de app que você usa de verdade:
- A key vazou? Abra o DevTools → Network e navegue pelo app inteiro. Nenhuma
requisição pode conter
sk_live_. Se contiver, alguma chamada está indo direto do frontend pro MCP.AI — mande o Lovable roteá-la pela edge function. - RLS está ligado? Com o app publicado, um projeto Supabase sem RLS deixa o seu extrato bancário acessível por URL. Confirme tabela por tabela.
- O app é seu. Não publique link público de um painel com o seu extrato, nem que "ninguém vai adivinhar a URL". Deixe atrás de login.
De onde vêm os dados
Todos os endpoints que este guia usa são o espelho REST das tools do Banco MCP — o mesmo dado que o seu agente lê no chat:
| Endpoint | O que devolve |
|---|---|
POST /api/openfinance/accounts/list | Contas e cartões conectados, com saldo |
POST /api/openfinance/transactions/list | Transações de uma conta (aceita from/to) |
POST /api/openfinance/transactions/by-item | Análise consolidada de uma conexão inteira |
POST /api/openfinance/credit-card-bills/list | Faturas do cartão, incluindo a aberta |
POST /api/openfinance/categories/list | A taxonomia de categorias |
A lista completa está na aba API do Banco MCP no app.mcp.ai.