Secret Vault Server

AES-256-GCM encrypted local secret storage exposed as Claude Code MCP tools. The critical security property: secret values and the master key are captured via native OS dialogs and never pass through the LLM API.

Part of the secret-vault skill. This repo contains the standalone MCP server. The full skill (MCP server + CLI + docs) lives at wwt/ai-skills-catalog — skills/secret-vault.

Security Contract

What the LLM sees	What the LLM never sees
Secret key names (github.token)	Secret values
Tags, created date, rotated date	The vault master key
Operation results ("stored", "deleted")	Decrypted vault contents

When you ask Claude to store a secret, it calls vault_set(name="github.token"). The MCP server opens a native macOS password dialog — you type the value there. It goes directly from the dialog into the encrypted vault file, never through the LLM API.

---

Installation

1. Clone and install dependencies

git clone https://github.com/sam-ueckert/vault-mcp.git ~/repos/vault-mcp
pip3 install -r ~/repos/vault-mcp/requirements.txt

2. Register the server in ~/.claude.json

Add to the top-level mcpServers object:

{
  "mcpServers": {
    "secret-vault": {
      "type": "stdio",
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/repos/vault-mcp/server.py"]
    }
  }
}

3. Allow the tools in ~/.claude/settings.json

{
  "permissions": {
    "allow": [
      "mcp__secret-vault__vault_status",
      "mcp__secret-vault__vault_init",
      "mcp__secret-vault__vault_rekey",
      "mcp__secret-vault__vault_list",
      "mcp__secret-vault__vault_set",
      "mcp__secret-vault__vault_rotate",
      "mcp__secret-vault__vault_delete",
      "mcp__secret-vault__vault_exists",
      "mcp__secret-vault__vault_get_metadata",
      "mcp__secret-vault__vault_update_tags",
      "mcp__secret-vault__vault_import"
    ]
  }
}

4. Restart Claude Code. The server spawns as a subprocess on first tool use.

---

Prerequisites

pip3 install cryptography mcp

mcp 1.0+ is required. argon2-cffi is optional — if installed, passphrase KDF upgrades from PBKDF2 to Argon2id.

---

Installation

1. Register the server in ~/.claude.json

Open ~/.claude.json and add to the top-level mcpServers object:

{
  "mcpServers": {
    "secret-vault": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/skills/secret-vault/mcp-server/server.py"]
    }
  }
}

Replace /path/to/ with the actual path to your skills checkout, e.g.:

~/repos/claude-skills/skills/secret-vault/mcp-server/server.py

2. Allow the tools in ~/.claude/settings.json

Add to the permissions.allow array:

"mcp__secret-vault__vault_status",
"mcp__secret-vault__vault_init",
"mcp__secret-vault__vault_list",
"mcp__secret-vault__vault_set",
"mcp__secret-vault__vault_rotate",
"mcp__secret-vault__vault_delete",
"mcp__secret-vault__vault_exists",
"mcp__secret-vault__vault_get_metadata",
"mcp__secret-vault__vault_update_tags",
"mcp__secret-vault__vault_rekey",
"mcp__secret-vault__vault_import"

3. Restart Claude Code

The server spawns as a subprocess on first tool use. No daemon to start.

---

First-Run Behaviour

On macOS, the server auto-initializes the vault on first use:

1. Generates a random 256-bit key
2. Stores it in the macOS Keychain under agent-secret-vault
3. Creates ~/.agent/vault/vault.enc

From that point on, all subsequent calls are silent — the Keychain handles key resolution without prompting.

To use a passphrase instead of the Keychain:

Ask Claude: "Initialize the vault with a passphrase"

This calls vault_init(key_tier="passphrase") and prompts via native dialog.

---

Vault Storage

~/.agent/vault/
├── vault.enc       # AES-256-GCM encrypted JSON — all secrets live here
├── .vault-meta     # Key tier, salt (if passphrase), created date
└── audit.log       # Append-only log: timestamps + key names, no values

The encryption format is identical to the CLI skill — both tools read and write the same vault.enc file.

---

Tools Reference

vault_status

Check initialization state, key tier, and number of stored secrets.

Ask Claude: "What's my vault status?"

---

vault_init(key_tier, force?)

Initialize or re-initialize the vault.

key_tier	Behaviour
keychain	Random 256-bit key stored in OS Keychain (default on macOS)
passphrase	Argon2id-derived key — prompts via native dialog
env	Reads VAULT_KEY hex env var

