@imenam/mcp-http-gateway 2.0.15 → 2.0.16

package/README.md

@@ -52,6 +52,7 @@ GATEWAY_CONFIG_DIR=./config
 |---|---|---|
 | `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`
@@ -105,6 +106,47 @@ 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`
@@ -651,13 +693,15 @@ points d'entrée par lesquels un agent atteint le gateway :
 - **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.
+  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. Redémarrer le gateway
+2. Appeler `POST /admin/reload` (voir [Rechargement à chaud](#rechargement-à-chaud)), ou redémarrer le gateway
 
 Aucune modification du MCP n'est nécessaire.

package/mcp-endpoint.js

@@ -39,13 +39,14 @@ const tools = [
   },
 ];
 
-function buildMcpServer({ registry, proxyTools = [] }) {
+function buildMcpServer(registry) {
   const server = new Server(
     { name: 'mcp-http-gateway-remote', version: '1.0.0' },
     { capabilities: { tools: {} } }
   );
 
   // Outils des MCP pré-exposés en ALL : publiés tels quels, appelables sans call_tool.
+  const { proxyTools } = registry;
   const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
   const allTools = [...tools, ...proxyTools.map(toolDefinition)];
 
@@ -57,7 +58,7 @@ function buildMcpServer({ registry, proxyTools = [] }) {
     try {
       const proxy = proxyIndex.get(name);
       if (proxy) {
-        const entry = registry.find(m => m.route === proxy.route);
+        const entry = registry.byRoute(proxy.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${proxy.route}` }], isError: true };
         }
