Concevoir un serveur MCP : design patterns, UX agent et compromis de conception

Cet article fait suite à MCP un an après : registries, confiance et commerce agentique. L’article précédent couvrait l’écosystème, les registries et les protocoles de commerce ; celui-ci se concentre sur la conception d’un serveur MCP — ce qui fait qu’un agent l’utilise bien, ou pas du tout.

L’erreur la plus fréquente quand on construit un serveur MCP, c’est de le penser comme une API REST avec un nouveau transport. C’est techniquement correct — JSON-RPC, des schémas, des endpoints — mais ça passe à côté du problème. Le consommateur d’un serveur MCP n’est pas un développeur qui lit une doc Swagger. C’est un LLM qui doit choisir le bon outil parmi N, comprendre ses paramètres, interpréter sa réponse, et enchaîner avec le suivant — le tout dans un budget de tokens fixe.

Concevoir un serveur MCP, c’est designer une UX. Sauf que l’utilisateur est un modèle de langage.

Cet article synthétise les retours d’expérience de GitHub, Datadog, Cloudflare, Anthropic, et de développeurs indépendants qui ont publié leurs leçons. Le fil conducteur : les décisions de design qui semblent mineures — un nom d’outil, le format d’une réponse, le nombre de paramètres — sont celles qui déterminent si un agent réussit ou échoue.

1. Le contexte window comme contrainte première

Avant de parler de design, il faut comprendre la contrainte qui gouverne tout le reste.

Chaque outil exposé par un serveur MCP coûte entre 550 et 1 400 tokens de schéma et description. Un serveur de 20 outils consomme 15 000 à 25 000 tokens. Cinq serveurs branchés simultanément ? 55 000 tokens avant que l’utilisateur ait tapé un seul mot [Source : Apideck — Your MCP Server Is Eating Your Context Window].

Un cas documenté : 143 000 tokens sur 200 000 consommés uniquement par les définitions d’outils. 72 % du budget raisonnement du modèle, parti en schémas JSON.

Le contexte window n’est pas un détail technique. C’est la ressource la plus rare dans une interaction agent. Chaque token consommé par vos définitions d’outils est un token en moins pour le raisonnement, la mémoire de conversation, et les résultats de vos propres appels.

Le principe fondateur : less is more. Minimiser l’empreinte dans le contexte tout en maximisant l’information pertinente [Source : Klavis — Less is More: 4 Design Patterns].

2. Penser intentions utilisateur, pas endpoints API

Le piège du miroir d’API

Le réflexe naturel d’un développeur : une route API → un outil MCP. C’est le chemin le plus court, et c’est un anti-pattern.

Problème : « Où en est ma commande ? »

Approche miroir d’API (operation-oriented) :

get_customer → récupère l’ID client
list_orders → récupère la liste de commandes
get_order_status → récupère le statut

Trois appels. Trois allers-retours dans le contexte. Trois occasions d’échouer.

Si chaque étape a un taux de réussite de 95 %, la chaîne complète tombe à 85,7 %.

Solution : un outil orienté intention (outcome-oriented) :

track_latest_order(customer_email: string)
→ { status, carrier, eta, tracking_url }

Un seul appel. Le serveur orchestre les trois requêtes en interne, de manière déterministe. Le LLM n’a pas à deviner la séquence [Source : MCP Tool Design: Why Your AI Agent Is Failing].

La règle du 80/20

Environ 20 % des capacités d’une API servent 80 % des requêtes utilisateur. Le bon serveur MCP couvre ce 20 % avec des outils orientés intention. Pour la longue traîne de requêtes rares, le code mode (section 8) prend le relais.

La même API peut — et souvent devrait — produire des serveurs MCP différents pour des utilisateurs différents. Un serveur MCP pour l’équipe support et un autre pour l’équipe analytics, même s’ils tapent dans le même backend [Source : Workato — Designing MCP Tools].

