MCP server: guida pratica per crearne uno stabile

Se vuoi capire davvero cos’è un mcp server e come usarlo in un progetto reale, il punto di partenza è avere chiaro il protocollo, i suoi componenti e il modo corretto in cui client, strumenti e dati dialogano tra loro. Per una panoramica introduttiva utile anche in fase di analisi tecnica, puoi leggere questa spiegazione sul Model Context Protocol. In pratica, un server MCP espone tools, resources e prompts a un client compatibile, così un modello AI può leggere dati o invocare azioni in modo standardizzato invece di dipendere da integrazioni proprietarie costruite ogni volta da zero.null

Quando ha senso creare un MCP server

Un mcp server ha senso quando devi collegare un modello AI a sistemi aziendali, API interne, database, file, CRM, repository o procedure operative che non vuoi esporre in modo diretto al modello. Il vantaggio principale è separare il livello di accesso ai dati dal livello di orchestrazione AI, mantenendo un perimetro più controllato e più facile da evolvere nel tempo.null

Dal punto di vista pratico, costruire un server custom è utile soprattutto in questi casi:

• devi usare API o fonti dati interne non coperte da server già pronti;
• hai regole di autorizzazione specifiche per utenti, team o tenant;
• vuoi limitare in modo rigoroso ciò che il modello può fare;
• devi tradurre flussi complessi in pochi strumenti chiari e sicuri;
• ti serve observability completa su input, output, errori e tempi di risposta.

Se invece il tuo obiettivo è andare live in poco tempo, spesso conviene partire da server già disponibili nell’ecosistema MCP. Il repository ufficiale mcp server github raccoglie implementazioni di riferimento, ma specifica anche in modo esplicito che molti esempi sono pensati come reference ed educativi, non come soluzioni production-ready. Questo punto è importante: una buona mcp server list è utile per accelerare i test, ma non sostituisce una revisione seria di sicurezza, logging, limiti operativi e gestione degli errori.null

Server custom o soluzioni già pronte

La scelta fra server custom e server esistente incide direttamente su tempi, costi e rischio di delivery. Se il caso d’uso è standard, ad esempio accesso a filesystem, GitHub o fetch web, usare uno dei mcp servers già disponibili può ridurre molto il tempo di setup iniziale. Se però devi governare permessi granulari, trasformare dati, aggiungere validazioni, mascherare campi sensibili o mantenere SLA chiari, un server custom è quasi sempre la scelta più solida.null

Se stai valutando il percorso migliore per il setup iniziale, può esserti utile anche questa guida sul setup di un MCP server, soprattutto per confrontare approccio rapido e implementazione più strutturata.

Architettura minima di un MCP server stabile

Per costruire un mcp server che non sia fragile, serve un’architettura essenziale ma pulita. Il protocollo prevede che il server esponga capacità standard e comunichi tramite JSON-RPC. Nei trasporti standard attuali, i due casi da conoscere sono stdio e Streamable HTTP. La documentazione del protocollo indica che i client dovrebbero supportare stdio quando possibile, mentre Streamable HTTP è il trasporto adatto a scenari remoti, multi-client e più vicini a integrazioni web. Inoltre, la specifica segnala che Streamable HTTP sostituisce il vecchio approccio HTTP+SSE nelle versioni più recenti del protocollo.null

Una base sana include questi componenti:

• layer di trasporto;
• registrazione di tools, resources e prompts;
• servizi applicativi che contattano API, DB o filesystem;
• validazione input e normalizzazione output;
• autenticazione e autorizzazione;
• logging strutturato;
• gestione timeout, retry e circuit breaker dove serve;
• test locali e test di regressione.

Molti team sbagliano perché mettono tutta la logica dentro la definizione del tool. Invece conviene tenere il tool sottile: riceve input, valida, delega a un servizio e restituisce un output prevedibile. Così il server resta più facile da mantenere e da testare.

Prerequisiti tecnici prima di iniziare

Prima di sviluppare un mcp server funzionante, assicurati di avere:

