Intégration MCP

Le Model Context Protocol (MCP) permet aux assistants IA d'interroger directement votre analytique Zenovay. Posez des questions comme « Combien de visiteurs ai-je eus cette semaine ? » ou « Quelles sont mes pages les plus consultées ? » et obtenez des données en direct depuis votre tableau de bord — sans quitter votre IDE ou votre chat.

Démarrage rapide

La connexion prend moins d'une minute. Ajoutez simplement l'URL du serveur à votre client MCP — OAuth se charge du reste.

1. Ajouter le serveur MCP

Ajoutez l'URL du serveur Zenovay à votre client IA. Aucune clé API ni configuration manuelle requise.

{
"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"
  }
}
}

Vous pouvez également l'ajouter via la CLI Claude Code :

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

2. Autoriser l'accès

Lors de votre première connexion, votre client MCP ouvrira une fenêtre de navigateur affichant la page d'autorisation Zenovay. Vous pouvez y :

• Sélectionner votre équipe (si vous appartenez à plusieurs équipes)
• Définir les permissions pour chaque catégorie d'outils (Aucune / Lecture / Écriture)
• Cliquer sur Autoriser pour accorder l'accès

C'est une configuration unique. Votre client MCP stocke le jeton OAuth et le renouvelle automatiquement.

3. Commencer à interroger

Une fois autorisé, vous pouvez poser à votre assistant IA des questions telles que :

• « Liste mes sites web »
• « Combien de visiteurs zenovay.com a-t-il eu cette semaine ? »
• « Quelles sont les 10 pages les plus visitées ? »
• « Compare le taux de rebond de cette semaine à celui de la semaine dernière »
• « Montre-moi les anomalies dans mon trafic »
• « Exporte les 30 derniers jours d'analytique au format CSV »
• « Crée un nouvel objectif pour ma page d'inscription »
• « Montre-moi tous mes objectifs et leurs taux de conversion »
• « Ajoute une exclusion d'IP pour notre réseau de bureau »

Fonctionnement de l'autorisation OAuth

Lorsque votre client MCP se connecte à https://api.zenovay.com/mcp, voici ce qui se produit automatiquement :

1. Découverte — Le client récupère les métadonnées OAuth depuis /.well-known/oauth-authorization-server
2. Enregistrement — Le client s'enregistre (une seule fois) via Dynamic Client Registration
3. Autorisation — Une fenêtre de navigateur s'ouvre affichant la page de consentement Zenovay
4. Échange de jeton — Après votre autorisation, le client échange le code contre un jeton d'accès
5. Connecté — Toutes les requêtes MCP utilisent le jeton OAuth. Il se renouvelle automatiquement à son expiration.

Vous pouvez consulter et révoquer les applications connectées dans Paramètres > Utilisation de votre tableau de bord Zenovay.

Détails de connexion

Permissions

Lors de l'autorisation, vous choisissez le niveau d'accès pour chaque catégorie d'outils :

Catégories d'outils

Limites de débit

Les limites de requêtes quotidiennes sont par équipe (partagées entre toutes les applications connectées) :

La plupart des outils coûtent 1 requête. L'outil de langage naturel query_analytics coûte 3 requêtes en raison de son traitement par IA.

L'utilisation se réinitialise quotidiennement à 00h00 UTC. Vérifiez votre quota restant à tout moment avec l'outil get_api_usage, ou dans Paramètres > Utilisation de votre tableau de bord.

Application des plans

Certains outils MCP sont réservés aux plans payants. Des outils comme get_session_replays, get_heatmap_data, get_revenue et get_retention_data nécessitent un abonnement Pro ou supérieur, tandis que export_data nécessite Scale ou supérieur. Les requêtes analytiques sont automatiquement limitées à la fenêtre de rétention des données de votre plan (par exemple, 1 an pour Free, 2 ans pour Pro).

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

Gestion des applications connectées

Vous pouvez consulter et révoquer les jetons OAuth des clients MCP connectés :

1. Allez dans Paramètres > Utilisation de votre Tableau de bord Zenovay
2. Faites défiler jusqu'à la section Requêtes MCP
3. Consultez l'utilisation quotidienne, les limites de débit et le nombre d'applications connectées
4. Pour révoquer l'accès, allez dans Clés API et gérez les jetons à partir de là

La révocation d'un jeton déconnecte immédiatement le client MCP. Le client devra se réautoriser pour se reconnecter.

Gestion des erreurs

En cas de problème, le serveur renvoie une erreur JSON-RPC :

Dépannage

« Needs authentication » dans Claude Code

Cela signifie que le flux OAuth n'est pas encore terminé. Exécutez claude mcp list pour vérifier l'état, puis démarrez une nouvelle session — elle vous invitera à autoriser dans le navigateur.

Le navigateur ne s'ouvre pas pour l'autorisation

Assurez-vous que votre client MCP prend en charge OAuth 2.1. Si vous utilisez un client plus ancien, vérifiez les mises à jour. L'URL du serveur seule (https://api.zenovay.com/mcp) devrait déclencher la découverte OAuth automatique.

« Invalid or expired OAuth token »

Votre jeton a expiré et le renouvellement automatique a échoué. Supprimez le serveur et rajoutez-le :

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

Erreurs de limite de débit

Vérifiez votre utilisation actuelle avec get_api_usage ou dans Paramètres > Utilisation. L'outil query_analytics coûte 3 requêtes — utilisez des outils spécifiques comme get_visitors (1 requête) quand c'est possible.

Prompt pour les assistants IA

Si votre assistant IA ne détecte pas automatiquement le serveur MCP, vous pouvez coller ce prompt pour l'aider à se connecter :

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.

Étapes suivantes

• Référence des outils — Documentation complète de tous les outils avec paramètres et exemples
• Permissions et limites — Modes d'accès, limites de débit et codes d'erreur