🔧 Configurazione Server MCP - Excel Custom

Guida completa per configurare il server MCP (Model Context Protocol) per ricerche su file Excel con il tuo assistente AI4CALL

Vai in "MARKET" → "Marketplace Plugin" e clicca su Acquista di "Excel Search" → FREE

Vai in "MARKET" → "I Miei Plugin" e clicca su Configura di "Excel Search"

🚀 Navigazione rapida:

⚠️ Servizi di terze parti

Le integrazioni descritte fanno riferimento a servizi di terze parti.
Rate limit, modalità di autenticazione, configurazioni tecniche, costi e policy sono definiti esclusivamente dai rispettivi provider e possono variare nel tempo.

I costi dei servizi esterni sono sostenuti direttamente dall’utente finale a favore dei fornitori dei servizi stessi e non sono in alcun modo gestiti o intermediati dal nostro portale (es. Meta o altri fornitori per WhatsApp, Zapier, Calendly, ecc.).

⚠️ IMPORTANTE DA SAPERE PRIMA DI INIZIARE

Il server MCP può esporre UN SOLO file Excel alla volta come tool "search_excel".

Puoi caricare e configurare tutti i file che vuoi, ma l'assistente AI potrà usare solo quello che hai esplicitamente attivato con il bottone "ATTIVA EXCEL".

Quando attivi un nuovo file, il server MCP sostituisce automaticamente il file precedente. Gli altri file rimangono salvati nel sistema ma non sono esposti come tool fino all'attivazione.

Schermata di configurazione: upload dei file, selezione del worksheet, definizione del tool e delle colonne

Carica il tuo file Excel

Inizia caricando il file Excel che contiene i dati su cui vuoi effettuare le ricerche.

🎯 Cosa fare:

Vai alla sezione "Upload Nuovo Excel"
Clicca su "Scegli il file"
Seleziona il file dal tuo computer (formati supportati: .xlsx, .xls)
Il file apparirà nella lista "Excel Disponibili"

💡 Nota bene

Il primo file caricato viene automaticamente preselezionato come "Excel da configurare", ma NON è ancora attivo per il server MCP finché non completi tutti i passaggi di configurazione e clicchi "ATTIVA EXCEL"!

Puoi caricare più file e configurarli tutti, ma ricorda: il server MCP userà solo quello che hai esplicitamente attivato.

Seleziona il foglio di lavoro

Il server MCP può lavorare su UN SOLO foglio alla volta. Scegli quale foglio specifico del tuo file Excel vuoi esporre come ricercabile.

🎯 Cosa fare:

Nella sezione "Excel da configurare", seleziona il file che vuoi configurare dalla lista a tendina
Scorri fino alla sezione "Seleziona Worksheet"
Apri il menu a tendina e scegli il foglio che ti interessa
Vedrai informazioni come: "StatisticheOperatività (29 colonne, 1000 righe)"

⚠️ Attenzione

Quando selezioni un foglio, il server MCP leggerà TUTTE le colonne di quel foglio e le mostrerà nella sezione successiva per il mapping.

Se il tuo Excel ha più fogli (es. "Gennaio", "Febbraio", "Settembre"), devi scegliere quale specifico foglio esporre. Non puoi attivare più fogli contemporaneamente - il server MCP lavorerà solo sul foglio selezionato.

Assicurati di scegliere il foglio corretto prima di procedere con il mapping delle colonne!

Configura il tool MCP

Definisci i parametri che l'assistente userà per identificare e utilizzare questo specifico file Excel tramite il server MCP.

🔌 Come funziona il server MCP?

Il Model Context Protocol (MCP) è un server che espone "tool" all'assistente AI. Quando configuri questo Excel:

Il server MCP crea un tool chiamato "search_excel"
La descrizione del tool dice all'LLM: "Quando l'utente chiede X, invoca questo tool"
Le colonne mappate diventano parametri dinamici del tool
Le descrizioni delle colonne dicono all'LLM: "Per cercare Y, usa il parametro Z"

In pratica: Più sei preciso e dettagliato nelle descrizioni, meglio l'assistente capirà QUANDO e COME usare questo Excel!

📝 Campi da compilare:

