McpVanguard

Security gateway for MCP agents and tool servers.

McpVanguard sits between an AI agent and an MCP server, normalizes and inspects tool traffic in real time, and enforces a layered policy before sensitive calls reach the underlying tool. It runs locally in front of stdio servers or as a hosted gateway over SSE and Streamable HTTP.

Product profiles—monitor,balanced,strict— let you adopt incrementally: start with audit-only discovery, move to balanced enforcement, then enable strict hardening for production-sensitive systems.

Existing MCP servers do not need to be rewritten.

MCP workflows are powerful, but once tools touch files, shells, or networks, guardrails matter.

McpVanguard adds a runtime enforcement boundary so you can:

- keep normal tool traffic flowing
- block unsafe calls before execution
- inspect and debug policy decisions with audit logs
- adopt incrementally without rewriting existing MCP servers

McpVanguard is for developers and platform teams who want explicit policy enforcement around MCP workflows.

- inspect MCP tool calls before execution
- block unsafe filesystem, command, and network patterns
- enforce auth, role, and scope requirements for sensitive tools
- inspect server metadata before it reaches downstream models
- track repeated suspicious behavior over time
- emit audit and telemetry signals for blocked, warned, and allowed traffic

Use one raw path and one guarded path against the same MCP server.

- safe file read passes in both paths
- path traversal attempt is blocked in the guarded path
- risky network request is blocked in the guarded path
- metadata poisoning attempts are filtered or blocked before model exposure

This gives you a fast signal that policy is active and enforcement behaves as expected.

- protect local desktop or developer-machine MCP servers without rewriting them
- add a hosted gateway in front of shared MCP servers
- compare raw versus guarded behavior for risky tool workflows
- add policy enforcement to high-risk file, shell, and network-access tools

# Multi-instance L3 behavioral state pip install "mcp-vanguard[redis]" # RE2-backed deterministic regex matching where the wheel is available pip install "mcp-vanguard[re2]" # Hosted/full deployment extras pip install "mcp-vanguard[full]"

# Balanced profile (default OSS/developer behavior) vanguard start --profile balanced --server "npx @modelcontextprotocol/server-filesystem ." # Strict profile (production hardening) vanguard start --profile strict --server "npx @modelcontextprotocol/server-filesystem ."

export VANGUARD_API_KEY="replace-with-a-long-random-secret" vanguard sse --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

For public/non-loopback hosted deployments,strictprofile refuses to start unless transport auth is configured with a long randomVANGUARD_API_KEYor OAuth/JWKS settings.balancedremains suitable for demos and staged rollouts, but will warn loudly when exposed without auth.

Hosted deployments can also enable opt-in per-session budgets for tool-call rate, risky decisions, and repeated blocked attempts. These act as circuit breakers around the layered policy path without changing defaults for local OSS use.

If you operate a hosted template or shared gateway, setVANGUARD_ALLOWED_SERVER_COMMANDSto restrict which upstream MCP server executables McpVanguard may spawn.

For private-network MCP servers reached through Anthropic MCP tunnels, the recommended placement is tunnel -> McpVanguard -> private MCP server. Tunnels reduce network exposure. McpVanguard enforces the execution boundary.

McpVanguard provides a documented MCP 2026-07-28 compatibility baseline in the2.2.xline. The baseline includes an opt-in stateless transport profile, additiveMcp-Method/Mcp-Nameconsistency checks, and explicit_metainspection coverage. It is not a claim of full Tasks, MCP Apps, subscriptions, MRTR, or final-spec conformance. Seedocs/MCP_2026_07_28_RC_COMPATIBILITY.md.

Need a complete deployment walkthrough? Seedocs/DEPLOYMENT.md,docs/railway-deployment-guide.md, anddocs/ANTHROPIC_MCP_TUNNELS.md.

# 1. Initialize safe zones and .env template vanguard init # 2. Optionally update Claude Desktop server entries vanguard configure-claude # 3. Launch the local security dashboard vanguard ui --port 4040 # 4. Run compliance and readiness checks vanguard audit-compliance

Safe zones are deterministic path-boundary checks, not a substitute for OS sandboxing or container isolation. They inspect standard and common custom path-like argument names recursively, but production deployments should still tunerules/safe_zones.yamlfor the actual schemas and directories your MCP tools are allowed to touch. Seedocs/SAFE_ZONES.md.

For operator triage, JSON audit logs include SIEM-friendly decision fields and structuredpolicy_explanationdata with the primary layer, rule family, profile effect, upstream-call status, and tuning hint. Seedocs/BLOCK_DECISIONS.md.

AI Agent -> McpVanguard -> MCP Server -> Tools / Files / External Systems

vanguard benchmark-run --profile monitor vanguard benchmark-run --profile balanced vanguard benchmark-run --profile strict vanguard benchmark-profiles vanguard benchmark-baselines

The benchmark results are a release and tuning signal, not a promise of universal detection or zero false positives. Seedocs/BENCHMARKS.mdfor interpretation guidance and the recommended release gate.

For the public research note behind the layered design, see[Why MCP Security Needs Layered Runtime Enforcement.

McpVanguard is local-first and supports stronger hosted-gateway controls when needed.

…