Introduction

Les primitives MCP constituent les principales unités de conception qui relient une application d’IA à des fonctionnalités et à un contexte externes. Lors de la création d’un serveur MCP, la question centrale n’est pas de savoir combien de endpoints exposer. Il s’agit de déterminer si chaque fonctionnalité doit être représentée par un outil, une ressource ou un prompt. Un mauvais choix de primitive peut rendre un agent dangereux, compliquer la découverte du contexte ou obliger les utilisateurs à répéter manuellement les instructions.

Les trois primitives reposent sur des modèles de contrôle et d’interaction différents. Les outils sont généralement contrôlés par le modèle : un agent peut décider de les appeler lorsqu’il a besoin d’effectuer une action ou un calcul. Les ressources sont généralement contrôlées par l’application : l’application hôte décide quand récupérer leur contenu et le présenter. Les prompts sont généralement contrôlés par l’utilisateur : celui-ci sélectionne ou invoque un modèle d’interaction réutilisable. Il s’agit de conventions courantes de conception MCP, et non de simples noms différents pour une même opération.

Cette leçon présente une méthode pratique de sélection, des règles de conception des contrats et un petit helper de décision. L’objectif est de rendre la sélection des primitives prévisible avant le début de l’implémentation.

Les trois primitives

Un outil représente une opération que le modèle ou l’agent peut demander. Cette opération peut lire des données, transformer des données, appeler un service ou provoquer un effet de bord. Parmi les exemples figurent la recherche dans un système de tickets, le calcul des frais d’expédition, la création d’un brouillon de facture ou l’annulation d’une réservation. Un outil doit avoir un nom spécifique, une description claire, un schéma d’entrée défini et une sortie que le modèle peut interpréter.

Une ressource représente des informations adressables identifiées par une URI. Elle convient aux documents, aux configurations, aux enregistrements, aux schémas, aux rapports ou à tout autre contexte qu’une application peut charger et mettre à la disposition du modèle. Une ressource peut être statique, comme un document de politique, ou dynamique, comme une fiche client dont l’URI identifie une entité actuelle. La lecture d’une ressource doit être considérée comme une récupération de contexte, et non comme une instruction visant à effectuer une action.

Un prompt est un modèle d’interaction réutilisable ayant un objectif défini. Il peut spécifier des messages suggérés, des arguments et la structure attendue d’une tâche. Par exemple, une application de support peut proposer un prompt pour résumer une réclamation client, tandis qu’une application de revue de code peut proposer un prompt pour examiner une pull request. Un prompt ne remplace pas un outil et ne doit pas dissimuler une opération qui modifie l’état d’un système externe.

Choisir la primitive appropriée

Commencez par identifier ce que l’utilisateur ou l’agent doit obtenir. Si le besoin concerne une action, un calcul, une recherche avec paramètres ou un effet de bord externe, commencez par un outil. Le fait qu’une opération se contente de lire des données n’en fait pas automatiquement une ressource. Une recherche paramétrée des commandes actuelles est souvent un outil, car le modèle demande un calcul et reçoit un résultat fondé sur les arguments fournis.

Choisissez une ressource lorsque sa valeur principale réside dans un contexte récupérable doté d’une identité stable. Un document tel qu’une politique de retour, l’URI d’un enregistrement de base de données ou un rapport généré peut être représenté comme une ressource lorsque l’application peut décider du moment où il doit être chargé. Les ressources sont particulièrement utiles lorsque les utilisateurs doivent parcourir, joindre, mettre en cache, actualiser ou examiner le contexte indépendamment d’une décision de l’agent.

Choisissez un prompt lorsque le besoin consiste à structurer un modèle de conversation réutilisable pour un utilisateur. Un prompt peut indiquer au modèle comment utiliser le contexte disponible, mais il ne doit pas se faire passer pour une opération métier exécutable. Si une demande dit « aidez-moi à préparer une demande de remboursement », un prompt peut structurer la conversation. Si elle dit « effectuez le remboursement », un outil doit exécuter l’opération autorisée.

