Integración MCP

El Model Context Protocol (MCP) permite que los asistentes de IA consulten tu analítica de Zenovay directamente. Haz preguntas como "¿Cuántos visitantes tuve esta semana?" o "¿Cuáles son mis páginas más visitadas?" y obtén datos en vivo desde tu panel — sin salir de tu IDE o chat.

Inicio rápido

Conectarse lleva menos de un minuto. Simplemente añade la URL del servidor a tu cliente MCP — OAuth se encarga del resto.

1. Añadir el servidor MCP

Añade la URL del servidor de Zenovay a tu cliente de IA. No se requiere clave de API ni configuración manual.

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"servers": {
  "zenovay-analytics": {
    "type": "http",
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "serverUrl": "https://api.zenovay.com/mcp"
  }
}
}

También puedes añadirlo a través del CLI de Claude Code:

claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

2. Autorizar el acceso

Cuando te conectes por primera vez, tu cliente MCP abrirá una ventana del navegador mostrando la página de autorización de Zenovay. Aquí puedes:

• Seleccionar tu equipo (si perteneces a varios equipos)
• Establecer permisos para cada categoría de herramientas (Ninguno / Lectura / Escritura)
• Hacer clic en Autorizar para conceder el acceso

Esta es una configuración única. Tu cliente MCP almacena el token OAuth y lo renueva automáticamente.

3. Empezar a consultar

Una vez autorizado, puedes hacer preguntas a tu asistente de IA como:

• "Lista mis sitios web"
• "¿Cuántos visitantes tuvo zenovay.com esta semana?"
• "¿Cuáles son las 10 páginas con más tráfico?"
• "Compara la tasa de rebote de esta semana con la de la semana pasada"
• "Muéstrame cualquier anomalía en mi tráfico"
• "Exporta los últimos 30 días de analítica como CSV"
• "Crea un nuevo objetivo para mi página de registro"
• "Muéstrame todos mis objetivos y sus tasas de conversión"
• "Añade una exclusión de IP para la red de nuestra oficina"

Cómo funciona la autorización OAuth

Cuando tu cliente MCP se conecta a https://api.zenovay.com/mcp, ocurre lo siguiente de forma automática:

1. Descubrimiento — El cliente obtiene los metadatos OAuth de /.well-known/oauth-authorization-server
2. Registro — El cliente se registra a sí mismo (una sola vez) mediante el registro dinámico de cliente
3. Autorización — Se abre una ventana del navegador mostrando la página de consentimiento de Zenovay
4. Intercambio de token — Después de que autorizas, el cliente intercambia el código por un token de acceso
5. Conectado — Todas las solicitudes MCP usan el token OAuth. Se renueva automáticamente cuando caduca.

Puedes ver y revocar las aplicaciones conectadas en Ajustes > Uso en tu panel de Zenovay.

Detalles de conexión

Permisos

Durante la autorización, eliges el nivel de acceso para cada categoría de herramientas:

Categorías de herramientas

Límites de tasa

Los límites diarios de consultas son por equipo (compartidos entre todas las aplicaciones conectadas):

La mayoría de las herramientas cuestan 1 consulta. La herramienta de lenguaje natural query_analytics cuesta 3 consultas debido a su procesamiento con IA.

El uso se restablece diariamente a las 00:00 UTC. Consulta tu cuota restante en cualquier momento con la herramienta get_api_usage, o en Ajustes > Uso en tu panel.

Aplicación de planes

Algunas herramientas MCP están restringidas a planes de pago. Herramientas como get_session_replays, get_heatmap_data, get_revenue y get_retention_data requieren una suscripción Pro o superior, mientras que export_data requiere Scale o superior. Las consultas de analítica se ajustan automáticamente a la ventana de retención de datos de tu plan (por ejemplo, 1 año para Free, 2 años para Pro).

{
"jsonrpc": "2.0",
"id": 1,
"error": {
  "code": -32002,
  "message": "This feature requires a paid plan. Upgrade at https://app.zenovay.com/plans"
}
}

Gestión de aplicaciones conectadas

Puedes ver y revocar los tokens OAuth de los clientes MCP conectados:

1. Ve a Ajustes > Uso en tu panel de Zenovay
2. Desplázate hasta la sección Solicitudes MCP
3. Consulta el uso diario, los límites de tasa y el número de aplicaciones conectadas
4. Para revocar el acceso, ve a Claves de API y gestiona los tokens desde allí

Revocar un token desconecta inmediatamente al cliente MCP. El cliente tendrá que volver a autorizarse para reconectarse.

Manejo de errores

Cuando algo va mal, el servidor devuelve un error JSON-RPC:

Solución de problemas

"Needs authentication" en Claude Code

Esto significa que el flujo OAuth aún no se ha completado. Ejecuta claude mcp list para comprobar el estado y luego inicia una nueva sesión — te pedirá que autorices en el navegador.

El navegador no se abre para la autorización

Asegúrate de que tu cliente MCP admita OAuth 2.1. Si usas un cliente antiguo, comprueba si hay actualizaciones. La URL del servidor por sí sola (https://api.zenovay.com/mcp) debería activar el descubrimiento OAuth automático.

"Invalid or expired OAuth token"

Tu token ha caducado y la renovación automática ha fallado. Elimina el servidor y vuelve a añadirlo:

claude mcp remove zenovay-analytics
claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

Errores de límite de tasa

Comprueba tu uso actual con get_api_usage o en Ajustes > Uso. La herramienta query_analytics cuesta 3 consultas — usa herramientas específicas como get_visitors (1 consulta) cuando sea posible.

Prompt para asistentes de IA

Si tu asistente de IA no detecta automáticamente el servidor MCP, puedes pegar este prompt para ayudarle a conectarse:

Connect to the Zenovay Analytics MCP server at https://api.zenovay.com/mcp

Authentication: OAuth 2.1 (automatic). When you first connect, a browser window will open for me to authorize access. No API key is needed.

Setup:
- Server URL: https://api.zenovay.com/mcp
- Transport: HTTP (Streamable HTTP, JSON-RPC 2.0)
- OAuth discovery: https://api.zenovay.com/.well-known/oauth-authorization-server

After connecting, call list_websites first to get my website IDs — every analytics tool requires a website_id parameter.

Available tool categories:
- Analytics (8 tools): visitors, pages, traffic sources, geographic data, real-time
- Advanced (13 tools): funnels, goals, sessions, heatmaps, errors, revenue, uptime
- AI Insights (4 tools): AI-generated insights, anomalies, weekly digest, recommendations
- Management (29 tools): website settings, goals, funnels, tracking, reports
- Settings (16 tools): IP exclusions, notifications, team members, domains
- Webhooks (6 tools): webhook CRUD, deliveries, automation rules

Rate limits: Free 25/day, Pro 100/day, Scale 500/day, Enterprise 10,000/day. The query_analytics tool costs 3 queries; all others cost 1.

Próximos pasos

• Referencia de herramientas — Documentación completa de todas las herramientas con parámetros y ejemplos
• Permisos y límites — Modos de acceso, límites de tasa y códigos de error