@imenam/mcp-http-gateway 2.0.14 → 2.0.16

package/README.md

@@ -1,512 +1,707 @@
-# MCP HTTP Gateway
-
-Serveur HTTP qui expose n'importe quel serveur MCP (Model Context Protocol) en tant qu'API REST, sans modifier les MCPs eux-mêmes. Conçu pour permettre à des agents ou applications ne supportant pas nativement le protocole MCP de communiquer avec l'écosystème MCP via de simples requêtes HTTP.
-
-## Fonctionnement
-
-Chaque MCP tourne en tant que processus enfant (transport stdio). Le gateway s'y connecte via le SDK MCP officiel et expose ses outils sur des routes HTTP configurables.
-
-```
-Agent / App externe
-       │
-       │  HTTP
-       ▼
-MCP HTTP Gateway (port 3500)
-       │
-       │  stdio (SDK MCP)
-       ├──▶ mcp-documentor  (/documentor)
-       ├──▶ mcp-raindrop     (/raindrop)
-       └──▶ ...
-```
-
-## Installation
-
-**En tant que CLI globale :**
-
-```bash
-npm install -g @imenam/mcp-http-gateway
-```
-
-**Via npx (sans installation) :**
-
-```bash
-npx @imenam/mcp-http-gateway
-```
-
-**En dépendance locale d'un projet :**
-
-```bash
-npm install @imenam/mcp-http-gateway
-```
-
-## Configuration
-
-### `.env`
-
-```env
-GATEWAY_PORT=3500
-GATEWAY_CONFIG_DIR=./config
-```
-
-| Variable | Défaut | Description |
-|---|---|---|
-| `GATEWAY_PORT` | `3500` | Port HTTP du gateway |
-| `GATEWAY_CONFIG_DIR` | `./config` (relatif au cwd) | Dossier contenant `mcp-servers.json` |
-| `GATEWAY_BODY_LIMIT` | `32mb` | Taille maximale du corps d'une requête. Le défaut d'express (100 ko) ne suffit pas dès qu'un appel d'outil porte le contenu d'un fichier en base64 ; au-delà de cette limite, la réponse est un `413`. |
-
-### `mcp-servers.json`
-
-À créer dans le dossier de configuration (`./config` par défaut, ou le chemin pointé par `GATEWAY_CONFIG_DIR`). Un fichier `config/mcp-servers.example.json` est fourni comme point de départ.
-
-Même format que la configuration `mcpServers` de Cursor. Ajouter `MCP_SERVER_ROUTE` dans `env` pour définir la route HTTP du MCP, et `description` pour la documentation.
-
-```json
-{
-  "mcpServers": {
-    "mon-mcp": {
-      "command": "node",
-      "args": ["/chemin/vers/dist/index.js"],
-      "description": "Description courte du MCP",
-      "env": {
-        "MA_VARIABLE": "valeur",
-        "MCP_SERVER_ROUTE": "/ma-route"
-      }
-    }
-  }
-}
-```
-
-> Un MCP sans `MCP_SERVER_ROUTE` est ignoré au démarrage.
-
-## Démarrage
-
-```bash
-npm start
-```
-
-Le gateway connecte chaque MCP configuré et démarre le serveur HTTP. Les MCPs en échec au démarrage sont ignorés sans bloquer les autres.
-
-## Routes
-
-### `GET /mcps`
-
-Retourne la liste des MCPs connectés avec leur route, description et instructions d'utilisation (format Markdown).
-
-```bash
-curl http://localhost:3500/mcps
-```
-
----
-
-### `GET /{route}/tools`
-
-Liste les outils disponibles d'un MCP avec leur nom, description et schéma d'arguments.
-
-```bash
-curl http://localhost:3500/documentor/tools
-```
-
----
-
-### `POST /{route}/tools/:toolName`
-
-Appelle un outil du MCP. Les arguments sont passés dans le body JSON.
-
-```bash
-curl -X POST http://localhost:3500/documentor/tools/list_projects -H "Content-Type: application/json" -d '{}'
-```
-
-```bash
-curl -X POST http://localhost:3500/documentor/tools/get_doc -H "Content-Type: application/json" -d '{"id":"mon-doc-id"}'
-```
-
-#### Réponse
-
-La réponse est le format brut du protocole MCP — un tableau `content` de blocs typés :
-
-```json
-{
-  "content": [
-    { "type": "text", "text": "Résultat de l'outil..." }
-  ]
-}
-```
-
-Pour extraire le texte directement avec `jq` :
-
-```bash
-curl -s -X POST http://localhost:3500/documentor/tools/list_projects -H "Content-Type: application/json" -d '{}' | jq -r '.content[0].text'
-```
-
-## Mode MCP
-
-Le gateway peut également démarrer en tant que **serveur MCP** (transport stdio). Dans ce mode, il se connecte à une instance du gateway HTTP et expose ses outils comme des outils MCP natifs.
-
-### Cas d'usage : agent dans un conteneur Docker
-
-Le gateway HTTP tourne **hors du conteneur**, avec accès aux MCPs et leurs clés sensibles. L'agent dans le conteneur reçoit uniquement le gateway en mode MCP — aucune clé ne lui est injectée.
-
-```
-[Agent dans conteneur]
-        │  stdio (MCP)
-        ▼
-[mcp-http-gateway --mcp]  ←── GATEWAY_URL
-        │  HTTP
-        ▼
-[mcp-http-gateway hors conteneur]
-        │  stdio
-        ▼
-[MCPs réels (clés sensibles)]
-```
-
-### Démarrage
-
-```bash
-GATEWAY_URL=http://host.docker.internal:3500 npx @imenam/mcp-http-gateway --mcp
-```
-
-### Configuration dans le conteneur
-
-```json
-{
-  "mcpServers": {
-    "gateway": {
-      "command": "npx",
-      "args": ["@imenam/mcp-http-gateway", "--mcp"],
-      "env": {
-        "GATEWAY_URL": "http://host.docker.internal:3500"
-      }
-    }
-  }
-}
-```
-
-> `host.docker.internal` est l'adresse de l'hôte depuis un conteneur Docker.
-
-### Variables d'environnement du mode `--mcp`
-
-| Variable | Requis | Description |
-|---|---|---|
-| `GATEWAY_URL` | oui | Base HTTP du gateway à relayer, sans barre finale. Le relais compose lui-même ses routes REST (`/startup-exposition`, `/mcp-definitions`, `/{route}/tools`, `/{route}/tools/{outil}`) : **ne pas** y ajouter `/mcp`. |
-| `GATEWAY_TOKEN` | non | Token porteur. S'il est défini, **tous** les appels sortants du relais portent `Authorization: Bearer <token>`. Absent, aucun en-tête n'est ajouté — le comportement est exactement celui des versions antérieures. |
-| `GATEWAY_INLINE_ROOTS` | non | Dossiers depuis lesquels le relais peut lire un fichier et en transmettre le contenu (cf. [Fichiers locaux](#fichiers-locaux--lagent-nomme-le-relais-lit)). **Non renseignée, tout appel à un outil qui déclare la paire échoue explicitement.** Séparateur : `;` sous Windows, `:` ailleurs. |
-| `GATEWAY_INLINE_EXTENSIONS` | non | Extensions autorisées à la lecture, séparées par des virgules. Défaut : `*` (toutes) — les racines restent le vrai garde-fou. |
-| `GATEWAY_INLINE_MAX_BYTES` | non | Taille maximale d'un fichier transmis, en octets, dans les deux sens. Défaut : `8388608` (8 Mio). |
-| `GATEWAY_INLINE_WRITE_ROOTS` | non | Dossiers dans lesquels le relais peut écrire un fichier renvoyé par un MCP (cf. [Fichiers reçus](#fichiers-reçus--le-mcp-produit-le-relais-écrit)). **Non renseignée, la fonction est désactivée** et tout outil qui la réclame échoue explicitement. Séparateur : `;` sous Windows, `:` ailleurs. |
-| `GATEWAY_INLINE_WRITE_EXTENSIONS` | non | Extensions autorisées à l'écriture, séparées par des virgules. Défaut : `*` (toutes) — les racines restent le vrai garde-fou. |
-
-> Ces deux variables sont lues dans l'environnement du process. Le relais fait
-> `import 'dotenv/config'` : un fichier `.env` présent dans le **répertoire courant de
-> l'agent** peut donc les fournir. dotenv n'écrase jamais une variable déjà définie —
-> le bloc `env` de la configuration MCP l'emporte toujours.
-
-### Derrière un frontal qui authentifie
-
-Quand le gateway n'est pas joint en direct mais à travers un frontal qui exige un token
-porteur (hub [`mcp-gateway-manager`](https://github.com/Matthieu-Pesnot-Pin), reverse-proxy
-maison…), `GATEWAY_TOKEN` est ce que le relais présente à chaque requête :
-
-```json
-{
-  "mcpServers": {
-    "gateway": {
-      "command": "npx",
-      "args": ["@imenam/mcp-http-gateway", "--mcp"],
-      "env": {
-        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
-        "GATEWAY_TOKEN": "…"
-      }
-    }
-  }
-}
-```
-
-Un refus (`401`/`403`) est rapporté à l'agent en clair — token manquant, ou token invalide —
-plutôt qu'en `HTTP 401` nu. Le token lui-même n'est **jamais** journalisé, pas même tronqué.
-
-### Outils exposés
-
-Le mode MCP expose 3 outils qui reflètent directement les routes du gateway :
-
-| Outil | Description |
-|---|---|
-| `list_mcps` | Liste les MCPs disponibles avec leur route et description |
-| `list_tools` | Liste les outils d'un MCP donné (`route` requis) |
-| `call_tool` | Appelle un outil (`route`, `tool_name`, `arguments`) |
-
-L'agent découvre d'abord les MCPs disponibles, explore les outils d'un MCP si besoin, puis appelle l'outil voulu.
-
-### Fichiers locaux : l'agent nomme, le relais lit
-
-Le relais tourne sur la machine de l'**agent** ; les MCP, eux, tournent sur la machine du
-**gateway**. Un chemin de fichier transmis tel quel ne veut donc rien dire à l'arrivée : le
-MCP le cherche chez lui et répond « fichier introuvable ».
-
-Le relais sait résoudre ça. Dès qu'un outil distant déclare une paire de paramètres
-`<x>_path` / `<x>_content`, le relais **lit le fichier localement, l'encode en base64 et
-envoie le contenu** dans `<x>_content` (plus le nom dans `<x>_name`, si le schéma le
-prévoit). Le paramètre `file_path` reste la seule chose que l'agent fournit : les
-paramètres que le relais remplit sont **retirés du schéma** publié à l'agent, par
-`tools/list` comme par `list_tools`. L'agent n'a donc aucun arbitrage à faire, et aucune
-occasion d'envoyer un chemin qui ne serait pas lisible à l'arrivée.
-
-Un outil qui ne déclare pas cette paire n'est jamais concerné : un `output_path` seul reste
-un chemin, interprété côté gateway comme avant.
-
-`<x>_path` est obligatoire pour l'agent si, et seulement si, le MCP le déclare obligatoire.
-Un outil qui le laisse optionnel accepte sa donnée autrement — un texte passé en ligne, par
-exemple. Sans `<x>_path`, le relais ne lit rien et transmet l'appel tel quel.
-
-**Le chemin vient de l'agent : il n'est pas digne de confiance.** La fonction est donc
-fermée par défaut et s'ouvre dossier par dossier :
-
-```json
-{
-  "mcpServers": {
-    "gateway": {
-      "command": "npx",
-      "args": ["@imenam/mcp-http-gateway", "--mcp"],
-      "env": {
-        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
-        "GATEWAY_TOKEN": "…",
-        "GATEWAY_INLINE_ROOTS": "C:\\Users\\moi\\Documents\\tableurs;C:\\travail\\exports"
-      }
-    }
-  }
-}
-```
-
-- **`GATEWAY_INLINE_ROOTS` est l'interrupteur.** Non renseignée, le relais ne lit aucun
-  fichier et **l'appel échoue** en nommant la variable à définir. Un outil qui déclare la
-  paire attend le contenu : laisser filer le chemin ferait chercher le fichier au MCP sur
-  la machine du gateway, où il ne le trouverait pas — ou pire, où il traiterait un homonyme
-  sans rien signaler. Pas de repli, pas de dégradation silencieuse.
-
-  > **Changement de comportement.** Les versions antérieures laissaient passer le chemin tel
-  > quel dans ce cas. Si un déploiement existant s'appuyait là-dessus, renseignez
-  > `GATEWAY_INLINE_ROOTS` — le message d'erreur le dit explicitement.
-- Les liens symboliques sont résolus **avant** le contrôle : un lien posé dans un dossier
-  autorisé ne fait pas sortir un fichier situé ailleurs. Une remontée par `..` est refusée
-  pour la même raison.
-- Seules les extensions de `GATEWAY_INLINE_EXTENSIONS` passent (défaut : toutes).
-- Au-delà de `GATEWAY_INLINE_MAX_BYTES` (8 Mio par défaut), refus explicite. Ce défaut
-  tient sous le plafond de 16 Mio que le hub `mcp-gateway-manager` applique quand il
-  journalise les corps de requête.
-- Tout refus est rapporté à l'agent en clair, et **chaque fichier transmis laisse une ligne
-  sur `stderr`** : ce qui sort de la machine est lisible dans le journal de l'agent.
-
-> Côté MCP, cette fonction suppose que l'outil accepte le contenu en base64. C'est le cas
-> de [`@imenam/xls-reader`](https://www.npmjs.com/package/@imenam/xls-reader) ≥ 2.2. Un MCP
-> qui n'expose que `file_path` ne déclare pas la paire, et rien ne change pour lui.
-
-> **Le mode MCP distant (`/mcp`, Claude.ai) n'a pas de relais local** : rien ne tourne alors
-> sur la machine de l'appelant, donc personne ne peut lire son disque. Par ce chemin, un
-> agent qui veut faire lire un fichier doit en envoyer lui-même le contenu.
-
-### Fichiers reçus : le MCP produit, le relais écrit
-
-Le sens retour, symétrique du précédent. Un MCP qui *fabrique* un fichier — un export, une
-pièce jointe, un téléchargement — ne peut pas le déposer sur la machine de l'agent : le
-protocole n'offre au serveur aucune primitive pour y écrire. Un chemin de destination
-transmis tel quel ferait écrire le MCP sur **son** disque, sans que personne s'en aperçoive.
-
-Dès qu'un outil distant déclare la paire `<x>_path` / `<x>_relay`, le relais :
-
-1. retire `<x>_relay` du schéma publié à l'agent, qui ne voit qu'un dossier à nommer ;
-2. retient `<x>_path`, ne le transmet pas, et pose `<x>_relay` à `true` ;
-3. reçoit le contenu du fichier dans la réponse du MCP, l'écrit **ici**, et le retire du
-   résultat avant de le rendre à l'agent.
-
-```json
-{
-  "mcpServers": {
-    "gateway": {
-      "command": "npx",
-      "args": ["@imenam/mcp-http-gateway", "--mcp"],
-      "env": {
-        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
-        "GATEWAY_TOKEN": "…",
-        "GATEWAY_INLINE_WRITE_ROOTS": "C:\\Users\\moi\\Téléchargements"
-      }
-    }
-  }
-}
-```
-
-- **`GATEWAY_INLINE_WRITE_ROOTS` est l'interrupteur**, distinct de celui de la lecture :
-  écrire est plus dangereux que lire, et n'hérite donc pas des dossiers autorisés en lecture.
-- **Non renseignée, l'appel échoue** en nommant la variable à définir. Pas de repli, pas de
-  dégradation silencieuse : mieux vaut un fichier perdu qu'un fichier écrit au mauvais endroit.
-- `<x>_path` est toujours un **dossier**, créé si besoin ; le fichier garde le nom que lui
-  donne le MCP. Le relais ne renomme jamais.
-- Comme au sens aller, `<x>_path` n'est obligatoire que si le MCP le déclare tel.
-  Un outil qui le déclare optionnel dit par là qu'il sait quoi faire sans destination —
-  renvoyer une capture inline, par exemple. Sans `<x>_path`, le relais ne retient rien,
-  ne pose pas `<x>_relay`, et le résultat repart intact.
-- Si l'outil déclare aussi `<x>_overwrite`, le relais l'honore ; sinon il refuse d'écraser.
-- Les liens symboliques sont résolus avant contrôle, y compris sur le plus proche ancêtre
-  existant quand la destination n'existe pas encore.
-- **Le contenu est retiré du résultat dans tous les cas**, y compris en cas d'échec
-  d'écriture. Un fichier de 8 Mio encodé en base64 n'a rien à faire dans le contexte d'un
-  agent : ça coûte cher, et un agent qui le recopierait à la main le corromprait.
-- Chaque fichier écrit laisse une ligne sur `stderr`.
-
-> Côté MCP, cette fonction suppose que l'outil sache renvoyer son fichier en bloc
-> `resource` (avec `blob` et `name`) quand `<x>_relay` est posé. C'est le cas de
-> [`file-share-mcp`](https://www.npmjs.com/package/file-share-mcp). Un MCP qui ne déclare
-> pas la paire n'est pas concerné, et son résultat repart intact.
-
----
-
-## Mode MCP distant (HTTPS / Claude.ai)
-
-Le gateway expose également un **endpoint MCP natif** sur `/mcp` via le transport **Streamable HTTP**, en mode **stateless**. Ce mode permet à Claude.ai — et à tout client MCP distant compatible — de se connecter directement au gateway, sans intermédiaire.
-
-Chaque `POST /mcp` est traité de façon autonome : aucun `mcp-session-id` n'est émis, aucun état n'est conservé entre deux requêtes. Les trois outils exposés étant du pur requête/réponse (aucune notification serveur→client), aucune session n'est nécessaire. Concrètement :
-
-- un connecteur laissé inactif ne peut pas « expirer » côté serveur — il n'y a rien à expirer ;
-- un redémarrage ou un redéploiement du gateway est transparent pour les clients connectés ;
-- l'endpoint peut être scalé horizontalement derrière un load balancer sans affinité de session.
-
-`GET /mcp` et `DELETE /mcp` répondent `405 Method Not Allowed` : sans session, il n'y a ni flux SSE autonome ni terminaison de session à gérer (la spec Streamable HTTP l'autorise explicitement).
-
-### Flow
-
-```
-Claude.ai
-    │  HTTPS + Bearer JWT
-    ▼
-[mcp-http-gateway /mcp]  ──── 401 + WWW-Authenticate si non authentifié
-    │
-    │  (découverte OAuth 2.1)
-    ▼
-[Authorization Server externe]  (Auth0, Keycloak, Authentik, Zitadel, Logto…)
-```
-
-Le gateway agit uniquement comme **Resource Server** : il valide les JWT via JWKS et expose l'URL de l'AS via le Protected Resource Metadata (RFC 9728). Toute la logique OAuth (DCR, PKCE, `/authorize`, `/token`) est déléguée à l'AS externe.
-
-### Variables d'environnement
-
-| Variable | Description |
-|---|---|
-| `MCP_OAUTH_ENABLED` | `true` pour activer la protection OAuth (recommandé en production) |
-| `MCP_PUBLIC_URL` | URL publique canonique du endpoint — ex. `https://gateway.example.com/mcp`. Utilisée comme `resource` (RFC 9728) et `aud` JWT. |
-| `OAUTH_JWKS_URI` | URI du JWKS de l'Authorization Server — ex. `https://your-auth-server/.well-known/jwks.json` |
-| `OAUTH_ISSUER` | Issuer attendu dans les JWT — ex. `https://your-auth-server` |
-
-> Sans `MCP_OAUTH_ENABLED=true`, `/mcp` est ouvert (utile pour les tests locaux). Claude.ai refusera cependant de s'y connecter sans 401 + `WWW-Authenticate`.
-
-### Configuration Claude.ai
-
-Dans Claude.ai → **Paramètres → Connecteurs** → Ajouter un connecteur MCP :
-
-```
-URL : https://gateway.example.com/mcp
-Authentification : OAuth (auto-détectée via /.well-known/oauth-protected-resource)
-```
-
-### Prérequis côté Authorization Server
-
-L'AS doit supporter :
-- **DCR** (RFC 7591) — `registration_endpoint` exposé
-- **PKCE S256** — `code_challenge_methods_supported: ["S256"]`
-- `redirect_uri` autorisé : `https://claude.ai/api/mcp/auth_callback`
-- JWT signés (RS256 ou ES256) avec claims `iss`, `aud=MCP_PUBLIC_URL`, `exp`
-
-### Exposition HTTPS publique
-
-Le endpoint `/mcp` doit être accessible depuis l'IP range `160.79.104.0/21` (Anthropic) en HTTPS. Options :
-
-| Option | Commande / Notes |
-|---|---|
-| **Cloudflare Tunnel** | `cloudflared tunnel --url http://localhost:3500` |
-| **ngrok** | `ngrok http 3500` — idéal pour les tests |
-| **Reverse-proxy** | Caddy / Traefik en frontal avec cert Let's Encrypt |
-
-### Outils exposés
-
-Les mêmes 3 outils que le mode stdio — avec accès direct aux clients MCP internes (sans repasser par HTTP) :
-
-| Outil | Description |
-|---|---|
-| `list_mcps` | Liste les MCPs disponibles avec leur route et description |
-| `list_tools` | Liste les outils d'un MCP donné (`route` requis) |
-| `call_tool` | Appelle un outil (`route`, `tool_name`, `arguments`) |
-
-### Pré-exposition de MCP au démarrage (`EXPOSE_AT_AGENT_STARTUP`)
-
-Par défaut, l'agent ne reçoit que les 3 outils de découverte et doit appeler `list_mcps` /
-`list_tools` pour découvrir les MCP. Pour les MCP fréquemment utilisés, la clé
-`EXPOSE_AT_AGENT_STARTUP` publie leurs outils **directement dans la réponse `tools/list`**,
-nommés `<serveur>__<outil>`, avec description et `inputSchema` complets. L'agent les appelle
-directement, sans passer par `call_tool` et sans aucun aller-retour de découverte.
-
-L'option se déclare **par MCP**, dans son bloc `env` de `config/mcp-servers.json` — au même
-endroit que `MCP_SERVER_ROUTE`, qui est également une directive lue par le gateway :
-
-```json
-{
-  "mcpServers": {
-    "documentor": {
-      "command": "node",
-      "args": ["/chemin/vers/documentor/dist/index.js"],
-      "description": "Documentation manager MCP",
-      "env": {
-        "MCP_SERVER_ROUTE": "/documentor",
-        "EXPOSE_AT_AGENT_STARTUP": "true"
-      }
-    },
-    "scraper": {
-      "command": "node",
-      "args": ["/chemin/vers/scraper/dist/index.js"],
-      "env": {
-        "MCP_SERVER_ROUTE": "/scraper"
-      }
-    }
-  }
-}
-```
-
-Ici `documentor` est pré-exposé ; `scraper`, sans la clé, ne l'est pas et reste accessible
-via `list_mcps` / `list_tools` / `call_tool`. Le `.env` du gateway ne contient **aucune**
-indication relative aux MCP.
-
-La valeur est un booléen : `"true"` (également `"1"`, `"yes"`, `"on"`) ou `"false"`. Toute
-autre valeur est refusée avec un avertissement au démarrage et le MCP n'est pas pré-exposé.
-
-**Pourquoi ce canal ?** Les définitions d'outils passent par `tools/list`, seul canal sans
-limite de taille. Le champ `instructions` du protocole, lui, est plafonné par les clients
-autour de **2 048 caractères** et tronqué silencieusement au-delà — un MCP de 30 outils
-avec ses schémas pèse ~33 000 caractères, il ne peut donc pas y transiter.
-
-**Quand l'activer ?** Le compromis, pour un MCP réellement utilisé :
-
-| | Découverte (défaut) | Pré-exposé |
-|---|---|---|
-| Allers-retours | 3 (`list_mcps`, `list_tools`, `call_tool`) | 1 (appel direct) |
-| Contexte | `list_tools` déverse tous les schémas dans la conversation dès le 1ᵉʳ usage, définitivement | les noms d'outils, puis le schéma des seuls outils utilisés |
-
-À activer donc pour les MCP utilisés dans la majorité des sessions. À laisser en découverte
-pour les MCP occasionnels : un MCP pré-exposé mais inutilisé coûte ses noms d'outils à
-chaque requête, et multiplier les outils similaires dégrade la sélection par l'agent.
-
-Dans tous les cas, le MCP enfant reste hébergé côté gateway : seules ses **définitions**
-sont relayées, les appels sont proxifiés. L'isolation est préservée.
-
-Cette config vit **uniquement côté serveur** et s'applique de façon transparente aux deux
-points d'entrée par lesquels un agent atteint le gateway :
-
-- **endpoint `/mcp` distant** (cas Claude.ai) — les outils proxy sont publiés directement ;
-- **bridge stdio** (`server.js --mcp`, cas local) — au démarrage, le bridge interroge le
-  serveur (`GET /startup-exposition`), publie les outils reçus et route leurs appels vers
-  la bonne route. Le bridge ne connaît pas la config : il ne fait que transmettre ce que le
-  serveur décide.
-
----
-
-## Ajouter un MCP
-
-1. Ajouter l'entrée dans `config/mcp-servers.json` avec `MCP_SERVER_ROUTE` dans `env`
-2. Redémarrer le gateway
-
-Aucune modification du MCP n'est nécessaire.
+# MCP HTTP Gateway
+
+Serveur HTTP qui expose n'importe quel serveur MCP (Model Context Protocol) en tant qu'API REST, sans modifier les MCPs eux-mêmes. Conçu pour permettre à des agents ou applications ne supportant pas nativement le protocole MCP de communiquer avec l'écosystème MCP via de simples requêtes HTTP.
+
+## Fonctionnement
+
+Chaque MCP tourne en tant que processus enfant (transport stdio). Le gateway s'y connecte via le SDK MCP officiel et expose ses outils sur des routes HTTP configurables.
+
+```
+Agent / App externe
+       │
+       │  HTTP
+       ▼
+MCP HTTP Gateway (port 3500)
+       │
+       │  stdio (SDK MCP)
+       ├──▶ mcp-documentor  (/documentor)
+       ├──▶ mcp-raindrop     (/raindrop)
+       └──▶ ...
+```
+
+## Installation
+
+**En tant que CLI globale :**
+
+```bash
+npm install -g @imenam/mcp-http-gateway
+```
+
+**Via npx (sans installation) :**
+
+```bash
+npx @imenam/mcp-http-gateway
+```
+
+**En dépendance locale d'un projet :**
+
+```bash
+npm install @imenam/mcp-http-gateway
+```
+
+## Configuration
+
+### `.env`
+
+```env
+GATEWAY_PORT=3500
+GATEWAY_CONFIG_DIR=./config
+```
+
+| Variable | Défaut | Description |
+|---|---|---|
+| `GATEWAY_PORT` | `3500` | Port HTTP du gateway |
+| `GATEWAY_CONFIG_DIR` | `./config` (relatif au cwd) | Dossier contenant `mcp-servers.json` |
+| `GATEWAY_ADMIN_TOKEN` | — | Active `POST /admin/reload` et en est le jeton. Absent, la route n'existe pas. Voir [Rechargement à chaud](#rechargement-à-chaud). |
+| `GATEWAY_BODY_LIMIT` | `32mb` | Taille maximale du corps d'une requête. Le défaut d'express (100 ko) ne suffit pas dès qu'un appel d'outil porte le contenu d'un fichier en base64 ; au-delà de cette limite, la réponse est un `413`. Ne s'applique pas aux routes de [relais HTTP](#relais-http-mcp_http_relay_port). |
+
+### `mcp-servers.json`
+
+À créer dans le dossier de configuration (`./config` par défaut, ou le chemin pointé par `GATEWAY_CONFIG_DIR`). Un fichier `config/mcp-servers.example.json` est fourni comme point de départ.
+
+Même format que la configuration `mcpServers` de Cursor. Ajouter `MCP_SERVER_ROUTE` dans `env` pour définir la route HTTP du MCP, et `description` pour la documentation.
+
+```json
+{
+  "mcpServers": {
+    "mon-mcp": {
+      "command": "node",
+      "args": ["/chemin/vers/dist/index.js"],
+      "description": "Description courte du MCP",
+      "env": {
+        "MA_VARIABLE": "valeur",
+        "MCP_SERVER_ROUTE": "/ma-route"
+      }
+    }
+  }
+}
+```
+
+> Un MCP sans `MCP_SERVER_ROUTE` est ignoré au démarrage.
+
+#### Relais HTTP (`MCP_HTTP_RELAY_PORT`)
+
+Un MCP peut avoir besoin de recevoir du trafic HTTP brut en plus de ses appels d'outils : le protocole HTTP de git, un flux binaire, etc. Il déclare alors `MCP_HTTP_RELAY_PORT` dans son bloc `env` :
+
+```json
+"env": {
+  "MCP_SERVER_ROUTE": "/github",
+  "MCP_HTTP_RELAY_PORT": "4610"
+}
+```
+
+- Le MCP écoute lui-même en HTTP sur `127.0.0.1:<port>`. Il reçoit la valeur par son environnement, comme toute variable du bloc `env`.
+- Le gateway relaie tel quel `/{route}/http/*` vers `http://127.0.0.1:<port>/*` : méthode, chemin, requête, en-têtes et corps à l'aller, statut, en-têtes et corps au retour.
+- Le gateway ne connaît rien du protocole relayé. Il authentifie la requête et applique le rate limiting comme sur toutes ses routes, puis retire l'en-tête `Authorization` avant de transmettre : son jeton ne parvient jamais au MCP.
+- Le corps circule en flux, sans être lu ni décodé. `GATEWAY_BODY_LIMIT` ne s'y applique pas.
+- Le port reste sur `127.0.0.1` : le seul point d'entrée exposé est le gateway.
+
+Une valeur hors de `1`–`65535` fait ignorer le MCP au démarrage, avec une erreur dans les logs. Si le MCP n'écoute pas sur le port déclaré, le relais répond `502`.
+
+## Démarrage
+
+```bash
+npm start
+```
+
+Le gateway connecte chaque MCP configuré et démarre le serveur HTTP. Les MCPs en échec au démarrage sont ignorés sans bloquer les autres.
+
+## Rechargement à chaud
+
+Avec `GATEWAY_ADMIN_TOKEN` défini, le gateway relit `mcp-servers.json` sur demande, sans redémarrer :
+
+```bash
+curl -X POST -H "X-Gateway-Admin-Token: $GATEWAY_ADMIN_TOKEN" http://127.0.0.1:3500/admin/reload
+```
+
+Chaque MCP est comparé à sa configuration en service :
+
+| Changement | Effet |
+|---|---|
+| MCP retiré du fichier | son processus est arrêté, sa route disparaît |
+| MCP ajouté, ou en échec jusque-là | il est lancé |
+| `command`, `args` ou une variable de `env` modifiés | **seul ce MCP** est relancé |
+| `description` ou `EXPOSE_AT_AGENT_STARTUP` seuls modifiés | mis à jour sans relance |
+| rien | rien |
+
+Les autres MCP ne sont pas touchés : leurs processus, leurs sessions et leurs appels en cours continuent.
+
+La réponse donne le résultat MCP par MCP :
+
+```json
+{
+  "revision": "5ecfab70.3",
+  "results": [
+    { "name": "documentor", "action": "unchanged", "ok": true },
+    { "name": "github", "action": "restarted", "ok": true },
+    { "name": "scraper", "action": "started", "ok": false, "error": "MCP error -32000: Connection closed" }
+  ]
+}
+```
+
+`action` vaut `started`, `restarted`, `stopped`, `updated` ou `unchanged`. Un MCP qui ne démarre pas est signalé par `ok: false` et reste hors service ; le rechargement suivant tente de le relancer. Un fichier illisible est refusé en `400`, et rien n'est modifié.
+
+Le jeton passe par l'en-tête `X-Gateway-Admin-Token`, indépendamment de l'authentification OAuth du gateway.
+
+### Révision
+
+Chaque réponse du gateway porte l'en-tête `X-Gateway-Revision`. Sa valeur change à chaque démarrage du gateway et à chaque rechargement qui modifie quelque chose. Le [mode MCP](#mode-mcp) s'en sert pour mettre à jour les outils de l'agent.
+
+## Routes
+
+### `GET /mcps`
+
+Retourne la liste des MCPs connectés avec leur route, description et instructions d'utilisation (format Markdown).
+
+```bash
+curl http://localhost:3500/mcps
+```
+
+---
+
+### `GET /{route}/tools`
+
+Liste les outils disponibles d'un MCP avec leur nom, description et schéma d'arguments.
+
+```bash
+curl http://localhost:3500/documentor/tools
+```
+
+---
+
+### `POST /{route}/tools/:toolName`
+
+Appelle un outil du MCP. Les arguments sont passés dans le body JSON.
+
+```bash
+curl -X POST http://localhost:3500/documentor/tools/list_projects -H "Content-Type: application/json" -d '{}'
+```
+
+```bash
+curl -X POST http://localhost:3500/documentor/tools/get_doc -H "Content-Type: application/json" -d '{"id":"mon-doc-id"}'
+```
+
+#### Réponse
+
+La réponse est le format brut du protocole MCP — un tableau `content` de blocs typés :
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "Résultat de l'outil..." }
+  ]
+}
+```
+
+Pour extraire le texte directement avec `jq` :
+
+```bash
+curl -s -X POST http://localhost:3500/documentor/tools/list_projects -H "Content-Type: application/json" -d '{}' | jq -r '.content[0].text'
+```
+
+---
+
+### `/{route}/http/*`
+
+Présente uniquement pour un MCP qui déclare `MCP_HTTP_RELAY_PORT` (voir [Relais HTTP](#relais-http-mcp_http_relay_port)). Toute méthode est acceptée ; la requête est transmise telle quelle au serveur HTTP du MCP, sans l'en-tête `Authorization`.
+
+```bash
+git clone -c http.extraHeader="Authorization: Bearer <jeton>" http://localhost:3500/github/http/repo.git
+```
+
+## Mode MCP
+
+Le gateway peut également démarrer en tant que **serveur MCP** (transport stdio). Dans ce mode, il se connecte à une instance du gateway HTTP et expose ses outils comme des outils MCP natifs.
+
+### Cas d'usage : agent dans un conteneur Docker
+
+Le gateway HTTP tourne **hors du conteneur**, avec accès aux MCPs et leurs clés sensibles. L'agent dans le conteneur reçoit uniquement le gateway en mode MCP — aucune clé ne lui est injectée.
+
+```
+[Agent dans conteneur]
+        │  stdio (MCP)
+        ▼
+[mcp-http-gateway --mcp]  ←── GATEWAY_URL
+        │  HTTP
+        ▼
+[mcp-http-gateway hors conteneur]
+        │  stdio
+        ▼
+[MCPs réels (clés sensibles)]
+```
+
+### Démarrage
+
+```bash
+GATEWAY_URL=http://host.docker.internal:3500 npx @imenam/mcp-http-gateway --mcp
+```
+
+### Configuration dans le conteneur
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "http://host.docker.internal:3500"
+      }
+    }
+  }
+}
+```
+
+> `host.docker.internal` est l'adresse de l'hôte depuis un conteneur Docker.
+
+### Variables d'environnement du mode `--mcp`
+
+| Variable | Requis | Description |
+|---|---|---|
+| `GATEWAY_URL` | oui | Base HTTP du gateway à relayer, sans barre finale. Le relais compose lui-même ses routes REST (`/startup-exposition`, `/mcp-definitions`, `/{route}/tools`, `/{route}/tools/{outil}`) : **ne pas** y ajouter `/mcp`. |
+| `GATEWAY_TOKEN` | non | Token porteur. S'il est défini, **tous** les appels sortants du relais portent `Authorization: Bearer <token>`. Absent, aucun en-tête n'est ajouté — le comportement est exactement celui des versions antérieures. |
+| `GATEWAY_INLINE_ROOTS` | non | Dossiers depuis lesquels le relais peut lire un fichier et en transmettre le contenu (cf. [Fichiers locaux](#fichiers-locaux--lagent-nomme-le-relais-lit)). **Non renseignée, tout appel à un outil qui déclare la paire échoue explicitement.** Séparateur : `;` sous Windows, `:` ailleurs. |
+| `GATEWAY_INLINE_EXTENSIONS` | non | Extensions autorisées à la lecture, séparées par des virgules. Défaut : `*` (toutes) — les racines restent le vrai garde-fou. |
+| `GATEWAY_INLINE_MAX_BYTES` | non | Taille maximale d'un fichier transmis, en octets, dans les deux sens. Défaut : `8388608` (8 Mio). |
+| `GATEWAY_INLINE_WRITE_ROOTS` | non | Dossiers dans lesquels le relais peut écrire un fichier renvoyé par un MCP (cf. [Fichiers reçus](#fichiers-reçus--le-mcp-produit-le-relais-écrit)). **Non renseignée, la fonction est désactivée** et tout outil qui la réclame échoue explicitement. Séparateur : `;` sous Windows, `:` ailleurs. |
+| `GATEWAY_INLINE_WRITE_EXTENSIONS` | non | Extensions autorisées à l'écriture, séparées par des virgules. Défaut : `*` (toutes) — les racines restent le vrai garde-fou. |
+| `GATEWAY_EXEC_ROUTES` | non | Liste blanche des routes, dans le gateway, des MCP autorisés à faire exécuter des commandes sur la machine de l'agent, séparées par des virgules (ex. `/github`) — cf. [Exécution sur la machine de l'agent](#exécution-sur-la-machine-de-lagent). **Vide, la fonction est désactivée.** Une entrée qui ne commence pas par `/` fait refuser le démarrage. |
+| `GATEWAY_WATCH_DIR` | non | Dossier des fichiers de veille déposés pour les [notifications](#notifications--un-veilleur-sur-la-machine-de-lagent). Défaut : `~/.mcp-http-gateway/watch`. |
+
+> Ces deux variables sont lues dans l'environnement du process. Le relais fait
+> `import 'dotenv/config'` : un fichier `.env` présent dans le **répertoire courant de
+> l'agent** peut donc les fournir. dotenv n'écrase jamais une variable déjà définie —
+> le bloc `env` de la configuration MCP l'emporte toujours.
+
+### Derrière un frontal qui authentifie
+
+Quand le gateway n'est pas joint en direct mais à travers un frontal qui exige un token
+porteur (hub [`mcp-gateway-manager`](https://github.com/Matthieu-Pesnot-Pin), reverse-proxy
+maison…), `GATEWAY_TOKEN` est ce que le relais présente à chaque requête :
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
+        "GATEWAY_TOKEN": "…"
+      }
+    }
+  }
+}
+```
+
+Un refus (`401`/`403`) est rapporté à l'agent en clair — token manquant, ou token invalide —
+plutôt qu'en `HTTP 401` nu. Le token lui-même n'est **jamais** journalisé, pas même tronqué.
+
+### Outils exposés
+
+Le mode MCP expose 3 outils qui reflètent directement les routes du gateway :
+
+| Outil | Description |
+|---|---|
+| `list_mcps` | Liste les MCPs disponibles avec leur route et description |
+| `list_tools` | Liste les outils d'un MCP donné (`route` requis) |
+| `call_tool` | Appelle un outil (`route`, `tool_name`, `arguments`) |
+
+L'agent découvre d'abord les MCPs disponibles, explore les outils d'un MCP si besoin, puis appelle l'outil voulu.
+
+### Fichiers locaux : l'agent nomme, le relais lit
+
+Le relais tourne sur la machine de l'**agent** ; les MCP, eux, tournent sur la machine du
+**gateway**. Un chemin de fichier transmis tel quel ne veut donc rien dire à l'arrivée : le
+MCP le cherche chez lui et répond « fichier introuvable ».
+
+Le relais sait résoudre ça. Dès qu'un outil distant déclare une paire de paramètres
+`<x>_path` / `<x>_content`, le relais **lit le fichier localement, l'encode en base64 et
+envoie le contenu** dans `<x>_content` (plus le nom dans `<x>_name`, si le schéma le
+prévoit). Le paramètre `file_path` reste la seule chose que l'agent fournit : les
+paramètres que le relais remplit sont **retirés du schéma** publié à l'agent, par
+`tools/list` comme par `list_tools`. L'agent n'a donc aucun arbitrage à faire, et aucune
+occasion d'envoyer un chemin qui ne serait pas lisible à l'arrivée.
+
+Un outil qui ne déclare pas cette paire n'est jamais concerné : un `output_path` seul reste
+un chemin, interprété côté gateway comme avant.
+
+`<x>_path` est obligatoire pour l'agent si, et seulement si, le MCP le déclare obligatoire.
+Un outil qui le laisse optionnel accepte sa donnée autrement — un texte passé en ligne, par
+exemple. Sans `<x>_path`, le relais ne lit rien et transmet l'appel tel quel.
+
+**Le chemin vient de l'agent : il n'est pas digne de confiance.** La fonction est donc
+fermée par défaut et s'ouvre dossier par dossier :
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
+        "GATEWAY_TOKEN": "…",
+        "GATEWAY_INLINE_ROOTS": "C:\\Users\\moi\\Documents\\tableurs;C:\\travail\\exports"
+      }
+    }
+  }
+}
+```
+
+- **`GATEWAY_INLINE_ROOTS` est l'interrupteur.** Non renseignée, le relais ne lit aucun
+  fichier et **l'appel échoue** en nommant la variable à définir. Un outil qui déclare la
+  paire attend le contenu : laisser filer le chemin ferait chercher le fichier au MCP sur
+  la machine du gateway, où il ne le trouverait pas — ou pire, où il traiterait un homonyme
+  sans rien signaler. Pas de repli, pas de dégradation silencieuse.
+
+  > **Changement de comportement.** Les versions antérieures laissaient passer le chemin tel
+  > quel dans ce cas. Si un déploiement existant s'appuyait là-dessus, renseignez
+  > `GATEWAY_INLINE_ROOTS` — le message d'erreur le dit explicitement.
+- Les liens symboliques sont résolus **avant** le contrôle : un lien posé dans un dossier
+  autorisé ne fait pas sortir un fichier situé ailleurs. Une remontée par `..` est refusée
+  pour la même raison.
+- Seules les extensions de `GATEWAY_INLINE_EXTENSIONS` passent (défaut : toutes).
+- Au-delà de `GATEWAY_INLINE_MAX_BYTES` (8 Mio par défaut), refus explicite. Ce défaut
+  tient sous le plafond de 16 Mio que le hub `mcp-gateway-manager` applique quand il
+  journalise les corps de requête.
+- Tout refus est rapporté à l'agent en clair, et **chaque fichier transmis laisse une ligne
+  sur `stderr`** : ce qui sort de la machine est lisible dans le journal de l'agent.
+
+> Côté MCP, cette fonction suppose que l'outil accepte le contenu en base64. C'est le cas
+> de [`@imenam/xls-reader`](https://www.npmjs.com/package/@imenam/xls-reader) ≥ 2.2. Un MCP
+> qui n'expose que `file_path` ne déclare pas la paire, et rien ne change pour lui.
+
+> **Le mode MCP distant (`/mcp`, Claude.ai) n'a pas de relais local** : rien ne tourne alors
+> sur la machine de l'appelant, donc personne ne peut lire son disque. Par ce chemin, un
+> agent qui veut faire lire un fichier doit en envoyer lui-même le contenu.
+
+### Fichiers reçus : le MCP produit, le relais écrit
+
+Le sens retour, symétrique du précédent. Un MCP qui *fabrique* un fichier — un export, une
+pièce jointe, un téléchargement — ne peut pas le déposer sur la machine de l'agent : le
+protocole n'offre au serveur aucune primitive pour y écrire. Un chemin de destination
+transmis tel quel ferait écrire le MCP sur **son** disque, sans que personne s'en aperçoive.
+
+Dès qu'un outil distant déclare la paire `<x>_path` / `<x>_relay`, le relais :
+
+1. retire `<x>_relay` du schéma publié à l'agent, qui ne voit qu'un dossier à nommer ;
+2. retient `<x>_path`, ne le transmet pas, et pose `<x>_relay` à `true` ;
+3. reçoit le contenu du fichier dans la réponse du MCP, l'écrit **ici**, et le retire du
+   résultat avant de le rendre à l'agent.
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
+        "GATEWAY_TOKEN": "…",
+        "GATEWAY_INLINE_WRITE_ROOTS": "C:\\Users\\moi\\Téléchargements"
+      }
+    }
+  }
+}
+```
+
+- **`GATEWAY_INLINE_WRITE_ROOTS` est l'interrupteur**, distinct de celui de la lecture :
+  écrire est plus dangereux que lire, et n'hérite donc pas des dossiers autorisés en lecture.
+- **Non renseignée, l'appel échoue** en nommant la variable à définir. Pas de repli, pas de
+  dégradation silencieuse : mieux vaut un fichier perdu qu'un fichier écrit au mauvais endroit.
+- `<x>_path` est toujours un **dossier**, créé si besoin ; le fichier garde le nom que lui
+  donne le MCP. Le relais ne renomme jamais.
+- Comme au sens aller, `<x>_path` n'est obligatoire que si le MCP le déclare tel.
+  Un outil qui le déclare optionnel dit par là qu'il sait quoi faire sans destination —
+  renvoyer une capture inline, par exemple. Sans `<x>_path`, le relais ne retient rien,
+  ne pose pas `<x>_relay`, et le résultat repart intact.
+- Si l'outil déclare aussi `<x>_overwrite`, le relais l'honore ; sinon il refuse d'écraser.
+- Les liens symboliques sont résolus avant contrôle, y compris sur le plus proche ancêtre
+  existant quand la destination n'existe pas encore.
+- **Le contenu est retiré du résultat dans tous les cas**, y compris en cas d'échec
+  d'écriture. Un fichier de 8 Mio encodé en base64 n'a rien à faire dans le contexte d'un
+  agent : ça coûte cher, et un agent qui le recopierait à la main le corromprait.
+- Chaque fichier écrit laisse une ligne sur `stderr`.
+
+> Côté MCP, cette fonction suppose que l'outil sache renvoyer son fichier en bloc
+> `resource` (avec `blob` et `name`) quand `<x>_relay` est posé. C'est le cas de
+> [`file-share-mcp`](https://www.npmjs.com/package/file-share-mcp). Un MCP qui ne déclare
+> pas la paire n'est pas concerné, et son résultat repart intact.
+
+### Exécution sur la machine de l'agent
+
+Un MCP du gateway tourne sur la machine du gateway et n'a aucun moyen de lancer quoi que
+ce soit sur celle de l'agent. Si sa route figure dans `GATEWAY_EXEC_ROUTES`, le relais lui
+en donne un, à travers les appels d'outils ordinaires :
+
+1. Le relais ajoute à chaque appel d'outil vers cette route l'argument réservé `_gateway_exec` :
+   `{ "version": 1, "cwd": "<dossier de lancement du relais>", "gatewayToken": true|false }`.
+2. Le MCP peut répondre par une **demande d'exécution** au lieu d'un résultat final, dans
+   `_meta["gateway/exec"]` :
+   ```json
+   { "id": "…", "steps": [ { "command": "git", "args": ["status"], "cwd": "repo", "env": { "…": "…" } } ] }
+   ```
+3. Le relais lance les étapes dans l'ordre, **sans shell**, et s'arrête à la première dont
+   le code de sortie n'est pas `0`.
+   - `cwd` est résolu par rapport au dossier de lancement du relais, c'est-à-dire le dossier où l'agent l'a démarré.
+   - Dans `args` et dans les valeurs de `env`, le relais remplace `{{GATEWAY_URL}}` et `{{GATEWAY_TOKEN}}` par ses propres valeurs. Un marqueur dont la valeur manque fait échouer l'appel.
+4. Il rappelle le même outil avec `_gateway_exec.continuation = { "id", "results" }`, un
+   résultat `{ code, stdout, stderr, error? }` par étape exécutée. Il recommence tant que le MCP renvoie une demande, dans la limite de 50 allers-retours.
+
+L'agent ne voit que le résultat final.
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://gateway.example.com",
+        "GATEWAY_TOKEN": "…",
+        "GATEWAY_EXEC_ROUTES": "/github"
+      }
+    }
+  }
+}
+```
+
+- **`GATEWAY_EXEC_ROUTES` est la liste blanche, côté agent** : les routes, dans le gateway,
+  des MCP autorisés à exécuter, séparées par des virgules. Vide, aucun MCP n'exécute.
+  - Seul un appel vers une route listée porte `_gateway_exec`. Un MCP qui a besoin
+    d'exécuter refuse les autres appels, en le disant.
+  - Une demande d'exécution renvoyée par une route non listée fait échouer l'appel, sans
+    rien lancer.
+  - `/github` et `/github/` désignent la même route. Une entrée qui ne commence pas par `/`
+    fait refuser le démarrage du relais.
+- **Pour un MCP listé, l'exécution est libre** : il peut faire lancer n'importe quelle
+  commande, avec les droits de l'utilisateur qui fait tourner le relais. Ne listez que des
+  MCP que vous maîtrisez.
+- **Les demandes ne viennent que du gateway de `GATEWAY_URL`** : le relais n'en lit que dans
+  les réponses à ses propres appels. `GATEWAY_TOKEN` prouve au gateway l'identité du relais,
+  mais pas l'inverse. C'est HTTPS qui garantit que la réponse vient bien de ce gateway. Sur
+  un `GATEWAY_URL` en `http://` hors de la machine, quiconque se trouve sur le chemin réseau
+  peut injecter des demandes d'exécution.
+- Chaque commande laisse une ligne sur `stderr`, avec ses marqueurs non remplacés : le
+  jeton n'y figure jamais.
+- La sortie standard et la sortie d'erreur de chaque étape sont tronquées au-delà de 1 Mio.
+- Un MCP dont le schéma refuse les arguments inconnus rejettera `_gateway_exec` : avec
+  l'exécution activée, ses appels échouent.
+
+> Côté MCP, c'est le cas de [`@imenam/mcp-github`](https://www.npmjs.com/package/@imenam/mcp-github)
+> en rôle `remote` : git s'exécute sur la copie de travail de l'agent, à travers le
+> [relais HTTP](#relais-http-mcp_http_relay_port) du gateway.
+
+### Notifications : un veilleur sur la machine de l'agent
+
+Le gateway ne sait que répondre : il ne pousse rien vers l'agent. Pour qu'un MCP du gateway
+réveille l'agent quand il a du nouveau (un post publié, un message reçu…), le relais fait
+armer par l'agent un **veilleur** : un processus lancé sur la machine de l'agent par l'outil
+`Monitor` de son hôte, qui appelle en boucle un outil d'attente du MCP à travers l'API REST du
+gateway. Chaque appel reste ouvert jusqu'à ce que le MCP ait un événement, ou 50 s au plus,
+sous les 60 s que le gateway accorde à un appel d'outil. Chaque événement devient une ligne
+sur la sortie du veilleur, et `Monitor` réveille l'agent à chaque ligne.
+
+La convention, côté MCP :
+
+1. Un **outil d'activation** déclare dans son schéma la propriété réservée `_gateway_watch`.
+   Le relais la retire du schéma montré à l'agent, et la remplit à chaque appel de cet outil :
+   `{ "version": 1 }`. Sans elle, le MCP sait qu'aucun relais ne veillera pour lui.
+2. L'outil d'activation répond par une **spécification de veille**, dans `_meta["gateway/watch"]` :
+   ```json
+   { "tool": "wait_for_posts", "arguments": {}, "cursor": "57", "description": "New posts in the Telegram channel" }
+   ```
+   L'outil d'attente, ses arguments fixes, le point de reprise de départ et le libellé du `Monitor`.
+3. Le relais dépose sur la machine de l'agent un **fichier de veille** en `0600` : adresse et
+   jeton du gateway, route, outil, arguments, point de reprise. Il rend à l'agent, à la place
+   de la réponse du MCP, l'appel `Monitor` à faire :
+   ```text
+   command:     "<node>" "<…>/mcp-http-gateway/server.js" --watch "<…>/watch/<id>.json"
+   timeout_ms:  1800000
+   ```
+   Le jeton ne figure jamais dans la commande, donc jamais dans la conversation.
+4. Le veilleur (`server.js --watch <fichier>`) appelle l'outil d'attente avec ses arguments,
+   plus `cursor` et `timeout_seconds: 50`. L'outil répond, dans `_meta["gateway/events"]` :
+   ```json
+   { "cursor": "58", "lines": ["[telegram] new post 42: … — read it with get_post"] }
+   ```
+   Le veilleur écrit chaque ligne telle quelle, enregistre le point de reprise dans le fichier
+   de veille, et rappelle aussitôt l'outil.
+
+Comportement du veilleur :
+
+- **Expiration du `Monitor`** (30 minutes au plus) : l'agent relance la même commande, et le
+  veilleur repart du point de reprise enregistré, sans rien perdre entre-temps.
+- **Réactivation pendant la veille** : si un veilleur suit déjà ce fichier, le relais le dit
+  au lieu de demander un second veilleur, et ne touche pas au point de reprise.
+- **Pannes** : le veilleur réessaie avec une temporisation croissante (de 1 s à 30 s) et ne
+  s'arrête jamais de lui-même. Un refus du jeton, un outil qui ne suit pas la convention, ou
+  trois échecs de suite sont annoncés une fois sur sa sortie, donc à l'agent ; le retour à la
+  normale aussi.
+- **Ménage** : le fichier de veille, qui contient le jeton, est propre au relais qui l'écrit.
+  Il est retiré à l'arrêt de ce relais (fermeture de son entrée standard) ou, si le relais a
+  été tué, par le prochain relais qui démarre.
+- Une spécification renvoyée par un outil qui n'a pas déclaré `_gateway_watch` est ignorée.
+- Un MCP n'accède ainsi qu'à la veille de ses propres outils : le veilleur n'appelle que
+  l'outil nommé dans la spécification, sur la route qui l'a renvoyée.
+
+> Côté MCP, c'est le cas de [`@imenam/mcp-telegram`](https://www.npmjs.com/package/@imenam/mcp-telegram) :
+> `enable_notifications` active la veille, `wait_for_posts` est l'outil d'attente.
+
+---
+
+## Mode MCP distant (HTTPS / Claude.ai)
+
+Le gateway expose également un **endpoint MCP natif** sur `/mcp` via le transport **Streamable HTTP**, en mode **stateless**. Ce mode permet à Claude.ai — et à tout client MCP distant compatible — de se connecter directement au gateway, sans intermédiaire.
+
+Chaque `POST /mcp` est traité de façon autonome : aucun `mcp-session-id` n'est émis, aucun état n'est conservé entre deux requêtes. Les trois outils exposés étant du pur requête/réponse (aucune notification serveur→client), aucune session n'est nécessaire. Concrètement :
+
+- un connecteur laissé inactif ne peut pas « expirer » côté serveur — il n'y a rien à expirer ;
+- un redémarrage ou un redéploiement du gateway est transparent pour les clients connectés ;
+- l'endpoint peut être scalé horizontalement derrière un load balancer sans affinité de session.
+
+`GET /mcp` et `DELETE /mcp` répondent `405 Method Not Allowed` : sans session, il n'y a ni flux SSE autonome ni terminaison de session à gérer (la spec Streamable HTTP l'autorise explicitement).
+
+### Flow
+
+```
+Claude.ai
+    │  HTTPS + Bearer JWT
+    ▼
+[mcp-http-gateway /mcp]  ──── 401 + WWW-Authenticate si non authentifié
+    │
+    │  (découverte OAuth 2.1)
+    ▼
+[Authorization Server externe]  (Auth0, Keycloak, Authentik, Zitadel, Logto…)
+```
+
+Le gateway agit uniquement comme **Resource Server** : il valide les JWT via JWKS et expose l'URL de l'AS via le Protected Resource Metadata (RFC 9728). Toute la logique OAuth (DCR, PKCE, `/authorize`, `/token`) est déléguée à l'AS externe.
+
+### Variables d'environnement
+
+| Variable | Description |
+|---|---|
+| `MCP_OAUTH_ENABLED` | `true` pour activer la protection OAuth (recommandé en production) |
+| `MCP_PUBLIC_URL` | URL publique canonique du endpoint — ex. `https://gateway.example.com/mcp`. Utilisée comme `resource` (RFC 9728) et `aud` JWT. |
+| `OAUTH_JWKS_URI` | URI du JWKS de l'Authorization Server — ex. `https://your-auth-server/.well-known/jwks.json` |
+| `OAUTH_ISSUER` | Issuer attendu dans les JWT — ex. `https://your-auth-server` |
+
+> Sans `MCP_OAUTH_ENABLED=true`, `/mcp` est ouvert (utile pour les tests locaux). Claude.ai refusera cependant de s'y connecter sans 401 + `WWW-Authenticate`.
+
+### Configuration Claude.ai
+
+Dans Claude.ai → **Paramètres → Connecteurs** → Ajouter un connecteur MCP :
+
+```
+URL : https://gateway.example.com/mcp
+Authentification : OAuth (auto-détectée via /.well-known/oauth-protected-resource)
+```
+
+### Prérequis côté Authorization Server
+
+L'AS doit supporter :
+- **DCR** (RFC 7591) — `registration_endpoint` exposé
+- **PKCE S256** — `code_challenge_methods_supported: ["S256"]`
+- `redirect_uri` autorisé : `https://claude.ai/api/mcp/auth_callback`
+- JWT signés (RS256 ou ES256) avec claims `iss`, `aud=MCP_PUBLIC_URL`, `exp`
+
+### Exposition HTTPS publique
+
+Le endpoint `/mcp` doit être accessible depuis l'IP range `160.79.104.0/21` (Anthropic) en HTTPS. Options :
+
+| Option | Commande / Notes |
+|---|---|
+| **Cloudflare Tunnel** | `cloudflared tunnel --url http://localhost:3500` |
+| **ngrok** | `ngrok http 3500` — idéal pour les tests |
+| **Reverse-proxy** | Caddy / Traefik en frontal avec cert Let's Encrypt |
+
+### Outils exposés
+
+Les mêmes 3 outils que le mode stdio — avec accès direct aux clients MCP internes (sans repasser par HTTP) :
+
+| Outil | Description |
+|---|---|
+| `list_mcps` | Liste les MCPs disponibles avec leur route et description |
+| `list_tools` | Liste les outils d'un MCP donné (`route` requis) |
+| `call_tool` | Appelle un outil (`route`, `tool_name`, `arguments`) |
+
+### Pré-exposition de MCP au démarrage (`EXPOSE_AT_AGENT_STARTUP`)
+
+Par défaut, l'agent ne reçoit que les 3 outils de découverte et doit appeler `list_mcps` /
+`list_tools` pour découvrir les MCP. Pour les MCP fréquemment utilisés, la clé
+`EXPOSE_AT_AGENT_STARTUP` publie leurs outils **directement dans la réponse `tools/list`**,
+nommés `<serveur>__<outil>`, avec description et `inputSchema` complets. L'agent les appelle
+directement, sans passer par `call_tool` et sans aucun aller-retour de découverte.
+
+L'option se déclare **par MCP**, dans son bloc `env` de `config/mcp-servers.json` — au même
+endroit que `MCP_SERVER_ROUTE`, qui est également une directive lue par le gateway :
+
+```json
+{
+  "mcpServers": {
+    "documentor": {
+      "command": "node",
+      "args": ["/chemin/vers/documentor/dist/index.js"],
+      "description": "Documentation manager MCP",
+      "env": {
+        "MCP_SERVER_ROUTE": "/documentor",
+        "EXPOSE_AT_AGENT_STARTUP": "true"
+      }
+    },
+    "scraper": {
+      "command": "node",
+      "args": ["/chemin/vers/scraper/dist/index.js"],
+      "env": {
+        "MCP_SERVER_ROUTE": "/scraper"
+      }
+    }
+  }
+}
+```
+
+Ici `documentor` est pré-exposé ; `scraper`, sans la clé, ne l'est pas et reste accessible
+via `list_mcps` / `list_tools` / `call_tool`. Le `.env` du gateway ne contient **aucune**
+indication relative aux MCP.
+
+La valeur est un booléen : `"true"` (également `"1"`, `"yes"`, `"on"`) ou `"false"`. Toute
+autre valeur est refusée avec un avertissement au démarrage et le MCP n'est pas pré-exposé.
+
+**Pourquoi ce canal ?** Les définitions d'outils passent par `tools/list`, seul canal sans
+limite de taille. Le champ `instructions` du protocole, lui, est plafonné par les clients
+autour de **2 048 caractères** et tronqué silencieusement au-delà — un MCP de 30 outils
+avec ses schémas pèse ~33 000 caractères, il ne peut donc pas y transiter.
+
+**Quand l'activer ?** Le compromis, pour un MCP réellement utilisé :
+
+| | Découverte (défaut) | Pré-exposé |
+|---|---|---|
+| Allers-retours | 3 (`list_mcps`, `list_tools`, `call_tool`) | 1 (appel direct) |
+| Contexte | `list_tools` déverse tous les schémas dans la conversation dès le 1ᵉʳ usage, définitivement | les noms d'outils, puis le schéma des seuls outils utilisés |
+
+À activer donc pour les MCP utilisés dans la majorité des sessions. À laisser en découverte
+pour les MCP occasionnels : un MCP pré-exposé mais inutilisé coûte ses noms d'outils à
+chaque requête, et multiplier les outils similaires dégrade la sélection par l'agent.
+
+Dans tous les cas, le MCP enfant reste hébergé côté gateway : seules ses **définitions**
+sont relayées, les appels sont proxifiés. L'isolation est préservée.
+
+Cette config vit **uniquement côté serveur** et s'applique de façon transparente aux deux
+points d'entrée par lesquels un agent atteint le gateway :
+
+- **endpoint `/mcp` distant** (cas Claude.ai) — les outils proxy sont publiés directement ;
+- **bridge stdio** (`server.js --mcp`, cas local) — au démarrage, le bridge interroge le
+  serveur (`GET /startup-exposition`), publie les outils reçus et route leurs appels vers
+  la bonne route. Le bridge ne connaît pas la config : il ne fait que transmettre ce que le
+  serveur décide. Quand une réponse du gateway porte une nouvelle
+  [révision](#révision), le bridge relit `GET /startup-exposition` et envoie
+  `notifications/tools/list_changed` à l'agent.
+
+---
+
+## Ajouter un MCP
+
+1. Ajouter l'entrée dans `config/mcp-servers.json` avec `MCP_SERVER_ROUTE` dans `env`
+2. Appeler `POST /admin/reload` (voir [Rechargement à chaud](#rechargement-à-chaud)), ou redémarrer le gateway
+
+Aucune modification du MCP n'est nécessaire.