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).
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
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 токен>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-mcpLa 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-mcpy 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+.
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-mcpSe 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-browserEl 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.
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 vaultNo 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.
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.
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.
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/k8sya 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 enargocd-rbac-cmy las políticas de Vault.
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=trueOpt-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í.
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:
Si argocd / vault / kcadm (kcadm.sh) ya está en PATH — se usa ese, no se descarga nada.
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.
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».
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í.
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=trueDesactiva 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)редактор ──stdio──▶ platform-mcp ──argv+env──▶ argocd ──▶ Argo CD
(OIDC, политика, vault ──▶ Vault
вырезание секретов) kcadm ──▶ KeycloakArgo 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.
npm install
npm run build
npm testLos 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).
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 — с обёрткой mcpServersLa 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-mcpCI (.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-tagsLa 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.
Кто вошёл в Argo CD и до какого момента действует токен.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description adds meaningful behavioral context by specifying the exact output (user identity and token timeout). This is sufficient for a read-only status tool and supports the agent's understanding of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant information. It is concise and front-loaded, stating exactly what the tool reports.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status tool with no output schema, the description provides all necessary context: it tells the agent what the tool returns and implies its read-only nature. There are no gaps in coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so the description carries the full burden by confirming that no arguments are needed. This aligns with the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly identifies the tool's function: reporting who is logged into Argo CD and the token's expiration. It clearly distinguishes this status query from sibling tools like argocd_login and argocd_logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The nature of a status tool implies it is used to check current authentication state, but no explicit guidance is given about when to use this versus alternatives. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Выполнить команду argocd (https://argocd.infra.sonar-corp.ru) от имени вошедшего пользователя.
Аргументы командной строки argocd, массивом. Адрес и токен подставляются сервером — флаги --server, --auth-token, --config, --core запрещены.
Примеры: ["app", "list", "-o", "json"] ["app", "get", "team-a-api", "-o", "json"] ["app", "sync", "team-a-api"] ["app", "logs", "team-a-api", "--tail", "100"] ["proj", "list", "-o", "json"]
Флаг вывода в JSON (-o json) стоит добавлять всегда, когда команда его поддерживает: табличный вывод разбирать сложнее и в нём теряются поля.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | Аргументы командной строки, по одному на элемент массива. | |
| stdin | No | Данные на стандартный ввод команды, если она их читает. | |
| __confirm | No | Токен подтверждения. Заполняется только при повторном вызове, после явного согласия пользователя на мутирующую операцию. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains that the address and token are supplied by the server and that certain flags are prohibited, which adds useful context. However, it does not mention potential side effects of mutating commands (e.g., `app sync`) or the confirmation flow described in the `__confirm` parameter schema, nor does it describe error/exit-code handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it front-loads the purpose, then states key constraints, provides illustrative examples, and finishes with a useful tip. Every sentence serves a purpose without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an exec-style tool, the description covers invocation, authentication, forbidden flags, and output format advice. It does not explicitly state the return format (e.g., raw stdout, exit codes) or error handling, which is a minor gap given there is no output schema. Overall, it is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage, but the description goes beyond by showing concrete examples of the `args` array structure and recommending `-o json` for better output parseability. This adds practical meaning that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it executes an `argocd` command on behalf of the authenticated user, using a specific verb and resource. It clearly distinguishes itself from sibling tools like `argocd_login`, `argocd_auth_status`, and `argocd_logout` by focusing on command execution rather than authentication. Examples further solidify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to run argocd commands) and gives practical advice, such as always adding `-o json` for parseable output and forbidding certain flags (`--server`, `--auth-token`, `--config`, `--core`). However, it does not explicitly state prerequisites like 'authenticate first with argocd_login' or compare with alternative tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Начать вход в Argo CD через GitLab SSO. Возвращает ссылку сразу, не дожидаясь завершения входа: результат нужно проверить вызовом argocd_auth_status.
| Name | Required | Description | Default |
|---|---|---|---|
| noBrowser | No | Не открывать браузер, только вернуть ссылку (SSH, devcontainer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses that the tool returns immediately without waiting for login completion, which is a critical non-obvious behavior. It also states that a link is returned, adding useful context, though it doesn't detail side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, consisting of two short sentences that immediately convey the main action and the asynchronous behavior. It avoids extraneous details while including the essential next step, making it well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers the tool's behavior for a simple login initiation: it returns a link and requires follow-up via argocd_auth_status. It doesn't describe the exact response format beyond 'link', but given the simplicity of the tool and absence of output schema, this is adequate. The context provided by sibling tools reinforces the intended workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single parameter noBrowser with a clear description in Russian, giving 100% schema coverage. The tool description does not elaborate on this parameter, but since the schema covers it, a baseline score of 3 is appropriate without additional value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it initiates an Argo CD login via GitLab SSO and returns a link immediately, using the specific verb 'login' and resource 'Argo CD'. It also distinguishes itself from the sibling argocd_auth_status by noting that the result must be checked via that tool, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining that the login is asynchronous and directing the agent to call argocd_auth_status to verify the result. While it doesn't explicitly exclude other tools or mention preconditions, it effectively guides the agent to the correct workflow among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Удалить сохранённую сессию Argo CD.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. 'Удалить сохранённую сессию' explicitly states that a saved session is deleted, which conveys a clear side effect. However, it does not indicate whether the deletion is purely local or also interacts with the server, and whether it is irreversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. Every word contributes to the meaning, and the information is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter logout operation, the description is mostly sufficient. It could add a note about the irreversible nature of removing local credentials or that the user must re-authenticate afterwards, but the core behavior is clear enough for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is fully covered (empty schema). According to the calibration baseline for zero-parameter tools, a score of 4 is appropriate since there is no parameter information to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Удалить сохранённую сессию Argo CD' clearly states the action (delete) and the resource (saved Argo CD session), distinguishing it from sibling tools like argocd_login and argocd_auth_status. The verb and object are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool or how it relates to alternatives. It does not mention that it reverses argocd_login or that it should be called before checking auth status with argocd_auth_status. Usage context must be inferred entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Кто вошёл в Vault и до какого момента действует токен.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It clearly states what is reported (user and token expiry) and implies it is a read-only status operation. It does not mention prerequisites like 'must be logged in' or error handling, but for a simple status tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that delivers complete meaning without waste. It is front-loaded with the core purpose and adds no redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and a simple status-check function, the description adequately covers the essential information: who and until when. It does not detail edge cases like unauthenticated state, but that is not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. Per the rubric, the baseline for 0 params is 4; the description appropriately omits parameter details since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: showing who is logged into Vault and the token expiration time. It uses a specific verb (status check) and resource (Vault), distinguishing it from sibling tools like argocd_auth_status, which clearly targets ArgoCD.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is evident: this is for checking Vault authentication status, as opposed to login/logout or ArgoCD-related tools. It stops short of explicitly naming alternatives or exclusion criteria, but the intended use is clear from the description and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Выполнить команду vault (https://vault.infra.sonar-corp.ru) от имени вошедшего пользователя.
Аргументы командной строки vault, массивом. Адрес и токен подставляются сервером — флаги -address, -tls-skip-verify запрещены, вход делается через vault_login.
Примеры: ["kv", "list", "kv/teams"] ["kv", "get", "kv/teams/team-a/postgres"] ["kv", "put", "kv/teams/team-a/postgres", "password=..."] ["policy", "read", "team-a"] ["read", "sys/mounts"]
Вывод по умолчанию в JSON (VAULT_FORMAT=json). Значения секретов вырезаются: возвращаются имена ключей и метаданные, но не содержимое — оно не должно попадать в контекст модели.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | Аргументы командной строки, по одному на элемент массива. | |
| stdin | No | Данные на стандартный ввод команды, если она их читает. | |
| __confirm | No | Токен подтверждения. Заполняется только при повторном вызове, после явного согласия пользователя на мутирующую операцию. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds significant behavioral context: server-side address/token injection, JSON output, and secret redaction ('Значения секретов вырезаются'). It omits the __confirm requirement for mutating operations (only in schema), but the redaction and credential handling are valuable disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, constraints, examples, and output behavior in three tight paragraphs. The examples are relevant and not excessive, earning their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic command executor, it covers execution scope, authentication precondition, output format, and secret safety. The missing confirmation flow is covered in the schema, so the description is sufficiently complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a clear description. The description's examples ('kv get', 'kv put') show how to structure args arrays, but they add practical value rather than deep semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes vault commands on behalf of the logged-in user ('Выполнить команду vault ... от имени вошедшего пользователя'), which distinguishes it from sibling auth tools. Examples like 'kv get' and 'policy read' illustrate the supported operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies a precondition: login via vault_login ('вход делается через vault_login'), and prohibits certain flags (-address, -tls-skip-verify). It doesn't explicitly name alternatives, but sibling tools are clearly auth-only, leaving vault_exec as the execution counterpart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Начать вход в Vault через GitLab SSO. Возвращает ссылку сразу, не дожидаясь завершения входа: результат нужно проверить вызовом vault_auth_status.
| Name | Required | Description | Default |
|---|---|---|---|
| noBrowser | No | Не открывать браузер, только вернуть ссылку (SSH, devcontainer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It transparently reveals the asynchronous nature ('returns a link immediately, does not wait for login completion') and instructs to verify via vault_auth_status. This goes beyond basic 'login' expectations, though it does not mention edge cases like already-authenticated states or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and key detail (returns a link). Every sentence contributes value: the first states the purpose, the second explains the async behavior and follow-up. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple login tool with one optional parameter and no output schema, the description is complete. It tells the user what to expect (a link) and what to do next (call vault_auth_status). The schema covers the parameter, and the flow is adequately explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter 'noBrowser'. The description does not add any additional meaning beyond what the schema already provides, so the baseline of 3 applies. No enhancement or clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Start login to Vault via GitLab SSO.' It uses a specific verb ('start login'), names the resource (Vault) and the method (GitLab SSO), and distinguishes itself from sibling tools like vault_logout or vault_auth_status by focusing on initiating the login flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating that the tool returns a link immediately and that the result must be checked via vault_auth_status. This implicitly guides the user to follow up with the status check. However, it does not explicitly compare with alternatives like argocd_login, though the resource distinction is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Удалить сохранённую сессию Vault.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral consequences. It only states that a saved session is deleted, without explaining side effects (e.g., whether the Vault token is invalidated server-side, whether other sessions are affected, or whether the action is reversible). This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no redundant words. It is front-loaded and efficient, conveying the full purpose in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of a logout tool, the description is adequate but leaves out behavioral details such as idempotency, error outcomes, or whether an active session is required. With no annotations and no output schema, a bit more context would be helpful, but the tool is basic enough that a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is trivially 100% covered. Per the baseline rule for 0-param tools, the description need not add parameter details, and the empty schema leaves no room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Удалить сохранённую сессию Vault' (Delete saved Vault session) uses a specific verb and resource, clearly distinguishing it from siblings like vault_login and vault_auth_status. It leaves no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings such as argocd_logout or vault_login. There is no mention of prerequisites, typical scenarios, or conditions under which this tool should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1argocd_auth_statusargocd_execargocd_loginargocd_logoutvault_auth_statusvault_execvault_loginvault_logoutScored across 8 tools
Each tool is clearly scoped to either Argo CD or Vault, and within each service the login, auth_status, logout, and exec actions are distinct. The system prefix (argocd_ vs vault_) removes any ambiguity between the two sets.
All tool names follow the consistent pattern {service}_{action} using lowercase snake_case: login, auth_status, logout, exec. The naming is uniform and predictable across both Argo CD and Vault.
With 8 tools covering two infrastructure services, the count is well-scoped. Each tool serves a clear and necessary purpose, leaving no redundancy or bloat.
For a server designed to provide authenticated CLI access to Argo CD and Vault, the tool surface is complete: login, auth status check, logout, and command execution for each system. The exec tools are generic enough to cover the full command surface of both CLIs.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
