Come integrare MCP in uno stack software esistente: architettura, sicurezza e rollout

La maggior parte delle aziende che valuta MCP non ha bisogno di un'altra piattaforma. Ha bisogno di un modo sicuro per permettere agli agenti AI di usare le piattaforme che possiede già.

I dati sono già nel database, le attività commerciali vivono nel CRM e le regole operative sono codificate nelle API. Autenticazione, ruoli, audit log e approvazioni esistono già. Ricostruire tutto per gli agenti sarebbe costoso e rischioso. Un livello Model Context Protocol può rendere disponibili le parti utili attraverso un'interfaccia standard, lasciando la fonte autorevole dei dati e delle regole al suo posto.

Il prototipo può sembrare semplice: si avvolge un'API, si descrivono alcuni tool e si collega un client. Un'integrazione pronta per la produzione richiede di più. Bisogna decidere cosa un agente può vedere e fare, tradurre le operazioni aziendali in tool stabili, preservare i confini di autorizzazione e rendere i fallimenti osservabili.

Cosa cambia con MCP e cosa non sostituisce

MCP è un protocollo aperto che collega applicazioni AI a capacità esterne. Un server può esporre tre elementi principali:

• Tool, con cui il modello richiede azioni, come creare un ticket o cercare un ordine.
• Risorse, che forniscono contesto, come una scheda cliente o un documento.
• Prompt, cioè template riutilizzabili per workflow specifici.

La documentazione ufficiale dei server MCP descrive queste primitive e il modo in cui i client interagiscono con esse.

MCP non sostituisce API gateway, permessi del database, servizi applicativi o interfacce prodotto. È un adattatore tra un host agentico e parti controllate del software aziendale. Il sistema esistente rimane la fonte autorevole; il server MCP diventa un'interfaccia intenzionalmente limitata.

Se l'API consente di rimborsare un ordine solo quando certe condizioni sono rispettate, il tool MCP dovrebbe chiamare quella stessa operazione. Non dovrebbe riprodurre una versione meno rigorosa della regola nel livello di protocollo.

Un'architettura di riferimento

Una configurazione pronta per la produzione contiene normalmente cinque livelli:

1. Host agentico: assistente desktop, coding agent, copilot interno o applicazione personalizzata.
2. Client MCP: scopre le capacità del server e scambia messaggi secondo il protocollo.
3. Server MCP: pubblica tool e risorse, valida gli input e traduce le richieste.
4. Identità e policy: autenticazione, autorizzazione, contesto utente, consenso, limiti e approvazioni.
5. Sistemi esistenti: API, database, SaaS, code, document store e servizi interni.

Il flusso è:

Intento utente → host agentico → client MCP → server autenticato → servizio esistente → risultato validato

Il server dovrebbe essere abbastanza sottile da lasciare le regole di business nell'applicazione, ma abbastanza strutturato da offrire all'agente operazioni sicure invece di accesso indiscriminato al backend.

Parti dai lavori da svolgere, non dagli endpoint

Un errore frequente è trasformare ogni endpoint REST in un tool MCP. Il risultato è una superficie ampia e confusa che scarica sul modello tutta l'orchestrazione.

Conviene partire dai lavori che l'agente deve completare:

• Recuperare lo stato di un ordine.
• Preparare il riepilogo di un caso di assistenza.
• Creare una bozza di follow-up nel CRM dopo approvazione.
• Confrontare l'utilizzo con i limiti del piano.
• Individuare gli errori collegati a una release.

Poi si progetta un tool coerente per ogni lavoro. Un tool come getcustomercontext può combinare account, attività recente e stato dell'assistenza dietro un unico schema. È più affidabile che chiedere al modello di chiamare quattro endpoint nell'ordine corretto e unire i risultati.

Un buon tool ha un nome orientato al business, una descrizione precisa, input piccoli e tipizzati, output prevedibili, errori espliciti, permessi legati all'identità corrente e una strategia di idempotenza per le scritture.

L'obiettivo non è esporre tutto. È esporre il set minimo di capacità che permette all'agente di completare lavoro utile in modo affidabile.

Quando basta avvolgere un'API

In genere incontriamo tre situazioni.

L'API rappresenta già operazioni di business

