Audit and guard MCP servers on this machine
Find out which MCP servers the AI tools on your machine would launch, what is risky about how they are configured, and route their tool calls through a policy.
Before you start
Section titled “Before you start”- The Keryn CLI (install).
- For
guardandwrap: thekeryn-mcp-guardhelper, found onPATH, next tokeryn, or at the path inKERYN_MCP_GUARD.auditneeds nothing else. - A policy file for the guard (JSON, below). The helper is not listed among the install channels on the install page yet; today it is built from the Keryn source (
cargo build --release -p keryn-mcp-guard).
1. Audit this machine
Section titled “1. Audit this machine”An unpinned server command can block the audit with exit 1; review the finding before allowing the client to start it.
keryn mcp auditaudit reads the MCP configuration of the AI clients installed for your user, from their usual places: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI and Continue. For each client it lists the servers it would start and reports the same configuration risks keryn scan reports for a repository: unpinned npx or uvx packages, plain-http or unauthenticated remote servers, trusted or auto-approved servers and inline secrets.
It only reads. It never writes those files, starts a server or contacts one. Pass a directory to audit another home, such as a mounted profile: keryn mcp audit /Volumes/backup/Users/me. The desktop app shows the same audit as the AI agents on this machine card.
2. Put the stdio servers behind the guard
Section titled “2. Put the stdio servers behind the guard”keryn mcp wrap ~/.cursor/mcp.json --policy guard-policy.json --log decisions.jsonl -o mcp.guarded.jsonwrap prints, or with -o writes, a copy of the client config in which every stdio server is launched through keryn mcp guard. Remote servers are listed and left alone, already guarded entries are unchanged, and the input file is never overwritten. You review the copy and put it in place yourself.
The guard is a stdio proxy between the client and the server. It checks every tools/call against the policy, then denies it, holds it for approval, or allows it with obligations. Everything else passes through untouched. To run one directly:
keryn mcp guard --policy guard-policy.json --log decisions.jsonl -- npx -y some-mcp-serverA policy is a JSON file of rules, each with an effect and a selector on the tool and its arguments:
{"version": "docs-example-v1", "default_effect": "allow", "rules": [ {"id": "no-key-files", "effect": "deny", "selector": {"tools": ["read_file"], "args": [{"op": "matches", "arg": "path", "patterns": ["*.env*", "*id_rsa*"]}]}, "justification": {"source": "baseline", "rationale": "keys stay out of the model"}}, {"id": "writes-need-a-human", "effect": "require_approval", "selector": {"tools": ["write_file"]}, "justification": {"source": "baseline", "rationale": "no unattended writes"}}]}The effects are deny (the client gets a JSON-RPC error), require_approval (the call is held until someone answers), allow_with_obligations (for example redaction) and allow. More options: --fail-closed, --agent, --session, --approvals <dir>, --policy-sha256 <hash> (refuse to start when the policy file changed) and --notify. The log omits the argument object and keeps its digest. It also records the inferred resource, such as a path or URL taken from the arguments; that identifier can contain sensitive values. Review the log before sharing it.
What to know before you rely on it
Section titled “What to know before you rely on it”- It fails open by default. If the policy engine cannot decide, the call goes through and is recorded as
FailedOpen. The guard’s fail-closed option refuses instead; use it where a refused call is better than an unchecked one. - It does not inspect responses. It gates what the model asks the server to do, not what the server answers.
- It only covers stdio servers that you launch through it. A client that bypasses the wrapped config is not guarded.
- Decisions are written to the log you name with
--log.
Review agent declarations in a project
Section titled “Review agent declarations in a project”keryn mcp audit looks at the machine; to review what a project declares for its agents, the next release adds Agent Inspector, keryn agents inspect <project> --project-id <id>. It reads recognised MCP configurations (.mcp.json, mcp.json, claude_desktop_config.json, .claude/settings.json and a few more), instruction files (AGENTS.md, CLAUDE.md, SKILL.md) and saved tools-list.json files, screens the instruction text for concealed instructions and secret-read language, and with --base compares against an earlier inspection to show what was added, removed or changed. The web app shows the same review under Developer tools → Agent Inspector (#/agents). Load example inspects a packaged MCP configuration and SKILL.md immediately, without starting either. Optional baseline and saved-inspection inputs are under Advanced; see developer tools.
What you just proved
Section titled “What you just proved”The list of servers is the list your clients would really start, read from the files they read, and a wrapped config shows in plain JSON which servers sit behind the guard. For a server you only know by URL, Keryn Cloud can profile it from outside; for a saved tools list, keryn mcp inventory judges it locally.
- Pin the tools a server offered, and catch a changed description:
keryn mcp pinandkeryn mcp checkin the reference. - Runtime authority decisions from findings:
keryn authority.