Vault MCP
Enables LLM agents to securely use credentials like passwords and API keys without exposing them in the context window, through encrypted storage and proxy-based injection.
README
Vault MCP
MCP server for credential isolation in LLM agents. Your bot uses passwords and API keys — but never sees them in its context window.
The Problem
User LLM Website
│ │ │
│ "password: MyP@ss!" │ │
├───────────────────────►│ │
│ │──── MyP@ss! ──────────►│
│ │ │
│ │◄──── 200 OK ───────────│
│ │ │
▼ ▼ ▼
┌──────────────┐
│ MyP@ss! is │
│ now stored │
│ in LLM │
│ context, │
│ conversation │
│ history, │
│ session logs │
└──────────────┘
The Solution
User Browser Form Vault MCP LLM Website
│ (localhost) │ │ │
│ ●●●●●●●● │ │ │ │
├──────────────►│ │ │ │
│ │── encrypt ─────►│ │ │
│ │ │◄── vault_login ─┤ │
│ │ │── fill form ───────────────────►│
│ │ │◄──── 200 OK ───────────────────┤
│ │ │── { status: ok }─►│ │
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐
│ Password: │ │ LLM context: │
│ AES-256-GCM │ │ │
│ encrypted │ │ "status: ok" │
│ on disk │ │ (no password)│
└──────────────┘ └──────────────┘
Scenarios
Scenario 1: First-time Login (vault_add → vault_login)
The agent needs credentials it doesn't have. It calls vault_add() — a browser form opens where you enter the password. Then vault_login() fills the form via Chrome.
User Claude Code Vault MCP Chrome
│ │ │ │
│ "Log me into │ │ │
│ Jira" │ │ │
├───────────────────►│ │ │
│ │── vault_list() ────►│ │
│ │◄─ { credentials:[] }┤ │
│ │ │ │
│ │── vault_add ───────►│ │
│ │ { site: "jira" } │ │
│ │ │ │
│ ┌────────────────────────────┐ │ │
│ │ Browser opens │ │ │
│ │ localhost:9900/add │ │ │
│ │ │ │ │
│ │ Site ID: [jira] │ │ │
│ │ Email: [me@work.com] │ │ │
│ │ Password: [●●●●●●●●●●] │ │ │
│ │ URL: [jira.com/login]│ │ │
│ │ │ │ │
│ │ [Add to Vault] │ │ │
│ └────────────┬───────────────┘ │ │
│ │ │ │
│ └── POST (encrypted) ────►│ │
│ │ │
│ │◄─ { status: ok } ───┤ │
│ │ site_id: "jira" │ │
│ │ │ │
│ │ (no password │ │
│ │ in this response) │ │
│ │ │ │
│ │── vault_login ─────►│ │
│ │ { site: "jira" } │── decrypt ──┐ │
│ │ │◄────────────┘ │
│ │ │── fill email ────►│
│ │ │── fill pass ────►│
│ │ │── click submit ──►│
│ │ │◄─ page loaded ───┤
│ │ │── clear pass ────►│
│ │ │ │
│ │◄─ { status: ok, ───┤ │
│ │ title: "Jira │ │
│ │ Dashboard" } │ │
│ │ │ │
│◄── "You're logged │ │ │
│ into Jira!" │ │ │
Scenario 2: API Key Proxy (vault_api_request)
The agent makes an API call. Vault injects the API key into headers — the key never appears in the LLM context.
Claude Code Vault MCP Stripe API
│ │ │
│── vault_api_request ►│ │
│ service: "stripe" │ │
│ url: "/v1/charges" │ │
│ method: "GET" │ │
│ │── decrypt API key │
│ │ │
│ │── GET /v1/charges ────────►│
│ │ Authorization: │
│ │ Bearer sk-live-**** │
│ │ │
│ │◄── { data: [...] } ───────┤
│ │ │
│ │── scan response │
│ │ for leaked key │
│ │ (replace with ***) │
│ │ │
│◄── { status: ok, ───┤ │
│ body: "..." } │ │
│ │ │
│ (API key NOT in │ │
│ this response) │ │
Scenario 3: Returning User (credentials already stored)
If credentials already exist, the agent skips vault_add and goes straight to vault_login:
User Claude Code Vault MCP Chrome
│ │ │ │
│ "Open GitHub" │ │ │
├───────────────────►│ │ │
│ │── vault_list() ────►│ │
│ │◄─ [{ siteId: ─┤ │
│ │ "github", │ │
│ │ active: true }] │ │
│ │ │ │
│ │── vault_login ─────►│ │
│ │ { site: "github" }│── decrypt ───┐ │
│ │ │◄─────────────┘ │
│ │ │── CDP login ─────►│
│ │ │◄─ success ───────┤
│ │◄─ { status: ok } ───┤ │
│ │ │ │
│◄── "Done!" │ │ │
Scenario 4: Credential Revocation
Remove access instantly — the agent can no longer use the credential:
Admin (CLI) Vault MCP Claude Code
│ │ │
│── vault-mcp remove │ │
│ "jira" │ │
│ │── delete from store │
│ │── audit: removed │
│◄── "Removed: jira" │ │
│ │ │
│ │ ... later ... │
│ │ │
│ │◄── vault_login ──────┤
│ │ { site: "jira" } │
│ │ │
│ │── { status: FAIL, ──►│
│ │ "Credential not │
│ │ found: jira" } │
│ │ │
Scenario 5: Audit Trail
Every credential use is logged with a tamper-proof hash chain:
~/.vault-mcp/audit.jsonl
┌─────────────────────────────────────────────────────────────┐
│ evt_001 │ credential.created │ jira │ success │ hash_1 │
│ │ │ │ │ │ │
│ evt_002 │ credential.used │ jira │ success │ │ │
│ │ bot: claude │ │ │ ▼ │
│ │ │ │ prevHash: hash_1 │
│ │ │ │ │ hash_2 │
│ │ │ │ │ │ │
│ evt_003 │ credential.used │ jira │ success │ ▼ │
│ │ bot: claude │ │ prevHash: hash_2 │
│ │ │ │ │ hash_3 │
│ │ │ │ │ │ │
│ evt_004 │ credential.removed │ jira │ success │ ▼ │
│ │ │ │ prevHash: hash_3 │
└─────────────────────────────────────────────────────────────┘
Modify any entry → hash chain breaks → tamper detected
$ vault-mcp audit
Chain integrity: VALID (4 entries)
Quickstart
# 1. Clone and build
git clone https://github.com/Chill-AI-Space/vault-mcp.git
cd vault-mcp
npm install
npm run build
# 2. Register with Claude Code
claude mcp add -s user vault -- node ~/path/to/vault-mcp/dist/index.js
# 3. Use in Claude Code
# "Log me into GitHub" →
# Claude calls vault_add("github") → browser form opens → you enter password
# Claude calls vault_login("github") → Chrome logs in via CDP
# Claude sees only { status: "success" }
Or add credentials via CLI (outside of Claude Code):
vault-mcp add --site github --email you@example.com --url https://github.com/login
# Password is prompted interactively (masked with *)
MCP Tools
| Tool | What it does | What the LLM sees |
|---|---|---|
vault_add(site_id?) |
Opens browser form for secure credential entry | { status, site_id } |
vault_login(site_id) |
Logs into website via Chrome CDP | { status, page_title } |
vault_api_request(service, url, ...) |
Makes API call with injected credentials | { status, body } |
vault_list() |
Lists stored credentials | [{ siteId, type, active }] |
vault_status(site_id) |
Shows credential metadata + audit stats | { siteId, active, lastUsed } |
What the LLM never sees: passwords, API keys, emails, tokens, encrypted data.
CLI Commands
vault-mcp add # Interactive: add credential (password masked)
vault-mcp add --site X --email Y # Semi-interactive
vault-mcp list # List credentials (no secrets)
vault-mcp remove <site_id> # Remove credential
vault-mcp audit [site_id] # View audit log + chain integrity
vault-mcp dashboard # Web UI on localhost:9900
vault-mcp serve # Start MCP server (for debugging)
Architecture
vault-mcp/
├── src/
│ ├── index.ts ── Entry: CLI or MCP mode (auto-detect)
│ ├── server.ts ── MCP server, 5 tools registered
│ ├── cli.ts ── CLI commands (commander + inquirer)
│ ├── tools/
│ │ ├── vault-add.ts ── Opens browser form, waits for submit
│ │ ├── vault-login.ts ── Decrypt → CDP → fill form → status
│ │ ├── vault-api.ts ── Decrypt → inject headers → fetch → sanitize
│ │ ├── vault-list.ts ── Return metadata only
│ │ └── vault-status.ts ── Metadata + audit stats
│ ├── store/
│ │ ├── encrypted-store.ts ── AES-256-GCM CRUD, JSON file backend
│ │ └── keychain.ts ── Master key: env var or auto-generate
│ ├── browser/
│ │ └── cdp-bridge.ts ── Playwright connectOverCDP, form fill
│ ├── audit/
│ │ └── logger.ts ── Append-only JSONL, SHA-256 hash chain
│ └── dashboard/
│ ├── server.ts ── HTTP server (127.0.0.1:9900 only)
│ ├── index.html ── Full dashboard (CRUD + audit viewer)
│ └── add.html ── Focused add-credential form (for vault_add)
└── test/ ── 29 tests including credential sanitization
Configuration
| Env Variable | Default | Description |
|---|---|---|
VAULT_MASTER_KEY |
(auto-generated) | Encryption key. Without it, a random key is saved to ~/.vault-mcp/.master-key |
VAULT_CDP_URL |
http://localhost:9222 |
Chrome DevTools Protocol endpoint |
# Register with env vars
claude mcp add -s user vault \
-e VAULT_MASTER_KEY=my-secret-key \
-e VAULT_CDP_URL=ws://localhost:9222 \
-- node ~/path/to/vault-mcp/dist/index.js
Storage
~/.vault-mcp/
├── credentials.json ── Encrypted credentials (AES-256-GCM, unique IV per entry)
├── audit.jsonl ── Append-only log with SHA-256 hash chain
└── .master-key ── Auto-generated master key (mode 0600)
Security
See SECURITY.md for full threat model.
Protects against Does NOT protect against
───────────────── ────────────────────────
✓ LLM context leakage ✗ User typing password in chat
✓ Plaintext credential storage ✗ Compromised host (root access)
✓ Audit log tampering ✗ Malicious MCP client
✓ Accidental exposure in logs ✗ Browser-level memory attacks
Testing
npm test # 29 tests
npm run test:watch # Watch mode
Tests verify: encryption round-trip, wrong-key rejection, credential sanitization in all tool responses, hash chain integrity, tamper detection, full lifecycle flows.
License
MIT
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.