Configuración de Amplitude MCP Analytics
Instrumenta un servidor MCP para que cada llamada a herramienta se convierta en un evento de Amplitude, unible con el resto de los datos de Amplitude del producto (retención, ingresos, uso web/móvil).
La referencia autorizada del SDK es el README del paquete:
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics).
El SDK está en vista previa y evoluciona rápidamente — siempre obtén el README más reciente y síguelo para instalación, formas de la API, configuración y eventos predeterminados. No te bases en fragmentos memorizados ni en los resúmenes de este skill para los detalles de la API del SDK; el README prevalece en cualquier conflicto.
Hay cuatro pasos. Los pasos 1 y 2 son obligatorios y están documentados en el README — este skill te indica qué secciones seguir y qué invariantes verificar. Los pasos 3 y 4 son muy recomendados y están documentados completamente aquí, porque requieren cambios fuera del SDK (los esquemas de herramientas del servidor y la aplicación web del producto) que el README del SDK intencionalmente no cubre.
Hazlos en orden: Paso 1 (llamadas a herramientas) → Paso 2 (identidad) → Paso 3 (justificación) → Paso 4 (UTM, solo si el servidor devuelve enlaces). Acierta la identidad antes de dar nada por "terminado" — todo lo demás depende de ello.
Antes de empezar
Confirma:
- Este es un servidor MCP Node/TypeScript construido sobre
@modelcontextprotocol/sdk. Este SDK no admite otros lenguajes/entornos de ejecución. - El usuario tiene (o puede obtener) una clave de API de Amplitude para el proyecto donde quiere que lleguen los eventos.
- Qué gestor de paquetes usa el repositorio (pnpm/npm/yarn) — ajusta el comando de instalación en consecuencia.
Paso 1 — Instalar el SDK y rastrear llamadas a herramientas (obligatorio)
Obtén el README y sigue sus secciones Install y Quick start. Instala siempre la última versión publicada (ej. pnpm add @amplitude/mcp-analytics@latest) — nunca fijes una versión de memoria, ni reproduzcas comandos de instalación de este skill.
Invariantes a verificar una vez conectado (el README explica cada una):
analytics.instrumentServer(server, ...)se ejecuta antes deserver.connect()— el orden importa.- Cada manejador de herramienta está envuelto con
analytics.instrumentTool(...). Las herramientas sin envolver no se rastrean. El envoltorio tiene la misma forma que el manejador y es un paso directo sin operación si el servidor nunca fue vinculado, por lo que es seguro envolver de forma defensiva. - Todos los eventos predeterminados llevan el prefijo
[MCP], por lo que nunca chocan con los eventos de Amplitude existentes del producto. Consulta la tabla de Default events en el README (ydocs/events.mden el repositorio) para conocer el conjunto actual de eventos y propiedades.
Opcional: adjunta dimensiones personalizadas estables (nivel de plan, equipo, flags de funcionalidad) a través de extra en instrumentTool/instrumentServer — consulta la sección Custom event properties del README.
Paso 2 — Configurar la identidad correctamente (obligatorio, haz esto antes de dar el Paso 1 por "terminado")
Los eventos MCP deben llevar el mismo user_id que el producto ya envía a Amplitude desde web/móvil. Si omites esto, el uso de MCP aparece como una población desconectada que no se puede unir a los datos del producto — esto anula la mayor parte del valor de la integración.
Sigue la sección Identity del README para la API actual: ofrece vinculación a nivel de servidor, setIdentity() por solicitud dentro de un manejador, y un mapeo resolveIdentity opcional a partir de las afirmaciones authInfo de la solicitud. Elige el que se ajuste al modelo de autenticación del servidor.
Un comportamiento que debes comunicar al usuario: los eventos completamente anónimos, sin anclaje, se descartan por defecto (no se cuentan como usuarios) a menos que se opte explícitamente por emitAnonymousEvent: true para rastreo solo agregado — pregunta antes de activar esto, ya que cambia lo que se cuenta.
Paso 3 — Capturar la justificación (recomendado)
A diferencia de un humano que hace clic en un botón, un agente puede decirte por qué llamó a una herramienta. Capturar esto convierte los datos de "qué sucedió" a "qué intentaba hacer el usuario".
El lado del SDK es una llamada (analytics.setRationale(...) — consulta la sección Rationale del README), pero el SDK nunca lee la justificación directamente de las entradas de la herramienta: cómo llega la justificación al servidor es una convención del lado del servidor que este skill implementa. El patrón probado en batalla es la inyección de esquema: agrega un campo rationale opcional al esquema de entrada de cada herramienta. Como el parámetro se describe en el esquema que los agentes ya leen, lo completan sin que se les pida, en todos los clientes, sin cambios del lado del cliente:
// Agregar al esquema de entrada de cada herramienta (ejemplo con zod):
rationale: z
.string()
.optional()
.describe(
'Breve explicación de por qué estás llamando a esta herramienta y qué ' +
'esperas aprender del resultado.',
),
Luego léelo dentro del manejador instrumentado y pásalo al SDK:
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
Hacer el campo opcional significa que nada se rompe cuando un agente lo omite. Se emite como la propiedad reservada [MCP] Rationale (truncada a 1000 caracteres; la última escritura gana). Vale la pena hacerlo en todas las herramientas, no solo en una muestra.
Paso 4 — Etiquetar UTM en enlaces salientes (recomendado, solo si el servidor devuelve URLs)
Este paso está completamente fuera del SDK — cambia cómo el servidor construye URLs y depende del análisis del lado web del producto. No está cubierto en el README del SDK.
Si alguna respuesta de herramienta incluye un enlace (panel, documento, página de producto), etiquétalo antes de que salga del servidor para que los clics sean atribuibles al tráfico MCP/agente en lugar de aparecer como directos:
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// El cliente conectado (ej. "Claude", "Cursor"), si lo conoces:
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
Enruta cada ruta de construcción de URL en las respuestas de herramientas a través de una función central como esta — un solo enlace sin etiquetar rompe la historia de atribución para ese flujo.
Prerrequisito (dile esto al usuario explícitamente): esto solo funciona si su análisis web captura los parámetros UTM en los eventos de vista de página (o cualquier evento que su sitio dispare al aterrizar). El SDK 2 de Amplitude para navegador hace esto por defecto — consulta Track marketing attribution (los parámetros UTM, referente y click ID se capturan de fábrica). Si usan un rastreador de vista de página personalizado, deben confirmar que los valores UTM también lleguen a esos eventos, o no habrá con qué unir los clics etiquetados por MCP.
Documentación relevante de Amplitude:
- Browser SDK 2 — Track marketing attribution (captura de UTM del lado web, la mitad de implementación de este paso)
- Sessions, channels, and attribution for marketing analytics (cómo el tráfico etiquetado se convierte en análisis de canales)
- Autocapture (vistas de página y más)
Después de instrumentar
Una vez que los eventos fluyen, dirige un agente de codificación al skill analyze-mcp-server publicado de Amplitude para ejecutar agrupación de intenciones y detectar patrones de error de llamadas a herramientas por intención. (Si este proyecto tiene instalado el skill mcp-intent-error-analysis, ese es el indicado — úsalo una vez que el usuario tenga datos fluyendo y quiera analizarlos, en lugar de duplicar ese análisis aquí.)
Errores comunes a señalar
- Seguir fragmentos de API desactualizados en lugar del README actual — obténlo fresco; el SDK está en vista previa y se mueve rápido.
- Instalar una versión fijada/antigua en lugar de la última versión.
- Llamar a
instrumentServer()después deserver.connect()— debe ser antes. - Envolver algunos manejadores de herramientas pero no otros — cada herramienta necesita
instrumentTool. - Enviar un
user_idque no coincide con el usado en web/móvil — rompe la unibilidad, el punto central de la integración. - Activar
emitAnonymousEvent: truesin que el usuario entienda que infla los conteos agregados con tráfico sin anclaje. - Olvidar el prerrequisito de UTM (captura del lado web) y asumir que etiquetar enlaces por sí solo es suficiente.