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 7 MCP tools with the client
• Holds your KEK in memory for the session duration
• Runs the context interceptor on all inbound MCP messages
• Handles tool calls: decrypts secrets locally, injects as env vars, returns only exit codes and output

---

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

WARN mode is provided for debugging. In production, always use BLOCK mode. Warn mode means secrets can reach the model — which defeats the purpose of OpaqueVault.

---

Session lifetime

The KEK is held in memory for the duration of ov mcp serve. When the process exits, the KEK is zeroed from memory. The next session requires the master password to derive a new KEK.

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