O que é o MCP?

O MCP (Model Context Protocol) permite que assistentes de IA como Claude, ChatGPT, Codex e Cursor acessem seus dados financeiros no Visor de forma segura. Com essa conexão, você pode conversar com a IA e pedir coisas como:

• “Quanto gastei com alimentação este mês?”
• “Crie uma categoria para assinaturas”
• “Qual meu saldo previsto para o final do mês?”
• “Mostre meus gastos por categoria”

A IA acessa seus dados em tempo real e pode até criar transações, categorias, metas e regras de categorização para você.

Requisitos

• Plano Pro ou Premium ativo
• Um cliente MCP compatível (Claude Code, Codex, Cursor, Claude Desktop, ChatGPT ou outro)

Como conectar

Opção 1: Claude Code (CLI)

No terminal, execute:

claude mcp add visor --transport http https://mcp.visorfinance.app

Opção 2: Codex (CLI)

No terminal, execute:

codex mcp add visor -- npx mcp-remote https://mcp.visorfinance.app

Requer Node.js instalado (o mcp-remote funciona como ponte entre o cliente e o servidor).

Opção 3: Cursor

Edite o arquivo ~/.cursor/mcp.json e adicione:

{ "mcpServers": { "visor": { "url": "https://mcp.visorfinance.app" } } }

Opção 4: Claude Desktop ou outros clientes

Para clientes que usam configuração JSON (como Claude Desktop), adicione ao bloco mcpServers:

{ "mcpServers": { "visor": { "command": "npx", "args": ["mcp-remote", "https://mcp.visorfinance.app"] } } }

Requer Node.js instalado.

Opção 5: ChatGPT (Modo desenvolvedor)

O ChatGPT conecta o Visor pelo Modo desenvolvedor, disponível no ChatGPT web para planos pagos (Plus, Pro, Business, Enterprise ou Edu). GPTs personalizados não funcionam com o MCP.

1. Ative o Modo desenvolvedor

1. No ChatGPT web, abra Configurações
2. Vá em Aplicativos e conectores (ou Apps) e abra Configurações avançadas
3. Ative o Modo desenvolvedor

2. Adicione o Visor

1. Em Aplicativos e conectores, clique em Criar
2. Preencha o nome Visor, a URL do servidor MCP https://mcp.visorfinance.app/ e a autenticação OAuth
3. Marque que confia no aplicativo e clique em Criar
4. Faça login no Visor na janela que abrir e escolha as permissões

3. Ative o Visor na conversa

O ChatGPT não usa o conector sozinho. Em cada conversa nova, clique no + ao lado do campo de mensagem, abra Mais, escolha Modo desenvolvedor e ative o Visor.

Os nomes dos menus podem mudar conforme o ChatGPT atualiza o aplicativo.

Autenticação

Na primeira vez que o cliente MCP tentar se conectar, uma janela do navegador vai abrir automaticamente para você fazer login no Visor. Depois de autenticar, a conexão fica ativa e você não precisa fazer login novamente.

O transporte usa HTTP com OAuth 2.0 - um padrão seguro de autorização. Seus dados nunca são compartilhados sem seu consentimento.

O que a IA pode fazer com o MCP?

O servidor oferece ferramentas para consultar, organizar e atualizar as principais informações do seu espaço financeiro. Você pode fazer o pedido em linguagem natural, sem precisar saber o nome técnico de cada ferramenta.

Visão geral, transações e cartões

• Consultar saldo, receitas, despesas, limite disponível e projeção de saldo
• Comparar gastos com o período anterior e acompanhar o ritmo de gastos
• Listar transações por período, tipo, categoria, conta, cartão, tag ou texto
• Consultar contas, cartões, faturas, próximos vencimentos e gastos por categoria
• Listar os cartões adicionais com seus ids e nomes; use include_hidden=true para encontrar cartões ocultos
• Renomear, ocultar ou restaurar cartões adicionais pelo id retornado em get_cards
• Excluir cartões adicionais, exceto o cartão principal
• Definir qual número de cartão é o principal
• Marcar e desmarcar faturas de cartão como pagas sem alterar os dados enviados pelo banco
• Ocultar e restaurar contas sincronizadas; use include_hidden=true para encontrar contas ocultas
• Criar uma conta manual e lançar receitas ou despesas nela
• Editar o limite de crédito e os dias de fechamento e vencimento de cartões manuais; cartões sincronizados mantêm o limite informado pelo banco
• Editar uma ou várias transações, inclusive descrição, valor, data, categoria e status de ignorada
• Excluir uma ou várias transações selecionadas
• Editar ou excluir todas as transações de um período, com até 500 transações por vez e filtro opcional por conta
• Mover uma ou várias transações para outro espaço
• Anexar ou remover tags de transações

