mcp-warden

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.

How it works

1. You store a credential once in the OS keychain via the mcp-warden CLI.
2. You define presets — named, scoped actions (e.g. github-read, stripe-charges).
3. The AI agent connects to mcp-warden as an MCP server (stdio).
4. When the agent wants to act, it calls proxy_http with a preset name and a path/method.
5. mcp-warden validates the request against the preset's allow-list, injects the credential, executes, and returns only the response.
6. 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.
7. 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

brew install ermoluk/tap/mcp-warden

Windows — Scoop

scoop bucket add ermoluk https://github.com/ermoluk/scoop-bucket

scoop install ermoluk/mcp-warden

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)

nix profile install github:ermoluk/mcp-warden

npm — for MCP clients configured with npx. The package is scoped: the unscoped mcp-warden on npm is an unrelated project.

{ "mcpServers": { "mcp-warden": { "command": "npx", "args": ["-y", "@mcp-warden/cli", "mcp"] } } }

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+):

cargo binstall mcp-warden

cargo install --locked mcp-warden

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.

curl -fsSL https://github.com/ermoluk/mcp-warden/releases/latest/download/install.sh | sh

irm https://github.com/ermoluk/mcp-warden/releases/latest/download/install.ps1 | iex

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:

gh attestation verify mcp-warden-aarch64-apple-darwin.tar.gz --repo ermoluk/mcp-warden

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

mcp-warden init

mcp-warden secret add gh_pat # paste your GitHub PAT when prompted mcp-warden preset add github-read \ --type http \ --base-url https://api.github.com \ --auth-bearer gh_pat \ --allowed-methods GET \ --allowed-paths /user/repos \ --approval auto --confirm-auto

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.

mcp-warden audit --last 5                     # see what the agent did

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:

mcp-warden scan                     # where are plaintext keys? (shows type + length, never values)

mcp-warden import # move them into the keychain and rewire the client entries mcp-warden run github # what the rewired entry runs: the server, with its key injected

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 ava