MCP tool reference

These are the tools kovra exposes to an MCP client such as Claude Code. Each one runs through kovra’s single policy decision; the table notes what comes back and the rule that governs it. No tool ever returns a sensitive plaintext — reveal is the only value-returning tool, and only within a narrow exception.

Coordinates follow the coordinate grammar; anything outside the session scope is unaddressable and never appears.

Inside a Claude Code session, the value-delivering tools (inject_run, reveal) work only when the session carries the credential gate’s hooks; the metadata tools always work.

Read metadata

Tool	Returns	Governing rule
list	Metadata for every addressable secret — coordinate, sensitivity, mode, fingerprint, flags, the usage note (description) and mint_only	Values never returned; out-of-scope secrets are absent
status	Metadata for one coordinate, the usage note and mint_only included	Errors if the coordinate isn’t addressable in this session
fingerprint	A short, truncated fingerprint of a value; — for a high, inject-only or prod value	Truncated by design — enough to compare, never to reconstruct; critical values have none

Ask before you tell the person

The preflight tool answers whether inject_run, reveal, set, generate, delete or edit_metadata would ask the person, where and why, without running anything and without returning a value. An out-of-scope coordinate is unaddressable; a reveal that would need the person is refused. See Preflight.

Use a value

Tool	Returns	Governing rule
inject_run	{status, stdout, stderr} with vault values masked, plus warnings when the run injected a mint-only secret (a denied or timed-out run carries them too). The run stops after timeout_secs (default 120, at most 600) and each stream keeps at most max_output_bytes (default 1 MiB, at most 4 MiB), saying where it was cut	Values go into the child process’s environment, never the caller’s context. high/prod requires an allowlisted executable and an attended bioProve in kovra’s review window
reveal	The plaintext value, into context, plus warnings for a mint-only secret (on a refusal too)	Permitted only for a secret marked revealable that is non-prod and non-high. prod / high / inject-only are never returned. A value with a known credential prefix reaches the model redacted by the credential gate

Create and manage

Tool	Returns	Governing rule
set	The new metadata (not the value)	A prod secret is born high. Updating a mint-only secret keeps its mark and note; a new one in a project vault over a mint-only global secret is refused. Overwriting a critical (high/inject-only) secret, or creating one in a project vault over a critical global one, takes an attended bioProve
generate	Metadata only	Value is generated server-side and stored; never returned. length is 1 to 4096 characters. The usage note takes at most 500 characters. Creating one in a project vault over a critical global secret takes an attended bioProve
request_secret	A request id for a pending intake	Queues a request to create a secret — coordinate, sensitivity, description only, never a value. Over a secret that already exists it rotates it, after the person’s approval (a keypair or a TOTP secret is refused). A human fulfils it out-of-band, so the value never reaches the agent’s context (I11/I14). A request for a project secret over a mint-only global one is refused
edit_metadata	Updated metadata	Edits sensitivity / description / revealable / reference / mint_only; lowering sensitivity is separately audited. On a critical secret, one edit can’t change both its sensitivity and its reference. A new reference is checked by its form first (no provider call): one a run would refuse is refused, before anything is asked or written. It may mark a secret mint-only, but never unmark one nor change its note
delete	Confirmation	Errors if the coordinate isn’t addressable in this session. A mint-only secret is never deleted here

Usage notes and mint-only secrets

Every secret can carry a usage note — its description, at most 500 characters — that list and status show, so an agent reads how a secret is meant to be used before it uses it. The note is the person’s metadata, never instructions to weaken kovra.

A literal or a reference can also be mint-only: a master credential that should only mint a scoped child token. Revealing or injecting one is not blocked; the answer — or the refusal — adds warnings, one per mint-only secret:

{
  "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"
    }
  ]
}

The advice is kovra’s own text; the note is the person’s, in its own field. An agent may mark a secret mint-only with edit_metadata, but only the person unmarks it, changes its note, deletes it or covers it from a project vault, from the CLI. That protects against an agent working through these tools; an agent that can run shell commands can run the CLI too, so the mark is guidance for agents, not a lock. A secret outside the session’s scope shows neither its note nor its mark.

The pattern behind the table

Three properties hold across every row, and they’re worth naming because they’re the reason an agent can be trusted with these tools at all:

1. Reading metadata is always safe — listing, diagnosing, and fingerprinting never touch a value.
2. Using a value never reveals it — inject_run delivers a secret through a process and masks it on the way out.
3. Creating a value never exposes it — set and generate return only metadata, so a freshly generated credential never passes through the model’s context.

The single exception — reveal — is deliberately the most constrained tool of all. See kovra over MCP for the narrative version and the decision process for exactly how each call is judged.