Analyser un serveur MCP — Analyse des intentions et des erreurs
Produisez un rapport qui répond à trois questions concernant un serveur MCP instrumenté avec le SDK MCP Analytics d'Amplitude :
- Quels outils sont utilisés, et lesquels échouent ? (volume par outil + taux d'erreur)
- Que tentent de faire les appelants avec chaque outil, et où chaque intention échoue-t-elle ? (justifications dans un outil × message d'erreur)
- Que doit corriger l'équipe en priorité ? (correctifs fondés sur les preuves d'erreur, pas sur des impressions)
L'élément clé qui rend cette analyse précieuse : l'outil localise le correctif ; la justification explique l'intention derrière celui-ci. Un taux d'erreur global indique "4,5 % des appels échouent." Ventilé par outil, il indique "query_chart échoue 22 % du temps" — vous savez maintenant quoi ouvrir. L'ajout des justifications dans cet outil indique "les échecs sont dus à des agents de rafraîchissement de tableau de bord qui atteignent la limite de taille de lot" — vous savez maintenant pourquoi, et le correctif s'écrit de lui-même. La justification est largement limitée à l'outil (chaque outil a sa propre raison d'être appelé), donc l'outil est l'axe principal et la justification est la deuxième coupe à l'intérieur de celui-ci — regrouper les justifications à l'échelle globale ne fait que retrouver les limites des outils tout en mélangeant des intentions incomparables.
Prérequis
-
Connecteur MCP Amplitude actif. S'il ne l'est pas, arrêtez-vous et demandez à l'utilisateur d'ajouter le connecteur Amplitude dans ses paramètres d'outils/connecteurs — il n'y a pas de source de données de repli.
-
Un projet contenant les événements du SDK. Le SDK émet des événements par défaut appartenant au SDK, tous préfixés
[MCP], et — point crucial — chaque propriété par défaut qu'ils transportent est également préfixée[MCP], ils peuvent avoir des propriétés personnalisées.Événements :
[MCP] Tool Call Response— le cheval de bataille : un événement par invocation d'outil qui a atteint un callback d'outil (succès ou erreur).[MCP] Tool Call Rejected— untools/callqui a échoué avant l'exécution d'un outil (outil inconnu/désactivé, validation du schéma d'entrée). C'est là qu'atterrissent les noms d'outils hallucinés/mal typés, portés sur[MCP] Attempted Tool Name(maintenu hors du[MCP] Tool Nameréservé).[MCP] Session Initialized,[MCP] Session Ended,[MCP] Tools Listed.
Propriétés clés sur
[MCP] Tool Call Response:[MCP] Tool Name,[MCP] Client Name,[MCP] Client Version,[MCP] Session ID,[MCP] Auth Type,[MCP] Rationale,[MCP] Is Error,[MCP] Error Message,[MCP] Error Type(returned_errorvsthrown_exception— sépare un outil qui a signalé un échec de celui qui a planté),[MCP] Response Duration,[MCP] Response Size,[MCP] Request Size. -
Les noms d'événements/propriétés peuvent encore dériver entre les versions du SDK. Ne supposez jamais — vérifiez avec les outils de taxonomie dans la Phase 0. Les noms canoniques ci-dessus proviennent du fichier
constants.tsdu SDK (EVENT_PROPERTY_KEYS) ; si les données du projet divergent, faites confiance au projet et adaptez-vous.
Phase 0 — Localiser et valider les données
- Appelez l'outil de contexte Amplitude (sans projectId) pour lister les projets. Si plusieurs projets plausibles existent et que l'utilisateur n'en a pas spécifié un, demandez.
- Confirmez que les événements
[MCP]existent dans le projet choisi (recherchez des événements ou listez les événements ;get_eventsfiltre uniquement par nom exact, utilisez donc la recherche pour la découverte du préfixe[MCP]). - Récupérez les propriétés d'événement pour
[MCP] Tool Call Response(et[MCP] Tool Call Rejected) afin de confirmer les noms exacts des propriétés — rappelez-vous qu'elles sont préfixées[MCP]et en casse titre (par exemple[MCP] Rationale, pastool rationale). Liez ce que vous trouvez aux noms utilisés dans les requêtes ci-dessous. - Exécutez une requête de volume/récence : totaux de
[MCP] Tool Call Response,[MCP] Session Initializedsur les 60 derniers jours, par intervalle hebdomadaire. Cela vous indique la fenêtre de date utilisable et s'il y a suffisamment de données. En dessous d'environ 5 000 appels d'outils au total, prévenez l'utilisateur que les ventilations par outil seront minces et les pourcentages instables — poursuivez quand même, mais mentionnez-le dans le rapport.
Enregistrez : l'ID du projet, la fenêtre de date, le volume total d'appels. Chaque requête ultérieure utilise la même plage pour que les nombres restent comparables.
Phase 1 — Ventilation par outil (l'épine dorsale)
C'est la carte principale ; tout le reste s'y rattache.
- Volume par outil : totaux de
[MCP] Tool Call Response, groupés par[MCP] Tool Name, groupByLimit ~100. - Erreurs par outil : identique, plus filtre
[MCP] Is Error is "true". - Appels rejetés par nom tenté : totaux de
[MCP] Tool Call Rejectedgroupés par[MCP] Attempted Tool Name. Ceux-ci n'atteignent jamais un callback, ils sont donc invisibles pour les deux requêtes ci-dessus — mais un nom tenté à volume élevé qui n'est pas un outil réel est l'un des résultats les plus exploitables qui soit (un changement de nom ou une hallucination que les agents devinent).
Calculez par outil le volume d'appels, le nombre d'erreurs et le taux d'erreur, et classez les outils de deux manières : par volume d'appels (ce qui est porteur de charge) et par volume d'erreurs (ce qui coûte le plus d'échecs). Choisissez les 3 à 5 outils principaux pour l'analyse approfondie — privilégiez le volume d'erreurs élevé, pas seulement le trafic élevé, et respectez le choix de l'utilisateur s'il a nommé des outils spécifiques. Un outil à faible trafic avec un taux d'erreur de 90 % peut surpasser un outil très fréquenté mais sain.
Phase 2 — Justifications dans chaque outil principal (le "pourquoi")
Pour chaque outil principal, échantillonnez ses justifications — totaux de [MCP] Tool Call Response groupés par [MCP] Rationale, filtrés sur ce seul outil ([MCP] Tool Name is "<tool>"), groupByLimit ~150. Ensuite, lisez-les et regroupez-les par ce que l'appelant essaie d'accomplir avec cet outil, pas par formulation. Conseils :
- Au sein d'un même outil, vous trouverez généralement 2 à 5 groupes d'intention, pas neuf — l'outil réduit déjà l'objectif. Nommez-les par intention (par exemple pour un outil
query_chart: "rafraîchissement de tableau de bord en direct", "exploration ad-hoc", "génération de rapports planifiés"). - Pondérez par volume d'appels (chaque valeur de justification porte son total), pas par chaînes distinctes.
- Surveillez un groupe indésirable : "placeholder", "ignore", "noop", "test", "dummy", lettres uniques. Sa taille est un résultat d'hygiène des justifications, et les éléments indésirables ne doivent pas contaminer les intentions réelles.
- Les justifications comme "Retry after rate limit" / "Retrying X" signalent des boucles de nouvelle tentative — notez-les.
- Les justifications non anglaises sont normales ; regroupez-les par sens.
- Calculez la couverture des justifications par outil (part des appels de l'outil avec une justification non vide). Si elle est faible (<50 %), les intentions ne décrivent qu'une partie — dites-le, et "améliorer la couverture des justifications au moment de l'instrumentation" devient une recommandation en soi.
- Calculez la part de l'intention principale par outil (le plus grand groupe d'intention en % des appels couverts par une justification de l'outil). C'est le signal de concentration : ~90 % signifie que l'outil sert une seule tâche et vous pouvez l'optimiser fortement (resserrez le schéma/description autour de ce chemin) ; une répartition plate (intention principale ~30 %) signifie que l'outil est surchargé et mérite peut-être d'être divisé, ou que ses erreurs seront réparties sur des intentions non liées. Signalez le nombre et, lorsque l'intention principale est dominante, nommez-la à côté de l'outil.
Workflows multi-outils (secondaire) : certaines justifications décrivent un objectif multi-outil ("résoudre l'ID du graphique avant de rafraîchir le tableau de bord"). Lorsqu'une seule intention couvre clairement plusieurs outils (par exemple search_events → create_chart → create_dashboard), mentionnez-la comme un workflow dans la section transversale — c'est la seule chose qu'une vue purement outil par outil manque.
Phase 3 — Analyse approfondie des erreurs par outil
Pour chaque outil principal, exécutez (filtré sur cet outil + [MCP] Is Error is "true") :
- groupé par
[MCP] Error Message→ pourquoi il échoue - éventuellement divisé par
[MCP] Error Type(returned_errorvsthrown_exception) lorsqu'un message est ambigu — un plantage et un refus bien formé lèvent tous deux[MCP] Is Error, mais un seul est un bogue dans l'outil.
Lorsqu'un outil a un groupe d'intention dominant de la Phase 2, qualifiez les erreurs par justification (ajoutez le filtre contains de justification) pour obtenir la phrase "cette intention échoue de cette façon".
Classez chaque message d'erreur significatif dans un archétype — l'archétype détermine le correctif :
| Archétype | Signature | Modèle de correctif |
|---|---|---|
| Nom d'outil obsolète/halluciné | [MCP] Tool Call Rejected avec [MCP] Attempted Tool Name = un nom renommé ou plausible | Alias côté serveur pour les outils renommés ; réponses de rejet qui nomment l'outil réel le plus proche pour que les agents s'auto-corrigent en un coup |
| Paramètre obligatoire manquant | erreur de validation, "Required", le chemin nomme un paramètre | Assouplir le schéma (accepter valeur unique ou tableau, ajouter des valeurs par défaut), ou faire en sorte que la description de l'outil énonce les exigences pour que les agents les respectent avant l'exécution |
| Inadéquation de forme du schéma | "Expected object, received string" etc. | Ajouter une coercition côté serveur, ou un exemple en ligne dans la description de l'outil |
| Collision de limite stricte | "Maximum of N …", "too_big" | Augmenter la limite, découper automatiquement côté serveur, ou indiquer la limite dans la description du paramètre — les agents n'apprennent actuellement les limites qu'en échouant |
| Violation de plage/conservation | "time range too large", "does not retain data before …" | Auto-coercition (par exemple, réduire la granularité) au lieu d'erreur ; annoncer les limites de conservation/plage dans la charge utile du contexte |
| Paramètre circulaire | un outil de contexte/découverte nécessite exactement l'ID qu'il existe pour fournir | Faire en sorte que les outils de découverte fonctionnent avec zéro argument obligatoire, par défaut à partir du jeton d'authentification |
| Autorisation refusée | langage de rôle/permission | Classe d'erreur distincte pour que "non autorisé" soit séparable de "cassé" ; souvent aussi un écart de documentation/onboarding |
| Erreur récurrente planifiée | même message se répétant quotidiennement sur le même outil | Corriger l'appelant du travail si interne ; pour le produit, signaler comme une automatisation qui se dégrade silencieusement — personne ne surveille une fenêtre de chat |
| Transitoire/amont | 5xx, timeouts, limites de débit | Indices de nouvelle tentative après dans le corps de l'erreur ; vérifier si les nouvelles tentatives ont effectivement lieu (voir l'entonnoir de boucle) |
Les meilleurs messages d'erreur énoncent le correctif ("ré-exécuter avec start >= …"). Confrontez chaque message d'erreur à volume élevé à cette norme — "rendre cette erreur aussi exploitable que votre meilleure" est souvent une recommandation légitime.
Phase 4 — Métriques contextuelles (optionnelles)
Ajoutez si le temps le permet ; elles affinent l'histoire :
- Boucle d'erreur répétée : entonnoir en 3 étapes, chaque étape
[MCP] Tool Call Responseavec[MCP] Is Error is "true", en maintenant[MCP] Tool Nameconstant, fenêtre de conversion d'environ 1 h. Montre quelle part des utilisateurs en erreur tourne en boucle sur le même outil. (Les étapes n'ont pas besoin d'être des événements consécutifs — dites "3+ erreurs sur le même outil en une heure", pas "3 consécutives".) - Erreur → récupération : entonnoir en 2 étapes, erreur puis succès, en maintenant le nom de l'outil constant. Un taux de récupération élevé associé à un taux de boucle élevé signifie ensemble que le coût est en tokens/latence gaspillés, pas en abandon — une conclusion matériellement différente.
- Mix client : uniques groupés par
[MCP] Client Name. Une part importante "inconnue" ou des noms de clients quasi-dupliqués (casse, variantes préfixées par plugin) sont des résultats d'instrumentation qui valent la peine d'être signalés.
Phase 5 — Vérifier, puis écrire
Avant d'écrire, revérifiez au moins un chiffre clé d'une deuxième manière (par exemple, le taux d'erreur global via une requête distincte de totaux de deux événements). Recalculez chaque pourcentage que vous citez à partir des totaux bruts. Si un nombre ne peut pas être vérifié, supprimez-le ou qualifiez-le d'estimation.
Structure du rapport
Utilisez ce modèle — organisé d'abord par outil :
# Analyse du serveur MCP — <nom du serveur/projet>
Données : <projet>, <fenêtre de date>, <N> appels d'outils, taux d'erreur global <X>%.
Note méthodologique : les ventilations par outil sont des résultats exacts de requêtes ; les intentions intra-outil sont dérivées du modèle à partir des justifications (directionnelles). Les noms d'appels rejetés proviennent de [MCP] Tool Call Rejected.
## Outils en un coup d'œil
<table : outil | appels | erreurs | taux d'erreur | intention principale (part %) | couverture des justifications>
<une ligne sur les noms d'outils rejetés/tentés si pertinent ; signaler les justifications indésirables si pertinent>
## Analyse approfondie : 3 à 5 outils principaux (classés par volume d'erreurs)
Pour chaque outil :
**Outil : <nom> — <appels>, <taux d'erreur> — à quoi il sert : <une phrase>**
- Intentions (justifications dans cet outil) : <groupe : part>, …
- 1 à 4 recommandations numérotées. Chacune énonce la preuve (message d'erreur + nombre), l'archétype et le correctif concret. Commencez par le correctif qui supprime le plus de volume d'erreurs.
## Résultats transversaux
<workflows multi-outils, taux de boucle/récupération, hygiène des noms de clients, hygiène des justifications, trafic de test interne, …>
## La phrase clé à retenir
<le changement unique qui supprime le plus de volume d'échecs, avec son nombre>
Style : des nombres à côté de chaque affirmation ; nommez les messages d'erreur textuellement (tronqués) pour que les ingénieurs puissent les rechercher ; les recommandations formulées comme des actions ("Expédier un alias pour query_chart → query_charts"), pas comme des observations ("la dénomination des outils pourrait être améliorée").
Graphiques dans la sortie
Rendez les graphiques Amplitude de support là où le client le prend en charge, en utilisant les outils de requête et de rendu de graphiques ad-hoc (construire une définition eventsSegmentation/funnels, puis la rendre). Soyez délibéré sur ce qui peut et ne peut pas être un graphique :
- Peut être représenté graphiquement — tout ce qui est basé sur une requête. Ce sont de vrais résultats de segmentation/entonnoir Amplitude, alors représentez-les : appels et erreurs par outil (groupés par
[MCP] Tool Name), taux d'erreur dans le temps, appels rejetés par[MCP] Attempted Tool Name, les entonnoirs de boucle d'erreur et de récupération par outil, et le mix client par[MCP] Client Name. La ventilation par outil est le graphique principal naturel. - Ne peut pas être représenté graphiquement — les groupes d'intention intra-outil. Le regroupement des justifications en intentions se fait dans ce modèle ; ces regroupements n'existent pas en tant que propriété Amplitude, il n'y a donc pas de graphique sauvegardé pour "appels par intention". Présentez les intentions sous forme de tableau construit à partir des totaux de justifications, et dites clairement que les chiffres d'intention sont dérivés du modèle (directionnels) tandis que les graphiques que vous rendez sont des résultats exacts de requêtes. N'impliquez pas qu'un graphique rendu soutient le regroupement des intentions.
Recueil de requêtes
Toutes les requêtes sont des définitions eventsSegmentation ou funnels par rapport à l'ID de projet de la Phase 0. Ajustez les noms d'événements/propriétés à ce que la Phase 0 a vérifié. Formes qui sont connues pour fonctionner :
Ventilation des outils (Phase 1) :
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Calls by Tool",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
"metric":"totals","countGroup":"User","groupBy":[],
...}
}
Requête d'erreurs par outil (Phase 1) :
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Errors by Tool",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Tool Name"}],
"filter_clause":"is_true([MCP] Is Error)"}],
"metric":"totals","countGroup":"User","groupBy":[],
...}
}
Justifications pour un outil spécifique (Phase 2) :
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Rationales for <tool>",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Rationale"}],
"filter_clause":"is_equal([MCP] Tool Name, \"<tool>\")"}],
"metric":"totals","countGroup":"User","groupBy":[],
...}
}
**Mesures contextuelles (Phase 4) — construisez des définitions d'entonnoir avec des fenêtres de conversion de 1 h et les mêmes propriétés/filtres. Utilisez "filter_clause" avec "is_equal" ou "is_true".
Ajustez les noms de propriétés exacts à ce que Phase 0 a vérifié. Remplacez toujours <PROJECT_ID> et <tool> par les valeurs réelles.
Lectures complémentaires
Consultez le référentiel du SDK MCP Analytics pour les événements complets et la documentation des propriétés : Analyse MCP avec Amplitude