Aller au contenu

Installation et configuration

Prérequis

  • Une instance canopsis-internal-api déjà installée et joignable (URL et port, 8082 par défaut).
  • Un compte utilisateur Canopsis dédié, avec une authkey et les permissions strictement nécessaires aux actions que vous souhaitez autoriser (voir Sécurité et audit).

canopsis-mcp-server est un composant Pro, livré comme les autres services Canopsis : image Docker mcp-server, et paquet RPM canopsis-pro qui installe le binaire (/opt/canopsis/bin/mcp-server), son fichier de configuration et son unité systemd. Aucune compilation n’est nécessaire.

Fichier de configuration

Le serveur lit un fichier YAML organisé en trois sections : server (le service HTTP MCP lui-même), api (comment joindre canopsis-internal-api) et mcp (comportement du protocole et routes de l’API utilisées).

server:
  # Nom du serveur, affiché aux clients MCP
  name: canopsis-mcp-server
  # Adresse d'écoute du serveur HTTP (host:port). Exemple : ":8081" ou "127.0.0.1:8081"
  bind_addr: ":8081"
  # Origines autorisées en CORS, séparées par des virgules. "*" autorise toutes les origines.
  cors_allowed_origins: ""

api:
  # URL de base de l'API Canopsis (sans slash final)
  url: "http://127.0.0.1:8082"
  # Timeout HTTP (en secondes) pour les appels vers l'API
  http_timeout_seconds: 10
  # Désactive la vérification TLS pour les appels vers l'API (à laisser à false en production)
  insecure_skip_verify: false

mcp:
  # Identifiant transmis dans les en-têtes d'audit MCP
  caller_id: canopsis-mcp
  # Active ou désactive les outils MCP mutables (kill switch d'écriture)
  write_enabled: true
  # Identifiant de connecteur utilisé pour les événements créés via create_alarm (obligatoire)
  connector: "mcp"
  # Nom lisible du connecteur (optionnel)
  connector_name: "mcp"
  # Route utilisée pour créer/mettre à jour une alarme
  create_alarm_route: "/internal/event"
  # Route pour récupérer une alarme par id (doit contenir un "%s")
  get_alarm_by_id_route: "/internal/alarms/%s"
  # Route pour récupérer une alarme par entité (doit contenir un "%s")
  get_alarm_by_entity_route: "/internal/open-alarms?_id=%s"
  # Route utilisée pour la recherche d'alarmes
  search_alarms_route: "/internal/alarms"

mcp.connector est obligatoire : c’est l’identifiant de connecteur associé aux événements créés par create_alarm, ce qui permet de distinguer dans Canopsis les alarmes issues du serveur MCP.

Le fichier de configuration est attendu par défaut à l’emplacement /opt/canopsis/share/config/mcp-server/config.yml, comme les autres fichiers de configuration Canopsis.

Options de démarrage

Option Description
--config <chemin>, -c <chemin> Chemin du fichier de configuration (par défaut /opt/canopsis/share/config/mcp-server/config.yml)
--debug, -d Active les journaux de débogage
--logger <sortie> Sortie des journaux : stderr ou journald
--version Affiche la version

La variable CPS_MCP_CONFIG_FILE n’est prise en compte que si l’option --config n’est pas utilisée.

Variables d’environnement

Chaque paramètre peut être surchargé par une variable d’environnement, utile en conteneur :

Variable Clé de configuration
CPS_MCP_SERVER_NAME server.name
CPS_MCP_BIND_ADDR server.bind_addr
CPS_MCP_CORS_ALLOWED_ORIGINS server.cors_allowed_origins
CPS_INTERNAL_API_URL api.url
CPS_API_HTTP_TIMEOUT api.http_timeout_seconds
CPS_API_INSECURE_SKIP_VERIFY api.insecure_skip_verify
CPS_MCP_CALLER_ID mcp.caller_id
CPS_MCP_WRITE_ENABLED mcp.write_enabled
CPS_MCP_CONNECTOR mcp.connector
CPS_MCP_CONNECTOR_NAME mcp.connector_name
CPS_MCP_CREATE_ALARM_ROUTE mcp.create_alarm_route
CPS_MCP_GET_ALARM_BY_ID_ROUTE mcp.get_alarm_by_id_route
CPS_MCP_GET_ALARM_BY_ENTITY_ROUTE mcp.get_alarm_by_entity_route
CPS_MCP_SEARCH_ALARMS_ROUTE mcp.search_alarms_route
CPS_MCP_CONFIG_FILE Chemin du fichier de configuration, si l’option --config n’est pas utilisée

Déploiement en sidecar

canopsis-mcp-server est conçu pour tourner à côté de canopsis-internal-api, sur le même réseau, plutôt que comme un service isolé : il doit pouvoir joindre api.url, et n’a pas vocation à être exposé directement sur Internet.

Le paquet canopsis-pro installe le binaire /opt/canopsis/bin/mcp-server, le fichier de configuration /opt/canopsis/share/config/mcp-server/config.yml et l’unité systemd canopsis-service@mcp-server.service.

Adaptez le fichier de configuration à votre environnement (voir ci-dessus), puis activez et démarrez le service :

systemctl enable canopsis-service@mcp-server.service
systemctl start canopsis-service@mcp-server.service

Consultez ses journaux avec :

journalctl -u canopsis-service@mcp-server.service -f

Le service mcp-server est déclaré dans le fichier docker-compose.override.yml de l’environnement Docker Compose Canopsis Pro, derrière un profil dédié mcp :

mcp-server:
  <<: *app_service_base
  profiles:
    - mcp
  image: ${DOCKER_REPOSITORY}${CPS_EDITION}/mcp-server:${CANOPSIS_IMAGE_TAG}
  ports:
    - "8081:8081"
  volumes:
    - ./files-pro/mcp-server/config.yml:/opt/canopsis/share/config/mcp-server/config.yml

Le fichier de configuration se trouve dans files-pro/mcp-server/config.yml. L’URL de l’API est reprise de la variable CPS_INTERNAL_API_URL du fichier canopsis.env.

Un simple docker compose up -d ne démarre pas ce service : il faut activer le profil explicitement.

Démarrez le service :

docker compose --profile mcp up -d mcp-server

Consultez ses journaux avec :

docker compose logs -f mcp-server

Note

Adaptez le nom d’image et les variables (DOCKER_REPOSITORY, CANOPSIS_IMAGE_TAG) à celles de l’environnement Docker Compose livré avec votre version de Canopsis.

Par défaut, ne publiez le port 8081 que sur les réseaux internes qui en ont besoin. Voir Sécurité et audit avant d’envisager un accès depuis l’extérieur du réseau Canopsis.

Vérifier que le service tourne

curl -i http://127.0.0.1:8081/

Une réponse non-2xx sur ce simple GET est normale : elle prouve seulement que le port HTTP répond. Un client MCP réalise l’initialisation du protocole via une requête POST.