Parcelamentos, contas fixas e dívidas

• Consultar parcelamentos ativos, parcelas pagas e restantes, valor mensal e saldo restante
• Criar um parcelamento manual em um cartão manual, informando valor exato, parcela atual, total de parcelas, data inicial e categoria opcional
• Consultar parcelamentos concluídos manualmente e concluir ou reabrir um parcelamento sem alterar o histórico de pagamentos
• Filtrar parcelamentos por mês ou pelos quatro últimos dígitos do cartão
• Renomear um parcelamento detectado e alterar sua categoria; a mudança de nome também é aplicada às parcelas já lançadas
• Criar, editar e desativar contas fixas e receitas recorrentes, inclusive definir ou remover uma data final para as projeções
• Cadastrar uma dívida ou financiamento manual com valor da parcela, data do primeiro pagamento, quantidade total de parcelas e parcelas já pagas, além de atualizar esses dados depois

Para criar um parcelamento manual pelo MCP, selecione um cartão manual com os dias de fechamento e vencimento configurados. O Visor usa esses dias do cartão nas faturas, projeções e no limite disponível. Se o cartão não tiver billing_cycle_close_day e billing_cycle_due_day, atualize os dois campos em update_account_settings e repita a solicitação. O parcelamento cria apenas o plano e sua recorrência vinculada; ele não cria várias transações futuras.

Orçamento, categorias e automações

• Consultar o orçamento total e os limites por categoria
• Planejar um orçamento, definir o total mensal, criar ou alterar limites por categoria e remover limites

Para alterar limites pelo MCP, o orçamento precisa estar ativado nas suas preferências do Visor. A mesma preferência vale no aplicativo.

• Listar, criar, editar, ocultar e restaurar categorias personalizadas
• Excluir categorias personalizadas, reatribuindo suas transações para a categoria de fallback correta
• Analisar categorias e criar, editar ou excluir regras de categorização automática

Metas, investimentos e organização

• Listar, criar e editar metas financeiras
• Planejar quanto guardar para alcançar uma meta, registrar ou remover contribuições e concluir uma meta
• Vincular um investimento ou o saldo de uma conta a uma meta e remover esse vínculo
• Excluir uma meta, removendo suas contribuições e fotos, ou desvincular uma transação da meta sem excluir a transação
• Consultar investimentos manuais e importados pelo Open Finance
• Criar e editar investimentos manuais e ajustar quais investimentos entram no patrimônio
• Excluir contas e investimentos manuais
• Consultar empréstimos e financiamentos
• Ocultar e restaurar empréstimos sincronizados; use include_hidden=true para encontrar empréstimos ocultos
• Excluir empréstimos e financiamentos cadastrados manualmente, quando não houver um pagamento pendente vinculado
• Criar ou substituir o cronograma de pagamentos SAC de um empréstimo manual, quando esse recurso estiver disponível para sua conta
• Criar, editar e excluir tags
• Listar seus espaços e alterar o nome, o ícone, a cor, o tipo ou o dia de início do mês financeiro de um espaço
• Mover contas e conexões do Open Finance para outro espaço
• Ativar ou desativar tipos de notificação por canal
• Gerar gráficos de barras, linhas ou rosca com seus dados

Algumas funcionalidades podem aparecer gradualmente conforme o Visor libera novos recursos. O próprio cliente MCP recebe sempre a lista de ferramentas disponível para a sua conta, incluindo apenas os recursos habilitados para você.

As ferramentas compatíveis com as permissões da conexão aparecem para sua conta. As ações destrutivas só são executadas depois da sua confirmação explícita.

Confirmações e tentativas

Para ações destrutivas, a IA pede sua confirmação antes de executar. Se a mesma solicitação for reenviada por causa de uma falha de conexão, o Visor reconhece a tentativa anterior para evitar uma alteração duplicada. Uma tentativa interrompida pode ser retomada automaticamente quando você reenviar a confirmação.