3. Design d’outils : les cinq décisions qui comptent

3.1 Le nommage

Le nom est le premier signal qu’un LLM utilise pour décider si un outil correspond à l’intention. Un mauvais nom crée de la confusion ; un bon nom rend la sélection évidente.

Règles concrètes :

Format verb_noun cohérent, en snake_case.
Préfixes distincts par action : search_* pour chercher plusieurs résultats, get_* pour récupérer un élément spécifique, create_*, update_*, delete_*.
Namespacing par service quand le serveur couvre plusieurs domaines : asana_projects_search, slack_threads_fetch.
Jamais de noms génériques : get_data, process_request, handle_info.

Anti-pattern : mélanger les conventions dans le même serveur — searchCustomers, find_user_by_id, getUserDetails [Source : Speakeasy — Design MCP Tools].

3.2 Les descriptions — le cœur du design

Les descriptions sont la surface de décision principale du LLM. C’est là que se joue l’essentiel de la qualité d’un serveur MCP. La recherche montre que des descriptions augmentées améliorent le taux de réussite de 5,85 points de pourcentage par rapport à des descriptions minimales.

Une bonne description contient six composantes :

Ce que l’outil fait (purpose)
Quand l’utiliser (guidelines — y compris les relations avec les autres outils)
Ce qu’il ne fait pas (limitations, alternatives)
Format des paramètres (conventions, contraintes)
Exemples concrets de valeurs d’entrée
Longueur suffisante sans noyer le modèle

Mauvais :

"Recherche de vols"

Bon :

"Recherche de vols disponibles entre deux aéroports à une date donnée.
Retourne jusqu'à 20 résultats triés par prix.
Utiliser des codes IATA à 3 lettres (ex. : 'CDG', 'JFK').
Ne recherche qu'en classe économique.
Pour les vols multi-segments, utiliser search_multi_city_flights."

Le conseil d’Anthropic : « pensez à la description comme à un onboarding pour un nouveau collègue. Rendez explicite tout le contexte implicite — formats spécialisés, terminologie métier, relations entre ressources » [Source : Writing Effective Tools for Agents].

3.3 Les paramètres

Le schéma JSON des paramètres ne peut pas exprimer les conventions d’usage à lui seul. C’est là que le design humain reste irremplaçable.

Principes :

Noms sans ambiguïté. Pas user mais user_id. Pas query mais search_term.
Types stricts et enums. Un LLM ne doit pas deviner — il doit choisir parmi des valeurs valides. Recognition over recall : lui donner la liste plutôt que de compter sur sa mémoire.
Contraintes dans le schéma. maxLength: 16, minimum: 1, maximum: 10000 — validées au parsing, pas dans le handler.
Défauts sensés. Les paramètres optionnels avec des défauts réduisent les erreurs et la surface de décision.
Rejeter les paramètres inconnus. Si le LLM hallucine un paramètre qui n’existe pas, l’appel doit échouer proprement au lieu de silencieusement ignorer.
Exemples réalistes dans la description. "ex. : 'WIDGET-42', 'BOLT-7'" vaut mieux que "identifiant du produit".

Anthropic insiste : les exemples d’usage dans les descriptions sont le meilleur moyen de lever les ambiguïtés que le schéma JSON seul ne peut pas exprimer — conventions de date, patterns d’ID, combinaisons valides de paramètres optionnels [Source : Anthropic — Advanced Tool Use].

3.4 Les valeurs de retour

C’est le point le plus contre-intuitif pour un développeur d’API. En API classique, on retourne tout et on laisse le client trier. En MCP, chaque octet de réponse entre dans le contexte window.

Principes :

