IBM Instana MCP Server

officiel

Le serveur IBM Instana MCP permet une interaction fluide avec la plateforme d'observabilité IBM Instana, vous donnant accès aux données d'observabilité en temps réel directement dans votre flux de développement.

GitHub

Essayer ce MCPSponsorisé

Que pouvez-vous faire avec IBM Instana MCP ?

Interroger les performances des applications — Demandez des métriques d'application, des alertes ou des détails de catalogue à l'aide des outils de catégorie app comme get_app_metrics ou get_app_alerts.
Surveiller la santé de l'infrastructure — Récupérez les ressources, la topologie et les métriques d'infrastructure via les outils infra tels que get_infra_metrics ou get_infra_topology.
Suivre les événements et incidents — Accédez aux événements Kubernetes ou aux données de surveillance des agents avec les outils events comme get_k8s_events ou get_agent_status.
Analyser la surveillance de sites web — Récupérez les métriques de site web, les informations de catalogue ou la configuration à l'aide des outils website comme get_website_metrics ou get_website_config.
Filtrer les outils par catégorie — Activez uniquement les catégories d'outils nécessaires au démarrage avec l'option --tools (par exemple, --tools infra,events) pour optimiser les performances.

Documentation

Table des matières

Serveur MCP pour IBM Instana

Serveur MCP pour IBM Instana

📚 Liens rapides

Outils et exemples - Documentation complète des outils avec exemples concrets
Politique de confidentialité - Informations sur le traitement des données et la confidentialité
Guide de déploiement Docker - Déploiement Docker complet, constructions multi-architectures et configuration de production

Le serveur MCP Instana permet une interaction fluide avec la plateforme d'observabilité Instana, vous donnant accès aux données d'observabilité en temps réel directement dans votre flux de travail de développement.

Il sert de pont entre les clients (tels que les agents IA ou les outils personnalisés) et les API REST Instana, convertissant les requêtes utilisateur en appels API Instana et formatant les réponses dans des formats structurés et facilement exploitables.

Le serveur prend en charge les deux modes de transport HTTP Streamable et Stdio pour une compatibilité maximale avec les différents clients MCP. Pour plus de détails, consultez la spécification des modes de transport MCP.

Vue d'ensemble de l'architecture

graph LR
    subgraph "Application Host Process"
        MH[MCP Host]
        MSI[Instana MCP Server]
        MST[ProductA MCP Server]
        MSC[ProductB MCP Server]

        MH <--> MSI
        MH <--> MSC
        MH <--> MST
    end

    subgraph "Remote Service"
        II[Instana Instance]
        TI[ProductA Instance]
        CI[ProductB Instance]

        MSI <--> II
        MST <--> TI
        MSC <--> CI
    end

    subgraph "LLM"
        L[LLM]
        MH <--> L
    end

Flux de travail

Prenons un exemple simple : vous utilisez un hôte MCP (tel que Claude Desktop, VS Code ou un autre client) connecté au serveur MCP Instana. Lorsque vous demandez des informations sur les alertes Instana, le processus suivant se déroule :

Le client MCP récupère la liste des outils disponibles auprès du serveur MCP Instana
Votre requête est envoyée au LLM avec les descriptions des outils
Le LLM analyse les outils disponibles et sélectionne celui ou ceux appropriés pour récupérer les alertes Instana
Le client exécute les outils sélectionnés via le serveur MCP Instana
Les résultats (alertes les plus récentes) sont renvoyés au LLM
Le LLM formule une réponse en langage naturel
La réponse vous est affichée

sequenceDiagram
    participant User
    participant ChatBot as MCP Host
    participant MCPClient as MCP Client
    participant MCPServer as Instana MCP Server
    participant LLM
    participant Instana as Instana Instance

    ChatBot->>MCPClient: Load available tools from MCP Server
    MCPClient->>MCPServer: Request available tool list
    MCPServer->>MCPClient: Return list of available tools
    User->>ChatBot: Ask "Show me the latest alerts from Instana for application robot-shop"
    ChatBot->>MCPClient: Forward query
    MCPClient->>LLM: Send query and tool description
    LLM->>MCPClient: Select appropriate tool(s) for Instana alert query
    MCPClient->>MCPServer: Execute selected tool(s)
    MCPServer->>Instana: Retrieve alerts for application robot-shop
    MCPServer->>MCPClient: Send alerts of Instana result
    MCPClient->>LLM: Forward alerts of Instana
    LLM->>ChatBot: Generate natural language response for Instana alerts
    ChatBot->>User: Show Instana alert response

Prérequis

Option 1 : Installation depuis PyPI (recommandé)

La façon la plus simple d'utiliser mcp-instana est de l'installer directement depuis PyPI :

pip install mcp-instana

Après l'installation, vous pouvez exécuter le serveur à l'aide de la commande mcp-instana directement.

Option 2 : Installation de développement

Pour le développement ou une personnalisation locale, vous pouvez cloner et configurer le projet localement.

Installation de uv

Ce projet utilise uv, un installateur et résolveur de paquets Python rapide. Pour installer uv, vous avez plusieurs options :

Avec pip :

pip install uv

Avec Homebrew (macOS) :

brew install uv

Pour plus d'options d'installation et d'instructions détaillées, consultez la documentation uv.

Configuration de l'environnement

