Démarrage rapide¶
Dernière mise à jour : 4 juin 2026
Ce guide vous accompagne pas à pas pour mettre en service AI-Bridge for Cisco UC — des prérequis jusqu'à votre première connexion réussie d'agent IA.
Avant de commencer¶
Le parcours complet se déroule en six étapes :
Durée estimée : ~une heure pour un déploiement standard sur un hôte Docker préparé.
Étape 1 — Prérequis¶
Docker¶
AI-Bridge for Cisco UC est déployé sous forme de conteneur Docker.
Prérequis :
- Docker Engine ≥ 27.0
- Docker Compose ≥ 2.32
Pour les instructions d'installation, consultez la documentation officielle de Docker.
Compte de service : créez un utilisateur non-root dédié (ex. docker) et ajoutez-le au groupe docker pour qu'il puisse gérer les conteneurs sans sudo :
Toutes les commandes suivantes de ce guide supposent que vous êtes connecté avec cet utilisateur.
Système d'exploitation hôte : tout OS capable d'exécuter Docker.
- Linux — recommandé pour la production (Docker Engine)
- macOS — pris en charge via Docker Desktop
- Windows — pris en charge via Docker Desktop avec WSL 2
Recommandation production
Pour les déploiements en production, utilisez un hôte Linux avec Docker Engine pour de meilleures performances, stabilité et sécurité. Docker Desktop (macOS / Windows) convient pour l'évaluation, le développement et les environnements de lab.
Ressources hôte minimales :
- CPU : 2 vCPUs
- RAM : 2 Go
- Disque : 10 Go (variable selon la rétention des sauvegardes et le volume de rapports)
Prérequis Cisco UC¶
Le module CUCM utilise trois protocoles : AXL, RIS et SSH.
| Protocole | Prérequis |
|---|---|
| AXL | Activer Cisco AXL Web Service sur le noeud publisher (Serviceability → Tools → Service Activation). Créer un compte utilisateur (EndUser ou ApplicationUSer) avec les rôles "Standard AXL API Users", "Standard SERVICEABILITY" et "Standard CCM Admin Users" |
| RIS | Cisco RisPort70 fonctionne par défaut — aucune activation nécessaire. Mêmes compte utilisateur que pour la connexion AXL. |
| SSH | Accès SSH activé sur les noeuds CUCM. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis. |
Le module IMP utilise deux protocoles : AXL et SSH.
| Protocole | Prérequis |
|---|---|
| AXL | Activer Cisco AXL Web Service sur le noeud publisher (Serviceability → Tools → Service Activation). Mêmes compte utilisateur que pour la connexion AXL du CUCM. |
| SSH | Accès SSH activé sur les noeuds IMP. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis. |
Le module CUC utilise deux protocoles : CUPI (REST) et SSH. Il n'y a pas d'AXL/SOAP ni de notion de cluster — les opérations sont effectuées par hôte.
| Protocole | Prérequis |
|---|---|
| CUPI | REST est activé par défaut sur tcp/8443 (/vmrest/). Créer un compte administrateur Unity Connection. Pour un usage en lecture seule, le rôle "System Administrator" suffit. Pour les opérations d'écriture (provisioning d'utilisateurs, call handlers, schedules, etc.), assigner le modèle de rôles couvrant les endpoints CUPI ciblés. |
| SSH | Accès SSH activé sur les noeuds CUC. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis. |
Comptes nominatifs — bonne pratique
Créez un compte dédié par utilisateur AI-Bridge sur les serveurs Cisco UC, plutôt que de partager un compte de service unique. Cela permet le contrôle d'accès par utilisateur, la corrélation bout-en-bout de la piste d'audit et l'isolation des identifiants.
Prérequis réseau¶
Assurez-vous que les ports suivants sont ouverts sur vos pare-feux :
| Source | Destination | Port | Protocole | Objet |
|---|---|---|---|---|
| Agent IA | Serveur | tcp/8443* | HTTPS | Connectivité client MCP |
| Reverse-proxy web | Serveur | tcp/8443* | HTTPS | (optionnel) Connectivité client MCP via reverse-proxy |
| Serveur | CUCM | tcp/8443 | HTTPS | AXL/SOAP, RIS/SOAP |
| Serveur | CUCM | tcp/22 | SSH | Commandes VOS CLI |
| Serveur | IMP | tcp/8443 | HTTPS | AXL/SOAP |
| Serveur | IMP | tcp/22 | SSH | Commandes VOS CLI |
| Serveur | CUC | tcp/8443 | HTTPS | CUPI/REST |
| Serveur | CUC | tcp/22 | SSH | Commandes VOS CLI |
| Serveur | Serveur SFTP | tcp/22 | SSH | Export de sauvegarde (optionnel) |
* MCP_SERVER_PORT par défaut — configurable dans .env.
Aucun accès internet requis
Le serveur n'initie jamais de connexions sortantes vers internet. Les licences, mises à jour et télémétries sont entièrement hors ligne.
Étape 2 — Obtenir votre licence¶
AI-Bridge for Cisco UC nécessite une licence valide pour fonctionner. Chaque licence est liée au nom d'hôte du serveur.
Récupérer le nom d'hôte de votre serveur :
Liaison au nom d'hôte
La licence est verrouillée sur le FQDN retourné par hostname -f sur l'hôte Docker. Assurez-vous que ce nom d'hôte est stable avant de commander — tout changement (renommage de VM, mise à jour DNS, migration) invalidera la licence.
Pour commander une licence :
- Contactez contact@sourdeau.com avec le nom de votre organisation, le périmètre de déploiement prévu et le nom d'hôte du serveur (
hostname -f). - Vous recevrez un fichier
license.jwtpar transfert sécurisé. - Le fichier de licence est installé ultérieurement (Étape 5).
Licence de démonstration disponible
Une licence de démonstration à durée limitée est disponible sur demande pour évaluer le produit dans votre environnement avant achat.
La licence est indépendante de la version
Une licence valide continue de fonctionner à travers les mises à niveau — aucune réémission n'est nécessaire après une mise à niveau.
Étape 3 — Installation¶
3.1 Obtenir le paquet¶
AI-Bridge est distribué sous forme d'une archive unique :
ai-bridge-for-cisco-uc-<version>.tar.gz # Archive de release (config, docker-compose, scripts, image Docker pré-construite)
Le paquet est livré par l'éditeur via transfert de fichiers sécurisé. Aucun accès internet n'est requis sur le serveur cible. Contactez contact@sourdeau.com pour demander une version.
3.2 Vérifier l'intégrité du paquet¶
Avant l'installation, vérifiez l'archive en utilisant la checksum SHA-512 publiée via DNS :
# 1. Interroger l'enregistrement TXT DNS publié par l'éditeur (utilise un ordinateur avec résolution DNS publique)
dig ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com txt +short
# 2. Calculer le hachage SHA-512 de l'archive téléchargée
sha512sum ai-bridge-for-cisco-uc-<version>.tar.gz
# 3. Comparer les deux valeurs — elles doivent correspondre exactement
# 1. Interroger l'enregistrement TXT DNS publié par l'éditeur (utilise un ordinateur avec résolution DNS publique)
nslookup -q=txt ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com
# 2. Calculer le hachage SHA-512 de l'archive téléchargée
Get-FileHash -Algorithm SHA512 ai-bridge-for-cisco-uc-<version>.tar.gz
# 3. Comparer les deux valeurs — elles doivent correspondre exactement
Ne pas ignorer cette étape
Si les valeurs ne correspondent pas, n'allez pas plus loin. Contactez contact@sourdeau.com immédiatement.
3.3 Extraire¶
Extrayez l'archive dans le répertoire d'installation de votre choix sur l'hôte Docker :
# Créer le répertoire d'installation et extraire le paquet
mkdir ~/ai-bridge && cd ~/ai-bridge
tar -xzf /path/to/ai-bridge-for-cisco-uc-<version>.tar.gz
Après extraction, le répertoire contient le docker-compose.yml, le fichier .env, l'image Docker pré-construite et tous les fichiers associés.
3.4 Charger l'image Docker¶
Chargez l'image Docker pré-construite incluse dans l'archive (aucun accès internet requis) :
Vérifiez que l'image est bien chargée :
Vous devriez voir ai-bridge-for-cisco-uc avec le tag latest.
Docker Compose utilisera l'image pré-chargée et montera les données d'exécution depuis ce répertoire.
Étape 4 — Configuration initiale¶
4.1 Éditer .env¶
Le fichier de configuration .env est inclus dans le paquet, prêt à être édité :
| Clé | Valeur à définir | Pourquoi |
|---|---|---|
HOST_FQDN |
Le FQDN de votre serveur (ex. mcp.domain.com) — exécutez hostname -f |
Obligatoire — utilisé comme nom d'hôte du conteneur Docker et doit correspondre à la liaison hostname de la licence |
AUTH_CLIENTS |
Définir au moins un client IA (ex. claude:sub-claude-20260512:admin) |
Obligatoire — le serveur refuse de démarrer sans au moins un client |
AUTH_ISSUER |
L'URL HTTPS de votre serveur (ex. https://mcp.domain.com:8443) |
Recommandé — intégré dans les tokens JWT et les métadonnées OAuth |
MCP_SERVER_SECURITY_ALLOWED_HOSTS |
Ajouter le FQDN du serveur (ex. localhost:*,127.0.0.1:*,mcp.domain.com:*) |
Recommandé — utilisé pour la protection DNS rebinding et les entrées SAN du certificat TLS |
MCP_SERVER_SECURITY_ALLOWED_ORIGINS |
Ajouter l'origine du serveur (ex. https://mcp.domain.com:8443) |
Recommandé — requis pour la validation CORS / en-tête Origin |
UID / GID |
L'UID et le GID de votre compte de service (exécutez id -u && id -g) |
Requis si votre utilisateur n'est pas UID 1000 — permet au conteneur d'écrire dans les volumes |
Référence complète de configuration
Tous les paramètres disponibles sont documentés dans le guide Setup. Vous pouvez reconfigurer .env à tout moment — les changements prennent effet au prochain docker compose up -d.
4.2 Importer un certificat signé par une CA (optionnel)¶
Par défaut, le serveur génère automatiquement un certificat TLS auto-signé au premier démarrage. Si vous disposez déjà d'un certificat signé par une CA, vous pouvez le déployer avant le premier démarrage :
# Placez votre chaîne de certificat et votre clé privée dans le répertoire secrets
cp /path/to/your-cert.crt secrets/server-ca-signed.crt
cp /path/to/your-cert.key secrets/server-ca-signed.key
chmod 600 secrets/server-ca-signed.key
Si ces fichiers sont présents au démarrage, le serveur les utilise à la place du certificat auto-signé. Aucune modification de .env n'est nécessaire — les chemins par défaut dans .env.example pointent déjà vers secrets/server-ca-signed.crt et secrets/server-ca-signed.key.
Pas encore de certificat ?
Pas de problème — démarrez d'abord le serveur avec le certificat auto-signé généré automatiquement (Étape 5). Vous pourrez générer une CSR et déployer un certificat signé par une CA ultérieurement (Étape 5.3) sans aucune perte de données.
Étape 5 — Premier démarrage¶
5.1 Installer la licence¶
Avant de démarrer le serveur pour la première fois, copiez le fichier de licence dans le répertoire secrets/ :
Aucun redémarrage nécessaire pour les renouvellements
Le watchdog de licence en arrière-plan vérifie toutes les 24 heures et prend automatiquement en charge un fichier de licence renouvelé.
5.2 Démarrer le conteneur¶
Vérifiez que le conteneur est en cours d'exécution et en bonne santé :
Au premier démarrage, le serveur effectue automatiquement :
- Génération d'une paire de clés RSA-4096 — utilisée pour la signature JWT, le chiffrement des sauvegardes et la vérification des licences
- Génération d'un certificat TLS auto-signé — avec des entrées SAN dérivées de
MCP_SERVER_SECURITY_ALLOWED_HOSTS - Création des répertoires clients — sous-répertoires
secrets/,reports/etcustom/isolés par client - Génération des tokens bearer clients — pour chaque client en mode d'auth JWT (écrits dans
clients/<name>/secrets/.token) - Génération des secrets oauth clients — pour chaque client en mode d'auth OAuth (écrits dans
clients/<name>/secrets/.secret) - Exécution de la vérification d'intégrité logicielle — par rapport à
manifest.jsonetmanifest.sig - Vérification de la licence — depuis
secrets/license.jwt
Après le démarrage, le serveur journalise son point de terminaison :
Toutes les données d'exécution sont persistées sur l'hôte via des volumes bind-mount :
| Chemin hôte | Chemin conteneur | Rôle |
|---|---|---|
./.env |
/app/.env |
Configuration (lecture seule) |
./secrets/ |
/app/secrets/ |
Clés RSA, certificats TLS |
./clients/ |
/app/clients/ |
Données clients, rapports |
./logs/ |
/app/logs/ |
Journaux applicatifs & audit |
./backups/ |
/app/backups/ |
Sauvegardes chiffrées |
./servers-data/ |
/app/servers-data/ |
Schémas AXL/RIS, prompts custom |
./upgrade/ |
/app/upgrade/ |
Paquets de mise à jour |
5.3 Déployer un certificat signé par une CA (optionnel)¶
Une fois le serveur en fonctionnement, vous pouvez remplacer le certificat auto-signé par un certificat signé par une CA. Générez une CSR directement dans le conteneur en cours d'exécution :
Le script lit votre .env automatiquement pour extraire le FQDN et génère une CSR avec les extensions SAN, Key Usage et Extended Key Usage appropriées. Les fichiers sont écrits dans le volume secrets/ sur l'hôte.
Faites ensuite signer la CSR par votre CA interne (la commande openssl exacte est affichée par le script), copiez le certificat signé en place et redémarrez :
# Après signature de la CSR par votre CA :
cp /path/to/signed-cert.crt secrets/server-ca-signed.crt
docker compose restart
Nettoyage du certificat auto-signé
Lorsque le serveur détecte un certificat CA-signé valide au démarrage, le certificat auto-signé généré automatiquement et sa clé privée sont supprimés de secrets/. (si openssl est disponible sur l'hôte) :
openssl req -new -newkey rsa:4096 -nodes \
-keyout secrets/server-ca-signed.key \
-out secrets/server-ca-signed.csr \
-subj "/C=FR/O=Mon Entreprise/CN=mcp.domain.com" \
-addext "subjectAltName=DNS:mcp.domain.com" \
-addext "keyUsage=digitalSignature,keyEncipherment" \
-addext "extendedKeyUsage=serverAuth"
chmod 600 secrets/server-ca-signed.key
Remplacez mcp.domain.com par le FQDN de votre serveur (la valeur de AUTH_ISSUER).
Aucune interruption
Le serveur fonctionne avec le certificat auto-signé jusqu'au déploiement du certificat signé par la CA. Un simple docker compose restart bascule sur le nouveau certificat.
Étape 6 — Connecter votre agent IA¶
6.1 Obtenir votre token Bearer¶
Votre token bearer est généré au premier démarrage. Récupérez-le :
Demandez un token de courte durée en utilisant vos identifiants client :
curl -sk -X POST https://mcp.domain.com:8443/token \
-u "<client_id>:<client_secret>" \
-d "grant_type=client_credentials"
client_id se trouve dans clients/<name>/secrets/.uuid et client_secret dans clients/<name>/secrets/.secret.
6.2 Configurer votre premier agent IA¶
Ajoutez le serveur MCP au fichier de configuration de votre agent, en utilisant le token récupéré ci-dessus.
Éditez claude_desktop_config.json :
Éditez opencode.json :
Éditez ~/.cursor/mcp.json (ou le fichier .cursor/mcp.json au niveau du projet) :
6.3 Faire confiance au certificat du serveur¶
Votre agent IA doit faire confiance au certificat TLS du serveur MCP — qu'il s'agisse du certificat auto-signé généré automatiquement ou d'un certificat signé par une CA déployé à l'étape 5.3. Importez le certificat dans le magasin de confiance de votre client ou configurez le client pour l'accepter.
6.4 Vérifier la connexion¶
Demandez à votre agent IA de vérifier la connectivité au serveur MCP et de lister les outils disponibles.
Vous devriez voir le statut du serveur MCP tel que MCP server is healthy and ready et la liste des outils (common_, infra_ et {products}_).
Et ensuite ?¶
| Guide | Ce que vous y trouverez |
|---|---|
| Setup | Configuration avancée : référence complète .env, configuration TLS, durcissement du transport, journalisation d'audit, modes d'authentification, gestion des clients, profils RBAC |
| Operations | Opérations courantes : démarrage/arrêt, supervision, sauvegarde, mise à niveau, rotation des clés |