Outils, ressources et requêtes

Le protocole de contexte du modèle (MCP) permet à un serveur externe d'exposer des fonctionnalités à Claude via une interface standard. Un seul serveur peut proposer exactement trois types de primitives :

• Outils — des actions que le modèle peut invoquer (faire quelque chose, souvent avec des effets secondaires)
• Ressources — des données et du contexte en lecture seule que le modèle peut intégrer (schémas, catalogues, documents)
• Invites — des modèles réutilisables qui structurent la formulation d'une tâche

Savoir quelle primitive correspond à une fonctionnalité est une compétence essentielle d'architecte : classer incorrectement une action comme ressource (ou l'inverse) produit des intégrations fragiles et déroutantes.

Les outils sont des actions. Ce sont les primitives que le modèle appelle pour produire un résultat : interroger une base de données en temps réel, créer un ticket, envoyer un message, traiter un remboursement. Les outils sont l'équivalent MCP des outils du SDK Agent que vous définissez déjà dans le champ tools d'une requête d'API.

Comme les outils pilotent le comportement, leurs descriptions constituent le principal mécanisme de sélection — et non leurs noms. Une bonne description d'outil précise son objectif, ses valeurs de retour, ses formats d'entrée avec des exemples et ses limites d'utilisation, afin que le modèle sélectionne le bon outil.

Les ressources sont des données en lecture seule. Elles fournissent au modèle un contexte sur lequel raisonner, plutôt qu'une action à effectuer : un schéma de base de données, un catalogue de produits, une spécification d'API, un fichier de configuration ou un document de référence.

Le test mental est le suivant : si le modèle lit pour comprendre, il s'agit d'une ressource ; s'il agit pour modifier quelque chose, il s'agit d'un outil. Exposer un schéma stable comme ressource évite de consommer un appel d'outil (et un aller-retour) simplement pour récupérer le contexte dont le modèle a besoin dès le départ.

Les invites sont des modèles. Un serveur MCP peut publier des modèles d'invite paramétrés et réutilisables — par exemple une invite standard « résumer cet incident » ou « examiner cette PR pour détecter des problèmes de sécurité », qui intègre la structure et les critères privilégiés par l'équipe.

Les invites ne sont ni des actions ni des données : elles indiquent comment formuler une tâche. Elles permettent à un serveur de fournir des instructions conformes aux bonnes pratiques (critères explicites, exemples few-shot), afin que chaque consommateur formule la requête de manière cohérente au lieu de la réinventer.

Placez les trois catégories côte à côte et leurs limites deviennent évidentes :

• Outil — « Faites X. » Produit des effets, peut échouer de manière transitoire et est invoqué au milieu de la boucle. Par exemple : process_refund.
• Ressource — « Voici X à lire. » Stable, idempotente et sans effets secondaires. Par exemple : le schéma des commandes.
• Invite — « Demandez-le comme ceci. » Un modèle, pas un appel. Par exemple : le modèle d'examen d'une PR.

Une erreur fréquente consiste à encapsuler un contexte en lecture seule dans un outil. Cela fonctionne, mais coûte un appel d'outil et un aller-retour ; une ressource fournit le même contexte à moindre coût et indique clairement l'intention.

L'endroit où vous enregistrez un serveur détermine qui y a accès. Deux portées sont importantes :

• Portée du projet — .mcp.json à la racine du dépôt, validé dans le système de gestion de versions. Partagé avec toute l'équipe ; toute personne qui clone le dépôt obtient les mêmes serveurs.
• Portée utilisateur — ~/.claude.json, personnelle et NON partagée via VCS. Adaptée à vos propres identifiants ou à des serveurs expérimentaux.

Pour une intégration dont toute l'équipe dépend, choisissez la portée du projet afin qu'elle soit conservée dans VCS et que les nouveaux membres de l'équipe en héritent automatiquement.

