Server MCP Invoiso

Invoiso parla il Model Context Protocol, così un client MCP — Claude, ChatGPT o qualsiasi altro che lo parli — può leggere e usare le fatture, le spese, i contatti, le giacenze e i report del tuo spazio invoiso. Questa pagina è tutto ciò che serve per collegarne uno.

L’endpoint

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

Alla maggior parte delle persone basta l’URL. Aggiungilo come connettore personalizzato in ChatGPT o come server MCP remoto in Claude, poi accedi a invoiso come sempre — nessuna chiave API necessaria. Il client scopre da solo come autenticarsi: una chiamata non autenticata risponde 401 con un header WWW-Authenticate che punta a https://www.invoiso.com/.well-known/oauth-protected-resource, dove sono indicati il server di autorizzazione e gli scope da richiedere.

Collegarsi

1. Aggiungi https://www.invoiso.com/api/mcp al tuo client come server MCP remoto.
2. Il client ti porta all’accesso di invoiso. Accedi come al solito.
3. Approva l’accesso descritto dalla schermata di consenso. Nomina lo spazio che stai collegando.
4. Sei collegato. Chiedi al tuo client qualcosa sui tuoi conti — «quanto ho fatturato il mese scorso?» è una buona prima domanda, perché non richiede permessi oltre alla lettura.

Gli scope richiesti sono openid, email, profile e user:org:read. L’ultimo è quello che ci dice quale spazio stai collegando; senza di esso il server rifiuta invece di indovinare — vedi sotto.

A quale spazio sei collegato

Sei collegato allo spazio che era attivo nel tuo browser quando hai approvato la connessione. La schermata di consenso lo nomina. È la stessa regola che segue il browser — una sessione sta in uno spazio per volta — e significa che cambiare spazio in invoiso non cambia ciò che vede il tuo client MCP.

Per puntare un client su un altro spazio: passa prima a quello spazio in invoiso, poi rimuovi e riaggiungi la connessione nel client. Ripasserai dal consenso e il nuovo token porterà il nuovo spazio.

Se il server non riesce a capire a quale spazio appartiene un token, risponde 403 con error="insufficient_scope" indicando lo scope da richiedere, invece di sceglierne uno. Scegliere sarebbe peggio che rifiutare: la risposta sbagliata plausibile è il tuo spazio personale vuoto, e concluderesti che invoiso ha perso i tuoi conti.

Che cosa può fare il tuo piano

All’assistente dentro invoiso è disponibile tutto, in ogni piano. Ciò che cambia per un client MCP esterno è se può scrivere.

Una connessione in sola lettura non è un client ridotto — è ogni strumento che si limita a riferire. La scrittura da un client esterno parte da Business. Chiedi a una connessione in sola lettura di cambiare qualcosa e te lo dirà in una frase senza cambiare nulla, invece di fallire in modo oscuro.

Che cosa fanno gli strumenti

Ci sono 167 strumenti. 63 di essi si limitano a riferire; gli altri scrivono. Ogni strumento porta le tre annotazioni definite da MCP — readOnlyHint, destructiveHint e openWorldHint — così il tuo client può chiederti conferma prima di fare qualcosa di irreversibile. 15 di essi possono cambiare qualcosa fuori da invoiso: inviare un’e-mail, pubblicare una pagina di pagamento, scrivere in Xero o QuickBooks. Sono quelli su cui vale la pena farsi chiedere conferma.

Gli importi sono sempre indicati due volte

Uno spazio può contenere documenti in più valute. Qualsiasi strumento che restituisce un importo lo restituisce nella valuta propria del documento e nella valuta di rendicontazione dello spazio, convertita al tasso fissato su quel documento. Solo la seconda è confrontabile tra documenti, e le istruzioni del server dicono al modello di non sommare mai due importi in valute diverse. Dove nessun tasso copriva una data, la cifra di rendicontazione è null invece di zero.

I totali vengono dallo strumento di reportistica

run_report risponde alle domande «quanto». Gli strumenti di elenco elencano; sommare un elenco non è la stessa aritmetica — bozze e note di credito si contano diversamente — e la descrizione di ogni strumento dice quale sia.

Che cosa legge il server e che cosa conserva

Una chiamata a uno strumento legge e scrive i dati del tuo spazio: le tue fatture, spese, contatti, prodotti e impostazioni. Le risposte contengono i record richiesti — per un contatto il nome, e può includere un indirizzo e-mail, un indirizzo postale o una partita IVA, perché sono i dati che compaiono su una fattura.

Il server non conserva alcuna copia separata di una conversazione, non invia alcuna risposta di uno strumento altrove che al client che l’ha chiesta e non restituisce mai credenziali, chiavi API o token OAuth — né tuoi né di un servizio collegato. Che cosa facciamo dei dati in generale, compreso quali terzi ricevono cosa, è nell’informativa sulla privacy, e i termini valgono per questa connessione come per qualsiasi altra.

Disconnettersi

Rimuovi la connessione nel tuo client MCP. È sufficiente: il token è l’unica cosa che concede l’accesso e dalla nostra parte nulla continua a funzionare senza di esso. Eliminare il tuo account invoiso rimuove tutto ciò che c’è dietro — l’informativa sulla privacy dice che cosa significa e quanto tempo richiede.

Dettagli del protocollo

Il server negozia 2025-06-18, 2025-03-26 e 2024-11-05, rispondendo con la più recente che sia lui sia il client comprendono. A una versione non riconosciuta risponde con la più recente che supportiamo anziché rifiutarla, come chiede la specifica.

L’autorizzazione segue OAuth 2.1 con PKCE. La discovery sono i metadati di risorsa protetta RFC 9728 su https://www.invoiso.com/.well-known/oauth-protected-resource, e il server di autorizzazione pubblica sia il documento RFC 8414 sia quello OpenID Connect. I client si registrano da soli tramite registrazione dinamica (RFC 7591), ed è per questo che i passaggi sopra non chiedono altro che un URL. L’endpoint di registrazione è annunciato solo sul documento RFC 8414; un client che legge solo quello OpenID Connect non lo troverà e avrà bisogno del client id predefinito qui sotto.

Se il tuo client non riesce a registrarsi da solo e chiede un client id, scrivi a support@invoiso.com e te ne daremo uno. Lascia vuoto il client secret — il client è pubblico e si autentica con PKCE.

I token sono verificati contro il JWKS della nostra istanza e devono portare il nostro issuer e lo scope che nomina il tuo spazio. Un token emesso da un altro deployment di invoiso, o da un’altra istanza Clerk, viene rifiutato. Un token di un’altra applicazione registrata su questa istanza non è distinguibile dal nostro e viene accettato — è questo che significa registrazione aperta, ed è il motivo per cui vale la pena leggere la schermata di consenso, che nomina l’applicazione che chiede, prima di approvarla.

Se qualcosa non va

Scrivi a support@invoiso.com indicando che cosa ha chiesto il tuo client e che cosa è tornato indietro. Un 401 di solito significa che la connessione va riapprovata; un 403 che nomina uno scope significa che il client non l’ha chiesto; e un rifiuto che nomina il tuo piano è il limite di sola lettura qui sopra, non un guasto.