Auto-hébergement

Tout ce que fait tourner le service hébergé se trouve dans le dépôt, et un document publié sur votre propre instance est le même document que s’il était publié ici. Le format est défini par une spécification, il n’appartient à personne : un agent pointé vers votre registre n’a donc besoin de rien de notre part.

Soyons francs sur l’état des choses : il n’existe pas d’installateur en une commande pour la production. Ce qui existe, c’est l’ensemble de charts Helm avec lesquels le service hébergé est lui-même déployé, un générateur de configuration, des realms sous forme de code et un script qui monte l’ensemble sur une seule machine. Si vous avez l’habitude d’exploiter un service sur Kubernetes, c’est l’affaire d’un après-midi ordinaire. Si vous voulez une solution clés en main, elle n’est pas prête.

Les éléments

ÉlémentCe qu’il faitObligatoire
Passerelle (gateway)MCPG, avec ses propres plugins (first-party). Elle termine les connexions MCP, vérifie l’identité, applique la gouvernance outil par outil et appelle Postgres ou imd-svc pour chaque outil.oui
PostgresPostgreSQL 17 avec pg_trgm, pgvector et pgcrypto, géré par CloudNativePG. L’état qui fait autorité, et les règles du registre sous forme de fonctions SQL.oui
imd-svcLe service propre au serveur, à côté de la passerelle : la signature, les identifiants des agents, les fichiers, le traitement en arrière-plan et les migrations du schéma.oui
NATSJetStream : les sessions, les abonnements et les notifications de la passerelle, partagés entre ses répliques. Rien de durable n’y est conservé.à partir de deux répliques de la passerelle
KeycloakLa connexion, avec ses realms sous forme de code : les personnes, les identifiants propres aux agents, les administrateurs.oui
Modèle d’embeddingsText Embeddings Inference avec BAAI/bge-base-en-v1.5, à l’intérieur du cluster : la recherche par le sens. Aucun texte d’instruction n’en sort.non
Le studioL’éditeur, un site statique qui se connecte à votre Keycloak et conserve son espace de travail sur votre serveur.non

Remarquez la dernière ligne. Toute la surface est du MCP : les agents et le client en ligne de commande s’adressent donc directement à la passerelle. Le studio est un client parmi d’autres, et une instance qui ne sert que des agents n’en a pas besoin. Sans le modèle d’embeddings, la recherche trouve les mots et les titres, mais pas le sens.

La plus petite instance qui fonctionne

Les charts de production dans un cluster k3d local, reliés comme ils le sont en production, sur une seule origine : le site à / avec le studio à /editor/, le serveur MCP à /mcp, Keycloak à /auth. Il faut Docker, k3d, kubectl, helm, Python 3 avec PyYAML, Node avec pnpm, rsync, openssl et environ 6 Go d’espace disque. C’est un vrai registre : les versions, les références (refs), les propositions, les organisations, la signature et la livraison par MCP fonctionnent toutes.

Shell
# 1. build the site, the studio, the docs and Learn for the stack's origin, as one tree (dist/web)
PUBLIC_IMD_AUTH_ISSUER=http://localhost:18080/auth/realms/instruction-md PUBLIC_IMD_AUTH_CLIENT=platform-web \
  PUBLIC_IMD_MCP_URL=http://localhost:18080/mcp PUBLIC_IMD_STUDIO_SIGN_IN=on pnpm build:web

# 2. a k3d cluster, the operators, the secrets and every chart
deploy/k8s/stack/up.sh                  # http://localhost:18080

# the same, on MCPG's published release
IMD_GATEWAY_IMAGE=ghcr.io/mcpg-dev/mcpg:0.1.0-beta.68 deploy/k8s/stack/up.sh

Tant que MCPG 0.1.0-beta.68 n’est pas publié, la passerelle par défaut du script est une construction locale : l’image publiée beta.67, avec une passerelle et ses deux plugins de backend construits sur la machine à partir de deploy/mcpg/data. Une fois cette version sortie, la seconde forme utilise l’image publiée et ses plugins signés. Connectez-vous sur http://localhost:18080/ et pointez un agent vers http://localhost:18080/mcp. Le realm de cette pile contient des utilisateurs de développement ; celui de la production n’en a pas. Le reste se trouve dans deploy/k8s/stack/README.md.