• Node.js aggiornato, se scegli TypeScript;
• un package manager coerente nel team, ad esempio npm o pnpm;
• familiarità con JSON Schema o con una libreria di validazione come Zod;
• un sistema di gestione segreti tramite variabili ambiente o secret manager;
• strumenti di test locale;
• accesso controllato alle API o alle fonti dati che vuoi esporre.

Per TypeScript, l’SDK ufficiale MCP segnala l’installazione di @modelcontextprotocol/sdk insieme a zod per la validazione degli schemi. La stessa documentazione raccomanda esempi distinti per stdio e HTTP e mette a disposizione quickstart ed esempi eseguibili.null

Stack consigliato per un progetto affidabile

Se vuoi un setup concreto e veloce da portare in produzione, uno stack TypeScript è spesso la scelta più pratica. Oggi è anche il più documentato nell’ecosistema ufficiale, con SDK, esempi e quickstart ben mantenuti.null

Stack consigliato per server locale o desktop

• TypeScript
• @modelcontextprotocol/sdk
• Zod per gli schemi input/output
• transport stdio
• dotenv o secret manager equivalente
• pino o winston per logging strutturato
• vitest o jest per test

Stack consigliato per server remoto

• TypeScript
• @modelcontextprotocol/sdk
• transport Streamable HTTP
• middleware auth
• reverse proxy
• rate limiting
• monitoraggio con tracing e metriche

Se stai ragionando sull’architettura complessiva e su come organizzare strumenti, risorse e policy, approfondisci anche questa guida all’architettura del protocollo MCP.

Setup minimo step by step con TypeScript

Vediamo ora un percorso pratico per mettere in piedi un mcp server minimale ma stabile.

Crea il progetto

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init

Questa base è coerente con l’installazione indicata nella documentazione dell’SDK TypeScript.null

Organizza le cartelle in modo semplice

src/
  server.ts
  tools/
    getCustomer.ts
  services/
    customerService.ts
  schemas/
    customer.ts
  lib/
    logger.ts

Non è una struttura obbligatoria, ma aiuta molto. Il punto è separare trasporto, logica business e validazione.

Definisci un primo tool utile

Un buon tool iniziale deve avere tre caratteristiche:

• input piccolo e chiaro;
• side effect ridotti o nulli;
• output facile da verificare.

Ad esempio, puoi esporre un tool get_customer_summary che riceve un ID cliente e restituisce nome, piano, stato e ultime attività. È molto meglio di un tool generico come “interroga il CRM”, perché riduce ambiguità e rischio operativo.

Registra il server e il tool

A livello concettuale, il server deve:

• dichiarare nome e versione;
• registrare capabilities;
• esporre strumenti con schema input esplicito;
• gestire errori applicativi senza rompere il canale JSON-RPC.

L’SDK ufficiale documenta in modo esplicito il supporto a tools, resources e prompts, oltre a esempi eseguibili per i pattern più comuni.null

Tools, resources e prompts: cosa usare davvero

Uno dei motivi per cui molti mcp servers diventano instabili è la confusione tra i tre mattoni principali del protocollo.

Quando usare un tool

Usa un tool quando il modello deve fare qualcosa:

• chiamare un’API;
• scrivere su un sistema;
• avviare un job;
• calcolare o trasformare dati;
• eseguire una ricerca filtrata.

Quando usare una resource

Usa una resource quando il modello deve leggere dati in modo prevedibile e senza side effect. Per esempio:

• configurazioni;
• documentazione interna;
• anagrafiche read-only;
• template e cataloghi.

Quando usare un prompt

Usa un prompt quando vuoi standardizzare il modo in cui l’utente o il client interagiscono con il modello in un certo flusso. I prompt non sostituiscono la logica applicativa, ma aiutano a guidarla.

La documentazione dell’SDK distingue in modo netto questi tre elementi e suggerisce di trattarli come primitive diverse, non intercambiabili.null

Trasporto stdio o Streamable HTTP