Comme .mcp.json à portée de projet est validé dans VCS, vous ne devez jamais y coder des secrets en dur. Référencez-les plutôt au moyen de variables d'environnement — par exemple ${GITHUB_TOKEN} — afin que la configuration puisse être partagée, tandis que le jeton réel reste hors du code source.

Il s'agit d'une garantie de sécurité, pas d'une simple commodité : un jeton validé est un jeton divulgué. L'indirection par variable d'environnement garde la configuration du projet portable et l'identifiant privé sur chaque machine.

Pour les intégrations standard — GitHub, Postgres, Slack, système de fichiers — préférez un serveur MCP communautaire bien maintenu plutôt que d'en développer un sur mesure. Vous bénéficiez ainsi gratuitement de descriptions d'outils éprouvées, de la gestion des erreurs et des mises à jour.

Réservez un serveur sur mesure aux systèmes véritablement propriétaires pour lesquels aucune solution communautaire n'existe. Cela reprend un principe d'architecture plus général : ne reconstruisez pas les composants standard ; consacrez vos efforts à ce qui est réellement propre à votre domaine.

Lorsqu'un outil MCP échoue, un message générique comme "Operation failed" laisse le modèle sans visibilité : il ne peut pas déterminer s'il doit réessayer, transmettre le problème ou tenter une autre solution. Renvoyez toujours des erreurs structurées afin que le modèle puisse les orienter intelligemment.

Une bonne erreur MCP contient : isError: true, une errorCategory (transitoire / validation / métier / autorisation), un indicateur isRetryable, un message compréhensible, la attempted_query et les éventuels partial_results. La catégorie et l'indicateur de possibilité de nouvelle tentative transforment une impasse en récupération intelligente.

Tout ce que vous savez sur la bonne conception des outils s'applique également aux outils MCP :

• Ce sont les descriptions, pas les noms, qui orientent la sélection : indiquez l'objectif, les résultats renvoyés, les formats d'entrée, les cas limites et les limites d'utilisation.
• Adaptez la portée des outils au rôle. Environ 4 à 5 outils par agent est optimal ; à partir d'environ 18, la fiabilité de la sélection diminue.
• Évitez les recouvrements. Deux outils aux descriptions ambiguës et similaires provoquent une mauvaise orientation.

Un serveur MCP qui déverse 20 outils décrits vaguement sur un agent constitue une anti-pratique, quelle que soit la capacité de chaque outil.

Imaginez un serveur MCP de gestion des commandes pour un agent d'assistance. Une conception claire utilise volontairement les trois primitives :

• Ressource schema://orders — afin que l'agent comprenne d'emblée le modèle de données, sans appel d'outil.
• Outils lookup_order, process_refund — les actions, chacune dotée d'une description précise et d'erreurs structurées.
• Instruction refund_review — un modèle qui encode les critères de justification des remboursements de l'équipe.

Enregistrez-le dans .mcp.json à la portée du projet, récupérez les secrets depuis les variables d'environnement et limitez le nombre d'outils. Voilà une intégration MCP digne d'un architecte.

Points essentiels pour l'examen et les réalisations concrètes :

• Un serveur MCP expose trois primitives : outils (actions), ressources (données/contexte en lecture seule), instructions (modèles).
• Décidez selon l'intention : agir → outil, lire pour comprendre → ressource, savoir comment demander → instruction.
• Portée : .mcp.json du projet (partagé dans le VCS) contre ~/.claude.json de l'utilisateur (personnel).
• Les secrets passent par des variables d'environnement comme ${GITHUB_TOKEN} — n'intégrez jamais de jetons dans le dépôt.
• Préférez les serveurs communautaires pour les intégrations standard ; limitez les outils à environ 4 ou 5 et fournissez-leur des descriptions précises.
• Renvoyez des erreurs structurées (isError, errorCategory, isRetryable, attempted_query, partial_results) afin que le modèle puisse récupérer intelligemment.