API and MCP

Version 0.11

Give a script, a CI pipeline or an AI assistant access to one project. Items stay end-to-end encrypted: the API key itself decrypts them on your machine, and our server never sees the plaintext.

API keys

A project manager creates keys on the project page in the web vault (section API keys). Each key:

A key looks like bwv_<id>.<secret>. Store it like a password, for example as a CI secret or an environment variable.

MCP server (Claude, Cursor and other AI assistants)

The MCP server runs on your computer, so items are decrypted locally. It is one file with no dependencies and needs Node.js 20 or newer.

  1. Download vault-mcp.mjs.
  2. Create an API key for the project. Use Can view unless the assistant should change things.
  3. Add it to your assistant.

Claude Code:

claude mcp add brahmweb-vault --env VAULT_API_KEY=bwv_... -- node /path/to/vault-mcp.mjs

Claude Desktop, Cursor, Windsurf (the mcpServers section of the config file):

{
  "mcpServers": {
    "brahmweb-vault": {
      "command": "node",
      "args": ["/path/to/vault-mcp.mjs"],
      "env": { "VAULT_API_KEY": "bwv_..." }
    }
  }
}

Self-hosted server? Also set VAULT_SERVER to its address.

ToolWhat it doesKey needs
vault_infoProject, permission and expiry of the keyview
list_itemsNames, websites, usernames and variable names (no secrets)view
get_itemOne item with its password or variablesview
get_env_fileEnvironment variables as .env textview
generate_passwordA strong random passwordview
list_membersPeople in the project, permission, expiryview
save_loginCreate or update a loginedit
save_envCreate or update environment variables (replace or merge)edit
delete_itemDelete an item for everyone in the projectedit
share_projectAdd a person or change their permission and expirymanage
remove_memberRemove a personmanage
project_activityRecent audit logmanage

Authentication

Base URL: https://vault.brahmweb.com. All requests and responses are JSON. The secret part of the key is never sent. Your client derives two values from it with HKDF-SHA256 (32 zero bytes as salt):

The secret in the key is base64url. Optionally send X-Vault-Client: mcp to label your calls as MCP in the activity log.

Encryption format

Endpoints

CallBodyReturnsKey needs
GET /api/v1/key{ id, name, role, projectId, projectName, orgName, wrappedKey, expiresAt }view
GET /api/items[{ id, data, projectId, role, updatedAt, lastUsedAt, lastUsedBy }]view
POST /api/items/activity{ id }Usage log of one itemview
POST /api/projects/members{ projectId }[{ email, name, role, expiresAt, active, publicKey }]view
PUT /api/items{ id?, data, label? }{ id } (no id creates)edit
DELETE /api/items{ id, label? }{}edit
POST /api/projects/add{ projectId, email, role, expiresAt }{}. expiresAt is ms since 1970 or nullmanage
POST /api/projects/remove{ projectId, email }{}manage
GET /api/keys/pending{ projects: [{ projectId, email, publicKey }] }manage
POST /api/keys/complete{ projects: [{ projectId, email, wrappedKey }] }{ done }manage
POST /api/projects/activity{ projectId }Project audit logmanage

After projects/add, people who already have a confirmed account appear in keys/pending. Wrap P with their public key and send it to keys/complete to start their access. New people get an email invite first.

Rate limits and errors

Security