mcp-server-patterns

MCP Server Patterns

Le Model Context Protocol (MCP) permet aux assistants IA d'appeler des outils, de lire des ressources et d'utiliser des prompts depuis votre serveur. Utilisez ce skill 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 de méthodes et signatures actuels.

Pour la décision plus large de savoir quand une capacité doit être une règle, un skill, MCP ou un simple workflow CLI/API, consultez docs/capability-surface-selection.md.

Quand utiliser

À utiliser lors de : l'implémentation 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 de problèmes d'enregistrement MCP et de transport.

Comment ça fonctionne

Concepts de base

• Outils : Actions que le modèle peut invoquer (par exemple, rechercher, exécuter 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 (par exemple, contenu 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 requêtes paramétrés et réutilisables que le client peut afficher (par exemple, dans Claude Desktop). Enregistrez-les avec registerPrompt() ou équivalent.
• Transport : stdio pour les clients locaux (par exemple, Claude Desktop) ; Streamable HTTP est préféré pour le remote (Cursor, cloud). Legacy HTTP/SSE 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 la documentation MCP actuelle ou Context7.

Connexion avec stdio

Pour les clients locaux, créez un transport stdio et transmettez-le à la méthode connect de votre serveur. L'API exacte varie selon la version du SDK (par exemple, constructeur vs fabrique). Consultez la documentation officielle MCP ou interrogez Context7 pour "MCP stdio server" afin d'obtenir le pattern 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.

Remote (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 legacy HTTP/SSE que lorsque la rétrocompatibilité est nécessaire.

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(). Idem pour les ressources — incluez un uri dans le gestionnaire lorsque l'API le fournit. Consultez 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 des schémas d'entrée pour chaque outil ; documentez les paramètres et la forme de retour.
• 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 les outils idempotents lorsque c'est possible afin que les tentatives soient sûres.
• 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.
• Versioning : Épinglez la version du SDK dans package.json ; consultez les notes de version lors de la mise à niveau.

SDK et documentation officiels

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