Il server MCP può chiamare servizi stabili, passare il contesto dell'utente autenticato e tradurre la risposta in una struttura adatta all'agente. Il livello di protocollo resta piccolo.

L'API è troppo vicina al database

Gli endpoint CRUD espongono meccaniche tecniche, non lavori utili. Conviene aggiungere un servizio applicativo deterministico che possa essere chiamato sia dal prodotto sia dal server MCP.

Non esiste un'API

L'accesso diretto al database può essere accettabile per risorse ristrette e in sola lettura. Le scritture dovrebbero passare da un servizio che possiede validazione e regole di business. Per SaaS esterni serve un connettore con retry, paginazione, gestione dei rate limit ed errori normalizzati.

Per questo implementare MCP è spesso un lavoro di integrazione full-stack. L'endpoint di protocollo è il risultato visibile; l'ingegneria decisiva avviene nei sistemi alle sue spalle.

L'autenticazione è solo il primo confine

Sapere chi si è collegato non basta. Il server deve decidere quali capacità quell'identità può scoprire e usare, quali record può leggere e quali azioni richiedono una conferma.

I controlli principali sono:

• Autenticazione: stabilire l'utente, il servizio o l'organizzazione dietro la sessione.
• Autorizzazione: verificare i permessi per ogni tool e risorsa usando, quando possibile, le stesse policy dell'applicazione.
• Isolamento dei tenant: legare il contesto organizzativo sul server, senza fidarsi di un tenant ID prodotto dal modello.
• Validazione: convalidare ogni argomento indipendentemente dallo schema mostrato al client.
• Filtraggio: rimuovere segreti, campi interni e dati personali non necessari.
• Approvazioni: richiedere conferma umana per azioni distruttive, finanziarie o esterne.
• Limiti: prevenire loop, uso incontrollato dei tool e carico accidentale sui sistemi a valle.
• Audit: registrare identità, tool, risultato e correlation ID senza salvare indiscriminatamente dati sensibili.

La prompt injection non scompare perché il tool è tipizzato. Gli argomenti prodotti dal modello restano input non affidabili. Per aziende italiane ed europee vanno inoltre definite finalità, minimizzazione, conservazione e accesso ai log in coerenza con il GDPR.

Letture e scritture richiedono rollout diversi

I tool in sola lettura sono un buon primo rilascio: mostrano come gli agenti scelgono le capacità e interpretano i risultati senza modificare lo stato aziendale.

Per le scritture il rischio va introdotto gradualmente:

1. Restituire un'azione proposta senza eseguirla.
2. Consentire all'utente di rivederla e approvarla.
3. Eseguire soltanto azioni reversibili o idempotenti.
4. Aggiungere autonomia ristretta solo dove rischio e valore lo giustificano.

Un agente può prima preparare una nota CRM e salvarla dopo approvazione. Invio di email, movimenti di denaro, cancellazione di dati e modifica dei permessi devono mantenere controlli più forti.

Testa il contratto e il comportamento dell'agente

I test tradizionali restano essenziali: schemi, autenticazione, autorizzazione, errori a valle, timeout, paginazione, concorrenza e retry. MCP aggiunge un livello: come i modelli scoprono e usano l'interfaccia.

Serve un set di valutazione con richieste realistiche. Bisogna misurare se l'agente sceglie il tool corretto, produce argomenti validi, evita azioni fuori perimetro, gestisce gli errori e restituisce il risultato senza inventare fatti.

Vanno inclusi casi avversariali: richieste tra tenant, istruzioni nascoste nei contenuti, risultati troppo grandi, scritture duplicate, credenziali scadute e fallimenti parziali.

L'obiettivo non è soltanto “il server ha restituito 200”. È “il lavoro dell'utente è stato completato in sicurezza e il sistema si è comportato in modo prevedibile quando non poteva completarlo”.

Osservabilità end-to-end

Il debugging è difficile quando le tracce dell'agente e i log applicativi vivono separati. Un correlation ID dovrebbe accompagnare la richiesta fino ai servizi a valle.

Conviene misurare invocazioni, successi, errori di validazione, permessi negati, latenza, dimensione dei risultati, chiamate ripetute, approvazioni accettate e costo per workflow. Conservazione e accesso alle tracce devono dipendere dalla sensibilità del caso d'uso, non dalla comodità del debug.

