Se connecter S'abonner
Dev & Code

Développer son premier serveur MCP (Model Context Protocol) : le guide d'intégration pour vos outils internes

Primitives Resources, Tools et Prompts, code TypeScript et sécurité : le guide pas à pas pour créer votre premier serveur Model Context Protocol (MCP).

Développer son premier serveur MCP (Model Context Protocol) : le guide d'intégration pour vos outils internes

1. Le problème : la fragmentation des connecteurs IA et le casse-tête des secrets

L'émergence des assistants de programmation intelligents et des agents autonomes basés sur les grands modèles de langage (LLM) a transformé le quotidien des équipes d'ingénierie logicielle. Qu'il s'agisse de naviguer dans une base de code volumineuse, d'interroger un système de gestion de bases de données ou d'exécuter des tests d'intégration, les développeurs s'appuient désormais au quotidien sur des outils comme Cursor, VS Code, Claude Desktop ou des agents personnalisés.

Cependant, l'intégration de ces assistants au sein des architectures logicielles d'entreprise se heurtait jusqu'à présent à un problème d'interopérabilité majeur. Chaque environnement de développement ou outil d'IA utilisait ses propres formats d'extension et ses propres méthodes d'appel de fonctions (function calling). Pour connecter un assistant à une API interne ou à un outil sur mesure, les équipes devaient développer des scripts ad hoc, souvent instables, mal documentés et difficiles à maintenir.

À cette fragmentation technique s'ajoute un enjeu de sécurité critique : la gestion des secrets et des accès. Renseigner en dur des clés d'API ou des identifiants de bases de données au sein d'extensions tierces ou de requêtes transmises à des modèles SaaS expose l'entreprise à des risques de fuites de données massives. De plus, accorder à un modèle de langage un accès direct et non filtré à des outils d'exécution sans couche de contrôle intermédiaire peut entraîner des modifications destructrices non souhaitées sur les systèmes de production.

C'est précisément pour résoudre ce double défi d'unification et de sécurité qu'Anthropic et la communauté open source ont introduit le Model Context Protocol (MCP). Conçu comme un standard ouvert et agnostique, le MCP fournit une interface universelle permettant de connecter de manière sécurisée n'importe quel modèle de langage à n'importe quelle source de données ou outil d'exécution.

2. La solution étape par étape : concevoir et coder un serveur MCP de A à Z

Le Model Context Protocol repose sur une architecture client-serveur légère. L'application d'IA (par exemple VS Code ou Claude Desktop) agit en tant que client MCP, tandis que vos outils internes sont encapsulés dans un serveur MCP exécuté localement ou sur votre réseau privé.

Un serveur MCP expose trois primitives d'échange fondamentales au modèle de langage :

  1. Les Ressources (Resources) : Des données en lecture seule fournies au modèle pour enrichir son contexte (documents, journaux d'application, schémas de base de données).
  2. Les Outils (Tools) : Des fonctions exécutables que le modèle peut décider de déclencher après validation (exécuter une requête SQL, lancer une suite de tests, créer un ticket Jira).
  3. Les Invites (Prompts) : Des modèles de requêtes pré-rédigés pour guider les interactions de l'utilisateur.

Voici la démarche pas à pas pour développer un serveur MCP robuste en TypeScript.

Étape 1 : Initialiser le projet et installer le SDK officiel

Pour construire un serveur MCP léger en Node.js/TypeScript, créez un nouveau répertoire de projet et installez le SDK officiel fourni par la communauté MCP.

mkdir mon-serveur-mcp
cd mon-serveur-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Initialisez la configuration TypeScript (tsconfig.json) en veillant à cibler un environnement ES2022 ou supérieur pour supporter les modules modernes et le traitement asynchrone.

Étape 2 : Déclarer le serveur et configurer le transport

Le serveur MCP communique avec le client via des flux de données standardisés. Pour un serveur local, le transport via l'entrée/sortie standard (stdio) est la méthode privilégiée car elle garantit l'isolation du processus et évite d'ouvrir des ports réseau inutiles.

Créez le fichier principal src/index.ts et instanciez le serveur :

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new Server(
{
name: "serveur-outils-internes",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);

Étape 3 : Définir et exposer un outil exécutable (Tool)

Chaque outil exposé par votre serveur MCP doit être décrit avec précision afin que le modèle de langage comprenne son rôle, ses paramètres d'entrée et son format de retour. Utilisez la bibliothèque Zod pour valider strictement les paramètres fournis par le modèle.

Dans cet exemple, nous créons un outil permettant de vérifier l'état de santé d'un service interne :

// Déclaration du catalogue d'outils
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "verifier_sante_service",
description: "Vérifie l'état de santé et la latence d'un service microservice interne",
inputSchema: {
type: "object",
properties: {
serviceName: {
type: "string",
description: "Le nom du service (ex: auth-api, payment-gateway)",
},
},
required: ["serviceName"],
},
},
],
};
});

