mcpvault
Install
← back to mcpvault
Docs menu+

Add, switch, rename, rotate tokens, remove. Multi-account workflows.

#Account management

mcpvault is built around the idea that you have many accounts per service. This page covers everything you can do with them: add, switch, rename, rotate the token, remove.

#Add

bash
mcpvault add <service>

Walks you through:

  1. 1Label — short, alphanumeric + dashes. work, personal, acme-prod, merel-staging.
  2. 2Description — what fuzzy search matches. Be specific: "Acme Corp prod, us-east-1" beats "production".
  3. 3Token — pasted, hidden input. Validated live against the upstream API before save.
  4. 4Optional defaults — e.g. default project ref for Supabase, team ID for Vercel.

You can run this as many times as you want per service.

#List

bash
mcpvault list                # everything
mcpvault list supabase       # one service
mcpvault list --json         # machine-readable

Output groups accounts by service, with the active label marked:

text
supabase
  ● work        Day job, prod + staging
  ○ personal    My side projects
  ○ client-x    Freelance client (us-east-1)

github
  ● personal    My personal repos
  ○ work        Org-scoped fine-grained PAT

#Switch the active account

From the CLI:

bash
mcpvault use <service> <label>

From inside a chat client (the natural way):

Switch to my work Supabase.

The agent calls mcpvault_find_account → mcpvault_activate_account. Each per-service wrapper re-reads ~/.mcpvault/active.json on every tool call, so the switch takes effect on the next tool invocation. No client restart, no MCP reconnect.

#Rename a label

bash
mcpvault rename <service> <old-label> <new-label>

Updates the vault and active.json atomically. The audit log keeps the old name for past entries (renames are not a rewrite).

#Update the description

bash
mcpvault describe <service> <label> "Acme Corp prod (us-east-1)"

If you keep getting the wrong account selected by fuzzy search, this is the lever to pull.

#Rotate the token

Replace the credential without deleting the account or losing its label, description and defaults:

bash
mcpvault rotate <service> <label>

Prompts for the new token. Validates against the upstream API. On success, the new token replaces the old one in-place. The audit log records account-rotated. The OS keyring cache is unaffected (the vault key didn't change — only the credential inside it did).

Use this when:

  • The upstream service rotated your PAT (some providers force a 90-day rotation).
  • You suspect the token leaked.
  • You upgraded a fine-grained PAT to a broader scope.

If validation fails, the old token stays in place — never a half-rotated state.

#Remove an account

bash
mcpvault remove <service> <label>

Asks for confirmation. If the account being removed was the active one, you're prompted to pick a replacement (or set active = none).

#Multi-account workflows

A common pattern for a freelance dev:

bash
# personal stuff
mcpvault add supabase    # label: personal,    desc: my side projects
mcpvault add github      # label: personal,    desc: my personal repos
mcpvault add vercel      # label: personal,    desc: side project deploys

# day job
mcpvault add supabase    # label: work,        desc: day job, prod + staging
mcpvault add github      # label: work,        desc: company GitHub org

# clients
mcpvault add supabase    # label: client-acme, desc: Acme Corp production
mcpvault add github      # label: client-acme, desc: Acme repos (read-only PAT)

Then in chat:

I'm working on Acme today. Switch all my accounts to client-acme and list the open PRs.

The agent activates client-acme for both Supabase and GitHub, then calls github_list_pulls.

#Tags (optional)

When adding an account you can set tags. They're not used by fuzzy search but are searchable from the CLI:

bash
mcpvault add supabase    # tags: client, prod
mcpvault list --tag client

#Pinning a wrapper to one account

Normally a wrapper follows the active label. To make a wrapper always use a specific account regardless of active.json, pass --account in your client's MCP config:

json
{
  "mcpServers": {
    "stripe-readonly": {
      "command": "mcpvault",
      "args": ["wrap", "stripe", "--account", "live-readonly"]
    }
  }
}

Useful if you want a single account to be unaffected by chat-driven switching.

Accounts — mcpvault docs