Nome Tool: OBBLIGATORIO
Identificatore univoco del tool MCP (es. Excel_OCClient_1 o Excel_Settembre)
→ L'assistente userà questo nome per invocare il tool tramite MCP
Max Risultati: OBBLIGATORIO
Numero massimo di righe da restituire in una ricerca (es. 100)
→ Limita tecnicamente i risultati restituiti dal server MCP
Descrizione: FONDAMENTALE
Spiega in modo chiaro cosa contiene questo Excel e quando usarlo
Esempio CORRETTO: "Database completo clienti con storico chiamate e operatività di Ottobre 2024"
Esempio SBAGLIATO: ~~"File Excel"~~ o ~~"Dati"~~
→ L'LLM usa questa descrizione per decidere SE invocare questo tool! Sii specifico!

💡 Esempi di descrizioni efficaci per il tool MCP

Invece di scrivere descrizioni generiche, sii SPECIFICO sul contenuto e l'uso:

❌ SBAGLIATO: "File Excel clienti"
✅ CORRETTO: "Database completo clienti attivi con storico chiamate, operatività e statistiche relative al mese di Ottobre 2024"

❌ SBAGLIATO: "Dati settembre"
✅ CORRETTO: "Statistiche operative settimanali di tutti gli operatori del call center per il periodo 1-30 Settembre 2024, include tempi di risposta e numero chiamate gestite"

❌ SBAGLIATO: "Excel sonixis"
✅ CORRETTO: "Report esportato da Sonixis contenente dettagli tecnici e anagrafici di tutte le chiamate ricevute, con timestamp, durata, esito e identificativo operatore"

Perché questo è importante?
L'LLM legge queste descrizioni per capire SE deve invocare questo tool. Più sei dettagliato su COSA contiene e QUANDO usarlo, meglio l'assistente capirà quando cercare in questo Excel invece che dare una risposta generica.

Mappa le colonne ricercabili

Questa è la parte PIÙ IMPORTANTE: decidi quali colonne del tuo Excel potranno essere usate dall'assistente per fare ricerche.

⚠️ REGOLA D'ORO

Solo le colonne con il toggle ATTIVO (🟢) saranno ricercabili!
Le colonne disattivate (⚪) esistono nel file ma l'assistente NON potrà usarle come filtri di ricerca.

⚠️ ATTENZIONE AL TIPO DI DATO

Il tipo di dato influenza direttamente come il server MCP fa le ricerche:

Testo: ricerca per contenuto/somiglianza (es. "Mario" trova "Mario Rossi")
Numero: confronto esatto o per range (es. cercando "42" trova solo esattamente 42, non "42abc")
Data: confronto temporale (es. dopo il, prima del, tra date)
Booleano: valori vero/falso (true/false, 1/0)

Se sbagli il tipo, le ricerche falliranno! Es. se una colonna contiene numeri tipo ID cliente (12345) ma imposti "Testo", il confronto non funzionerà correttamente.

🗂️ Per ogni colonna devi configurare:

Abilitata: Toggle ON/OFF (🟢/⚪) CRITICO
→ Solo le colonne ABILITATE (🟢) diventano parametri disponibili nel tool MCP!
→ Se disabiliti una colonna, l'assistente NON potrà cercare su di essa, anche se esiste nel file
Colonna: Nome automatico rilevato dall'intestazione del foglio Excel
→ Es. "Id", "Utente", "IdOperatore", "AfterCallWork", "Staffed"
Tipo: OBBLIGATORIO
Formato del dato - serve all'MCP per fare i confronti corretti
Opzioni: Testo (ricerca per somiglianza), Numero (confronto esatto/range), Data (confronto temporale), Booleano (vero/falso)
→ IMPORTANTE: Scegli il tipo corretto! Se metti "Testo" su una colonna numerica, le ricerche falliranno!
Descrizione: FONDAMENTALE
Spiega cosa contiene la colonna e quando l'LLM deve usarla
Esempi CORRETTI:
- "Codice univoco identificativo del cliente"
- "Nome completo dell'operatore che ha gestito la chiamata"
- "Timestamp della data e ora della chiamata"
- "Numero di telefono del cliente che ha chiamato"
Esempi SBAGLI ATI: ~~"Id"~~, ~~"Dati"~~, ~~"Campo"~~
→ L'LLM usa questa descrizione per capire SU QUALE colonna cercare quando l'utente fa una domanda!

💡 Esempio pratico di mapping MCP

Hai un Excel con dati clienti. Vuoi che l'assistente possa cercare per nome cliente e città, ma NON per note interne:

Configurazione mapping:

