# Organizze — how to use (mcp.ai)

Your Organizze finances in natural language: consolidated balances, monthly overview, transaction search, credit card invoices, recurring bills, budgets, reports by category and tag, cash flow forecast and Open Finance status. Connect your account in one click, no key or token. On the Organizze screen, uncheck "Permitir alterações" if you want read-only access.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_organizze?ms=1788507420000`
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. `organizze_add_transactions_tags`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/organizze`
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/organizze/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/organizze/add/transactions/tags` — Adiciona tags a VÁRIAS transações em uma chamada (acumula sobre as existentes; máx. 200). Cada item: transaction_id ou transaction_uuid + tags (string com vírgulas ou lista).
  - body: { items: object[] }
- `POST https://api.mcp.ai/api/organizze/clone/budgets` — Clona os orçamentos do mês anterior para o mês de destino (não sobrescreve um mês que já tenha orçamentos). Padrão: mês atual.
  - body: { month?: integer, year?: integer }
- `POST https://api.mcp.ai/api/organizze/create/account` — Cria uma conta bancária manual.
  - body: { name: string, institution_id?: string, initial_balance?: number, description?: string }
- `POST https://api.mcp.ai/api/organizze/create/budget` — Cria um limite de gastos (orçamento) para uma categoria. Padrão: despesa; use activity_type 'earning' para meta de receita. Prefira o NOME da categoria.
  - body: { category: string, amount: number, activity_type?: string, month?: integer, year?: integer }
- `POST https://api.mcp.ai/api/organizze/create/category` — Cria uma categoria de despesa ou receita (raiz ou subcategoria via parent_id).
  - body: { name: string, kind: string, group_id?: string, color?: string, parent_id?: integer }
- `POST https://api.mcp.ai/api/organizze/create/credit/card` — Cria um cartão de crédito MANUAL (automáticos vêm da conexão bancária). As faturas são geradas automaticamente após a criação.
  - body: { name: string, billing_due_day: integer, billing_cycle_day: integer, flag?: string, limit?: number, payment_account_id?: integer }
- `POST https://api.mcp.ai/api/organizze/create/transaction` — Cria uma transação (receita ou despesa). Prefira NOMES de conta/cartão e categoria (list_accounts / list_credit_cards / list_categories primeiro se não souber). Nunca invente UUID/id. Ex.: account: "N
  - body: { description: string, amount: number, date: string, account: string, category?: string, is_income: boolean, done?: boolean, observation?: string, tags?: string, times?: integer, recurring?: boolean, periodicity?: string, idempotency_key?: string }
- `POST https://api.mcp.ai/api/organizze/create/transfer` — Cria uma transferência entre duas contas bancárias (suporta recorrência). Prefira NOMES de conta (não invente ids). Não envolve cartões de crédito.
  - body: { amount: number, date: string, credit_account: string, debit_account: string, description?: string, done?: boolean, observation?: string, tags?: string, recurring?: boolean, periodicity?: string }
- `POST https://api.mcp.ai/api/organizze/delete/account` — Exclui uma conta. ATENÇÃO: todas as transações da conta são excluídas em background. Contas automáticas não podem ser excluídas (desconecte pelo menu de conexões).
  - body: { account: string }
- `POST https://api.mcp.ai/api/organizze/delete/budget` — Remove um orçamento (limite de gastos) de uma categoria.
  - body: { budget_id: integer }
- `POST https://api.mcp.ai/api/organizze/delete/category` — Exclui uma categoria; suas transações vão para outra categoria (substitute_category ou padrão). Categorias padrão NÃO podem ser excluídas. Ao excluir uma raiz, as subcategorias somem.
  - body: { category: string, substitute_category?: string }
- `POST https://api.mcp.ai/api/organizze/delete/credit/card` — Exclui um cartão de crédito. ATENÇÃO: todas as transações e faturas do cartão são excluídas. Cartões automáticos não podem ser excluídos (desconecte pelo menu de conexões).
  - body: { credit_card: string }