Après avoir installé uv, configurez l'environnement du projet en exécutant :

uv sync

Authentification par en-têtes pour le mode HTTP Streamable

Lorsque vous utilisez le mode HTTP Streamable, vous devez transmettre les identifiants Instana via les en-têtes HTTP. Cette approche améliore la sécurité et la flexibilité en :

Évitant le stockage des identifiants dans les variables d'environnement
Permettant l'utilisation de différents identifiants pour différentes requêtes
Prenant en charge les environnements partagés où la modification des variables d'environnement est restreinte
Prenant en charge l'authentification par jeton API et par session

Modes d'authentification pris en charge :

1. Authentification par jeton API (appels API directs)

En-têtes requis :

instana-base-url : L'URL de votre instance Instana
instana-api-token : Votre jeton API Instana

Exemple :

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-api-token: your-api-token"

2. Authentification par jeton de session (appels initiés par l'interface)

En-têtes requis :

instana-base-url : L'URL de votre instance Instana
instana-auth-token : Jeton d'authentification de session du backend de l'interface
instana-csrf-token : Jeton CSRF du backend de l'interface
instana-cookie-name : (Facultatif) Nom du cookie pour l'authentification de session (par défaut : instanaAuthToken)

Exemple :

--header "instana-base-url: https://your-instance.instana.io"
--header "instana-auth-token: your-session-token"
--header "instana-csrf-token: your-csrf-token"
--header "instana-cookie-name: in-token"

3. Authentification par jeton JWT (intégration plateforme IBM)

En-têtes requis :

instana-base-url : L'URL de votre instance Instana
instana-jwt-token : Jeton JWT de la plateforme IBM
instana-csrf-token : Jeton CSRF pour la validation des requêtes

Exemple de configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp",
        "--allow-http",
        "--header",
        "instana-base-url: https://your-instana-instance.instana.io",
        "--header",
        "instana-jwt-token: your_jwt_token_here",
        "--header",
        "instana-csrf-token: your_csrf_token_here"
      ]
    }
  }
}

Priorité d'authentification :

Jeton JWT (si fourni avec le jeton CSRF) - Prioritaire pour l'intégration plateforme IBM
Jetons de session (si auth_token et csrf_token sont tous deux fournis)
Jeton API (si fourni) - Authentification standard
Variable d'environnement (INSTANA_API_TOKEN) - Repli

Flux d'authentification :

Les en-têtes HTTP doivent être présents dans chaque requête
Le serveur valide les identifiants selon l'ordre de priorité
Les requêtes sans authentification valide échoueront

Cette conception garantit une transmission sécurisée des identifiants et prend en charge plusieurs flux d'authentification, y compris les appels initiés par l'interface via WebSocket → Coordinateur → Serveur MCP.

Assurez-vous que le jeton utilisé dispose des autorisations nécessaires pour invoquer les outils MCP. Consultez ici pour plus d'informations.

Démarrage du serveur MCP local

Avant de configurer un client MCP (Claude Desktop, GitHub Copilot ou des clients MCP personnalisés), vous devez démarrer le serveur MCP local. Le serveur prend en charge deux modes de transport : HTTP Streamable et Stdio.

Options de commande du serveur

Utilisation de la CLI (installation PyPI)

Si vous avez installé mcp-instana depuis PyPI, utilisez la commande mcp-instana :

mcp-instana [OPTIONS]

Utilisation de l'installation de développement

Pour le développement local, utilisez la commande uv run :

uv run src/core/server.py [OPTIONS]

Options disponibles :

--transport <mode> : Mode de transport (choix : streamable-http, stdio)
--env KEY=VALUE : Définir une variable d'environnement (peut être répété pour plusieurs variables, par ex. --env INSTANA_BASE_URL=https://... --env INSTANA_API_TOKEN=...)
--debug : Activer le mode débogage avec journalisation supplémentaire
--log-level <level> : Définir le niveau de journalisation (choix : DEBUG, INFO, WARNING, ERROR, CRITICAL)
--tools <categories> : Liste séparée par des virgules des catégories d'outils à activer (par ex. infra,app,events,website). L'activation d'une catégorie active également ses invites associées. Par exemple : --tools infra active les outils infra et toutes les invites liées à infra.
--list-tools : Lister toutes les catégories d'outils disponibles et quitter
--port <port> : Port du serveur MCP (par défaut : 8080, peut être remplacé par la variable d'environnement PORT)
--verify-ssl : Activer la vérification du certificat SSL pour les appels API Instana sortants. Équivalent à la définition de INSTANA_SSL_VERIFY=true. La vérification SSL est désactivée par défaut.
--help : Afficher le message d'aide et quitter

Démarrage en mode HTTP Streamable

Le mode HTTP Streamable fournit une interface API REST et est recommandé pour la plupart des cas d'utilisation.

Utilisation de la CLI (installation PyPI)

# Start with all tools enabled (default)
mcp-instana --transport streamable-http

# Start with debug logging
mcp-instana --transport streamable-http --debug

# Start with a specific log level
mcp-instana --transport streamable-http --log-level WARNING

# Start with specific tool categories only
mcp-instana --transport streamable-http --tools infra,events

# Combine options (specific log level, custom tools)
mcp-instana --transport streamable-http --log-level DEBUG --tools app,events

Utilisation de l'installation de développement

# Start with all tools enabled (default)
uv run src/core/server.py --transport streamable-http

# Start with debug logging
uv run src/core/server.py --transport streamable-http --debug

# Start with a specific log level
uv run src/core/server.py --transport streamable-http --log-level WARNING

# Start with specific tool and prompts categories only
uv run src/core/server.py --transport streamable-http --tools infra,events

# Start with custom port
uv run src/core/server.py --transport streamable-http --port 9000

# Combine options (specific log level, custom tools and prompts)
uv run src/core/server.py --transport streamable-http --log-level DEBUG --tools app,events

Caractéristiques clés du mode HTTP Streamable :

Utilise les en-têtes HTTP pour l'authentification (aucune variable d'environnement requise)
Prend en charge différents identifiants par requête
Mieux adapté aux environnements partagés
Port par défaut du serveur MCP : 8080
Point de terminaison MCP : http://0.0.0.0:8080/mcp/

