# Audit and guard MCP servers on this machine

> List the MCP servers your AI clients would start, report their configuration risks, and put their stdio servers behind a policy-enforcing guard.

Source: https://keryn.dev/docs/guides/mcp-guard/

## Goal

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

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)).
- For `guard` and `wrap`: the `keryn-mcp-guard` helper, found on `PATH`, next to `keryn`, or at the path in `KERYN_MCP_GUARD`. `audit` needs nothing else.
- A policy file for the guard (JSON, below). The helper is not listed among the install channels on the [install page](https://keryn.dev/docs/start/install/) yet; today it is built from the Keryn source (`cargo build --release -p keryn-mcp-guard`).

## 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.

```sh
keryn mcp audit
```

`audit` 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

```sh
keryn mcp wrap ~/.cursor/mcp.json --policy guard-policy.json --log decisions.jsonl -o mcp.guarded.json
```

`wrap` 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:

```sh
keryn mcp guard --policy guard-policy.json --log decisions.jsonl -- npx -y some-mcp-server
```

A policy is a JSON file of rules, each with an effect and a selector on the tool and its arguments:

```json
{"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

- **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

`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](https://keryn.dev/docs/guides/web-app/#developer-tools).

> **Note: In the next release**
> Agent Inspector is in the Keryn source after release 0.5.2 and in no release yet, so `keryn agents` is not in the CLI reference. It is static: it starts no server, runs no skill and contacts no tool. It does not enforce a guard, sandbox tools or approve anything, and its signals are cues for a person to review, not proof of intent or of access. An incomplete inspection exits 3 rather than reporting a clean result.

## 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](https://keryn.dev/docs/cloud/scans/#mcp-server) can profile it from outside; for a saved tools list, [`keryn mcp inventory`](https://keryn.dev/docs/reference/cli/mcp-inventory/) judges it locally.

## Next

- Pin the tools a server offered, and catch a changed description: `keryn mcp pin` and `keryn mcp check` in the [reference](https://keryn.dev/docs/reference/cli/mcp-inventory/).
- Runtime authority decisions from findings: [`keryn authority`](https://keryn.dev/docs/reference/cli/authority-propose/).