La scelta del trasporto cambia parecchio il progetto.

Quando scegliere stdio

• test locale;
• sviluppo rapido;
• integrazioni dove il client lancia il server come subprocess;
• superficie di rete quasi nulla.

Nel trasporto stdio, il client avvia il server come subprocess, il server legge da stdin e scrive risposte su stdout. La specifica sottolinea anche che il server non deve scrivere su stdout nulla che non sia un messaggio MCP valido; i log devono andare su stderr. Questo dettaglio è essenziale per evitare rotture difficili da diagnosticare.null

Quando scegliere Streamable HTTP

• server remoto;
• più client concorrenti;
• sessioni e contesto lato server;
• integrazione web;
• necessità di autenticazione standard.

La documentazione del protocollo indica che Streamable HTTP usa richieste POST per i messaggi JSON-RPC e può usare anche eventi server-to-client; inoltre raccomanda protezioni precise come validazione dell’header Origin, binding a localhost in locale e autenticazione corretta, per ridurre rischi come il DNS rebinding.null

Autenticazione e autorizzazione senza creare fragilità

Se il tuo mcp server legge dati sensibili o compie azioni rilevanti, non basta “mettere una API key”. La documentazione ufficiale chiarisce che l’autorizzazione in MCP è opzionale ma fortemente raccomandata quando il server accede a dati utente, richiede audit o espone operazioni sensibili. Per i server remoti, il riferimento è OAuth 2.1; per quelli locali basati su stdio possono esserci modalità più flessibili di acquisizione credenziali.null

Scelta pratica per ambiente locale

• usa stdio;
• salva credenziali in variabili ambiente o secret store locale;
• non hardcodare mai token nel codice;
• se il tool chiama API esterne, applica scope minimi.

Scelta pratica per ambiente remoto

• usa Streamable HTTP;
• implementa OAuth o un proxy di autenticazione;
• traccia chi esegue cosa;
• separa autenticazione da autorizzazione;
• aggiungi rate limit e revoca token.

Una best practice molto concreta è trattare ogni tool come un endpoint privilegiato. Se un utente non può fare una certa operazione in app, non deve poterla fare nemmeno via MCP. Sembra banale, ma è uno dei punti più trascurati nelle prime implementazioni.

Gestione errori: il punto che separa demo e produzione

Un mcp server fragile di solito funziona “quasi sempre”, finché incontra input sporchi, time out o dati incoerenti. Per evitarlo, definisci una politica errori fin dall’inizio.

Errori da coprire sempre

• input non validi;
• risorsa non trovata;
• credenziali mancanti o scadute;
• servizio esterno non disponibile;
• risposta esterna incompleta o malformata;
• timeout;
• rate limit del provider;
• errori interni non previsti.

Best practice operative

• valida sempre input e output;
• usa messaggi di errore leggibili ma non troppo verbosi;
• non esporre stack trace o segreti al client;
• genera correlation ID per ogni richiesta;
• logga il dettaglio tecnico solo lato server;
• imposta timeout espliciti per ogni chiamata esterna.

Se un tool dipende da una API esterna, aggiungi retry solo per errori transienti e solo dove l’operazione è idempotente. Un retry applicato male su un’azione di scrittura può moltiplicare ordini, ticket o aggiornamenti.

Test locale: come verificare che il server funzioni davvero

Per testare il server in locale, lo strumento più utile è l’MCP Inspector. La documentazione ufficiale lo presenta come tool interattivo per test e debugging, eseguibile via npx, sia per pacchetti pubblicati sia per server sviluppati localmente. L’Inspector permette di verificare connettività, capability negotiation, tools, resources, prompt, log e gestione dei casi limite.null

Comando tipico per server locale

npx @modelcontextprotocol/inspector node build/index.js

Con questo passaggio puoi controllare subito:

• se il server parte correttamente;
• se gli strumenti risultano registrati;
• se gli schemi input sono leggibili dal client;
• se i tool restituiscono output coerenti;
• se gli errori vengono gestiti bene.

