Une fois OpenClaw Gateway stabilisée, brancher la chaîne d’outils MCP se heurte rarement au simple « ping » : le dur est le choix du transport, le cycle de vie des sous-processus, le protocole de handshake et les blocages en aval. Avec les articles liste blanche MCP et connectivité, durcissement et installation multiplateforme, nous clarifions ici le périmètre et sept irritants récurrents, un tableau stdio vs HTTP/SSE, une intégration reproductible en sept étapes, la découverte d’outils et la dérive de version, plus un aide-mémoire symptôme → action pour traiter MCP comme une chaîne d’approvisionnement auditable et non comme un script jetable.
Le guide d’installation répond à la présence durable du processus Gateway ; le guide sécurité à la surface d’écoute, aux jetons, à dmPolicy et au trafic sortant ; le texte liste blanche au premier réflexe quand l’enregistrement des outils ou les refus de permission bloquent. Ce texte vient après : il compare stdio (sous-processus local) et MCP HTTP distant côté exploitation, et indique quels journaux consulter pour handshake, timeouts et blocages.
Si au moins trois des sept points suivants vous concernent, ouvrez dans la fiche de revue une ligne de risque explicite « niveau exécution MCP » plutôt que de le noyer sous « on redémarre la Gateway ».
La ligne de commande ne tient qu’en dev : chemins npx, micro-version de Node et paquets globaux diffèrent entre shell interactif et environnement systemd — « ça marche en SSH, ça casse quand la Gateway démarre ».
Dépendances implicites au répertoire de travail : le serveur MCP suppose la racine d’un dépôt ; un HOME vide ou un montage en lecture seule fait échouer sans bruit.
Le MCP HTTP ne voit que l’URL, pas TLS : chaîne de certificats, SNI, certificats internes et networkPolicy mal combinés donnent un symptôme de « handshake infini ».
Cache d’outils périmé : après ajout/suppression côté serveur, le client garde un ancien schéma — échecs de validation de paramètres apparemment aléatoires.
Appels longs sans timeout : une API aval bloquée retient threads ou connexions côté Gateway jusqu’à un blocage global.
Sous-processus zombie : fermeture incorrecte d’un bout de tuyau stdio — le processus vit mais ne lit ni n’écrit, consomme des descripteurs et du CPU à vide.
Dérive de configuration non signée : plusieurs copies de openclaw.json modifiées à la main, sans trace validate/doctor — le diagnostic repose sur le bouche-à-oreille.
Une fois ces points dans le runbook, MCP peut suivre le même modèle que la CI : « ticket de changement + version de retour arrière ». Ensuite, un tableau aligne le coût d’exploitation de stdio et de HTTP pour éviter qu’en réunion un « le distant est plus simple » efface TLS et la gouvernance sortante.
Dans les pratiques plateforme 2026, la gouvernance des outils se lie souvent à « qui peut lancer des sous-processus en production » : stdio pousse la frontière vers l’utilisateur OS et les fichiers ; HTTP la pousse vers la politique réseau et les jetons d’identité. Il n’y a pas de gagnant absolu, seulement l’adéquation avec l’observabilité et la permanence dont vous disposez déjà.
Ce tableau sert d’alignement avec SRE, sécurité et métiers : ne comparez pas seulement la latence — intégrez identité, sortie, montée de version et isolement des pannes.
| Axe | stdio (sous-processus local) | MCP HTTP / SSE distant |
|---|---|---|
| Déploiement typique | Même machine ou même espace de noms conteneur que la Gateway | Service dédié, sidecar ou grappe interne |
| Identité et confiance | Utilisateur OS, droits fichiers, bac à sable optionnelle | mTLS, Bearer, auth en proxy inverse |
| Chemin de mise à jour | Verrou d’image/paquet, roll de la Gateway ou du paquet sous-processus | Blue/green indépendant, attention à la négociation de version de protocole |
| Observabilité | Code de sortie, stderr, fuite de fd, OOM | HTTP 5xx/429, pools de connexions, durée du handshake TLS |
| Isolement des pannes | Crash relançable par superviseur | Partition réseau pouvant ralentir plusieurs outils — besoin de disjoncteurs |
Industrialiser MCP, c’est transformer les appels d’outils en chaîne versionnée, bornée et réversible ; le transport ne fait que déplacer la complexité vers le noyau ou vers le réseau.
Si vous avez déjà resserré networkPolicy via le durcissement, l’ajout d’un MCP HTTP impose de repasser la liste blanche sortante ; en stdio, vérifiez que l’utilisateur de la Gateway peut exécuter les binaires attendus sans « chmod +x pour tout le monde par facilité ».
Ces étapes supposent une Gateway déjà démarrable ; si l’installation ou le démon manque, revenez au guide multi-OS et aux articles systemd/Docker en production.
Geler le runtime : notez la micro-version de Node, le gestionnaire de paquets et la version du serveur MCP ; préprod et prod doivent partager la même source.
Sonde stdio minimale : lancez une fois le MCP en commande non interactive sous le même utilisateur que la Gateway pour valider PATH et répertoire courant.
Fragment de configuration : enregistrez le serveur dans openclaw.json (ou le fichier documenté par votre version), avec un préfixe d’équipe pour éviter les collisions de noms.
Chaîne de validation : openclaw config:validate puis openclaw doctor ; toute différence va dans le ticket de changement.
Raccorder la liste blanche : selon le guide liste blanche, resserrer noms d’outils et espaces de noms au strict nécessaire.
Crochets d’observabilité : seuils CPU/mémoire pour les sous-processus, P95 pour le MCP HTTP, branchement sur votre pipeline de logs.
Exercice de retour arrière : conservez la dernière config valide et le digest d’image ; supprimer une entrée MCP doit pouvoir rétablir la ligne de base.
{
"mcpServers": {
"corp-files-stdio": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/var/lib/openclaw/mcp-data"],
"env": { "NODE_OPTIONS": "--max-old-space-size=512" }
},
"internal-api-http": {
"url": "https://mcp.internal.example/sse",
"headers": { "Authorization": "Bearer ${MCP_SERVICE_TOKEN}" }
}
}
}
Rappel : les clés réelles et l’imbrication suivent la doc de votre version OpenClaw ; l’exemple illustre la coexistence des entrées stdio et HTTP. Avant une montée majeure, relancez la validation et lisez les changements incompatibles des notes de version.
Les noms d’outils côté passerelle portent souvent un espace de noms ; un Gateway partagé entre environnements favorise les incidents « même nom, autre implémentation ». Préfixez explicitement dans la config (par ex. prod_ / stg_) et joignez au release une diff de la liste d’outils.
Lors d’un roll du MCP HTTP, privilégiez un schéma rétrocompatible ; en cas de rupture, mettez à jour la liste autorisée côté Gateway et grisez un sous-ensemble de sessions. Pour les serveurs stdio, surveillez l’ABI binaire et les bibliothèques dynamiques, surtout dans les images conteneur minimales.
Attention : n’utilisez pas en prod sur la Gateway un npx -y non épinglé qui tire la dernière version ; figez digest ou artefact interne, sinon la chaîne d’audit se rompt.
Tableau pour la première page d’astreinte ; le détail reste dans les journaux Gateway et la doc du serveur MCP.
| Observation | Vérifier en priorité | Action fréquente |
|---|---|---|
| Handshake immédiat en échec | Champs de version, en-têtes d’auth, chaîne TLS | Aligner la version de protocole ; corriger les certificats ou le SNI |
| Premier succès puis plus rien | Pool épuisé, sous-processus figé | Redémarrer côté MCP ; timeouts et disjoncteur |
| Outils manquants dans la liste | Cache, routage de version, liste blanche | Vider le cache ; recouper allowlist et règles de routage |
| Timeouts aléatoires | API aval, quotas, DNS | Timeouts en cascade ; journaliser l’identifiant de trace |
openclaw.json doit laisser dans le ticket un extrait de sortie de la commande de validation pour la post-mortem.Tout concentrer sur un portable de développement expose l’outil à sommeil, VPN instable et sessions bureau multi-utilisateur — disponibilité « parfois ». Exposer un MCP HTTP sur Internet sans TLS ni politique multiplie la surface d’attaque de la Gateway. Si votre équipe a besoin d’un macOS stable pour l’automatisation liée à la chaîne Apple (build mobile, signature, agents locaux couplés à MCP), déporter l’exécution vers des nœuds Mac distants contractuels clarifie souvent permissions et journaux par rapport aux machines personnelles. En croisant transport, gouvernance des sous-processus et modèle d’astreinte, la location de Mac Mini cloud NodeMini peut compléter le plan : avec les articles OpenClaw sur installation, sécurité et observabilité, vous séparez clairement « passerelle modèle + outils + exécution macOS ».
Vérifiez d’abord le PATH, le répertoire courant et les droits d’exécution pour le même utilisateur que la Gateway ; puis OOM, arrêts système et cache npm/npx. Pour la capacité et les références réseau, voir tarifs Mac mini cloud et centre d’aide cloud Mac.
Le guide liste blanche traite enregistrement, permissions et premier diagnostic connectivité ; celui-ci traite choix stdio/HTTP, cycle de vie et blocages. En revue, faites passer les deux tableaux ensemble.
Par la catégorie OpenClaw du blog (installation, systemd, Docker, sécurité, observabilité), puis revenez ici pour le niveau « exécution MCP ».