Créer un serveur MCP en TypeScript (SDK v2) | We.Inc
Créez un serveur MCP fonctionnel avec le SDK TypeScript officiel v2 : installation, enregistrement d'un outil avec un schéma Zod, connexion via stdio et test dans le MCP Inspector.
Installez le paquet officiel @modelcontextprotocol/server et Zod, créez un McpServer avec un nom et une version, enregistrez chaque outil avec registerTool, une description et un schéma d'entrée Zod, puis connectez un StdioServerTransport. Lancez npx @modelcontextprotocol/inspector pour appeler vos outils à la main avant qu'une application d'IA ne les utilise.
Les éléments nécessaires
Élément
Provenance
Rôle
McpServer
@modelcontextprotocol/server
Contient vos outils et répond aux requêtes du protocole
registerTool
Méthode de McpServer
Ajoute un outil : nom, description, schéma d'entrée, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Communique avec l'hôte via l'entrée et la sortie standard
z.object(...)
zod/v4
Décrit et valide les arguments de l'outil
Inspector
npx @modelcontextprotocol/inspector
Permet de lister et d'appeler les outils à la main
Cochez chaque étape au fur et à mesure. La checklist garde votre progression, et chaque étape contient la commande ou le fichier exact dont vous avez besoin. Le serveur final recherche dans une petite liste de notes, ce qui suffit pour voir chaque rouage sans base de données.
Créez un dossier, ajoutez le package.json ci-dessous et installez les deux dépendances.
Collez server.ts et remplacez le tableau notes par vos propres données ou un appel d'API.
Lancez l'Inspector et indiquez-lui la commande qui exécute votre serveur.
Listez les outils, appelez notes_search avec un mot et vérifiez le texte renvoyé.
N'écrivez jamais sur stdout depuis un serveur stdio. Ce flux transporte les messages du protocole, un console.log égaré les corrompt donc. Utilisez console.error, qui écrit sur stderr.
Gardez chaque outil petit et précis. Deux outils nommés notes_search et notes_create sont plus faciles à départager pour un modèle qu'un seul outil notes avec un sélecteur de mode.
Validez dans le handler en plus du schéma quand un outil touche à de l'argent, des fichiers ou les données d'autres personnes. Le schéma vérifie la forme, pas les permissions.
Fixez la version majeure du SDK dans package.json. La version 1 vivait dans un autre paquet, @modelcontextprotocol/sdk, les anciens tutoriels ne correspondront donc pas à ces imports.
Questions fréquentes
Quel paquet npm dois-je installer ?
Pour la version 2 du SDK, installez @modelcontextprotocol/server pour les serveurs et @modelcontextprotocol/client pour les clients. L'ancien paquet v1, @modelcontextprotocol/sdk, vit sur une branche v1.x et reçoit des correctifs de bugs et de sécurité pendant au moins six mois après la sortie de la v2.
Ai-je besoin de Zod ?
Le README de la v2 utilise Zod v4 pour les schémas d'entrée et l'importe depuis zod/v4, et il précise que d'autres bibliothèques Standard Schema comme Valibot et ArkType fonctionnent aussi. Installez celle de votre choix à côté du SDK.
Le serveur peut-il tourner sur Bun ou Deno ?
Le README du SDK indique qu'il fonctionne sur Node.js, Bun et Deno. L'Inspector est un outil Node distinct et son README demande Node 22.19.0 ou plus récent.
Comment rendre le serveur accessible à distance ?
Remplacez le transport stdio par Streamable HTTP et hébergez le processus à un endroit joignable. Ajoutez une authentification avant d'exposer un outil qui modifie des données, car toute personne qui peut atteindre l'URL peut envoyer des requêtes.
Comment savoir si une application d'IA comprendra mon outil ?
Relisez votre description et votre schéma comme si vous ne saviez rien d'autre du projet. Si un inconnu ne pouvait pas deviner quand appeler l'outil et quoi lui passer, un modèle devra deviner lui aussi. L'Inspector montre exactement ce que verra un hôte.
Pourquoi commencer par stdio
Un serveur stdio n'est qu'un programme lancé par l'hôte. Pas de port, pas d'hébergement, pas de connexion : c'est le chemin le plus rapide vers un outil fonctionnel que vous pouvez tester sur votre propre machine.
Une fois les outils au point, passer à Streamable HTTP change la ligne du transport et l'hébergement, pas le code des outils. Cette séparation est la principale raison de garder la logique métier dans de simples fonctions appelées par les handlers.
Concevoir la réponse du handler
Un handler renvoie un objet avec un tableau content. Les éléments texte sont le cas courant, et un texte court et précis fonctionne le mieux : dites ce qui correspond et combien, plutôt que de déverser tout un jeu d'enregistrements.
Quand rien ne correspond, renvoyez une phrase qui le dit. Une chaîne vide laisse le modèle deviner si l'appel a échoué ou si la recherche était simplement vide.
Le serveur complet
Deux fichiers. Remplacez le tableau notes par ce que votre serveur doit rechercher.
type module permet d'exécuter directement la syntaxe d'import ES ; le script start utilise tsx, vous évitez donc une étape de build.
Un outil avec un schéma Zod, une simple fonction de recherche et une connexion stdio. Les logs vont sur stderr pour ne jamais se mêler aux messages du protocole.
Le tester avec l'Inspector
L'Inspector a trois modes. L'interface web est le point de départ le plus simple ; le mode CLI convient aux scripts et à la CI.
Modes de l'Inspector
Dans l'interface web, connectez-vous avec la commande qui lance votre serveur (npx tsx server.ts), puis ouvrez la liste des outils.
Installer le SDK, Zod et un exécuteur TypeScript
Écrire server.ts avec un outil
Lancer le serveur une fois pour vérifier qu'il ne plante pas
Ouvrir l'Inspector et se connecter à votre serveur
Lister les outils et appeler notes_search à la main