MCP: collegare strumenti e fonti
MCP offre un contratto tra un client AI e server che espongono strumenti o risorse. Il valore non è «collegare tutto», ma rendere capacità e dati espliciti, ispezionabili e limitati al compito.
Cosa affronti, passo dopo passo
Client, server, strumenti, risorse e prompt
MCP, Model Context Protocol, è un contratto che permette a un'applicazione con un agente di scoprire e usare capacità esterne in modo strutturato. Per ragionarci bene devi separare chi chiede, chi espone la capacità e il sistema che svolge davvero il lavoro.
Il client gestisce la sessione dell’agente. Il server MCP può esporre strumenti, risorse e prompt: uno strumento esegue un’operazione con input strutturato, una risorsa fornisce contenuto leggibile, un prompt offre una richiesta riutilizzabile. In Claude Code puoi richiamare le risorse con `@`; i prompt MCP appaiono come comandi.
Il servizio finale, come GitHub o un filesystem, può trovarsi dietro il server. Nomi vaghi e schemi incompleti aumentano chiamate sbagliate anche se la connessione funziona. Con Tool Search, Claude Code scopre gli schemi completi quando servono: descrizioni precise restano quindi essenziali.
Un operatore chiede se il ricambio `BRK-204` è disponibile e quale politica di reso si applica. Il gestionale di magazzino resta dietro un server MCP.
- Il client scopre `getInventory`, strumento in sola lettura con input obbligatorio `sku`, e `return-policy`, risorsa testuale versionata e senza dati cliente.
- L'agente usa la risorsa per leggere le condizioni generali, poi propone la chiamata a `getInventory` con il solo codice `BRK-204`.
- Il server valida il codice, interroga il gestionale e restituisce quantità, sede e orario del dato; non espone credenziali o query interne.
- Se il gestionale non risponde, lo strumento restituisce `service_unavailable` e nessuna quantità stimata; l'operatore vede che la disponibilità non è stata verificata.
Risultato: Politica e disponibilità restano due capacità riconoscibili. L'agente può citare la fonte letta e non trasforma un errore del magazzino in una risposta inventata.
Locale o remoto è una decisione di fiducia
Locale e remoto non descrivono soltanto dove gira un server MCP. Descrivono un confine di fiducia: quali dati lasciano la macchina, quale identità li può leggere e da quale servizio dipendi per continuare a lavorare.
Un server locale usa normalmente un processo `stdio`; un server remoto usa normalmente HTTP. Locale non significa offline: quel processo può comunque chiamare Internet. Un server remoto centralizza aggiornamenti e disponibilità, ma invia dati oltre il confine della macchina. Valuta provenienza, dati trasmessi, latenza e comportamento quando il servizio non risponde.
Disegna il confine prima della configurazione: quali dati escono, chi li riceve, per quanto tempo esistono e quale identità autorizza l’operazione?
Il team legale vuole cercare termini di rinnovo in una cartella di contratti clienti. Un servizio remoto sarebbe più facile da aggiornare, ma riceverebbe il testo dei documenti.
- Classifica i dati e traccia il flusso: query, estratti di contratto, nomi dei clienti, log e risultati. Conferma che i documenti non siano autorizzati a uscire dalla macchina.
- Scegli un server locale in sola lettura, confinato alla cartella approvata; escludi allegati, cartelle temporanee e collegamenti simbolici diretti altrove.
- Espone `searchClauses` con query e limite risultati; restituisce percorso relativo, breve estratto e pagina, senza copiare il documento completo nel log.
- Spegni la rete durante la prova, tenta un percorso escluso e simula un PDF illeggibile; verifica che ogni errore sia distinto e che nessun file venga modificato.
Risultato: La ricerca resta utile senza trasferire i contratti. Il costo della gestione locale è esplicito e il perimetro è testato anche nei casi di errore.
Scope e token minimi
Un token è una credenziale che rappresenta un'identità e le operazioni consentite. Gli scope sono i permessi associati. La regola pratica è semplice: concedi la capacità minima necessaria per il tempo minimo necessario.
Un token non deve essere più potente del compito. Per leggere issue non serve creare branch o amministrare il repository. Scope stretti limitano il danno se la credenziale viene sottratta, il server viene compromesso o una richiesta viene manipolata.
Non mostrare token in log, configurazioni condivise o screenshot. Prevedi rotazione e revoca. L’agente deve poter spiegare quale capacità richiede ogni permesso.
Un agente prepara il briefing del mattino leggendo titolo, severità e stato degli incidenti. Non deve chiuderli, modificare turni o vedere dati di fatturazione.
- Elenca le sole chiamate necessarie: lista incidenti e dettaglio di un incidente nell'ambiente di produzione; nessuna operazione di scrittura.
- Crea un'identità di servizio dedicata con `incidents:read`, scadenza breve e accesso al solo progetto interessato; conserva il token nel secret store.
- Configura il server perché filtri i campi restituiti e mascheri eventuali dati personali presenti nelle note prima di passarli al client.
- Prova lettura valida, tentativo di chiusura e token revocato: la prima riesce, la seconda è negata, la terza produce un errore di autenticazione senza stampare la credenziale.
Risultato: Il briefing contiene ciò che serve, mentre una chiamata sbagliata non può cambiare lo stato degli incidenti. La revoca è stata provata prima di dipendere dal collegamento.
Handshake, prova minima e diagnosi
Quando un collegamento MCP non funziona, «il server è rotto» è una conclusione troppo larga. La chiamata attraversa più strati e ciascuno può fallire in modo diverso: processo, configurazione, scoperta, autenticazione, validazione e servizio finale.
L’handshake è il saluto iniziale con cui client e server concordano versione e capacità. Verifica poi la connessione in strati: configurazione letta, processo o endpoint raggiungibile, inizializzazione riuscita, capacità disponibili, autenticazione valida e chiamata minima riuscita. In Claude Code, `/mcp` mostra stato e autenticazione del server.
I log devono mostrare nomi delle capacità, tempi e errori senza rivelare segreti. Se uno strumento è visibile ma fallisce, confronta lo schema degli argomenti e lo scope prima di cambiare server.
- Avvia e verifica che il processo del server sia raggiungibile.
- Controlla che il client legga la configurazione prevista.
- Ispeziona strumenti, risorse e relativi schemi scoperti.
- Esegui una sola chiamata in lettura con input noto.
- Registra risultato, durata e confine del guasto senza esporre token.
Il client dichiara la connessione attiva, ma l'agente non vede lo strumento che dovrebbe recuperare un ordine di prova.
- Controlla il processo con una richiesta di salute e conferma che il client usi il file di configurazione dell'ambiente di prova, non una copia precedente.
- Richiedi l'elenco delle capacità: scopri che il server pubblica `get_order`, mentre la documentazione e il client si aspettano `getOrder`.
- Allinea nome e schema, riavvia soltanto il componente necessario e verifica la scoperta prima di toccare token o servizio ordini.
- Esegui una lettura sull'ordine fittizio `TEST-104`; registra durata e stato. Poi prova ID vuoto e servizio indisponibile per confermare errori distinti e privi di segreti.
Risultato: Il guasto viene attribuito alla scoperta delle capacità, non all'autenticazione. La correzione è piccola e la suite di prove rende visibili eventuali problemi successivi.
Issue reader in sola lettura
Task Notes usa issue pubbliche come backlog, senza modificare il repository remoto.
Server: repository remoto verificato
Strumenti: listIssues, getIssue
Scope: contents:read, issues:read
Esclusi: createIssue, push, merge, admin
Prova: recupera una issue nota e registra il tempo di risposta