Serveur MCP de ClickStack

Connectez des assistants IA à ClickStack à l’aide du serveur MCP (Model Context Protocol)

ClickStack intègre un serveur Model Context Protocol (MCP) qui permet aux assistants IA d’interagir avec vos données d’observability. Une fois connecté, un assistant IA peut interroger les logs, les traces et les métriques ; gérer les tableaux de bord et les alertes ; explorer les sources de données ; et utiliser les recherches enregistrées — le tout en langage naturel.

Vous pouvez ainsi utiliser des outils comme Claude Code, Cursor ou tout client compatible MCP pour analyser des incidents, créer des tableaux de bord et gérer votre configuration d’observability sans quitter votre environnement de développement.

​

Disponibilité

Le serveur MCP est disponible pour les types de déploiement ClickStack suivants :

Déploiement	Statut
Open Source ClickStack	Disponible
BYOC (Bring Your Own Cloud)	Disponible
ClickStack on ClickHouse Cloud	Disponible
HyperDX v1 (hyperdx.io)	Non pris en charge

Configuration différente pour ClickHouse Cloud et OSS/BYOC

ClickStack on ClickHouse Cloud utilise un endpoint et une méthode d’authentification différents de ceux des déploiements Open Source et BYOC. Consultez la section ClickStack on ClickHouse Cloud ci-dessous pour la configuration spécifique à ClickHouse Cloud.

​

ClickStack on ClickHouse Cloud

ClickStack on ClickHouse Cloud se connecte via le MCP endpoint Cloud à https://mcp.clickhouse.cloud/clickstack et utilise OAuth 2.0 pour l’authentification. L’authentification par clé API n’est pas prise en charge pour ce endpoint.

​

Prérequis

• Un service ClickHouse Cloud en cours de fonctionnement avec ClickStack activé
• MCP activé sur le service — ouvrez la console Cloud, cliquez sur Connect, sélectionnez Connect with MCP, puis activez-le

​

Endpoint

https://mcp.clickhouse.cloud/clickstack

L’authentification utilise OAuth 2.0. Lorsque votre client MCP se connecte pour la première fois, une fenêtre de navigateur s’ouvre afin que vous puissiez vous connecter avec vos identifiants ClickHouse Cloud. Aucune clé API n’est nécessaire.

​

Connexion d’un client MCP

Chaque client gère automatiquement le flux OAuth lors de la première connexion.

Claude Code

claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack

Lancez Claude Code et exécutez /mcp, puis sélectionnez clickstack pour terminer le flux OAuth.

Cursor

Ajoutez ce qui suit à .cursor/mcp.json :