Un test utile consiste à compléter la phrase « Qui initie cette interaction ? » Si le modèle doit décider du moment où invoquer une opération, utilisez un outil. Si l’application hôte doit récupérer ou joindre des informations, utilisez une ressource. Si l’utilisateur doit choisir un workflow préparé, utilisez un prompt. Certains workflows utilisent légitimement les trois primitives à la suite.

Concevoir des contrats robustes

Un bon contrat d’outil réduit les ambiguïtés au minimum. Son nom doit décrire l’opération, et non l’implémentation. Sa description doit préciser quand l’utiliser, quand ne pas l’utiliser, quelles autorisations sont requises et quelles contraintes importantes s’appliquent. Les champs d’entrée doivent avoir des types explicites, des descriptions pertinentes, des règles de validation et, dans la mesure du possible, des valeurs limitées. Un outil qui accepte un objet entièrement libre pour chaque requête rend plus difficile la détection des erreurs, tant pour les modèles que pour les serveurs.

Les sorties des outils doivent distinguer les données renvoyées avec succès des informations d’échec. Renvoyez des résultats structurés lorsque le client doit examiner les champs par programmation, et incluez un contenu concis et lisible par l’utilisateur lorsque le résultat sera présenté à un modèle ou à un utilisateur. N’indiquez pas qu’une opération a réussi simplement parce qu’une requête est parvenue au serveur. Pour les outils produisant des effets de bord, le résultat doit préciser si l’opération a été terminée, rejetée, partiellement terminée ou seulement préparée sous forme de brouillon.

La conception des ressources dépend d’identifiants stables et d’un contenu prévisible. Utilisez des URI qui identifient l’objet métier ou le document sans y intégrer de détails accidentels liés à l’implémentation. Déterminez si une ressource est immuable, actualisable ou versionnée, et documentez la gestion du contenu obsolète. Une ressource contenant des données sensibles nécessite également une politique d’autorisation ; une URI est un identifiant, pas une autorisation de lire les données sous-jacentes.

La conception des prompts ne doit exposer que les arguments que les utilisateurs ou les applications sont raisonnablement en mesure de fournir. La description d’un prompt doit préciser le résultat attendu et le contexte requis. Séparez les instructions opérationnelles des données utilisateur et évitez d’intégrer des affirmations que le modèle devrait considérer comme faisant autorité, sauf si l’application est en mesure de les maintenir à jour. Un prompt peut recommander un appel d’outil, mais l’autorisation et la validation doivent rester assurées par l’outil et les couches serveur.

Exemple détaillé

Imaginez une application de support client répondant à trois besoins. Elle doit trouver les commandes ouvertes d’un client, fournir la politique de retour actuelle et guider un agent au cours d’une conversation sur un retour. Le premier besoin est une recherche paramétrée effectuée sur un système en temps réel ; il correspond donc à un outil. Le deuxième est un document adressable que l’application peut charger lorsque cela est nécessaire ; il correspond donc à une ressource. Le troisième est un modèle de conversation réutilisable, sélectionné par l’utilisateur ; il correspond donc à un prompt.

L’helper JavaScript local suivant exprime cette règle de décision. Il ne s’agit pas d’un serveur MCP et il ne remplace pas l’enregistrement auprès du protocole. Son objectif est de rendre les revues de conception explicites avant l’implémentation. Le résultat inclut la primitive choisie ainsi que la raison qui justifie ce choix.