Warning: Re-initializing creates a new empty vault, permanently destroying all stored secrets. The tool refuses if secrets exist unless force=True is passed. Use vault_rekey to rotate the master key while preserving secrets.

Ask Claude: "Initialize the vault" or "Initialize with a passphrase"

---

vault_rekey(new_key_tier)

Rotate the vault master key while preserving all stored secrets.

Decrypts with the current key, generates or derives a new key via native dialog (for passphrase), re-encrypts every secret under the new key, and updates the key tier. The new key never passes through the LLM.

new_key_tier	Behaviour
keychain	New random key stored in OS Keychain
passphrase	New passphrase collected via native dialog
env	New key read from VAULT_KEY env var

Ask Claude: "Rekey the vault" or "Rotate the vault master key to use a passphrase"

---

vault_list(tags?)

List all stored secret names, tags, and timestamps. Values are never shown.

Ask Claude: "List my secrets" or "List secrets tagged env:prod"

---

vault_set(name, tags?)

Store a new secret or overwrite an existing one.

The value is not a parameter — a native macOS password dialog opens and captures it directly. The LLM only receives the key name.

Ask Claude: "Store a secret called github.token" or "Save my AWS access key as aws.access_key_id tagged env:prod,service:aws"

---

vault_rotate(name)

Replace an existing secret's value. Same dialog-capture behaviour as vault_set. Records a rotation timestamp.

Ask Claude: "Rotate my github.token"

---

vault_delete(name)

Permanently remove a secret.

Ask Claude: "Delete the secret github.token"

---

vault_exists(name)

Check whether a key exists without retrieving its value.

Ask Claude: "Does github.token exist in the vault?"

---

vault_get_metadata(name)

Return tags, created date, and last-rotated date for a secret. No value.

Ask Claude: "Show me the metadata for aws.access_key_id"

---

vault_update_tags(name, tags)

Replace all tags on a secret without touching its value.

Ask Claude: "Tag github.token with env:prod,service:github"

---

vault_import(file_path, tags?, keep?)

Import secrets from a file on disk. Supports .env (KEY=VALUE) and JSON ({"key": "value"}) formats.

Write the secrets to a file yourself, then call this tool — values go from the file directly into the encrypted vault via the MCP server process, never through the LLM API. The file is securely overwritten with random bytes and deleted after import. Pass keep=True to preserve it.

Parameter	Default	Description
file_path	required	Absolute path to the .env or JSON file
tags	""	Comma-separated tags applied to all imported secrets
keep	False	Keep the file on disk after import

Ask Claude: "Import secrets from /tmp/staging.env" or "Import /tmp/keys.json tagged env:prod"

---

Key Naming Convention

Use dot-separated namespaces for discoverability:

service.credential_type
aws.access_key_id
aws.secret_access_key
github.pat
github.token
azure.client_secret
slack.bot_token
anthropic.api_key

---

Relationship to the CLI Skill

This MCP server and the CLI script (vault.py in wwt/ai-skills-catalog) share the same vault file (~/.agent/vault/vault.enc) and encryption format — both tools can read and write the same vault.

Use case	Tool
Asking Claude to manage secrets interactively	MCP server — values never hit LLM
Bulk import from .env or JSON file	vault_import MCP tool or CLI vault.py import
Scripting / CI pipelines	CLI vault.py get key --export
Export for GitHub Actions / GitLab CI	CLI vault.py export --format github-actions

Warning: vault.py get <key> prints the value to stdout. If captured as a Claude tool result, the secret is exposed to the LLM API. Use the MCP server for all interactive agent use.

---

Gotchas

• Keychain prompt on first use: macOS may show a Keychain authorization dialog the first time a new session accesses agent-secret-vault. Click "Always Allow" to suppress future prompts.
• Passphrase mode re-prompts every session: The master key is cached in the server process memory. When you open a new Claude Code session, the passphrase dialog appears on the first vault tool call.
• No value retrieval tool by design: There is no vault_get_value tool. This is intentional — if you need a secret injected into a command, use vault.py get key --export in a shell script outside of Claude.
• Binary secrets: Files with non-UTF-8 content (SSH keys, etc.) are stored as base64. The CLI skill handles these natively via file-based operations.
• Vault location is fixed: ~/.agent/vault/ — not configurable in this version.