🔐 Credential Vault MCP

Secure credential storage for AI agents. Keep your passwords, API keys, and secrets encrypted and invisible to AI models. When agents need credentials, they get a secure reference—never the actual value.

Why Credential Vault?

AI agents are incredibly powerful, but they shouldn't have access to your sensitive credentials. Credential Vault solves this with a security-first architecture:

• 🔒 End-to-End Encryption: ChaCha20-Poly1305 encryption with Argon2i key derivation
• 👻 Agent-Invisible: Agents see only credential IDs, never actual values
• 🛡️ Zero Trust: Credentials stored separately from AI context
• 📊 Full Audit Trail: Track every credential access and modification
• 🔄 Conflict Detection: Automatically detect credential changes and duplicates
• 🎯 Easy Setup: One-command initialization, MCP integration ready

Security Architecture

┌─────────────────────────────────────────┐
│  AI Agent / Claude                       │
│  (Cannot see credential values)          │
└────────────┬────────────────────────────┘
             │
             │ Requests: "Get stripe_api_key"
             │ Receives: {credential_id: "cred_xxx", name: "stripe_api_key"}
             │
┌────────────▼────────────────────────────┐
│  MCP Tool Interface                      │
│  • store_credential                      │
│  • get_credential_reference              │
│  • list_credentials                      │
└────────────┬────────────────────────────┘
             │
┌────────────▼────────────────────────────┐
│  Credential Storage (Encrypted)          │
│  ~/.credential-vault-mcp/vault.json      │
│                                          │
│  ChaCha20-Poly1305 Encryption           │
│  Argon2i Key Derivation                 │
│  600 File Permissions (User Only)       │
└──────────────────────────────────────────┘

Quick Start

1. Installation

npm install -g credential-vault-mcp

2. Initialize Vault

credential-vault init

You'll be prompted to set a master password. This password:

• Never leaves your machine
• Is never sent to any server
• Is used to derive an encryption key (not stored directly)
• Must be at least 8 characters

3. Add Your First Credential

credential-vault add stripe_api_key --type api_key

4. Configure MCP in Claude Code / Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "credential-vault": {
      "command": "credential-vault-mcp",
      "args": []
    }
  }
}

Or for development:

{
  "mcpServers": {
    "credential-vault": {
      "command": "npx",
      "args": ["credential-vault-mcp"]
    }
  }
}

5. Use in Claude

Tell Claude:

I have credentials stored in Credential Vault MCP. Can you initialize the vault with my master password, then retrieve my stripe_api_key?

Claude will:

1. Call initialize_vault tool with your master password
2. Call get_credential_reference to get credential ID
3. Never see the actual API key value

CLI Commands

List all credentials

credential-vault list

Get a credential value

credential-vault get stripe_api_key

Delete a credential

credential-vault delete stripe_api_key

View audit log

credential-vault audit 100

Verify vault integrity

credential-vault verify

Available MCP Tools

initialize_vault

Initialize the vault with master password. Call this first.

{
  "master_password": "your-secure-password-8+chars"
}

store_credential

Store a new credential (encrypted).

{
  "name": "stripe_api_key",
  "value": "sk_live_...",
  "type": "api_key"
}

Types: api_key, password, token, connection_string, ssh_key, custom

get_credential_reference

Get a credential reference (safe for agents).

{
  "credential_name": "stripe_api_key"
}

Returns: { credential_id: "cred_xxx", name: "...", type: "..." }

list_credentials

List all stored credentials (no values).

delete_credential

Permanently delete a credential.

get_audit_log

View access and modification history.

Security Best Practices

✅ DO

• ✅ Use a strong, unique master password (20+ characters recommended)
• ✅ Store your master password in a password manager
• ✅ Review audit logs regularly
• ✅ Rotate sensitive credentials periodically
• ✅ Run credential-vault verify to check vault integrity
• ✅ Keep your system and dependencies updated

❌ DON'T

• ❌ Share your master password
• ❌ Store master password in plaintext
• ❌ Use the same master password as other services
• ❌ Store credentials in public/shared environments without encryption
• ❌ Ignore audit log warnings about conflicts
• ❌ Commit .credential-vault-mcp/ to version control

File Structure

~/.credential-vault-mcp/
├── vault.json           # Encrypted credential storage (mode: 600)
└── [secure directory]   # Stored in user home, readable only by user

Permissions: Vault directory and file are created with 0700 / 0600 permissions (user read/write only).

Encryption Details

• Algorithm: ChaCha20-Poly1305 (AEAD)
• Key Derivation: Argon2i (OPSLIMIT_MODERATE, MEMLIMIT_MODERATE)
• Nonce: Random 24-byte nonce per credential
• Integrity: Poly1305 MAC prevents tampering
• Library: libsodium.js (audited crypto library)

Each credential is encrypted independently with a random nonce. Even if one credential is compromised, others remain secure.

Advanced Usage

Using with different Claude interfaces

Claude.ai Code

Add to MCP settings in Code interface

Claude Desktop App

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "credential-vault": {
      "command": "npx",
      "args": ["credential-vault-mcp"]
    }
  }
}

VS Code Extension

Configure in extension settings for Claude extension

Backing up credentials

Important: Your master password is required to decrypt credentials.

# Backup encrypted vault (safe - encrypted)
cp ~/.credential-vault-mcp/vault.json ~/backup/vault.json.backup

# Never do this:
# ❌ cp ~/.credential-vault-mcp/vault.json /public/location
# ❌ git add vault.json

Handling master password changes

Currently: Delete old vault and create new one

rm ~/.credential-vault-mcp/vault.json
credential-vault init

Then re-add credentials with new master password.

Troubleshooting

"Vault not initialized" error

# Initialize first
credential-vault init

"Permission denied" error

Check file permissions:

ls -la ~/.credential-vault-mcp/vault.json
# Should show: -rw------- (600)

Fix permissions:

chmod 600 ~/.credential-vault-mcp/vault.json

Forgotten master password?

Unfortunately, there's no recovery. The password is required to decrypt credentials.

Prevention: Store master password in a password manager with recovery codes.

"Conflict detected" warning

This means a credential with the same value exists under a different name. This could indicate:

• Password reuse (audit the old credential)
• Accidental duplicate entry
• Shared secret across services

Check audit log:

credential-vault audit

Development

Clone & Install

git clone https://github.com/CipherSatoru/credential-vault-mcp.git
cd credential-vault-mcp
npm install

Build

npm run build

Run in development

npm run dev

Test CLI

npm run cli -- init

Contributing

Contributions welcome! This is security-sensitive software, so:

1. Security first: Test all encryption paths
2. No plaintext logging: Credentials must never be logged
3. Audit trail: Track what happens
4. Documentation: Update SECURITY.md for significant changes

License

MIT License - See LICENSE file for details

Support

• 📖 Read SECURITY.md for security details
• 🐛 Report issues
• 💬 Discussions

Disclaimer

This tool encrypts credentials locally on your machine. However:

• The MCP interface is only as secure as its integration
• Running on a compromised machine still exposes credentials
• Master password security is your responsibility
• No encryption is perfect - use defense in depth

Always follow your organization's security policies when handling credentials.

---

Made with 🔒 for secure AI agent workflows