Wundervault Vault

Wundervault is an encrypted, self-hosted secret vault that exposes secrets to agents via MCP tools. Secrets never appear in chat — they are decrypted server-side and injected directly into commands or returned over the encrypted MCP channel.

Check Setup First

Before doing anything vault-related, check whether the vault tools are available:

• vault_entries_list — available? → vault is connected, proceed
• If tools are missing → tell the user to install the MCP server (see INSTALL.md)

Tools

vault_entries_list

List all vault entries available to this agent. Returns entry IDs and names only — no secret values.

vault_entries_list()
→ [{ id: "abc123", name: "ResendApiKey", tier: "full" }, ...]

Use this first to discover available secrets before calling vault_entry_get.

vault_entry_get

Retrieve a secret by entry ID. The plaintext value is returned over the encrypted MCP channel.

vault_entry_get(entry_id: "abc123")
→ { name: "ResendApiKey", value: "re_..." }

Use the entry ID from vault_entries_list, not the secret name.

vault_exec

Execute a shell command with a vault secret injected — the secret is never exposed in chat or logs.

vault_exec(entry_id: "abc123", command: "npm publish --access public")

Two tiers:

• Tier 1 (free): runs immediately, no unlock needed
• Tier 2 (session-locked): call vault_session_unlock first — used for high-risk operations (deployments, publishes, infrastructure changes)

Shell escape sequences ($(), backticks, bash -c, eval) are hard-blocked before the secret is decrypted. Do not attempt to use them.

vault_entry_inject_env

Write a secret into a config file as an environment variable, without it passing through chat.

vault_entry_inject_env(entry_id: "abc123", path: "/home/user/app/.env", key: "RESEND_API_KEY")

vault_session_unlock

Unlock Tier 2 execution for the current session. Call this before vault_exec on a Tier 2 entry.

vault_session_unlock()
→ { unlocked: true, expires_at: "..." }

vault_session_status

Check whether the current session is unlocked and when it expires.

vault_session_status()
→ { locked: false, expires_at: "..." }

vault_entry_forget

Discard a vault entry reference from context. Does not delete the vault entry.

vault_entry_forget(entry_id: "abc123")
→ ✔️ Reference discarded.

Common Patterns

Find and read a secret:

1. vault_entries_list() → get entry ID for "ResendApiKey"
2. vault_entry_get(entry_id: "abc123") → use value

Run a command with secret injected (Tier 1):

vault_exec(entry_id: "abc123", command: "aws s3 sync ./dist s3://mybucket")

Tier 2 flow (e.g. npm publish, deploy):

1. vault_session_unlock()
2. vault_exec(entry_id: "abc123", command: "npm publish --access public")

Security Notes

• Secrets are end-to-end encrypted; the agent receives only what it needs
• The inject_as field on vault entries controls how the secret is passed (env var name, CLI flag prefix, etc.)
• Tier 2 entries are configured by the vault owner — the agent cannot escalate a Tier 1 entry to Tier 2
• Never echo, log, or store a secret retrieved via vault_entry_get

More Info

• npm: @wundervault/mcp-server
• Vault UI: wundervault.com