Postgres, et les sauvegardes qui comptent

Postgres, c’est tout l’état. Les liaisons SQL de la passerelle l’atteignent à travers PgBouncer en mode transaction, ce qui exige max_prepared_statements parce que MCPG prépare ses requêtes, tandis que LISTEN et le lecteur d’événements vont directement au serveur primaire, puisqu’un pooler en mode transaction ne peut pas garder un LISTEN ouvert. Chaque client vérifie le certificat du serveur auprès de l’autorité de certification du cluster. Le chart met tout cela en place.

Les sauvegardes passent par le plugin Barman Cloud de CloudNativePG, vers n’importe quel bucket compatible S3 : les WAL en continu, une sauvegarde de base chaque nuit, les deux conservés 30 jours. Vous pouvez ainsi restaurer à un instant donné sur un autre hôte.

YAML
# deploy/k8s/imd-postgres/values.yaml
backup:
  enabled: true
  destinationPath: s3://imd-postgres-backup/imd-postgres
  endpointURL: http://rgw.internal:7480
  credentialsSecret: imd-postgres-backup   # ACCESS_KEY_ID, ACCESS_SECRET_KEY
  retentionPolicy: "30d"
  schedule: "0 0 3 * * *"                  # a base backup nightly; WAL all the time

deploy/k8s/restore-drill.sh restaure un second cluster à partir du bucket, compare chaque table avec celle du cluster en service, puis le supprime. Lancez-le après la première sauvegarde nocturne, et après toute modification des sauvegardes. NATS n’a pas besoin de sauvegarde : s’il est perdu, la passerelle reconstruit ce qu’elle y gardait.

Identité

La passerelle attend trois choses d’un jeton : un sujet stable, une audience liée à votre point d’accès MCP, et une revendication (claim) indiquant si l’appelant est une personne, un agent ou un service, car les agents restent plafonnés en dessous de l’administration complète, quelle que soit la personne pour laquelle ils agissent. Le serveur s’appuie aussi sur Keycloak pour autre chose que la connexion : imd-svc émet les identifiants propres à chaque agent dans le realm des agents. Le fournisseur d’identité est donc Keycloak, et vos collaborateurs peuvent tout de même se connecter avec votre propre fournisseur grâce au courtage d’identité (brokering) de Keycloak.

Les realms sont fournis sous forme de code, généré plutôt qu’édité à la main (deploy/keycloak/gen-realms.py) : un pour les personnes, un pour les agents, un pour les administrateurs. Keycloak les importe à son premier démarrage. Après chaque installation ou mise à niveau, un job applique de nouveau leur contenu par l’API d’administration : il ajoute ce qui est nouveau et laisse ce qui existe, car remplacer un realm en service détruirait les organisations et les liens d’identités fédérées. Seuls le realm des personnes et celui des agents sont exposés. L’administration reste à l’intérieur du cluster.

Les générateurs gardent un profil pour chaque endroit où tourne le serveur : la machine d’un développeur, la pile locale et la production sur instruction.md. Votre propre domaine est un profil à vous dans deploy/mcpg/gen-config.py et deploy/keycloak/gen-realms.py, avec votre origine, vos émetteurs (issuers) et votre audience.

Signature

imd-svc dérive une clé d’éditeur pour chaque organisation à partir d’une seule clé maîtresse : aucune clé privée n’est donc jamais stockée. Les moitiés publiques sont servies pour la vérification, et les moitiés privées n’existent qu’à l’intérieur du processus, le temps de signer. Une seconde clé signe chaque livraison.

Secrets
# deploy/k8s/bootstrap-secrets.sh, in the Secret imd-keys
IMD_SIGNING_MASTER_KEY   # each organization's publisher key is derived from it
IMD_DELIVERY_KEY         # signs each delivery: one reader, one resolution

deploy/k8s/bootstrap-secrets.sh crée les deux à sa première exécution et les conserve ensuite. Gardez-en une copie là où vous rangez ce genre de choses : si vous perdez la clé maîtresse, la clé d’éditeur de chaque organisation change ; si vous perdez la clé de livraison, les livraisons antérieures ne peuvent plus être vérifiées. Sans clé maîtresse, la plateforme ne signe rien, ce qui est un choix légitime. Les éditeurs peuvent toujours apporter leurs propres clés et signer sur leurs propres machines, et les consommateurs vérifient exactement de la même façon.

