Qual è la differenza tra Risorse e Strumenti in MCP?

Gli Strumenti eseguono azioni contro l'API (creare fattura, elencare spese). Le Risorse espongono dati di riferimento statici che l'agente può consultare senza effettuare chiamate all'API. Aliquote fiscali, calendari fiscali o categorie di spesa sono sempre disponibili come contesto.

Cosa sono i Prompt MCP e come si usano?

I Prompt sono flussi di lavoro guidati che concatenano più strumenti in una sequenza logica. Invece di eseguire singole operazioni, un prompt come monthly-close guida l'agente passo dopo passo: revisionare le fatture in sospeso, categorizzare le spese, verificare gli obblighi fiscali.

Devo aggiornare qualcosa per usare la v1.2?

Se usi npx @frihet/mcp-server, ottieni l'ultima versione automaticamente. Se hai un'installazione fissa, aggiorna con npm update @frihet/mcp-server. Non ci sono cambiamenti di rottura rispetto alla v1.1.0.

MCP Server v1.2: risorse, prompt e output strutturato

La versione 1.2.1 del server MCP di Frihet non aggiunge più strumenti. Aggiunge intelligenza. Risorse affinché gli agenti abbiano contesto fiscale senza chiedere. Prompt affinché eseguano flussi completi senza intervento. Output strutturato affinché ogni risposta sia parsabile in modo deterministico.

Questo aggiornamento trasforma il server MCP da un ponte di operazioni CRUD a un’interfaccia di gestione aziendale completa per gli agenti AI.

Risorse: dati di riferimento sempre disponibili

Le Risorse MCP sono dati statici che l’agente può leggere in qualsiasi momento senza effettuare chiamate all’API di Frihet. Non consumano quota, non richiedono autenticazione aggiuntiva e sono disponibili dal momento in cui il server si connette.

La v1.2 introduce 5 risorse:

`frihet://api/schema`

Riepilogo di tutti gli endpoint disponibili, metodi di autenticazione e limiti di frequenza. Quando un agente ha bisogno di sapere cosa può fare con Frihet, consulta questa risorsa invece di scoprirlo per tentativi.

`frihet://tax/rates`

Aliquote fiscali vigenti in Spagna: IVA generale (21%), ridotta (10%) e super-ridotta (4%); IGIC canario (7%, 3%, 0%); ritenute IRPF. L’agente ha questo contesto prima di creare una fattura o registrare una spesa. Non ha bisogno di chiederti quale IVA applicare se sa già dove opera la tua attività.

`frihet://tax/calendar`

Date di presentazione delle dichiarazioni trimestrali: Modello 303 (IVA), Modello 130 (IRPF), Modello 420 (IGIC). Quando l’agente prepara una chiusura trimestrale, sa esattamente quando scade ogni obbligo.

`frihet://config/expense-categories`

Le 8 categorie di spesa con le loro regole di deducibilità. Materiale d’ufficio, forniture, trasporto, diarie, formazione, assicurazioni, servizi professionali, altro. Ogni categoria include la percentuale di deducibilità e le condizioni applicabili.

`frihet://config/invoice-statuses`

Il flusso degli stati di una fattura: bozza, emessa, inviata, incassata, scaduta, annullata. Ogni stato include le transizioni consentite e i trigger che possono essere attivati (webhook, notifiche). L’agente sa quali azioni sono valide in ogni momento.

Prompt: flussi di lavoro guidati

Uno Strumento esegue un’operazione. Un Prompt orquestra diverse operazioni in un flusso coerente. La differenza è passare da “crea questa spesa” a “elabora questi 15 scontrini di spesa, categorizzali, applica le imposte corrette e conferma prima di creare”.

La v1.2 include 5 prompt:

`monthly-close`

Chiusura mensile guidata. L’agente revisiona le fatture in sospeso, categorizza le spese non assegnate, verifica che gli obblighi fiscali del periodo siano coperti e genera un riepilogo. Un flusso che normalmente richiede un’ora di revisione manuale, eseguito in una conversazione.

`onboard-client`

Registrazione di un nuovo cliente. Determina il tipo di imposta in base alla posizione del cliente (IVA peninsulare, IGIC canario, intracomunitario), crea la registrazione con i dati fiscali corretti e genera un preventivo di benvenuto. Tutto in una sequenza.

