platform-mcp

Servidor MCP para los servicios de infraestructura del clúster sonar-prod — Argo CD, Vault y Keycloak — con inicio de sesión SSO (GitLab para Argo/Vault, FreeIPA para Keycloak).

Para qué sirve

El agente del editor necesita acceso a Argo CD, Vault y Keycloak, pero no se le puede dar una cuenta de servicio: en la auditoría aparecería una cuenta compartida en lugar de una persona, y los permisos serían más amplios que los de cualquier desarrollador concreto.

Este paquete se instala localmente y realiza el inicio de sesión SSO habitual a través del navegador. Después ejecuta los comandos en nombre del usuario que ha iniciado sesión: en los registros de auditoría se ve el login real, y los permisos son exactamente los que otorga la pertenencia a los grupos.

Hay exactamente una herramienta por servicio — argocd_exec, vault_exec y keycloak_exec, que aceptan argumentos de línea de comandos. Por debajo están las CLI oficiales (argocd, vault, kcadm), por lo que está disponible todo lo que ellas saben hacer. Un servicio nuevo se añade con una implementación de la interfaz.

Related MCP server: mcp-read-only-argocd

Instalación

Paso 1. Acceso al registro de paquetes

Se necesita una sola vez y para todos los métodos siguientes: el paquete está en el registro npm de este proyecto de GitLab, no en el npm público. Obtenga un token con el permiso read_package_registry (personal access token o deploy token del proyecto) y añádalo a ~/.npmrc:

@sonar:registry=https://git.sonar-corp.ru/api/v4/projects/98/packages/npm/
//git.sonar-corp.ru/api/v4/projects/98/packages/npm/:_authToken=<ваш gitlab токен>

Paso 2. Conexión al editor

Claude Code y Cursor — con el plugin. El repositorio es su propio catálogo de plugins, por lo que bastan dos comandos:

/plugin marketplace add https://github.com/K-manankov/platform-mcp.git
/plugin install platform-mcp

La dirección es GitHub, no GitLab, y no es un error tipográfico — véase Por qué el catálogo de plugins está en GitHub.

Las direcciones de Argo CD, Vault y Keycloak ya están configuradas en el plugin — no hay que configurar nada. Las actualizaciones llegan solas: el plugin arranca el servidor con npx -y, es decir, siempre la última versión publicada. Para actualizar el propio plugin — /plugin marketplace update.

Claude Desktop no instala plugins de este formato, por lo que allí la configuración se hace manualmente. Instale el paquete globalmente:

npm install -g @sonar/platform-mcp

y añádalo a claude_desktop_config.json (Settings → Developer → Edit Config). La ruta a node y al servidor debe ser absolutamente absoluta: las aplicaciones GUI en macOS no heredan PATH de la shell. Consulte sus propias rutas con los comandos which node y which platform-mcp:

{
  "mcpServers": {
    "platform": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/@sonar/platform-mcp/dist/index.js"],
      "env": {
        "ARGOCD_BASE_URL": "https://argocd.infra.sonar-corp.ru",
        "VAULT_ADDR": "https://vault.infra.sonar-corp.ru",
        "KEYCLOAK_BASE_URL": "https://auth.infra.sonar-corp.ru",
        "PLATFORM_MCP_INSECURE": "true"
      }
    }
  }
}

No es necesario instalar Argo CD, Vault y Keycloak por separado en ninguna de las variantes: el servidor descarga las versiones necesarias de las CLI en la primera petición (véase De dónde salen argocd, vault y kcadm). Para kcadm la máquina debe tener Java 17+.

Por qué el catálogo de plugins está en GitHub

Claude Desktop solo conecta catálogos de plugins desde GitHub. Además, nuestro GitLab vive en la red interna y desde fuera es inaccesible en absoluto, así que ni siquiera llegaría a git.sonar-corp.ru.

Por eso el código fuente permanece en GitLab, y en github.com/K-manankov/platform-mcp está configurado un espejo de las ramas protegidas. Solo está protegida una rama — main, y es la única que viaja a GitHub en cada push. No hay sincronización inversa: los cambios se hacen solo en GitLab; la copia de GitHub existe para la instalación del plugin.

El propio espejo no revela nada de más — allí está el mismo paquete npm público y las direcciones de los servicios internos, que de todos modos solo se resuelven desde la red. En el repositorio no hay secretos ni debe haberlos: el servidor guarda los tokens de acceso en ~/.config/platform-mcp/, y el token del registro de paquetes cada uno se lo crea en su propio ~/.npmrc.

Para actualizar el plugin instalado después de los cambios:

