VaultBridge

Secret management for AI coding agents. Your secrets never enter the LLM context window.

License: MIT CI

---

The Problem

• 29 million secrets were leaked on GitHub in 2025 (GitGuardian State of Secrets Sprawl), up 25% year-over-year
• AI-assisted commits leak secrets at 2x the baseline rate — autocomplete and agent workflows bypass the muscle memory that keeps developers from pasting keys into code
• 24,000+ secrets found in MCP config files — the new claude_desktop_config.json is the new .env committed to git
• Every secret in the LLM context window is sent to the AI provider's servers — even if the model never prints it, it was transmitted and processed

VaultBridge is an MCP server that gives AI agents access to your secrets without ever exposing the values. The agent sees metadata (names, services, env var mappings). The actual values flow through a side channel directly to their targets.

How It Works

┌─── Your Machine ────────────────────────────────────────────┐
│                                                              │
│   Claude Code / Cursor / Windsurf / AI Agent                 │
│       │                                                      │
│       │ MCP Protocol (tool calls)                            │
│       ▼                                                      │
│   ┌─────────────────────────────────────────────────┐        │
│   │  VaultBridge MCP Server                         │        │
│   │  ● Returns metadata only (names, IDs, mappings) │        │
│   │  ● Secret values NEVER in tool responses        │        │
│   └────────┬───────────────────────────┬────────────┘        │
│            │                           │                     │
│     MCP Tools                    Hook API (:9847)            │
│     (search, inject,             (capture, redact,           │
│      manifest, status)            check-value, redeem)       │
│            │                           │                     │
│            ▼                           ▼                     │
│   ┌─────────────────────────────────────────────────┐        │
│   │  Bitwarden CLI (bw / rbw)                       │        │
│   └────────────────────┬────────────────────────────┘        │
│                        │                                     │
│                        ▼                                     │
│   ┌─────────────────────────────────────────────────┐        │
│   │  Vaultwarden / Bitwarden Cloud (encrypted)      │        │
│   └─────────────────────────────────────────────────┘        │
│                                                              │
│   Hooks: auto-capture · redact · leak-prevent                │
└──────────────────────────────────────────────────────────────┘

Data flow: The agent calls vault_search and gets back names and IDs. When it needs a value, it calls vault_inject which writes directly to a .env file, clipboard, or template — the value never appears in the tool response. Hooks intercept secrets in shell output and file writes before they reach the LLM.

Quick Start

Prerequisites

• Runtime: Bun 1.0+ or Node.js 18+
• Vault CLI: Bitwarden CLI (bw) or rbw
• Vault backend: Vaultwarden (self-hosted) or Bitwarden cloud account

1. Install

Add to your Claude Code MCP config (~/.claude/settings.json):

{
  "mcpServers": {
    "vaultbridge": {
      "command": "bun",
      "args": ["run", "/path/to/vaultbridge-mcp-server/src/index.ts"],
      "env": {
        "BW_SESSION": "<your-bitwarden-session-key>",
        "BW_URL": "https://vault.example.com"
      }
    }
  }
}

2. Unlock your vault

# Bitwarden CLI
export BW_SESSION=$(bw unlock --raw)

# Or rbw
rbw unlock

3. Verify

Ask your agent: "Check vault status" — it will call vault_status and confirm the connection.

MCP Tools

Tool	Description	Returns Values?
vault_search	Search secrets by name, service, project, environment	Never
vault_store	Store a new secret (generated passwords only via tool)	Never
vault_inject	Inject a secret into .env, clipboard, or template file	Never
vault_resolve_env	Populate .env from .env.example using vault lookups	Never
vault_manifest	Read project secret manifest (.vault-manifest.json)	Never
vault_status	Check vault connection and lock state	N/A

Claude Code Hooks

VaultBridge ships with three hooks that form a defense-in-depth layer:

Hook	Trigger	What It Does
post-bash	PostToolUse / Bash	Scans shell output for secrets (pattern + entropy detection), auto-captures to vault, redacts from context
pre-write	PreToolUse / Write|Edit	Blocks file writes containing detected secrets; suggests vault_inject instead
session-start	SessionStart	Loads project manifest, pre-warms vault connection, registers env var mappings