`quarterly-tax-prep`

Preparazione trimestrale delle imposte. Raccoglie tutte le fatture del periodo, calcola le basi imponibili di IVA o IGIC, applica le ritenute IRPF e genera un’anteprima del Modello 303 o 130. L’agente svolge il lavoro; tu o il tuo commercialista validate il risultato.

`overdue-followup`

Sollecito fatture scadute. Identifica tutte le fatture fuori termine, le raggruppa per cliente, calcola l’importo totale in sospeso per ciascuno e redige messaggi di sollecito personalizzati. Da “devo controllare cosa mi devono” a “ecco le bozze pronte per l’invio”.

`expense-batch`

Elaborazione delle spese in lotti. Riceve un elenco di spese, le categorizza secondo le regole configurate, applica le imposte corrispondenti, verifica la deducibilità di ciascuna e le crea con conferma previa. Ideale per elaborare scontrini accumulati di una settimana o di un viaggio.

Output strutturato: risposte parsabili

Finora, le risposte del server MCP erano testo formattato. Utile per la lettura umana, ma gli agenti necessitano di dati strutturati per prendere decisioni programmatiche.

La v1.2 aggiunge outputSchema e structuredContent a ogni strumento. Ogni risposta include uno schema JSON che descrive esattamente la struttura dei dati restituiti. L’agente sa prima di chiamare quali campi riceverà, di che tipo sono e quali sono opzionali.

Questo è ciò che permette a un prompt come quarterly-tax-prep di concatenare 4 operazioni in modo affidabile: ogni passaggio produce dati con una struttura conosciuta che il passaggio successivo può consumare senza ambiguità.

Per gli sviluppatori che costruiscono integrazioni sul server MCP, questo elimina la necessità di parsare testo libero. La risposta ha sempre la stessa forma.

Annotazioni di sicurezza

Ogni strumento del server MCP ora include annotazioni che indicano se l’operazione è di sola lettura o distruttiva. Un list-invoices è contrassegnato come lettura. Un delete-expense è contrassegnato come distruttivo.

Questo permette agli agenti di implementare politiche di conferma. Un agente può eseguire operazioni di lettura senza chiedere, ma richiedere conferma esplicita prima di eliminare o modificare i dati. La sicurezza non dipende dall’agente — viene definita dal server.

Installazione universale

Il server si installa con un solo comando in qualsiasi agente compatibile:

npx @frihet/mcp-server

Funziona in Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Codex e qualsiasi client MCP. Per gli agenti che supportano l’installazione tramite skills:

npx skills add Frihet-io/frihet-mcp

Entrambi i metodi danno accesso a oltre 30 strumenti, alle 5 risorse, ai 5 prompt e all’output strutturato.

Repository sotto Frihet-io

Il server MCP è stato trasferito all’organizzazione Frihet-io su GitHub. L’URL del repository è ora github.com/Frihet-io/frihet-mcp. I link precedenti reindirizzano automaticamente.

Il pacchetto npm rimane @frihet/mcp-server. Non ci sono cambiamenti nell’installazione.

A chi è rivolto questo aggiornamento

Professionisti che già usano il server MCP ottengono Risorse come contesto fiscale automatico e Prompt come flussi che prima eseguivano passo dopo passo manualmente.

Sviluppatori che costruiscono su Frihet ottengono output strutturato per integrazioni deterministiche e annotazioni di sicurezza per politiche di conferma.

Studi di consulenza e commercialisti ottengono prompt specifici per i loro flussi di lavoro: chiusura mensile, preparazione trimestrale, monitoraggio degli incassi.

Qualsiasi attività che utilizzi agenti AI ottiene un server MCP che non solo esegue operazioni, ma sa come concatenarle in flussi di business reali.

Come aggiornare

Se usi npx @frihet/mcp-server, hai già l’ultima versione. Se hai un’installazione fissa:

npm update @frihet/mcp-server

Non ci sono cambiamenti di rottura. Tutti gli strumenti esistenti mantengono la loro interfaccia. Le Risorse, i Prompt e l’output strutturato sono aggiunte pure.

La documentazione completa è su docs.frihet.io/desarrolladores. Il codice sorgente su GitHub (Frihet-io/frihet-mcp). Il pacchetto su npm come @frihet/mcp-server.