/plugin marketplace update sonar-infra
/plugin update platform-mcp

Inicio de sesión

Se necesita VPN: los nombres argocd.infra.sonar-corp.ru, vault.infra.sonar-corp.ru y auth.infra.sonar-corp.ru solo se resuelven desde dentro de la red. Desde fuera los captura el wildcard público *.infra.sonar-corp.ru, y la petición se va silenciosamente a otro sitio — la comprobación dig +short argocd.infra.sonar-corp.ru debe dar 192.168.88.106.

Lo más sencillo es entrar directamente desde el diálogo: pida al agente que llame a argocd_login, vault_login o keycloak_login, abra el enlace que se le da y complete el inicio de sesión. No hace falta reiniciar el editor.

Lo mismo desde la terminal, si el paquete está instalado globalmente:

export ARGOCD_BASE_URL=https://argocd.infra.sonar-corp.ru
export VAULT_ADDR=https://vault.infra.sonar-corp.ru
export KEYCLOAK_BASE_URL=https://auth.infra.sonar-corp.ru
export PLATFORM_MCP_INSECURE=true   # пока нет настоящих сертификатов, см. TLS

platform-mcp login             # во все настроенные сервисы подряд
platform-mcp login keycloak    # только в один

Se abrirá el navegador: para Argo CD y Vault — GitLab SSO, para Keycloak — FreeIPA en el realm master (cliente platform-mcp-cli, véase bootstrap en infra). Las sesiones se guardarán en ~/.config/platform-mcp/ con permisos 0600 y serán comunes para todos los editores: si ha iniciado sesión una vez, ha iniciado sesión en todas partes.

Por SSH o en devcontainer, donde no hay navegador:

platform-mcp login --no-browser

El enlace de la salida debe abrirse en su propia máquina; el puerto 8085 (Argo CD), 8250 (Vault) o 8280 (Keycloak) debe estar redirigido al host donde se ejecuta el comando.

Inicio de sesión como administrador de Vault

El inicio de sesión normal va al punto de montaje oidc, donde la política se otorga según la pertenencia al subgrupo. Los permisos completos sobre el almacén viven en un mount separado oidc-admin y solo los obtienen los Owner del grupo infra/k8s — por qué es así se describe en platform/vault-config/40-groups.yaml:

VAULT_OIDC_MOUNT=oidc-admin platform-mcp login vault

Configuración

No es obligatorio cambiar nada — las direcciones ya están configuradas en el plugin.

Cursor. Plugins → Configure en platform-mcp: URL de Argo CD, Vault y Keycloak, PLATFORM_MCP_INSECURE, y el mount de Vault OIDC (oidc — inicio de sesión normal, oidc-admin — permisos completos para los Owner de infra/k8s). Los valores por defecto coinciden con el clúster sonar-prod.

Claude Code y configuración manual. Si necesita algo distinto (su propio instancia, oidc-admin, sus propias prohibiciones), sobrescriba las variables de entorno en la configuración del editor o póngalas en ~/.config/platform-mcp/config.json:

{
  "argocdUrl": "https://argocd.infra.sonar-corp.ru",
  "vaultUrl": "https://vault.infra.sonar-corp.ru",
  "keycloakUrl": "https://auth.infra.sonar-corp.ru",
  "vaultOidcMount": "oidc",
  "policy": {
    "requireConfirmation": true,
    "denyVaultPaths": ["kv/infra/"]
  }
}

Basta con indicar la dirección de al menos un servicio — los demás simplemente no aparecerán en la lista de herramientas.

Si no hay sesión o ha caducado, las herramientas devolverán un error comprensible, y el agente podrá llamar a argocd_login / vault_login / keycloak_login directamente desde el diálogo — no hace falta reiniciar el editor. Estas herramientas abren el navegador y de inmediato devuelven el enlace, sin esperar a que se complete el inicio de sesión: la persona tarda minutos en el SSO, mientras que el tiempo de espera de petición en los clientes MCP suele ser de 60 segundos. El resultado se comprueba con una llamada aparte a *_auth_status.

Comandos

platform-mcp                    # MCP-сервер поверх stdio (так его запускает редактор)
platform-mcp login [сервис]     # интерактивный вход, --no-browser для headless
platform-mcp status [сервис]    # кто вошёл и до какого момента действует токен
platform-mcp logout [сервис]    # удалить сохранённую сессию

El servicio es argocd, vault o keycloak; sin él, el comando se aplica a todos los configurados.

Herramientas

Por cada servicio: <servicio>_exec, <servicio>_login, <servicio>_auth_status, <servicio>_logout.

