Wundervault MCP

What is Wundervault MCP?

Wundervault MCP is an open-source Model Context Protocol server that integrates with the Wundervault secret management service. It allows AI agents to securely retrieve and use vault secrets with a zero-knowledge encryption model—the server never sees the decryption key. Designed for developers and operators who need agent-driven secret handling without exposing plaintext secrets to the calling process.

How to use Wundervault MCP?

Clone the repository, run npm install and npm run build, then configure credentials via CLI flags (--api-key, --enc-key, --url), environment variables, or a credentials JSON file. Use the provided MCP tools (vault_entries_list, vault_entry_get, vault_entry_forget) to list, retrieve, and discard secret references. The vault_entry_get tool supports an optional exec parameter to run a shell command with the decrypted secret; the plaintext is never returned to the agent.

Key features of Wundervault MCP

• Zero-knowledge encryption key lives only in the MCP process.
• Burn-after-reading: plaintext secrets are never returned to the calling agent.
• Exec scrubbing: stdout/stderr are stripped of plaintext when using exec.
• Directive integrity verified via PBKDF2-HMAC-SHA256 with 600k iterations.
• Timing-safe HMAC comparison using crypto.timingSafeEqual.

Use cases of Wundervault MCP

• List all vault entries available to an agent without exposing secret values.
• Retrieve and decrypt a vault secret for use in an automated task (e.g., service restart).
• Execute a command with a decrypted secret using a secure stdin pattern (e.g., sudo -S).
• Discard a local reference to a vault entry after use.

FAQ from Wundervault MCP

How is the encryption key stored?

The encryption key lives only in the MCP server process memory. It is loaded from CLI flags, environment variables, or a credentials file; the Wundervault server never sees it.

What happens to plaintext secrets after decryption?

After decryption, the calling agent receives only the message "Secret retrieved and burned." The plaintext is never returned and is immediately discarded.

How can I use the exec parameter securely?

Pass the secret via stdin using a heredoc pattern (e.g., sudo -S systemctl restart nginx <<< "$WUNDERVault_SECRET"). Do not use echo $SECRET | sudo -S as that exposes the secret in process logs.

What credential loading methods are supported?

Credentials are loaded in this order: CLI flags (--api-key, --enc-key, --url), environment variables (WUNDERVault_AGENT_VAULT_API_KEY, WUNDERVault_AGENT_KEY, WUNDERVault_AGENT_VAULT_URL), WUNDERVault_CREDENTIALS_FILE environment variable, ~/.wundervault/creds.json, and ~/.config/wundervault/credentials.

What is the license and open‑core model?

Licensed under AGPL-3.0-or-later. The MCP server and client are open source; the hosted service at wundervault.com is a commercial offering.