Un solo ponte, per tutti
I custom tool che parlano con Kross o Stripe non chiamano quei sistemi direttamente: passano tutti per lo stesso indirizzo,mcp.mattone.co (l’MCP Gateway, multi-tenant). Non esiste un dominio per cliente e non esiste un ponte “tutto suo” per nessuno studente: il cliente si riconosce dal token dentro il codice del tool, non dall’URL che chiama. Quel token lo scrive la piattaforma quando crea o allinea i tool — non è un secret che si crea o si sposta a mano nel workspace.
Per Kross, il ponte serve due modelli diversi dietro lo stesso indirizzo — nuovo studente (chiave generica nostra) o cliente con una sua chiave già esistente. Come riconoscerli e cosa cambia: Kross → Prima di iniziare: partner o own?.
Regola d’oro: tool + skill sempre insieme
Aggiungere un tool senza la skill che spiega all’agente quando e come usarlo è equivalente a non aggiungerlo. L’agente Conduit non “scopre” autonomamente i tool disponibili: deve ricevere istruzioni esplicite tramite la skill su quale trigger usare il tool, quali parametri passare e come interpretare la risposta.🔴 L’agente legge la description del TUO workspace, non quella del gateway
È la trappola che ci è costata una giornata l’08/09/2026, e ricapiterà a chiunque non la conosca. Il pontemcp.mattone.co ha imparato a cercare la prenotazione anche per codice di canale (quello che l’ospite cita davvero: Airbnb, Booking, Vrbo) e a mostrare le cancellate. Mergiato, deployato, provato in produzione con un codice Booking vero: funziona.
Sul campo non è cambiato niente, perché l’agente non legge mai la description scritta nel gateway: legge quella del custom tool montato sul suo workspace, che diceva ancora «codice prenotazione Kross (es. 375/2026)» e basta.
Ma non propagare a mano su tutta la flotta
Sembra ovvio dire «allora copiamo la description canonica ovunque». È sbagliato, ed è pericoloso. Censimento dell’08/09 sui sei workspace che montano i tool Kross:
Sono in due lingue e personalizzate per cliente: tre workspace su sei hanno testi scritti apposta per quel cliente. Una propagazione «canonica» riscriverebbe in inglese le description italiane di clienti paganti. E un controllo che confronta con la canonica risulterebbe rosso su tutti, per sempre, quindi verrebbe spento in una settimana.
Se vuoi un controllo di allineamento, confronta il codice del tool, non la description. Lì la divergenza è vera: tre workspace su sei non hanno il retry con backoff né il timeout che hanno gli altri.⚠️ Ma non è grave quanto sembra, ed è stato misurato l’08/09/2026. Anche quei tre trasformano un errore in un «sistema occupato» e non lo mostrano mai crudo all’ospite. E soprattutto il ponte ritenta già al posto loro: davanti a un errore passeggero di Kross riprova internamente e risponde comunque con un esito buono, mai con un errore. Quello che a quei tre manca non è la protezione, è il recupero — e il recupero arriva dal ponte, gratis.
Aggiornato il 10/09/2026. Il censimento qui sopra è quello che ha portato alla decisione di una versione sola per tutti gli studenti. «Non a mano» resta vero: la versione nuova si porta sui workspace con lo script di allineamento e con la procedura Quando esce una versione nuova dei tool, che prima di scrivere ferma ogni testo scritto apposta per un cliente e lo sposta dove deve stare (skill, KB, istruzioni dell’agente).
Il ponte non restituisce mai un errore di trasporto
Verificato in esecuzione su sei classi di guasto (errore del server Kross persistente e passeggero, limite di frequenza superato, timeout, risposta malformata, credenziali rifiutate): la risposta è sempre un esito buono con un messaggio parlante dentro, mai un errore di trasporto.Il canale che invece funziona già, gratis
Quando il ponte non trova la prenotazione non risponde «non c’è»: risponde dicendo dove ha cercato e chiedendo all’ospite il codice, sia quello Kross sia quello del canale. Quel testo arriva all’agente di tutti i workspace senza toccare nessuna configurazione. Quindi la capacità nuova, al secondo giro, è già disponibile ovunque. Quello che manca è che l’agente la chieda al primo, ed è esattamente ciò che una riga di description in più otterrebbe.Catalogo tool disponibili
Kross (prenotazioni e check-in)
Smart Lock (serrature)
Stripe (pagamenti)
Chi li monta
I custom tool sono provisionati esclusivamente dal team Mattone durante l’onboarding o su richiesta successiva. Lo studente non ha accesso alla configurazione dei tool. Il catalogo completo dei tool disponibili e i loro parametri sono documentati nel catalogo MCP.Due errori di provisioning da non ripetere
Tutti e due sono successi davvero, e tutti e due li avevamo messi noi, montando i tool. Lo studente non c’entra: non ha nemmeno accesso alla configurazione.1. Mai un dato vero come esempio in una description
Le description dei tool e dei loro parametri entrano nel contesto del modello a ogni turno di conversazione. Un nome, un telefono o un’email scritti lì come «esempio di formato» vengono ripresentati all’AI a ogni messaggio di qualunque ospite, su qualunque appartamento. Il 10/09/2026, su un workspace studente, la description di un parametro portava come esempio nome, cognome e cellulare di un ospite reale, preso da una conversazione. È stato corretto; gli altri workspace controllati erano puliti.
Il formato si descrive a parole. Se un esempio serve davvero, dev’essere palesemente finto.
2. Mai il token in chiaro dentro il codice
Il token del gateway è l’identità del cliente: chi ce l’ha, per il gateway, è quel cliente. Scritto come stringa letterale nel campocode del tool, viene restituito da list_custom_tools a chiunque abbia un token API di Conduit.
Dall’ottobre 2026 il codice canonico dei tool legge il token da una Variable di workspace di Conduit (Settings → Variables), e usa il token scritto nel codice solo come ripiego finché la Variable non è impostata. Le Variables non si impostano da programma: è un passo manuale, da dashboard, ed è obbligatorio nel provisioning di ogni studente.
1
Crea o allinea i tool dalla piattaforma
Il codice del tool contiene già la riga che legge la Variable: il nome esatto della Variable è scritto lì.
2
Imposta la Variable nel workspace dello studente
In Conduit: Settings → Variables, una Variable con quel nome e come valore il token dello studente (lo stesso che oggi è nel codice come ripiego).
3
Verifica
Una ricerca prenotazione dalla chat di test del workspace deve rispondere come prima. Il controllo settimanale della piattaforma segnala i workspace che usano ancora il ripiego.
no-pii-descriptions) impedisce che le sue description contengano email, telefoni o nomi tra virgolette. Protegge la sorgente centrale; le copie dentro i workspace restano responsabilità di chi le monta.
Una versione sola per tutti gli studenti
Tutti i workspace hanno la stessa versione di ogni tool. Stessa descrizione, stessi parametri, stesso codice. L’unica cosa che cambia da uno studente all’altro è il suo token. Il perché è misurato, non teorico: a un censimento, su trenta descrizioni montate nei workspace degli studenti nessuna era uguale a quella del gateway, e c’erano tre riscritture diverse. Un miglioramento fatto sul gateway non era arrivato a nessuno. In due workspace un parametro dichiarava un valore di default diverso da quello che il gateway usa davvero: l’agente riceveva un’informazione falsa.Cosa può essere diverso da uno studente all’altro, e dove sta
Una personalizzazione che non sta in questa tabella non è una personalizzazione, è una deriva. Se serve davvero, si scrive nel registro dello studente con il motivo, così chi viene dopo sa che è voluta.
Dopo ogni modifica, si rilegge
Ogni modifica a un tool, a una skill o a un agente si chiude rileggendo e confrontando: quello che si voleva cambiare è cambiato, e tutto il resto è rimasto identico — gli altri guardrail, le skill agganciate, la modalità, i trigger. Alcune API di Conduit non dichiarano di preservare i campi che non mandi: il controllo si fa, non si presume.Quando esce una versione nuova dei tool
Una versione nuova arriva a tutti gli studenti, ma un workspace alla volta, e senza toccare quello che di ogni studente è davvero suo. Chi fa cosa: il team tecnico rilascia e allinea; il delivery controlla le personalizzazioni con chi segue lo studente e legge le conversazioni del giorno dopo.Cosa si aggiorna e cosa no
Le personalizzazioni di uno studente stanno solo nella colonna di destra (la tabella «Cosa può essere diverso da uno studente all’altro», qui sopra). Il codice di un tool non è una personalizzazione: se in un workspace è diverso, o è una versione vecchia o è una deriva.
Da dove nasce una versione. C’è un solo generatore, nella platform: è lo stesso che usa il provisioning di un nuovo studente e lo stesso che usa lo script di allineamento. Descrizione e parametri dei tool Kross e Stripe il generatore li prende dal gateway in produzione, non dal codice nel repository: finché la modifica al gateway non è pubblicata, lo script allinea alla versione di prima. Nessuno scrive una versione a mano dentro un workspace.
Prima di scrivere
1
1. Il rilascio ha un nome (team tecnico)
La modifica entra nella platform (o nel gateway) con una PR unita. Quella PR è la versione: il suo numero è il nome del rilascio. Nella descrizione della PR, in piano: cosa cambia per l’agente, e se cambia il nome di un tool o di un parametro.Verifica: la PR è unita, e se la modifica tocca il gateway, il gateway in produzione la serve già.
2
2. Copia di sicurezza di ogni workspace (team tecnico)
Prima di qualunque scrittura si salva l’elenco completo dei custom tool di ogni workspace del rilascio, con tutti i campi, codice compreso: un file per workspace, con la data. Lo script non la fa da solo: si fa prima, a parte.La copia contiene dati riservati dello studente: si tiene fuori da qualunque repository, e mai in questa guida.Verifica: c’è un file per ogni workspace, e il numero di tool nel file è quello che si vede nella dashboard del workspace.
3
3. Confronto a secco (team tecnico)
Si lancia lo script di allineamento senza l’opzione di scrittura, su tutti i workspace del rilascio. Non scrive niente. Per ogni tool dice «già allineato» oppure «diverso in» e l’elenco dei campi (descrizione, parametri, codice…). Dice anche due cose su cui non agisce:
- un tool mancante lo segnala e basta: lo script allinea, non crea;
- un gruppo di tool con il token non univoco, o con lo stesso token di un altro gruppo, non lo tocca: è montato male e va sistemato a parte.
4
4. Controllo delle personalizzazioni (team tecnico + delivery)
Lo script non distingue una versione vecchia da una modifica fatta a mano: per lui sono entrambe «diverso». Quindi ogni differenza si legge.
- È soltanto la versione precedente → si va avanti.
- C’è qualcosa che non viene da nessuna nostra versione, ed è specifico di quello studente (una frase aggiunta alla descrizione, un parametro in più) → ci si ferma e il delivery chiede a chi segue lo studente perché c’è. Due uscite:
- era una deriva → si allinea;
- rispondeva a un bisogno vero di quello studente → il bisogno si sposta dove deve stare (skill, KB, istruzioni dell’agente o guardrail), si scrive nel registro dello studente con il motivo, e solo dopo si allinea.
- C’è un miglioramento nel codice del tool presente su più workspace e non nel generatore (un bug del wrapper corretto a mano, non una richiesta di un cliente) → non è una personalizzazione da spostare, e non si allinea alla versione vecchia. Prima si aggiorna il generatore (
codiceTool()inconduit-tool-canonici.ts) perché produca quel codice, poi si allinea la flotta alla versione nuova — quella con il fix.
Il rilascio, un workspace alla volta
1
5. Si parte da un workspace pilota in copilot (team tecnico)
Il primo workspace è uno in copilot: le risposte dell’agente passano da una persona prima di arrivare all’ospite. Mai uno in autopilot come primo.Si lancia lo script con l’opzione di scrittura, solo su quel workspace. Per ogni tool diverso scrive, rilegge e confronta campo per campo; se la rilettura non combacia si ferma su quel workspace e lo dice. Tocca solo descrizione, parametri, codice, linguaggio e messaggio di esecuzione.Verifica: ogni tool risulta «allineato e verificato», e l’esito finale dice zero workspace fermati.
2
6. Si rilegge campo per campo (team tecnico)
Lo script verifica i campi che ha scritto. Il resto si controlla a mano contro la copia del passo 2, come dopo ogni modifica: stesso numero di tool, stessi nomi, stessa abilitazione, skill ancora agganciate e attive, modalità dell’agente invariata.Verifica: nessuna differenza fuori dai campi del rilascio.
3
7. Si prova un tool in sola lettura (team tecnico o delivery)
Una conversazione di test nel workspace pilota, con una domanda che fa chiamare un tool che legge e basta: le date libere di un appartamento, o la ricerca di una prenotazione. Mai una prova con un tool che fa qualcosa nel mondo (link di pagamento, apertura porta).Verifica: nei log il tool è stato chiamato, con i parametri giusti, e la risposta contiene dati veri. Come si leggono: Come verificare che un tool funzioni.
4
8. Si guardano le conversazioni del giorno dopo (delivery)
Il giorno dopo si leggono le conversazioni vere del pilota in cui l’agente ha chiamato un tool: errori, risposte «non trovo», escalation in più rispetto al solito.Verifica: nessun errore di tool nuovo, escalation nella norma. Solo allora si prosegue.
5
9. Gli altri workspace, uno per volta (team tecnico)
Si ripetono i passi 5, 6 e 7 su un workspace alla volta: prima quelli in copilot, per ultimi quelli in autopilot. Se uno si ferma, gli altri aspettano finché non si è capito perché.Verifica: ogni workspace del rilascio ha il suo «allineato e verificato».
Ogni rilascio lascia traccia
1
10. Si scrive nella PR del rilascio (team tecnico, poi delivery)
Nella PR della versione (passo 1) si aggiunge un commento con: quale versione, quali workspace sono stati allineati, quando (data e ora, con il fuso), l’esito, e i workspace saltati con il motivo. Il delivery aggiunge l’esito del controllo del giorno dopo.Verifica: chi apre quella PR fra un mese sa, senza chiedere a nessuno, quale workspace ha quale versione.
Come si torna indietro
- Un solo workspace: si riscrivono dalla copia del passo 2 i campi che il rilascio aveva toccato (descrizione, parametri, codice, linguaggio, messaggio di esecuzione), e si rilegge come al passo 6.
- Tutti: si annulla la PR della versione (e la modifica al gateway, se era lì), poi si rilancia lo script: allinea alla versione di prima, con gli stessi passi, a secco, pilota, uno alla volta.
- Anche il ritorno indietro lascia traccia nella stessa PR, con il motivo.
Come verificare che un tool funzioni
Dopo aver montato un tool, esegui sempre questa verifica prima di dichiarare l’onboarding completato.1
Verifica che il tool appaia nell'elenco del workspace
Apri il workspace Conduit dello studente e vai nella sezione Tools. Controlla che il tool appena montato sia presente nell’elenco e risulti abilitato. Se non compare, il provisioning non è andato a buon fine: ripeti l’operazione dal catalogo.
2
Verifica che la skill abbinata esista e sia attiva
Vai nella sezione Skills del workspace. Cerca la skill corrispondente al tool (vedi tabella sopra). Verifica che sia in stato attivo, una skill salvata ma disabilitata ha lo stesso effetto di una skill assente: il tool viene ignorato.
3
Testa con un messaggio ospite realistico
Apri una conversazione di test nel workspace e invia un messaggio che dovrebbe attivare il tool. Per esempio, per
open-door invia “Puoi aprire la porta?”; per stripe-payment-link invia “Vorrei fare il late check-out, quanto costa?”. Usa un linguaggio naturale, non comandi tecnici, così validi che la skill funziona nelle condizioni reali.4
Controlla i log per confermare che il tool sia stato chiamato
Dopo il test, apri i log della conversazione e verifica che il tool sia stato chiamato esplicitamente (vedrai il nome del tool e i parametri passati). Se nei log compare il path nativo invece del tool, o se l’agente risponde genericamente senza chiamare il tool, la skill non sta funzionando: ricontrolla la formulazione e lo stato di attivazione.