Signal, pas exhaustivité. Retourner name, image_url, file_type — pas uuid, 256px_image_url, mime_type (sauf si l’outil suivant en a besoin).
Réponses bornées. Toujours paginer, jamais de dump complet. Inclure has_more: true et un mécanisme de continuation.
Proposer deux formats. Un paramètre response_format: "concise" | "detailed" permet à l’agent d’être frugal quand il explore et exhaustif quand il a besoin de précision.
CSV plutôt que JSON pour les données tabulaires. Datadog a découvert que le CSV consomme environ 50 % de tokens en moins que le JSON à données équivalentes. Pour des données sans imbrication, c’est le bon choix [Source : Datadog — Designing MCP tools for agents].
Les IDs uniquement quand ils servent en aval. Si aucun outil suivant ne prend l’ID en paramètre, ne l’incluez pas dans la réponse.

3.5 La gestion d’erreur

En API classique, un code 400 et un message suffisent. En MCP, l’erreur est une instruction de correction pour le LLM.

Le template à trois parties :

Ce qui a échoué
Ce qui était attendu
Un exemple de valeur correcte

Mauvais :

{ "error": "Invalid input" }

Bon :

{
  "error": "Format de date invalide pour 'departure': '15/04/2026'. Utiliser ISO 8601 (YYYY-MM-DD). Exemple : '2026-04-15'",
  "isError": true
}

Deux points critiques :

Toujours utiliser isError: true dans le résultat MCP. Sans ce flag, le client (Claude, ChatGPT) ne sait pas que l’appel a échoué et ne tente pas de correction [Source : Vonage — 4 Lessons Learned].
Suggérer une ou deux corrections maximum. Plusieurs options forcent le LLM à choisir au hasard. « stauts — vouliez-vous dire status ? » est mieux que trois suggestions [Source : Datadog].

Les réponses MCP peuvent aussi contenir du guidage contextuel mêlé aux résultats. Contrairement à une API REST, le serveur MCP peut ajouter « peut-être vouliez-vous le service payments ? » à côté des résultats de recherche — c’est un avantage à exploiter.

4. Combien d’outils ? Le problème du scaling

4.1 Les données empiriques

Le nombre d’outils n’est pas un choix de style — c’est un paramètre mesurable avec un seuil de décrochage.

Nombre d’outils	Taux de réussite	Source
10	~100 %	Speakeasy
20	~95 %	Speakeasy
30-40	Dégradation visible	Demiliani / SEP-1576
107	Échec complet	Speakeasy

Au-delà de 30-40 outils, les LLM présentent deux pathologies documentées :

Hallucination d’outils : le modèle invente des noms d’outils qui n’existent pas.
Confusion de paramètres : il mélange les paramètres d’outils différents.

La dégradation n’est pas progressive — elle est abrupte. Un serveur qui fonctionne à 20 outils peut s’effondrer à 30 [Source : SEP-1576 — Mitigating Token Bloat].

4.2 GitHub : de 40 outils à 13

Le cas le plus documenté. GitHub MCP Server exposait 101 outils dans sa configuration par défaut, consommant 64 600 tokens. La plupart des utilisateurs n’en personnalisaient jamais la liste et payaient un coût de performance pour des outils qu’ils n’utilisaient pas.

GitHub Copilot a réduit ses outils built-in de ~40 à 13 outils core + 4 catégories virtuelles. Résultats :

+2 à 5 points de taux de réussite sur les benchmarks SWE-Lancer et SWEbench-Verified.
-400 ms de latence moyenne (Time to Final Token).
-190 ms sur le Time to First Token.

La leçon de l’équipe : « Too many tools doesn’t always make [an agent] smarter. Sometimes it just makes it slower » [Source : GitHub Blog — How We’re Making Copilot Smarter with Fewer Tools].

4.3 La recommandation pratique

5 à 15 outils par serveur. C’est le consensus qui se dégage des retours d’expérience. Au-delà, il faut un mécanisme de découverte dynamique (sections 5 et 6).

Anthropic recommande de garder 3 à 5 outils les plus utilisés toujours chargés, et de différer les autres pour découverte à la demande. Le seuil de rentabilité de la découverte dynamique : 10+ outils ou 10 000+ tokens de définitions [Source : Anthropic — Advanced Tool Use].

