Connecter Claude à son agent Hermes : le guide complet du pont MCP

À la fin de ce guide, vous écrivez à votre agent Hermes depuis Claude (web, mobile ou Desktop), exactement comme vous le faites sur Telegram. Ni plus, ni moins : Claude ne peut rien faire que vous ne pourriez faire vous-même dans Telegram.

La démonstration en vidéo :

La vidéo est hébergée par YouTube : cliquer charge le lecteur YouTube. Voir la vidéo sur YouTube

Le « pont » est un petit serveur MCP (le protocole que Claude utilise pour parler à des outils extérieurs). Il tourne sur le même serveur que Hermes et n'expose qu'un seul outil : parler_a_hermes. Claude l'appelle, le pont transmet le message à Hermes en local, et renvoie la réponse.

Trois choses rendent ce montage sûr :

• Un seul compte autorisé. La connexion passe par un compte Codeberg dédié. Tout autre compte est refusé, même s'il réussit à se connecter.
• Une seule porte d'entrée. Le serveur n'accepte les appels que depuis les adresses IP d'Anthropic, sauf les trois pages de connexion que votre navigateur doit voir.
• Aucune action sensible. Si Hermes demande une approbation (supprimer un fichier, lancer une commande risquée), le pont répond automatiquement non. Ces actions-là se font uniquement depuis Telegram.

Tout ce qui est dans le cadre pointillé tourne sur votre serveur. Seul Caddy est visible depuis Internet ; le pont et l'API Hermes n'écoutent qu'en local.

Avant de commencer : êtes-vous prêt ?

Ce guide s'adresse à des personnes à l'aise avec un terminal. Si ce n'est pas encore votre cas, pas d'inquiétude : commencez par vous familiariser avec la connexion SSH à un serveur et l'édition d'un fichier, puis revenez ici. Et si vous préférez être accompagné pour la mise en place, écrivez-moi.

Vous devez déjà avoir :

• ☐Un serveur (VPS) sous Debian 12 ou Ubuntu 24.04, accessible en SSH par clé (pas par mot de passe).
• ☐Hermes Agent installé et fonctionnel sur ce serveur (vous lui parlez déjà sur Telegram).
• ☐Un nom de domaine dont vous gérez les DNS (chez OVH, Gandi, Cloudflare, peu importe).
• ☐Un compte Claude qui permet d'ajouter un connecteur personnalisé.
• ☐Un gestionnaire de mots de passe (Bitwarden, Vaultwarden, KeePassXC) pour ranger les secrets.

Ce qu'il faut savoir faire : vous connecter en SSH, éditer un fichier avec un éditeur en terminal (vim ou nano), copier-coller une commande et lire son résultat.

Temps : comptez une demi-journée la première fois, tests compris. Coût : rien de plus que ce que vous payez déjà. Le pont tourne sur le serveur de Hermes, Codeberg est gratuit, le certificat HTTPS aussi.

Les mots à connaître

Les 7 règles de sécurité non négociables

1. Snapshot d'abord. Prenez un instantané du serveur chez votre hébergeur avant de toucher quoi que ce soit.
2. Jamais de secret dans un chat. Ni dans Claude, ni dans Telegram, ni dans une capture d'écran. Les secrets se tapent dans votre session SSH, avec une saisie masquée (voir étape 5).
3. Un compte Codeberg dédié et vide. Codeberg ne sait pas limiter ce qu'une application peut faire : l'autorisation donne lecture et écriture sur tout le compte. Ne connectez jamais votre compte principal.
4. Un seul sub autorisé. Le pont vérifie l'identifiant du compte à la connexion, à chaque requête et dans l'outil. N'importe qui peut créer un compte Codeberg ; seul le vôtre doit passer.
5. Hermes reste en local. L'API Hermes (8642) et le pont (8765) écoutent sur 127.0.0.1. Seuls les ports 22, 80 et 443 sont ouverts.
6. Aucune approbation à distance. Le pont refuse toute action sensible. Vous les refaites depuis Telegram.
7. Rien en « toujours autoriser ». Si vous faites l'installation avec Claude Code sur le serveur, validez les commandes une par une. Jamais de mode automatique.

L'installation, étape par étape

Dans tout le guide, remplacez ces trois valeurs par les vôtres :

Le code du pont (server.py, requirements.txt, .env.example et les modèles de configuration) sera publié sur Codeberg sous licence libre dans les prochains jours.

Étape 0 : le filet de sécurité

Dans la console de votre hébergeur, prenez un snapshot du serveur et nommez-le avant-pont-mcp. En cas de casse, le retour en arrière prend deux clics. Puis sauvegardez le fichier de configuration de Hermes :