argocd_exec, vault_exec y keycloak_exec aceptan args — un array de argumentos de línea de comandos:

argocd_exec { "args": ["app", "list", "-o", "json"] }
argocd_exec { "args": ["app", "sync", "team-a-api"] }
vault_auth_status   # сначала: username, role, policies
vault_exec  { "args": ["token", "lookup"] }
vault_exec  { "args": ["kv", "list", "kv/teams"] }
vault_exec  { "args": ["kv", "get", "kv/teams/team-a/postgres"] }
keycloak_exec { "args": ["get", "realms"] }
keycloak_exec { "args": ["get", "users", "-r", "sonar-prod", "-q", "username=alice"] }

Para Vault empiece con vault_auth_status: por policies se ve de inmediato si hay acceso al KV. ["token","lookup"] es el canon de la CLI (no lookup-self). sys/mounts para usuarios OIDC normales suele dar 403 — no lo use para discovery. El exit code 2 en kv list normalmente significa «vacío o sin list ACL», no «hay que probar otro mount».

Los argumentos siempre se pasan como array y nunca se concatenan en una cadena: la shell no participa, por lo que ; y $(...) en los argumentos siguen siendo texto normal.

La dirección y el token los pone el servidor. Las flags que los sobrescriben (--server, --auth-token, --config, --core en Argo CD; -address, -tls-skip-verify en Vault; --server, --config, --no-config en Keycloak) están prohibidas — de lo contrario, el token de trabajo del entorno del proceso hijo podría enviarse a un host ajeno.

Confirmación de operaciones peligrosas

Los comandos de lectura se ejecutan de inmediato. Para Argo CD y Vault, todo lo demás requiere la confirmación del usuario.

Se considera mutadora cualquier comando que no se reconozca como de lectura: la lista de verbos está cerrada hacia el lado seguro, por lo que un comando desconocido caerá bajo la confirmación y no se colará por delante de ella.

Si el cliente soporta MCP elicitation, aparece el diálogo habitual. Si no — funciona el esquema de respaldo: la primera llamada devuelve la descripción de las consecuencias y un token de un solo uso; la segunda llamada con ese token ejecuta la operación. El token vive 5 minutos y está vinculado a los argumentos concretos, por lo que «confirmó una cosa, ejecutó otra» no pasará, y el agente no puede inventárselo por su cuenta.

Keycloak — es la excepción: las mutaciones se ejecutan de inmediato, pero a la respuesta del agente se le añade un warning — la configuración viaja por CR/operador; las ediciones manuales a través de kcadm el operador puede sobrescribirlas en el sync. Son preferibles los manifiestos en Git.

Están prohibidos por completo:

• entrar y salir (argocd login, vault login, kcadm config …) — la sesión la gestiona el propio servidor;

• comandos que no terminan: vault server|agent|proxy|monitor, argocd app logs --follow;

• argocd admin — gestión del propio Argo CD;

• vault operator seal|step-down|init|rekey|generate-root|migrate — el fallo de cualquiera de ellos tumba el almacén entero;

• modificación de las aplicaciones de infraestructura de Argo CD (argocd, vault, keycloak, cert-manager, ingress-nginx, …): viajan desde Git mediante merge request, no desde el diálogo con el agente. Se pueden leer.

Las listas se configuran en config.json (policy.denyApplications, policy.denyVaultPaths).

Esto es una protección contra errores del agente, no un límite de seguridad. Un miembro del grupo infra/k8s ya es administrador de Argo CD (g, infra/k8s, role:admin) y puede hacer lo mismo a través de la UI. Limitar los permisos de verdad solo se puede con la separación de roles en argocd-rbac-cm y las políticas de Vault.

Los secretos no llegan al contexto del modelo

Los valores de los secretos se recortan de las respuestas, mientras que los nombres de las claves y los metadatos permanecen:

• Vault — valores de kv get, read por ruta KV y unwrap. Las respuestas de kv list, kv metadata get, policy read, sys/mounts no se tocan: no hay secretos allí, y el recorte las volvería inútiles.

• Argo CD — data y stringData en recursos Secret, incluidos los campos manifest, liveState, targetState, donde Argo CD devuelve los manifiestos como cadenas con JSON dentro. base64 no es cifrado.

Las vías de escape están cerradas: vault kv get -field=password imprime el valor pelado fuera del JSON, y -format=table no da de qué recortar — ambos se rechazan con una explicación.

Si los valores son realmente necesarios en el diálogo:

export PLATFORM_MCP_ALLOW_SECRET_VALUES=true

