Alojamiento propio
Todo lo que ejecuta el servicio alojado está en el repositorio, y un documento publicado en tu propia instancia es el mismo documento que uno publicado aquí. El formato está especificado, no tiene dueño, así que un agente que apunte a tu registro no necesita nada de nosotros.
Para ser francos sobre el estado de esto: no hay un instalador de un solo comando para producción. Lo que existe es un conjunto de charts de Helm con los que se despliega el propio servicio alojado, un generador de configuración, realms como código y un script que levanta todo el conjunto en una sola máquina. Si te sientes cómodo operando un servicio en Kubernetes, es una tarde normal. Si quieres un producto empaquetado y listo para usar, aún no está listo.
Las piezas
| Pieza | Qué hace | Obligatoria |
|---|---|---|
| Pasarela (gateway) | MCPG, con sus propios plugins (first-party). Termina MCP, verifica la identidad, aplica la gobernanza por herramienta y llama a Postgres o a imd-svc para cada herramienta. | sí |
| Postgres | PostgreSQL 17 con pg_trgm, pgvector y pgcrypto, gestionado por CloudNativePG. El estado de referencia y las reglas del registro como funciones SQL. | sí |
| imd-svc | El servicio propio del servidor junto a la pasarela: la firma, las credenciales de los agentes, los archivos, el proceso en segundo plano y las migraciones del esquema. | sí |
| NATS | JetStream: las sesiones, suscripciones y notificaciones de la pasarela, compartidas entre sus réplicas. Allí no vive nada duradero. | con dos o más réplicas de la pasarela |
| Keycloak | El inicio de sesión, con sus realms como código: las personas, las credenciales propias de los agentes, los administradores. | sí |
| Modelo de embeddings | Text Embeddings Inference con BAAI/bge-base-en-v1.5, dentro del clúster: búsqueda por significado. Ningún texto de las instrucciones sale de él. | no |
| El estudio | El editor, un sitio estático que inicia sesión en tu Keycloak y guarda su espacio de trabajo en tu servidor. | no |
Fíjate en la última fila. Toda la superficie es MCP, así que los agentes y el cliente de línea de comandos hablan directamente con la pasarela. El estudio es un cliente entre varios, y una instancia que solo atiende a agentes no lo necesita. Sin el modelo de embeddings, la búsqueda encuentra palabras y títulos, pero no significado.
La instancia mínima que funciona
Los charts de producción en un clúster k3d local, conectados como los conecta producción, en un solo origen: el
sitio en / con el estudio en /editor/, el servidor MCP en /mcp y Keycloak
en /auth. Necesita Docker, k3d, kubectl, helm, Python 3 con PyYAML, Node con pnpm, rsync, openssl y
unos 6 GB de disco. Es un registro de verdad: las versiones, las referencias (refs), las propuestas, las
organizaciones, la firma y la entrega por MCP funcionan.
# 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
Hasta que se publique MCPG 0.1.0-beta.68, la pasarela predeterminada del script es una compilación local: la
imagen publicada de beta.67 con una pasarela y sus dos plugins de backend compilados en la máquina, a partir de
deploy/mcpg/data. Con la publicación, la segunda forma usa la imagen publicada y sus plugins
firmados. Inicia sesión en http://localhost:18080/ y apunta un agente a
http://localhost:18080/mcp. El realm de este stack tiene usuarios de desarrollo; el de producción,
no. El resto está en deploy/k8s/stack/README.md.
Postgres y las copias de seguridad que importan
Postgres es todo el estado. Los enlaces SQL de la pasarela llegan a él a través de PgBouncer en modo transacción,
que necesita max_prepared_statements porque MCPG prepara sus sentencias, mientras que LISTEN y el
lector de eventos van directos al primario, ya que un pooler de transacciones no puede mantener un LISTEN. Cada
cliente verifica el certificado del servidor con la CA del clúster. El chart configura todo esto.
Las copias de seguridad pasan por el plugin Barman Cloud de CloudNativePG hacia cualquier bucket compatible con S3: el WAL de forma continua y una copia base cada noche, ambos conservados 30 días, de modo que puedes recuperar el estado de un momento concreto en otro host.
# 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 recupera un segundo clúster a partir del bucket, compara cada tabla con
la del clúster en servicio y lo elimina. Ejecútalo después de la primera copia nocturna y después de cualquier
cambio en las copias de seguridad. NATS no necesita copia: si se pierde, la pasarela reconstruye lo que guardaba
allí.
Identidad
La pasarela necesita tres cosas de un token: un sujeto estable, una audiencia ligada a tu punto de acceso MCP y un claim que diga si quien llama es una persona, un agente o un servicio, porque los agentes quedan limitados por debajo de la administración completa, actúen en nombre de quien actúen. El servidor también depende de Keycloak para algo más que el inicio de sesión: imd-svc emite las credenciales propias de cada agente en el realm de los agentes. Por eso el proveedor de identidad es Keycloak, y tu gente puede seguir iniciando sesión con tu propio proveedor mediante la intermediación (brokering) de Keycloak.
Los realms se distribuyen como código, generado y no editado a mano
(deploy/keycloak/gen-realms.py): uno para las personas, uno para los agentes y uno para los
administradores. Keycloak los importa en su primer arranque. Después de cada instalación o actualización, un job
vuelve a aplicar su contenido a través de la API de administración: añade lo nuevo y deja lo que existe, porque
reemplazar un realm en servicio destruiría las organizaciones y los vínculos de identidad federada. Solo se
exponen hacia fuera los realms de las personas y de los agentes. La administración se queda dentro del clúster.
Los generadores mantienen un perfil para cada lugar donde se ejecuta el servidor: la máquina de un desarrollador,
el stack local y producción en instruction.md. Tu propio dominio es un perfil tuyo en
deploy/mcpg/gen-config.py y deploy/keycloak/gen-realms.py, con tu origen, tus emisores
(issuers) y tu audiencia.
Firma
imd-svc deriva una clave de editor para cada organización a partir de una única clave maestra, de modo que nunca se almacena ninguna clave privada: las mitades públicas se sirven para la verificación, y las privadas existen solo dentro del proceso mientras firma. Una segunda clave firma cada entrega.
# 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 crea ambas en su primera ejecución y las conserva a partir de
entonces. Guarda una copia donde guardes este tipo de cosas: si pierdes la clave maestra, cambia la clave de
editor de todas las organizaciones; si pierdes la clave de entrega, las entregas anteriores ya no se pueden
verificar. Sin clave maestra la plataforma no firma nada, lo cual es una opción legítima. Los editores pueden
seguir trayendo sus propias claves y firmar en sus propias máquinas, y los consumidores verifican exactamente de
la misma manera.
Kubernetes
Seis charts, un espacio de nombres, instalados en este orden, esperando a que cada uno esté listo. Es el orden en
que los ejecuta .github/workflows/deploy-server.yml, y ese workflow pasa completos los archivos de
los realms y el script del job que los aplica. La pasarela descarga sus plugins first-party al arrancar y solo
admite los firmados.
# 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 El script de secretos crea todos los secretos del espacio de nombres. Toma cada valor del entorno (lo que le entrega tu gestor de secretos); si no, del Secret que ya existe; si no, genera uno nuevo al azar, y después escribe los Secrets derivados que leen los charts. Ninguno de ellos debe estar en los archivos de values, y los charts no los aceptan allí. Más de una réplica de la pasarela, agrupadas en clúster sobre NATS, necesita una licencia de MCPG. El stack local funciona con la concesión gratuita de MCPG para usos que no son de producción.
El servidor habla un solo protocolo, MCP 2026-07-28, que no tiene sesión, así que cualquier réplica responde a cualquier petición. Por ahora los charts ejecutan una sola réplica, en modo clúster: la pasarela todavía acepta el protocolo anterior con sesiones, cuyas peticiones, con dos réplicas, pueden llegar a una que no vio empezar su sesión. La segunda réplica volverá cuando MCPG desactive ese protocolo.
Actualizaciones y operación
Los runbooks que usa el servicio alojado están en el repositorio, en docs/runbooks: el despliegue
del servidor, la vuelta atrás, la rotación de claves, la recuperación de Postgres, la observabilidad, el control
de publicaciones de MCPG, la respuesta a incidentes y la baja de una organización. Están escritos para nuestro
entorno, pero el planteamiento se puede trasladar.
Licencia
El texto de la especificación está bajo Creative Commons Attribution 4.0. Impleméntalo, cítalo, bifúrcalo, véndelo. El corpus de conformidad está bajo Apache 2.0, porque las implementaciones copian esos archivos en sus propios árboles de código.
El código de la plataforma está bajo la Business Source License 1.1. En la práctica: puedes ejecutarlo, modificarlo y usarlo para tus propios fines, también comerciales, y lo único que no puedes hacer es ofrecerlo a terceros como un servicio alojado que compita con el nuestro. Cada publicación pasa a Apache 2.0 cuatro años después de su fecha. Hoy no es una licencia de código abierto, y el aviso del repositorio lo dice con claridad.
El soporte comercial y las licencias alternativas aún no están definidos, así que, si necesitas alguna de las dos cosas, la respuesta ahora mismo es una conversación y no una página.