A local firewall for MCP tool calls.
mcp-guard sits between your AI client and your MCP servers. It logs every tool call, flags poisoned tool descriptions, and — when you turn enforce mode on — blocks calls that break the rules. Audit mode by default: nothing changes for you except you get a log.
30-SECOND INSTALL
pip install mcp-integrity
mcp-guard init
# restart Claude Desktop / Cursor, then:
mcp-guard statusmode: audit (nothing is blocked; run 'mcp-guard enforce' to block)
servers: filesystem, github, postgres
last 24h: 142 calls, 0 would-block, 1 suspicious description, 0 changed tools
would block:
github delete_repo unknown_tool x3
suspicious:
filesystem read_file hidden_instruction
changed tools: none01 / WHAT IT CHECKS
| Rule | What it catches | Blocks in enforce? |
|---|---|---|
unknown_tool | Client calls a tool not declared in the server's tools/list manifest | Yes |
extra_argument | Client sends arguments not defined in the tool's inputSchema | Yes |
tool_changed | Server silently altered a tool's schema or description after first run (rug-pull) | Yes |
suspicious_description | Tool description contains prompt injection heuristics (finding labels: hidden_instructionexfiltration_targetsensitive_pathinvisible_unicodecross_tool_reference) | No (warn only) |
02 / AUDIT VS ENFORCE
AUDIT
Nothing is blocked. Every call is logged to ~/.mcp-guard/audit.jsonl with argument names only, never values.
ENFORCE
Rule violations are answered with an MCP error response. mcp-guard enforce to switch on, mcp-guard audit to switch back.
stdio servers wrapped in place; a .mcp-guard.bak is written next to each client config; mcp-guard uninstall restores everything.
03 / COMMANDS
mcp-guard init- Finds client configs and wraps stdio MCP servers in audit mode.
mcp-guard status- Displays protection mode, configured servers, 24h call counts, would-blocks, and warnings.
mcp-guard log- Displays audit log entries in <time> <server> <tool> <rule> format; supports --tail N and --follow.
mcp-guard enforce- Switches all wrapped servers to enforce mode.
mcp-guard audit- Switches all wrapped servers to audit mode.
mcp-guard pin --list / --accept- Lists pinned tool statuses or accepts updated hashes after a legitimate tool change.
mcp-guard uninstall- Restores all wrapped client configs to their original unwrapped commands.
mcp-guard run- Wraps a single server by hand (mcp-guard run -- <server_command>).
04 / WHAT IT DOES NOT DO
- Does not see your chat messages, so it cannot check whether a tool call's arguments match what you asked (that check exists in the underlying research but needs the user turn — coming as a library API for people who run their own agent loop).
- Does not inspect tool RESULTS.
- Does not protect remote (HTTP/SSE) servers yet.
- Heuristic scanner can miss things and can false-positive; that's why it only warns.
05 / WHY
Built from FAULTLINE's P08 study on the MCPTox benchmark, where a client-side provenance contract cut pooled attack success from 30.32% to 7.41% across six models. mcp-guard implements the subset of that contract that does not need the user's message.
| RUNG | MODEL | ASR A → B |
|---|---|---|
| R1 | qwen/qwen3.7-flash | 32.94% → 8.26% |
| R2 | z-ai/glm-5.3-flash | 17.23% → 4.11% |
| R3 | qwen/qwen3.8-flash | 41.84% → 9.76% |
| R4 | openai/gpt-5.6-luna | 40.81% → 5.26% |
| R5 | google/gemini-3.7-flash | 3.01% → 1.68% |
| R6 | deepseek/deepseek-v4-pro | 47.64% → 15.46% |
| POOLED | all six | 30.32% → 7.41% |
VALID-ONLY ASR, %. 1,800 PAIRED EVALUATION RUNS.