vaultgate

vaultgate

[CI] [CodeQL] [OpenSSF Scorecard] [License: Apache-2.0]

A self-hosted, remote MCP server that lets hosted AI agents such as Claude, Claude Cowork, Claude Code and Codex use your credentials without ever seeing them. The credentials stay in your Bitwarden (or Vaultwarden) vault. vaultgate uses them on the agent's behalf against systems you define (an HTTP API, Microsoft Graph, a SQL Server or PostgreSQL database, an SSH or WinRM host, a GitHub repository searched with Semble) under your policy, and hands back only the result. It is its own OAuth 2.1 authorization server, so the agent holds a short-lived, scoped, revocable token and nothing else.

Status: release candidate. Milestones M1 to M7 are merged: configuration, SQLite store, operator identity with TOTP, the OAuth 2.1 authorization server, the MCP tool surface, the managed bw serve backend, the audit trail, packaging and the Azure template. M8 (hardening and compatibility evidence) is in progress. The actions layer, opt-in and off by default, has landed through M14: M9 the engine, the operator pages and the http connector, M10 the Microsoft Graph credential adapter, M11 sql, M12 ssh, M13 winrm, and M14 the policy-form validation messages, the call-history and writes views and grant management from the connected-clients list. M16 adds the code connector: Semble code search over private GitHub repositories, with its sidecar (guide). An http destination may pin its certificate or trust a private certificate authority, and the oauth2 credential mode obtains tokens from any OAuth 2.0 token endpoint (guide). vaultgate's own per-call write confirmation is withdrawn: approval belongs to the agent's client. The opt-in credential relay serves bw serve's read API to programs on tagged Tailscale nodes (guide). browser is M15; see docs/PLAN.md.

Why

A credential an agent can read ends up in the transcript. Once an agent reveals a password in order to use it, the value sits in the model's context, in the chat transcript, in the client's logs and on whatever command line the agent builds, and revoking the agent does not take it back. vaultgate is built so that the agent never needs the value:

