MCP Guard

MCP Guard is a free guard for coding agents. It checks each shell command and file edit that Claude Code is about to run: destructive ones wait until a named person signs them in Permission Protocol, and only a verified, signed receipt lets them run. Everything else runs as before.

Install for Claude Code

In your project folder, run:

npx -y @permission-protocol/mcp-guard init --preset coding-agent --hook claude-code

This works in any folder. In a folder that already has .claude/ or CLAUDE.md, you can leave out --hook claude-code.

What you need

• A free Permission Protocol account with the owner or admin role in a workspace. Sign up at https://app.permissionprotocol.com/guard. If you have no passkey yet, your first signature sets one up.
• Node.js with npx.
• On Windows, Git for Windows: Claude Code runs the hook through Git Bash.

What the command does

1. It prints a pairing code and opens a Permission Protocol page in your browser. Over SSH, in CI or on Linux without a display it prints the link instead and says why. Check that the page shows the same code and choose Connect.
2. It writes the coding-agent policy to pp.config.yaml and adds the hook to .claude/settings.json.
3. It runs a local self-test of the hook. Nothing is sent and nothing runs.
4. It holds one do-nothing test call and opens its signing page. Sign it to get your first receipt.
5. It tells you to restart Claude Code, which then loads the hook.

It also stores an install token (in the OS keychain, or in a file restricted to your user) and creates a local signing key under ~/.config/mcp-guard/. An existing pp.config.yaml that loads is kept as it is. It does not change any MCP server: init lists the ones it found that are not wrapped yet and prints the command that guards one (init --preset coding-agent --server <name>). The checks that can refuse run before the login, so a refusal changes nothing. Every step in detail: docs/hooks.md.

What a held call looks like

• The signing page opens in your browser. It does not open over SSH, in CI, on Linux without a display, or when you switch it off (details). Waiting calls are also listed at https://app.permissionprotocol.com/guard.
• A named person chooses Sign or Reject. A rejected call is denied.
• After a signature, the receipt is verified offline against keys pinned in the package and redeemed once, and the call runs. Claude is told Approved by <name> through Permission Protocol. Receipt: <link>, and you see the same line.
• If nobody signs within 240 seconds, the call is denied with the signing link. Sign it, then retry the same call.

See what it did

In the project folder:

npx -y @permission-protocol/mcp-guard report

It reads the local log only and sends nothing (details).

Remove it

In the project folder:

npx -y @permission-protocol/mcp-guard hook uninstall

This removes only the mcp-guard entry from .claude/settings.json. At the end of its run, init prints the exact command for your setup under To undo:. What else init changed:

• pp.config.yaml (unless one was already there) and, once calls are checked, the log pp-receipts.jsonl beside it. Delete them if you no longer want them.
• The install token and the signing key stay on this machine for other projects (where). To disconnect the machine, revoke its token in your workspace under Settings > Developer access.
• If you ran init with --server <name>, To undo: names the backup to copy back over that MCP config file.

More

• What is guarded
• What it does not catch
• What leaves this machine: for a held call, and the daily usage heartbeat, which is on by default
• MCP servers: the proxy
• Troubleshooting

What is guarded

The hook sees Claude Code's Bash, PowerShell, Write, Edit and NotebookEdit calls. The coding-agent preset holds these for a signature (the same rules apply to MCP tools when the preset guards a wrapped server):

Rule	Holds
destructive-shell	rm -rf outside the working tree, force pushes, pushes that delete a branch or tag, --mirror and --all pushes, disk writes, destructive SQL through psql -c and similar
destructive-sql	DROP, TRUNCATE, DELETE / UPDATE without WHERE, in the SQL argument of an MCP database tool (sql, query, ...)
terraform-destroy	terraform destroy, apply -destroy, apply -auto-approve without a saved plan
cloud-delete	Cloud and Kubernetes deletes of databases, volumes, buckets, snapshots, clusters, namespaces
production-target	Any call naming a production target you list under targets: (empty by default, so it matches nothing until you add names)
guard-tamper*	Changes to the guard itself: its policy, receipt log, keys, install token, the hook entry and Claude Code settings files, killing it

Secret reads (cat .env, printenv, token printers) are recorded only (secret-read has observe: true) until you delete that line. From 0.6.0 a plain push to main or master (git push origin main) is recorded too (git-push-protected), not held; to hold it again, delete except_kinds: [git_push_protected] and the comma before it from the destructive-shell rule. A policy written by an earlier version is never rewritten by an upgrade, so it keeps holding plain pushes until you edit it or write it again. A command the detectors cannot read (eval, python -c, curl | sh) is held. Everything else runs, and Claude Code's own permission prompts still apply to it: the guard only adds restrictions.

What it does not catch

The detectors are heuristics that stop mistakes. They are not a sandbox.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