Démarrage en mode Stdio

Le mode Stdio utilise l'entrée/sortie standard pour la communication et nécessite des variables d'environnement pour l'authentification.

Utilisation de la CLI (installation PyPI)

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
mcp-instana

# Or explicitly specify stdio mode
mcp-instana --transport stdio

# Option 2: Use --env flag to set environment variables directly
mcp-instana --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
mcp-instana --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Utilisation de l'installation de développement

# Option 1: Set environment variables first
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"

# Start the server (stdio is the default if no transport specified)
uv run src/core/server.py

# Or explicitly specify stdio mode
uv run src/core/server.py --transport stdio

# Option 2: Use --env flag to set environment variables directly
uv run src/core/server.py --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

# Or with explicit stdio mode
uv run src/core/server.py --transport stdio --env INSTANA_BASE_URL=https://your-instana-instance.instana.io --env INSTANA_API_TOKEN=your_instana_api_token

Caractéristiques clés du mode Stdio :

Utilise les variables d'environnement pour l'authentification (peuvent être définies via export ou le drapeau --env)
Communication directe via stdin/stdout
Requis pour certaines configurations de clients MCP
Le drapeau --env offre un moyen pratique de définir les identifiants sans modifier l'environnement du shell

Catégories d'outils

Vous pouvez optimiser les performances du serveur en activant uniquement les catégories d'outils et d'invites dont vous avez besoin :

Utilisation de la CLI (installation PyPI)

# List all available categories
mcp-instana --list-tools

# Enable specific categories
mcp-instana --transport streamable-http --tools infra,app
mcp-instana --transport streamable-http --tools events

Utilisation de l'installation de développement

# List all available categories
uv run src/core/server.py --list-tools

# Enable specific categories
uv run src/core/server.py --transport streamable-http --tools infra,app
uv run src/core/server.py --transport streamable-http --tools events

Catégories disponibles :

infra : Outils et invites de surveillance d'infrastructure (ressources, catalogue, topologie, analyse, métriques)
app : Outils et invites de performance applicative (ressources, métriques, alertes, catalogue, topologie, analyse, paramètres, alertes globales)
events : Outils et invites de surveillance d'événements (événements Kubernetes, surveillance des agents)
website : Outils et invites de surveillance de sites Web (métriques, catalogue, analyse, configuration)

Vérification du certificat SSL

La vérification du certificat SSL pour les appels API Instana sortants est désactivée par défaut. Cela s'applique aux deux modes de transport HTTP Streamable et Stdio.

Pour activer la vérification du certificat SSL, utilisez l'option CLI --verify-ssl ou la variable d'environnement INSTANA_SSL_VERIFY.

Utilisation de l'option CLI

uv run src/core/server.py --verify-ssl

L'option --verify-ssl équivaut à définir :

export INSTANA_SSL_VERIFY=true

Utilisation de la variable d'environnement

export INSTANA_SSL_VERIFY=true
uv run src/core/server.py

La vérification SSL est désactivée lorsque INSTANA_SSL_VERIFY est défini sur 0, false ou no (insensible à la casse), ou laissé non défini. Toute autre valeur active la vérification — utilisez true, 1 ou yes comme choix conventionnels.

Utilisation d'un bundle CA personnalisé

Lorsque la vérification SSL est activée, le bundle CA système est utilisé par défaut. Pour utiliser un bundle de certificats CA personnalisé, définissez INSTANA_CA_BUNDLE :

export INSTANA_SSL_VERIFY=true
export INSTANA_CA_BUNDLE=/path/to/ca-bundle.crt
uv run src/core/server.py

INSTANA_CA_BUNDLE n'est utilisé que lorsque la vérification des certificats SSL est activée.

Le serveur journalise l'état effectif de la vérification SSL au démarrage, afin que vous puissiez immédiatement confirmer si votre variable d'environnement ou votre option CLI a bien été prise en compte.

Vérification de l'état du serveur

Une fois démarré, vous pouvez vérifier que le serveur fonctionne :

Pour le mode Streamable HTTP :

# Check MCP server
curl http://0.0.0.0:8080/mcp/

# Or with custom port
curl http://0.0.0.0:9000/mcp/

Pour le mode Stdio : Le serveur démarrera et attendra l'entrée standard (stdin) des clients MCP.

Problèmes de démarrage courants