Un rollout che non richiede di rifare lo stack

Una sequenza sensata prevede cinque fasi:

1. Discovery: scegliere uno o due lavori ad alto valore e mappare dati, operazioni, identità, permessi e conseguenze degli errori.
2. Contratti: definire tool e risorse prima del codice, facendoli rivedere da esperti di dominio e ingegneri.
3. Vertical slice: collegare un client reale a un workflow reale con identità e dati simili alla produzione.
4. Pilota controllato: rilasciare a un piccolo gruppo, mantenendo le scritture dietro approvazione.
5. Hardening: completare threat model, test di carico e fallimento, alert, runbook, rotazione credenziali, privacy review e passaggio di ownership.

Errori comuni

• Pubblicare tutta l'API: più tool rendono la selezione difficile e ampliano la superficie di rischio.
• Duplicare le regole di business: divergono quando vivono separatamente nell'applicazione e nel server MCP.
• Fidarsi dell'identità proposta dal modello: utente e tenant devono provenire da una sessione verificata.
• Restituire payload pensati per la UI: le risposte per agenti devono essere concise, strutturate e stabili.
• Dare troppo potere alle scritture: approvazione e reversibilità devono seguire le conseguenze dell'azione.
• Saltare le valutazioni: una risposta valida a livello di protocollo non prova che l'agente usi bene l'interfaccia.
• Ignorare l'ownership: schemi, dipendenze, credenziali e incidenti devono avere un responsabile.

Cosa abbiamo imparato costruendo Storm

Gorilli ha costruito Storm, un marketplace decentralizzato per tool MCP sviluppato durante l'hackathon AI Blueprints con Filecoin Recall, dove ha vinto il secondo posto.

Il modello marketplace ha reso evidente una lezione: una capacità MCP è un contratto di prodotto, non soltanto la firma di una funzione. Uno sviluppatore deve capire cosa fa il tool, un agente deve selezionarlo correttamente e un operatore deve fidarsi del suo comportamento. Descrizioni chiare, permessi limitati, risultati prevedibili e utilizzo osservabile determinano se il tool è davvero riutilizzabile.

Per questo il nostro servizio di sviluppo e integrazione MCP considera l'architettura circostante importante quanto il server.

Checklist prima di iniziare

• Quale lavoro deve completare l'agente?
• Quale servizio possiede l'operazione di business?
• Come vengono stabilite identità utente e tenant?
• Quali permessi valgono per ogni tool e risorsa?
• Quali azioni richiedono approvazione?
• Le scritture sono idempotenti o reversibili?
• Quali dati vanno filtrati o oscurati?
• Cosa succede quando una dipendenza non è disponibile?
• Quali test dimostrano che il workflow è utile e sicuro?
• Come si collegano le tracce ai log applicativi?
• Chi mantiene il server dopo il lancio?

Se diverse risposte non sono chiare, la prima fase dovrebbe occuparsi di architettura e policy prima che di codice.

Domande frequenti

Dobbiamo sostituire le API esistenti per usare MCP?

No. Un server MCP ben progettato si posiziona normalmente davanti ad API e servizi esistenti. Può servire un servizio più alto livello quando l'API è troppo tecnica, ma una riscrittura raramente è il punto di partenza.

Un server MCP dovrebbe collegarsi direttamente al database?

L'accesso in sola lettura può essere appropriato per risorse ristrette. Le scritture dovrebbero passare da servizi applicativi che applicano regole di business, permessi, validazione e audit.

MCP è sicuro per impostazione predefinita?

MCP definisce come client e server scambiano capacità; autenticazione, autorizzazione, isolamento dei tenant, approvazioni, validazione, privacy e monitoraggio restano responsabilità dell'implementazione.

Come scegliamo il primo tool MCP?

Scegli un workflow frequente e utile, con permessi chiari e conseguenze limitate in caso di errore. Un'attività interna soprattutto in lettura è normalmente il punto di partenza migliore.

Se vuoi rendere un prodotto o un sistema interno accessibile agli agenti, raccontaci cosa vuoi collegare. Possiamo mappare le capacità, costruire il livello MCP e portare l'integrazione fino alla produzione.