LocalVault MCP — Secrets for AI Agents

AI coding agents need your API keys to do useful work — call your APIs, deploy your code, interact with services. But you don't want to paste secrets into chat, hardcode them in config files, or give your agent a plaintext credential store.

LocalVault solves this with a built-in MCP (Model Context Protocol) server. Your secrets stay encrypted. The agent gets controlled read/write access. Your passphrase never leaves your machine.

One-time setup

localvault install-mcp

This registers localvault as a user-scope MCP server in Claude Code globally — works across all your projects without per-project configuration.

For Cursor or Windsurf:

localvault install-mcp cursor
localvault install-mcp windsurf

How it works

When you run eval $(localvault unlock) or localvault show, the derived master key is cached for the active vault. MCP uses the same default-vault and session-cache rules as the CLI, so localvault switch, LOCALVAULT_VAULT, and localvault lock affect what the agent can access.

The agent never sees your passphrase. It gets access to individual secrets only when it calls the MCP tools.

Tools available to the agent

Tool	What it does
`localvault_whoami`	Diagnose active vault, session, and unlocked state
`list_secrets`	List/search secret keys (values hidden)
`localvault_build_exec`	Build a `localvault exec` command for process injection
`get_secret`	Retrieve an exact secret key when plaintext is explicitly allowed
`set_secret`	Store a new secret
`delete_secret`	Delete a secret

All tools accept an optional vault parameter to target a specific named vault.

Multiple vaults

The agent can work with any unlocked vault:

get_secret(key: "DATABASE_URL", vault: "production")
set_secret(key: "NEW_TOKEN", value: "...", vault: "staging")
list_secrets(vault: "intellectaco")
list_secrets(vault: "intellectaco", prefix: "AWS_IAM.")
localvault_build_exec(command: ["aws", "sts", "get-caller-identity"], profile: "aws")

If no vault is specified, MCP uses the same active vault as the CLI: explicit vault, then LOCALVAULT_VAULT, then localvault switch / configured default.

For most agent work, prefer localvault_build_exec over get_secret. The agent can run a command with injected environment variables without copying the secret value into model context. get_secret requires an exact key and an explicit plaintext acknowledgement.

Manual config (without install-mcp)

If you prefer manual setup, add to your MCP config:

{
  "mcpServers": {
    "localvault": {
      "command": "localvault",
      "args": ["mcp"]
    }
  }
}

The server picks up the active default vault and any cached unlock state automatically.

Security model

Your passphrase never touches the MCP protocol
The session token (LOCALVAULT_SESSION) is a derived key — it can decrypt your vault but cannot reconstruct your passphrase
Cached unlocks expire by TTL or immediately when you run localvault lock
The MCP server only runs when invoked — there is no background daemon