✅ Colonna "CLIENTE" → Toggle ON (🟢)
• Tipo: Testo
• Descrizione: "Nome completo del cliente (cognome e nome)"
✅ Colonna "CITTA" → Toggle ON (🟢)
• Tipo: Testo
• Descrizione: "Città di residenza del cliente"
❌ Colonna "NOTE_INTERNE" → Toggle OFF (⚪)
• Non configurata = non ricercabile

Risultato MCP: Il server genera un tool con parametri dinamici CLIENTE e CITTA

Esempio di utilizzo:
Utente chiede: "Cerca Mario Rossi a Milano"
→ L'LLM invoca: search_excel(CLIENTE="Mario Rossi", CITTA="Milano")
→ L'assistente trova i risultati filtrati per entrambi i parametri
→ Le NOTE_INTERNE non sono accessibili all'assistente

📊 Indicatore di progresso

In alto vedrai un contatore tipo (3/29) che indica:
→ 3 colonne mappate (attivate)
→ 29 colonne totali disponibili nel foglio

Attiva l'Excel per il server MCP

Ultimo passaggio: rendi il file Excel effettivamente esposto dal server MCP all'assistente AI.

⚠️ ⚠️ NON DIMENTICARE QUESTO STEP!

Anche se hai configurato tutto perfettamente, se non clicchi "ATTIVA EXCEL" il tool MCP NON sarà esposto!
Questo passaggio finale "dice" al server MCP: "Usa QUESTO file quando l'assistente invoca il tool search_excel"

🎯 Cosa fare:

Dopo aver completato la configurazione e il mapping delle colonne
Scorri fino in fondo alla pagina
Troverai un bottone verde con scritto "ATTIVA EXCEL"
Cliccaci sopra
Il server MCP caricherà questo file e lo esporrà come tool disponibile all'assistente

🔌 Cosa succede quando attivi l'Excel?

Quando clicchi "ATTIVA EXCEL":

Il server MCP carica il file selezionato in memoria
Crea un tool chiamato search_excel con i parametri dinamici basati sulle colonne mappate
Espone il tool all'assistente AI con la descrizione che hai scritto
L'assistente può ora invocare il tool quando l'utente fa domande pertinenti

Se c'era un altro Excel attivo, viene automaticamente disattivato e sostituito con quello nuovo.

🔄 Cambiare file attivo

Se in futuro vorrai usare un altro file Excel:

Seleziona il nuovo file dalla lista "Excel da configurare"
Clicca su "ATTIVA EXCEL"
Il vecchio file verrà automaticamente disattivato dal server MCP
Il nuovo file diventa quello esposto come tool all'assistente

Importante: Un solo file alla volta può essere esposto dal server MCP. Non è possibile avere 2 Excel attivi contemporaneamente.

✅ Configurazione completata!

Una volta attivato l'Excel, il server MCP esporrà il tool search_excel all'assistente. L'AI potrà ora invocare questo tool per cercare informazioni nei dati che hai configurato.

Prova a fare una domanda all'assistente che richieda di cercare nei dati del tuo Excel!

🎯 RIEPILOGO RAPIDO - Configurazione Server MCP

Carica il file Excel → Sezione "Upload Nuovo Excel"
Seleziona il foglio di lavoro → Dropdown "Seleziona Worksheet"
Configura tool MCP: Nome univoco + DESCRIZIONE DETTAGLIATA (fondamentale!) + Max risultati
Mappa colonne: Attiva toggle (🟢) + Tipo corretto + DESCRIZIONE SPECIFICA di ogni colonna
Attiva l'Excel → Bottone verde "ATTIVA EXCEL" (senza questo NON funziona!)

⚡ RICORDA: Le descrizioni (del tool e delle colonne) sono FONDAMENTALI perché vengono lette dall'LLM per capire QUANDO invocare il tool MCP e QUALI parametri usare. Non sono opzionali!

❓ Domande frequenti

Le risposte alle domande più comuni sulla configurazione Excel Custom

? Posso usare più file Excel contemporaneamente per le ricerche?

No. Il server MCP può esporre un solo file Excel alla volta come tool "search_excel". Puoi caricare e configurare più file, ma solo quello attivato con il bottone "ATTIVA EXCEL" sarà utilizzabile dall'assistente. Gli altri restano salvati ma non esposti.

? Come faccio a cambiare il file Excel attivo?

Seleziona il nuovo file dalla lista "Excel da configurare", poi clicca "ATTIVA EXCEL". Il server MCP sostituirà automaticamente il file precedente con quello nuovo. La sostituzione è istantanea.

