Ce que fait ContextForge
ContextForge est une passerelle pour le Model Context Protocol (MCP), le protocole qui permet à un agent IA de découvrir et d'appeler des outils. Elle se place entre vos clients — assistants de code, frameworks d'agents, automatisations — et les outils qu'ils utilisent : serveurs MCP distants, API REST ou gRPC existantes.
Le projet est publié par IBM sous licence Apache-2.0. Il fournit une API d'administration, une console web, une gestion d'utilisateurs et de jetons, et des serveurs virtuels : des regroupements d'outils exposés chacun à sa propre adresse MCP. Sur un VPS, c'est le point d'entrée unique de vos agents.
Ce que la passerelle apporte
- Une seule adresse — vos clients se connectent à la passerelle, pas à chaque outil.
- Des API REST devenues outils — une URL, une méthode et un schéma d'entrée, sans écrire de serveur MCP.
- Des serveurs virtuels — un jeu d'outils par agent, par projet ou par client.
- La fédération — des serveurs MCP distants enregistrés et exposés au même endroit.
- Des jetons d'API — un par client, avec une date d'expiration, révocables un par un.
- Une console web — outils, serveurs, jetons et utilisateurs gérés depuis
/admin.
Brancher chaque outil ou passer par ContextForge
Faites défiler le tableau
| Un serveur MCP par outil | ContextForge | |
|---|---|---|
| Configuration des clients | Un outil à déclarer dans chaque client | Une adresse et un jeton |
| Identifiants des services | Recopiés dans chaque client | Gardés par la passerelle |
| API REST existante | Un serveur MCP à écrire | Déclarée comme outil |
| Retirer un accès | Client par client | Révoquer un jeton |
| Outils visibles par un agent | Tous ceux qu'il a configurés | Ceux de son serveur virtuel |
Prérequis
Un VPS Ubuntu 24.04 avec 2 Go de RAM et 2 vCPU suffit : avec deux processus de travail, la passerelle occupe environ 800 Mo de mémoire. Les données tiennent dans une base SQLite de quelques mégaoctets.
Il vous faut Docker avec le plugin Compose, nginx et certbot sur l'hôte, jq pour lire les réponses de l'API, et un nom (mcp.example.com dans ce guide) qui pointe vers l'IP du VPS.
Installer ContextForge avec Docker Compose
Générer les secrets
Dans un dossier dédié, écrivez un fichier
.envavec le nom de domaine, le mot de passe administrateur et deux secrets distincts :SECRET_KEYsigne les jetons,ENCRYPTION_KEY_HEX64chiffre les identifiants des serveurs que vous enregistrez. ContextForge refuse de démarrer avec des secrets trop courts ou laissés à leur valeur d'exemple.mkdir -p /opt/contextforge && cd /opt/contextforge cat > .env <<EOF DOMAIN=mcp.example.com ADMIN_PASSWORD=$(openssl rand -base64 18) SECRET_KEY=$(openssl rand -hex 32) ENCRYPTION_KEY_HEX64=$(openssl rand -hex 32) EOF chmod 600 .envÉcrire le fichier docker-compose.yml
L'image tourne sous un utilisateur non privilégié (uid 10001) : le service
contextforge-initrend le volume inscriptible avant le démarrage.AUTH_REQUIREDetMCP_REQUIRE_AUTHferment l'API et le point MCP, et le port n'est publié que sur la boucle locale.DEFAULT_USER_PASSWORD, le mot de passe provisoire des comptes créés sans mot de passe, est tiré au hasard à chaque démarrage.services: contextforge-init: image: ghcr.io/ibm/mcp-context-forge:v1.1.1 user: "0:0" entrypoint: ["chown", "-R", "10001:10001", "/app/data"] restart: "no" volumes: - contextforge-data:/app/data contextforge: image: ghcr.io/ibm/mcp-context-forge:v1.1.1 restart: unless-stopped depends_on: contextforge-init: condition: service_completed_successfully environment: HOST: "0.0.0.0" PORT: "4444" ENVIRONMENT: "production" APP_DOMAIN: "https://${DOMAIN}" ALLOWED_ORIGINS: "https://${DOMAIN}" DATABASE_URL: "sqlite:////app/data/mcp.db" CACHE_TYPE: "database" GUNICORN_WORKERS: "2" MCPGATEWAY_UI_ENABLED: "true" MCPGATEWAY_ADMIN_API_ENABLED: "true" AUTH_REQUIRED: "true" MCP_CLIENT_AUTH_ENABLED: "true" MCP_REQUIRE_AUTH: "true" EMAIL_AUTH_ENABLED: "true" PLATFORM_ADMIN_EMAIL: "[email protected]" PLATFORM_ADMIN_PASSWORD: "${ADMIN_PASSWORD}" JWT_SECRET_KEY: "${SECRET_KEY}" AUTH_ENCRYPTION_SECRET: "${ENCRYPTION_KEY_HEX64}" entrypoint: ["/bin/bash", "-c"] command: - | export DEFAULT_USER_PASSWORD="$$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')" exec ./docker-entrypoint.sh ports: - "127.0.0.1:4444:4444" volumes: - contextforge-data:/app/data volumes: contextforge-data: {}Démarrer et vérifier
Lancez la pile, puis interrogez le point de santé. La première fois, ContextForge crée sa base et le compte administrateur ; le conteneur passe
healthyen moins d'une minute.docker compose up -d docker compose ps curl -s http://127.0.0.1:4444/healthLa réponse attendue est
{"status":"healthy"}. Toute autre route,/toolsou/versionpar exemple, répond 401 sans jeton.
Ne désactivez jamais l'authentification
Une passerelle MCP ouverte donne à n'importe qui les outils que vous y avez branchés — et les identifiants qui vont avec. Gardez AUTH_REQUIRED et MCP_REQUIRE_AUTH à true, le port sur 127.0.0.1, et laissez nginx seul face à Internet.
Publier ContextForge en HTTPS avec nginx
Créez un server block dans /etc/nginx/sites-available/ et activez-le. X-Forwarded-Proto compte : la console compare l'origine du formulaire de connexion à l'adresse de la requête, et refuse la connexion si elles divergent. proxy_buffering off laisse passer les réponses en flux du protocole MCP.
server {
server_name mcp.example.com;
location / {
proxy_pass http://127.0.0.1:4444;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 300s;
}
}Vérifiez la configuration, puis demandez le certificat :
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d mcp.example.comSe connecter et créer un jeton d'API
Ouvrez https://mcp.example.com/admin et connectez-vous avec [email protected] et le mot de passe du fichier .env. La console permet de créer des jetons ; l'API aussi. Le login renvoie un jeton de session de courte durée, qui sert à créer un jeton d'API nommé, valable 30 jours ici :
SESSION=$(curl -s https://mcp.example.com/auth/email/login -H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"VOTRE_MOT_DE_PASSE"}' | jq -r .access_token)
TOKEN=$(curl -s https://mcp.example.com/tokens -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
-d '{"name":"agent-1","expires_in_days":30}' | jq -r .access_token)Créez un jeton par client ou par agent : vous pourrez en révoquer un sans toucher aux autres.
Transformer une API REST en outil MCP
Un outil REST se déclare par son URL, sa méthode et le schéma de ses paramètres. L'exemple ci-dessous expose l'API publique zen de GitHub, qui renvoie une phrase et n'attend aucun paramètre :
curl -s https://mcp.example.com/tools -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"tool":{"name":"github_zen","url":"https://api.github.com/zen","integration_type":"REST","request_type":"GET","input_schema":{"type":"object","properties":{}}}}' \
| jq -r .idLa commande affiche l'identifiant de l'outil. Côté MCP, son nom devient github-zen. Pour une API interne, remplacez l'URL et décrivez ses paramètres dans input_schema : c'est ce schéma que l'agent lit pour savoir comment l'appeler.
Regrouper les outils et brancher un client MCP
Un serveur virtuel regroupe des outils sous une adresse MCP. Créez-le avec l'identifiant de l'outil :
curl -s https://mcp.example.com/servers -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"server":{"name":"demo","associated_tools":["ID_OUTIL"]}}' | jq -r .idVérifiez ensuite, comme le ferait un client, que l'outil est bien listé :
curl -s https://mcp.example.com/servers/ID_SERVEUR/mcp -H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Dans votre client MCP, déclarez l'adresse du serveur virtuel et le jeton. La forme exacte dépend du client ; beaucoup acceptent une entrée de ce type :
{
"mcpServers": {
"contextforge": {
"type": "http",
"url": "https://mcp.example.com/servers/ID_SERVEUR/mcp",
"headers": { "Authorization": "Bearer VOTRE_JETON" }
}
}
}Sauvegarder et mettre à jour
À sauvegarder : le volume contextforge-data, qui contient la base SQLite — outils, serveurs, utilisateurs et jetons — et le fichier .env. Sans ENCRYPTION_KEY_HEX64, les identifiants chiffrés de la base ne se relisent plus. Arrêtez le service le temps de la copie :
cd /opt/contextforge
docker compose stop contextforge
docker compose cp contextforge:/app/data ./sauvegarde-$(date +%F)
docker compose start contextforgePour mettre à jour, changez le tag de l'image dans les deux services après avoir lu les notes de version, puis :
docker compose pull
docker compose up -dContextForge applique ses migrations de base au démarrage : faites la sauvegarde avant.
Installation en un clic sur ServOrbit
Sur un VPS ServOrbit, ContextForge s'installe depuis le Marketplace : le script déploie l'image officielle, génère le mot de passe administrateur et les secrets, ferme l'instance à toute requête sans jeton et configure nginx en HTTPS. L'adresse est un sous-domaine de l'un de vos domaines ou le sous-domaine gratuit du VPS, certificat compris, et le mot de passe s'affiche dans votre espace client.
servorbit.com/ma-fr/blog/self-host-contextforge-vps