Come creare un server MCP in TypeScript (SDK v2) | We.Inc
Crea un server MCP funzionante con l'SDK TypeScript ufficiale v2: installa, registra un tool con uno schema Zod, connettilo via stdio e testalo nell'MCP Inspector.
Installa il pacchetto ufficiale @modelcontextprotocol/server e Zod, crea un McpServer con nome e versione, registra ogni tool con registerTool, una descrizione e uno schema di input Zod, poi collega uno StdioServerTransport. Esegui npx @modelcontextprotocol/inspector per chiamare i tuoi tool a mano prima che qualsiasi applicazione AI li tocchi.
I pezzi che ti servono
Pezzo
Da dove arriva
Cosa fa
McpServer
@modelcontextprotocol/server
Contiene i tuoi tool e risponde alle richieste del protocollo
registerTool
Metodo di McpServer
Aggiunge un tool: nome, descrizione, schema di input, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Comunica con l'host tramite standard input e output
z.object(...)
zod/v4
Descrive e valida gli argomenti del tool
Inspector
npx @modelcontextprotocol/inspector
Ti permette di elencare e chiamare i tool a mano
Spunta ogni passaggio man mano che procedi. La checklist ricorda dove sei arrivato, e ogni passaggio ha il comando o il file esatto che ti serve. Il server finito cerca in un piccolo elenco di note, sufficiente per vedere ogni parte in movimento senza un database.
Crea una cartella, aggiungi il package.json mostrato qui sotto e installa le due dipendenze.
Incolla server.ts e sostituisci l'array notes con i tuoi dati o una chiamata API.
Avvia l'Inspector e indicagli il comando che esegue il tuo server.
Elenca i tool, chiama notes_search con una parola e verifica il testo restituito.
Non scrivere mai su stdout da un server stdio. Quel flusso trasporta i messaggi del protocollo, quindi un console.log di troppo li corrompe. Usa console.error, che va su stderr.
Mantieni ogni tool piccolo e specifico. Per un modello è più facile scegliere tra due tool chiamati notes_search e notes_create che usare un unico tool notes con un selettore di modalità.
Valida dentro l'handler oltre che nello schema quando un tool tocca denaro, file o dati di altre persone. Lo schema controlla la forma, non i permessi.
Fissa la versione major dell'SDK in package.json. La versione 1 stava in un pacchetto diverso, @modelcontextprotocol/sdk, quindi i tutorial più vecchi non corrisponderanno a questi import.
Domande frequenti
Quale pacchetto npm devo installare?
Per la versione 2 dell'SDK, installa @modelcontextprotocol/server per i server e @modelcontextprotocol/client per i client. Il vecchio pacchetto v1, @modelcontextprotocol/sdk, vive su un branch v1.x e riceve correzioni di bug e di sicurezza per almeno sei mesi dopo il rilascio della v2.
Mi serve Zod?
Il README della v2 usa Zod v4 per gli schemi di input e lo importa da zod/v4, e dice che funzionano anche altre librerie Standard Schema come Valibot e ArkType. Installa quella che scegli insieme all'SDK.
Il server può girare su Bun o Deno?
Il README dell'SDK dice che gira su Node.js, Bun e Deno. L'Inspector è uno strumento Node separato e il suo README richiede Node 22.19.0 o successivo.
Come rendo il server disponibile da remoto?
Sostituisci il transport stdio con Streamable HTTP e ospita il processo in un posto raggiungibile. Aggiungi l'autenticazione prima di esporre qualsiasi tool che modifica dati, perché chiunque raggiunga l'URL può inviare richieste.
Come faccio a sapere se un'applicazione AI capirà il mio tool?
Leggi la descrizione e lo schema come se non sapessi nient'altro del progetto. Se un estraneo non riuscisse a capire quando chiamare il tool e cosa passargli, anche un modello andrà a tentativi. L'Inspector mostra esattamente ciò che vedrà un host.
Perché partire da stdio
Un server stdio è semplicemente un programma che l'host avvia. Niente porta, niente hosting e niente login: è la strada più rapida verso un tool funzionante da testare sulla tua macchina.
Quando i tool funzionano, passare a Streamable HTTP cambia la riga del transport e l'hosting, non il codice dei tool. Questa separazione è il motivo principale per tenere la logica di business in semplici funzioni chiamate dagli handler.
Progettare la risposta dell'handler
Un handler restituisce un oggetto con un array content. Gli elementi di testo sono il caso comune, e un testo breve e specifico funziona meglio: indica cosa corrisponde e quanti risultati ci sono, invece di riversare un intero insieme di record.
Quando non corrisponde nulla, restituisci una frase che lo dice. Una stringa vuota lascia il modello a chiedersi se la chiamata sia fallita o se la ricerca fosse semplicemente vuota.
Il server completo
Due file. Sostituisci l'array notes con ciò in cui il tuo server deve cercare.
type module permette di eseguire direttamente la sintassi import ES; lo script start usa tsx così salti la fase di build.
Un tool con uno schema Zod, una semplice funzione di ricerca e una connessione stdio. I log vanno su stderr così non si mescolano mai con i messaggi del protocollo.
Testalo con l'Inspector
L'Inspector ha tre modalità. La UI web è il punto di partenza più facile; la modalità CLI è adatta a script e CI.
Modalità dell'Inspector
Nella UI web, connettiti con il comando che avvia il tuo server (npx tsx server.ts), poi apri l'elenco dei tool.
Installa l'SDK, Zod e un runner TypeScript
Scrivi server.ts con un tool
Avvia il server una volta per verificare che non vada in crash