# Black Vault > Open-source API key firewall for AI agents. Proxy gateway with per-token rate limits, budget caps, model restrictions, and instant kill switch. Agents never see the real key. - **Type:** MCP server - **Install:** `agentstack add mcp-venkat22022202-black-vault` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [venkat22022202](https://agentstack.voostack.com/s/venkat22022202) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [venkat22022202](https://github.com/venkat22022202) - **Source:** https://github.com/venkat22022202/black-vault - **Website:** https://black-vault-murex.vercel.app ## Install ```sh agentstack add mcp-venkat22022202-black-vault ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About BlackVault The open-source API key firewall for AI agents. Agents never see the real key. Kill access instantly. Per-token rate limits, budgets, and model restrictions. Quick Start • Universal Gateway • Features • Proxy Usage • Access Controls • Deploy • Issues • Contributing --- ## The Problem When you share an API key with an AI agent (OpenClaw, Moltbook bots, LangChain, CrewAI, or any agent framework), you can't revoke **just that agent's** access without rotating the key and breaking **every other agent** that uses it. BlackVault fixes this with a proxy layer: ``` Agent → BlackVault (bvt_ token) → OpenAI / Anthropic / Google / Nebius (real key) ↑ ↑ You control this Agent never sees this ``` **One key, many proxy tokens. Kill a token = instant 401. No rotation needed.** ## Universal AI Gateway **One endpoint. One token. Every AI provider.** BlackVault includes an OpenAI-compatible gateway at `/api/v1/chat/completions` that auto-routes to the correct provider based on the model name and translates request/response formats automatically. ```bash # Use Claude through BlackVault (auto-translates OpenAI format → Anthropic) curl https://your-blackvault.vercel.app/api/v1/chat/completions \ -H "Authorization: Bearer bvt_your_token" \ -H "Content-Type: application/json" \ -d '{"model": "claude-sonnet-4-5-20250929", "messages": [{"role": "user", "content": "hello"}], "max_tokens": 1024}' # Use GPT through the same endpoint and token curl https://your-blackvault.vercel.app/api/v1/chat/completions \ -H "Authorization: Bearer bvt_your_token" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}' # Use Gemini through the same endpoint and token curl https://your-blackvault.vercel.app/api/v1/chat/completions \ -H "Authorization: Bearer bvt_your_token" \ -H "Content-Type: application/json" \ -d '{"model": "gemini-2.0-flash", "messages": [{"role": "user", "content": "hello"}]}' ``` ### Works with ANY OpenAI-compatible tool **OpenClaw:** ```bash OPENAI_BASE_URL=https://your-blackvault.vercel.app/api/v1 OPENAI_API_KEY=bvt_your_token ``` **LangChain (Python):** ```python from langchain_openai import ChatOpenAI llm = ChatOpenAI( base_url="https://your-blackvault.vercel.app/api/v1", api_key="bvt_your_token", model="claude-sonnet-4-5-20250929" # or gpt-4o, gemini-2.0-flash, etc. ) ``` **OpenAI SDK (Python):** ```python import openai client = openai.OpenAI( base_url="https://your-blackvault.vercel.app/api/v1", api_key="bvt_your_token" ) response = client.chat.completions.create( model="claude-sonnet-4-5-20250929", # any model, any provider messages=[{"role": "user", "content": "hello"}] ) ``` **OpenAI SDK (Node.js):** ```typescript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://your-blackvault.vercel.app/api/v1", apiKey: "bvt_your_token", }); const response = await client.chat.completions.create({ model: "gemini-2.0-flash", // routes to Google automatically messages: [{ role: "user", content: "hello" }], }); ``` **Cursor / Continue / Cline:** Set the base URL to `https://your-blackvault.vercel.app/api/v1` and API key to `bvt_your_token` in your IDE settings. ### How it works | Model prefix | Routes to | Format translation | |---|---|---| | `gpt-*`, `o1*`, `o3*` | OpenAI | None (native) | | `claude-*` | Anthropic | OpenAI ↔ Anthropic Messages API | | `gemini-*` | Google AI | OpenAI ↔ Gemini API | | `deepseek-ai/*`, `meta-llama/*` | Nebius | None (OpenAI-compatible) | The gateway looks up the user's vault key for the target provider automatically. One `bvt_` token can access ALL providers the user has keys for. ## MCP Server BlackVault is also a **remote MCP server**, so any MCP client (Claude Desktop, Cursor, Claude Code, …) can get **governed** access to your vaulted AI keys. Your MCP config holds a `bvt_` token — never a provider key — and every tool call is subject to your budget caps, rate limits, model restrictions, kill switch, and audit trail. **Endpoint:** `https://your-blackvault.vercel.app/api/mcp` (JSON-RPC 2.0 over Streamable HTTP) **Config (Claude Desktop / Cursor `mcp.json`):** ```json { "mcpServers": { "blackvault": { "url": "https://your-blackvault.vercel.app/api/mcp", "headers": { "Authorization": "Bearer bvt_your_token" } } } } ``` **Tools exposed:** | Tool | What it does | |------|--------------| | `list_models` | Lists the models this token may use, across your vaulted provider keys. | | `chat` | Runs a completion on any allowed model (`gpt-*`, `claude-*`, `gemini-*`, open-source via Nebius). BlackVault injects the real key, enforces budget/rate/model limits, and audits the call. | The agent never sees a provider key, and revoking the `bvt_` token (or hitting the kill switch) blocks its next MCP call instantly. See [`docs/design/0002-mcp-credential-broker.md`](docs/design/0002-mcp-credential-broker.md) for the roadmap (generic HTTP-credential brokering and upstream-MCP proxying are next). ## Features ### Core - **Universal AI Gateway** — One OpenAI-compatible endpoint for ALL providers. Auto-routes by model name, translates formats. Works with OpenClaw, LangChain, CrewAI, Cursor, and any OpenAI-compatible tool. - **Encrypted Vault** — AES-256-GCM with per-user derived keys. Zero-knowledge at rest. - **Proxy Gateway** — Forward requests to OpenAI, Anthropic, Google AI, Nebius AI with full SSE streaming. - **Instant Kill Switch** — Revoke a session, a key, or everything. Propagates in X-BlackVault-Cost: 0.003200 X-BlackVault-Budget-Limit: 5.0000 X-BlackVault-Budget-Remaining: 4.9968 X-Session-RateLimit-RPM-Limit: 30 X-Session-RateLimit-RPM-Remaining: 28 X-BlackVault-Allowed-Models: gpt-4o-mini,gpt-3.5-turbo ``` ## Architecture ``` src/ ├── app/ │ ├── api/ │ │ ├── v1/chat/completions/ # Universal AI Gateway (OpenAI-compatible) │ │ ├── v1/models/ # Available models endpoint │ │ └── proxy/[provider]/[...path]/ # Direct proxy gateway │ ├── (dashboard)/ # Dashboard pages │ └── page.tsx # Landing page ├── server/ │ ├── db/schema.ts # Drizzle schema (Postgres) │ ├── routers/ # tRPC routers │ │ ├── vault.ts # Key CRUD + encryption │ │ ├── proxy.ts # Token generation, sessions, rate limits │ │ ├── killswitch.ts # Emergency revocation │ │ └── cost.ts # Real-time cost queries │ └── services/ │ ├── encryption.ts # AES-256-GCM encrypt/decrypt │ ├── proxy-auth.ts # Token auth + IP/budget enforcement │ ├── model-router.ts # Model → provider auto-routing │ ├── format-translator.ts # OpenAI ↔ Anthropic/Google translation │ ├── proxy-providers.ts # Provider configs │ ├── proxy-pricing.ts # Token cost estimation │ ├── ratelimit.ts # Global + per-session rate limiting │ └── redis.ts # Upstash Redis cache └── lib/ ├── constants.ts # Provider configs, activity types └── utils.ts # Shared utilities ``` ## Tech Stack | Layer | Technology | |-------|------------| | Framework | Next.js 16 + React 19 + TypeScript | | API | tRPC 11 | | Database | Neon Postgres + Drizzle ORM | | Cache & Rate Limiting | Upstash Redis | | Auth | Clerk | | Styling | Tailwind CSS v4 + Framer Motion | | Encryption | AES-256-GCM (Node.js crypto) | | Charts | Recharts | ## Security - API keys encrypted at rest with AES-256-GCM using per-user derived keys (HMAC-SHA256) - Proxy tokens SHA-256 hashed before storage -- plaintext never persisted - Session lookups Redis-cached (60s TTL) for fast revocation - **Three-tier rate limiting:** global (200 RPM/user) + per-session RPM + per-session RPD via Redis sliding window - **Budget enforcement:** session-level spend caps block at 402 when exhausted - **Model restrictions:** per-session model allowlists prevent unauthorized model usage - **IP allowlisting:** per-session IP restrictions enforced at auth time - CORS allows `*` on proxy (tokens are the auth boundary, not origin) - All secrets are environment variables -- never in code ## Deploy ### Vercel (recommended) 1. Fork this repo 2. Import in [Vercel](https://vercel.com) 3. Add environment variables from `.env.example` 4. Deploy ### Self-hosted ```bash npm run build npm start ``` ## Roadmap - [x] **Universal AI Gateway** -- OpenAI-compatible endpoint, auto-routes to any provider - [x] **Per-Session Rate Limiting** -- Configurable RPM/RPD per proxy token - [x] **Budget Caps & Model Restrictions** -- Per-token spend limits and model whitelists - [x] **MCP Server** -- Remote MCP server (`/api/mcp`) exposing governed `list_models` + `chat` tools to Claude Desktop, Cursor, Claude Code, etc. - [ ] **OpenClaw Skill** -- Official skill for the OpenClaw AI assistant - [ ] **Groq, Mistral, Together AI** -- More provider support - [ ] **Webhook alerts** -- Notify when budget thresholds hit or rate limits trigger - [ ] **Token scoping** -- Per-token endpoint restrictions - [ ] **Usage analytics dashboard** -- Graphs of cost, latency, and token usage over time - [ ] **Team workspaces** -- Shared vaults with role-based access ## Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Good first issues:** Check the [`good first issue`](https://github.com/venkat22022202/black-vault/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label. ## Contributors ## Star History If BlackVault is useful to you, consider giving it a star. It helps others discover the project. [](https://star-history.com/#venkat22022202/black-vault&Date) ## License [MIT](LICENSE) ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [venkat22022202](https://github.com/venkat22022202) - **Source:** [venkat22022202/black-vault](https://github.com/venkat22022202/black-vault) - **License:** MIT - **Homepage:** https://black-vault-murex.vercel.app Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-venkat22022202-black-vault - Seller: https://agentstack.voostack.com/s/venkat22022202 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.