{
  "mcpServers": {
    "clickstack": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

VS Code

Ajoutez ce qui suit à .vscode/mcp.json :

{
  "servers": {
    "clickstack": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

OpenCode

Ajoutez ce qui suit à opencode.json :

{
  "mcp": {
    "clickstack": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

LibreChat

Ajoutez ce qui suit à librechat.yaml :

mcpServers:
  clickstack:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/clickstack

Autres

Tout client MCP compatible avec Streamable HTTP et OAuth peut se connecter. Configurez-le avec :

• URL : https://mcp.clickhouse.cloud/clickstack

​

Cibler un service spécifique

Sans l’en-tête x-service-id, les requêtes sont dirigées par défaut vers le premier service ClickStack provisionné et utilisé par votre compte. Pour cibler un autre service, ajoutez x-service-id: <YOUR_SERVICE_ID> comme en-tête dans la configuration de votre client MCP.

​

Open Source et BYOC

Les déploiements Open Source et BYOC utilisent l’endpoint MCP intégré de votre instance ClickStack avec une authentification par jeton Bearer.

​

Prérequis

• Une instance ClickStack active (voir Déploiement pour les options de déploiement)
• Une Personal API Access Key — trouvez la vôtre dans HyperDX, sous Team Settings → API Keys → Personal API Access Key

La Personal API Access Key est différente de la clé API d’ingestion disponible dans Team Settings, qui sert à authentifier les données de télémétrie envoyées au collecteur OpenTelemetry.

​

endpoint

Le serveur MCP est disponible sur le chemin /api/mcp de l’URL du frontend ClickStack. Par exemple, avec un déploiement local par défaut, l’URL est http://localhost:8080/api/mcp. Remplacez localhost:8080 par l’hôte et le port de votre instance si vous avez modifié les valeurs par défaut.

Les exemples de cette page utilisent l’URL de l’application frontend (port 8080 par défaut). Vous pouvez aussi accéder directement au serveur MCP via le backend à l’adresse <BACKEND_URL>/mcp, mais tous les déploiements n’exposent pas le backend ; cette documentation utilise donc le chemin du frontend.

Le serveur MCP utilise le transport Streamable HTTP avec une authentification par Bearer token.

​

Connexion d’un client MCP

Remplacez <YOUR_CLICKSTACK_URL> par l’URL de votre instance (par exemple, http://localhost:8080) et <YOUR_API_KEY> par votre Personal API Access Key.

Claude Code

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Cursor

Ajoutez les éléments suivants à .cursor/mcp.json :

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

VS Code

Ajoutez les éléments suivants à .vscode/mcp.json :

{
  "servers": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

OpenCode

Ajoutez les éléments suivants à opencode.json :

{
  "mcp": {
    "hyperdx": {
      "type": "remote",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

LibreChat

Ajoutez les éléments suivants à librechat.yaml :

mcpServers:
  clickstack:
    type: streamable-http
    url: <YOUR_CLICKSTACK_URL>/api/mcp
    headers:
      Authorization: "Bearer <YOUR_API_KEY>"

Autre

Tout client MCP prenant en charge Streamable HTTP peut se connecter. Configurez-le comme suit :

• URL : <YOUR_CLICKSTACK_URL>/api/mcp
• En-tête : Authorization: Bearer <YOUR_API_KEY>

​

Que pouvez-vous faire avec MCP ?

Une fois connecté, votre assistant IA a accès à un ensemble d’outils couvrant les principaux domaines de ClickStack. Il s’agit notamment de :

• Interrogation des données — Recherchez et agrégerez les logs, les traces et les métriques à l’aide du query builder de ClickStack, de la syntaxe de recherche ou de SQL brut.
• Sources de données — Répertoriez les sources de données disponibles, les connexions aux bases de données, les schémas de colonnes et les clés d’attribut.
• Tableaux de bord — Créez, mettez à jour, supprimez et inspectez les tableaux de bord ainsi que leurs tuiles.
• Alertes — Créez, mettez à jour et inspectez les alertes, ainsi que leur historique d’évaluation.
• Recherches enregistrées — Créez, mettez à jour et inspectez des définitions de recherches enregistrées réutilisables.
• Webhooks — Répertoriez les destinations webhook disponibles pour les notifications d’alerte.
• Équipes — Répertoriez les équipes auxquelles appartient l’utilisateur actuel et identifiez l’équipe active.

L’ensemble des outils disponibles peut évoluer au fil du temps. Votre client MCP découvrira automatiquement les outils disponibles lors de la connexion.

​

Utilisation par plusieurs équipes (OSS/BYOC)

Cela s’applique uniquement aux déploiements Open Source et BYOC. Pour ClickStack on ClickHouse Cloud, voir Cibler un service spécifique.

Par défaut, les requêtes MCP s’exécutent dans le contexte de votre équipe principale. Si vous appartenez à plusieurs équipes, ajoutez l’en-tête x-hdx-team avec l’ID de l’équipe, en plus de votre en-tête Authorization. Si cet en-tête est omis, votre équipe principale est utilisée. Si vous spécifiez une équipe à laquelle vous n’appartenez pas, la requête est rejetée avec une erreur 401.

Utilisez l’outil de liste des équipes de votre MCP client pour voir à quelles équipes vous avez accès et laquelle est active.

​

Dépannage

​

ClickStack on ClickHouse Cloud

Le flux OAuth n’aboutit pas

• Vérifiez que votre client MCP prend en charge OAuth 2.0. Les clients qui ne prennent en charge que le Bearer token ou le transport stdio ne peuvent pas s’authentifier auprès de l’endpoint Cloud.
• Vérifiez que votre navigateur ne bloque pas la fenêtre contextuelle ou la redirection OAuth.
• Vérifiez que votre compte ClickHouse Cloud a accès à l’organisation et au service.

MCP est activé, mais le client ne parvient pas à se connecter

• Vérifiez que vous utilisez l’endpoint ClickStack (https://mcp.clickhouse.cloud/clickstack), et non l’endpoint MCP Cloud général (https://mcp.clickhouse.cloud/mcp).
• Vérifiez que MCP est activé sur le service dans la console Cloud.

Les requêtes sont envoyées au mauvais service

Sans l’en-tête x-service-id, les requêtes sont envoyées par défaut au premier service ClickStack provisionné et utilisé par votre compte. Ajoutez cet en-tête pour cibler un service spécifique. Voir Cibler un service spécifique.

​

Open Source et BYOC

J’obtiens une erreur d’authentification 403

• Vérifiez que vous utilisez la Personal API Access Key (et non la clé API d’ingestion).
• Vérifiez que la clé est bien incluse sous forme de jeton Bearer dans l’en-tête Authorization.
• Vérifiez que votre instance ClickStack est en cours d’exécution et accessible à l’URL que vous avez configurée.

Je fais face à une limitation de débit

Le serveur MCP impose une limite de 600 requêtes par minute par utilisateur. Si vous dépassez cette limite, les requêtes sont temporairement rejetées. Réduisez la fréquence des requêtes ou attendez avant de réessayer.

J’obtiens une erreur 401 avec l’en-tête x-hdx-team

Vérifiez que l’ID d’équipe est correct et que votre compte utilisateur appartient bien à cette équipe.

Je ne parviens pas à me connecter au serveur MCP

• Assurez-vous que votre client MCP prend en charge le transport Streamable HTTP. Les anciens clients qui ne prennent en charge que le transport stdio ne fonctionneront pas.
• Si vous exécutez ClickStack localement, vérifiez que l’application est accessible à l’URL configurée (par défaut, http://localhost:8080).
• Pour les déploiements BYOC derrière un load balancer ou un proxy inverse, assurez-vous que le chemin /api/mcp n’est ni bloqué ni réécrit.