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 :

npm install -g @imenam/mcp-http-gateway

Via npx (sans installation) :

npx @imenam/mcp-http-gateway

En dépendance locale d'un projet :

npm install @imenam/mcp-http-gateway

Configuration

.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 |

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.

{
  "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

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).

curl http://localhost:3500/mcps

GET /{route}/tools

Liste les outils disponibles d'un MCP avec leur nom, description et schéma d'arguments.

curl http://localhost:3500/documentor/tools

POST /{route}/tools/:toolName

Appelle un outil du MCP. Les arguments sont passés dans le body JSON.

curl -X POST http://localhost:3500/documentor/tools/list_projects -H "Content-Type: application/json" -d '{}'

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 :

{
  "content": [
    { "type": "text", "text": "Résultat de l'outil..." }
  ]
}

Pour extraire le texte directement avec jq :

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

GATEWAY_URL=http://host.docker.internal:3500 npx @imenam/mcp-http-gateway --mcp

Configuration dans le conteneur

{
  "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.

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.

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.