mcpvault
Install
← back to mcpvault
Docs menu+

Common errors and their fixes, ordered by frequency.

#Troubleshooting

Common issues, in order of how often they hit people.

#"command not found: mcpvault"

The npm global bin directory isn't on your PATH.

macOS / Linux: run npm config get prefix. Add <prefix>/bin to your PATH in ~/.zshrc or ~/.bashrc:

bash
export PATH="$(npm config get prefix)/bin:$PATH"

Windows (PowerShell): run npm config get prefix. Add that path (no /bin suffix on Windows) to your user PATH:

powershell
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$(npm config get prefix)", "User")

Then open a fresh terminal.

#Vault prompts for password every command

The OS keyring isn't accessible. mcpvault falls back to a single-session prompt.

macOS: should "just work". If it doesn't, check that the binary is signed (codesign -dv $(which mcpvault)). Unsigned npm-installed binaries can't write to Keychain on some macOS versions; reinstall via npm install -g @elraian/mcpvault --force.

Linux: install libsecret and either gnome-keyring or kwallet. On headless servers, set MCPVAULT_KEYRING=none to skip the cache and re-prompt every time on purpose.

Windows: should "just work" via DPAPI. If it doesn't, you're likely on a domain-joined account with restrictive policy; ask IT or use MCPVAULT_KEYRING=none.

#Client doesn't see mcpvault tools after mcpvault setup

The client wasn't fully restarted, or it's looking in a different config file than mcpvault wrote to.

  1. 1Quit the client completely — Cmd+Q on macOS, "Quit" from the tray icon on Windows. "Reload window" is not enough for most clients.
  2. 2Run mcpvault doctor --client <name> to confirm the file mcpvault wrote is the one your client reads.
  3. 3Check the client's MCP / "tools" panel for the actual error — most clients log "failed to spawn mcpvault" if the binary isn't on PATH.

If you're on Windows and the client is launched from a GUI shortcut, the client may not inherit the PATH from your shell. Reboot once after install, or reference mcpvault by absolute path in the config ("command": "C:\\Users\\you\\AppData\\Roaming\\npm\\mcpvault.cmd").

#"wrong token format" when adding an account

mcpvault validates tokens live against the upstream API. Common causes:

  • Supabase: must be a Personal Access Token (sbp_...), NOT the project's anon or service-role key.
  • GitHub: fine-grained PATs (github_pat_...) and classic tokens (ghp_...) both work, but the token must have repo and read:org scopes at minimum.
  • Vercel: any token works, but if you select the wrong team scope, lookups will be empty.
  • Stripe: must be a Restricted Key (rk_live_... or rk_test_...). Secret keys (sk_...) are rejected by the wrapper.

See Services for the exact token URL and scopes per provider.

#"permission denied" on ~/.mcpvault (Linux / WSL)

The directory was created by sudo at some point. Reclaim ownership:

bash
sudo chown -R "$USER:$USER" ~/.mcpvault
chmod 700 ~/.mcpvault
chmod 600 ~/.mcpvault/vault.enc

Never run mcpvault with sudo. The vault belongs to your user, not root.

#Vault locked after reboot

By design, the OS keyring sometimes evicts the cached key — for example, after a Windows feature update or a macOS keychain reset. Run mcpvault unlock to re-prompt for the master password and re-cache the key.

If this happens every boot, your OS isn't persisting keyring entries across sessions. On Linux, ensure gnome-keyring-daemon is autostarted. On macOS, check that you're logging into the same account that created the entry.

#Tools work, but agent picks the wrong account

Two causes:

  1. 1Active label isn't what you think. Run mcpvault active to see what's currently selected per service.
  2. 2Description is too generic. Fuzzy search matches against the description field. If three accounts have description "production", the agent will guess. Make descriptions specific: "Acme Corp prod (us-east-1)" beats "production".

#Resetting everything

Delete the vault and start over (you will lose all stored credentials):

bash
mcpvault lock
rm -rf ~/.mcpvault
mcpvault init

The OS keyring entry is named mcpvault.session; remove it manually if you want a truly clean slate.

#Still stuck

Open an issue with the output of mcpvault doctor --verbose: github.com/Elraian/mcpvault/issues.

Troubleshooting — mcpvault docs