Problèmes SSL / Certificats : Consultez la section Vérification des certificats SSL ci-dessus pour les options de configuration. Si vous rencontrez des erreurs SSL avec la vérification activée et que vous utilisez macOS, assurez-vous que votre environnement Python a accès aux certificats système :

# macOS - Install certificates for Python
/Applications/Python\ 3.13/Install\ Certificates.command

Port déjà utilisé : Si le port 8080 est déjà utilisé, spécifiez un autre port :

uv run src/core/server.py --transport streamable-http --port 9000

Dépendances manquantes : Assurez-vous que toutes les dépendances sont installées :

uv sync

Configuration et utilisation

Bob IDE

Bob est l'IDE propulsé par l'IA d'IBM qui prend nativement en charge l'intégration MCP. Bob offre une expérience de développement fluide avec une assistance IA intégrée et des outils d'observabilité.

Mode Streamable HTTP

Le mode Streamable HTTP fournit une interface API REST pour la communication MCP utilisant JSON-RPC sur HTTP.

Étape 1 : Démarrer le serveur MCP en mode Streamable HTTP

Avant de configurer Bob, vous devez démarrer le serveur MCP en mode Streamable HTTP. Veuillez vous référer à la section Démarrage du serveur MCP local pour des instructions détaillées.

Étape 2 : Configurer Bob

Dans le coin supérieur droit du panneau Bob, vous verrez un menu déroulant avec les serveurs MCP :

En le sélectionnant, vous devriez voir l'option de configurer MCP au niveau du projet ou au niveau global.

Portées de configuration MCP

Bob prend en charge deux niveaux de configuration MCP, vous permettant de choisir la portée la mieux adaptée à votre cas d'utilisation :

1. Configuration globale (niveau utilisateur)

La configuration globale applique les serveurs MCP à tous les projets de l'utilisateur actuel. C'est idéal lorsque vous souhaitez que les mêmes serveurs MCP soient disponibles dans chaque projet sur lequel vous travaillez.

Emplacements des fichiers :

macOS : ~/Library/Application Support/Bob/bob_config.json
Windows : %APPDATA%\Bob\bob_config.json
Linux : ~/.config/Bob/bob_config.json

2. Configuration du projet (niveau projet)

La configuration du projet applique les serveurs MCP uniquement à un projet spécifique. C'est utile lorsque différents projets nécessitent différentes configurations de serveurs MCP ou lorsque vous souhaitez partager les paramètres MCP avec votre équipe via le contrôle de version.

Emplacement du fichier :

.bob/bob_config.json dans le répertoire racine de votre projet

Choix entre configuration globale et configuration du projet :

Utilisez la configuration globale pour les serveurs MCP que vous souhaitez disponibles dans tous vos projets
Utilisez la configuration du projet pour les serveurs MCP spécifiques à un projet ou pour partager des configurations avec votre équipe
Les deux configurations peuvent coexister — les paramètres au niveau du projet priment sur les paramètres globaux pour le même nom de serveur

Pour plus d'informations sur Bob et la configuration MCP, visitez : https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob

Configuration locale :

Configurez Bob pour vous connecter à votre serveur Instana MCP local :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Configuration distante :

Configurez Bob pour vous connecter à un serveur Instana MCP distant (par exemple, déployé sur IBM Code Engine) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://app-instana-750.1zetetanw8ul.us-east.codeengine.appdomain.cloud/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Remarque : Pour utiliser npx, nous recommandons d'installer d'abord NVM (Node Version Manager), puis de l'utiliser pour installer Node.js. Les instructions d'installation sont disponibles à l'adresse : https://nodejs.org/en/download

Étape 3 : Tester la connexion

Une fois la configuration MCP établie, le serveur MCP nouvellement configuré devrait apparaître comme activé. Un point vert indique que le serveur fonctionne correctement.

Vous pouvez maintenant exécuter des requêtes dans Bob IDE :

get me all applications from Instana in the last 24 hours

Mode Stdio

Configuration à l'aide de la CLI (installation PyPI - recommandée) :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Remarque : Si vous rencontrez des erreurs « command not found », utilisez le chemin complet vers mcp-instana. Trouvez-le avec which mcp-instana et utilisez ce chemin à la place.

Configuration à l'aide d'une installation de développement :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Claude Desktop

Claude Desktop prend en charge les modes Streamable HTTP et Stdio pour l'intégration MCP.

Configurez Claude Desktop en modifiant le fichier de configuration :

Emplacements des fichiers :

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json

Mode Streamable HTTP

Le mode Streamable HTTP fournit une interface API REST pour la communication MCP utilisant JSON-RPC sur HTTP.

Étape 1 : Démarrer le serveur MCP en mode Streamable HTTP

Avant de configurer Claude Desktop, vous devez démarrer le serveur MCP en mode Streamable HTTP. Veuillez vous référer à la section Démarrage du serveur MCP local pour des instructions détaillées.

Étape 2 : Configurer Claude Desktop

Configurez Claude Desktop pour transmettre les identifiants Instana via les en-têtes :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Étape 3 : Tester la connexion

Redémarrez Claude Desktop. Vous devriez maintenant voir Instana MCP Server dans l'interface de Claude Desktop comme illustré ci-dessous :

Vous pouvez maintenant exécuter des requêtes dans Claude Desktop :

get me all endpoints from Instana

Mode Stdio

