Documentación del MCP Analyzer

Servidor Model Context Protocol basado en HTTP para la supervisión de la latencia de red y el análisis inteligente. El servidor MCP funciona conectándose a la API de Latencetech ya existente para comunicarse con la propia base de datos del Analyzer.

Funcionalidades

Supervisión principal

Consultar la latencia en todos los protocolos de latencia (TCP, UDP, HTTP, HTTPS, ICMP, TWAMP)
Análisis de la salud de la conectividad con KPI completos
Supervisión de la calidad de la señal de radio (RSSI, RSRP, RSRQ, SINR)
Previsión predictiva de la latencia con intervalos de confianza
Datos de rendimiento correlacionados con la geolocalización
Supervisión de las métricas del sistema (CPU, RAM, almacenamiento, carga)
Mediciones de caudal y de calidad Lifbe
Series temporales de pérdida de paquetes (subida, bajada, global)
Instantáneas de caudal iPerf TCP/UDP

Análisis inteligente

Detección de anomalías: Detecta las anomalías de red en todos los protocolos
Tendencias de rendimiento: Analiza las tendencias de rendimiento de los agentes con respecto a las referencias históricas
Alertas de degradación: Identifica los agentes que muestran una degradación del rendimiento
Análisis de correlación: Detecta patrones entre agentes que indican problemas a escala de la red
Eventos de picos de protocolo: Detecta los picos de latencia sincronizados multiprotocolo en un solo agente
Informes de salud: Genera informes completos sobre la salud de la red con recomendaciones
Clasificaciones de los agentes: Clasifica los agentes por métricas de rendimiento y tendencias

Configuración

Requisitos previos

El servidor MCP requiere que el puerto 12098 esté abierto en la máquina.

Variables de entorno

Defina los valores directamente en docker-compose.yml:

environment:
  # OBLIGATORIO: Sustitúyala por su clave API
  - API_KEY=your-api-key-here

  # OBLIGATORIO: Sustitúyala por una clave segura que se utilizará para crear tokens
  - ADMIN_KEY=change-this-secure-admin-key

  # SERVER_HOST: Déjelo vacío para la detección automática de la IP externa, 
  # O defina la IP de su VM (p. ej.: 192.168.1.100)
  # O defina su DNS (p. ej.: demo.example.com)
  - SERVER_HOST=

  # ENABLE_HTTPS: Establecer en 'false' ÚNICAMENTE cuando se utilice una dirección DNS
  # Manténgalo en true si utiliza una dirección IP (por defecto)
  - ENABLE_HTTPS=true

  # ENABLE_OAUTH: Establecer en 'false' para desactivar los endpoints OAuth (Claude Web no funcionará)
  # Mantenga 'true' para la compatibilidad con Claude Web (por defecto: true)
  # Establecer en 'false' para admitir únicamente tokens bearer
  # Si está activado, cualquier persona con la dirección del MCP puede conectarse a él sin verificación
  - ENABLE_OAUTH=false

  # Opcional
  - LOG_LEVEL=INFO
  - API_TIMEOUT=120
  - HTTP_PORT=12098
  - DEFAULT_CUSTOMER_ID=0
  - DEFAULT_AGENT_ID=1

Notas de configuración importantes:

