@imenam/mcp-http-gateway 2.0.7 → 2.0.8

package/README.md

@@ -182,6 +182,42 @@ GATEWAY_URL=http://host.docker.internal:3500 npx @imenam/mcp-http-gateway --mcp
 
 > `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. |
+
+> 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 :
@@ -198,7 +234,15 @@ L'agent découvre d'abord les MCPs disponibles, explore les outils d'un MCP si b
 
 ## Mode MCP distant (HTTPS / Claude.ai)
 
-Le gateway expose également un **endpoint MCP natif** sur `/mcp` via le transport **Streamable HTTP** (sessions `mcp-session-id`). Ce mode permet à Claude.ai — et à tout client MCP distant compatible — de se connecter directement au gateway, sans intermédiaire.
+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
 
@@ -263,6 +307,75 @@ Les mêmes 3 outils que le mode stdio — avec accès direct aux clients MCP int
 | `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

package/mcp-endpoint.js

@@ -1,12 +1,11 @@
-import { randomUUID } from 'node:crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
-  isInitializeRequest,
 } from '@modelcontextprotocol/sdk/types.js';
 import { getProtectedResourceMetadata } from './auth.js';
+import { toolDefinition } from './startup-exposition.js';
 
 const tools = [
   {
@@ -40,18 +39,31 @@ const tools = [
   },
 ];
 
-function buildMcpServer({ registry }) {
+function buildMcpServer({ registry, proxyTools = [] }) {
   const server = new Server(
     { name: 'mcp-http-gateway-remote', version: '1.0.0' },
     { capabilities: { tools: {} } }
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  // Outils des MCP pré-exposés en ALL : publiés tels quels, appelables sans call_tool.
+  const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
+  const allTools = [...tools, ...proxyTools.map(toolDefinition)];
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args = {} } = request.params;
 
     try {
+      const proxy = proxyIndex.get(name);
+      if (proxy) {
+        const entry = registry.find(m => m.route === proxy.route);
+        if (!entry) {
+          return { content: [{ type: 'text', text: `No MCP found for route: ${proxy.route}` }], isError: true };
+        }
+        return await entry.client.callTool({ name: proxy.toolName, arguments: args });
+      }
+
       if (name === 'list_mcps') {
         const text = registry
           .map(m => `- ${m.name} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
@@ -64,7 +76,7 @@ function buildMcpServer({ registry }) {
         if (!entry) {
           return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
         }
-        const text = JSON.stringify(entry.tools, null, 2);
+        const text = JSON.stringify(entry.tools);
         return { content: [{ type: 'text', text }] };
       }
 
@@ -111,7 +123,7 @@ function buildDnsRebindingConfig() {
   return { allowedHosts, allowedOrigins };
 }
 
-export function registerMcpEndpoint(app, { clients, registry }) {
+export function registerMcpEndpoint(app, { clients, registry, proxyTools }) {
   app.get('/.well-known/oauth-protected-resource', (req, res) => {
     res.json(getProtectedResourceMetadata());
   });
@@ -120,87 +132,28 @@ export function registerMcpEndpoint(app, { clients, registry }) {
   console.log('[gateway] DNS rebinding protection — allowedHosts:', allowedHosts);
   console.log('[gateway] DNS rebinding protection — allowedOrigins:', allowedOrigins);
 
-  const SESSION_TTL_MS = parseInt(process.env.SESSION_TTL_MINUTES ?? '30', 10) * 60_000;
-  const SESSION_MAX = parseInt(process.env.SESSION_MAX_COUNT ?? '100', 10);
-  console.log(`[gateway] Session limits — TTL: ${SESSION_TTL_MS / 60_000} min, max: ${SESSION_MAX}`);
-
-  const transports = {};
+  // Mode stateless : un Server + un transport éphémères par requête, aucun état inter-requêtes.
+  // Les trois outils exposés sont du pur requête/réponse (aucune notification serveur→client,
+  // ni sampling, ni subscription), donc aucune session n'est nécessaire.
+  // 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 transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+      enableDnsRebindingProtection: true,
+      allowedHosts,
+      allowedOrigins,
+    });
+
+    res.on('close', () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
 
-  const cleanupExpiredSessions = () => {
-    const now = Date.now();
-    for (const [sid, entry] of Object.entries(transports)) {
-      if (now - entry.lastActivity > SESSION_TTL_MS) {
-        console.log(`[mcp-endpoint] Session ${sid} expired (TTL), closing.`);
-        entry.transport.close?.();
-        delete transports[sid];
-      }
-    }
-  };
-
-  const cleanupTimer = setInterval(cleanupExpiredSessions, 60_000);
-  cleanupTimer.unref();
-
-  const handleMcpRequest = async (req, res) => {
     try {
-      const sessionId = req.headers['mcp-session-id'];
-      const entry = sessionId ? transports[sessionId] : undefined;
-
-      let transport;
-
-      if (!entry && isInitializeRequest(req.body)) {
-        const activeCount = Object.keys(transports).length;
-        if (activeCount >= SESSION_MAX) {
-          console.warn(`[mcp-endpoint] Session cap reached (${activeCount}/${SESSION_MAX}), rejecting initialize.`);
-          return res.status(429).json({
-            jsonrpc: '2.0',
-            error: { code: -32000, message: 'Too Many Requests: session limit reached' },
-            id: null,
-          });
-        }
-
-        const ownerSub = req.auth?.sub ?? null;
-        transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
-          enableDnsRebindingProtection: true,
-          allowedHosts,
-          allowedOrigins,
-          onsessioninitialized: (sid) => {
-            transports[sid] = { transport, ownerSub, lastActivity: Date.now() };
-          },
-        });
-        transport.onclose = () => {
-          if (transport.sessionId) delete transports[transport.sessionId];
-        };
-        await buildMcpServer({ registry }).connect(transport);
-      } else if (!entry) {
-        if (sessionId) {
-          // Session ID fourni mais inconnu (restart serveur, session expirée) → 404
-          // Le client MCP doit réinitialiser une nouvelle session (spec MCP §Session Management §4)
-          return res.status(404).json({
-            jsonrpc: '2.0',
-            error: { code: -32000, message: 'Session not found' },
-            id: null,
-          });
-        }
-        // Pas de session ID sur une requête non-initialize → 400
-        return res.status(400).json({
-          jsonrpc: '2.0',
-          error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
-          id: null,
-        });
-      } else {
-        if (entry.ownerSub !== null && req.auth?.sub !== entry.ownerSub) {
-          console.warn(`[mcp-endpoint] Session hijacking attempt: session owned by "${entry.ownerSub}", request by "${req.auth?.sub}"`);
-          return res.status(403).json({
-            jsonrpc: '2.0',
-            error: { code: -32000, message: 'Forbidden: session belongs to another client' },
-            id: null,
-          });
-        }
-        entry.lastActivity = Date.now();
-        transport = entry.transport;
-      }
-
+      await server.connect(transport);
       await transport.handleRequest(req, res, req.body);
     } catch (err) {
       console.error('[mcp-endpoint] handleMcpRequest error:', err);
@@ -212,11 +165,17 @@ export function registerMcpEndpoint(app, { clients, registry }) {
         });
       }
     }
-  };
+  });
 
-  app.post('/mcp', handleMcpRequest);
-  app.get('/mcp', handleMcpRequest);
-  app.delete('/mcp', handleMcpRequest);
+  // Sans session, il n'y a ni flux SSE autonome (GET) ni terminaison de session (DELETE).
+  // La spec Streamable HTTP autorise explicitement 405 sur ces deux méthodes.
+  const methodNotAllowed = (req, res) => res.status(405).json({
+    jsonrpc: '2.0',
+    error: { code: -32000, message: 'Method not allowed' },
+    id: null,
+  });
+  app.get('/mcp', methodNotAllowed);
+  app.delete('/mcp', methodNotAllowed);
 
-  console.log('[gateway] MCP remote endpoint registered at /mcp');
+  console.log('[gateway] MCP remote endpoint registered at /mcp (stateless)');
 }

package/mcp-mode.js

@@ -13,8 +13,91 @@ if (!GATEWAY_URL) {
   process.exit(1);
 }
 
+// Token porteur optionnel. Utile quand le gateway n'est pas joint en direct mais à
+// travers un frontal qui authentifie (hub mcp-gateway-manager, reverse-proxy…).
+//
+// ATTENTION — `import 'dotenv/config'` ci-dessus charge le `.env` du **répertoire
+// courant de l'agent**, pas celui du gateway. dotenv n'écrase jamais une variable
+// déjà présente dans l'environnement : le bloc `env` de la config MCP l'emporte
+// donc toujours. En revanche, si le bloc `env` ne définit PAS GATEWAY_TOKEN, un
+// `.env` traînant dans le projet de l'agent peut en fournir un. C'est le
+// comportement historique (GATEWAY_URL est dans le même cas), on ne le change pas.
+//
+// Le token n'est JAMAIS journalisé, même tronqué.
+const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN?.trim() || undefined;
+
+/**
+ * En-têtes d'un appel sortant du relais.
+ *
+ * Sans GATEWAY_TOKEN, rien n'est ajouté et l'appel part exactement comme avant —
+ * la rétrocompatibilité avec les déploiements existants est stricte.
+ */
+function gatewayHeaders(base) {
+  const headers = { ...base };
+  if (GATEWAY_TOKEN) headers.Authorization = `Bearer ${GATEWAY_TOKEN}`;
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+/** Le seul point de sortie HTTP du relais : tout appel au gateway passe par ici. */
+function gatewayFetch(path, init = {}) {
+  const headers = gatewayHeaders(init.headers);
+  return fetch(`${GATEWAY_URL}${path}`, headers ? { ...init, headers } : init);
+}
+
+/** Un refus d'authentification mérite mieux qu'un `HTTP 401` nu. */
+function isAuthStatus(status) {
+  return status === 401 || status === 403;
+}
+
+function authErrorText(status) {
+  return GATEWAY_TOKEN
+    ? `Accès refusé par le gateway (HTTP ${status}) : le GATEWAY_TOKEN fourni est invalide, ` +
+        `révoqué, ou ne correspond pas à cette gateway. Régénérez-le puis mettez à jour la ` +
+        `variable GATEWAY_TOKEN dans la configuration de ce serveur MCP.`
+    : `Accès refusé par le gateway (HTTP ${status}) : aucun GATEWAY_TOKEN n'est défini alors ` +
+        `que ${GATEWAY_URL} en exige un. Ajoutez GATEWAY_TOKEN dans le bloc « env » de la ` +
+        `configuration de ce serveur MCP.`;
+}
+
+/** Message d'erreur d'un appel outil — inchangé hors 401/403. */
+function gatewayErrorText(status, body) {
+  return isAuthStatus(status) ? authErrorText(status) : `Gateway error ${status}: ${body}`;
+}
+
+/** Message d'une erreur relancée — inchangé hors 401/403. */
+function gatewayThrowText(status) {
+  return isAuthStatus(status) ? authErrorText(status) : `HTTP ${status}`;
+}
+
 // --- MCP Server ---
 
+// Le gateway (mode serveur HTTP) peut être paramétré (EXPOSE_AT_AGENT_STARTUP) pour
+// 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.
+async function fetchProxyTools() {
+  try {
+    const res = await gatewayFetch('/startup-exposition');
+    if (!res.ok) {
+      // La pré-exposition reste optionnelle : on n'interrompt pas le démarrage.
+      // 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 [];
+    }
+    const { proxyTools } = await res.json();
+    return proxyTools ?? [];
+  } catch {
+    return [];
+  }
+}
+
+const proxyTools = await fetchProxyTools();
+if (proxyTools.length) {
+  console.error(`[mcp-mode] ${proxyTools.length} proxy tool(s) exposed directly from gateway`);
+}
+
 const server = new Server(
   { name: 'mcp-http-gateway-mcp', version: '1.0.0' },
   { capabilities: { tools: {} } }
@@ -52,15 +135,32 @@ const tools = [
   },
 ];
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
+const allTools = [...tools, ...proxyTools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
   try {
+    const proxy = proxyIndex.get(name);
+    if (proxy) {
+      const res = await gatewayFetch(`${proxy.route}/tools/${proxy.toolName}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(args ?? {}),
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        return { content: [{ type: 'text', text: gatewayErrorText(res.status, text) }], isError: true };
+      }
+      return await res.json();
+    }
+
     if (name === 'list_mcps') {
-      const res = await fetch(`${GATEWAY_URL}/mcp-definitions`);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const res = await gatewayFetch('/mcp-definitions');
+      if (!res.ok) throw new Error(gatewayThrowText(res.status));
       const definitions = await res.json();
       const text = definitions
         .map(m => `- ${m.id} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
@@ -69,22 +169,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 
     if (name === 'list_tools') {
-      const res = await fetch(`${GATEWAY_URL}${args.route}/tools`);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const res = await gatewayFetch(`${args.route}/tools`);
+      if (!res.ok) throw new Error(gatewayThrowText(res.status));
       const toolsList = await res.json();
-      const text = JSON.stringify(toolsList, null, 2);
+      const text = JSON.stringify(toolsList);
       return { content: [{ type: 'text', text }] };
     }
 
     if (name === 'call_tool') {
-      const res = await fetch(`${GATEWAY_URL}${args.route}/tools/${args.tool_name}`, {
+      const res = await gatewayFetch(`${args.route}/tools/${args.tool_name}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(args.arguments ?? {}),
       });
       if (!res.ok) {
         const text = await res.text();
-        return { content: [{ type: 'text', text: `Gateway error ${res.status}: ${text}` }], isError: true };
+        return { content: [{ type: 'text', text: gatewayErrorText(res.status, text) }], isError: true };
       }
       return await res.json();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-http-gateway",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "type": "module",
   "description": "HTTP gateway that exposes MCP servers as REST routes — bridge between MCP and any HTTP-capable agent",
   "main": "server.js",

package/server.js

@@ -14,6 +14,7 @@ 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 { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { rateLimit } from 'express-rate-limit';
@@ -179,7 +180,7 @@ async function main() {
   initDb(dbPath);
 
   const clients = [];
-  const registry = []; // { name, route, description, tools }
+  const registry = []; // { name, route, description, tools, exposeAtStartup }
 
   for (const [name, cfg] of Object.entries(servers)) {
     const route = cfg.env?.MCP_SERVER_ROUTE;
@@ -188,11 +189,19 @@ async function main() {
       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`);
+    }
+
     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 });
+      registry.push({ name, route, description: cfg.description ?? null, tools, client, exposeAtStartup });
       registerMcpRoutes(app, route, client, name);
       for (const tool of tools) {
         if (!tool.description) continue;
@@ -240,6 +249,25 @@ async function main() {
     );
   });
 
+  // Outils des MCP pré-exposés (EXPOSE_AT_AGENT_STARTUP), publiés tels quels dans
+  // `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 });
+  });
+
   app.get('/mcps', (req, res) => {
     const lines = [
       '# MCP Gateway — Serveurs disponibles',
@@ -256,7 +284,7 @@ async function main() {
     res.type('text/plain').send(lines.join('\n'));
   });
 
-  registerMcpEndpoint(app, { clients, registry });
+  registerMcpEndpoint(app, { clients, registry, proxyTools });
 
   const httpServer = app.listen(GATEWAY_PORT, GATEWAY_HOST, () => {
     console.log(`[gateway] Listening on http://${GATEWAY_HOST}:${GATEWAY_PORT}`);