- `POST https://api.mcp.ai/api/organizze/delete/transaction` — Exclui uma transação. Transações automáticas (Open Finance) não podem ser excluídas. Para recorrentes use delete_recurrence. O transaction_id/uuid DEVE ser copiado de list_transactions, search_transac
  - body: { transaction_id?: integer, transaction_uuid?: string, delete_recurrence?: string }
- `POST https://api.mcp.ai/api/organizze/find/duplicates` — Encontra transações possivelmente duplicadas (mesmo valor e descrição similar em datas próximas). Útil para limpeza de lançamentos em dobro. Padrão: mês atual.
  - body: { start_date?: string, end_date?: string, days_threshold?: integer, include_automatic?: boolean }
- `POST https://api.mcp.ai/api/organizze/find/installments` — Encontra COMPRAS PARCELADAS no período (use isto, não busca por texto). Combina parcelas estruturadas e heurística para Open Finance (apresentadas como "possível parcelamento"). Sem datas, últimos 12 
  - body: { start_date?: string, end_date?: string, account?: string, min_occurrences?: integer }
- `POST https://api.mcp.ai/api/organizze/find/subscriptions` — Detecta ASSINATURAS e serviços recorrentes (Netflix, Spotify, ChatGPT, aluguel...). Use para "minhas assinaturas", "o que pago todo mês", "o que posso cancelar". Funciona em contas/cartões CONECTADOS 
  - body: { start_date?: string, end_date?: string, account?: string, min_occurrences?: integer, include_recurrences?: boolean }
- `POST https://api.mcp.ai/api/organizze/get/account/context` — Orientação inicial em uma só chamada: entidade conectada, plano, data de hoje no fuso do usuário, e listas compactas (id ↔ nome) de contas, cartões e categorias. Chame no início para evitar várias cha
- `POST https://api.mcp.ai/api/organizze/get/balances` — Saldo consolidado: saldo atual de cada conta, fatura atual em aberto de cada cartão e o patrimônio (contas − faturas atuais em aberto). Base caixa; não trata parcelas/faturas futuras como dívida. Use 
- `POST https://api.mcp.ai/api/organizze/get/bank/connections` — Lista as conexões bancárias (Open Finance / Conectado) ATIVAS e o status de cada uma (estável/indisponível). Somente leitura — não força sincronização. Use para "meu banco não atualiza".
- `POST https://api.mcp.ai/api/organizze/get/budget/summary` — Resumo dos limites de gastos do mês com alertas de budgets excedidos ou próximos do limite ("estou no controle?"). Padrão: mês atual.
  - body: { month?: integer, year?: integer }
- `POST https://api.mcp.ai/api/organizze/get/cashflow/forecast` — Projeção de fluxo de caixa: parte do saldo atual e aplica os lançamentos não pagos de contas manuais na janela, retornando o saldo projetado ao fim e o menor ponto (risco de negativo). Base caixa; não
  - body: { days?: integer, start_date?: string }
- `POST https://api.mcp.ai/api/organizze/get/categories/evolution` — Evolução de gastos/receitas por categoria ao longo do tempo (diário/semanal/mensal). Ideal para tendências. Padrão: últimos 3 meses.
  - body: { start_date?: string, end_date?: string, periodicity?: string, category_ids?: integer[], only_parent_category?: boolean, lens?: string }
- `POST https://api.mcp.ai/api/organizze/get/categories/report` — Relatório de gastos e receitas agrupados por categoria (inclui compras de cartão; base POR LANÇAMENTO). Percentuais e subcategorias. Padrão: mês atual.
  - body: { start_date?: string, end_date?: string, lens?: string }
- `POST https://api.mcp.ai/api/organizze/get/credit/card/invoice` — Detalhes de uma fatura específica de cartão: transações, pagamentos e gastos por categoria. Prefira passar credit_card com o NOME do cartão.
  - body: { credit_card?: string, credit_card_id?: integer, invoice_id?: integer, month?: integer, year?: integer }