5. Quatre patterns de gestion du scaling

Quand le nombre d’outils dépasse la capacité raisonnable d’un contexte, quatre patterns permettent de rester performant.

5.1 Découverte progressive

Guider l’agent par étapes plutôt que tout exposer d’un coup. L’idée mime le comportement d’un développeur humain qui tape --help avant de lire toute la doc.

Étape 1 : discover_categories()
         → ["gestion_commandes", "catalogue", "analytics"]

Étape 2 : get_category_actions("gestion_commandes")
         → [{ name: "track_order", desc: "..." },
            { name: "cancel_order", desc: "..." }]
         (noms + descriptions, pas de schémas)

Étape 3 : get_action_details("track_order")
         → { inputSchema: {...}, outputSchema: {...} }
         (schéma complet uniquement quand l'agent en a besoin)

Étape 4 : execute_action("track_order", { order_id: "..." })

Avantage : scale indéfiniment. Les tokens initiaux sont quasi-nuls. Inconvénient : latence supplémentaire (2-3 appels avant l’exécution). Quand l’utiliser : plateformes B2B avec des dizaines d’intégrations, marketplaces d’API [Source : Klavis].

5.2 Routage sémantique par embeddings

L’approche de GitHub Copilot. Plutôt que d’exposer tous les outils, un embedding de la requête utilisateur est comparé aux embeddings pré-calculés des outils, et seuls les plus pertinents sont chargés.

Résultats de GitHub :

Méthode	Couverture d’outils
Liste statique par défaut	69,0 %
Sélection par LLM	87,5 %
Routage par embeddings	94,5 %

+27,5 points absolus par rapport à la sélection par LLM. Les embeddings sont « précis, stables et reproductibles » — là où un LLM de catégorisation ne peut pas contrôler le nombre de groupes et coûte cher en tokens [Source : GitHub Blog].

5.3 Outils virtuels (clustering adaptatif)

Les outils sont regroupés en catégories sémantiques. Chaque catégorie est un « outil virtuel » qui fonctionne comme un répertoire. L’agent voit 4-5 catégories au lieu de 40 outils ; quand il sélectionne une catégorie, les outils pertinents sont déployés.

C’est la deuxième innovation de GitHub Copilot : des clusters calculés par similarité cosinus sur les embeddings, pas par catégorisation LLM.

5.4 Code mode

Au lieu d’appeler des outils séquentiellement, l’agent écrit un programme complet qui orchestre les appels. C’est le pattern le plus radical — détaillé en section 8.

6. Les trois primitives : outils, resources, prompts

MCP définit trois types de capacités, chacun avec un plan de contrôle différent. La plupart des serveurs n’utilisent que les outils. C’est une erreur de design.

Primitive	Contrôleur	Usage
Tool	Le LLM décide quand l’invoquer	Actions, requêtes, mutations
Resource	L’application hôte décide quand l’injecter	Documentation, schémas, templates, configuration
Prompt	L’utilisateur décide quand le déclencher	Workflows complets, séquences déterministes

6.1 Resources : le contexte de référence

Les resources fournissent du matériel de lecture — documentation, schémas, templates — que le LLM peut consulter sans exécuter d’action. Elles sont application-controlled : c’est le client (Claude Desktop, Cursor) qui décide quand les injecter dans le contexte, pas le modèle.

Cas d’usage typiques :

Un schéma de base de données que le LLM consulte avant d’écrire une requête.
Un template de rapport que l’agent doit suivre.
La documentation d’une API tierce dont les outils dépendent.

Le problème aujourd’hui : le support côté clients est mince. Peu de clients MCP implémentent correctement l’injection de resources. Trois ponts existent en attendant :

Servir le contenu de la resource via un outil (get_schema, get_template).
L’inclure dans un prompt via .with_resource().
Utiliser des préfixes URI sémantiques (docs://, config://, template://) pour être prêt quand les clients mûriront.

6.2 Prompts : les workflows encodés

Les prompts sont le primitif le plus sous-utilisé — et probablement le plus puissant pour les cas d’usage production.

Un prompt MCP n’est pas un template de message. C’est un workflow complet avec des étapes serveur-side, du data flow entre étapes, et des points d’intervention pour le LLM uniquement là où l’intelligence est nécessaire.

Le problème qu’ils résolvent :

Quand un LLM orchestre un workflow multi-étapes avec des outils seuls, il atteint ~60-70 % de conformité sur les tâches complexes. Le mode d’échec dominant : le modèle saute les étapes déterministes pour économiser des appels et fait le calcul lui-même — avec des erreurs.

L’approche workflow :

Rapport de ventes hebdomadaire :

Étape 1 (serveur) : requête BDD → sales_data
Étape 2 (serveur) : agrégation par catégorie → aggregated
Étape 3 (serveur) : calcul tendances semaine-sur-semaine → trends
Étape 4 (LLM)    : rédiger le résumé exécutif à partir des données

Les trois premières étapes sont déterministes — le serveur les exécute et retourne les résultats. Le LLM ne reçoit le contrôle qu’à l’étape 4, avec toutes les données déjà calculées. Le calcul de tendances ne peut plus être hallucié.

Résultat : 85-95 % de conformité au lieu de 60-70 %.

Le conseil de design : « observer les tâches que votre équipe répète chaque semaine. Ce sont des candidats prompt, pas des requêtes ad-hoc » [Source : MCP Prompts and Resources: The Primitives You’re Not Using].

6.3 Quand utiliser quoi

Question	Réponse
L’agent doit-il décider seul quand agir ?	Tool
L’agent a besoin de contexte de référence pour mieux décider ?	Resource
L’utilisateur déclenche toujours le même workflow ?	Prompt
Le workflow mélange étapes déterministes et étapes intelligentes ?	Prompt avec des tools en interne
Le support client pour les resources est trop immature ?	Tool qui retourne le contenu de la resource

7. Le design des réponses

Le format de ce que votre serveur retourne a un impact mesurable sur la qualité de l’agent.

7.1 CSV > JSON pour le tabulaire

Datadog a mesuré : le CSV consomme ~50 % de tokens en moins que le JSON pour des données tabulaires sans imbrication. Avec le même budget de tokens, ils ont pu retourner 5× plus d’enregistrements.

# JSON : ~45 tokens par enregistrement
[{"timestamp":"2026-04-15T10:00:00Z","service":"api","status":"error","latency_ms":1250},
 {"timestamp":"2026-04-15T10:01:00Z","service":"api","status":"ok","latency_ms":85}]

# CSV : ~22 tokens par enregistrement
timestamp,service,status,latency_ms
2026-04-15T10:00:00Z,api,error,1250
2026-04-15T10:01:00Z,api,ok,85

Règle : si les données n’ont pas d’imbrication, CSV ou TSV. Si elles sont imbriquées, JSON minimal [Source : Datadog].

7.2 Paginer par tokens, pas par records

La pagination classique par nombre d’enregistrements (limit=50) ne tient pas compte de la taille variable des enregistrements. Datadog a basculé sur une pagination par budget de tokens : le serveur retourne autant d’enregistrements que le budget le permet, avec un curseur pour la suite.

C’est un changement de paradigme par rapport au design d’API classique, mais c’est ce que la contrainte de contexte window impose.

7.3 Guidage contextuel dans les réponses

Contrairement à une API REST, un serveur MCP peut mêler des données et des indices de navigation dans la même réponse.

{
  "results": [...],
  "note": "Les résultats sont filtrés par le service 'api'. Vouliez-vous le service 'payments' ? Utilisez search_logs(service='payments')."
}

Datadog l’a implémenté systématiquement : des suggestions de correction, des alias de champs, des liens vers d’autres outils. C’est un levier puissant pour guider l’agent sans alourdir les descriptions [Source : Datadog].

7.4 Distinguer les états de sortie

Retourner un booléen success/failure est insuffisant. Chaque état distinct doit guider une décision différente de l’agent :

État	Ce que l’agent doit comprendre
`nothing_found`	Élargir la recherche
`invalid_reference`	Corriger le paramètre
`permission_denied`	Demander à l’utilisateur
`rate_limited`	Attendre et réessayer
`partial_results`	Continuer avec la pagination

Source : Workato — Designing MCP Tools.

8. Code mode : le paradigme alternatif

8.1 Le constat de Cloudflare

L’argument de Cloudflare est frontal : « LLMs have seen a lot of code. They have not seen a lot of tool calls ». Le tool calling repose sur des données d’entraînement synthétiques ; la génération de code exploite des millions de dépôts open-source.

En code mode, l’agent ne fait pas 50 appels séquentiels — il écrit un programme complet qui orchestre les appels en parallèle, filtre, agrège, et ne retourne que le résultat final.

// Au lieu de 50 appels séquentiels dans le contexte :
const results = await Promise.all(
  pages.map((i) => mcp.call("search_leads", { page: i })),
);
const filtered = results.flatMap((r) => r.leads).filter((l) => l.score > 80);
return { count: filtered.length, top_10: filtered.slice(0, 10) };

Les résultats intermédiaires ne passent jamais par le réseau neuronal du LLM. Seul le résultat final entre dans le contexte [Source : Cloudflare — Code Mode: The Better Way to Use MCP].

8.2 Quand le code mode bat le tool calling

Scénario	Tool calling	Code mode
Opération simple, un seul outil	Optimal	Overhead inutile
Batch de 50+ appels parallèles	200k+ tokens dans le contexte	~1 000 tokens (résumé seul)
Filtrage/agrégation de données	Chaque intermédiaire dans le contexte	Traitement local
Workflow CRM complexe	50+ appels séquentiels	Un seul programme

Anthropic a mesuré 37 % de réduction de tokens sur des tâches complexes en utilisant du code d’orchestration plutôt que des appels séquentiels. La consommation moyenne est passée de 43 588 à 27 297 tokens [Source : Anthropic — Advanced Tool Use].

8.3 Ce que ça implique pour le design du serveur

Si le code mode prend de l’ampleur — et les signaux de Cloudflare, Anthropic et GitHub vont dans ce sens — alors le serveur MCP devient une bibliothèque d’API typée plus qu’un catalogue d’outils. Les descriptions importent toujours (elles guident la génération de code), mais les schémas prennent une importance encore plus grande : l’agent génère du code qui doit compiler.

9. Statelessness, idempotence et récupération

9.1 Stateless par défaut

Un serveur MCP dont les outils dépendent d’un état interne (« appeler A avant B ») force le LLM à maintenir cet état dans son contexte — ce qu’il fait mal.

Principe : chaque appel d’outil doit être auto-suffisant. Si un état est nécessaire, l’externaliser dans un store durable (Redis, base de données) et passer une référence (un ID de session, un curseur) en paramètre.

L’avantage collatéral : un serveur stateless se scale horizontalement sans problème [Source : Nordic APIs — 8 Tips].

9.2 Idempotence

Les agents font des erreurs et retentent. Un outil create_order appelé deux fois ne doit pas créer deux commandes. Le même pattern qu’en design d’API REST (clé d’idempotence), mais encore plus critique quand le consommateur est un LLM qui ne lit pas les headers de réponse avec la même fiabilité qu’un client HTTP.

9.3 Séparation serveur / transport

Un conseil récurrent dans les retours d’expérience : découpler la logique métier du transport dès le début. Un serveur MCP peut être consommé en stdio (IDE local), en Streamable HTTP (production distante), ou demain en WebSocket. Si la logique est couplée au transport, chaque nouveau client impose un refactor [Source : Vonage].

10. Sécurité : ce qui est spécifique à MCP

La sécurité MCP a été couverte en détail dans l’article précédent (section 5). Ici, les points spécifiques au design du serveur :

10.1 Ne jamais passer d’input utilisateur directement

Un audit Invariant Labs de 2025 a trouvé que 43 % des serveurs MCP précoces contenaient des vulnérabilités d’injection de commande. La règle est simple : valider chaque paramètre contre son schéma JSON avant traitement. Pas de concaténation dans des commandes shell, des requêtes SQL, ou des chemins de fichier [Source : Nordic APIs].

10.2 Le danger du tool poisoning

Les descriptions d’outils sont lues par le LLM — pas affichées à l’utilisateur. Un serveur malveillant peut cacher des instructions dans ses descriptions qui redirigent l’agent. La contre-mesure côté design : des descriptions vérifiables et signées, avec invalidation automatique si le schéma change (cf. Sigstore, GitHub Attestations).

10.3 Sandbox d’exécution

Pour le code mode, Cloudflare utilise des isolates V8 plutôt que des conteneurs : démarrage en quelques millisecondes, quelques mégaoctets de mémoire, pas d’accès réseau direct. Le code généré ne reçoit que des bindings typés vers les serveurs MCP autorisés — jamais d’accès brut au réseau.

Pour les serveurs classiques, les mêmes principes s’appliquent : sandboxer l’exécution des outils via conteneurs ou WebAssembly, surtout en multi-tenant [Source : Cloudflare].

11. Évaluer la qualité d’un serveur MCP

11.1 Métriques de sélection d’outils

GitHub traite la sélection d’outils comme un problème de classification multi-classes :

Accuracy : pourcentage d’inputs qui déclenchent le bon outil.
Precision : proportion de bons appels parmi tous les appels à cet outil.
Recall : proportion de bons appels parmi les cas où l’outil aurait dû être appelé.
Matrice de confusion : quels outils sont confondus entre eux — guide les améliorations de noms et descriptions.

Source : GitHub Blog — Measuring What Matters.

11.2 Métriques de qualité des paramètres

Quatre tests spécifiques :

Hallucination de paramètres : le modèle a-t-il inventé un nom de paramètre ?
Complétude : tous les paramètres attendus sont-ils fournis ?
Paramètres requis : les champs obligatoires sont-ils présents ?
Valeurs exactes : les valeurs correspondent-elles aux attentes ?

11.3 Test pragmatique

En l’absence d’infrastructure de benchmark :

Tester la sélection d’outils sur 10 requêtes utilisateur diversifiées — viser 90 %+ de précision.
Faire passer 20 utilisateurs métier sur leurs workflows réels — viser 80 %+ de complétion.
Tracer quels outils sont appelés, lesquels échouent, et quelles requêtes ne matchent aucun outil.

Source : MCP Tool Design: Why Your AI Agent Is Failing.

12. Récapitulatif des design patterns

Pattern	Quand l’utiliser	Token cost initial	Latence	Complexité
Outils orientés intention	Toujours, par défaut	Moyen	Faible	Faible
Découverte progressive	>15 outils, plateforme B2B	Quasi-nul	+2-3 appels	Moyenne
Routage sémantique	>20 outils, accès fréquent	Quasi-nul	+1 lookup	Élevée
Outils virtuels (clusters)	>20 outils, catégories naturelles	Réduit	+1 appel	Moyenne
Code mode	Batch, agrégation, 50+ appels	Très faible	Variable	Élevée
Prompts-workflows	Workflows répétés, étapes déterministes	Moyen	Réduit	Moyenne
Format CSV	Données tabulaires	N/A (réponse)	N/A	Faible

13. Pièges et limitations connues

Le réflexe du miroir d’API

Le piège le plus courant. Un développeur prend une spec OpenAPI de 200 endpoints, génère 200 outils MCP. L’agent s’effondre. Le bon réflexe : identifier les 20-30 intentions utilisateur réelles et construire les outils autour d’elles [Source : The MCP Tool Trap — Jentic].

L’intelligence prématurée

Essayer de rendre le serveur « intelligent » trop tôt — des réponses qui interprètent, qui résument, qui devinent. Ça casse la fiabilité. Le serveur doit être déterministe et laisser l’intelligence au LLM [Source : Datadog].

La configuration silencieuse

La majorité du temps de développement initial est perdu en configuration, pas en code. Les configs MCP ne se comportent pas comme des scripts shell : le client spawn un process directement, pas de sh -c, pas de cd, pas de chaînage. Les échecs sont silencieux si les chemins ne sont pas absolus [Source : Vonage].

Le dump de données

Exposer des resources géantes — inventaires complets, configurations entières, dumps de base. Le modèle est noyé dans le bruit, le risque d’hallucination augmente. Garder les resources petites et ciblées [Source : Nordic APIs].

Le trust approve-once

La plupart des clients MCP fonctionnent en approve-once-trust-forever. Si le serveur change son schéma après approbation — intentionnellement (rug pull) ou par mise à jour — le client ne le détecte pas. C’est un problème de design d’écosystème, pas de serveur, mais il faut en être conscient quand on versionne ses outils [Source : Andrew Baker — MCP in 2026].

Le test uniquement en dev

Le fossé entre un serveur MCP qui marche dans Cursor en local (stdio, un seul utilisateur, réseau rapide) et un serveur qui tient en production (Streamable HTTP, multi-tenant, latence réseau) est significatif. Tester le transport distant dès le début [Source : Vonage].

14. Ce qu’il faut retenir

Le contexte window est la contrainte première. Chaque outil coûte 550-1 400 tokens. Cinq serveurs × 20 outils = plus de la moitié du budget parti avant que l’utilisateur parle. Less is more.
Penser intentions, pas endpoints. Un outil par intention utilisateur, pas par route API. Le serveur orchestre en interne, l’agent consomme le résultat.
5 à 15 outils par serveur. Au-delà, utiliser la découverte progressive, le routage sémantique, ou les outils virtuels. L’effondrement à 30+ outils est empiriquement documenté.
Les descriptions sont le cœur du design. Pas les schémas, pas le code — les descriptions. C’est la surface de décision du LLM. Y investir le même effort que dans une bonne documentation d’API.
Les réponses comptent autant que les requêtes. CSV plutôt que JSON pour le tabulaire (50 % de tokens en moins). Réponses bornées. Guidage contextuel dans les résultats. Paginer par tokens, pas par records.
Les prompts sont le primitif sous-utilisé. Pour les workflows répétés, encoder les étapes déterministes côté serveur et ne laisser le LLM intervenir que là où l’intelligence est nécessaire. 85-95 % de conformité au lieu de 60-70 %.
Le code mode monte. Cloudflare, Anthropic, GitHub convergent vers la génération de code plutôt que l’appel séquentiel d’outils — 37 % de tokens en moins sur les tâches complexes. Ça change la nature du serveur MCP : moins un catalogue d’outils, plus une bibliothèque d’API typée.
Tester comme un problème de classification. Accuracy, precision, recall, matrice de confusion sur la sélection d’outils. 10 requêtes diversifiées, 90 %+ de précision comme cible.
La sécurité est un problème de design, pas de déploiement. 43 % des serveurs précoces avaient des injections. Valider au schéma, sandboxer l’exécution, signer les descriptions.

Le message de fond est le même que pour toute bonne UX : l’effort de conception se déplace vers la compréhension de l’utilisateur — sauf que l’utilisateur est un modèle de langage avec un budget d’attention fixe, aucune patience, et une tendance à halluciner quand on lui donne trop de choix.