• Use, don't read. With the actions layer enabled (guide, spec 13 and 13a, ADR 0007), an agent names a target you defined and describes an operation: an HTTP request, a SQL query or statement, a command on an SSH or WinRM host, a Semble search of a GitHub repository. vaultgate fetches the credential from the vault, connects to the pinned destination, runs the operation inside your policy, scrubs every injected value from the result and returns what is left. An agent never supplies a host, a URL base, a database name or a credential; its arguments change what runs, never where or as whom.
• Writes are opt-in twice, and approved where you work. A write needs its own scope at consent and a target policy that allows it. Approving each call is the agent's client's job — Claude Code, for one, asks before it runs a tool its permissions do not allow — and the console lists every call that changed something.
• One audited door for the rare value that must be read. The vault tools return metadata. A single tool returns a secret value, one field of one item per call, behind its own scope, with every call audited.
• Nothing runs on the vaultgate host. No tool runs whatever an agent sends wherever it likes: ssh_run and winrm_run run one command on one configured host under your allowlist (a target that accepts any command needs both its own flag and the deployment's consent), and every operation executes at its target.
• The agent holds a token and nothing else. The master password and API key live only in the vaultgate process on your host, encrypted under your secret key once you connect the vault on the console's Vault page.
• Standards as written. OAuth 2.1, PKCE, RFC 9728 / 8414 / 8707 / 7591 / 7009 / 9207 and Client ID Metadata Documents, per the MCP authorization specification (2026-07-28).
• Any Bitwarden. bitwarden.com, bitwarden.eu, self-hosted Bitwarden and Vaultwarden.
• Boring to operate. One process, one SQLite file, structured logs, health probes, an audit trail. docker compose up is a complete installation.

Compared with other Bitwarden MCP servers

Hosted agents reach MCP servers over HTTPS and cannot run a process next to your vault, and the other Bitwarden MCP servers are built for exactly that local process:

"Not described" means the project's README does not document one. Dated verification notes with links, and when the official stdio server is the better choice: docs/comparison.md.

Quick start

The current version is 0.1.0-rc.26 (package.json; releases are tagged on GitHub). On a VM with Docker Engine, the Compose plugin, a DNS name pointing at it and ports 80 and 443 reachable from the internet:

git clone https://github.com/adamrowles1996/vaultgate.gitcd vaultgatecp .env.example .env

Set VAULTGATE_DOMAIN, VAULTGATE_PUBLIC_URL and VAULTGATE_VERSION in .env, then:

mkdir -p secretshead -c 32 /dev/urandom | base64 > secrets/vaultgate_secret_keytouch secrets/bw_password secrets/bw_client_secretchmod 0400 secrets/* && sudo chown 10001 secrets/*docker compose up -ddocker compose logs -f vaultgate

First run: the log prints a one-time /setup?token=… URL. Open it and create the operator account with an e-mail address, a password and a code from your authenticator (TOTP). That password is vaultgate's own operator login; it is not, and never becomes, your Bitwarden master password. Sign in, and on the Vault page connect the vault: server, API key client id and secret, and master password. vaultgate stores that connection encrypted under VAULTGATE_SECRET_KEY, so it survives restarts and upgrades. Then add https://<host>/mcp to Claude (or Claude Code, Codex, the MCP Inspector) as a remote MCP server and approve the scopes on the consent page. The bw CLI that vaultgate drives is bundled in the image and installed by install.sh; nothing else is needed on the host. Walkthrough: docs/guides/first-run.md; details and the verification of the image: docs/guides/install-docker-compose.md.

To let agents use credentials rather than read them, set VAULTGATE_ENABLE_ACTIONS=true and the switch for each connector you want, restart, and add connections (targets) on the console's Connections page: docs/guides/actions.md.

How it works

Claude / Codex ──HTTPS + Bearer──▶ vaultgate ──loopback──▶ bw serve ──▶ Bitwarden                 ▲                    │    │                 │                    │    └──pinned──▶ your API, database, SSH or WinRM host                 └── OAuth 2.1 ◀──────┘        (credential injected by vaultgate, result scrubbed)                   (consent page, operator login with TOTP)

1. An agent calls /mcp and is challenged with WWW-Authenticate.
2. It discovers the authorization server from the protected resource metadata, registers (Client ID Metadata Document, dynamic registration, or a pre-registered id) and sends you to the consent page.
3. You log in (password + TOTP) and approve the scopes: vault:read, vault:reveal, vault:generate, optionally vault:write, and the actions:* scopes of each connector the deployment enables.
4. With an actions:* scope, the agent lists the targets granted to it and calls them: http_request, sql_query, sql_execute, ssh_run, winrm_run, and code_search, code_find_related and code_read for Semble connections. vaultgate fetches the credential from the vault, performs the operation at the target and returns the scrubbed result; the credential never reaches the agent.
5. With the vault scopes, it can search items, read metadata, reveal one secret field at a time, generate passwords and, if allowed, create or update items.

Install

TLS is always terminated in front of vaultgate; every method below ends with a public https:// origin that hosted agents can reach.

Releases publish ghcr.io/adamrowles1996/vaultgate:<version> for linux/amd64 and linux/arm64, signed with Sigstore cosign and carrying an SBOM and a provenance attestation, plus vaultgate-<version>.tgz and its .sha256 for the script install.

Documentation

Development

Requires Node 26 (see .nvmrc) and mise for the pinned external linters.

mise install         # actionlint, shellcheck, shfmt, hadolint, gitleaks, editorconfig-checkernpm cinpm run dev          # runs src/main.ts directly with Node's type strippingnpm run quality      # format, every linter, types, dead code, file sizes, provenance, tests at 100%

Every check that runs in CI runs locally with npm run quality. See CONTRIBUTING.md for the rules the repository enforces and why.

Licence

Apache-2.0. See LICENSE and NOTICE.