McpVanguard MCP Server

An open-source security proxy and active firewall for the Model Context Protocol (MCP).

GitHub
13

Documentation

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.

Tests CodeQL Security Audit SBOM PyPI version License: MIT Python 3.11+

Why Developers Use It

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

What It Does

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

Quick Verification Scenario

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.

Use Cases

  • 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

Quickstart

Install the package:

pip install mcp-vanguard

Optional deployment extras:

# 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]"

Wrap a local stdio MCP server:

# 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 ."

Run as a hosted gateway:

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

For public/non-loopback hosted deployments, strict profile refuses to start unless transport auth is configured with VANGUARD_API_KEY or OAuth/JWKS settings. balanced remains 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.

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 is also tracking the MCP 2026-07-28 release candidate. The 2.1.x line includes additive Mcp-Method / Mcp-Name consistency checks when those headers are present, plus explicit _meta inspection coverage. See docs/MCP_2026_07_28_RC_COMPATIBILITY.md.

Deploy on Railway:

Deploy on Railway

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

Getting Started

Bootstrap a local workspace:

# 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

How It Works

McpVanguard uses five core inspection layers, L0 through L3 plus L1.5, with auth policy and a final policy composer around them. Every tool call is inspected before it reaches the upstream MCP server.

LayerPurposeNotes
L0 - PreflightNormalize and annotate (URL decode, NFKC, strip zero-width, size/depth gates)Always on
AuthOAuth scope enforcement and destructive-tool policyRole-aware
L1 - RulesDeterministic blocking using signatures, recursive argument inspection, and safe boundariesFast path
L1.5 - CamouflageDetect trust-signal camouflage and scorer manipulationProfile-sensitive
L2 - SemanticOptional intent scoring (can escalate/block, cannot downgrade deterministic blocks)Async
L3 - BehavioralSession and sequence-aware anomaly checksStateful
Policy ComposerFinal verdict: ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCKExplainable

The five core inspection layers are L0, L1, L1.5, L2, and L3. Auth policy and the final policy composer sit around that core path.

If a request is blocked, the agent receives a standard JSON-RPC error and the upstream server never sees the call. The audit log records the primary reason and all supporting findings.

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 tune rules/safe_zones.yaml for the actual schemas and directories your MCP tools are allowed to touch. See docs/SAFE_ZONES.md.

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

Deployment Model

McpVanguard is best understood as a security gateway for MCP workflows.

  • Local-first mode: wraps stdio MCP servers on a developer machine
  • Gateway mode: exposes hardened SSE and Streamable HTTP endpoints for hosted or shared deployments

Typical path:

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

Current Capabilities

  • hardened SSE and Streamable HTTP transport paths with request rate, concurrency, session-binding, and session-count controls
  • metadata poisoning inspection on initialize and tools/list
  • JWT, JWKS, issuer, audience, claim, and scope checks for bearer-auth deployments
  • server integrity and capability drift verification
  • cross-server isolation and server_id traceability
  • signed-manifest, provenance, detached signature, and Sigstore-backed trust verification
  • benchmark and taxonomy tooling for measurable coverage
  • optional receipt_v1 JSONL emission for offline-verifiable runtime evidence with mcp-receipt after export/signing

Benchmarks

McpVanguard includes packaged benchmark corpora for adversarial and benign MCP traffic. Use them to compare profiles before deployment:

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. See docs/BENCHMARKS.md for interpretation guidance and the recommended release gate.

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

Authentication Modes

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

  • stdio mode: no network auth required
  • SSE / Streamable HTTP mode: supports VANGUARD_API_KEY
  • Bearer / JWT mode: supports verified JWT/JWKS validation, issuer/audience/claim/scope checks, and auth-aware policy on the hosted gateway path
  • Strict hosted mode: refuses public binds without transport auth, sets bearer-claim mismatch handling to block, and requires Origin when an allowlist is configured

Management Plane

Native vanguard_* management tools are disabled by default. If you enable them, also choose an explicit management-plane mode:

  • disabled: no native management tools are exposed
  • same_session_dev: local/dev only; read and mutating tools share the governed MCP session and startup prints a warning
  • operator_only: read-only tools may be visible, but mutating tools require an admin role or vanguard:admin / scope:admin scope

For production, keep mutating management out of normal governed agent sessions unless the caller is an authenticated operator. Management actions are audited and denied/mutating attempts are risk-visible.

Semantic Backend Options

The optional Layer 2 semantic scorer supports multiple backends. The first configured backend wins.

BackendEnv VarsNotes
Universal CustomVANGUARD_SEMANTIC_CUSTOM_KEY, related custom varsFast inference providers such as Groq or DeepSeek
OpenAIVANGUARD_OPENAI_API_KEYDefault model: gpt-4o-mini
OllamaVANGUARD_OLLAMA_URLLocal execution, no API key required

For a more detailed local/offline setup guide, see docs/LOCAL_SEMANTIC_MODE.md.

Integrity and Trust

McpVanguard includes:

  • signed upstream server manifests
  • capability baselines and drift checks
  • provenance verification hooks
  • detached artifact-signature verification
  • Sigstore bundle verification with identity and issuer constraints

This should be described as server integrity, baseline verification, and trust verification, not as a full SBOM platform.

Project Status

  • 2.1.x is the current runtime hardening patch line for layered enforcement
  • layered enforcement path (L0 -> L1 -> L1.5 -> L2 -> L3 -> Policy Composer) is implemented and covered by local and CI verification
  • product profiles (monitor / balanced / strict) are the supported deployment modes for this release line
  • broader research-only features (GPU attestation, hardware-rooted provenance, zero-FP claims) are intentionally outside the core OSS release scope

See CHANGELOG.md for the release history and docs/DEPLOYMENT.md for deployment details.

Privacy

McpVanguard focuses on local inspection and gateway enforcement. See PRIVACY.md for current privacy and data-handling details.

Support

FAQ

Does this replace my MCP server?
No. McpVanguard sits in front of your existing MCP server and enforces policy before calls reach it.

Do I need to rewrite tools or agent code?
Usually no. Most setups start by routing one workflow through McpVanguard.

Is this only for hosted setups?
No. It supports local-first stdio wrapping and hosted gateway modes.

License

MIT License - see LICENSE.

Built by Provnai.