Amplitude/builder-skills

Amplitude MCP Analytics Einrichtung

Instrumentiert einen MCP-Server, sodass jeder Tool-Aufruf zu einem Amplitude-Ereignis wird, das mit den übrigen Amplitude-Daten des Produkts (Retention, Revenue, Web-/Mobilnutzung) verknüpfbar ist.

Die maßgebliche SDK-Referenz ist die Paket-README: https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics). Die SDK befindet sich in der Vorschauphase und entwickelt sich schnell weiter – rufe immer die aktuelle README ab und folge ihr für Installation, API-Strukturen, Konfiguration und Standardereignisse. Verlasse dich nicht auf auswendig gelernte Code-Schnipsel oder Zusammenfassungen aus diesem Skill für SDK-API-Details; bei Konflikten hat die README Vorrang.

Es gibt vier Schritte. Schritte 1–2 sind erforderlich und in der README dokumentiert – dieses Skill sagt dir, welchen Abschnitten du folgen und welche Invarianten du überprüfen sollst. Schritte 3–4 werden dringend empfohlen und sind hier vollständig dokumentiert, da sie Änderungen außerhalb der SDK erfordern (die Tool-Schemata des Servers und die Web-App des Produkts), die die SDK-README bewusst nicht abdeckt.

Führe sie in der richtigen Reihenfolge aus: Schritt 1 (Tool-Aufrufe) → Schritt 2 (Identität) → Schritt 3 (Begründung) → Schritt 4 (UTM, nur falls der Server Links zurückgibt). Stelle die Identität korrekt ein, bevor du etwas als „erledigt” bezeichnest – alles Weitere hängt davon ab.

Bevor du beginnst

Stelle sicher:

1. Es handelt sich um einen Node/TypeScript MCP-Server, der auf @modelcontextprotocol/sdk basiert. Dieses SDK unterstützt keine anderen Sprachen/Laufzeitumgebungen.
2. Der Benutzer hat (oder kann erhalten) einen Amplitude-API-Key für das Projekt, in dem die Ereignisse landen sollen.
3. Welchen Paketmanager das Repository verwendet (pnpm/npm/yarn) – passe den Installationsbefehl entsprechend an.

Schritt 1 – SDK installieren und Tool-Aufrufe tracken (erforderlich)

Rufe die README ab und folge den Abschnitten Install und Quick start. Installiere immer die neueste veröffentlichte Version (z.B. pnpm add @amplitude/mcp-analytics@latest) – verwende niemals eine festgeschriebene Version aus dem Gedächtnis und übernimm keine Installationsbefehle aus diesem Skill.

Zu überprüfende Invarianten nach der Einrichtung (die README erklärt jede im Detail):

• analytics.instrumentServer(server, ...) wird vor server.connect() ausgeführt – die Reihenfolge ist wichtig.
• Jeder Tool-Handler wird mit analytics.instrumentTool(...) umwickelt. Nicht umwickelte Tools werden nicht getrackt. Der Wrapper hat die identische Struktur wie der Handler und ist eine No-Op-Durchleitung, wenn der Server nie gebunden wurde, daher ist es sicher, ihn defensiv anzuwenden.
• Standardereignisse tragen alle das Präfix [MCP] , sodass sie nie mit den bestehenden Amplitude-Ereignissen des Produkts kollidieren. Siehe die Tabelle Default events in der README (und docs/events.md im Repository) für den aktuellen Ereignissatz und die aktuellen Eigenschaften.

Optional: Füge stabile, benutzerdefinierte Dimensionen (Tarifstufe, Team, Feature-Flags) über extra in instrumentTool/instrumentServer hinzu – siehe Abschnitt Custom event properties in der README.

Schritt 2 – Identität korrekt einstellen (erforderlich, mache dies, bevor du Schritt 1 als „erledigt” bezeichnest)

MCP-Ereignisse müssen die gleiche user_id tragen, die das Produkt bereits von Web/Mobil an Amplitude sendet. Wird dies übersprungen, erscheint die MCP-Nutzung als eine getrennte Population, die nicht mit Produktdaten verknüpft werden kann – dies macht den Großteil des Nutzens der Integration zunichte.

Folge dem Abschnitt Identity in der README für die aktuelle API: Sie bietet eine Bindung auf Serverebene, ein setIdentity() pro Anfrage innerhalb eines Handlers und eine optionale resolveIdentity-Zuordnung von den authInfo-Claims der Anfrage. Wähle, was zum Authentifizierungsmodell des Servers passt.

Ein Verhalten, das dem Benutzer mitgeteilt werden sollte: Vollständig anonyme, ankerlose Ereignisse werden standardmäßig verworfen (nicht als Benutzer gezählt), es sei denn, sie werden explizit über emitAnonymousEvent: true für ein reines Aggregat-Tracking aktiviert – frage, bevor du dies einschaltest, da es verändert, was gezählt wird.

Schritt 3 – Begründung erfassen (empfohlen)

Im Gegensatz zu einem Menschen, der auf einen Button klickt, kann ein Agent dir sagen, warum er ein Tool aufgerufen hat. Die Erfassung dieser Information verwandelt die Daten von „Was ist passiert?” in „Was der Benutzer zu tun versuchte.”