// Traitement de l'exécution de l'outil
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "verifier_sante_service") {
const serviceName = String(request.params.arguments?.serviceName);

// Logique d'exécution interne (ex: appel HTTP ou requête interne)
const statut = serviceName === "auth-api" ? "OK" : "DEGRADED";
const latence = Math.floor(Math.random() * 50) + 10;

return {
content: [
{
type: "text",
text: JSON.stringify({
service: serviceName,
status: statut,
latencyMs: latence,
checkedAt: new Date().toISOString(),
}),
},
],
};
}

throw new Error(`Outil inconnu : ${request.params.name}`);
});

Étape 4 : Lancer le serveur et connecter le client

Connectez le serveur au transport stdio pour écouter les demandes du client MCP :

async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Serveur MCP d'outils internes démarré sur stdio");
}

main().catch((error) => {
console.error("Erreur fatale lors du démarrage du serveur MCP :", error);
process.exit(1);
});

Pour tester votre serveur dans Claude Desktop ou VS Code, ajoutez la configuration suivante dans votre fichier claude_desktop_config.json ou dans la configuration de votre extension MCP :

{
"mcpServers": {
"outils-internes": {
"command": "npx",
"args": ["tsx", "/chemin/vers/mon-serveur-mcp/src/index.ts"],
"env": {
"API_SECRET_KEY": "cle_secrete_interne_locale"
}
}
}
}

3. Les pièges à éviter : sécurité, injection de requêtes et gestion des erreurs

La création d'un serveur MCP est accessible, mais l'intégration dans un environnement professionnel nécessite d'éviter plusieurs erreurs de conception fréquentes.

Le piège de l'injection de requêtes (Prompt Injection)

Lorsqu'un outil MCP prend en entrée une chaîne de caractères générée par le modèle ou issue d'une source externe, cette chaîne peut contenir des instructions malveillantes conçues pour tromper le modèle ou altérer la commande d'exécution. Si votre outil exécute une requête SQL ou une commande système, ne concaténez jamais directement les arguments fournis par le modèle. Utilisez systématiquement des requêtes préparées avec des paramètres liés ou des bibliothèques d'assainissement strictes.

L'absence de confirmation humaine pour les actions destructrices

Par défaut, le protocole MCP recommande que toute action modifiant l'état d'un système (écriture en base de données, suppression de fichier, envoi d'e-mail ou déploiement de code) nécessite une confirmation explicite de l'utilisateur final. Côté serveur, vous devez étiqueter clairement les outils de modification et prévoir un mode de simulation (dry-run) lorsque cela est possible.

Une gestion bavarde des erreurs d'exécution

Lorsqu'une erreur survient dans votre serveur MCP (échec de connexion à la base de données, timeout HTTP), ne renvoyez pas de traces de pile (stack traces) complètes contenant des chemins de fichiers internes ou des identifiants. Renvoyez un message d'erreur lisible et structuré afin que le modèle puisse comprendre le problème et ajuster sa requête sans exposer votre infrastructure.

4. Pour aller plus loin : conteneurisation, sécurité et déploiement d'équipe

Une fois votre premier serveur MCP opérationnel en local, l'étape suivante consiste à industrialiser son déploiement pour l'ensemble de votre équipe d'ingénierie.

Isoler le serveur dans un conteneur Docker

Pour éviter les divergences d'environnement entre les postes de travail des développeurs, encapsulez votre serveur MCP dans un conteneur Docker minimaliste basé sur Alpine Linux. L'exécution du conteneur via docker run -i --rm sur le transport stdio garantit que l'outil s'exécute dans un bac à sable hermétique sans accès non autorisé au système de fichiers de l'hôte.

Centraliser la gestion des secrets et des autorisations

En entreprise, les clés d'API et identifiants utilisés par le serveur MCP ne doivent pas être stockés sur les postes des développeurs. Utilisez un coffre-fort de secrets centralisé (comme HashiCorp Vault ou AWS Secrets Manager) et faites en sorte que le serveur MCP récupère des jetons éphémères à durée de vie courte lors de son initialisation.

Distribuer un catalogue de serveurs d'équipe

Pour simplifier l'adoption du MCP dans votre organisation, créez un dépôt centralisé répertoriant les configurations des serveurs MCP validés par l'équipe de sécurité. Les développeurs peuvent ainsi cloner ou référencer ces serveurs pré-configurés dans leurs IDE, bénéficiant immédiatement d'assistants IA enrichis du contexte métier et parfaitement sécurisés.

Sources :

  1. ModelContextProtocol.io — Introduction to Model Context Protocol (MCP)
  2. GitHub — Model Context Protocol TypeScript SDK
  3. ModelContextProtocol.io — MCP Server Architecture and Concepts
  4. Anthropic News — Introducing the Model Context Protocol
  5. GitHub Blog — github-mcp-server is now available in public preview

À lire ensuite

Commentaires ()