Comment Construire Votre Premier Serveur MCP : Guide Pratique

Table des matières

Mis à jour juin 2026.

TL;DR : MCP (Model Context Protocol) est la façon de donner à Claude un accès structuré aux outils et données externes — bases de données, fichiers, APIs — sans surcharger la fenêtre de contexte. Le serveur est plus simple qu’il n’y paraît : installez le SDK, définissez vos outils en JSON schema, implémentez les handlers, connectez via stdio. Vous pouvez avoir Claude appelant vos outils personnalisés en moins de 30 minutes.

[Point de vue opérateur] Je connecte régulièrement de nouveaux outils à mes agents, et MCP est maintenant la voie standard pour le faire proprement. Une fois le serveur construit, chaque client compatible — Claude Desktop, Claude Code, toute application utilisant le SDK Anthropic — peut l’utiliser sans modification du code appelant. C’est la valeur : construire une fois, réutiliser partout.

Ce qu’est réellement MCP

Le Model Context Protocol est un protocole ouvert qui standardise la façon dont les modèles d’IA se connectent au contexte externe et aux outils. Pensez-y comme un standard USB-C pour les intégrations IA : avant lui, chaque application qui voulait que Claude lise une base de données ou appelle une API devait inventer sa propre plomberie. Après lui, vous construisez un serveur MCP et tout hôte compatible peut l’utiliser.

MCP définit trois choses qu’un serveur peut offrir :

• Outils — fonctions que Claude peut appeler (lire un fichier, interroger une BD, envoyer un message Slack)
• Ressources — données que Claude peut lire (documents, lignes de base de données, arborescences de fichiers)
• Prompts — modèles de prompts réutilisables que l’hôte peut injecter

Pour la plupart des cas d’usage opérateurs, vous construisez des serveurs d’outils. Les ressources et prompts viennent après, une fois les bases fonctionnelles.

L’architecture est client-serveur, avec le client (Claude Desktop, Claude Code, votre application personnalisée) qui contrôle tout. Le serveur est passif — il écoute simplement les requêtes d’appel d’outils et retourne des résultats.

Les trois pièces de tout serveur MCP

Chaque serveur MCP que vous construisez a la même structure :

1. L’objet serveur — déclare le nom, la version et les capacités de votre serveur (outils, ressources, prompts)
2. Définitions d’outils — une liste d’outils avec noms, descriptions et schémas JSON pour leurs entrées
3. Handlers de requêtes — les fonctions qui s’exécutent quand Claude appelle un outil

C’est tout. Pas de base de données, pas de stack HTTP, pas de couche d’auth requise pour commencer. Le serveur minimal fait moins de 30 lignes de TypeScript.

Prérequis (2 minutes)

• Node.js 18+ — vérifiez avec node --version
• TypeScript 5+ (inclus comme dépendance de développement)
• Un client MCP pour tester — Claude Desktop est gratuit et la façon la plus simple de voir votre serveur fonctionner

Aucune clé API Anthropic n’est nécessaire pour faire tourner un serveur MCP. La clé API vit dans le client (Claude Desktop), pas dans votre serveur.

Étape 1 : Configurer le projet (3 minutes)

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

Ajoutez dans package.json :

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Créez tsconfig.json :

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src/**/*"]
}

Étape 2 : Écrire le serveur minimal (5 minutes)

Créez src/index.ts :

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

