Collega un assistente AI (MCP)

MoneyLights ha un server MCP integrato, quindi un assistente AI — Claude Desktop, Claude Code, un agente IDE, qualsiasi cosa che parli il protocollo — può lavorare con i dati della tua organizzazione su richiesta.

È la stessa credenziale dell’API REST: una connessione MCP è una chiave API, con gli stessi ambiti, gli stessi limiti e lo stesso pulsante di revoca. Non c’è nulla di separato da gestire.

Collegamento

L’endpoint è https://api.moneylights.app/mcp (Streamable HTTP). Una configurazione tipica del client:

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

Con Claude Code è un solo comando:

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

Crea la chiave in Impostazioni → Chiavi API e concedile solo gli ambiti di cui l’assistente ha bisogno. Tutto richiede la chiave, incluso l’elenco degli strumenti.

Cosa può fare l’assistente

L’elenco degli strumenti è calcolato dagli ambiti della tua chiave, ad ogni richiesta. Una chiave senza un ambito non viene nemmeno informata dell’esistenza dello strumento corrispondente.

Strumento	Ambito	Cosa fa
get_cashflow_overview	cashflow:read	Entrate/spese/netto mensili, saldo iniziale, categorie principali
get_analytics_overview	analytics:read	Aggregati per categoria, cliente, progetto e persona
list_transactions	transactions:read	Transazioni, filtrate e paginate, ognuna con i documenti ad essa collegati
list_documents	documents:read	Documenti e i loro campi estratti, ognuno con i movimenti ad esso collegati
get_document_file	documents:read	Il file originale di un documento — il PDF o l’immagine che l’app mostra
get_pending_distribution	profitpulse:read	Distribuzioni Safe-to-Spend in attesa
list_vendors	vendors:read	Fornitori, con spesa totale
list_clients	clients:read	Clienti, con entrate totali
list_projects	projects:read	Progetti, con totali e obiettivi
upload_document	documents:write	Archivia un fattura o una ricevuta nei tuoi documenti

Entrambi gli overview si calcolano sulla stessa base e lo dicono: ogni risposta porta un basis — periodo, valute, i conti coperti (ogni conto visibile, a meno che non venga richiesto per id), e come sono stati trattati i trasferimenti tra i conti della stessa organizzazione. Per impostazione predefinita, sono esclusi da entrate e spese, movimento per movimento, esattamente come mostra la vista Cashflow dell’app; passa includeInternalTransfers: true a uno dei due strumenti per il movimento bancario grezzo, che il basis etichetta come tale e che non è comparabile con il predefinito. Confronta i numeri tra i due strumenti solo quando il loro basis corrisponde. netCashResult è il reddito meno le spese dei movimenti bancari — un risultato di cassa, non un profitto contabile.

Quale documento va con quale movimento

Entrambi gli elenchi lo dicono, da entrambi i lati, come mostra l’app. Ogni transazione porta linkedDocuments e ogni documento porta linkedTransactions; ogni voce nomina l’altro lato e un link:

• confirmed — il documento è abbinato al movimento, il che conta come documentato.
• suggested — il matcher propone l’abbinamento; nessuno l’ha confermato e il movimento è ancora privo del suo documento. La voce porta il score del matcher.

Un assistente può quindi distinguere nessuna fattura da una fattura in attesa di conferma da già archiviata — e non può cambiare nulla di tutto ciò, perché questa connessione non ha uno strumento per farlo.

Un movimento può portare diversi documenti confermati. Un documento si collega al massimo a un movimento, quindi una fattura pagata in più parti mostra solo il movimento a cui è stata abbinata. Un documento ancora Processing non ha collegamenti ancora; None significa nessuno.

Gli ambiti continuano a valere: il lato lontano di un collegamento è descritto (fornitore e numero, o descrizione e importo) solo a una chiave che può leggere anche quella risorsa. Con un ambito ottieni l’id dell’altro lato, il tipo di collegamento e il punteggio — sufficiente per sapere che un movimento è documentato, non cosa dice la fattura.

Lettura di un originale

get_document_file prende un documentId da list_documents e restituisce il file memorizzato stesso — lo stesso PDF o immagine che l’app apre — come risorsa incorporata con il suo tipo MIME (application/pdf, image/jpeg, …), accanto all’id del documento, nome del file e dimensione — file fino a 10MB, lo stesso limite di un upload. Questo è come un assistente verifica se una differenza proviene dalla fattura, da ciò che è stato estratto o dal movimento a cui è stato abbinato, senza esportare nulla. È una lettura: nulla sul documento, i suoi campi estratti o i suoi collegamenti cambia. Un documento che non è tuo è semplicemente non trovato.

Archiviazione di documenti

upload_document è l’unico strumento che scrive, ed è stato scelto per quel ruolo deliberatamente: aggiunge sempre e solo. L’assistente invia il file (PDF o immagine, fino a 10MB) e MoneyLights lo elabora attraverso la stessa pipeline di un upload nell’app — memorizzato, i suoi campi estratti (fornitore, data, numero, importi) e abbinato automaticamente alle tue transazioni bancarie.

Inviare lo stesso file due volte non duplica mai i tuoi dati: il re-upload è registrato come un duplicato contrassegnato che punta all’originale. Tutto ciò che l’assistente archivia è visibile — e cancellabile — nell’app.

Ogni altra scrittura (creazione di clienti, riclassificazione delle transazioni, configurazione di buste…) rimane nell’app di proposito: quelle azioni presuppongono un umano che le confermi.

Promemoria curati

Il server offre anche punti di partenza pronti all’uso — una revisione mensile del cashflow, un’analisi della spesa dei fornitori, una pulizia dei documenti mancanti — elencati solo quando la tua chiave può eseguire ogni strumento di cui hanno bisogno. Usali così come sono o modifica liberamente.

Sicurezza

• L’assistente è vincolato dalla chiave, ricontrollato ad ogni richiesta. Declassa o rimuovi il creatore della chiave e l’assistente si restringe o si ferma alla prossima chiamata.
• I dati finanziari contengono testo scritto da estranei — riferimenti di pagamento, documenti inviati via email. I risultati degli strumenti vengono consegnati all’interno di un confine contrassegnato che dice al modello di trattarli come dati, mai come istruzioni. Considera questo come una mitigazione, non una garanzia, e limita strettamente le chiavi.
• Per disconnettere un assistente, revoca la sua chiave in Impostazioni → Chiavi API. Immediato, sempre disponibile.

Dai a ogni assistente la sua chiave — una per cliente significa che puoi disconnetterne uno senza disturbare gli altri.