O MCP também oferece as ferramentas reconcile_scheduled_payment e undo_scheduled_payment para administrar parcelas de empréstimos manuais. A primeira concilia uma parcela agendada com uma transação existente ou cria a transação na conta informada. A segunda desfaz uma parcela já conciliada, respeitando a ordem dos pagamentos e mantendo o histórico da transação vinculada. Essas ferramentas usam a permissão OAuth mcp:payments:write, separada das permissões de consulta. As ferramentas create_manual_loan_schedule, replace_manual_loan_schedule e delete_manual_loan usam mcp:accounts:write.

As ferramentas marcadas como destrutivas pelo servidor, incluindo edit_transaction e batch_edit_transactions, exigem confirmed=true e um idempotency_key não vazio em cada chamada. O servidor valida a solicitação antes da confirmação, registra a execução de forma durável e devolve o mesmo resultado quando recebe novamente a mesma chave. O cliente deve guardar essa chave e reenviá-la somente para repetir a mesma solicitação.

As ferramentas mark_bill_paid e unmark_bill_paid usam a permissão OAuth mcp:payments:write. Elas retornam o id da fatura, o id da conta, o estado atual e se a confirmação do banco ainda está pendente. Essas ações alteram apenas o estado manual da fatura; não alteram o valor da fatura nem os pagamentos informados pelo banco.

Ao excluir uma categoria personalizada, o Visor reatribui suas transações e referências de categoria das regras para uma categoria de sistema compatível. Categorias de sistema não podem ser excluídas. A exclusão de uma regra interrompe apenas as aplicações futuras: alterações já feitas nas transações permanecem.

Uma repetição exata já concluída e uma tentativa simultânea enquanto a mesma chave está em processamento não consomem uma nova cota de escrita. A cota é cobrada somente da solicitação que obtém a execução durável.

E se eu tiver mais de um espaço?

Se você usa espaços para separar suas finanças (pessoal, empresa, família), a IA consegue trabalhar com todos eles:

• Peça “liste meus espaços” para ver o nome e o id de cada um
• Nas consultas, você pode indicar o espaço desejado (“quanto gastei no espaço da empresa?”); sem indicação, vale o espaço ativo no app
• Para criar ou editar algo, a IA sempre confirma em qual espaço a mudança deve entrar antes de fazer

Consultar ou editar um espaço pela IA não muda o espaço que você está vendo no app.

Onde encontrar as instruções no Visor

Você também pode copiar os comandos de instalação diretamente no Visor:

1. Abra o Visor no navegador
2. Acesse a página Configurações em /configuracoes
3. Abra a seção Apps conectados em /configuracoes/connected_apps e encontre o card do servidor MCP com os comandos prontos para copiar

Problemas comuns

A janela de login não abre

Verifique se o navegador padrão está configurado corretamente. Alguns terminais podem bloquear a abertura automática - nesse caso, copie a URL que aparece no terminal e cole no navegador.

Erro de autenticação

Certifique-se de que você está logado no Visor com um plano Pro ou Premium ativo. O MCP não está disponível no plano gratuito.

Comando npx não encontrado

Instale o Node.js (versão 18 ou superior) em nodejs.org.

O cliente não reconhece o servidor

Reinicie o cliente MCP depois de adicionar a configuração. A maioria dos clientes precisa ser reiniciada para carregar novos servidores.

O ChatGPT diz que não tem ferramentas do Visor

Ative o Visor na conversa: clique no +, abra Mais, escolha Modo desenvolvedor e ative o Visor. Se o conector foi criado antes de você entrar no plano Pro ou Premium, exclua o conector em Aplicativos e conectores e crie de novo para o ChatGPT buscar as ferramentas outra vez.

Como controlar as memórias da IA

O assistente pode consultar suas memórias salvas ao iniciar uma conversa, sem precisar de uma palavra-chave. Essas memórias incluem preferências, contexto e um resumo das conversas. Elas pertencem ao seu usuário e não são compartilhadas com outros usuários.

No site, abra Configurações > Preferências > Memórias da IA para ver, editar ou excluir uma memória. Em telas menores, a seção Memórias da IA aparece diretamente nas configurações. Para remover tudo, use Excluir todas e confirme.

O Visor também pode identificar informações duradouras nas suas mensagens em uma rotina diária. Uma memória que você editou não é alterada por essa rotina. Ao excluir memórias, as mensagens anteriores não são processadas novamente para recriá-las. Novas conversas podem criar novas memórias.