McpVanguard is an open-source security proxy and active firewall for the Model Context Protocol (MCP). It acts as a real-time "Reflex System" between AI agents and their tools, protecting the host system from malicious intent, prompt injection, and data exfiltration.
Part of the Provnai Open Research Initiative — Building the Immune System for AI.
No changes to your agent. No changes to your server. Just wrap it.
# 1. Install
pip install mcp-vanguard
# 2. Start as a Cloud Security Gateway (SSE)
# Set an API key to protect your endpoint
export VANGUARD_API_KEY="your-secret-key"
vanguard sse --server "npx @modelcontextprotocol/server-filesystem ."
# 3. Traditional Stdio Wrap (no network, no auth needed)
vanguard start --server "npx @modelcontextprotocol/server-filesystem ."
# 4. Enable VEX Flight Recorder (Immutable Audit)
export VANGUARD_VEX_URL="https://api.vexprotocol.com"
export VANGUARD_VEX_KEY="your-agent-jwt"
vanguard sse --server "..." --behavioral
# 5. Sync latest threat signatures from GitHub
vanguard updateMcpVanguard sits at the Interception Layer of the Provnai stack. It prevents the gap between Cognitive Intent (what the agent thinks) and Environmental Execution (what actually happens to your PC).
| Layer | Component | Defense Mechanism | Performance |
|---|---|---|---|
| L0 | Cloud Gateway | SSE/Network Bridge with optional API key auth | <5ms |
| L1 | Static Rules | 80+ security signatures across 5 categories | <1ms |
| L2 | Semantic Intelligence | Local Ollama LLM intent classification | Async |
| L3 | Behavioral Analysis | Sliding-window anomaly detection (Scraping/Enum) | Stateful |
- Filesystem: Path traversal, null bytes, restricted roots (
/etc/,~/.ssh/), Cyrillic homograph detection. - Command: Pipe-to-shell, reverse shells, semicolon/
&&/newline command chaining, expansion bypasses. - Network: SSRF, cloud metadata endpoints (AWS/GCP/Azure), IPv6 and hex/octal encoded IPs.
- Jailbreak: Prompt extraction, instruction-ignore patterns, unicode hidden characters.
- Privilege: SUID binary creation,
LD_PRELOADinjection, crontab manipulation.
McpVanguard integrates natively with the VEX Protocol. Whenever the proxy blocks a malicious action (L1/L2/L3), it instantly processes a "fire-and-forget" payload directly to the VEX API.
The VEX Server cryptographically hashes the blocked intent, runs it through the CHORA Gate, and anchors an immutable receipt (PoE) to the Bitcoin blockchain.
Enterprise auditors can mathematically prove exactly why an agent was blocked without relying entirely on local log trust.
┌─────────────────────────────┐ ┌──────────────┐
AI Agent │ McpVanguard Proxy │ │ VEX API │
(Claude, GPT) │ │──Async─▶│ (CHORA Gate) │
│ │ ┌──────────────────────┐ │ └──────────────┘
│──JSON-RPC▶│ │ L1: Rules Engine │ │ │
│ │ │ L2: Semantic Scorer │ │ ▼
│ │ │ L3: Behavioral Logic │ │ [Bitcoin Anchor]
│ │ └──────────────────────┘ │
│◀─ BLOCK ──│ or ALLOW ───────────▶│ MCP Server
│ (Status │ │ (filesystem, shell...)
│ Code) └─────────────────────────────┘
Traffic is inspected on every message, in both directions. Blocked messages return a standard JSON-RPC error response — the server never sees the attack.
| Phase | Goal | Status |
|---|---|---|
| Phase 1 | Foundation (Proxy, CLI, Defensive Rules) | ✅ DONE |
| Phase 2 | Intelligence (L2 Semantic OpenAI, L3 Behavioral Redis Scaling) | ✅ DONE |
| Phase 3 | Flight Recorder (VEX & CHORA Integration) | ✅ DONE |
| Phase 4 | Distribution (v1.0.0 Stable, PyPI, WSL Verified) | ✅ DONE |
| Phase 5 | Enterprise Integration (Railway, 100% Finality) | ✅ DONE |
Apache License 2.0 — see LICENSE.
Built by the Provnai Open Research Initiative. "Verifying the thoughts and actions of autonomous agents."