Le symptôme

Je viens de finaliser un endpoint webhook dans le hugo-mcp-proxy qui recevra des notifications de GitHub à chaque push sur le repo arleo.eu. Implementation propre : HMAC-SHA256, rate limiting, IPAddressAllow GitHub ranges côté systemd.

Test fonctionnel depuis un client externe :

$ curl -X POST https://mcp-hugo.arleo.eu/webhook/test \
    -H "Content-Type: application/json" \
    -d '{"test": true}'

Réponse : 403 Forbidden.

Curieux. Le service tourne, l’IP source de mon test est dans le whitelist, le HMAC est correct. Pourquoi 403 ?

Investigation côté serveur

Logs nginx côté NUC :

$ sudo tail -100 /var/log/nginx/mcp-hugo.access.log | grep webhook

Vide. Aucune requête n’arrive sur nginx.

Logs mcp-oauth-proxy :

$ sudo journalctl -u mcp-oauth-proxy -n 100 | grep webhook

Vide aussi. La requête n’arrive pas jusqu’au service.

Soit elle est bloquée par firewall avant nginx (CrowdSec ou ufw), soit en amont par Cloudflare.

La vérité côté Cloudflare

Le bug

mcp-installer est un script bash que j’ai écrit pour automatiser l’installation du mcp-oauth-proxy (FastAPI + nginx + systemd) sur un nouveau host. Workflow standard : clone, run, c’est tout.

Sauf qu’en relançant le script sur un host déjà installé (par exemple pour mettre à jour la version), j’ai découvert un bug d’idempotence : tous les secrets étaient régénérés.

$ sudo ./install.sh
[+] Generating MCP_TOKEN...
[+] Generating CLIENT_ID...
[+] Generating CLIENT_SECRET...
[+] Generating TOKEN_SECRET...
[+] Writing /etc/mcp-oauth-proxy/.env...

Si tu as déjà un .env avec des tokens en service, l’installer les écrase. Tous les clients OAuth déjà enregistrés (Claude.ai dans mon cas) se retrouvent avec des credentials invalides. La connexion casse.

Pourquoi c’est arrivé

Le script utilisait cette logique :

MCP_TOKEN=$(openssl rand -hex 32)
CLIENT_ID=$(openssl rand -hex 16)
CLIENT_SECRET=$(openssl rand -hex 32)
TOKEN_SECRET=$(openssl rand -hex 32)

cat > /etc/mcp-oauth-proxy/.env <<EOF
MCP_TOKEN=$MCP_TOKEN
CLIENT_ID=$CLIENT_ID
CLIENT_SECRET=$CLIENT_SECRET
TOKEN_SECRET=$TOKEN_SECRET
EOF

Le pattern « génère puis écris » est correct pour une première install. Mais en relance, il ignore complètement le .env existant.

C’est l’erreur classique : l’auteur (moi) a testé le script uniquement sur un host fresh. Le mode “réinstall sur host existant” n’a jamais été testé.

Reproduction du bug

$ sudo ./install.sh
[OK] Installation complete
$ cat /etc/mcp-oauth-proxy/.env | head -1
MCP_TOKEN=a7f3e9d2c4b8a1...

$ sudo ./install.sh
[OK] Installation complete
$ cat /etc/mcp-oauth-proxy/.env | head -1
MCP_TOKEN=8c2f6a1b9e4d7c...   ← DIFFÉRENT

Test reproductible en 30 secondes. C’est presque comique que je ne l’aie pas vu plus tôt.

La leçon : “idempotent” est un contrat, pas un espoir

Un script d’installation doit être idempotent par défaut. C’est-à-dire : ./install.sh 1 fois, 2 fois, 5 fois → le système est dans le même état stable.

J’avais ce contrat dans ma tête. Je ne l’avais pas dans le code.

Le fix : pre-flight checks + force flag explicite

Contexte

J’ai mis en production un Hugo MCP Server (FastAPI, 7 tools) qui me permet d’éditer arleo.eu depuis Claude.ai. Architecture : claude.ai → mcp-oauth-proxy NUC → hugo-mcp-proxy NUC → MCP server VM.