Guide de déploiement

ContextForge sur VPS : une passerelle MCP pour vos agents IA

Déployer sur un VPS Cloud →

Tutoriel

Self-hosting

ContextForge sur VPS : une passerelle MCP pour vos agents IA

Chaque agent IA qui doit appeler vos outils réclame sa propre configuration : un serveur MCP par service, déclaré dans chaque client, avec ses identifiants. ContextForge, la passerelle MCP open source d'IBM, réunit tout cela derrière une seule adresse. Ce guide l'installe sur un VPS avec Docker Compose, la ferme par des jetons d'API, la publie en HTTPS derrière nginx, transforme une API REST en outil MCP et y branche un client.

7 min de lecture3 étapes
Sommaire· Ce que fait ContextForge1/12
  1. 01Ce que fait ContextForge
  2. 02Ce que la passerelle apporte
  3. 03Brancher chaque outil ou passer par ContextForge
  4. 04Prérequis
  5. 05Installer ContextForge avec Docker Compose
  6. 06Ne désactivez jamais l'authentification
  7. 07Publier ContextForge en HTTPS avec nginx
  8. 08Se connecter et créer un jeton d'API
  9. 09Transformer une API REST en outil MCP
  10. 10Regrouper les outils et brancher un client MCP
  11. 11Sauvegarder et mettre à jour
  12. 12Installation en un clic sur ServOrbit

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 outilContextForge
Configuration des clientsUn outil à déclarer dans chaque clientUne adresse et un jeton
Identifiants des servicesRecopiés dans chaque clientGardés par la passerelle
API REST existanteUn serveur MCP à écrireDéclarée comme outil
Retirer un accèsClient par clientRévoquer un jeton
Outils visibles par un agentTous ceux qu'il a configurésCeux 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

  1. Générer les secrets

    Dans un dossier dédié, écrivez un fichier .env avec le nom de domaine, le mot de passe administrateur et deux secrets distincts : SECRET_KEY signe les jetons, ENCRYPTION_KEY_HEX64 chiffre 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
  2. Écrire le fichier docker-compose.yml

    L'image tourne sous un utilisateur non privilégié (uid 10001) : le service contextforge-init rend le volume inscriptible avant le démarrage. AUTH_REQUIRED et MCP_REQUIRE_AUTH ferment 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: {}
  3. 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 healthy en moins d'une minute.

    docker compose up -d
    docker compose ps
    curl -s http://127.0.0.1:4444/health

    La réponse attendue est {"status":"healthy"}. Toute autre route, /tools ou /version par 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.com

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

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

Vé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 contextforge

Pour 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 -d

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

Partager cet articleservorbit.com/ma-fr/blog/self-host-contextforge-vps