sudo cp ~hermes/.hermes/.env ~hermes/.hermes/.env.bak-$(date +%F)

Adaptez le chemin si Hermes tourne sous un autre utilisateur que hermes.

Étape 1 : ouvrir l'API de Hermes (en local seulement)

Hermes a une API qui permet à un programme de lui parler. On l'active, en la gardant invisible depuis Internet. Générez une clé et ajoutez les 4 lignes sans jamais l'afficher :

KEY=$(openssl rand -hex 32)
printf 'API_SERVER_ENABLED=true\nAPI_SERVER_HOST=127.0.0.1\nAPI_SERVER_PORT=8642\nAPI_SERVER_KEY=%s\n' "$KEY" | sudo tee -a ~hermes/.hermes/.env >/dev/null
unset KEY

Relancez Hermes, puis vérifiez que l'API répond :

sudo systemctl restart hermes-gateway
curl -s http://127.0.0.1:8642/health

Vous devez voir {"status": "ok"}. Le nom du service (hermes-gateway) peut différer selon votre installation : systemctl list-units | grep -i hermes vous le donne.

Étape 2 : le sous-domaine

Chez votre registrar, ajoutez un enregistrement DNS de type A : nom mcp, valeur IP_DU_SERVEUR. Attendez quelques minutes, puis vérifiez depuis votre ordinateur :

dig +short mcp.mondomaine.fr

La commande doit renvoyer l'IP de votre serveur.

Étape 3 : le pare-feu (les deux !)

Il y a souvent deux pare-feu : celui du serveur (ufw) et celui de l'hébergeur (dans sa console web). Les deux doivent laisser passer 22, 80 et 443, et rien d'autre. Sur le serveur :

sudo apt install ufw
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Chez l'hébergeur (Hetzner : Firewalls dans la console Cloud), créez une règle entrante pour 22, 80, 443 en TCP, plus ICMP pour pouvoir faire un ping. C'est l'oubli classique : tant que 80 et 443 n'y sont pas, le certificat HTTPS échoue.

Étape 4 : le compte Codeberg dédié et l'application OAuth

Le pont vous demandera de vous connecter avec Codeberg. On crée un compte qui ne sert qu'à ça.

1. Créez un nouveau compte sur codeberg.org (par exemple mon-compte-hermes), avec une adresse email qui vous appartient.
2. Activez la double authentification (TOTP) dans ses paramètres de sécurité. Rangez l'identifiant, le mot de passe et les codes de récupération dans votre gestionnaire de mots de passe. Ne faites aucune capture d'écran de ces codes.
3. Dans les paramètres du compte, section Applications, créez une application OAuth2 : nom mcp-hermes ; URI de redirection https://mcp.mondomaine.fr/auth/callback ; client confidentiel coché.
4. Codeberg affiche un Client ID et un Client secret. Le secret n'est montré qu'une fois : copiez-le directement dans votre gestionnaire de mots de passe.
5. Récupérez le sub, l'identifiant numérique du compte dédié (commande ci-dessous).

curl -s https://codeberg.org/api/v1/users/mon-compte-hermes | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])'

Notez ce nombre : c'est le seul compte que le pont acceptera. Ce n'est pas un secret, mais c'est la clé de voûte du filtrage.

Étape 5 : installer le pont

Le pont tourne sous son propre utilisateur système, sans shell et sans droits, dans /opt/mcp-hermes.

Remplacez <URL_DU_DÉPÔT> par l'adresse du dépôt Codeberg dès sa publication.

sudo apt install python3-venv git
sudo useradd --system --home-dir /opt/mcp-hermes --shell /usr/sbin/nologin mcp-hermes
sudo git clone <URL_DU_DÉPÔT> /opt/mcp-hermes
sudo mkdir -p /opt/mcp-hermes/data
sudo python3 -m venv /opt/mcp-hermes/.venv
sudo /opt/mcp-hermes/.venv/bin/pip install -r /opt/mcp-hermes/requirements.txt

Créez la configuration à partir du modèle, puis éditez les valeurs qui ne sont pas secrètes (domaine, Client ID, sub) :

sudo cp /opt/mcp-hermes/.env.example /opt/mcp-hermes/.env
sudo vim /opt/mcp-hermes/.env

Dans vim : i pour écrire, Échap puis :wq pour enregistrer et quitter. Les noms exacts des variables sont dans .env.example, chacune y est commentée.

Les secrets, eux, ne passent jamais par l'écran. Pour le Client secret Codeberg, collez-le dans une saisie masquée :

read -rsp "Client secret Codeberg : " S; echo
echo "CODEBERG_CLIENT_SECRET=$S" | sudo tee -a /opt/mcp-hermes/.env >/dev/null
echo "Longueur : ${#S} caractères"; unset S