Kubernetes

Six charts, un seul namespace, installés dans cet ordre, en attendant chaque fois que le précédent soit prêt. C’est l’ordre dans lequel .github/workflows/deploy-server.yml les exécute, et ce workflow transmet en entier les fichiers des realms et le script du job d’application. La passerelle télécharge ses plugins first-party à son démarrage et n’admet que ceux qui sont signés.

Shell
# first, once per cluster: the CloudNativePG operator, cert-manager and the Barman Cloud plugin
# (docs/runbooks/server-deploy.md §1). Then the namespace's secrets:
deploy/k8s/bootstrap-secrets.sh instruction-md

helm upgrade --install imd-postgres   deploy/k8s/imd-postgres   -n instruction-md
kubectl -n instruction-md wait cluster/imd-postgres --for=condition=Ready --timeout=15m
helm upgrade --install imd-nats       deploy/k8s/imd-nats       -n instruction-md --wait
helm upgrade --install imd-keycloak   deploy/k8s/imd-keycloak   -n instruction-md --wait \
  --set-file realms.users=deploy/keycloak/realms/prod/instruction-md-realm.json …
helm upgrade --install imd-embeddings deploy/k8s/imd-embeddings -n instruction-md --wait
helm upgrade --install imd-svc        deploy/k8s/imd-svc        -n instruction-md --wait \
  --set image.tag=<tag>
helm upgrade --install imd-gateway    deploy/k8s/imd-gateway    -n instruction-md --wait \
  --set-file config=deploy/mcpg/prod.yaml

Le script des secrets crée tous les secrets du namespace. Il prend chaque valeur dans l’environnement (ce que votre gestionnaire de secrets lui fournit), sinon dans le Secret déjà présent, sinon il en génère une nouvelle au hasard, puis il écrit les Secrets dérivés que lisent les charts. Aucun d’eux n’a sa place dans les fichiers de values, et les charts ne les y accepteront pas. Plus d’une réplique de la passerelle, en cluster sur NATS, exige une licence MCPG. La pile locale tourne avec l’autorisation gratuite de MCPG pour les usages hors production.

Le serveur parle un seul protocole, MCP 2026-07-28, qui n’a pas de session : n’importe quelle réplique répond donc à n’importe quelle requête. Pour l’instant, les charts font tourner une seule réplique, en mode cluster : la passerelle accepte encore l’ancien protocole à sessions, dont les requêtes, avec deux répliques, peuvent arriver sur celle qui n’a pas vu leur session commencer. La seconde réplique reviendra quand MCPG désactivera ce protocole.

Mises à niveau et exploitation

Les procédures d’exploitation (runbooks) qu’utilise le service hébergé sont dans le dépôt, sous docs/runbooks : déployer le serveur, revenir en arrière, renouveler les clés, restaurer Postgres, l’observabilité, le contrôle des versions de MCPG avant leur mise en service, la réponse aux incidents et la mise hors service d’une organisation. Elles sont écrites pour notre environnement, mais la démarche se transpose.

Licence

Le texte de la spécification est sous licence Creative Commons Attribution 4.0. Mettez-le en œuvre, citez-le, dérivez-en votre version, vendez-le. Le corpus de conformité est sous Apache 2.0, parce que les implémentations copient ces fichiers dans leur propre arborescence de sources.

Le code source de la plateforme est sous Business Source License 1.1. En pratique : vous pouvez le faire tourner, le modifier et l’utiliser pour vos propres besoins, y compris commerciaux, et la seule chose que vous ne pouvez pas faire est de le proposer à des tiers comme service hébergé concurrent. Chaque version passe sous Apache 2.0 quatre ans après sa publication. Ce n’est pas une licence open source aujourd’hui, et la notice du dépôt le dit clairement.

Le support commercial et les licences alternatives ne sont pas encore arrêtés : si vous avez besoin de l’un ou de l’autre, la réponse, pour le moment, est une conversation plutôt qu’une page.