Hook configuration in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "curl -s http://127.0.0.1:9847/api/check-value -d '{\"value\":\"$TOOL_OUTPUT\"}' | jq -r '.should_block'"
        }]
      }
    ]
  }
}

Configuration

Environment Variable	Default	Description
VAULTBRIDGE_TRANSPORT	stdio	Transport mode: stdio or http
VAULTBRIDGE_PORT	9847	Port for Hook API (and HTTP transport)
VAULTBRIDGE_AUTH_TOKEN	(generated)	Bearer token for HTTP endpoints
VAULTBRIDGE_BACKEND	bw	Vault CLI backend: bw or rbw
BW_SESSION	—	Bitwarden session key (required for bw)
BW_URL	—	Vaultwarden/Bitwarden server URL

See docs/configuration.md for the complete reference.

Security Model

What's protected

• Secret values never appear in MCP tool responses — the LLM cannot see them
• The Hook API runs on 127.0.0.1 only in stdio mode — no network exposure
• One-time redeem tokens expire in 10 seconds and are single-use
• Clipboard injection auto-clears after a configurable TTL (default 30s)

What's visible to the agent

• Secret metadata: names, IDs, service labels, project/environment tags, env var mappings
• Vault connection status (locked/unlocked, server URL, email)
• Injection confirmations (target type, file path — never the value)

Defense layers

1. MCP layer — Tools return metadata only; vault_inject writes to targets via side channel
2. Hook layer — post-bash scans output for secrets before the LLM sees it; pre-write blocks file writes containing secrets
3. Vault layer — All secrets encrypted at rest in Vaultwarden/Bitwarden; accessed via CLI with session authentication
4. Transport layer — HTTP mode requires Bearer token auth; stdio mode binds to localhost only

Comparison

vs Indie/Open-Source Projects

Feature	VaultBridge	AgentSecrets	agent-secrets	phantom-secrets	claude-secrets
Values never reach LLM	Yes	Yes	No (leases expose)	Yes	Partial
Auto-capture from output	Yes	No	No	No	Yes
Leak prevention (block writes)	Yes	No	No	No	No
Uses existing password manager	Yes (Bitwarden)	No (own store)	No (age files)	No (OS keychain)	No (Fernet vault)
MCP server	Yes	Yes	No	Yes	No
Claude Code hooks	Yes	No	No	No	Partial
Team/workspace support	No	Yes	No	No	No
Session leases / TTL	No	No	Yes	No	Yes

vs Enterprise Products

Feature	VaultBridge	1Password Unified	GitHub Secret Scanning	Bitwarden MCP
Auto-capture from shell output	Yes	No	No	No
Pre-LLM redaction (hooks)	Yes	No	No	No
Leak prevention on file write	Yes	No	Post-commit only	No
Metadata-only responses	Yes	No (returns values)	N/A	No (returns values)
Open source	Yes	No	Partial	Yes
Self-hostable vault	Yes	No	N/A	Yes
MCP native	Yes	No	No	Yes

VaultBridge's niche: The only tool that combines Bitwarden integration + auto-capture + pre-LLM redaction + leak prevention in one system. AgentSecrets is the closest competitor but uses its own encrypted store and takes a network proxy approach instead of hooks.

Development

# Clone
git clone https://github.com/Code-for-100k/vaultbridge.git
cd vaultbridge

# Install dependencies
bun install

# Type check
bun run typecheck

# Run in stdio mode (local dev)
bun run start

# Run in HTTP mode
bun run start:http

# Build
bun run build

See CONTRIBUTING.md for the full development guide.

Architecture

VaultBridge operates as a 4-layer system:

1. Agent Layer — Claude Code / Cursor makes MCP tool calls
2. MCP Server Layer — Processes requests, enforces metadata-only responses
3. Hook Layer — Intercepts secrets in shell output and file writes
4. Vault Layer — Bitwarden CLI talks to encrypted storage

See docs/architecture.md for detailed diagrams and data flow documentation.

License

MIT - Copyright 2026 Code-for-100k Contributors