Ingénierie Webship

Connecter de manière sécurisée les agents d'IA au serveur MCP de Webship

Configurez le plan de contrôle MCP isolé de Webship avec TLS 1.3, un jeton porteur sécurisé, une liaison en boucle locale, un tunnel SSH, la validation de configuration et une liste de contrôle pratique pour la réponse aux incidents.

Publié 10 septembre 2026

# Connectez de manière sécurisée les agents d'IA au serveur MCP de Webship

Une connexion MCP à un serveur web n'est pas un widget de chat. C'est une interface d'opérations qui peut inspecter l'état de production, modifier la politique de routage et de sécurité, recharger les certificats, activer des versions statiques, coordonner les changements de flotte et installer une mise à jour Webship signée.

Traitez-le en conséquence : comme une API administrative privilégiée. La configuration Webship la plus sûre maintient l'écouteur MCP hors du plan de données public, le lie à la boucle locale, le protège avec TLS 1.3 et un jeton porteur puissant, et y accède via un tunnel SSH authentifié.

Ce guide construit cette configuration, explique pourquoi chaque limite existe et vous donne une liste de contrôle pour la faire fonctionner sans transformer la commodité en exposition.

Commencez par la frontière de confiance

Le trafic public de Webship et le trafic MCP utilisent des écouteurs séparés. Le plan de contrôle MCP est désactivé par défaut et ne partage jamais le listener HTTP, HTTP/2, HTTP/3 ou WebTransport normal. Lorsqu'il est activé, il sert MCP via un point de terminaison HTTP/1.1 TLS 1.3 dédié.

Un déploiement sécurisé comporte quatre contrôles indépendants :

Accessibilité réseau : le récepteur MCP se lie à 127.0.0.1, et non à une adresse publique ou LAN privée.
Identité du transport : le client vérifie un certificat émis par une AC qu'il reconnaît.
Authentification de l'application : chaque requête contient un jeton porteur unique et sécurisé.
Accès administratif : les opérateurs atteignent l'écouteur de boucle locale via un compte SSH authentifié et un tunnel.

Aucun de ces contrôles ne remplace un autre. TLS sans un chemin réseau privé expose toujours une surface d'authentification. Un tunnel sans vérification de certificat rend l'identité du point de terminaison ambiguë. Un jeton porteur dans un fichier lisible par tous n'est pas un secret.

Préparez le certificat et le jeton

Délivrez un certificat MCP dédié depuis votre CA interne. Pour le tunnel montré ci-dessous, incluez localhost et 127.0.0.1 dans les noms alternatifs du sujet du certificat, puis installez le CA émetteur dans le magasin de confiance de la machine cliente MCP. Ne résolvez pas une erreur de confiance avec une option TLS non sécurisée.

Créez un jeton unique avec au moins 32 octets ASCII imprimables et sans espace. Une valeur aléatoire de 32 octets encodée en hexadécimal vous donne 64 caractères sûrs :

umask 077
openssl rand -hex 32

Webship lit actuellement le jeton MCP directement à partir de la configuration TOML protégée ; token_file n'est pas pris en charge. Stockez le résultat dans un fichier de configuration lisible uniquement par le compte de service Webship et son groupe administratif. Ne placez pas le jeton dans une unité systemd, l'historique du shell, un ticket, un message de chat ou une invite envoyée à un modèle d'IA.

Sur un hôte Debian typique :

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

Adaptez l'utilisateur et le groupe du service à votre installation. La clé privée et la configuration doivent être lisibles par Webship, mais pas par des comptes non liés.

Activer l'écouteur isolé

Ajoutez cette section à la configuration Webship active :

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

Une liste allowed_ips vide n'ouvre pas le point de terminaison. Les clients en boucle locale restent autorisés par défaut. expose_remote = false rend la limite prévue explicite : si quelqu'un modifie plus tard listen pour une adresse non loopback, Webship rejette la configuration au lieu de publier silencieusement le plan de contrôle.

Webship rejette également un écouteur MCP activé sans TLS, sans jeton, avec un jeton court ou contenant des espaces, ou avec des chemins de certificat vides. Les jetons publics de remplacement sont rejetés avant une exposition distante.

Valider avant de redémarrer

Le lecteur MCP, l'identité TLS et les modifications de jeton reconstruisent le plan de contrôle, ils nécessitent donc un redémarrage du processus. Validez d'abord la configuration complète :

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

Confirmez que l'écouteur existe uniquement sur le loopback :

ss -ltn | grep '127.0.0.1:9443'

Ne pas ajouter le port 9443 aux règles de pare-feu publiques de l’hôte. L’étape suivante y accède via SSH.

Créer le tunnel privé

Depuis la station de travail de l'administrateur, redirigez un port local vers l'écouteur de boucle locale de Webship :

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

Le client MCP se connecte maintenant à https://localhost:19443/mcp. TCP atteint le serveur SSH, SSH transfère la connexion à l'hôte, et l'hôte ouvre la connexion finale à Webship sur le loopback. La fermeture de la session SSH supprime immédiatement ce chemin.

Utilisez l'authentification SSH basée sur des clés, limitez les administrateurs qui peuvent ouvrir le tunnel et appliquez vos contrôles d'accès habituels sur l'hôte. Si un hôte de saut est nécessaire, maintenez le listener MCP sur l'interface de loopback de l'hôte Webship et étendez le chemin SSH plutôt que d'élargir le listener.

Configurer le client MCP

