vault-mcp

A personal secrets vault your AI coding agent can use without ever seeing your keys.

Store your API keys once. When the agent needs a Stripe key, a Google Maps key or a database URL, it searches the vault, finds the metadata, and writes the value straight into your .env. The value goes to disk; the conversation only ever sees the variable name.

You:    "Add a map to the dashboard showing user locations."

Agent:  [vault_search "google maps"]  -> finds google-maps/default/api_key
        [vault_inject_env]            -> writes NEXT_PUBLIC_GOOGLE_MAPS_API_KEY into .env
        "I set NEXT_PUBLIC_GOOGLE_MAPS_API_KEY in .env and wired up the map component."

No more pasting keys into chat.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity, VS Code, Zed — anything that speaks MCP over stdio.

What it does

• Your agent stops asking you for keys. It searches the vault first and injects what it finds.

• It never sees the values. All 29 tools return metadata and status only. Values go to a file, a process environment or a remote server, never back through the conversation.

• Groups and accounts. stripe/acme and stripe/personal stay apart, each with its own secret key, publishable key and webhook secret.

• Projects. A project holds its own secrets and links to shared ones, so one call sets up a whole .env.

• Four injection targets. A local .env, any config file through {{vault:path}} placeholders, a command's environment with the output redacted, or a remote server's env file over SSH.

• Two ways to add a key. Tell the agent the value, or have it open the vault in your browser so you type the key in yourself behind your access code.

• Encrypted at rest, no password to remember. AES-256-GCM, with the master key in Windows Credential Manager or the macOS Keychain.

• An access code for what matters. Gates the web UI, and individually gates any secret marked --protected.

• Backups. Local snapshots for undoing mistakes, portable passphrase-sealed backups for a drive or another machine.

• Guard rails. It refuses to write a secret into a git-tracked file, warns when a server-only key is headed for a browser variable, and logs every read and injection.

• 15 service presets. Stripe, Google Maps, AWS, OpenAI, Anthropic, Cloudflare, Supabase, Firebase, Twilio, SendGrid, Resend, GitHub, a database URL, an SSH server, and a generic catch-all.

Related MCP server: Vault MCP

Install

git clone https://github.com/MHasnainJafri/vault-mcp.git
cd vault-mcp
npm install
npm run build
npm link                # makes `vault` available everywhere (optional)
vault init              # creates ~/.vault-mcp and the master key

Then register it with your editor or agent. vault install shows which clients it found on your machine:

vault install                       # list clients, and mark the ones detected
vault install --client cursor       # write that client's config
vault install --all                 # every client it detected
vault install --print               # just show the JSON to paste

The config it writes is merged into whatever is already there, and the original is copied to <config>.vault-backup first, so no other server or setting is disturbed.

Any other MCP client takes the standard block:

{
  "mcpServers": {
    "vault": { "command": "node", "args": ["/abs/path/to/vault-mcp/dist/cli.js", "serve"] }
  }
}

VS Code names that block servers instead of mcpServers. A newly registered server appears the next time the client starts.

Then set your access code, which you type yourself and never share with the agent:

vault set-pin

Add your keys

Three ways, none of which put the value in a chat window.

Guided, per service — walks the fields a service needs, hidden prompts:

vault add stripe/acme          # secret_key, publishable_key, webhook_secret
vault add google-maps/default  # api_key
vault setup                    # first-run wizard: init + first service + install

One key at a time:

vault add openai/personal/api_key --env OPENAI_API_KEY --tags ai
cat key.pem | vault add ssh/prod/private_key --stdin

Import a file you already have — a .env, or a JSON object of named fields:

vault import ./my-app/.env --to projects/my-app
vault import ./server.json --to vps/my-server

JSON is the quickest way to add something with several fields at once:

{ "host": "198.51.100.20", "username": "deploy", "password": "…", "port": 22 }

Each field becomes its own secret. Nested objects are flattened, so {"db":{"user":"root"}} becomes db/user, and an array is kept whole as one value. The format is picked from the file extension, or sniffed from the content if the name does not say.

Or use the local web UI:

vault ui

Opens http://127.0.0.1:5177 on loopback only. If you have set an access code it asks for that first. Add, edit, tag, import, back up, and reveal values (reveal works only in this local page, never through the agent).

Two ways to add a key mid-conversation

When the agent needs a key you do not have stored yet, you pick which way it goes in:

For the second one, the agent is deliberately not given the URL token, so it cannot read that page. Your access code is what unlocks it.

vault set-pin      # set the access code once

Organize

Paths are group/account/field, so multiple accounts of the same service stay apart:

stripe/
  acme/       secret_key, publishable_key, webhook_secret
  personal/   secret_key
google-maps/
  default/    api_key
projects/
  my-shop/    database_url            <- project-specific

Link a shared key into a project instead of copying it:

vault link projects/my-shop stripe/acme/secret_key
vault link projects/my-shop stripe/acme/secret_key --env PAYMENTS_KEY   # rename per project

Then one call injects everything that project needs:

vault inject --project projects/my-shop --file .env

What the agent can do

The server registers as vault, so its tools appear as vault_*. All 29, with their parameters, are in TOOLS.md. The ones that matter day to day:

Finding a key

Using a key

Adding and organizing

Backups

Plus one resource, vault://catalog: every secret as metadata in a single document.

Placeholders

For anything that is not a .env, write a placeholder and let the vault fill it:

# docker-compose.yml
environment:
  STRIPE_KEY: "{{vault:stripe/acme/secret_key}}"
  SA_JSON: "{{vault:firebase/prod/service_account|base64}}"

vault_render_file { filePath: "docker-compose.yml" }