API_KEY: Obligatoria para el acceso a la API backend
ADMIN_KEY: Obligatoria para crear/gestionar los tokens de acceso
Configuración HTTPS:
Para Claude Desktop con IP: Establecer ENABLE_HTTPS=true para los certificados autofirmados
Para Claude Web: Debe utilizar un dominio con SSL válido (consulte Configuración SSL más abajo)
ENABLE_OAUTH:
ENABLE_OAUTH=true → Los 5 endpoints OAuth registrados; Claude Web puede conectarse
ENABLE_OAUTH=false → Endpoints OAuth no registrados; solo funcionan los tokens bearer
Los endpoints de gestión de tokens (/admin/tokens/*) siempre funcionan, independientemente del parámetro OAuth

Los registros mostrarán:

INFO: OAuth endpoints enabled
# o bien
INFO: OAuth endpoints disabled - bearer token only mode

Configuración SSL para Claude Web

Claude Web requiere un certificado SSL de confianza y no puede utilizar certificados autofirmados.

Subdominio con Nginx + Let's Encrypt

Añadir un registro DNS A para un subdominio (p. ej.: mcp.yourdomain.com → IP de su servidor)
Crear la configuración de nginx (/etc/nginx/sites-available/mcp.yourdomain.com):

server {
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass          http://localhost:12098;
        proxy_set_header    Host $http_host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto $scheme;
        proxy_read_timeout  90;

        # Compatibilidad con conexiones largas
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 80;
}

Activar el sitio y obtener el certificado SSL:

sudo ln -s /etc/nginx/sites-available/mcp.yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d mcp.yourdomain.com

Actualizar mcp-server.yml:

- ENABLE_HTTPS=false

Reiniciar el contenedor:

docker compose down
docker compose up -d

Integración con clientes MCP

Claude Web (claude.ai)

Requisitos: - Certificado SSL válido (los certificados autofirmados NO funcionarán) - Debe utilizar un subdominio con Let's Encrypt o una CA de confianza similar - OAuth debe estar activado (ENABLE_OAUTH=true)

Claude Web utiliza automáticamente la autenticación OAuth 2.1:

Vaya a Configuración de Claude → Conectores
Haga clic en "Añadir conector personalizado"
Nombre: Latency Monitoring
URL del servidor MCP remoto: https://mcp.yourdomain.com (debe utilizar SSL de confianza)
Deje vacíos los campos OAuth (el servidor gestiona el registro dinámico)
Haga clic en "Añadir"; Claude iniciará automáticamente el flujo OAuth
Apruebe la autorización (aprobada automáticamente por el servidor, sin verificación real)
Conexión establecida con un token de acceso generado

Cómo funciona: - Claude descubre los endpoints OAuth mediante .well-known/oauth-authorization-server - El servidor aprueba automáticamente la autorización y genera un token de acceso - Token gestionado automáticamente por Claude (no es necesaria la gestión manual del token) - El token caduca a los 30 días y puede renovarse

Claude Desktop

Claude Desktop puede utilizar certificados autofirmados con una solución alternativa.

Claude Desktop requiere el proxy mcp-remote con token bearer:

1) Crear un token de acceso:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=claude-desktop" \
  -H "X-Admin-Key: your-admin-key-here"

Respuesta:

{
  "token": "TOKEN-CREATED",
  "name": "claude-desktop"
}

2) Configurar Claude Desktop:

Para certificados autofirmados (dirección IP):

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Para SSL de confianza (subdominio con Let's Encrypt):

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.yourdomain.com",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED"
      }
    }
  }
}

Nota de seguridad: NODE_TLS_REJECT_UNAUTHORIZED=0 desactiva la validación del certificado SSL y solo debería utilizarse en desarrollo o en entornos de red de confianza. Para producción, utilice un subdominio con Let's Encrypt.

3) Reinicie Claude Desktop

Cursor

Cursor admite servidores MCP remotos mediante token bearer.

1) Crear un token de acceso:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=cursor" \
  -H "X-Admin-Key: your-admin-key-here"

2) Configurar Cursor en .cursor/mcp.json (nivel de proyecto) o ~/.cursor/mcp.json (global):

Para SSL de confianza (subdominio con Let's Encrypt):

{
  "mcpServers": {
    "latency-mcp": {
      "url": "https://mcp.yourdomain.com",
      "headers": {
        "Authorization": "Bearer TOKEN-CREATED"
      }
    }
  }
}

Para certificados autofirmados (dirección IP):

Utilice el proxy mcp-remote:

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

3) Recargue Cursor y compruebe que el servidor aparece en Configuración de Cursor > MCP

Google Antigravity

Google Antigravity admite servidores MCP remotos mediante token bearer.

1) Crear un token de acceso:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=antigravity" \
  -H "X-Admin-Key: your-admin-key-here"

2) Configurar Antigravity en ~/.gemini/config/mcp_config.json (global) o .agents/mcp_config.json (workspace). También puede abrir este archivo desde Agent panel > ... > MCP Servers > Manage MCP Servers > View raw config.

Importante: Antigravity utiliza serverUrl (y no url) para los servidores MCP remotos basados en HTTP.

Para SSL de confianza (subdominio con Let's Encrypt):

{
  "mcpServers": {
    "latency-mcp": {
      "serverUrl": "https://mcp.yourdomain.com",
      "headers": {
        "Authorization": "Bearer TOKEN-CREATED"
      }
    }
  }
}

Para certificados autofirmados (dirección IP):

Utilice el proxy mcp-remote:

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

3) Reinicie Antigravity o actualice los servidores MCP desde Settings > Customizations > Installed MCP Servers

Otros clientes MCP

Para cualquier cliente MCP compatible con tokens bearer:

Cree un token (consulte la sección de gestión de tokens más abajo)
Configure el cliente para que envíe la cabecera Authorization: Bearer <token>
Conéctese a la URL de su servidor

Gestión de tokens

Crear tokens

Crear nuevos tokens de acceso para los clientes:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client" \
  -H "X-Admin-Key: your-admin-key-here"

Respuesta:

{
  "token": "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH",
  "name": "my-client"
}

Modificar la fecha de caducidad predeterminada

Por defecto, los tokens caducan a las 720 horas (1 mes), pero puede modificarlo utilizando el parámetro expires_hours:

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client&expires_hours=3600" \
  -H "X-Admin-Key: your-admin-key-here"

Listar los tokens

Mostrar todos los tokens activos:

curl -k -X GET "https://localhost:12098/admin/tokens/list" \
  -H "X-Admin-Key: your-admin-key-here"

Respuesta:

{
  "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH": {
    "name": "my-client",
    "expires_at": "2025-11-02T10:30:00"
  }
}

Revocar tokens

Revocar un token específico:

curl -k -X DELETE "https://localhost:12098/admin/tokens/xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH" \
  -H "X-Admin-Key: your-admin-key-here"

Detalles de los tokens: - Los tokens caducan por defecto a los 30 días (720 horas) - Los tokens caducados se eliminan automáticamente durante la validación - Los tokens se almacenan en /app/data/tokens.json (persistente mediante un volumen Docker) - Cada token está vinculado a un nombre descriptivo para facilitar su gestión

Notas de seguridad

Cambie ADMIN_KEY respecto al valor predeterminado
Mantenga segura su API_KEY
La carpeta data/ contiene los tokens de autenticación: ¡haga una copia de seguridad!
Defina los permisos de archivo adecuados:

chmod 700 data/
chmod 600 data/tokens.json

No utilice nunca NODE_TLS_REJECT_UNAUTHORIZED=0 en entornos de producción
Para los despliegues de producción con Claude Web, utilice siempre certificados SSL de confianza

Herramientas disponibles

Herramientas de supervisión principales

Herramienta	Descripción	Parámetros obligatorios
`list_customer_networks`	Listar todas las redes de clientes disponibles	Ninguno
`search_agents`	Buscar agentes de un cliente	`customer_id` (por defecto 0)
`query_latency`	Consultar la latencia con filtros de tiempo/protocolo	`customer_id`, `agent_id`, `protocol` + (`time_range` O `chosen_time`)
`get_connectivity_health`	Análisis completo de la conectividad	`customer_id`, `agent_id` (ambos por defecto 0,1)
`analyze_radio_conditions`	Análisis de la calidad de la señal de radio	`customer_id`, `agent_id` + (`time_range` O `chosen_time`)
`get_system_metrics`	Métricas de rendimiento del sistema	Ninguno
`get_forecast`	Análisis predictivo de la latencia	`customer_id`, `agent_id` (ambos por defecto 0,1)
`get_geolocation_data`	Rendimiento correlacionado con la ubicación	`customer_id`, `agent_id`, `time_range`
`get_lifbe_data`	Métricas de caudal Lifbe	`customer_id`, `agent_id` (ambos por defecto 0,1)
`get_twamp_data`	Mediciones del protocolo TWAMP	`customer_id`, `agent_id` (ambos por defecto 0,1)
`query_packet_loss`	Series temporales de pérdida de paquetes	`customer_id`, `agent_id` + (`time_range` O `chosen_time`)
`get_iperf_throughput`	Última instantánea de caudal iPerf	`customer_id`, `agent_id` (ambos por defecto 0,1)

Herramientas de análisis inteligente

Herramienta	Descripción	Parámetros obligatorios
`get_anomalies`	Detectar las anomalías de red en todos los protocolos	`customer_id`, `agent_id` (por defecto 0,1)
`analyze_performance_trends`	Comparar el rendimiento actual con el de referencia	`customer_id`, `agent_id` (por defecto 0,1)
`get_degradation_alerts`	Identificar los agentes en degradación	`customer_id` (por defecto 0)
`detect_correlation_patterns`	Encontrar problemas de rendimiento correlacionados	`customer_id` (por defecto 0)
`detect_protocol_spike_events`	Encontrar las ventanas de picos de latencia multiprotocolo en un agente	`customer_id`, `agent_id` + opcionales `time_range`, `protocols`, `min_protocols`, `spike_ratio`
`generate_health_report`	Análisis completo de la salud de la red	`customer_id` (por defecto 0)
`rank_agents_by_performance`	Clasificar los agentes por métricas de rendimiento	`customer_id` (por defecto 0)

Prompts disponibles

Los prompts son flujos de trabajo guiados (skills) que indican al modelo cómo combinar las herramientas para resolver problemas específicos. Los clientes compatibles con los prompts MCP pueden invocarlos directamente.

Prompt	Descripción
`radio-signal-troubleshooting`	Diagnostica los problemas de calidad de la señal celular interpretando las métricas RSSI, RSRP, RSRQ y SINR. Úselo al investigar problemas de conectividad o de mala calidad de la señal.
`multi-site-correlation`	Analiza el rendimiento de varios agentes para distinguir los problemas específicos de un sitio de una degradación a escala de la red. Úselo al comparar agentes o al investigar problemas correlacionados.
`customer-health-reports`	Genera informes profesionales sobre la salud de la red con resúmenes ejecutivos y recomendaciones aplicables. Úselo al crear informes diarios, semanales o mensuales para las partes interesadas.
`latency-protocol-comparison`	Compara en paralelo las latencias TCP, UDP, HTTP, HTTPS, ICMP y TWAMP para determinar si un problema de rendimiento es específico de un protocolo o afecta a toda la red.
`predictive-capacity-planning`	Combina los datos de previsión, las tendencias y las clasificaciones de los agentes para identificar los agentes que se acercan a sus límites de rendimiento antes de que se conviertan en incidentes.
`incident-investigation`	Playbook paso a paso para incidentes activos: determina el radio de impacto, precisa la cronología e identifica la capa de la causa raíz (ISP vs radio vs equipo local).
`geolocation-latency-analysis`	Correlación de la latencia con la ubicación física para identificar clústeres geográficos, el impacto de la distancia a la torre y si agentes cercanos comparten una causa raíz.
`throughput-quality-assessment`	Determina si la lentitud se debe a una saturación del ancho de banda o a problemas de calidad de la conexión (pérdida de paquetes, jitter) mediante los datos de Lifbe e iPerf.

Endpoints de la API

El servidor MCP expone estos endpoints HTTP:

GET / - Información sobre el servidor
GET /health - Comprobación de salud
POST /mcp/initialize - Inicialización MCP
POST /mcp/resources/list - Listar los recursos
POST /mcp/resources/read - Leer el contenido del recurso
POST /mcp/tools/list - Listar las herramientas disponibles
POST /mcp/tools/call - Ejecutar una herramienta

Resolución de problemas

Problemas de certificado SSL

Claude Web: - Error: "certificado autofirmado" o fallos de conexión - Solución: Claude Web requiere certificados SSL de confianza. Los certificados autofirmados NO funcionarán. Debe configurar un subdominio con Let's Encrypt (consulte la sección Configuración SSL anterior)

Claude Desktop: - Error: Errores de "certificado autofirmado" - Solución: Añada NODE_TLS_REJECT_UNAUTHORIZED: "0" a la sección env de su configuración de Claude Desktop (consulte la configuración de Claude Desktop anterior) - Nota: Esto es solo para desarrollo/pruebas. Para producción, utilice certificados SSL de confianza

Problemas de conexión

Compruebe si la clave API es correcta
Compruebe si la API de LatenceTech es accesible
Para Docker: utilice host.docker.internal en lugar de localhost, o utilice network_mode: "host" en mcp-server.yml
Compruebe la configuración del cortafuegos para el puerto 12098
Para Claude Web: Asegúrese de que el DNS del subdominio está configurado correctamente y apunta a su servidor
Para las configuraciones de nginx: Compruebe que nginx funciona y está configurado correctamente (sudo nginx -t)

Registro

Defina LOG_LEVEL=DEBUG para un registro detallado de las solicitudes/respuestas
Consulte los registros del contenedor: docker logs <container_id>
Consulte los registros de nginx: sudo tail -f /var/log/nginx/error.log

Ejemplos de consultas y pruebas

"Dame un resumen de la latencia del agente 1."
"Muéstrame todas las anomalías de red detectadas para el agente 1 durante la última hora. Céntrate en el protocolo TCP si hay problemas."
"¿Qué agentes tienen advertencias de salud de la conectividad?"
"Genera una previsión de la latencia esperada del agente 2"
"¿Puedes analizar las tendencias de rendimiento del agente 1 del cliente 0 durante los últimos 7 días? Quiero ver si ha habido una degradación con respecto a la referencia."
"Genera un informe diario completo sobre la salud de la red para el cliente 0. Incluye recomendaciones aplicables para todos los problemas que encuentres."