Rien ne s'affiche au moment de coller : c'est normal. La longueur permet de vérifier que quelque chose de plausible a bien été collé.

Recopiez la clé de l'API Hermes dans le pont, toujours sans l'afficher, et générez la clé de signature des jetons :

sudo grep '^API_SERVER_KEY=' ~hermes/.hermes/.env | sed 's/^API_SERVER_KEY=/HERMES_API_KEY=/' | sudo tee -a /opt/mcp-hermes/.env >/dev/null
echo "JWT_SIGNING_KEY=$(openssl rand -hex 32)" | sudo tee -a /opt/mcp-hermes/.env >/dev/null

Verrouillez le dossier :

sudo chown -R mcp-hermes:mcp-hermes /opt/mcp-hermes
sudo chmod 600 /opt/mcp-hermes/.env

Vérifiez que toutes les variables sont là, en n'affichant que leurs noms :

sudo cut -d= -f1 /opt/mcp-hermes/.env | grep -v '^#'

Étape 6 : le service systemd

Copiez le modèle fourni dans le dépôt, puis activez-le :

sudo cp /opt/mcp-hermes/deploy/mcp-hermes.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-hermes
sudo systemctl status mcp-hermes

Le statut doit afficher active (running). Le modèle est durci : le pont ne peut écrire que dans data/, ne voit pas les dossiers personnels, et n'écoute que sur 127.0.0.1:8765. Vous pouvez mesurer le durcissement avec systemd-analyze security mcp-hermes (plus le score est bas, mieux c'est).

Si le statut est en erreur, lisez les dernières lignes du journal :

sudo journalctl -u mcp-hermes -n 50 --no-pager

Étape 7 : Caddy, le portier HTTPS

Caddy obtient le certificat Let's Encrypt tout seul et filtre les visiteurs. La règle : tout le site est réservé aux serveurs d'Anthropic (plage 160.79.104.0/21), sauf les trois pages de connexion que votre navigateur doit pouvoir afficher.

sudo apt install caddy
sudo vim /etc/caddy/Caddyfile

Contenu (remplacez le domaine) :

mcp.mondomaine.fr {
    log {
        output file /var/log/caddy/mcp-access.log
    }

    @connexion path /authorize /consent /auth/callback
    handle @connexion {
        reverse_proxy 127.0.0.1:8765
    }

    @anthropic remote_ip 160.79.104.0/21
    handle @anthropic {
        reverse_proxy 127.0.0.1:8765
    }

    handle {
        respond 403
    }
}

Vérifiez et rechargez :

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Depuis votre ordinateur, https://mcp.mondomaine.fr/mcp doit répondre 403 : c'est le signe que le filtre fonctionne. Vérifiez la plage d'adresses à jour dans la documentation des connecteurs Claude : si Anthropic la change, votre connecteur cessera de fonctionner.

Étape 8 : brancher le pont dans Claude

Dans les réglages de Claude, ajoutez un connecteur personnalisé avec l'URL https://mcp.mondomaine.fr/mcp.

Claude ouvre une page de connexion Codeberg. Connectez-vous avec le compte dédié (pas votre compte principal), validez la page de consentement, et c'est branché. Dans une conversation, activez le connecteur dans le menu des outils, puis écrivez : « Demande à Hermes qui il est. »

Le menu exact des réglages évolue : en cas de doute, cherchez « connecteur personnalisé » sur support.claude.com.

Les tests à faire avant de vous en servir

Un pont qui « marche » n'est pas forcément un pont sûr. Cochez chaque ligne.

• ☐Hermes répond depuis Claude. « Demande à Hermes qui il est » renvoie une réponse.
• ☐Les fils sont séparés. Le message envoyé depuis Claude n'apparaît pas dans votre fil Telegram.
• ☐Un autre compte est refusé. Créez un compte Codeberg jetable, essayez de connecter le connecteur avec : la connexion doit échouer. Supprimez ensuite ce compte.
• ☐Votre compte principal est refusé. Même test. Puis, dans les paramètres de votre compte principal (Applications autorisées), révoquez mcp-hermes s'il y apparaît.
• ☐Les ports internes sont fermés. Depuis votre ordinateur (pas le serveur), les deux commandes ci-dessous doivent échouer (timeout ou refus).
• ☐Le site est fermé aux curieux. curl -I https://mcp.mondomaine.fr/mcp depuis chez vous renvoie 403.
• ☐Les actions sensibles sont bloquées. Demandez depuis Claude une action que Hermes soumet à approbation : la réponse doit indiquer un refus, et rien ne doit se passer.
• ☐Aucun secret dans les logs. Parcourez les journaux du pont et de Caddy : vous ne devez y voir ni contenu de message ni clé.

