Referencia de herramientas MCP

Estas son las herramientas que kovra expone a un cliente MCP como Claude Code. Cada una corre a través de la única decisión de política de kovra; la tabla indica qué vuelve y la regla que la gobierna. Ninguna herramienta devuelve jamás un texto plano sensible — reveal es la única herramienta que devuelve valores, y solo dentro de una excepción estrecha.

Las coordenadas siguen la gramática de coordenadas; cualquier cosa fuera del scope de la sesión es no direccionable y nunca aparece.

Dentro de una sesión de Claude Code, las herramientas que entregan valores (inject_run, reveal) funcionan solo si la sesión tiene los hooks del gate de credenciales; las de metadatos funcionan siempre.

Leer metadatos

Herramienta	Devuelve	Regla que la gobierna
list	Metadatos de todo secreto direccionable — coordenada, sensibilidad, modo, fingerprint, flags, la nota de uso (description) y mint_only	Los valores nunca se devuelven; los secretos fuera de scope están ausentes
status	Metadatos de una coordenada, con la nota de uso y mint_only	Da error si la coordenada no es direccionable en esta sesión
fingerprint	Un fingerprint corto y truncado de un valor; — para un valor high, inject-only o de prod	Truncado por diseño — suficiente para comparar, nunca para reconstruir; los valores críticos no tienen

Preguntar antes de avisarle a la persona

La herramienta preflight responde si inject_run, reveal, set, generate, delete o edit_metadata le pedirían aprobación a la persona, dónde y por qué, sin ejecutar nada y sin devolver ningún valor. Una coordenada fuera del alcance es unaddressable; un reveal que necesitaría a la persona es refused. Vea Preflight.

Usar un valor

Herramienta	Devuelve	Regla que la gobierna
inject_run	{status, stdout, stderr} con los valores del vault enmascarados, más warnings si la corrida inyectó un secreto mint-only (también si se niega o vence). La corrida se detiene a los timeout_secs (120 por omisión, 600 como máximo) y cada flujo conserva hasta max_output_bytes (1 MiB por omisión, 4 MiB como máximo), e indica dónde se cortó	Los valores van al entorno del proceso hijo, nunca al contexto del llamante. high/prod requiere un ejecutable de la allowlist y una bioProve atendida en la ventana de revisión de kovra
reveal	El valor en texto plano, al contexto, más warnings para un secreto mint-only (también al negarlo)	Permitido solo para un secreto marcado como revelable que sea no-prod y no-high. prod / high / inject-only nunca se devuelven. Un valor con prefijo de credencial conocido llega al modelo redactado por el gate de credenciales

Crear y gestionar

Herramienta	Devuelve	Regla que la gobierna
set	Los nuevos metadatos (no el valor)	Un secreto prod nace high. Actualizar un secreto mint-only conserva su marca y su nota; uno nuevo en la bóveda de un proyecto sobre un secreto global mint-only se rechaza. Sobrescribir un secreto crítico (high/inject-only), o crear uno en la bóveda de un proyecto sobre uno global crítico, requiere una bioProve atendida
generate	Solo metadatos	El valor se genera del lado del servidor y se almacena; nunca se devuelve. length va de 1 a 4096 caracteres. La nota de uso admite hasta 500 caracteres. Crear uno en la bóveda de un proyecto sobre un secreto global crítico requiere una bioProve atendida
request_secret	Un id de solicitud para un intake pendiente	Encola una solicitud para crear un secreto — solo coordenada, sensibilidad, descripción, nunca un valor. Sobre un secreto que ya existe, lo rota, tras la aprobación de la persona (un par de claves o un secreto TOTP se rechaza). Un humano la cumple fuera de banda, así que el valor nunca llega al contexto del agente (I11/I14). Se rechaza la solicitud de un secreto de proyecto sobre uno global mint-only
edit_metadata	Metadatos actualizados	Edita sensibilidad / descripción / revealable / referencia / mint_only; bajar la sensibilidad se audita por separado. En un secreto crítico, una sola edición no puede cambiar a la vez su sensibilidad y su referencia. Una referencia nueva se revisa primero por su forma (sin llamar al proveedor): la que una ejecución rechazaría se rechaza, antes de pedir nada o de escribir. Puede marcar un secreto como mint-only, pero nunca desmarcarlo ni cambiar su nota
delete	Confirmación	Da error si la coordenada no es direccionable en esta sesión. Un secreto mint-only nunca se borra aquí

Notas de uso y secretos mint-only

Cada secreto puede llevar una nota de uso — su description, de hasta 500 caracteres — que list y status muestran, para que un agente lea cómo se debe usar un secreto antes de usarlo. La nota es un metadato de la persona, nunca instrucciones para debilitar kovra.

Un literal o una referencia también puede ser mint-only: una credencial maestra que solo debe usarse para acuñar un token hijo con alcance acotado. Revelar o inyectar uno no se bloquea; la respuesta — o el rechazo — agrega warnings, uno por cada secreto mint-only:

{
  "warnings": [
    {
      "coordinate": "dev/example/admin-token",
      "note": "mint a repo-scoped token for each job",
      "advice": "mint-only: use this secret only to mint a scoped child token; do not use it directly"
    }
  ]
}

El advice es el texto propio de kovra; la note es de la persona, en su propio campo. Un agente puede marcar un secreto como mint-only con edit_metadata, pero solo la persona lo desmarca, cambia su nota, lo borra o lo cubre desde la bóveda de un proyecto, desde la CLI. Eso protege frente a un agente que trabaja con estas herramientas; un agente que puede ejecutar comandos de shell también puede usar la CLI, así que la marca es una guía para los agentes, no un candado. Un secreto fuera del scope de la sesión no muestra ni su nota ni su marca.

El patrón detrás de la tabla

Tres propiedades se sostienen en cada fila, y vale la pena nombrarlas porque son la razón por la que se puede confiar a un agente estas herramientas en absoluto:

1. Leer metadatos es siempre seguro — listar, diagnosticar y hacer fingerprinting nunca toca un valor.
2. Usar un valor nunca lo revela — inject_run entrega un secreto a través de un proceso y lo enmascara a la salida.
3. Crear un valor nunca lo expone — set y generate devuelven solo metadatos, así que una credencial recién generada nunca pasa por el contexto del modelo.

La única excepción — reveal — es deliberadamente la herramienta más restringida de todas. Ver kovra sobre MCP para la versión narrada y el proceso de decisión para saber exactamente cómo se juzga cada llamada.