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ément | Ce qu’il fait | Obligatoire |
|---|---|---|
| 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 |
| Postgres | PostgreSQL 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-svc | Le 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 |
| NATS | JetStream : 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 |
| Keycloak | La connexion, avec ses realms sous forme de code : les personnes, les identifiants propres aux agents, les administrateurs. | oui |
| Modèle d’embeddings | Text 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 studio | L’é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.
# 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.
# 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.
# 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.
# 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.