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.

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.

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

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.