Configuration à l'aide de la CLI (installation PyPI - recommandée) :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Remarque : Si vous rencontrez des erreurs « command not found », utilisez le chemin complet vers mcp-instana. Trouvez-le avec which mcp-instana et utilisez ce chemin à la place.

Configuration à l'aide d'une installation de développement :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana-folder>",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Configuration de Kiro

Kiro est un IDE agentique, et non une extension qui peut être téléchargée dans VS Code ou un autre IDE.

Étape 1 : Téléchargez et installez Kiro pour votre système d'exploitation à partir de https://kiro.dev/.

Étape 2 : Après l'installation, lancez Kiro et ouvrez n'importe quel projet dans l'IDE. alt text

Étape 3 : Cliquez sur l'icône Kiro (Fantôme) dans la barre latérale gauche pour accéder aux fonctionnalités de Kiro. alt text

Étape 4 : Sélectionnez l'icône Edit Config dans le coin supérieur droit de la section MCP Servers. alt text

Étape 5 : Ouvrez le fichier de configuration du serveur MCP (mcp.json) et configurez-le en fonction de votre mode de transport préféré :

Mode Streamable HTTP (recommandé pour Kiro)

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ]
    }
  }
}

Remarque : Assurez-vous de démarrer le serveur MCP en mode streamable-http avant d'utiliser cette configuration :

mcp-instana --transport streamable-http

Mode Stdio

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Étape 6 : Après avoir enregistré le fichier, cliquez sur le bouton Enable MCP et vous verrez votre serveur MCP et ses outils disponibles apparaître dans la section en bas à gauche de Kiro. alt text

Étape 7 : Accédez au panneau AI Chat, saisissez une invite liée à votre serveur MCP et affichez la réponse directement dans Kiro. alt text

GitHub Copilot

GitHub Copilot prend en charge l'intégration MCP via la configuration VS Code. Pour l'intégration de GitHub Copilot avec VS Code, consultez ce guide de configuration.

Mode Streamable HTTP

Étape 1 : Démarrer le serveur MCP en mode Streamable HTTP

Avant de configurer VS Code, vous devez démarrer le serveur MCP en mode Streamable HTTP. Veuillez vous référer à la section Démarrage du serveur MCP local pour des instructions détaillées.

Étape 2 : Configurer VS Code

Consultez Utiliser les serveurs MCP dans VS Code pour une configuration détaillée.

Vous pouvez créer ou mettre à jour directement .vscode/mcp.json avec la configuration suivante :

{
  "servers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: https://your-instana-instance.instana.io",
        "--header", "instana-api-token: your_instana_api_token"
      ],
      "env": {
        "PATH": "/usr/local/bin:/bin:/usr/bin",
        "SHELL": "/bin/sh"
      }
    }
  }
}

Remarque : Remplacez les valeurs suivantes par votre configuration réelle :

instana-base-url : L'URL de votre instance Instana
instana-api-token : Votre jeton API Instana
command : Mettez à jour le chemin npx pour qu'il corresponde à l'installation Node.js de votre système (par exemple, /path/to/your/node/bin/npx)
Variables d'environnement : Ajustez PATH et les autres variables d'environnement selon les besoins de votre système

Mode Stdio

Étape 1 : Créer la configuration MCP de VS Code

À l'aide de la CLI (installation PyPI - recommandée) :

Créez .vscode/mcp.json dans la racine de votre projet :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "servers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": ["--transport", "stdio"],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "servers": {
    "Instana MCP Server": {
      "command": "mcp-instana",
      "args": [
        "--transport", "stdio",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

À l'aide d'une installation de développement :

Créez .vscode/mcp.json dans la racine de votre projet :

Option 1 : Utilisation de variables d'environnement dans la configuration :

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py"
      ],
      "env": {
        "INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
        "INSTANA_API_TOKEN": "your_instana_api_token"
      }
    }
  }
}

Option 2 : Utilisation de l'option --env (méthode alternative) :

{
  "servers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project/mcp-instana",
        "run",
        "src/core/server.py",
        "--env", "INSTANA_BASE_URL=https://your-instana-instance.instana.io",
        "--env", "INSTANA_API_TOKEN=your_instana_api_token"
      ]
    }
  }
}

Remarque : Remplacez les valeurs suivantes par votre configuration réelle :

Pour l'installation CLI : Assurez-vous que mcp-instana est dans votre PATH
Pour l'installation de développement :
- command : Mettez à jour le chemin uv pour qu'il corresponde à l'installation uv de votre système (par exemple, /path/to/your/uv/bin/uv ou /usr/local/bin/uv)
- --directory : Mettez à jour avec le chemin absolu vers votre répertoire de projet mcp-instana
INSTANA_BASE_URL : L'URL de votre instance Instana
INSTANA_API_TOKEN : Votre jeton API Instana

Étape 2 : Gérer le serveur dans VS Code

Ouvrez .vscode/mcp.json — vous verrez les contrôles de gestion du serveur en haut
Cliquez sur Start à côté de Instana MCP Server pour démarrer le serveur
L'état d'exécution ainsi que le nombre d'outils indiquent que le serveur fonctionne

Étape 3 : Tester l'intégration

Passez en mode Agent dans GitHub Copilot et rechargez les outils. Voici un exemple de réponse de GitHub Copilot :

GitHub Copilot Response

Mistral AI