Transforms: |base64, |json, |uri.

Running commands

vault_run {
  command: "npx",
  args: ["wrangler", "secret", "put", "STRIPE_KEY"],
  secrets: [{ path: "stripe/acme/secret_key", varName: "STRIPE_KEY" }],
  stdinSecret: "stripe/acme/secret_key"
}

The child process gets the real value. Every occurrence of it — plain, base64, or URL-encoded — is stripped from the stdout and stderr you get back.

How the keys are protected

• The vault is one AES-256-GCM encrypted file at ~/.vault-mcp/vault.enc.

• The master key lives in your OS keychain: Windows Credential Manager or macOS Keychain, via @napi-rs/keyring. Nothing to type, nothing to remember, and another user account on the same machine cannot read it.

• Headless or CI: set VAULT_MASTER_PASSWORD and the key is derived from it instead.

• Access code (optional). vault set-pin sets a 4-12 digit code. It does two jobs: it unlocks the web UI, and it guards individual secrets marked --protected. Secrets added with --protected are sealed with sha256(masterKey || scrypt(pin)), so they need both the keychain and the PIN. Give the PIN to the agent when it needs one; it unlocks for 15 minutes. Five wrong tries locks it for ten. The PIN is a second gate on top of the keychain, not the primary encryption — a 4-digit PIN alone would be trivial to brute-force, which is why the master key is doing the real work.

Rules the code enforces

1. No MCP tool result contains a secret value. A test drives all 29 tools and scans every response for known plaintexts, including base64 and URL-encoded forms.

2. vault_run redacts secret values from command output.

3. Injecting into a git-tracked file, or an un-ignored file inside a repo, is refused unless you pass force. addToGitignore: true fixes it properly instead.

4. Nothing may be written inside ~/.vault-mcp itself.

5. Every read and injection is appended to ~/.vault-mcp/audit.log — paths and destinations, never values.

6. The web UI is loopback-only and needs a token generated at startup. When an access code is set, the page also asks for it before showing anything, and five wrong tries lock it for ten minutes.

7. vault_open_ui starts that server but is not given the token, so the agent cannot read the page it opened.

8. A portable backup refuses a passphrase under 10 characters, and no tool accepts a passphrase as an argument.

Backups

Everything in the vault, in one encrypted file. Two kinds, and the difference matters.

vault backup                 # portable: asks for a passphrase (10+ characters)
vault backup --local         # local snapshot, no passphrase
vault backups                # list what you have
vault restore <file>         # merge into the vault
vault restore <file> --replace   # make the vault match the backup exactly

Or use the Backup panel in vault ui, which creates the file and hands it straight to your browser's downloads so you can save it to a drive. The passphrase is typed in the page and never leaves it.

The agent can take local snapshots itself (vault_backup) and does so automatically before a restore or a delete from the UI. It cannot make a portable backup, because that needs a passphrase and a passphrase must never be typed into a conversation.

A few things worth knowing:

• It is one encrypted file, not a zip of the vault folder. A zip would reveal how many keys you have and what they are called; this reveals only a date and a count.

• Copying vault.enc on its own to another machine will not work — the master key lives in that machine's keychain. Portable backups exist precisely for this.

• The file carries a checksum, so a truncated or tampered copy is refused rather than half-restored.

• A restore always takes a safety snapshot first, so even --replace is undoable.

• Lose the passphrase and the portable backup is gone. There is no recovery path, by design.

Commands

vault init                  Create the vault and master key
vault setup                 Guided first run
vault add <path>            Add a secret or a whole service preset
vault ls [path]             List what is stored
vault info <path>           Show one secret's metadata (--preview for a mask)
vault get <path>            Print a value to stdout (for piping)
vault rm <path>             Delete (-r for a container)
vault import <file> --to    Import a .env or JSON file
vault link <project> <path> Link a shared secret into a project
vault inject --project ...  Write secrets into a local .env
vault set-pin               Set the access code (web UI + protected secrets)
vault backup [--local]      Portable backup with a passphrase, or a local snapshot
vault restore <file>        Restore a backup (--replace to mirror it exactly)
vault backups               List backups on this machine
vault export / import-bundle  Older bundle format; backup/restore supersedes it
vault ui                    Local web UI
vault ui-url / ui-stop      Link to, or stop, a UI an agent started
vault serve                 Run the MCP server (what your client launches)
vault install               Register with Cursor, Windsurf, Antigravity, Claude…
vault status / audit / presets

Where things live

Development

npm run build       # tsup -> dist/
npm test            # vitest, 83 tests
npm run typecheck

Layout:

src/core/    crypto, keychain, store, envfile, importer, template, presets, git guards, audit, backup
src/mcp/     server + tools (read, inject, run, manage, ssh, backup, open-ui)
src/cli/     commander CLI
src/ui/      loopback web UI with the access-code lock screen
test/        core, vault, backup, git-guard, and the no-leak suite

How much fits

There is no hard limit. Measured on this machine:

Thousands of keys are fine. A single value can be as large as you like within reason — a PEM private key or a Firebase service-account JSON is normal. The whole vault is held in memory while the server runs, so this is built for a person's keys, not for a company-wide store.

Known limits

• vault get prints a value by design; do not run it on a shared screen.

• The web UI can reveal values. It is local-only, token-gated and code-gated, but it is a deliberate hole in the "never show a value" rule, for the human, not for the agent.

• The audit log is append-only but not tamper-proof; anything that can read the vault file can also rewrite it.

• The "the agent never sees a value" property covers the MCP tool surface. It keeps keys out of your transcript; it is not a sandbox against an agent that also has shell access to your machine.