Opt-in consciente: después de él, el contenido de los secretos viaja al proveedor del modelo. Por defecto, consulte los secretos directamente en Vault.

Además: las respuestas de más de 100 KB se truncan con una sugerencia de cómo acotar la petición, y la salida se marca como datos del clúster — los manifiestos, las anotaciones y los logs los escriben personas, y el agente no debe ejecutar las instrucciones que encuentre allí.

De dónde salen argocd, vault y kcadm

El servidor no trabaja con un cliente REST propio, sino con las CLI oficiales: Argo CD no tiene cliente Node en absoluto; el oficial de Vault es una biblioteca Go y el mismo binario; para Keycloak Admin API — kcadm de la distribución. La plenitud de capacidades es entonces igual a la de la CLI.

No hace falta instalarlas manualmente:

1. Si argocd / vault / kcadm (kcadm.sh) ya está en PATH — se usa ese, no se descarga nada.

2. Si no, en la primera petición se descarga la versión fijada de los releases oficiales (github.com/argoproj/argo-cd, releases.hashicorp.com, github.com/keycloak/keycloak) para la plataforma actual. Para Keycloak — el zip de la distribución completo (~170 MB): kcadm es un script Java, no un binario Go independiente.

3. La suma de comprobación se verifica antes de descomprimir y antes del chmod +x. Sin este paso, todo se reduciría a «descargar de internet y ejecutar».

4. El archivo se coloca en ~/.config/platform-mcp/bin/ y se reutiliza a partir de entonces.

Para kcadm la máquina necesita Java 17+ (java en PATH o JAVA_HOME). Sin ella, el servidor devolverá un error comprensible.

La descarga ocurre en el primer uso, no en postinstall: los scripts postinstall se desactivan en todas partes (npm ci --ignore-scripts), y la instalación quedaría silenciosamente incompleta.

Las versiones están fijadas en src/config.ts y coinciden con las desplegadas en el clúster (Argo CD v3.4.5, Vault 2.0.3, Keycloak 26.6.4). Al actualizar el clúster hay que subirlas también aquí.

TLS

argocd.infra.sonar-corp.ru, vault.infra.sonar-corp.ru y auth.infra.sonar-corp.ru ahora mismo no tienen certificados reales: en el Ingress no se ha indicado el secreto con el certificado, por lo que ingress-nginx entrega su autofirmado por defecto (CN=Kubernetes Ingress Controller Fake Certificate, SAN ingress.local).

Mientras sea así, se necesita un opt-in explícito:

export PLATFORM_MCP_INSECURE=true

Desactiva la verificación del certificado para Node (login OIDC) e imprime una advertencia en cada ejecución. La conexión permanece cifrada, pero no se confirma la autenticidad del servidor, y por este canal circulan tokens de acceso. En kcadm, cuando no hay truststore en la configuración, la validación de certificados está omitida (advertencia en stderr de la CLI).

NODE_EXTRA_CA_CERTS aquí no ayuda: el SAN del certificado (ingress.local) no coincide con el nombre del host, por lo que la verificación del nombre fallará incluso con una CA raíz de confianza.

Tras la emisión de certificados normales, hay que quitar la opción. Si están firmados por una CA interna, basta con indicar la raíz: las variables se heredan a las CLI hijas:

export NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem   # для самого сервера (Node)
export SSL_CERT_FILE=/path/to/internal-ca.pem         # для argocd и vault (Go)

Cómo funciona

редактор ──stdio──▶ platform-mcp ──argv+env──▶ argocd ──▶ Argo CD
                    (OIDC, политика,  vault  ──▶ Vault
                     вырезание секретов) kcadm ──▶ Keycloak

Argo CD. El acceso es Authorization Code + PKCE mediante Dex. Se usa el cliente público argo-cd-cli, que Argo CD registra en Dex automáticamente junto con la redirect URI http://localhost:8085/auth/callback, por lo que no hace falta cambiar argocd-cm para la instalación. Argo CD acepta como Bearer precisamente el id_token, no el access_token — este último en Dex es opaco y el servidor de API no lo verifica. El token se renueva mediante el refresh token.

La CLI se ejecuta con --grpc-web: ingress-nginx hace proxy hacia argocd-server con HTTP/1.1 normal (configs.params.server.insecure: true), y el gRPC puro no llega hasta él.

Vault. El flujo es más simple: PKCE no es necesario, porque el código lo cambia por el token el propio Vault — el secreto de la aplicación OAuth se almacena en él. Del cliente se requiere levantar un listener en http://localhost:8250/oidc/callback (ya está predefinido en allowedRedirectURIs) y devolver code, state y client_nonce. El parámetro state lo genera el propio Vault y lo coloca dentro del enlace emitido — de ahí se toma para verificar el redirect. El token se renueva mediante auth/token/renew-self mientras sea renewable.