nc -zv -w 3 IP_DU_SERVEUR 8642
nc -zv -w 3 IP_DU_SERVEUR 8765

sudo journalctl -u mcp-hermes -n 50 --no-pager
sudo tail -n 50 /var/log/caddy/mcp-access.log

Au quotidien

Comment ça se passe dans une conversation. Claude envoie votre message à Hermes et attend jusqu'à 90 secondes. Si Hermes travaille plus longtemps, Claude reçoit « Hermes travaille encore » avec un numéro de tâche, et va chercher la réponse plus tard avec ce numéro. Le message n'est jamais renvoyé deux fois, pour ne pas faire exécuter deux fois la même chose.

Repartir de zéro. La conversation avec Hermes est continue. Pour changer de sujet proprement, demandez à Claude de démarrer un nouveau fil avec Hermes.

Ce que le pont ne fait pas :

• Hermes ne peut pas écrire à Claude en premier. Ses rapports automatiques restent sur Telegram.
• Les actions qui demandent votre approbation se refont depuis Telegram.
• Les très longues réponses (au-delà d'environ 80 000 caractères) sont tronquées.

Maintenance :

• Après une mise à jour de FastMCP (la bibliothèque du pont), refaites les tests « autre compte refusé » et « compte dédié accepté ».
• Le certificat HTTPS se renouvelle tout seul. Rien à faire.
• Gardez le snapshot avant-pont-mcp jusqu'à ce que tout tourne depuis quelques semaines.

Quand ça ne marche pas

Les pièges dans lesquels je suis tombé

• Coller au mauvais endroit. J'ai collé un prompt d'installation dans Telegram au lieu du terminal. Vérifiez toujours la fenêtre active avant de coller.
• Un secret sur une capture d'écran. Les codes de récupération de la double authentification étaient visibles. Je les ai régénérés. Une capture qui montre un secret, c'est un secret à changer.
• Le pare-feu cloud oublié. ufw était bon, mais le pare-feu Hetzner bloquait 80 et 443. Le certificat échouait sans message clair.
• Croire aux scopes de Codeberg. Demander seulement openid profile ne limite rien. D'où le compte dédié.
• Le filtre IP à l'envers. Mon premier réflexe bloquait aussi les pages de connexion. Votre navigateur doit voir /authorize, /consent et /auth/callback ; tout le reste est réservé à Anthropic.
• Confondre application et utilisateur. Le Client ID et le secret identifient le pont, pas la personne qui se connecte. C'est le sub qui dit qui a le droit d'entrer.
• Tout empiler d'un coup. Testez chaque couche avant d'ajouter la suivante : l'API Hermes seule, puis le pont seul, puis Caddy, puis l'authentification.
• sudo avec Claude Code. Si vous faites l'installation avec Claude Code sur le serveur, il ne peut pas taper votre mot de passe. J'ai créé une règle sudo temporaire, validé chaque commande à la main, puis supprimé la règle à la fin. Ne l'oubliez pas.

Questions fréquentes

Pourquoi pas directement l'API de Hermes exposée sur Internet ? Parce qu'elle donne accès à un terminal, protégé par une seule clé. Le pont ajoute la connexion par compte, le filtrage IP, le refus des approbations et la limitation du nombre d'appels.

Pourquoi Codeberg et pas Google ou GitHub ? Par choix de souveraineté : Codeberg est une association européenne à but non lucratif. Le principe reste le même avec un autre fournisseur OpenID Connect.

Est-ce que Claude peut tout faire sur mon serveur ? Non. Il parle à Hermes comme vous sur Telegram, avec les mêmes limites, et sans pouvoir approuver d'action sensible.

Ça marche sur mobile ? Oui : une fois ajouté, le connecteur est disponible sur claude.ai, l'application mobile et l'application Desktop.

Je peux l'adapter à un autre agent que Hermes ? Oui, il suffit de remplacer la partie qui appelle l'API de Hermes. Le reste (authentification, filtrage, service) ne change pas.

Besoin d'aide ?

Ce guide et le code sont fournis tels quels, sous licence libre. Si vous bloquez sur une étape, écrivez-moi via le formulaire de contact en précisant « guide pont MCP », l'étape concernée, votre système et le message d'erreur exact (sans aucun secret dedans).

Si vous préférez que ce type de montage soit installé et maintenu pour vous, découvrez notre offre VPS Linux managé ou écrivez-nous directement.

Sources

• Vidéo de démonstration
• Documentation de l'API Hermes Agent
• FastMCP : OIDC Proxy
• Connecteurs Claude : authentification et adresses IP