Analizar Servidor MCP — Análisis de Intención y Errores
Genera un informe que responde a tres preguntas sobre un servidor MCP instrumentado con el SDK de Análisis MCP de Amplitude:
- ¿Qué herramientas se usan y cuáles fallan? (volumen por herramienta + tasa de errores)
- ¿Qué intentan hacer los llamadores con cada herramienta y dónde se rompe cada intención? (justificaciones dentro de una herramienta × mensaje de error)
- ¿Qué debería corregir el equipo primero? (correcciones basadas en evidencia de errores, no en corazonadas)
El movimiento central que hace valioso este análisis: la herramienta localiza la corrección; la justificación explica la intención detrás de ella. Una tasa de error general dice "El 4.5% de las llamadas fallan". Desglosada por herramienta dice "query_chart falla el 22% del tiempo" — ahora sabes qué abrir. Agregar las justificaciones dentro de esa herramienta dice "los fallos son agentes de actualización de paneles que alcanzan el límite de tamaño de lote" — ahora sabes por qué, y la corrección se escribe sola. La justificación está mayormente limitada al ámbito de la herramienta (cada herramienta tiene su propia razón para ser llamada), por lo que la herramienta es el eje principal y la justificación es el segundo corte dentro de ella — agrupar justificaciones globalmente simplemente re-deriva los límites de las herramientas mientras mezcla intenciones incomparables.
Requisitos previos
-
Conector MCP de Amplitude activo. Si no lo está, detente y pide al usuario que añada el conector Amplitude en la configuración de herramientas/conectores — no hay fuente de datos alternativa.
-
Un proyecto que contenga los eventos del SDK. El SDK emite eventos predeterminados propiedad del SDK, todos con prefijo
[MCP], y — crucialmente — cada propiedad predeterminada que llevan también tiene prefijo[MCP], pueden tener propiedades personalizadas.Eventos:
[MCP] Tool Call Response— el caballo de batalla: un evento por invocación de herramienta que alcanzó un callback de herramienta (éxito o error).[MCP] Tool Call Rejected— una llamadatools/callque falló antes de que se ejecutara cualquier herramienta (herramienta desconocida/inhabilitada, validación del esquema de entrada). Aquí es donde aterrizan los nombres de herramientas alucinados/con errores tipográficos, transportados en[MCP] Attempted Tool Name(mantenido fuera del reservado[MCP] Tool Name).[MCP] Session Initialized,[MCP] Session Ended,[MCP] Tools Listed.
Propiedades clave en
[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— separa una herramienta que reportó un fallo de una que falló),[MCP] Response Duration,[MCP] Response Size,[MCP] Request Size. -
Los nombres de eventos/propiedades pueden variar entre versiones del SDK. Nunca asumas — verifica con las herramientas de taxonomía en la Fase 0. Los nombres canónicos anteriores provienen de
constants.tsdel SDK (EVENT_PROPERTY_KEYS); si los datos del proyecto discrepan, confía en el proyecto y adáptate.
Fase 0 — Localizar y validar los datos
- Llama a la herramienta de contexto de Amplitude (sin projectId) para listar proyectos. Si hay más de un proyecto plausible y el usuario no ha especificado, pregunta.
- Confirma que los eventos
[MCP]existen en el proyecto elegido (busca eventos o lista eventos;get_eventsfiltra solo por nombre exacto, así que usa la búsqueda para el descubrimiento del prefijo[MCP]). - Obtén las propiedades de eventos para
[MCP] Tool Call Response(y[MCP] Tool Call Rejected) para confirmar los nombres exactos de las propiedades — recuerda que tienen prefijo[MCP]y están en Formato Título (ej.[MCP] Rationale, notool rationale). Vincula lo que encuentres a los nombres usados en las consultas siguientes. - Ejecuta una consulta de volumen/actualidad: totales de
[MCP] Tool Call Response,[MCP] Session Initializeden los últimos 60 días, con intervalo semanal. Esto te indica la ventana de fecha utilizable y si hay suficientes datos. Con menos de ~5k llamadas a herramientas en total, advierte al usuario que los desgloses por herramienta serán escasos y los porcentajes inestables — aún así continúa, pero indícalo en el informe.
Registra: ID del proyecto, ventana de fecha, volumen total de llamadas. Cada consulta posterior usa el mismo rango para que los números sigan siendo comparables.
Fase 1 — Desglose por herramienta (la columna vertebral)
Este es el mapa principal; todo lo demás profundiza en él.
- Volumen por herramienta: totales de
[MCP] Tool Call Response, agrupados por[MCP] Tool Name, groupByLimit ~100. - Errores por herramienta: lo mismo, más filtro
[MCP] Is Error is "true". - Llamadas rechazadas por nombre intentado: totales de
[MCP] Tool Call Rejectedagrupados por[MCP] Attempted Tool Name. Estas nunca llegan a un callback, por lo que son invisibles para las dos consultas anteriores — pero un nombre intentado de alto volumen que no es una herramienta real es uno de los hallazgos más accionables que existen (un cambio de nombre o alucinación que los agentes siguen adivinando).
Calcula por herramienta: volumen de llamadas, recuento de errores y tasa de errores, y clasifica las herramientas de dos maneras: por volumen de llamadas (lo que soporta la carga) y por volumen de errores (lo que cuesta más fallos). Selecciona las 3–5 herramientas principales para el análisis profundo — sesga hacia el alto volumen de errores, no solo hacia el alto tráfico, y respeta la elección del usuario si nombró herramientas específicas. Una herramienta de bajo tráfico con una tasa de error del 90% puede superar a una ocupada y saludable.
Fase 2 — Justificaciones dentro de cada herramienta principal (el "por qué")
Para cada herramienta principal, muestra sus justificaciones — totales de [MCP] Tool Call Response agrupados por
[MCP] Rationale, filtrados a esa única herramienta ([MCP] Tool Name is "<tool>"), groupByLimit
~150. Luego léelas y agrúpalas por lo que el llamador intenta lograr con esta herramienta,
no por la redacción. Orientación:
- Dentro de una sola herramienta normalmente encontrarás 2–5 grupos de intención, no nueve — la herramienta ya
reduce el propósito. Nómbralos por intención (ej. para una herramienta
query_chart: "actualización de panel en vivo", "exploración ad-hoc", "generación de informes programados"). - Pondera por volumen de llamadas (cada valor de justificación lleva su total), no por cadenas distintas.
- Cuidado con un grupo basura: "placeholder", "ignore", "noop", "test", "dummy", letras individuales. Su tamaño es un hallazgo de higiene de justificaciones, y la basura no debe contaminar las intenciones reales.
- Justificaciones como "Reintentar tras límite de tasa" / "Reintentando X" señalan bucles de reintento — anótalos.
- Las justificaciones en otros idiomas son normales; agrupa por significado.
- Calcula la cobertura de justificaciones por herramienta (proporción de las llamadas de la herramienta con una justificación no vacía). Si es baja (<50%), las intenciones describen solo una parte — indícalo, y "mejorar la cobertura de justificaciones en el momento de la instrumentación" se convierte en una recomendación en sí misma.
- Calcula la participación de la intención principal por herramienta (el grupo de intención más grande como % de las llamadas cubiertas por justificación de la herramienta). Esta es la señal de concentración: ~90% significa que la herramienta sirve para un trabajo y puedes optimizar intensamente para él (ajusta el esquema/descripción en torno a esa ruta); una distribución plana (intención principal ~30%) significa que la herramienta está sobrecargada y puede merecer una división, o sus errores se repartirán entre intenciones no relacionadas. Reporta el número y, cuando la intención principal sea dominante, nómbrala junto a la herramienta.
Flujos de trabajo entre herramientas (secundario): algunas justificaciones describen un objetivo de múltiples herramientas
("resolver el ID del gráfico antes de actualizar el panel"). Cuando una sola intención abarca claramente
distintas herramientas (ej. search_events → create_chart → create_dashboard), menciónalo como un flujo de trabajo
en la sección transversal — es lo único que una vista puramente herramienta por herramienta pasa por alto.
Fase 3 — Análisis detallado de errores por herramienta
Para cada herramienta principal, ejecuta (filtrado a esa herramienta + [MCP] Is Error is "true"):
- agrupado por
[MCP] Error Message→ por qué falla - opcionalmente dividido por
[MCP] Error Type(returned_errorvsthrown_exception) cuando un mensaje es ambiguo — un fallo y una negativa bien formada elevan ambos[MCP] Is Error, pero solo uno es un error en la herramienta.
Donde una herramienta tenga un grupo de intención dominante de la Fase 2, califica los errores por justificación
(añade el filtro de contains de justificación) para obtener la frase "esta intención se rompe de esta manera".
Clasifica cada mensaje de error significativo en un arquetipo — el arquetipo determina la corrección:
| Arquetipo | Firma | Patrón de corrección |
|---|---|---|
| Nombre de herramienta desactualizado/alucinado | [MCP] Tool Call Rejected con [MCP] Attempted Tool Name = un nombre renombrado o de sonido plausible | Alias del lado del servidor para herramientas renombradas; respuestas de rechazo que nombren la herramienta real más cercana para que los agentes se autocorrijan de una sola vez |
| Parámetro obligatorio faltante | error de validación, "Required", path nombra un parámetro | Afloja el esquema (acepta valor único o array, añade valores predeterminados), o haz que la descripción de la herramienta indique los requisitos para que los agentes lo hagan bien antes de la ejecución |
| Discrepancia de forma del esquema | "Expected object, received string" etc. | Añade coerción del lado del servidor, o un ejemplo en línea en la descripción de la herramienta |
| Colisión de límite duro | "Maximum of N …", "too_big" | Aumenta el límite, auto-fragmenta del lado del servidor, o indica el límite en la descripción del parámetro — los agentes actualmente solo aprenden los límites al fallar |
| Violación de rango/retención | "time range too large", "does not retain data before …" | Auto-coerción (ej. degradar granularidad) en lugar de dar error; anuncia los límites de retención/rango en el payload de contexto |
| Parámetro de huevo y gallina | una herramienta de contexto/descubrimiento requiere el mismo ID que existe para proporcionar | Haz que las herramientas de descubrimiento funcionen con cero argumentos obligatorios, usando valores predeterminados del token de autenticación |
| Permiso denegado | lenguaje de rol/permiso | Clase de error distinta para que "no permitido" sea separable de "roto"; a menudo también una brecha de documentación/incorporación |
| Error programado recurrente | el mismo mensaje repitiéndose a diario en la misma herramienta | Corrige el llamador del trabajo si es interno; para el producto, marca como automatización que degrada silenciosamente — nadie está mirando una ventana de chat |
| Transitorio/ascendente | 5xx, tiempos de espera, límites de tasa | Pistas de reintento después en el cuerpo del error; verifica si realmente ocurren los reintentos (ver el embudo de bucle) |
Los mejores mensajes de error indican la corrección ("vuelve a ejecutar con start >= …"). Mantén cada mensaje de error de alto volumen con ese estándar — "haz que este error sea tan accionable como tu mejor error" es a menudo una recomendación legítima.
Fase 4 — Métricas de contexto opcionales
Añade si el tiempo lo permite; agudizan la historia:
- Bucle de error repetido: embudo de 3 pasos, cada paso
[MCP] Tool Call Responsecon[MCP] Is Error is "true", manteniendo[MCP] Tool Nameconstante, ventana de conversión ~1h. Muestra qué proporción de usuarios con errores entran en bucles en la misma herramienta. (Los pasos no necesitan ser eventos consecutivos — di "3+ errores en la misma herramienta dentro de una hora", no "3 consecutivos"). - Error → recuperación: embudo de 2 pasos, error luego éxito, manteniendo el nombre de la herramienta constante. La alta recuperación + la alta tasa de bucle juntos significan que el costo son tokens/latencia desperdiciados, no abandono — una conclusión materialmente diferente.
- Combinación de clientes: únicos agrupados por
[MCP] Client Name. Una gran proporción "desconocido" o nombres de cliente casi duplicados (mayúsculas, variantes con prefijo de plugin) son hallazgos de instrumentación que vale la pena reportar.
Fase 5 — Verificar, luego escribir
Antes de escribir, vuelve a verificar al menos un número principal de una segunda manera (ej. tasa de error general mediante una consulta separada de totales de dos eventos). Recalcula cada porcentaje que cites a partir de totales brutos. Si un número no se puede verificar, elimínalo o etiquétalo como estimación.
Estructura del informe
Usa esta plantilla — organizada primero por herramienta:
# Análisis del Servidor MCP — <nombre del servidor/proyecto>
Datos: <proyecto>, <ventana de fecha>, <N> llamadas a herramientas, tasa de error general <X>%.
Nota metodológica: los desgloses por herramienta son resultados exactos de consultas; las intenciones dentro de la herramienta se derivan del modelo
a partir de las justificaciones (direccionales). Los nombres de llamadas rechazadas provienen de [MCP] Tool Call Rejected.
## Herramientas de un vistazo
<table: herramienta | llamadas | errores | tasa de error | intención principal (% participación) | cobertura de justificaciones>
<una línea sobre nombres de herramientas rechazadas/intentadas si es relevante; menciona justificaciones basura si es relevante>
## Análisis profundo: 3–5 herramientas principales (clasificadas por volumen de errores)
Para cada herramienta:
**Herramienta: <nombre> — <llamadas>, <tasa de error> — para qué sirve: <una oración>**
- Intenciones (justificaciones dentro de esta herramienta): <grupo: participación>, …
- 1–4 recomendaciones numeradas. Cada una indica la evidencia (mensaje de error + recuento),
el arquetipo y la corrección concreta. Lidera con la corrección que elimina el mayor volumen de errores.
## Hallazgos transversales
<flujos de trabajo entre herramientas, tasas de bucle/recuperación, higiene de nombres de cliente, higiene de justificaciones, tráfico de pruebas internas, …>
## La conclusión en una oración
<el cambio único que elimina el mayor volumen de fallos, con su número>
Estilo: números junto a cada afirmación; nombra los mensajes de error textualmente (truncados) para que los ingenieros puedan buscarlos con grep; recomendaciones redactadas como acciones ("Implementa alias para query_chart → query_charts"), no como observaciones ("la nomenclatura de herramientas podría mejorarse").
Gráficos en la salida
Representa los gráficos de Amplitude de apoyo donde el cliente lo soporte, utilizando las herramientas de consulta y renderizado de gráficos
ad-hoc (construye una definición de eventsSegmentation/funnels, luego renderízala).
Sé deliberado sobre qué puede y no puede ser un gráfico:
- Se puede graficar — cualquier cosa respaldada por consultas. Estos son resultados reales de segmentación/embudo
de Amplitude, así que represéntalos: llamadas y errores por herramienta (agrupados por
[MCP] Tool Name), tasa de error a lo largo del tiempo, llamadas rechazadas por[MCP] Attempted Tool Name, los embudos de error repetido y recuperación por herramienta, y combinación de clientes por[MCP] Client Name. El desglose por herramienta es el gráfico principal natural. - No se puede graficar — los grupos de intención dentro de la herramienta. La agrupación de justificaciones en intenciones ocurre en este modelo; esos grupos no existen como una propiedad de Amplitude, por lo que no hay gráfico guardado para "llamadas por intención". Presenta las intenciones como una tabla construida a partir de los totales de justificaciones, y di claramente que las cifras de intención se derivan del modelo (direccionales) mientras que los gráficos que representas son resultados exactos de consultas. No insinúes que un gráfico renderizado respalda la agrupación de intenciones.
Recetario de consultas
Todas las consultas son definiciones de eventsSegmentation o funnels contra el ID de proyecto de la
Fase 0. Ajusta los nombres de eventos/propiedades a lo que la Fase 0 verificó. Formas que se sabe que
funcionan:
Desglose de herramientas (Fase 1):
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Llamadas por Herramienta",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
"metric":"totals","countGroup":"User","groupBy":[],"intentions":[]}}
Errores por herramienta (Fase 1):
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Errores por Herramienta",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Tool Name"}],
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]}]}],
"metric":"totals","countGroup":"User","groupBy":[],"intentions":[]}}
Justificaciones por herramienta (Fase 2):
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Justificaciones para <tool>",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Rationale"}],
"filters":[{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]}],
"metric":"totals","countGroup":"User","groupBy":[],"intentions":[]}}
Mensajes de error por herramienta (Fase 3):
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Errores para <tool>",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Error Message"}],
"filters":[{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"],
{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]}]}],
"metric":"totals","countGroup":"User","groupBy":[],"intentions":[]}}
Bucles de error repetido (Fase 4):
{"type":"funnels","app":"<PROJECT_ID>","name":"[MCP] Bucles de Error Repetido en <tool>",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]},
{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]},
{"event_type":"[MCP] Tool Call Response",
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]},
{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]},
{"event_type":"[MCP] Tool Call Response",
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]},
{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]}],
"conversion_window":"1h","metric":"totals","countGroup":"User"}}
Recuperación tras error (Fase 4):
{"type":"funnels","app":"<PROJECT_ID>","name":"[MCP] Recuperación de Error en <tool>",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["true"]},
{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]},
{"event_type":"[MCP] Tool Call Response",
"filters":[{"type":"event","value":"[MCP] Is Error","comparator":"is","values":["false"]},
{"type":"event","value":"[MCP] Tool Name","comparator":"is","values":["<tool>"]}]}],
"conversion_window":"1h","metric":"totals","countGroup":"User"}}
Combinación de clientes (Fase 4):
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Clientes",
"params":{"range":"Últimos 30 Días",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Client Name"}]}],
"metric":"uniques","countGroup":"User","groupBy":[],"intentions":[]}}
Consideraciones de implementación
- Nunca ejecutes consultas de segmentación con grupos ilimitados — siempre establece un
groupByLimitmanejable. - Los nombres de eventos y propiedades tienen distinción entre mayúsculas y minúsculas. La Fase 0 existe para confirmar la capitalización real.
- Las propiedades con prefijo
[MCP]usan corchetes literales en el nombre. Las consultas pueden requerir codificación por URL dependiendo del cliente de la API. - Las justificaciones pueden estar vacías. Una justificación vacía no es una intención; excluye los vacíos del análisis de intenciones pero indícalos en la métrica de cobertura.
- Si el proyecto tiene muy pocos datos (<100 eventos), di "datos insuficientes" en lugar de presentar desgloses que inducirían a error.
- Cuando cites ejemplos de justificaciones en el informe, usa las 2–3 más frecuentes por grupo de intención para que los desarrolladores puedan verificar en sus registros.
- Si
[MCP] Rationaleno existe como propiedad, informa que la instrumentación de justificaciones necesita añadirse — sin justificaciones, el análisis de intención dentro de la herramienta es imposible. Pasa a las Fases 1 y 3 (desglose por herramienta + errores) que aún pueden entregar valor, pero marca el informe como parcial.