MCP Tools Overview

OpaqueVault exposes 8 MCP tools through ov mcp serve. Every tool is designed around one constraint: plaintext secret values never appear in any tool response.

Two tools that don’t exist — by design

There is no get_secret tool and no vault_inject_env tool. There never will be. MCP tool responses are visible to the AI model, so a tool that returns a plaintext secret value — or writes one to disk for later pickup — would defeat the entire purpose of OpaqueVault. Secrets only ever reach a subprocess environment via vault_run, ephemerally, and the response carries only the exit code and output.

Vault must be unlocked

All tools require a running, unlocked ov agent, and the two failure modes look different: if the agent wasn’t running when the bridge started, every tool returns a plain-text ov agent is not running — run 'ov agent start' in a terminal to unlock your vault error; if the agent is running but its session has locked or expired, tools return {"code":"SESSION_LOCKED","action":"…"} (the action field is a static remediation string). Fixes for both — including when an MCP client restart is required — in Troubleshooting.

---

App context

When ov mcp serve starts, it resolves the active app and environment through the standard chain (.ov.yaml, then your ov app use config default). All 8 tools resolve that (app, env) context per call — Claude Code does not need to pass an app parameter, but every tool call re-verifies context rather than trusting a value cached at bridge startup.

The active app is visible in vault_status, which reports the live-verified context for the most recent call, and vault_check_context lets the agent verify the resolved context before touching any secrets — its verdict now predicts every tool’s dispatch, not just vault_run’s.

---

Tools

Tool	Purpose
vault_run	Run a command with secrets injected as env vars — returns only exit code and output
vault_list_secrets	List secret names and metadata (never values) in the active app, scoped to the resolved env — the server still has no env filter; scoping is computed client-side. Ancient pre-encryption-era secret names never appear here in any env — use ov secret list
vault_secret_exists	Check whether a named secret exists (HMAC-based lookup)
vault_create_secret	Store a new secret — encrypted client-side, write-only
vault_update_secret	Rotate or update an existing secret’s value — write-only
vault_delete_secret	Permanently delete a secret (requires confirm: true)
vault_status	Session info, active app/env, interceptor count
vault_check_context	Preflight: verify the resolved app/env matches declared intent. Its verdict predicts every tool’s dispatch, not just vault_run’s — every tool resolves context the same way

---

What tools return

All tools return structured JSON. The schema is designed so that no field in any response ever contains a plaintext secret value.

vault_run returns:

{
  "exit_code": 0,
  "stdout": "migrations: 3 applied",
  "stderr": ""
}

vault_list_secrets returns:

{
  "secrets": ["DATABASE_URL", "OPENAI_API_KEY", "STRIPE_SECRET_KEY"],
  "total": 3
}

vault_status returns:

{
  "unlocked": true,
  "intercept_mode": "block",
  "intercepted_count": 0,
  "session_age_seconds": 600
}

vault_check_context returns {"match": true, "resolved": {...}} when the resolved app/env matches the declared expected_app / expected_env, or {"match": false, "reason": ..., "resolved": ..., "expected": ...} when they differ. With OV_STRICT_CONTEXT on (the default since v0.11.0), vault_run requires the same expected_app / expected_env declaration and refuses mismatches.

---

Tool availability by plan

All 8 MCP tools are available on every plan including Free. The interceptor is always active.