- `POST https://api.mcp.ai/api/organizze/get/credit/card/invoices` — Lista faturas de um cartão. Informe credit_card_id.
  - body: { credit_card_id: integer, start_date?: string, end_date?: string }
- `POST https://api.mcp.ai/api/organizze/get/financial/summary` — Resumo financeiro do período (receitas, despesas, comparação, maiores gastos). Totais em base caixa; maiores gastos em base por lançamento (incluem cartão) — não somam com os totais.
  - body: { start_date?: string, end_date?: string, year?: integer, month?: integer }
- `POST https://api.mcp.ai/api/organizze/get/income/vs/expenses` — Relatório de entradas vs saídas (receitas vs despesas) por período, em modo cashflow. Use account_id para filtrar uma conta. Padrão: mês atual. Base caixa por conta — exclui compras individuais de car
  - body: { start_date?: string, end_date?: string, periodicity?: string, account_id?: integer }
- `POST https://api.mcp.ai/api/organizze/get/invoices/matrix` — Matriz de faturas (mês × cartão) com totais por mês, por cartão e total geral, usando os mesmos valores de get_credit_card_invoices. Use quando o usuário pedir faturas de VÁRIOS cartões e/ou meses, em
  - body: { start_date?: string, end_date?: string, cards?: string[] }