? Cosa succede se non mappo alcune colonne del mio Excel?

Le colonne non mappate (con toggle disattivato) NON diventano parametri del tool MCP. L'assistente non potrà cercare su quelle colonne, anche se i dati esistono nel file. Solo le colonne con toggle attivo sono esposte come parametri ricercabili.

? Perché la descrizione del tool è così importante?

La descrizione viene letta dall'LLM per decidere QUANDO invocare il tool MCP. Se scrivi "File Excel" l'AI non saprà quando usarlo. Se scrivi "Database clienti con storico chiamate di Ottobre 2024" l'AI capirà esattamente quando cercare in questo file. Più sei specifico, meglio funziona.

? A cosa serve la descrizione di ogni singola colonna?

L'LLM usa le descrizioni delle colonne per capire SU QUALE parametro cercare. Se l'utente chiede "cerca il cliente Mario Rossi", l'AI deve sapere che "CLIENTE" è la colonna giusta da usare. Senza descrizioni chiare, l'AI non sa quale parametro invocare nel tool MCP.

? Cosa significa il tipo di dato (Testo/Numero/Data) nelle colonne?

Il tipo di dato determina come il server MCP fa i confronti: Testo = ricerca per somiglianza/contenuto, Numero = confronto esatto o per range, Data = confronto temporale, Booleano = vero/falso. Se sbagli tipo (es. metti Testo su ID numerici), le ricerche falliranno.

? Posso configurare più fogli (worksheet) dello stesso Excel?

No. Il server MCP lavora su UN SOLO foglio alla volta. Se il tuo Excel ha più fogli, devi scegliere quale specifico foglio esporre nella sezione "Seleziona Worksheet". Non è possibile attivare contemporaneamente più fogli dello stesso file.

? Cosa succede quando clicco su "ATTIVA EXCEL"?

Il server MCP carica il file selezionato in memoria, crea il tool "search_excel" con i parametri dinamici basati sulle colonne mappate, e lo espone all'assistente AI con la descrizione configurata. Da quel momento l'assistente può invocare il tool per cercare nei dati.

? Come faccio a sapere quante colonne ho mappato?

Nella sezione "Mapping Colonne" vedrai un contatore tipo (3/29) che indica: 3 colonne mappate (attivate) su 29 colonne totali disponibili nel foglio. Il numero cambia in tempo reale mentre attivi/disattivi i toggle.

? Posso cambiare il mapping delle colonne dopo aver attivato l'Excel?

Sì. Puoi tornare sulla configurazione, modificare le colonne mappate (attivare/disattivare toggle, cambiare tipi, aggiornare descrizioni) e poi cliccare nuovamente "ATTIVA EXCEL" per applicare le modifiche. Il server MCP ricaricherà il file con la nuova configurazione.

? A cosa serve il campo "Max Risultati" nella configurazione?

Limita tecnicamente il numero massimo di righe che il server MCP restituisce in una singola chiamata del tool. Se imposti 100 e la ricerca trova 500 risultati, il server restituirà solo i primi 100. Previene risposte troppo lunghe che potrebbero saturare il contesto dell'LLM.

? L'assistente può cercare su più colonne contemporaneamente?

Sì. L'assistente può invocare il tool MCP passando più parametri contemporaneamente. Ad esempio: search_excel(CLIENTE="Mario Rossi", CITTA="Milano") cercherà risultati che matchano ENTRAMBI i criteri. Tutte le colonne mappate sono utilizzabili insieme.

? Cosa succede se elimino un file Excel attivo?

Se elimini il file attualmente attivo, il tool MCP smetterà di funzionare immediatamente. L'assistente non potrà più invocare search_excel finché non attivi un altro file Excel configurato. Gli altri file caricati non vengono influenzati dall'eliminazione.

? Posso usare lo stesso nome per più tool Excel?

No. Il nome del tool deve essere univoco. Se provi a creare due configurazioni con lo stesso nome (es. "Excel_Clienti"), il server MCP andrà in conflitto. Usa nomi diversi tipo "Excel_Clienti_Gennaio", "Excel_Clienti_Febbraio" per distinguerli.

? Il server MCP supporta formule Excel nelle celle?

Il server MCP legge solo i VALORI risultanti delle celle, non le formule. Se una cella contiene una formula che calcola "100", il server vedrà "100". Le formule non vengono eseguite dal server MCP, vengono letti solo i valori già calcolati nel file.