Claude Code

OpaqueVault is designed first and foremost for Claude Code. This guide covers the full setup.

---

1. Install and authenticate

brew install opaquevault-brew/tap/ov
ov auth login

---

2. Store your secrets

ov secret set DATABASE_URL
ov secret set OPENAI_API_KEY
ov secret set STRIPE_SECRET_KEY

---

3. Unlock your vault

ov agent start

The agent holds your decryption key in memory — it’s what the MCP bridge talks to. It runs in the foreground, so keep this terminal open. Start it before Claude Code launches the bridge: without it, every MCP tool call fails with an ov agent is not running error, and once a session expires, calls return SESSION_LOCKED (see Troubleshooting).

---

4. Add to Claude Code MCP config

Claude Code reads MCP server configuration from ~/.claude/claude_desktop_config.json.

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

Save the file and restart Claude Code. You should see OpaqueVault listed in the MCP servers panel.

---

5. Verify the connection

In Claude Code, ask:

“Check the OpaqueVault status.”

Claude will call vault_status and respond with your session info, secret count, and interceptor status.

---

6. Use secrets in a session

Claude Code can now:

Run commands with secrets:

“Run the database migrations using my DATABASE_URL secret.”

Check what secrets are available:

“What secrets do I have stored in OpaqueVault?”

Store a new secret:

“Store my new Stripe key as STRIPE_SECRET_KEY.”

Tip

You don’t need to tell Claude to use vault_run explicitly. Just ask it to run commands that need credentials — Claude will figure out that it should use the MCP tool.

---

How it looks in practice

You: Run the database migrations.

Claude: I'll run the database migrations using your DATABASE_URL secret.

[Calls vault_run({ command: ["go", "run", "./cmd/migrate"], secret_names: ["DATABASE_URL"],
                   expected_app: "myapp", expected_env: "dev" })]

Result: exit_code: 0, redacted: true (stdout/stderr divert to the daemon terminal / agent log)

Claude: The migrations completed with exit code 0. The migration output is on
your agent terminal if you want the details.

The database URL never appeared — not in Claude’s thinking, not in the response, not in logs. Since v0.16.0 the subprocess output doesn’t appear to Claude either: you read it on the daemon terminal (foreground) or in the agent log (~/.local/state/ov/agent.log on Linux, ~/Library/Logs/ov/agent.log on macOS), matched by the response’s invocation_id.

---

The interceptor in Claude Code

If a secret pattern appears in a result one of OpaqueVault’s MCP tools is about to return, the bridge drops the whole result and Claude receives this instead:

⊘ BLOCKED · Secret pattern detected in output · Use vault_run to inject secrets safely instead

vault_status increments intercepted_count, and ov mcp serve writes a line naming the matched detectors to its own stderr.

The interceptor does not see your chat messages

It scans tool results on their way out of ov mcp serve. A secret you type or paste into the Claude Code chat goes straight to the model — no local process sits in that path, so nothing can intercept it. Treat a pasted credential as disclosed, and rotate it.

---

Windows users

Native Windows MCP support is in development (OV-59). Until it lands, use WSL2:

1. wsl --install (one-time)
2. Inside WSL2: curl -fsSL https://get.opaquevault.com | sh
3. Claude Code on Windows can connect to WSL2 MCP servers via localhost — no other config needed

The Windows-native CLI (ov auth, ov secret, ov run, ov scan) works today on Windows 10/11 without WSL2 — see the installation guide.

Troubleshooting

More fixes in the central Troubleshooting page.

Tool calls fail with a locked-vault error:

• Plain-text ov agent is not running … error → the agent wasn’t running when the bridge started. Run ov agent start, then restart Claude Code (a degraded bridge never reconnects on its own).
• {"code":"SESSION_LOCKED","action":"…"} → the agent is running but its session expired. Run ov agent stop then ov agent start, then restart Claude Code.
• Details: Troubleshooting → SESSION_LOCKED

OpaqueVault not showing in MCP servers:

• Verify ov is in your PATH: which ov
• Check the config file path and JSON syntax
• Restart Claude Code completely (quit and reopen)

vault_run returns secret_not_found:

• Run vault_list_secrets to see what’s stored
• Secret names are case-sensitive — DATABASE_URL ≠ database_url

Interceptor blocking legitimate content:

• Set OV_INTERCEPT_MODE=redact to keep the surrounding context and replace only the flagged values
• High-entropy false positives can be tuned — file an issue on GitHub