Mistral AI prend en charge l'intégration MCP exclusivement via le mode Streamable HTTP.

Étape 1 : Lancer le serveur MCP en mode Streamable HTTP

Démarrez le serveur MCP en mode Streamable HTTP en fournissant vos identifiants Instana. Exécutez la commande suivante :

uv run src/core/server.py --transport streamable-http \
  --api-token "your_instana_api_token" \
  --base-url "https://your-instana-instance.instana.io" \
  --port 8080

Étape 2 : Configurer le transfert de port avec Ngrok

Configurez le transfert de port pour exposer votre serveur local. Suivez la documentation de configuration Ngrok pour des instructions détaillées.

Étape 3 : Configurer Mistral AI

Accédez à l'onglet Intelligence dans la barre latérale gauche et sélectionnez Connectors
Cliquez sur Add Connector
Créez un connecteur personnalisé en saisissant un nom de connecteur et l'URL du serveur MCP transférée via Ngrok
Démarrez une nouvelle session de chat et vérifiez que les outils MCP sont activés. Vous pouvez afficher la réponse ici

Connexion à plusieurs serveurs Instana MCP

Vous pouvez configurer votre client MCP pour vous connecter à plusieurs instances. Voici un exemple de configuration :

{
  "mcpServers": {
    "Instana MCP Server1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header",
        "instana-base-url: ENV1_INSTANA_URL",
        "--header",
        "instana-api-token: ENV1_INSTANA_API_TOKEN"
      ]
    },
    "Instana MCP Server2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header",
        "instana-base-url: ENV2_INSTANA_URL",
        "--header",
        "instana-api-token: ENV2_INSTANA_API_TOKEN"
      ]
    }
  }
}

Pour cibler un serveur spécifique, assurez-vous que :

Le serveur est configuré avec le nom d'environnement approprié dans la configuration MCP (par exemple, Instana MCP Server1)
L'invite mentionne explicitement le nom du serveur/environnement. La requête sera ensuite routée vers le serveur configuré correspondant. Si aucun serveur/environnement n'est explicitement mentionné dans l'invite, MCP utilise le premier serveur défini dans la configuration comme serveur par défaut.

Remarque : Si le serveur demandé est hors ligne ou inaccessible, MCP se comporte comme prévu et transmet l'échec de l'API. L'utilisateur recevra l'erreur correspondante renvoyée par l'API, indiquant que le serveur est indisponible. MCP repose sur la disponibilité de l'API sous-jacente et n'effectue pas de basculement automatique.

Fonctionnalités prises en charge

Outils disponibles

Outil	Catégorie	Description
`manage_applications`	Applications et infrastructure	Outil unifié pour gérer les métriques d'application, les configurations d'alertes, les paramètres et le catalogue
`manage_websites`	Surveillance de sites web	Routeur intelligent unifié pour les opérations d'analyse, de catalogue, de configuration et de configuration avancée des sites web
`manage_custom_dashboards`	Tableaux de bord personnalisés	Outil unifié pour gérer les opérations CRUD des tableaux de bord personnalisés
`manage_infrastructure`	Infrastructure	Routeur intelligent unifié pour l'analyse d'infrastructure, le catalogue (`get_plugin_schema`) et les opérations sur les ressources d'instantané
`manage_automation`	Automatisation	Routeur intelligent unifié pour l'automatisation : parcourir le catalogue d'actions et consulter l'historique d'exécution
`manage_events`	Événements	Routeur intelligent unifié pour la surveillance des événements : obtenir un événement par ID, obtenir des événements par IDs, événements Kubernetes, événements de surveillance d'agent et tous les événements
`manage_slo`	Gestion des SLO	Routeur intelligent unifié pour les configurations SLO, les rapports, les alertes et les fenêtres de correction avec gestion intelligente des fuseaux horaires
`manage_releases`	Gestion des versions	Routeur intelligent unifié pour le suivi des versions : lister les versions avec pagination et filtrage par nom, obtenir les détails des versions, créer/mettre à jour/supprimer des versions avec prise en charge des fuseaux horaires
`manage_maintenance_windows`	Fenêtres de maintenance	Routeur intelligent unifié pour la gestion du cycle de vie des fenêtres de maintenance : créer, modifier, fermer et lister les fenêtres de maintenance avec prise en charge des modèles et intégration ServiceNow
`manage_mobile_apps`	Surveillance des applications mobiles	Routeur intelligent unifié pour la surveillance des applications mobiles : analyser les balises, les métriques de performance, la relecture de session, la configuration et la gestion des alertes
`manage_synthetics`	Surveillance synthétique	Routeur intelligent unifié pour la surveillance synthétique : catalogue, métriques, paramètres (lecture seule) et résultats de lecture de test

👉 Pour une documentation détaillée des outils, les capacités et la référence technique, consultez Outils et exemples

Filtrage des outils

Le serveur MCP prend en charge le chargement sélectif des outils pour optimiser les performances et réduire l'utilisation des ressources. Vous pouvez activer uniquement les catégories d'outils dont vous avez besoin pour votre cas d'utilisation spécifique.

Catégories d'outils disponibles

