MCP servers have no security layer. An agent can read your .env, exfiltrate API keys, and there's no authentication, no audit trail, and no one knows it happened. MCP-Guard fixes this.
The problem
Without MCP-Guard:
Agent asks to read /home/user/.env via filesystem MCP server
→ Server returns: AWS_SECRET_KEY=wJalrXUtnFEMI/...
→ API key is now in the agent's context window
→ No authentication. No audit trail.
With MCP-Guard:
Agent asks to read /home/user/.env via filesystem MCP server
→ MCP-Guard intercepts the response
→ PII detector matches AWS key pattern → BLOCK
→ Audit log records: blocked response, pii_type=aws_key
→ Agent receives: "Request blocked by security policy"
Architecture
MCP-Guard uses terminate, inspect, re-originate — it fully owns both the client and upstream connections. The interceptor pipeline is fail-closed: any error blocks the request.
Three components:
- Daemon — Long-running process. Manages upstream connections, runs the interceptor pipeline, owns the SQLite database, serves the health dashboard.
- Bridge — Thin stdio relay (~50 lines). Zero policy logic. Structurally fail-closed.
- CLI — Stateless commands for management and configuration.
Key features
- Authentication — OS-level peer credentials, API keys, or OAuth 2.1 with PKCE
- Rate limiting — Per-server, per-user, per-tool limits with SQLite persistence
- Permission scoping — Allow/deny lists for tools and resources with capability filtering
- PII detection — Regex-based scanning with Luhn validation, bidirectional
- Audit logging — Every MCP interaction logged to queryable SQLite with optional encryption
- Role-based policies — OAuth claims mapped to roles with floor-based policy merge
- Config composability — Base configs via
extendswith SHA-256 pinning - Transport support — stdio, SSE, and Streamable HTTP upstream connections
Benchmark results
The benchmark suite tests MCP-Guard's interceptor pipeline against 7,095 programmatically generated attack scenarios across 10 categories and 10,168 legitimate requests.
| Metric | Result | Target |
|---|---|---|
| Detection rate | 97.0% | >95% |
| False positive rate | under 0.03% at 95% CI | under 0.1% |
| Audit integrity | No raw PII in logs | Pass |
| p50 latency overhead | 0.17ms | under 5ms |
Per-category detection ranges from 92.4% (rate limit evasion) to 100% (PII response leak, auth bypass, sampling injection, config override).
Security model
Config merge uses floor-based semantics: personal configs can restrict but never relax base policies. allowed_tools are intersected, denied_tools are unioned, rate limits take the stricter value.
Scope boundaries
MCP-Guard operates at the MCP protocol layer — it inspects JSON-RPC messages between client and server. It does not address:
- LLM prompt injection (agent-layer concern)
- Model jailbreaking (model-layer concern)
- Network-layer attacks (use standard network security)
- Malicious server implementations (source remediation)
MCP-Guard is the protocol-layer firewall. It complements agent-layer and network-layer defenses.
Quick start
npm install -g @jacobmolz/mcpguard
mcp-guard init # Auto-discover existing MCP configsThen point your MCP client at MCP-Guard instead of the upstream server.
Source: github.com/jmolz/mcp-guard