- `POST https://api.mcp.ai/api/organizze/get/latest/imports` — Transações mais recentemente importadas via Open Finance (contas/cartões conectados). Use para "lançamentos novos/recém-importados". Paginação via page/per_page (padrão 50, máx 100).
  - body: { limit?: integer, page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/organizze/get/monthly/overview` — Visão geral do mês em uma só chamada: receitas, despesas, saldo, maiores categorias de despesa, status dos limites e contas a pagar dos próximos 7 dias. Padrão: mês atual. totals são base caixa; top_e
  - body: { month?: integer, year?: integer }
- `POST https://api.mcp.ai/api/organizze/get/open/finance/status` — Status AO VIVO do agregador Open Finance (Belvo), opcionalmente por banco. Use para saber se "o banco não atualiza" é uma instabilidade upstream. Cacheado ~5 min.
  - body: { institution?: string }
- `POST https://api.mcp.ai/api/organizze/get/tags/report` — Relatório de transações agrupadas por tag (despesas e receitas, com percentuais). Para projetos/históricos longos informe start_date e end_date amplos — o padrão é só o mês atual.
  - body: { start_date?: string, end_date?: string, tag_name?: string, tag_name_prefix?: string }
- `POST https://api.mcp.ai/api/organizze/get/transaction` — Detalhes completos de uma transação pelo id ou uuid.
  - body: { transaction_id?: integer, transaction_uuid?: string }
- `POST https://api.mcp.ai/api/organizze/get/upcoming/bills` — Contas a pagar dos próximos dias: lançamentos não pagos com vencimento na janela e faturas de cartão que vencem no período ("o que vence essa semana?"). Padrão: 7 dias.
  - body: { days?: integer, start_date?: string }
- `POST https://api.mcp.ai/api/organizze/inform/invoice/payment` — Informa pagamento de fatura em cartão automático (Open Finance).
  - body: { credit_card: string, invoice_date_or_id?: string, date?: string, observation?: string }
- `POST https://api.mcp.ai/api/organizze/list/accounts` — Lista as contas do usuário com ids.
- `POST https://api.mcp.ai/api/organizze/list/budgets` — Lista limites de gastos por categoria. Passe year e/ou month para escopo.
  - body: { year?: integer, month?: integer }
- `POST https://api.mcp.ai/api/organizze/list/categories` — Lista as categorias usadas para classificar transações.
- `POST https://api.mcp.ai/api/organizze/list/credit/cards` — Lista os cartões de crédito do usuário com ids e limites.
- `POST https://api.mcp.ai/api/organizze/list/institutions` — Catálogo de instituições financeiras (bancos/operadoras) com o id (slug) usado em institution_id ao criar/editar contas e cartões. Use query para filtrar por nome.
  - body: { query?: string, limit?: integer }
- `POST https://api.mcp.ai/api/organizze/list/recurrences` — Lista as contas fixas CADASTRADAS (lançamentos recorrentes/infinitos): aluguel, assinaturas, salário, etc., com periodicidade, valor e a próxima ocorrência. Só traz recorrências cadastradas (contas/ca
- `POST https://api.mcp.ai/api/organizze/list/transactions` — Lista transações do usuário no período selecionado, com paginação (page/per_page; máximo 80 por página). Detalhes Open Finance (dados crus do banco) não são incluídos nesta listagem para economizar co
  - body: { start_date?: string, end_date?: string, account_id?: integer, credit_card_id?: integer, category_id?: integer, order_by?: string, list_mode?: string, page?: integer, per_page?: integer, installments_only?: boolean }
- `POST https://api.mcp.ai/api/organizze/list/transferences` — Lista transferências entre contas com paginação (page/per_page). Datas em YYYY-MM-DD.
  - body: { start_date?: string, end_date?: string, account_id?: integer, page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/organizze/load/skill` — Carrega um guia detalhado de uso (skill) sobre um tema do Organizze. Chame ANTES de responder quando a conversa tocar um destes temas:
  - body: { skill_name: string }
- `POST https://api.mcp.ai/api/organizze/mass/create/transactions` — Cria VÁRIAS transações em lote (máx. 100) a partir de uma lista de objetos. Use em vez de create_transaction repetido. Cada linha no array deve ser única (descrição+valor+data+conta) — dedupe no paylo
  - body: { transactions: object[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/organizze/mass/delete/transactions` — Exclui VÁRIAS transações por lista de ids/uuids (máx. 500). Os ids DEVEM vir de uma busca recente (list/search/find_duplicates/get_transaction) — nunca invente. Automáticas são ignoradas; recorrentes 
  - body: { transactions: object[] }
- `POST https://api.mcp.ai/api/organizze/mass/manage/categories` — Aplica VÁRIAS mudanças na árvore de categorias em uma chamada atômica (máx. 100 ops). Operações: create, rename, move (parent '0' = raiz), archive, unarchive (NÃO há delete — use archive). Resolve por
  - body: { operations: object[] }
- `POST https://api.mcp.ai/api/organizze/mass/update/transactions` — Atualiza VÁRIAS transações por FILTRO de busca (máx. 200) — prefira isto a montar listas de IDs quando a mesma alteração vale para todas as linhas. Antes, valide com list_transactions/search_transacti
  - body: { query?: string, start_date?: string, end_date?: string, category_id?: integer, account_id?: integer, credit_card_id?: integer, activity_type?: string, tag_filter?: string, paid_filter?: boolean, new_category?: string, new_description?: string, description_find?: string, description_replace?: string, new_observation?: string, new_tags?: string, tag_action?: string, new_paid?: boolean }
- `POST https://api.mcp.ai/api/organizze/register/invoice/payment` — Registra o pagamento de uma fatura de cartão MANUAL como lançamento, vinculado à fatura. Para cartões automáticos use inform_invoice_payment. Prefira NOMES de cartão/conta. Liste faturas com get_credi
  - body: { credit_card: string, source_account?: string, amount: number, date: string, invoice_date_or_id?: string, observation?: string }
- `POST https://api.mcp.ai/api/organizze/resolve/entity` — Resolve um nome aproximado para o id/uuid real de conta, cartão ou categoria. Use ANTES de uma escrita para evitar ids inventados. Quando ambíguo, retorna as correspondências.
  - body: { name: string, kind?: string }
- `POST https://api.mcp.ai/api/organizze/search/transactions` — Busca transações por texto na descrição, observação ou tags (ex.: "iFood", "Uber", "salário"). Paginação via page/per_page; sem datas, o padrão são os últimos 6 meses.
  - body: { query: string, start_date?: string, end_date?: string, min_amount?: number, max_amount?: number, activity_type?: string, page?: integer, per_page?: integer, tags_only?: boolean }
- `POST https://api.mcp.ai/api/organizze/set/transaction/paid` — Marca uma transação como paga/recebida (paid=true) ou não paga (paid=false) em conta MANUAL ("já paguei o aluguel"). Idempotente. Transações automáticas são sempre pagas.
  - body: { paid: boolean, transaction_id?: integer, transaction_uuid?: string }
- `POST https://api.mcp.ai/api/organizze/suggest/categories` — Sugere categorias para uma ou mais descrições de transação, usando as edições anteriores do próprio usuário, o histórico já categorizado e padrões globais. Use ANTES de create_transaction ao classific
  - body: { items: object[] }
- `POST https://api.mcp.ai/api/organizze/transactions/list/results` — Totais financeiros de um período (receitas, despesas, resultado, saldo, previstos) sem paginar transação por transação. Ideal para "quanto gastei esse mês?", "qual meu saldo?". Padrão: mês atual. Base
  - body: { start_date?: string, end_date?: string, account_id?: integer, category_id?: integer, list_mode?: string }
- `POST https://api.mcp.ai/api/organizze/uninform/invoice/payment` — Desfaz um "Informar Pagamento" em cartão AUTOMÁTICO (marcador aguardando Open Finance). Não remove pagamentos reais já confirmados. invoice_date_or_id é obrigatório.
  - body: { credit_card: string, invoice_date_or_id: string }
- `POST https://api.mcp.ai/api/organizze/update/account` — Atualiza uma conta (nome, descrição, instituição, arquivar). Contas automáticas só permitem nome e archived. Prefira NOME (não invente id).
  - body: { account: string, name?: string, description?: string, institution_id?: string, archived?: boolean, hide_balance?: boolean }
- `POST https://api.mcp.ai/api/organizze/update/budget` — Atualiza o valor de um orçamento existente. amount = 0 remove o orçamento.
  - body: { budget_id: integer, amount: number }
- `POST https://api.mcp.ai/api/organizze/update/category` — Atualiza uma categoria (nome, cor, pai, arquivar). Categorias padrão não podem ser excluídas, mas podem ser renomeadas/arquivadas. Prefira NOME (não invente id).
  - body: { category: string, name?: string, color?: string, parent?: string, archived?: boolean }
- `POST https://api.mcp.ai/api/organizze/update/credit/card` — Atualiza um cartão de crédito (nome, bandeira, dias de fatura, limite, arquivar). Cartões automáticos só permitem nome e archived. Prefira NOME (não invente id).
  - body: { credit_card: string, name?: string, flag?: string, billing_due_day?: integer, billing_cycle_day?: integer, limit?: number, payment_account_id?: integer, archived?: boolean }
- `POST https://api.mcp.ai/api/organizze/update/transaction` — Atualiza uma transação existente (informe só os campos a alterar). Em transações automáticas só descrição, categoria, observação e tags podem mudar. Prefira NOMES de conta/categoria (não invente ids).
  - body: { transaction_id?: integer, transaction_uuid?: string, description?: string, amount?: number, date?: string, category?: string, account?: string, paid?: boolean, observation?: string, tags?: string, update_recurrence?: string }
- `POST https://api.mcp.ai/api/organizze/update/transactions/categories` — Define a categoria de VÁRIAS transações em uma chamada, com destino por linha (máx. 200). Ideal após suggest_categories quando cada linha tem categoria diferente. Prefira category (NOME) e IDs só de l
  - body: { updates: object[] }
- `POST https://api.mcp.ai/api/organizze/update/transactions/descriptions` — Substitui a descrição de VÁRIAS transações em uma chamada (máx. 200). Cada item: transaction_id (ou id) OU transaction_uuid (ou uuid) + description (ou new_description). IDs só de list_transactions/se
  - body: { updates: object[] }

## Example prompts
- "How was my month? Income, expenses and balance"
- "Which recurring subscriptions do I have?"
- "How much do I still have to pay this week?"

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