router : Gestion unifiée des applications et de l'infrastructure
- manage_instana_resources : Outil unique pour les métriques d'application, les configurations d'alertes, les paramètres et le catalogue
- Prend en charge les perspectives d'application, les points de terminaison, les services et les services manuels
- Gère à la fois les configurations d'alertes spécifiques aux applications et globales
- Fournit l'accès au catalogue de balises d'application et au catalogue de métriques
dashboard : Gestion des tableaux de bord personnalisés
- manage_custom_dashboards : Opérations CRUD pour les tableaux de bord personnalisés
- Prend en charge la création, la récupération, la mise à jour et la suppression de tableaux de bord
- Gère les utilisateurs partageables et les jetons API pour les tableaux de bord
infra : Outils de gestion de l'infrastructure
- manage_infrastructure : Routeur intelligent unifié pour l'analyse d'infrastructure, le catalogue et les opérations sur les ressources d'instantané
- get_plugin_schema combine get_metrics + get_tag_catalog en un seul appel API
- Prend en charge dynamiquement tous les types d'entités disponibles dans votre installation Instana (chargés automatiquement depuis le catalogue API)
- Inclut JVM, Kubernetes, Docker, hôtes, bases de données, files de messages et tout type d'entité personnalisé ou nouvellement ajouté
- Agrégation flexible des métriques, filtrage, regroupement et requêtes sur plages de temps
automation : Outils d'action d'automatisation
- manage_automation : Routeur intelligent unifié pour le catalogue d'automatisation et l'historique d'exécution
- Catalogue d'actions : parcourir les actions, obtenir les détails, rechercher par nom/description, filtrer par application ou ID de snapshot
- Historique des actions : lister les instances d'exécution avec filtrage, obtenir les détails d'exécution
events : Outils de surveillance des événements
- Événements : événements Kubernetes, surveillance des agents et suivi des événements système
website : Outils de surveillance de sites Web
- Métriques de site Web : mesure des performances des sites Web
- Catalogue de sites Web : métadonnées et définitions des sites Web
- Analyse de site Web : analyse des performances des sites Web
- Configuration de site Web : gestion de la configuration des sites Web
slo : Gestion des objectifs de niveau de service (SLO)
- manage_slo : Routeur intelligent unifié pour des opérations SLO complètes
- Gestion de la configuration : créer, lire, mettre à jour, supprimer des configurations SLO avec prise en charge des indicateurs basés sur le temps et sur les événements
- Génération de rapports : générer des rapports SLO détaillés avec les valeurs SLI, les budgets d'erreur, les taux de consommation et les graphiques de séries temporelles
- Configuration des alertes : gérer les configurations d'alertes SLO pour la surveillance du budget d'erreur et le suivi du taux de consommation
- Fenêtres de correction : créer et gérer des fenêtres de maintenance pour exclure les temps d'arrêt planifiés des calculs SLO
- Gestion intelligente des fuseaux horaires : élucidation automatique du fuseau horaire pour les entrées de date et heure afin de garantir un contexte temporel précis
- Élucidation en deux passes : collecte interactive des paramètres pour les opérations complexes nécessitant plusieurs entrées
releases : Suivi des versions et gestion des déploiements
- manage_releases : Routeur intelligent unifié pour les opérations de version
- Lister les versions : obtenir toutes les versions avec une pagination efficace (page_number, page_size) et un filtrage par nom
- Détails de la version : récupérer les informations spécifiques d'une version par ID, y compris les applications, les services et les portées
- Créer/Mettre à jour/Supprimer : opérations CRUD complètes pour la gestion des versions
- Gestion intelligente des fuseaux horaires : élucidation automatique du fuseau horaire pour les heures de début des versions
- Pagination efficace : éviter les récupérations de données redondantes grâce à une navigation par page appropriée
- Filtrage par nom : correspondance de sous-chaîne insensible à la casse pour trouver des versions par nom
maintenance_window : Gestion du cycle de vie des fenêtres de maintenance
- manage_maintenance_windows : Routeur intelligent unifié pour les opérations de fenêtres de maintenance
- Opérations de fenêtres : créer, modifier, fermer et lister les fenêtres de maintenance (actives, planifiées, toutes, expirées)
- Opérations en masse : créer des fenêtres de maintenance pour plusieurs applications simultanément
- Prise en charge des modèles : modèles prédéfinis pour les scénarios courants (deployment, database_migration, infrastructure_upgrade, emergency, routine)
- Fenêtres récurrentes : prise en charge des fenêtres de maintenance récurrentes à l'aide du format RRULE RFC 5545
- Intégration ServiceNow : intégration facultative avec les demandes de changement ServiceNow
- Validation : validation des paramètres avant la création de la fenêtre
- Durée flexible : spécifier la durée en minutes, heures ou jours
mobile_app : Surveillance des applications mobiles
- manage_mobile_apps : Routeur intelligent unifié pour les opérations de surveillance des applications mobiles
- Relecture de session : récupérer les balises d'action de relecture de session paginées par ID d'application mobile et ID de session (resource_type="session_replay")
- Analyse des balises : interroger les données de balises des applications mobiles avec regroupement et filtrage
- Métriques de performance : suivre la durée des sessions, les taux de plantage et les performances des requêtes HTTP
- Analyse géographique : analyser la répartition des utilisateurs par pays, ville et région
- Analyse des appareils : surveiller les performances sur différents appareils, plateformes et versions de système d'exploitation
- Gestion de la configuration : gérer les configurations des applications mobiles, la géolocalisation et les paramètres de masquage IP
- Gestion des alertes : configurer et gérer les configurations d'alertes des applications mobiles
synthetics : Gestion de la surveillance synthétique
- manage_synthetics : Routeur intelligent unifié pour toutes les opérations de surveillance synthétique
- Catalogue : découvrir les ID de métriques et les noms de balises valides avant de construire des requêtes
- Métriques : récupérer les temps de réponse agrégés et les taux de réussite groupés par emplacement ou nom de test
- Paramètres : lister et rechercher des tests et des emplacements avec résolution automatique des noms ; identifier les PoP de datacenter (Managed) par rapport aux PoP auto-hébergés (Private)
- Relecture de test : résultats bruts par exécution, analyses LAST_VALUE, résumés des taux de réussite par emplacement et téléchargements de fichiers de détails (LOGS, HAR, captures d'écran)

Exemples d'utilisation

Utilisation de la CLI (installation PyPI)

# Enable only router (unified app/infra management) and events tools
mcp-instana --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
mcp-instana --tools infra --transport streamable-http

# Enable router and infrastructure analysis
mcp-instana --tools router,infra --transport streamable-http

# Enable events and website tools
mcp-instana --tools events,website --transport streamable-http

# Enable dashboard and router tools
mcp-instana --tools dashboard,router --transport streamable-http

# Enable releases and events tools
mcp-instana --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
mcp-instana --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
mcp-instana --transport streamable-http

# List all available tool categories and their tools
mcp-instana --list-tools

Utilisation de l'installation de développement

# Enable only router (unified app/infra management) and events tools
uv run src/core/server.py --tools router,events --transport streamable-http

# Enable only infrastructure analysis tools
uv run src/core/server.py --tools infra --transport streamable-http

# Enable router and infrastructure analysis
uv run src/core/server.py --tools router,infra --transport streamable-http

# Enable events and website tools
uv run src/core/server.py --tools events,website --transport streamable-http

# Enable dashboard and router tools
uv run src/core/server.py --tools dashboard,router --transport streamable-http

# Enable releases and events tools
uv run src/core/server.py --tools releases,events --transport streamable-http

# Enable maintenance window and events tools
uv run src/core/server.py --tools maintenance_window,events --transport streamable-http

# Enable all tools (default behavior)
uv run src/core/server.py --transport streamable-http

# List all available tool categories and their tools
uv run src/core/server.py --list-tools

Avantages du filtrage des outils

Performance : temps de démarrage et utilisation de la mémoire réduits
Sécurité : limiter l'exposition aux seules API nécessaires
Clarté : se concentrer sur des cas d'utilisation spécifiques (par exemple, uniquement la surveillance de l'infrastructure)
Efficacité des ressources : réduction de l'utilisation du processeur et du réseau