@@ -65,14 +66,14 @@ function buildMcpServer({ registry, proxyTools = [] }) {
       }
 
       if (name === 'list_mcps') {
-        const text = registry
+        const text = registry.entries
           .map(m => `- ${m.name} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
           .join('\n');
         return { content: [{ type: 'text', text }] };
       }
 
       if (name === 'list_tools') {
-        const entry = registry.find(m => m.route === args.route);
+        const entry = registry.byRoute(args.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
         }
@@ -81,7 +82,7 @@ function buildMcpServer({ registry, proxyTools = [] }) {
       }
 
       if (name === 'call_tool') {
-        const entry = registry.find(m => m.route === args.route);
+        const entry = registry.byRoute(args.route);
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
         }
@@ -123,7 +124,7 @@ function buildDnsRebindingConfig() {
   return { allowedHosts, allowedOrigins };
 }
 
-export function registerMcpEndpoint(app, { clients, registry, proxyTools }) {
+export function registerMcpEndpoint(app, registry) {
   app.get('/.well-known/oauth-protected-resource', (req, res) => {
     res.json(getProtectedResourceMetadata());
   });
@@ -138,7 +139,7 @@ export function registerMcpEndpoint(app, { clients, registry, proxyTools }) {
   // Conséquence : plus de 404 "session inconnue" après une période d'inactivité ou un redémarrage,
   // et l'endpoint supporte le scale-out multi-instances.
   app.post('/mcp', async (req, res) => {
-    const server = buildMcpServer({ registry, proxyTools });
+    const server = buildMcpServer(registry);
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: undefined,
       enableJsonResponse: true,

package/mcp-mode.js

@@ -47,9 +47,11 @@ function gatewayHeaders(base) {
 }
 
 /** Le seul point de sortie HTTP du relais : tout appel au gateway passe par ici. */
-function gatewayFetch(path, init = {}) {
+async function gatewayFetch(path, init = {}) {
   const headers = gatewayHeaders(init.headers);
-  return fetch(`${GATEWAY_URL}${path}`, headers ? { ...init, headers } : init);
+  const res = await fetch(`${GATEWAY_URL}${path}`, headers ? { ...init, headers } : init);
+  noteRevision(res.headers.get('x-gateway-revision'));
+  return res;
 }
 
 /** Un refus d'authentification mérite mieux qu'un `HTTP 401` nu. */
@@ -594,7 +596,7 @@ async function toolSchema(route, toolName) {
 // pré-exposer les outils de certains MCP directement à l'agent. La config vit uniquement
 // sur le serveur : ce bridge se contente de récupérer ces outils et de les publier, de
 // façon transparente. En cas d'échec (ancien gateway sans la route, gateway protégé par
-// OAuth, etc.), on continue sans pré-exposition.
+// OAuth, etc.), on continue sans pré-exposition. Rend null si les outils n'ont pas pu être lus.
 async function fetchProxyTools() {
   try {
     const res = await gatewayFetch('/startup-exposition');
@@ -603,23 +605,51 @@ async function fetchProxyTools() {
       // Mais un 401/403 ici annonce que TOUS les appels seront refusés — le dire
       // maintenant évite de chercher plus tard. Sans le token, évidemment.
       if (isAuthStatus(res.status)) console.error(`[mcp-mode] ${authErrorText(res.status)}`);
-      return [];
+      return null;
     }
     const { proxyTools } = await res.json();
     return proxyTools ?? [];
   } catch {
-    return [];
+    return null;
   }
 }
 
-const proxyTools = await fetchProxyTools();
-if (proxyTools.length) {
-  console.error(`[mcp-mode] ${proxyTools.length} proxy tool(s) exposed directly from gateway`);
+// --- Suivi des changements de configuration du gateway ---
+//
+// Le gateway renvoie la révision de son état dans l'en-tête `X-Gateway-Revision` de chaque
+// réponse ; elle change quand un MCP est ajouté, retiré ou relancé, et à chaque démarrage du
+// gateway. Dès qu'une réponse en porte une nouvelle, le relais relit les outils pré-exposés,
+// oublie les schémas mis en cache et notifie l'agent par `notifications/tools/list_changed`.
+
+let knownRevision = null;
+let refreshQueue = Promise.resolve();
+
+function noteRevision(revision) {
+  if (!revision || revision === knownRevision) return;
+  const previous = knownRevision;
+  knownRevision = revision;
+  if (previous === null) return;
+  refreshQueue = refreshQueue.then(() => refreshTools(previous)).catch((err) => {
+    console.error(`[mcp-mode] Rafraîchissement des outils impossible : ${err.message}`);
+  });
+}
+
+async function refreshTools(previousRevision) {
+  routeSchemas.clear();
+  const next = await fetchProxyTools();
+  if (next === null) {
+    // Révision remise à l'ancienne valeur : la prochaine réponse du gateway relancera la lecture.
+    knownRevision = previousRevision;
+    return;
+  }
+  setProxyTools(next);
+  await server.sendToolListChanged();
+  console.error(`[mcp-mode] Configuration du gateway modifiée (révision ${knownRevision}) : ${next.length} outil(s) pré-exposé(s)`);
 }
 
 const server = new Server(
   { name: 'mcp-http-gateway-mcp', version: '1.0.0' },
-  { capabilities: { tools: {} } }
+  { capabilities: { tools: { listChanged: true } } }
 );
 
 const tools = [
@@ -654,15 +684,26 @@ const tools = [
   },
 ];
 
-const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
-const allTools = [
-  ...tools,
-  ...proxyTools.map(({ name, description, inputSchema }) => ({
-    name,
-    description,
-    inputSchema: schemaForAgent(inputSchema),
-  })),
-];
+let proxyIndex = new Map();
+let allTools = tools;
+
+function setProxyTools(proxyTools) {
+  proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
+  allTools = [
+    ...tools,
+    ...proxyTools.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema: schemaForAgent(inputSchema),
+    })),
+  ];
+}
+
+const initialProxyTools = (await fetchProxyTools()) ?? [];
+setProxyTools(initialProxyTools);
+if (initialProxyTools.length) {
+  console.error(`[mcp-mode] ${initialProxyTools.length} proxy tool(s) exposed directly from gateway`);
+}
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
 

package/mcp-registry.js

@@ -0,0 +1,234 @@
+import crypto from 'crypto';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { buildProxyTools, overlongProxyNames, parseExposeFlag } from './startup-exposition.js';
+import { HTTP_RELAY_PORT_KEY, parseRelayPort, relayPrefix } from './http-relay.js';
+
+// --- Registre des MCP hébergés par le gateway ---
+//
+// Le registre est la seule source de vérité sur les MCP en service : les routes REST, le
+// relais HTTP, l'endpoint /mcp et la pré-exposition le consultent à chaque requête.
+//
+// `apply(servers)` aligne le registre sur une configuration `mcpServers` :
+//   - MCP absent de la configuration      → son processus est arrêté ;
+//   - MCP nouveau, ou pas en service      → il est lancé ;
+//   - command, args ou env modifiés       → seul ce MCP est relancé ;
+//   - description ou EXPOSE_AT_AGENT_STARTUP seuls modifiés → mis à jour sans relance.
+// Les autres MCP ne sont pas touchés.
+//
+// Chaque changement effectif incrémente la révision, que le gateway renvoie dans l'en-tête
+// `X-Gateway-Revision` : le relais stdio (mcp-mode.js) s'en sert pour rafraîchir ses outils.
+
+export const REVISION_HEADER = 'X-Gateway-Revision';
+
+// Variables système minimales transmises aux MCPs enfants.
+// On exclut délibérément toutes les variables propres au gateway
+// (OPENAI_API_KEY, OAUTH_*, GATEWAY_*, MCP_*, etc.).
+const CHILD_ENV_WHITELIST = new Set([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL',
+  'LANG', 'LC_ALL', 'LC_CTYPE',
+  'TEMP', 'TMP', 'TMPDIR',
+  'USERPROFILE', 'APPDATA', 'LOCALAPPDATA',
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR',
+  'COMSPEC', 'PATHEXT', 'USERNAME',
+  'PROGRAMFILES', 'NODE_PATH',
+]);
+
+// Directives lues par le gateway seul : les modifier ne justifie pas de relancer le MCP.
+const GATEWAY_ONLY_KEYS = new Set(['EXPOSE_AT_AGENT_STARTUP']);
+
+function buildChildEnv(cfgEnv = {}) {
+  const safeEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k]) => CHILD_ENV_WHITELIST.has(k))
+  );
+  return { ...safeEnv, ...cfgEnv };
+}
+
+async function connectMcp(name, cfg) {
+  const transport = new StdioClientTransport({
+    command: cfg.command,
+    args: cfg.args ?? [],
+    env: buildChildEnv(cfg.env),
+  });
+  const client = new Client({ name: 'mcp-gateway', version: '1.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  console.log(`[gateway] Connected: ${name} → ${cfg.env?.MCP_SERVER_ROUTE}`);
+  return client;
+}
+
+/** Empreinte de ce qui définit le processus enfant : la changer impose de le relancer. */
+function processKey(cfg) {
+  const env = Object.entries(cfg.env ?? {})
+    .filter(([key]) => !GATEWAY_ONLY_KEYS.has(key))
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return JSON.stringify([cfg.command, cfg.args ?? [], env]);
+}
+
+/**
+ * Lit les directives gateway d'un MCP. Lève une erreur si le MCP ne peut pas être servi.
+ */
+function readDirectives(name, cfg) {
+  const route = cfg.env?.MCP_SERVER_ROUTE;
+  if (!route) throw new Error('no MCP_SERVER_ROUTE defined');
+
+  const rawExpose = cfg.env?.EXPOSE_AT_AGENT_STARTUP;
+  const { value: exposeAtStartup, valid } = parseExposeFlag(rawExpose);
+  if (!valid) {
+    console.warn(`[gateway] "${name}": invalid EXPOSE_AT_AGENT_STARTUP="${rawExpose}" (expected true | false) — not pre-exposed`);
+  }
+
+  const rawRelayPort = cfg.env?.[HTTP_RELAY_PORT_KEY];
+  const { port: relayPort, valid: relayPortValid } = parseRelayPort(rawRelayPort);
+  if (!relayPortValid) {
+    throw new Error(`invalid ${HTTP_RELAY_PORT_KEY}="${rawRelayPort}" (expected a port 1-65535)`);
+  }
+
+  return { route, exposeAtStartup, relayPort, description: cfg.description ?? null };
+}
+
+export class McpRegistry {
+  /** Entrées en service, dans l'ordre de la configuration. */
+  entries = [];
+  proxyTools = [];
+  /** Préfixes `<route>/http` des MCP qui déclarent un relais HTTP. */
+  relayPrefixes = new Set();
+
+  #bootId = crypto.randomUUID().slice(0, 8);
+  #generation = 0;
+  #queue = Promise.resolve();
+  #onToolsLoaded;
+
+  /**
+   * @param {{ onToolsLoaded?: (name: string, tools: object[]) => void }} options
+   *   `onToolsLoaded` est appelé à chaque lancement d'un MCP, avec ses outils.
+   */
+  constructor({ onToolsLoaded } = {}) {
+    this.#onToolsLoaded = onToolsLoaded ?? (() => {});
+  }
+
+  /** Identifiant de l'état servi : change à chaque démarrage du gateway et à chaque changement effectif. */
+  get revision() {
+    return `${this.#bootId}.${this.#generation}`;
+  }
+
+  byRoute(route) {
+    return this.entries.find((entry) => entry.route === route) ?? null;
+  }
+
+  byName(name) {
+    return this.entries.find((entry) => entry.name === name) ?? null;
+  }
+
+  /**
+   * Aligne le registre sur `servers` (le bloc `mcpServers` de la configuration).
+   * Les appels sont sérialisés. Rend une ligne par MCP concerné :
+   * `{ name, action, ok, error? }`, `action` ∈ started | restarted | stopped | updated | unchanged.
+   */
+  apply(servers) {
+    const run = this.#queue.then(() => this.#apply(servers));
+    this.#queue = run.catch(() => {});
+    return run;
+  }
+
+  async closeAll() {
+    await Promise.allSettled(this.entries.map((entry) => entry.client.close()));
+  }
+
+  async #apply(servers) {
+    const results = [];
+    const wanted = new Map(Object.entries(servers ?? {}));
+    const restarting = new Set();
+    let changed = false;
+
+    // Arrêts d'abord : un MCP relancé ou une route reprise ne doivent pas croiser l'ancien processus.
+    for (const entry of [...this.entries]) {
+      const cfg = wanted.get(entry.name);
+      if (cfg && processKey(cfg) === entry.processKey) continue;
+      await this.#stop(entry);
+      changed = true;
+      if (cfg) restarting.add(entry.name);
+      else results.push({ name: entry.name, action: 'stopped', ok: true });
+    }
+
+    for (const [name, cfg] of wanted) {
+      const current = this.byName(name);
+
+      if (current) {
+        const { description, exposeAtStartup } = readDirectives(name, cfg);
+        const updated = current.description !== description || current.exposeAtStartup !== exposeAtStartup;
+        current.description = description;
+        current.exposeAtStartup = exposeAtStartup;
+        if (updated) changed = true;
+        results.push({ name, action: updated ? 'updated' : 'unchanged', ok: true });
+        continue;
+      }
+
+      const action = restarting.has(name) ? 'restarted' : 'started';
+      try {
+        await this.#start(name, cfg);
+        changed = true;
+        results.push({ name, action, ok: true });
+      } catch (err) {
+        console.error(`[gateway] Failed to start "${name}": ${err.message}`);
+        results.push({ name, action, ok: false, error: err.message });
+      }
+    }
+
+    // Ordre de la configuration, conservé pour list_mcps, /mcps et la pré-exposition.
+    const order = [...wanted.keys()];
+    this.entries.sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
+
+    if (changed) {
+      this.#generation += 1;
+      this.#refreshDerived();
+    }
+    return results;
+  }
+
+  async #start(name, cfg) {
+    const directives = readDirectives(name, cfg);
+    if (this.byRoute(directives.route)) {
+      throw new Error(`route ${directives.route} already served by "${this.byRoute(directives.route).name}"`);
+    }
+    const client = await connectMcp(name, cfg);
+    let tools;
+    try {
+      ({ tools } = await client.listTools());
+    } catch (err) {
+      await client.close().catch(() => {});
+      throw err;
+    }
+    this.entries.push({ name, ...directives, tools, client, processKey: processKey(cfg) });
+    if (directives.relayPort) {
+      console.log(`[gateway] HTTP relay: ${relayPrefix(directives.route)}/* → 127.0.0.1:${directives.relayPort} (${name})`);
+    }
+    this.#onToolsLoaded(name, tools);
+  }
+
+  async #stop(entry) {
+    this.entries = this.entries.filter((e) => e !== entry);
+    try {
+      await entry.client.close();
+    } catch (err) {
+      console.error(`[gateway] Error while closing "${entry.name}":`, err.message);
+    }
+    console.log(`[gateway] Stopped: ${entry.name}`);
+  }
+
+  #refreshDerived() {
+    this.relayPrefixes = new Set(
+      this.entries.filter((e) => e.relayPort).map((e) => relayPrefix(e.route))
+    );
+    this.proxyTools = buildProxyTools(this.entries);
+
+    const preExposed = this.entries.filter((e) => e.exposeAtStartup);
+    if (preExposed.length) {
+      console.log(`[gateway] Pre-exposed at agent startup: ${preExposed.map((e) => e.name).join(', ')} — ${this.proxyTools.length} tool(s) published directly in tools/list`);
+    }
+    const overlong = overlongProxyNames(this.proxyTools);
+    if (overlong.length) {
+      console.warn(`[gateway] WARNING: proxy tool name(s) may exceed client limits once prefixed: ${overlong.join(', ')}`);
+    }
+    console.log(`[gateway] Revision ${this.revision} — ${this.entries.length} MCP(s) in service`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-http-gateway",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "type": "module",
   "description": "HTTP gateway that exposes MCP servers as REST routes — bridge between MCP and any HTTP-capable agent",
   "main": "server.js",
@@ -17,7 +17,8 @@
     "startup-exposition.js",
     "http-relay.js",
     "gateway-exec.js",
-    "gateway-watch.js"
+    "gateway-watch.js",
+    "mcp-registry.js"
   ],
   "scripts": {
     "start": "node server.js",

package/server.js

@@ -13,17 +13,16 @@ if (process.argv.includes('--watch')) {
   // Process stays alive: the MCP transport keeps stdin open until the client disconnects
 }
 
+import crypto from 'crypto';
 import { readFileSync } from 'fs';
 import path from 'path';
 import express from 'express';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { initDb, getOrComputeToolEmbedding, getAllToolEmbeddings } from './embeddings/db.js';
 import { getEmbedding, cosineSimilarity } from './embeddings/vectorizer.js';
 import { registerMcpEndpoint } from './mcp-endpoint.js';
-import { buildProxyTools, overlongProxyNames, parseExposeFlag } from './startup-exposition.js';
 import { createMcpTokenVerifier } from './auth.js';
-import { HTTP_RELAY_PORT_KEY, parseRelayPort, relayPrefix, isRelayPath, createHttpRelay } from './http-relay.js';
+import { relayPrefix, isRelayPath, createHttpRelay } from './http-relay.js';
+import { McpRegistry, REVISION_HEADER } from './mcp-registry.js';
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { rateLimit } from 'express-rate-limit';
 
@@ -38,65 +37,61 @@ function normalizeCfg(cfg) {
   return { ...cfg, command, args, env };
 }
 
-// Variables système minimales transmises aux MCPs enfants.
-// On exclut délibérément toutes les variables propres au gateway
-// (OPENAI_API_KEY, OAUTH_*, GATEWAY_*, MCP_*, etc.).
-const CHILD_ENV_WHITELIST = new Set([
-  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL',
-  'LANG', 'LC_ALL', 'LC_CTYPE',
-  'TEMP', 'TMP', 'TMPDIR',
-  'USERPROFILE', 'APPDATA', 'LOCALAPPDATA',
-  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR',
-  'COMSPEC', 'PATHEXT', 'USERNAME',
-  'PROGRAMFILES', 'NODE_PATH',
-]);
-
-function buildChildEnv(cfgEnv = {}) {
-  const safeEnv = Object.fromEntries(
-    Object.entries(process.env).filter(([k]) => CHILD_ENV_WHITELIST.has(k))
-  );
-  return { ...safeEnv, ...cfgEnv };
-}
+// --- Routes des MCP ---
+
+/**
+ * Routes `<route>/tools`, `<route>/tools/:toolName` et `<route>/http/*` de chaque MCP,
+ * résolues sur le registre à chaque requête.
+ */
+function mcpRoutes(registry) {
+  return async (req, res, next) => {
+    for (const entry of registry.entries) {
+      const { route, name, client } = entry;
+      if (req.path !== route && !req.path.startsWith(`${route}/`)) continue;
+      const rest = req.path.slice(route.length);
+
+      if (entry.relayPort && (rest === '/http' || rest.startsWith('/http/'))) {
+        req.url = req.url.slice(relayPrefix(route).length) || '/';
+        return createHttpRelay({ name, port: entry.relayPort })(req, res);
+      }
 
-// --- MCP client ---
+      if (req.method === 'GET' && rest === '/tools') {
+        try {
+          const { tools } = await client.listTools();
+          return res.json(tools);
+        } catch (err) {
+          console.error(`[${name}] listTools error:`, err.message);
+          return res.status(500).json({ error: err.message });
+        }
+      }
 
-async function connectMcp(name, cfg) {
-  const transport = new StdioClientTransport({
-    command: cfg.command,
-    args: cfg.args ?? [],
-    env: buildChildEnv(cfg.env),
-  });
-  const client = new Client({ name: 'mcp-gateway', version: '1.0.0' }, { capabilities: {} });
-  await client.connect(transport);
-  console.log(`[gateway] Connected: ${name} → ${cfg.env?.MCP_SERVER_ROUTE}`);
-  return client;
+      const toolMatch = /^\/tools\/([^/]+)$/.exec(rest);
+      if (req.method === 'POST' && toolMatch) {
+        const toolName = decodeURIComponent(toolMatch[1]);
+        try {
+          const result = await client.callTool({ name: toolName, arguments: req.body ?? {} });
+          return res.json(result);
+        } catch (err) {
+          console.error(`[${name}] callTool(${toolName}) error:`, err.message);
+          return res.status(500).json({ error: err.message });
+        }
+      }
+    }
+    return next();
+  };
 }
 
-// --- Routes ---
-
-function registerMcpRoutes(app, route, client, name) {
-  app.get(`${route}/tools`, async (req, res) => {
-    try {
-      const { tools } = await client.listTools();
-      res.json(tools);
-    } catch (err) {
-      console.error(`[${name}] listTools error:`, err.message);
-      res.status(500).json({ error: err.message });
-    }
-  });
+function readServers(configPath) {
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  return config.mcpServers ?? {};
+}
 
-  app.post(`${route}/tools/:toolName`, async (req, res) => {
-    try {
-      const result = await client.callTool({
-        name: req.params.toolName,
-        arguments: req.body ?? {},
-      });
-      res.json(result);
-    } catch (err) {
-      console.error(`[${name}] callTool(${req.params.toolName}) error:`, err.message);
-      res.status(500).json({ error: err.message });
-    }
-  });
+/** Comparaison à temps constant du jeton d'administration présenté. */
+function adminTokenMatches(presented, expected) {
+  if (typeof presented !== 'string') return false;
+  const a = crypto.createHash('sha256').update(presented).digest();
+  const b = crypto.createHash('sha256').update(expected).digest();
+  return crypto.timingSafeEqual(a, b);
 }
 
 // --- Bootstrap ---
@@ -113,8 +108,18 @@ async function main() {
     ? path.resolve(process.env.GATEWAY_CONFIG_DIR)
     : path.join(process.cwd(), 'config');
   const configPath = path.join(configDir, 'mcp-servers.json');
-  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-  const servers = config.mcpServers ?? {};
+  const servers = readServers(configPath);
+
+  const registry = new McpRegistry({
+    onToolsLoaded: (name, tools) => {
+      for (const tool of tools) {
+        if (!tool.description) continue;
+        getOrComputeToolEmbedding(name, tool, getEmbedding).catch(err =>
+          console.error(`[gateway] Embedding error for ${name}::${tool.name}:`, err.message)
+        );
+      }
+    },
+  });
 
   const app = express();
   if (process.env.TRUST_PROXY) {
@@ -127,10 +132,39 @@ async function main() {
   // qui repartirait sinon en « 413 Payload Too Large » sans explication.
   const BODY_LIMIT = process.env.GATEWAY_BODY_LIMIT ?? '32mb';
   const jsonParser = express.json({ type: '*/*', limit: BODY_LIMIT });
+  app.use((req, res, next) => {
+    res.setHeader(REVISION_HEADER, registry.revision);
+    next();
+  });
+
+  // Rechargement de la configuration, réservé au détenteur de GATEWAY_ADMIN_TOKEN.
+  // Seuls les MCP dont la configuration a changé sont arrêtés, lancés ou relancés.
+  const ADMIN_TOKEN = process.env.GATEWAY_ADMIN_TOKEN?.trim() || null;
+  if (ADMIN_TOKEN) {
+    app.post('/admin/reload', async (req, res) => {
+      if (!adminTokenMatches(req.get('X-Gateway-Admin-Token'), ADMIN_TOKEN)) {
+        return res.status(401).json({ error: 'Unauthorized' });
+      }
+      let nextServers;
+      try {
+        nextServers = readServers(configPath);
+      } catch (err) {
+        console.error('[gateway] Reload refused, unreadable configuration:', err.message);
+        return res.status(400).json({ error: `Unreadable configuration ${configPath}: ${err.message}` });
+      }
+      const results = await registry.apply(nextServers);
+      const summary = results
+        .filter(r => r.action !== 'unchanged')
+        .map(r => `${r.name}: ${r.action}${r.ok ? '' : ' (failed)'}`);
+      console.log(`[gateway] Reload — ${summary.length ? summary.join(', ') : 'no change'}`);
+      return res.json({ revision: registry.revision, results });
+    });
+    console.log('[gateway] Admin endpoint enabled: POST /admin/reload');
+  }
+
   // Les routes de relais HTTP transmettent leur corps en flux, sans le lire ni le borner.
-  const relayPrefixes = new Set();
   app.use((req, res, next) =>
-    isRelayPath(relayPrefixes, req.path) ? next() : jsonParser(req, res, next)
+    isRelayPath(registry.relayPrefixes, req.path) ? next() : jsonParser(req, res, next)
   );
 
   const globalWindowMin = parseInt(process.env.RATE_LIMIT_GLOBAL_WINDOW_MINUTES ?? '15', 10);
@@ -196,53 +230,8 @@ async function main() {
   const dbPath = path.join(dataDir, 'embeddings', 'embeddings.db');
   initDb(dbPath);
 
-  const clients = [];
-  const registry = []; // { name, route, description, tools, exposeAtStartup }
-
-  for (const [name, cfg] of Object.entries(servers)) {
-    const route = cfg.env?.MCP_SERVER_ROUTE;
-    if (!route) {
-      console.warn(`[gateway] Skipping "${name}": no MCP_SERVER_ROUTE defined`);
-      continue;
-    }
-
-    // Directive gateway déclarée par MCP dans son bloc `env` (comme MCP_SERVER_ROUTE) :
-    // pré-expose ou non ses outils à l'agent. Absente → MCP non pré-exposé.
-    const rawExpose = cfg.env?.EXPOSE_AT_AGENT_STARTUP;
-    const { value: exposeAtStartup, valid } = parseExposeFlag(rawExpose);
-    if (!valid) {
-      console.warn(`[gateway] "${name}": invalid EXPOSE_AT_AGENT_STARTUP="${rawExpose}" (expected true | false) — not pre-exposed`);
-    }
-
-    const rawRelayPort = cfg.env?.[HTTP_RELAY_PORT_KEY];
-    const { port: relayPort, valid: relayPortValid } = parseRelayPort(rawRelayPort);
-    if (!relayPortValid) {
-      console.error(`[gateway] Skipping "${name}": invalid ${HTTP_RELAY_PORT_KEY}="${rawRelayPort}" (expected a port 1-65535)`);
-      continue;
-    }
-
-    try {
-      const client = await connectMcp(name, cfg);
-      const { tools } = await client.listTools();
-      clients.push(client);
-      registry.push({ name, route, description: cfg.description ?? null, tools, client, exposeAtStartup, relayPort });
-      registerMcpRoutes(app, route, client, name);
-      if (relayPort) {
-        const prefix = relayPrefix(route);
-        relayPrefixes.add(prefix);
-        app.use(prefix, createHttpRelay({ name, port: relayPort }));
-        console.log(`[gateway] HTTP relay: ${prefix}/* → 127.0.0.1:${relayPort} (${name})`);
-      }
-      for (const tool of tools) {
-        if (!tool.description) continue;
-        getOrComputeToolEmbedding(name, tool, getEmbedding).catch(err =>
-          console.error(`[gateway] Embedding error for ${name}::${tool.name}:`, err.message)
-        );
-      }
-    } catch (err) {
-      console.error(`[gateway] Failed to connect "${name}":`, err.message);
-    }
-  }
+  await registry.apply(servers);
+  app.use(mcpRoutes(registry));
 
   app.get('/tools/search', searchLimiter, async (req, res) => {
     const q = req.query.q?.trim();
@@ -251,12 +240,13 @@ async function main() {
     try {
       const queryEmbedding = await getEmbedding(q);
       const results = getAllToolEmbeddings()
+        .filter(row => registry.byName(row.mcp_name)?.tools.some(t => t.name === row.tool_name))
         .map(row => ({ ...row, score: cosineSimilarity(queryEmbedding, row.embedding) }))
         .sort((a, b) => b.score - a.score)
         .slice(0, limit)
         .map(({ mcp_name, tool_name, description, score }) => ({
           mcp_name,
-          mcp_description: registry.find(r => r.name === mcp_name)?.description ?? null,
+          mcp_description: registry.byName(mcp_name)?.description ?? null,
           tool_name,
           description,
           score,
@@ -270,7 +260,7 @@ async function main() {
 
   app.get('/mcp-definitions', (req, res) => {
     res.json(
-      registry.map(({ name, route, description, tools }) => ({
+      registry.entries.map(({ name, route, description, tools }) => ({
         id: name,
         route,
         description,
@@ -283,19 +273,8 @@ async function main() {
   // `tools/list`. Exposés en HTTP pour que le bridge stdio (server.js --mcp /
   // mcp-mode.js) puisse les récupérer et les relayer à l'agent de façon transparente —
   // la config vit uniquement côté serveur, le bridge se contente de transmettre.
-  const proxyTools = buildProxyTools(registry);
-
-  const preExposed = registry.filter(r => r.exposeAtStartup);
-  if (preExposed.length) {
-    console.log(`[gateway] Pre-exposed at agent startup: ${preExposed.map(r => r.name).join(', ')} — ${proxyTools.length} tool(s) published directly in tools/list`);
-  }
-  const overlong = overlongProxyNames(proxyTools);
-  if (overlong.length) {
-    console.warn(`[gateway] WARNING: proxy tool name(s) may exceed client limits once prefixed: ${overlong.join(', ')}`);
-  }
-
   app.get('/startup-exposition', (req, res) => {
-    res.json({ proxyTools });
+    res.json({ proxyTools: registry.proxyTools, revision: registry.revision });
   });
 
   app.get('/mcps', (req, res) => {
@@ -307,7 +286,7 @@ async function main() {
       '',
       '## Serveurs',
       '',
-      ...registry.map(({ name, route, description, relayPort }) =>
+      ...registry.entries.map(({ name, route, description, relayPort }) =>
         `### ${name}\n- **Route** : \`${route}\`\n- **Description** : ${description ?? 'Non renseignée'}` +
         (relayPort ? `\n- **Relais HTTP** : \`${relayPrefix(route)}/*\`` : '')
       ),
@@ -315,7 +294,7 @@ async function main() {
     res.type('text/plain').send(lines.join('\n'));
   });
 
-  registerMcpEndpoint(app, { clients, registry, proxyTools });
+  registerMcpEndpoint(app, registry);
 
   const httpServer = app.listen(GATEWAY_PORT, GATEWAY_HOST, () => {
     console.log(`[gateway] Listening on http://${GATEWAY_HOST}:${GATEWAY_PORT}`);
@@ -328,7 +307,7 @@ async function main() {
 
   const shutdown = async () => {
     console.log('[gateway] Shutting down...');
-    await Promise.allSettled(clients.map(c => c.close()));
+    await registry.closeAll();
     process.exit(0);
   };