vaultmcp

How it works

1. Sign in with GitHub and create a workspace on vaultmcp.dev.

2. Store secrets once (encrypted at rest — see Encryption). Share with teammates when needed.

3. Point your IDE at `https://vaultmcp.dev/mcp` (or your self-hosted `/mcp`).

4. Call tools like `aws__…` / `github__…`. Credentials are injected server-side — never pasted into `mcp.json`.

flowchart LR
  subgraph clients [MCP clients]
    Claude[Claude]
    VSCode[VS Code]
    Cursor[Cursor]
    Windsurf[Windsurf]
    Zed[Zed]
  end

  subgraph vaultmcp [VaultMCP]
    API[Vault · OAuth · MCP gateway]
  end

  subgraph upstreams [Upstreams]
    MCP[AWS · GitHub · other MCP]
  end

  Claude --> API
  VSCode --> API
  Cursor --> API
  Windsurf --> API
  Zed --> API
  API -->|inject secrets| MCP

Features

• Write-only vault — list APIs, MCP responses, and audit logs never return secret values
• Server-side injection — decryption only happens inside the API when calling an upstream
• Private and shared secrets — per-user or workspace-wide visibility
• GitHub OAuth or personal tokens — browser login for IDEs, or `vmcp_…` tokens in `Authorization`
• Namespaced tools — register upstreams once; call them as `provider__tool_name`
• Single public port — Docker Compose exposes port 80; API and UI stay on the internal network
• Optional CLI — inject shared workspace secrets into local `npm run dev` (and similar) without sharing `.env` files

Quick start (local)

Need: Node.js 22+, pnpm 9, Docker (Postgres + Redis), and a GitHub OAuth App.

git clone https://github.com/Axiler-Lab/vaultmcp.git
cd vaultmcp
cp .env.example .env

Fill in at least: `VAULT_MASTER_KEY`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `PUBLIC_URL`, `WEB_ORIGIN`, `DATABASE_URL`, `REDIS_URL`. Local defaults are in `.env.example`.

GitHub OAuth App

The callback must match `PUBLIC_URL`.

docker compose up -d postgres redis
pnpm install
pnpm --filter @vaultmcp/shared build
pnpm db:generate   # first time / after schema changes
pnpm db:migrate
pnpm dev:api       # :3001
pnpm dev:web       # :5173

Open http://localhost:5173 → sign in → create a workspace → add secrets → register an upstream (AWS example). Host-run AWS `uvx` upstreams need `uv` on your `PATH`.

Docker Compose

One public entrypoint on port 80. API and web are not published directly.

cp .env.example .env
# Set PUBLIC_URL, WEB_ORIGIN, GITHUB_*, VAULT_MASTER_KEY
# VITE_API_URL=          # empty = same-origin
# COOKIE_SECURE=false    # true behind HTTPS

docker compose up --build

Migrations run when the API container starts. Production notes: docs/DEPLOY.md.

Connect Cursor (or any MCP client)

Same config shape for Cursor, Claude Desktop, VS Code, Windsurf, Zed, and other MCP clients. Use OAuth (browser login) or a personal access token from the dashboard Connect tab. Never put provider secrets in client config.

OAuth (hosted)

{
  "mcpServers": {
    "vaultmcp": {
      "url": "https://vaultmcp.dev/mcp"
    }
  }
}

Personal token (`vmcp_…` from Connect)

{
  "mcpServers": {
    "vaultmcp": {
      "url": "https://vaultmcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer vmcp_…"
      }
    }
  }
}

Self-host: replace with `https://YOUR_HOST/mcp`. Local API: `http://localhost:3001/mcp`.

Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`. Other clients use their own MCP config path.

After auth: `list_workspaces` → `use_workspace` → call namespaced tools (`github__…`, `aws__…`).

Local env CLI (optional)

For shared team secrets in local apps (not MCP agents), use `@vaultmcp-axiler/cli`:

npx @vaultmcp-axiler/cli@latest login --token vmcp_… --url https://YOUR_HOST
npx @vaultmcp-axiler/cli@latest run -w your-slug -- npm run dev

Create a PAT with the Runtime env (CLI) preset (`env` scope only). MCP tokens and env tokens are not interchangeable. Prefer `run` over `env` so secrets stay in the child process.

Full guide: **docs/CLI.md**.

Encryption

Secret values are encrypted at rest with AES-256-GCM using envelope encryption:

• Each workspace has its own data encryption key (DEK)
• DEKs are wrapped by `VAULT_MASTER_KEY` (kept out of the database)
• GCM AAD binds ciphertext to the `workspaceId`, so blobs cannot be swapped across workspaces
• Decryption happens only server-side — for MCP upstream injection, or opt-in CLI export
• Secret names and other metadata are not encrypted (so the UI can list and authorize without decrypting)

Treat `VAULT_MASTER_KEY` as a root credential. Rotate provider secrets in the UI without changing IDE config.

Also: list APIs and audit logs never return plaintext values; viewers cannot invoke secret-backed tools or export runtime env.

Details: **docs/CRYPTO.md**.

Repository layout

apps/api            Gateway, OAuth, REST, upstream proxy
apps/web            Control plane UI
packages/shared     Crypto helpers + shared schemas
packages/cli        Local env injection CLI
deploy/             Reverse proxy config
docs/               Deploy, CLI, and crypto guides
examples/           Upstream walkthroughs

Why AGPL

VaultMCP is often run as a network service. AGPL-3.0-only means if you modify it and offer that service over a network, you must share the corresponding source. That keeps hosted forks honest while still allowing self-hosting and contribution.

Contributing

VaultMCP is an open-source project from Axiler Labs. We’d love help from the community — issues and pull requests are very welcome, especially around security, reliability, docs, and MCP compatibility.

Ways to help:

• Open an issue for bugs or clear feature ideas
• Send a pull request (small, focused changes are easiest to review)
• Improve docs and examples for common upstreams

By contributing, you agree your work is licensed under AGPL-3.0-only, same as the rest of the repo. Never commit secrets; use `.env.example` for variable names only.

Learn more at **vaultmcp.dev · Axiler Labs: axiler.com**.

License

Copyright © 2026 Axiler Labs.

VaultMCP is licensed under the GNU Affero General Public License v3.0 only (`AGPL-3.0-only`).