Configuration de l'Analytique MCP Amplitude
Instruments un serveur MCP pour que chaque appel d'outil devienne un événement Amplitude, joignable au reste des données Amplitude du produit (rétention, revenus, usage web/mobile).
La référence SDK faisant autorité est le README du paquet :
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics).
Le SDK est en préversion et évolue rapidement — récupérez toujours le dernier README et suivez-le pour
l'installation, les formes d'API, la configuration et les événements par défaut. Ne vous fiez pas à des extraits mémorisés ou
aux résumés de cette compétence pour les détails de l'API du SDK ; le README prévaut en cas de conflit.
Il y a quatre étapes. Les étapes 1 à 2 sont obligatoires et sont documentées dans le README — cette compétence vous dit quelles sections suivre et quels invariants vérifier. Les étapes 3 à 4 sont fortement recommandées et sont documentées en détail ici, car elles nécessitent des modifications en dehors du SDK (les schémas d'outils du serveur et l'application web du produit) que le README du SDK ne couvre intentionnellement pas.
Faites-les dans l'ordre : Étape 1 (appels d'outils) → Étape 2 (identité) → Étape 3 (justification) → Étape 4 (UTM, uniquement si le serveur renvoie des liens). Assurez-vous d'avoir l'identité correcte avant de déclarer quoi que ce soit comme « terminé » — tout ce qui suit en dépend.
Avant de commencer
Confirmez :
- Il s'agit d'un serveur MCP Node/TypeScript basé sur
@modelcontextprotocol/sdk. Ce SDK ne prend pas en charge d'autres langages/exécutions. - L'utilisateur a (ou peut obtenir) une clé API Amplitude pour le projet dans lequel les événements doivent arriver.
- Quel gestionnaire de paquets le dépôt utilise (pnpm/npm/yarn) — ajustez la commande d'installation en conséquence.
Étape 1 — Installer le SDK et suivre les appels d'outils (obligatoire)
Récupérez le README et suivez ses sections Installation et Démarrage rapide. Installez toujours la dernière
version publiée (ex. pnpm add @amplitude/mcp-analytics@latest) — ne figez jamais une version de mémoire,
et ne reproduisez pas les commandes d'installation de cette compétence.
Invariants à vérifier une fois le branchement effectué (le README explique chacun) :
analytics.instrumentServer(server, ...)s'exécute avantserver.connect()— l'ordre est important.- Chaque gestionnaire d'outil est enveloppé avec
analytics.instrumentTool(...). Les outils non enveloppés ne sont pas suivis. L'enveloppe a la même forme que le gestionnaire et est un passe-through sans effet si le serveur n'a jamais été lié, il est donc sûr d'envelopper défensivement. - Les événements par défaut portent tous le préfixe
[MCP], donc ils n'entrent jamais en collision avec les événements Amplitude existants du produit. Consultez le tableau des Événements par défaut du README (etdocs/events.mddans le dépôt) pour l'ensemble actuel des événements et propriétés.
Optionnel : attachez des dimensions personnalisées stables (niveau de plan, équipe, indicateurs de fonctionnalité) via extra sur
instrumentTool/instrumentServer — voir la section Propriétés d'événement personnalisées du README.
Étape 2 — Obtenir une identité correcte (obligatoire, faites ceci avant de déclarer l'étape 1 « terminée »)
Les événements MCP doivent porter le même user_id que le produit envoie déjà à Amplitude depuis le web/mobile.
Ignorer ceci et l'utilisation MCP apparaîtra comme une population déconnectée qui ne peut pas être jointe aux données produit —
ceci va à l'encontre de l'objectif principal de l'intégration.
Suivez la section Identité du README pour l'API actuelle : elle propose une liaison au niveau du serveur,
setIdentity() par requête à l'intérieur d'un gestionnaire, et une carte resolveIdentity optionnelle à partir des
revendications authInfo de la requête. Choisissez celle qui correspond au modèle d'authentification du serveur.
Un comportement à signaler à l'utilisateur : les événements entièrement anonymes, sans ancrage sont ignorés par défaut
(non comptés comme utilisateurs) sauf si l'option emitAnonymousEvent: true est explicitement activée pour un suivi
uniquement agrégé — demandez avant d'activer ceci, car cela modifie ce qui est compté.
Étape 3 — Capturer la justification (recommandé)
Contrairement à un humain cliquant sur un bouton, un agent peut vous dire pourquoi il a appelé un outil. Capturer ceci transforme les données de « ce qui s'est passé » en « ce que l'utilisateur essayait de faire ».
Le côté SDK est un appel (analytics.setRationale(...) — voir la section Justification du README),
mais le SDK ne lit jamais la justification à partir des entrées de l'outil lui-même : comment la justification atteint le serveur
est une convention côté serveur que cette compétence implémente. Le modèle éprouvé est l'injection de schéma —
ajoutez un champ rationale optionnel au schéma d'entrée de chaque outil. Comme le paramètre est décrit
dans le schéma que les agents lisent déjà, ils le remplissent sans y être invités, sur tous les clients, avec zéro
modification côté client :
// Ajoutez au schéma d'entrée de chaque outil (exemple avec zod) :
rationale: z
.string()
.optional()
.describe(
'Brève explication de la raison pour laquelle vous appelez cet outil et ce que ' +
'vous attendez d\'apprendre du résultat.',
),
Puis lisez-la à l'intérieur du gestionnaire instrumenté et transmettez-la au SDK :
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
Rendre le champ optionnel signifie que rien ne casse lorsqu'un agent l'omet. Il est émis comme la propriété réservée
[MCP] Rationale (tronquée à 1 000 caractères ; la dernière écriture gagne). Cela vaut la peine d'être fait sur chaque outil,
pas seulement un échantillon.
Étape 4 — Baliser UTM les liens sortants (recommandé, uniquement si le serveur renvoie des URL)
Cette étape est entièrement en dehors du SDK — elle modifie la façon dont le serveur construit les URL et dépend de l'analyse côté web du produit. Elle n'est pas couverte dans le README du SDK.
Si une réponse d'outil inclut un lien (tableau de bord, documentation, page produit), balisez-le avant qu'il ne quitte le serveur afin que les clics soient attribuables au trafic MCP/agent au lieu d'apparaître comme directs :
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// Le client connecté (ex. "Claude", "Cursor"), si vous le connaissez :
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
Faites passer chaque chemin de construction d'URL dans les réponses d'outils par une fonction centrale comme celle-ci — un seul lien non balisé brise l'histoire d'attribution pour ce flux.
Prérequis (dites-le explicitement à l'utilisateur) : cela ne fonctionne que si leur analyse web capture les paramètres UTM sur les événements de visionnage de page (ou tout autre événement que leur site déclenche à l'arrivée). Le SDK Browser 2 d'Amplitude le fait par défaut — voir Suivi de l'attribution marketing (Les paramètres UTM, de référent et d'ID de clic sont capturés d'office). S'ils utilisent un suivi de visionnage de page personnalisé, ils doivent confirmer que les valeurs UTM arrivent également sur ces événements, sinon il n'y a rien à joindre aux clics balisés MCP.
Documentation Amplitude pertinente :
- Browser SDK 2 — Suivi de l'attribution marketing (capture UTM côté web, la moitié d'implémentation de cette étape)
- Sessions, canaux et attribution pour l'analyse marketing (comment le trafic balisé devient une analyse de canal)
- Capture automatique (visionnages de pages et plus)
Après l'instrumentation
Une fois que les événements circulent, dirigez un agent de codage vers la compétence analyze-mcp-server publiée d'Amplitude pour effectuer
un clustering d'intention et faire apparaître les modèles d'erreur d'appel d'outil par intention. (Si ce projet a la
compétence mcp-intent-error-analysis installée, c'est celle-ci — utilisez-la une fois que l'utilisateur a des données qui circulent et
souhaite les analyser, plutôt que de dupliquer cette analyse ici.)
Erreurs courantes à signaler
- Suivre des extraits d'API obsolètes au lieu du README actuel — récupérez-le à jour ; le SDK est en préversion et évolue rapidement.
- Installer une version figée/ancienne au lieu de la dernière version publiée.
- Appeler
instrumentServer()aprèsserver.connect()— doit être avant. - Envelopper certains gestionnaires d'outils mais pas d'autres — chaque outil a besoin de
instrumentTool. - Envoyer un
user_idqui ne correspond pas à celui utilisé sur le web/mobile — casse la possibilité de jonction, le but même de l'intégration. - Activer
emitAnonymousEvent: truesans que l'utilisateur comprenne que cela gonfle les comptes agrégés avec du trafic sans ancrage. - Oublier le prérequis UTM (capture côté web) et supposer que le simple balisage des liens est suffisant.