const server = new Server(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Déclarer quels outils ce serveur offre
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Compte les mots dans un bloc de texte.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "Le texte dans lequel compter les mots",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Gérer les appels d'outils du client
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Nombre de mots : ${count}` }],
    };
  }

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

// Se connecter via stdio — c'est ainsi que Claude Desktop parle au serveur
const transport = new StdioServerTransport();
await server.connect(transport);

C’est le serveur complet. Il enregistre un outil (get_word_count) et l’implémente. La structure est ce qui compte.

Étape 3 : Construire et enregistrer dans Claude Desktop (5 minutes)

Compilez TypeScript :

npm run build

Enregistrez-le dans le fichier de config de Claude Desktop.

Sur macOS : ~/Library/Application Support/Claude/claude_desktop_config.json Sur Windows : %APPDATA%\Claude\claude_desktop_config.json

Si le fichier n’existe pas, créez-le :

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/chemin/absolu/vers/my-mcp-server/build/index.js"]
    }
  }
}

Utilisez le chemin absolu. Redémarrez Claude Desktop après avoir sauvegardé. Vous verrez une icône de marteau (🔨) dans la saisie de message — cela signifie que Claude a découvert vos outils.

Étape 4 : Construire un outil utile

Le comptage de mots est illustratif. Voici un outil plus utile : lire des fichiers depuis un répertoire de projet, ce que j’utilise pour les agents d’injection de contexte qui résument des bases de code, changelogs ou fichiers de configuration.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

La logique est la même : définissez les outils avec des schémas JSON précis, implémentez les handlers, validez les entrées pour prévenir le path traversal, et retournez du texte au client.

Les erreurs que j’ai faites (pour que vous ne les fassiez pas)

Le chemin doit être absolu. Les chemins relatifs dans la config Claude Desktop ne se résolvent pas comme prévu. Utilisez toujours le chemin complet /home/utilisateur/....

Stdio signifie aucun console.log dans votre serveur. Claude Desktop communique avec votre serveur via stdin/stdout. Un console.log de débogage corrompt le flux JSON-RPC. Loggez vers stderr :

process.stderr.write(`Debug : ${message}\n`);

Redémarrez Claude Desktop après chaque modification de config. Les serveurs MCP sont chargés au démarrage. Un fichier de config modifié ne fait rien jusqu’à ce que vous fermiez et rouvriez l’application.

Les descriptions d’outils sont le produit. Claude décide d’appeler votre outil en fonction du champ description. Une description vague signifie que Claude ne saura pas quand l’utiliser. Une précise signifie que Claude y recourt au bon moment. Investissez plus de temps dans les descriptions que dans l’implémentation.

Comment j’utilise les serveurs MCP en production

Le pattern stdio fonctionne très bien pour Claude Desktop et Claude Code (local). Pour les agents en production — les 30+ que j’exécute sur Cloudflare Workers — j’utilise l’API tool-use du SDK Anthropic directement, car j’ai besoin de la flexibilité pour router vers Haiku vs Sonnet par étape.

Les patterns que je livre en production :

1. Outillage de développement local — serveurs MCP pour Claude Code qui exposent des outils spécifiques au projet
2. Injection de contexte — serveurs MCP qui pré-chargent des docs pertinents sans copier manuellement
3. Pont prototype-vers-API — je construis MCP d’abord (plus rapide à itérer), puis je migre la logique vers le SDK tool-use pour la production

Quoi construire ensuite

Une fois la structure du serveur comprise, les outils utiles sont ceux qui accèdent au contexte externe de Claude :

• Lecteur de base de données — exécute une requête SQL en lecture seule et retourne les résultats en JSON
• Lecteur Slack — récupère les N derniers messages d’un canal
• Lecteur GitHub — liste les PRs ouvertes, lit un fichier à un commit spécifique
• Wrapper d’API interne — appelle votre propre API REST avec les headers d’auth intégrés

FAQ

Ai-je besoin d’une clé API Anthropic pour construire un serveur MCP ?

Non. Votre serveur MCP n’appelle pas l’API Anthropic. Il répond simplement aux requêtes d’appel d’outils du client. La clé API vit dans le client, pas dans le serveur.

Mon serveur MCP peut-il appeler des APIs externes ?

Oui — le handler est juste du code TypeScript asynchrone. Récupérez une API météo, interrogez une base de données, écrivez dans un fichier. Le serveur ne se préoccupe pas de ce que fait le handler en interne.

Quelle est la différence entre les transports stdio et HTTP ?

Stdio est pour les serveurs locaux — même machine que Claude Desktop ou Claude Code. HTTP avec SSE est pour les serveurs distants que vous pouvez déployer comme service web. Commencez par stdio ; c’est plus simple à déboguer.

Comment Claude sait-il quand appeler mon outil ?

Claude décide en fonction du champ description de l’outil et du contexte de la conversation. Si Claude continue d’ignorer votre outil, affinez la description.