Ligar um assistente de IA (MCP)

MoneyLights tem um servidor MCP integrado, para que um assistente de IA — Claude Desktop, Claude Code, um agente IDE, qualquer coisa que fale o protocolo — possa trabalhar com os dados da tua organização quando solicitado.

É a mesma credencial que a API REST: uma conexão MCP é uma chave de API, com os mesmos scopes, os mesmos limites e o mesmo botão de revogação. Não há nada separado para gerir.

Conectando

O endpoint é https://api.moneylights.app/mcp (Streamable HTTP). Uma configuração típica do cliente:

{
  "mcpServers": {
    "moneylights": {
      "url": "https://api.moneylights.app/mcp",
      "headers": { "X-API-Key": "ml_sk_..." }
    }
  }
}

Com o Claude Code é um comando:

claude mcp add --transport http moneylights https://api.moneylights.app/mcp \
  --header "X-API-Key: ml_sk_..."

Cria a chave em Definições → Chaves de API e concede-lhe apenas os scopes que o assistente precisa. Tudo requer a chave, incluindo listar as ferramentas.

O que o assistente pode fazer

A lista de ferramentas é calculada a partir dos scopes da tua chave, em cada pedido. Uma chave sem um scope nunca é informada da existência da ferramenta correspondente.

Ferramenta	Scope	O que faz
get_cashflow_overview	cashflow:read	Rendimento/despesa/lucro mensal, saldo de abertura, principais categorias
get_analytics_overview	analytics:read	Agregados por categoria, cliente, projeto e pessoa
list_transactions	transactions:read	Transações, filtradas e paginadas, cada uma com os documentos que lhe estão ligados
list_documents	documents:read	Documentos e os seus campos extraídos, cada um com os movimentos que lhe estão ligados
get_pending_distribution	profitpulse:read	Distribuições pendentes Safe-to-Spend
list_vendors	vendors:read	Fornecedores, com total gasto
list_clients	clients:read	Clientes, com total de receitas
list_projects	projects:read	Projetos, com totais e metas
upload_document	documents:write	Arquiva uma fatura ou recibo nos teus documentos

Qual documento vai com qual movimento

Ambas as listas o dizem, dos dois lados, tal como a aplicação o mostra. Cada transação traz linkedDocuments e cada documento traz linkedTransactions; cada entrada identifica o outro lado e um link:

• confirmed — o documento está associado ao movimento, o que conta como documentado.
• suggested — o emparelhador propõe a associação; ninguém a confirmou e ao movimento continua a faltar o documento. A entrada traz o score do emparelhador.

Um assistente consegue assim distinguir sem fatura de fatura à espera de confirmação de já arquivada — e não pode alterar nada disso, porque esta ligação não tem ferramenta para tal.

Um movimento pode ter vários documentos confirmados. Um documento liga-se no máximo a um movimento, pelo que uma fatura paga em várias partes mostra apenas o movimento ao qual foi associada. Um documento ainda em Processing ainda não tem ligações; None significa nenhuma.

Os scopes continuam a valer: o outro lado de uma ligação é descrito (fornecedor e número, ou descrição e montante) apenas a uma chave que também possa ler esse recurso. Com um só scope obténs o id do outro lado, o tipo de ligação e o score — o suficiente para saber que um movimento está documentado, não o que a fatura diz.

Arquivar documentos

upload_document é a única ferramenta que escreve, e foi escolhida para esse papel deliberadamente: ela apenas adiciona. O assistente envia o ficheiro (PDF ou imagem, até 10MB) e o MoneyLights processa-o através do mesmo pipeline que um upload na aplicação — armazenado, os seus campos extraídos (fornecedor, data, número, montantes) e automaticamente correspondido com as tuas transações bancárias.

Enviar o mesmo ficheiro duas vezes nunca duplica os teus dados: o re-upload é registado como um duplicado sinalizado apontando para o original. Tudo o que o assistente arquiva é visível — e eliminável — na aplicação.

Todas as outras escritas (criar clientes, reclassificar transações, configurar envelopes…) permanecem na aplicação de propósito: essas ações assumem um humano a confirmá-las.

Prompts curados

O servidor também oferece pontos de partida prontos — uma revisão mensal de cashflow, uma análise de gastos de fornecedores, uma limpeza de documentos em falta — listados apenas quando a tua chave pode executar todas as ferramentas que precisam. Usa-os como estão ou edita livremente.

Segurança

• O assistente é limitado pela chave, verificada em cada pedido. Despromove ou remove o criador da chave e o assistente restringe ou para na próxima chamada.
• Os dados financeiros contêm texto escrito por estranhos — referências de pagamento, documentos enviados por e-mail. Os resultados das ferramentas são entregues dentro de um limite marcado dizendo ao modelo para tratá-los como dados, nunca como instruções. Trata isso como uma mitigação, não como uma garantia, e limita os scopes das chaves de forma rigorosa.
• Para desligar um assistente, revoga a chave em Definições → Chaves de API. Imediato, sempre disponível.

Dá a cada assistente a sua própria chave — uma por cliente significa que podes cortar uma sem perturbar as restantes.