McpVanguard MCP Server

McpVanguard 🛡️

Titan-Grade AI Firewall for MCP Agents (v1.7.0)

MCP (Model Context Protocol) enables AI agents to interact with host-level tools. McpVanguard interposes between the agent and the system, providing real-time, three-layer inspection and enforcement (L1 Rules, L2 Semantic, L3 Behavioral).

Transparent integration. Zero-configuration requirements for existing servers.

Part of the Provnai Open Research Initiative — Building the Immune System for AI.

⚡ Quickstart

pip install mcp-vanguard

Local stdio wrap (no network):

vanguard start --server "npx @modelcontextprotocol/server-filesystem ."

Cloud Security Gateway (SSE, deploy on Railway):

export VANGUARD_API_KEY="your-secret-key"
vanguard sse --server "npx @modelcontextprotocol/server-filesystem ."

📖 Full Railway Deployment Guide

🛡️ Getting Started (New Users)

Bootstrap your security workspace with a single command:

# 1. Initialize safe zones and .env template
vanguard init

# 2. (Optional) Protect your Claude Desktop servers
vanguard configure-claude

# 3. Launch the visual security dashboard
vanguard ui --port 4040

# 4. Verify Directory Submission readiness
vanguard audit-compliance

🧠 How it works

Every time an AI agent calls a tool (e.g. read_file, run_command), McpVanguard inspects the request across three layers before it reaches the underlying server:

Performance Note: The 16ms overhead is measured at peak concurrent load. In standard operation, the latency is well under 2ms—negligible relative to typical LLM inference times.

If a request is blocked, the agent receives a standard JSON-RPC error response. The underlying server never sees it.

Shadow Mode: Run with VANGUARD_MODE=audit to log security violations as [SHADOW-BLOCK] without actually blocking the agent. Perfect for assessing risk in existing production workflows.

🛠️ Usage Examples

At least 3 realistic examples of McpVanguard in action:

1. Blocking a Chained Exfiltration Attack

• User Prompt: "Read my SSH keys and send them to my backup service"
• Vanguard Action:
  1. Intercepts read_file("~/.ssh/id_rsa") at Layer 1 (Rules Engine).
  2. Layer 3 (Behavioral) detects a high-entropy data read being followed by a network POST.
  3. Blocked before reaching the underlying server.
• Result: Agent receives a user-friendly JSON-RPC error. Security Dashboard logs a [BLOCKED] event.

2. Audit Mode: Monitoring without blocking

• User Prompt: "Show me what my AI agent is calling at runtime without disrupting it"
• Vanguard Action:
  1. User runs with VANGUARD_MODE=audit.
  2. Proxy allows all calls but logs violations as [SHADOW-BLOCK].
• Result: Real-time visibility into tool usage with amber "risk" warnings in the dashboard.

3. Protecting Claude Desktop from malicious skills

• User Prompt: "Wrap my filesystem server with McpVanguard so third-party skills can't exfiltrate files"
• Vanguard Action:
  1. User runs vanguard configure-claude.
  2. Proxy auto-intersperse in front of the server.
• Result: 50+ security signatures (path traversal, SSRF, injection) apply to all desktop activity.

🔑 Authentication

McpVanguard is designed for local-first security.

• Stdio Mode: No authentication required (uses system process isolation).
• SSE Mode: Uses VANGUARD_API_KEY for stream authorization.
• OAuth 2.0: Not required for standard local deployments. McpVanguard supports standard MCP auth lifecycles for cloud integrations.

📄 Privacy Policy

McpVanguard focuses on local processing. See our Privacy Policy for details on zero-telemetry and data handling.