mcp-server-patterns

MCP Server Patterns

Le Protocole de Contexte de Modèle (MCP) permet aux assistants IA d'appeler des outils, de lire des ressources et d'utiliser des prompts depuis votre serveur. Utilisez cette compétence lors de la construction ou de la maintenance de serveurs MCP. L'API du SDK évolue ; vérifiez Context7 (query-docs pour "MCP") ou la documentation officielle MCP pour les noms et signatures de méthodes actuels.

Pour la décision plus large de routage indiquant si une capacité doit être une règle, une compétence, MCP ou un simple workflow CLI/API, voir docs/capability-surface-selection.md.

Quand l'utiliser

Utilisez-la lors de : la mise en œuvre d'un nouveau serveur MCP, l'ajout d'outils ou de ressources, le choix entre stdio et HTTP, la mise à niveau du SDK, ou le débogage des problèmes d'enregistrement et de transport MCP.

Comment ça fonctionne

Concepts essentiels

• Outils : Actions que le modèle peut invoquer (ex. recherche, exécution d'une commande). Enregistrez-les avec registerTool() ou tool() selon la version du SDK.
• Ressources : Données en lecture seule que le modèle peut récupérer (ex. contenus de fichiers, réponses API). Enregistrez-les avec registerResource() ou resource(). Les gestionnaires reçoivent généralement un argument uri.
• Prompts : Modèles de prompts paramétrés et réutilisables que le client peut afficher (ex. dans Claude Desktop). Enregistrez-les avec registerPrompt() ou équivalent.
• Transport : stdio pour les clients locaux (ex. Claude Desktop) ; Streamable HTTP est préféré pour les clients distants (Cursor, cloud). HTTP/SSE hérité est pour la rétrocompatibilité.

Le SDK Node/TypeScript peut exposer tool() / resource() ou registerTool() / registerResource() ; le SDK officiel a changé au fil du temps. Vérifiez toujours auprès de la documentation MCP actuelle ou de Context7.

Connexion avec stdio

Pour les clients locaux, créez un transport stdio et passez-le à la méthode connect de votre serveur. L'API exacte varie selon la version du SDK (ex. constructeur vs factory). Consultez la documentation officielle MCP ou interrogez Context7 avec "MCP stdio server" pour le modèle actuel.

Gardez la logique du serveur (outils + ressources) indépendante du transport afin de pouvoir brancher stdio ou HTTP dans le point d'entrée.

Connexion distante (Streamable HTTP)

Pour Cursor, le cloud ou d'autres clients distants, utilisez Streamable HTTP (un seul point de terminaison MCP HTTP selon la spécification actuelle). Ne supportez le HTTP/SSE hérité que lorsque la rétrocompatibilité est requise.

Exemples

Installation et configuration du serveur

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

Enregistrez les outils et les ressources en utilisant l'API fournie par votre version du SDK : certaines versions utilisent server.tool(name, description, schema, handler) (arguments positionnels), d'autres utilisent server.tool({ name, description, inputSchema }, handler) ou registerTool(). Même chose pour les ressources — incluez un uri dans le gestionnaire lorsque l'API le fournit. Vérifiez la documentation officielle MCP ou Context7 pour les signatures actuelles de @modelcontextprotocol/sdk afin d'éviter les erreurs de copier-coller.

Utilisez Zod (ou le format de schéma préféré du SDK) pour la validation des entrées.

Bonnes pratiques

• Schéma d'abord : Définissez les schémas d'entrée pour chaque outil ; documentez les paramètres et la forme de la réponse.
• Erreurs : Renvoyez des erreurs structurées ou des messages que le modèle peut interpréter ; évitez les traces de pile brutes.
• Idempotence : Préférez des outils idempotents lorsque c'est possible afin que les tentatives soient sans risque.
• Limites de taux et coût : Pour les outils qui appellent des API externes, tenez compte des limites de taux et du coût ; documentez-les dans la description de l'outil.
• Versionnement : Verrouillez la version du SDK dans package.json ; consultez les notes de version lors de la mise à niveau.

SDK officiels et documentation

• JavaScript/TypeScript : @modelcontextprotocol/sdk (npm). Utilisez Context7 avec le nom de bibliothèque "MCP" pour les modèles d'enregistrement et de transport actuels.
• Go : SDK Go officiel sur GitHub (modelcontextprotocol/go-sdk).
• C# : SDK C# officiel pour .NET.