ov mcp serve

ov mcp serve starts OpaqueVault as a local MCP server over stdio. It’s the bridge between your AI client (Claude Code, Cursor, etc.) and your encrypted secrets.

You don’t run this command manually — your MCP client config runs it for you.

---

Claude Code config

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "opaquevault": {
      "command": "ov",
      "args": ["mcp", "serve"]
    }
  }
}

---

What it does

• Starts a JSON-RPC 2.0 MCP server on stdin/stdout
• Registers all 8 MCP tools with the client
• Connects to the running ov agent over a Unix socket — the agent holds your KEK, not the bridge
• Runs the context interceptor on all inbound MCP messages
• Handles tool calls: secrets are decrypted locally by the agent, injected as env vars, and only exit codes and run metadata are returned — subprocess output diverts to the daemon terminal / agent log (v0.16.0)
• Prints its own version, commit, and build time at startup, so a bridge left running across an in-place binary upgrade is visible at a glance (see Upgrading)
• Resolves and verifies the project’s .ov.yaml (app, env) per call, for every MCP tool (not just vault_run) as of v0.12.0 (OV-319) — and since OV-305 the daemon enforces that env end-to-end (previously it was bridge-verified only; the daemon served its start-time env regardless). vault_run and the three write tools additionally require declared expected_app/expected_env under OV_STRICT_CONTEXT (default on)

---

Environment variables

Variable	Default	Description
OV_INTERCEPT_MODE	block	Interceptor mode: block drops any tool result containing a detected secret, redact replaces the detected values and lets the rest through. Any other value falls back to block.
OV_API_KEY	from ~/.ov/config	Override the API key used for this session
api_url (config file)	https://api.opaquevault.com	Override the API endpoint for self-hosting. Set in ~/.config/ov/config.toml or via ov auth login --api-url — there is no OV_API_URL environment variable.
OV_LOG_LEVEL	info	Log verbosity: debug, info, warn, error

---

Interceptor modes

# Default — drop any tool result containing a detected secret
OV_INTERCEPT_MODE=block ov mcp serve

# Redact mode — replace detected values, pass the surrounding context through
OV_INTERCEPT_MODE=redact ov mcp serve

Caution

REDACT mode lets the rest of the result reach the model, and redaction quality is bounded by detector precision — if a detector matches only a prefix of a value, the remainder passes through. Use BLOCK where any partial leak is unacceptable.

There is no mode that disables the interceptor. An unset or unrecognized OV_INTERCEPT_MODE resolves to BLOCK.

---

Session lifetime

The unlocked session lives in the ov agent daemon, not in the bridge. Start it with ov agent start before the MCP client launches the bridge. The two failure modes differ:

• Agent not running at bridge startup — the bridge starts in degraded mode and every tool call returns a plain-text ov agent is not running — run 'ov agent start' in a terminal to unlock your vault error. A degraded bridge never re-dials the agent: start the agent, then restart the MCP client.
• Agent running but session locked/expired — tool calls return {"code":"SESSION_LOCKED","action":"…"}. Restart the session with ov agent stop + ov agent start, then restart the MCP client (an interactively-started agent mints a new socket key the running bridge doesn’t have).

Details in Troubleshooting. When the agent locks or exits, the KEK is zeroed from memory; the next ov agent start requires the master password. Machine-key agents serve headless ov run use only — the MCP bridge cannot authenticate to a machine-key agent today, so MCP sessions need an interactively unlocked agent.

The MCP client (Claude Code) starts and stops ov mcp serve automatically based on your config. You don’t need to manage the bridge’s process lifecycle manually — only the agent’s.