Die SDK-Seite ist ein einziger Aufruf (analytics.setRationale(...) – siehe Abschnitt Rationale in der README), aber die SDK liest die Begründung nicht selbst aus den Tool-Eingaben: Wie die Begründung zum Server gelangt, ist eine serverseitige Konvention, die dieses Skill implementiert. Das bewährte Muster ist die Schema-Injektion – füge ein optionales rationale-Feld zum Eingabeschema jedes Tools hinzu. Da der Parameter im Schema beschrieben ist, das Agenten bereits lesen, füllen sie ihn unaufgefordert aus, über alle Clients hinweg, ohne clientseitige Änderungen:

// Zu jedem Tool-Eingabeschema hinzufügen (zod-Beispiel):
rationale: z
  .string()
  .optional()
  .describe(
    'Kurze Erklärung, warum du dieses Tool aufrufst und was ' +
    'du aus dem Ergebnis zu lernen erwartest.',
  ),

Lese es dann innerhalb des instrumentierten Handlers aus und übergib es an die SDK:

analytics.instrumentTool(async (args, extra) => {
  if (typeof args.rationale === 'string') {
    analytics.setRationale(args.rationale);
  }
  return doWork(args);
}, { name: 'search' });

Das optionale Feld stellt sicher, dass nichts kaputtgeht, wenn ein Agent es weglässt. Es wird als reservierte Eigenschaft [MCP] Rationale ausgegeben (auf 1.000 Zeichen gekürzt; der letzte Schreibvorgang gewinnt). Es lohnt sich, dies bei jedem Tool zu tun, nicht nur bei einer Stichprobe.

Schritt 4 – UTM-Tagging für ausgehende Links (empfohlen, nur wenn der Server URLs zurückgibt)

Dieser Schritt liegt vollständig außerhalb der SDK – er ändert, wie der Server URLs erstellt, und hängt von der produktseitigen Web-Analyse ab. Er wird nicht in der SDK-README behandelt.

Wenn eine Tool-Antwort einen Link enthält (Dashboard, Dokumentation, Produktseite), versehe ihn mit Tags, bevor er den Server verlässt, sodass Klicks dem MCP-/Agenten-Traffic zugeordnet werden können, anstatt als direkte Zugriffe zu erscheinen:

function addUtmParams(url: string, clientName?: string): string {
  const u = new URL(url);
  u.searchParams.append('utm_source', 'mcp');
  u.searchParams.append('utm_medium', 'referral');
  // Der verbundene Client (z.B. "Claude", "Cursor"), falls bekannt:
  u.searchParams.append('utm_content', clientName ?? 'unknown');
  return u.toString();
}

Leite jeden URL-Erstellungspfad in Tool-Antworten durch eine zentrale Funktion wie diese – ein einzelner ungetaggter Link unterbricht die Zuordnungsgeschichte für diesen Flow.

Voraussetzung (teile dies dem Benutzer explizit mit): Dies funktioniert nur, wenn ihre Web-Analyse UTM-Parameter bei Page-View-Ereignissen (oder einem anderen Ereignis, das ihre Seite beim Laden auslöst) erfasst. Das Amplitude Browser SDK 2 tut dies standardmäßig – siehe Marketing-Attribution tracken (UTM-, Referrer- und Click-ID-Parameter werden von Haus aus erfasst). Wenn sie einen benutzerdefinierten Page-View-Tracker verwenden, müssen sie bestätigen, dass UTM-Werte auch bei diesen Ereignissen landen, da es sonst nichts gibt, wogegen die MCP-getaggten Klicks gejoint werden können.

Relevante Amplitude-Dokumentation:

• Browser SDK 2 – Marketing-Attribution tracken (Webseitige UTM-Erfassung, die Implementierungshälfte dieses Schritts)
• Sitzungen, Kanäle und Attribution für Marketing-Analysen (wie der getaggte Traffic zur Kanalanalyse wird)
• Autocapture (Page Views und mehr)

Nach der Instrumentierung

Sobald Ereignisse fließen, weise einen Coding-Agenten auf das veröffentlichte Skill analyze-mcp-server von Amplitude an, um Intent-Clustering durchzuführen und Tool-Aufruf-Fehlermuster nach Absicht zu ermitteln. (Falls dieses Projekt das installierte mcp-intent-error-analysis-Skill hat, verwende dieses – nutze es, sobald der Benutzer Daten fließen hat und analysieren möchte, anstatt diese Analyse hier zu duplizieren.)

Häufige Fehler, auf die hingewiesen werden sollte

• Verwendung veralteter API-Schnipsel anstelle der aktuellen README – rufe sie frisch ab; die SDK befindet sich in der Vorschauphase und entwickelt sich schnell weiter.
• Installation einer festgeschriebenen/älteren Version anstelle der neuesten Version.
• Aufruf von instrumentServer() nach server.connect() – muss davor erfolgen.
• Umwickeln einiger Tool-Handler, aber nicht aller – jedes Tool benötigt instrumentTool.
• Senden einer user_id, die nicht mit der auf Web/Mobil verwendeten übereinstimmt – unterbricht die Verknüpfbarkeit, den eigentlichen Sinn der Integration.
• Aktivieren von emitAnonymousEvent: true, ohne dass der Benutzer versteht, dass dies die aggregierten Zählungen durch ankerlosen Traffic aufbläht.
• Vergessen der UTM-Voraussetzung (Webseitige Erfassung) und Annahme, dass das Taggen von Links allein ausreicht.