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.

Leer metadatos

Herramienta	Devuelve	Regla que la gobierna
list	Metadatos de todo secreto direccionable — coordenada, sensibilidad, modo, fingerprint, flags	Los valores nunca se devuelven; los secretos fuera de scope están ausentes
status	Metadatos de una coordenada	Da error si la coordenada no es direccionable en esta sesión
fingerprint	Un fingerprint corto y truncado de un valor	Truncado por diseño — suficiente para comparar, nunca para reconstruir

Usar un valor

Herramienta	Devuelve	Regla que la gobierna
inject_run	{status, stdout, stderr} con los valores del vault enmascarados	Los valores van al entorno del proceso hijo, nunca al contexto del llamante. high/prod requiere un ejecutable de la allowlist y un kovra approve atendido
reveal	El valor en texto plano, al contexto	Permitido solo para un secreto marcado como revelable que sea no-prod y no-high. prod / high / inject-only nunca se devuelven

Crear y gestionar

Herramienta	Devuelve	Regla que la gobierna
set	Los nuevos metadatos (no el valor)	Un secreto prod nace high
generate	Solo metadatos	El valor se genera del lado del servidor y se almacena; nunca se devuelve
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. Un humano la cumple fuera de banda, así que el valor nunca llega al contexto del agente (I11/I14)
edit_metadata	Metadatos actualizados	Edita sensibilidad / descripción / revealable / referencia; bajar la sensibilidad se audita por separado
delete	Confirmación	Da error si la coordenada no es direccionable en esta sesión

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.