Installation et configuration¶
Prérequis¶
- Une instance
canopsis-internal-apidéjà installée et joignable (URL et port,8082par 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.