👉 Pour des exemples d'utilisation et des invites, voir Exemples d'invites

Déploiement Docker

Le serveur MCP Instana peut être déployé à l'aide de Docker pour les environnements de production. La configuration Docker est optimisée pour la sécurité, les performances et une utilisation minimale des ressources.

Construction de l'image Docker

Prérequis

Docker installé et en cours d'exécution
Accès au code source du projet

Construction et exécution

# Build the image
docker build -t mcp-instana:latest .

# Build with a specific tag
docker build -t mcp-instana:<image_tag> .

# Run the container (credentials are supplied via HTTP headers at request time)
docker run -p 8080:8080 mcp-instana

# Run with a custom host port
docker run -p 8081:8080 mcp-instana

📖 Pour une documentation Docker complète incluant les builds multi-architectures, .dockerignore, les bonnes pratiques de sécurité et des exemples de déploiement en production, voir DOCKER.md.

Dépannage

Problèmes Docker

Le conteneur ne démarre pas

# Check container logs
docker logs <container_id>
# Common issues:
# 1. Port already in use
# 2. Invalid container image
# 3. Missing dependencies
# Credentials are passed via HTTP headers from the MCP client

Problèmes de connexion

# Test container connectivity (expects 406 from a bare GET — means server is up)
curl http://localhost:8080/mcp
# Check port mapping
docker port <container_id>

Problèmes de performance

# Check container resource usage
docker stats <container_id>
# Monitor container health
docker inspect <container_id> | grep -A 10 Health

Problèmes généraux

GitHub Copilot
- Si vous rencontrez des problèmes avec GitHub Copilot, essayez de démarrer/arrêter/redémarrer le serveur dans le fichier mcp.json et ne gardez qu'un seul serveur en cours d'exécution à la fois.
Problèmes de certificats
- Si vous rencontrez des problèmes de certificats, tels que [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate :
  - Vérifiez que vous pouvez atteindre le point de terminaison de l'API Instana à l'aide de curl ou wget avec vérification SSL.
    - Si cela fonctionne, votre environnement Python peut ne pas être en mesure de vérifier le certificat et peut ne pas avoir accès aux mêmes certificats que votre shell ou votre système. Assurez-vous que votre environnement Python utilise les certificats système (macOS). Vous pouvez le faire en installant les certificats dans Python : /Applications/Python\ 3.13/Install\ Certificates.command
  - Si vous ne pouvez pas atteindre le point de terminaison avec la vérification SSL, essayez sans. Si cela fonctionne, vérifiez les certificats CA de votre système et assurez-vous qu'ils sont à jour.