mcp-warden
A local-first credential broker for the Model Context Protocol — lets any AI coding agent (Claude Code, Cursor, Cline, Codex, Continue, Zed) take real actions without ever seeing your secrets.
The agent calls high-level tools (proxy_http); mcp-warden injects the secret server-side, executes the action, and returns only the result. Your context window stays clean. A leaked transcript leaks nothing useful.
[ci]
[crates.io]
[License: Apache-2.0]
[mcp-warden demo: the agent calls the GitHub API through a preset without seeing the token, a prompt-injected DELETE is refused before any request is sent and lands in the audit log as refused, an SSH deploy runs after approval in Telegram, and mcp-warden scan finds a plaintext key in ~/.claude.json that import moves into the keychain]
How it works
- You store a credential once in the OS keychain via the
mcp-warden CLI.
- You define presets — named, scoped actions (e.g.
github-read, stripe-charges).
- The AI agent connects to
mcp-warden as an MCP server (stdio).
- When the agent wants to act, it calls
proxy_http with a preset name and a path/method.
mcp-warden validates the request against the preset's allow-list, injects the credential, executes, and returns only the response.- Sensitive presets trigger an approval prompt: a native dialog on macOS and Windows, a desktop notification with Approve / Deny on Linux, or a Telegram message on any OS — where
/lock also works as a kill switch from your phone. Opt in to time-boxed approvals per preset so one OK can cover a short burst of follow-up calls without re-prompt spam.
- Every action lands in a local SQLite audit log, hash-chained and anchored in the keychain so an edit shows (
mcp-warden audit verify) — including a windowed decision for calls authorised by an active approval window, a refused decision (with the raw requested path or command) for calls the allow-list turned away, and a failed decision when the approval prompt could not be shown.
The agent's context window contains zero secrets.
Install
Every option installs the same single binary — no background service, no auto-updater, no telemetry. To update, run the same tool again.
macOS and Linux — Homebrew
Windows — Scoop
A winget package (ermoluk.mcp-warden) and an AUR package (mcp-warden-bin) are coming but not listed yet. Until they are, use Scoop on Windows, and Homebrew or the install script below on Arch Linux; on Linux the script installs the static musl build.
Nix (builds from source)
npm — for MCP clients configured with npx. The package is scoped: the unscoped mcp-warden on npm is an unrelated project.
The binary for your platform comes from an optional dependency; nothing is downloaded at install or run time. npx @mcp-warden/cli init and the other subcommands work the same way.
Rust — prebuilt with cargo-binstall, or from source (Rust 1.94.1+):
Install script — downloads the release archive for your machine, refuses it unless it matches the release's SHA256SUMS, and puts the binary in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\mcp-warden\bin). No sudo, and it changes neither your PATH nor your shell profile. Read it first if you like: install.sh, install.ps1.
Claude Desktop — download the .mcpb bundle for your platform from the latest release and open it. The bundle contains only the server; install the CLI with one of the options above to create presets and store secrets.
By hand — every GitHub release has archives for macOS (arm64, x86_64), Linux (x86_64, aarch64; static musl builds, plus an x86_64 glibc build) and Windows (x86_64), a combined SHA256SUMS, and a build-provenance attestation for each archive:
The macOS binaries are not notarized. Homebrew, npm, cargo and the install script don't mark them as downloaded, but an archive or bundle saved from a browser may be blocked by Gatekeeper until you run xattr -d com.apple.quarantine on it.
There is no Docker image, on purpose: the OS keychain — macOS Keychain, Windows Credential Manager, the Linux kernel keyring — isn't reachable from inside a container, and mcp-warden never falls back to keeping secrets in a file.
90-second quickstart
The preset auto-approves only GET /user/repos; any other path is refused before the token is touched. To let the agent read more, widen the allow-list (e.g. --allowed-paths '/user/repos,/repos/OWNER/[^/]+') and prefer a fine-grained PAT limited to specific repos. Patterns match the whole path, as exact strings or regexes anchored as ^(?:…)$, never as prefixes; [^/]+ is safer than .* for one segment. They see the percent-decoded path, so %2F is a separator: a GitLab-style id like /projects/group%2Fproject needs /projects/[^/]+/[^/]+. An HTTP preset with no allowed_paths allows every path under base_url — preset add and doctor warn about it, and the built-in github-read / gitea-read / stripe-read templates ship with approval = "prompt" for that reason.
Wire mcp-warden into your agent — see docs/claude-code-setup.md or docs/cursor-setup.md.
In your agent: ask "list my GitHub repos via mcp-warden". Watch the agent call list_presets, then proxy_http — and watch your PAT stay out of the prompt.
Find and fix plaintext keys
Keys pasted into MCP client configs sit on disk in plaintext, where the agent, a synced dotfile or a screenshot can pick them up. Three commands fix that:
scan reads Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and Codex configs plus .mcp.json / .env files in the current directory (--path DIR for more). import handles keys in a stdio server's env; for keys in arguments, headers, URLs or .env files, scan says what to do instead. To wrap a server by hand: mcp-warden server add github --env GITHUB_PERSONAL_ACCESS_TOKEN -- npx -y @modelcontextprotocol/server-github (the value is read from stdin). Details: docs/scan-and-import.md.
CLI reference
MCP tools exposed
list_presets — read-only catalogue of available actions.proxy_http — execute an HTTP request through a preset; allow-list validation runs before credential injection.ssh_exec (v0.2.0) — run a shell command on an SSH host; command must match preset's anchored regex allow-list; key-based auth + host-key verification.ssh_run (v0.6.0) — run one of an SSH preset's named commands: the command line is fixed in the preset, the agent supplies typed values (int, enum, string or path), checked before any credential is read. Optionally each command is also its own tool (expose_as_tools).sftp_transfer (v0.2.0) — get/put a file over SFTP; remote path matches preset's sftp_allowed_paths, local path under $HOME or /tmp.db_query (v0.2.0) — run a NAMED QUERY against PostgreSQL / MySQL / Redis. SQL/command is fixed at preset definition; agent supplies only query_name + positional params.get_secret_for_env — last-resort tool when a child process must read a secret from env. Always prompts for approval, regardless of preset policy.
Claude Code plugin
For Claude Code there is a plugin that bundles the MCP server config, a skill that teaches Claude to use mcp-warden correctly (discover presets first, never ask for tokens, respect approvals, treat get_secret_for_env as a last resort) and a guided /mcp-warden:setup command. Install the binary first, then in Claude Code:
Restart Claude Code and run /mcp-warden:setup. If you previously added the server with claude mcp add, remove that entry so it isn't registered twice. Details: plugins/mcp-warden/.
Other MCP clients: see docs/claude-code-setup.md and docs/cursor-setup.md for manual setup.
What's new in v0.6.0
- Named SSH commands. Declare the commands an agent may run, with typed parameters (
int, enum, string, path); the agent calls ssh_run with a name and values, and never composes a command line. Every template is checked at startup, every value before the key is read, and the prompt shows the full command. Each command can have its own approval policy and window, and expose_as_tools makes each one its own MCP tool. Try one with mcp-warden preset test NAME --run CMD --param k=v; start from mcp-warden preset scaffold ssh-deploy.
- More ways to authenticate HTTP: an API key as a query parameter, OAuth2 (a fresh access token for each call, refresh-token rotation handled across processes) and AWS SigV4, with templates for Google Maps, Google Drive and S3.
- A tamper-evident audit log. Every write is hash-chained, the chain is anchored in the keychain, and
mcp-warden audit verify names any edited, deleted or rolled-back entry. A rewritten log is never anchored.
- Dependencies: russh 0.65, mysql_async 0.37 and notify-rust 4.18 clear seven of the eight accepted RustSec advisories; RSA SSH keys now sign with SHA-2, so they work with current OpenSSH.
- Plus:
max_output_bytes for SSH presets, doctor warnings for catch-all command patterns and destructive templates, scan recognises AWS temporary keys and Google OAuth credentials, and upstream errors no longer include the request URL.
After upgrading:
- Restart your MCP clients, so no 0.5.x server keeps writing to the audit log without the chain.
- If you give a named command
approval = "auto", run mcp-warden preset confirm for its preset; until then it asks.
- Building from source now needs Rust 1.94.1. Prebuilt binaries and packages are unaffected.
Every change: CHANGELOG.md. The re-audit of this release is in docs/security/security-audit-2026-11.md.
How it compares
Other MCP credential brokers make different trade-offs:
Compared with Keyward 0.1.1, Wundervault MCP server 2.1.0 and Janee 0.16.0, from each project's README and docs as of November 2026. ? means not documented there. If something here is wrong or out of date, please open an issue.
Security model
mcp-warden's threat model and security invariants live in docs/threat-model.md. At a glance:
- Secrets in the OS keychain only — never on disk in plaintext, never in logs.
- A credential the upstream echoes back in a
proxy_http response (an echo endpoint, an error that quotes the token) is replaced with [redacted by mcp-warden] before the agent sees it. The rest of the response is untrusted upstream data and is passed through as is.
- Allow-list validation runs before credential injection.
- Default approval policy is
prompt; auto requires --confirm-auto at preset creation and a human confirmation in the approval prompt, bound to the preset's exact form — an edited auto preset asks again until mcp-warden preset confirm.
- The MCP server loads and validates
config.toml once at startup and never re-reads it: restart the server after editing presets.
- Audit log is append-only — the trait surface itself contains no
delete / clear method.
mcp-warden lock stops every running server at its next call; a server that has seen the lock stays locked until it restarts, and unlock needs a human to approve it.- Presets can cap and trim what
proxy_http hands the agent (max_response_bytes, response_fields); a credential the upstream echoes back is always scrubbed.
ssh_exec refuses shell syntax whatever the preset's patterns allow, because sshd runs every command through the remote login shell. For a second allow-list on the server — a dedicated account, command= / ForceCommand and a gate script — see docs/ssh-hardening.md.- Wrapped servers (
mcp-warden run) only get keys stored for them (server/<name>/<VAR>), never a preset's secret, and their command is fixed in the config. The key is still visible to the process it is handed to.
- Stdout is the MCP protocol channel; all logs go to stderr.
Links
License
Apache-2.0 — permanent commitment for the OSS core. See LICENSE.
mcp-warden stays fully functional for free, forever — see our open-core commitment.