Les formats de configuration des clients diffèrent, mais une entrée MCP HTTP typique ressemble à ceci :

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Utilisez le mécanisme de secret protégé du client lorsqu'il en possède un. Sinon, limitez la configuration du client au compte du système d'exploitation actuel. Le client HTTP — et non le modèle — doit joindre l'en-tête d'autorisation. Ne collez jamais le jeton en direct dans une conversation.

Gardez la vérification des certificats activée. Si le client rejette le certificat, réparez les noms alternatifs du sujet du certificat ou installez l'AC interne correcte. N'ajoutez pas de contournement permanent.

Rendre la première session en lecture seule

Après que le tunnel et le client sont connectés, commencez par la découverte et l'inspection :

Demandez tools/list ; sa réponse est le schéma d'argument autoritaire pour la version en cours.
Appelez webship.get_config et enregistrez la version de configuration actuelle.
Inspecter webship.reverse_proxy.get_status, webship.security.get_status, webship.ddos.get_status et webship.tls.get_status selon le cas.
Utilisez webship.policy.explain ou webship.security.simulate avant de modifier une politique.
Confirmez que la configuration renvoyée masque les jetons d'accès.

Ce n'est qu'ensuite qu'il faut tester une mutation dans un environnement non productif. Les mutations de configuration de Webship nécessitent l'ID de version actuel. Une écriture obsolète est rejetée au lieu d'écraser un changement plus récent. La politique candidate peut être vérifiée avec une vérification en ombre et des scénarios de laboratoire de trafic avant l'activation.

Webship refuse également certaines réductions de sécurité en direct sélectionnées. Une demande MCP ne peut pas désactiver un WAF actif, une couche DDoS, API Shield, un défi bot, une politique d'authentification en périphérie ou une couche d'en-tête de réponse. Les modifications liées au processus du listener, du protocole, du worker, du runtime et de l'authentification MCP nécessitent un redémarrage délibéré.

Ces gardes réduisent les erreurs ; ils ne rendent pas chaque action autorisée inoffensive. Le jeton offre une puissante interface de contrôle, y compris les opérations de mise à jour et de libération. Passez en revue les appels d'outils proposés exactement comme vous passeriez en revue une commande shell d'administrateur.

Si la liaison à distance est inévitable

Loopback plus SSH est la conception recommandée. Si votre environnement nécessite un écouteur sur un réseau privé, rendez l'exception explicite :

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

Conservez le bloc TLS de l'exemple précédent, utilisez un certificat correspondant au nom DNS privé et appliquez la même plage de sources aux pare-feu de l'hôte et du réseau. N'utilisez jamais 0.0.0.0/0 ou ::/0 comme liste blanche de commodité. N'oubliez pas qu'une liste blanche d'application voit l'adresse source qui atteint réellement Webship ; vérifiez le comportement lorsqu'un équilibreur de charge, une passerelle NAT ou une maillage de services se trouve devant.

L'exposition à distance augmente la valeur des journaux d'accès centralisés, des fenêtres opérationnelles courtes et de la rotation rapide. Elle n'est pas nécessaire simplement parce que le client MCP fonctionne sur une autre machine ; c'est exactement ce que le tunnel SSH résout.

Opérez le plan de contrôle délibérément

Utilisez cette liste de contrôle pour la production :

Gardez MCP désactivé là où aucun agent ou opérateur n'en a besoin.
Se lier à la boucle locale et utiliser un tunnel SSH par défaut.
Utilisez une identité TLS dédiée et gardez la vérification des certificats activée.
Générez un jeton porteur unique pour chaque environnement Webship.
Protégez le TOML, la configuration du client, la clé TLS et les clés SSH avec les permissions du système de fichiers.
Séparez les identifiants de développement, de test et de production.
Commencez les sessions avec des outils de simulation de statut et de politique avant les mutations.
Conserver et examiner les événements d'audit de sécurité de Webship.
Faites tourner le jeton et redémarrez Webship après une exposition suspectée.
Fermez les tunnels lorsque la session administrative se termine.

Pour la réponse aux incidents, fermez les tunnels actifs, restreignez le compte SSH, remplacez le jeton MCP dans le TOML protégé, redémarrez Webship et examinez les enregistrements récents des audits de sécurité et des versions de configuration. Si la clé privée TLS peut être exposée, émettez un nouveau certificat et une nouvelle clé dans le cadre du même redémarrage. Testez ensuite l'ancien jeton et confirmez qu'il est rejeté.

Un plan de contrôle doit rester un plan de contrôle

MCP est utile car un agent peut inspecter l'état réel et appliquer des modifications validées sans passer ces opérations par le chemin de requête public. Cet avantage disparaît si le récepteur de contrôle devient un autre point de terminaison Internet.

Gardez la frontière simple : un écouteur séparé, une accessibilité en boucle locale, TLS vérifié, une seule information d’identification de transport protégée, un tunnel authentifié, des changements vérifiés selon la version, et un processus de révision humaine pour les opérations puissantes. Webship fournit le protocole et les dispositifs de sécurité ; l’opérateur décide qui peut y accéder.

Ce guide est basé sur la documentation de l'opérateur Webship 1.3.1, les exemples de configuration fournis, la validation MCP et le code de transport, les protections de configuration à l'exécution et le catalogue d'outils. Consultez la documentation actuelle Webship et la réponse du serveur en cours d'exécution tools/list avant de l'appliquer à une autre version.