ov mcp serve

import { Aside } from ‘@astrojs/starlight/components’;

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 output are returned
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). 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 messages containing secrets, `warn` allows them through but logs the event
`OV_API_KEY`	from `~/.ov/config`	Override the API key used for this session
`OV_API_URL`	`https://api.opaquevault.com`	Override the API endpoint (useful for self-hosted)
`OV_LOG_LEVEL`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`

Interceptor modes

# Default — block any message containing a detected secret
OV_INTERCEPT_MODE=block ov mcp serve

# Warn mode — log the event but allow the message through
OV_INTERCEPT_MODE=warn ov mcp serve

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.