Checklist di test minimo

• avvio server senza eccezioni;
• tool discovery corretta;
• esecuzione con input valido;
• errore controllato con input invalido;
• timeout simulato su provider esterno;
• assenza di log spurii su stdout;
• test di concorrenza se usi HTTP.

Debug locale e osservabilità

Per evitare debugging “alla cieca”, costruisci osservabilità già dal primo commit. L’Inspector aiuta nel test interattivo, ma in un progetto reale servono anche log strutturati, livelli di severità, metriche e tracciamento delle dipendenze esterne. La guida di debugging MCP richiama esplicitamente l’importanza di workflow iterativo, monitoraggio dei messaggi e verifica dei casi edge.null

Cosa loggare

• tool invocato;
• durata esecuzione;
• esito;
• codice errore;
• dipendenza esterna coinvolta;
• sessione o correlation ID.

Cosa non loggare

• token;
• dati personali non necessari;
• payload completi se contengono segreti;
• contenuti sensibili provenienti da sistemi interni.

Come evitare implementazioni fragili

Molti problemi ricorrenti non dipendono dal protocollo, ma da scelte progettuali sbagliate. Ecco gli errori più frequenti quando si realizza un github mcp server o un server collegato a sistemi interni.

Errori comuni

• tool troppo generici;
• assenza di validazione schema;
• assenza di timeout;
• mix di business logic e trasporto;
• nessun controllo di autorizzazione per singolo tool;
• dipendenza da output non stabile di servizi terzi;
• nessun test di errore;
• nessun versionamento delle interfacce.

Pattern più robusti

• tools piccoli e molto specifici;
• contratti input/output espliciti;
• layer servizi separato;
• error mapping coerente;
• capability limitate al minimo necessario;
• feature flag per funzioni sperimentali;
• test automatici su casi reali e casi sporchi.

Se stai scegliendo quali strumenti esporre prima e quali tenere fuori dal perimetro iniziale, può esserti utile anche questa selezione dei migliori tool MCP, soprattutto per ragionare sul rapporto fra valore operativo e rischio.

Esempio di percorso di delivery realistico

In un progetto B2B tipico, il modo più efficace per rilasciare un mcp server non è partire da dieci tool, ma da uno o due casi d’uso ad alto impatto e basso rischio. Per esempio:

• fase 1: tool read-only per interrogare dati cliente;
• fase 2: tool con filtri e ricerca avanzata;
• fase 3: tool di aggiornamento con audit;
• fase 4: risorse statiche e prompt guidati;
• fase 5: hardening sicurezza, rate limit, osservabilità completa.

Questo approccio riduce il rischio di creare un server ampio ma instabile. Inoltre ti permette di misurare presto se il modello usa davvero gli strumenti come previsto.

Come valutare una mcp server list senza perdere tempo

Quando cerchi una mcp server list o esplori un repository mcp server github, non fermarti al numero di stelle o alla popolarità. Il repository ufficiale dei server MCP chiarisce che molte implementazioni servono come reference implementation e non vanno assunte automaticamente come pronte per la produzione.null

Prima di adottare uno dei mcp servers disponibili, verifica sempre:

• ultimo aggiornamento del repository;
• presenza di issue aperte su sicurezza o stabilità;
• documentazione su autenticazione e permessi;
• copertura test;
• chiarezza sugli scope;
• modalità di deploy e configurazione;
• limiti dichiarati dal maintainer.

Mini checklist finale per andare live

• hai scelto il trasporto corretto tra stdio e Streamable HTTP;
• ogni tool ha uno schema input esplicito;
• ogni chiamata esterna ha timeout e gestione errori;
• stdout è riservato ai messaggi MCP;
• i log sono strutturati e sicuri;
• le credenziali non sono nel codice;
• l’autorizzazione è coerente con i permessi applicativi reali;
• hai testato il server con MCP Inspector;
• hai definito un piano di versionamento e rollback;
• hai deciso in modo consapevole se usare un server custom o partire da uno già esistente.