function chooseMcpPrimitive(requirement) {
  const text = requirement.toLowerCase();

  if (text.includes("perform") || text.includes("create") || text.includes("update") ||
      text.includes("delete") || text.includes("search") || text.includes("calculate") ||
      text.includes("send") || text.includes("live")) {
    return {
      primitive: "tool",
      reason: "The requirement describes an operation, computation, parameterized lookup, or side effect."
    };
  }

  if (text.includes("document") || text.includes("policy") || text.includes("record") ||
      text.includes("report") || text.includes("read") || text.includes("context")) {
    return {
      primitive: "resource",
      reason: "The requirement describes addressable information that an application can retrieve and attach as context."
    };
  }

  if (text.includes("guide") || text.includes("workflow") || text.includes("template") ||
      text.includes("conversation") || text.includes("summarize")) {
    return {
      primitive: "prompt",
      reason: "The requirement describes a reusable interaction pattern selected by a user or application."
    };
  }

  return {
    primitive: "review",
    reason: "The requirement does not provide enough information to distinguish action, context, and interaction template."
  };
}

console.log(chooseMcpPrimitive("search live open orders for a customer"));
console.log(chooseMcpPrimitive("read the current return policy document"));
console.log(chooseMcpPrimitive("guide an agent through a return conversation"));

Le premier appel doit produire une décision concernant un outil, le deuxième une décision concernant une ressource et le troisième une décision concernant un prompt. L’helper adopte volontairement une approche prudente face à l’ambiguïté. Une véritable revue de conception doit examiner l’autorisation, l’actualité des données, le contrôle exercé par l’utilisateur et la présence éventuelle d’effets de bord avant tout enregistrement.

Modes d’échec courants

Une erreur fréquente consiste à exposer chaque capacité sous forme d’outil, car les outils sont faciles à appeler pour un agent. Cela crée un catalogue d’outils surdimensionné et incite le modèle à récupérer des documents via des opérations qui auraient dû être consultables ou contrôlées par l’application. Séparez le contexte de récupération des actions, en particulier lorsque le contexte est stable et peut être mis en cache.

Une autre erreur consiste à rédiger une description d’outil trop vague. Un nom tel que process_request n’indique pas au modèle s’il doit rechercher, approuver, soumettre ou supprimer quelque chose. Les descriptions ambiguës augmentent le nombre d’appels incorrects et compliquent la revue des autorisations. Décrivez directement l’opération, les entrées requises, les exclusions importantes et le comportement relatif aux effets de bord.

Une ressource peut également être mal conçue lorsque son URI expose des secrets, dépend de détails internes instables de la base de données ou laisse entendre un accès sans réellement l’appliquer. Utilisez des identifiants opaques lorsque cela est pertinent, validez les autorisations à chaque lecture et définissez la manière de signaler un contenu manquant, obsolète ou indisponible. Pour les prompts, évitez de considérer un prompt comme une frontière de sécurité. Les instructions incluses dans un prompt ne peuvent pas remplacer la validation côté serveur.

Enfin, ne supposez pas que la combinaison de primitives crée automatiquement un workflow efficace. Vérifiez que l’hôte expose les ressources au bon moment, que les utilisateurs peuvent comprendre les arguments des prompts et que les outils rejettent les requêtes malformées ou non autorisées. L’observabilité doit consigner le nom de la primitive, le résultat de la validation, le résultat de l’autorisation et la catégorie de l’échec, sans journaliser inutilement les valeurs sensibles.

Résumé

Les outils servent aux opérations, aux calculs, aux recherches paramétrées et aux effets de bord. Les ressources servent aux informations adressables qu’une application peut récupérer et fournir comme contexte. Les prompts servent aux modèles d’interaction réutilisables que les utilisateurs peuvent sélectionner ou invoquer. Leurs différences concernent à la fois la forme des données et la responsabilité du contrôle.

Un processus de conception fiable commence par le besoin, identifie l’initiateur de l’interaction, détermine si le résultat est une action ou un contexte, puis définit un contrat ciblé. Pour chaque primitive, les descriptions, les schémas, les permissions, les erreurs et le comportement en matière d’actualisation doivent être explicites.

Lorsqu’un workflow couvre plusieurs aspects, composez les primitives de manière délibérée. Un utilisateur peut sélectionner un prompt, l’application peut joindre une ressource et le modèle peut appeler un outil. La séparation de ces responsabilités produit un comportement plus clair, une autorisation plus sûre et des intégrations MCP plus faciles à tester et à maintenir.