Keycloak. Authorization Code + PKCE mediante el cliente público platform-mcp-cli en el realm master (se crea una vez en el bootstrap, redirect http://localhost:8280/oidc/callback). El acceso es FreeIPA. En la sesión se guarda el access_token (Admin API). Antes de kcadm, el servidor escribe un kcadm.config privado en ~/.config/platform-mcp/ — no el ~/.keycloak/kcadm.config compartido.

Los tokens se pasan a los procesos hijos solo mediante el entorno (Argo/Vault) o mediante un archivo de configuración privado (Keycloak): en argv serían visibles en ps para cualquier proceso del usuario. El entorno no se hereda por completo — la CLI recibe exactamente lo que necesita, sin los secretos de los servicios vecinos.

Las sesiones se almacenan en archivos propios, no en ~/.config/argocd/config, ~/.vault-token ni ~/.keycloak/kcadm.config: el proveedor rota el token al renovarlo, y un archivo compartido haría que las CLI normales en la terminal y este servidor se invalidaran las sesiones mutuamente.

Desarrollo

npm install
npm run build
npm test

Los tests cubren la clasificación de comandos y las prohibiciones, el recorte de secretos, los tokens de confirmación de un solo uso, la ausencia de shell al ejecutar la CLI y un descompresor ZIP propio (es necesario porque HashiCorp entrega vault como archivo, y Node no tiene descompresor integrado).

Plugin

El repositorio es a la vez el catálogo de plugins y el propio plugin:

.claude-plugin/marketplace.json      каталог для Claude Code
.cursor-plugin/marketplace.json      каталог для Cursor
plugins/platform-mcp/
  .claude-plugin/plugin.json         манифест для Claude Code
  .cursor-plugin/plugin.json         манифест для Cursor
  .mcp.json                          сервер для Claude Code — ПЛОСКАЯ карта
  mcp.json                           тот же сервер для Cursor — с обёрткой mcpServers

La descripción del servidor está duplicada en dos formatos, y esto no es descuido. Claude Code lee .mcp.json como un mapa plano «nombre → servidor»: con la envoltura mcpServers no recoge el servidor en silencio — el plugin se instala y figura como habilitado, pero las herramientas no aparecen. Cursor, en cambio, toma el archivo por la ruta desde mcpServers en su plugin.json, y los plugins funcionales para él usan el formato con envoltura. command/args y las claves env coinciden; los valores de env en Cursor son placeholders ${VAR} (esquema variables en plugin.json, Configure en la UI), en Claude son valores predeterminados literales. npm run check:manifests vigila que los formatos no diverjan.

El código del servidor no se copia al plugin: ambos archivos ejecutan el paquete publicado mediante npx, por lo que el plugin sigue siendo unos pocos archivos pequeños y no requiere recompilación ante cambios del servidor.

Se pueden comprobar los cambios antes del push conectando el directorio desde una ruta local:

/plugin marketplace add /путь/к/platform-mcp
/plugin install platform-mcp

Publicación

CI (.gitlab-ci.yml) publica el paquete en el registro npm de GitLab de este proyecto automáticamente con una etiqueta del tipo vX.Y.Z; la autenticación se hace mediante el CI_JOB_TOKEN integrado, no se requieren tokens personales en CI.

La versión está duplicada en los manifiestos del plugin, y hay que subirla también allí:

npm version <major|minor|patch> --no-git-tag-version   # только package.json
# поправить version в обоих plugins/platform-mcp/*/plugin.json
npm run check:manifests                                # сверить
git commit -am "0.X.Y" && git tag v0.X.Y && git push --follow-tags

La discrepancia la detectará CI: el job test compara las versiones en los tres manifiestos y la coherencia de las dos descripciones del servidor, y publish compara la versión de la etiqueta con package.json. Sin esto, el plugin del usuario quedaría «sin cambios» con un servidor nuevo: tanto Claude Code como Cursor deciden si actualizar el plugin según su version.

No hace falta publicar el plugin por separado en ningún sitio: el push a main viaja a GitHub mediante el espejo de ramas protegidas, y los usuarios recogen los cambios mediante /plugin marketplace update. Tenga en cuenta que el plugin se instala desde la rama, no desde la etiqueta: en cuanto la corrección llega a main, ya está disponible para todos — incluso si la versión aún no se ha publicado con una etiqueta.