# 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](https://github.com/provnai/McpVanguard/actions/workflows/test.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/test.yml)
[![CodeQL](https://github.com/provnai/McpVanguard/actions/workflows/codeql.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/codeql.yml)
[![Security Audit](https://github.com/provnai/McpVanguard/actions/workflows/security-audit.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/security-audit.yml)
[![SBOM](https://github.com/provnai/McpVanguard/actions/workflows/sbom.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/sbom.yml)
[![PyPI version](https://img.shields.io/pypi/v/mcp-vanguard.svg?color=blue)](https://pypi.org/project/mcp-vanguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)

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

For a credential-free, synthetic check in 2.2.2, run `python -m core.demo_verify`.
It checks a benign read and two blocked calls against the bundled in-memory
upstream, using explicit demo-only safe zones. See
[self-service evaluation](docs/SELF_SERVICE_EVALUATION.md) for installation,
expected output, and the separate real-workflow evaluation. Earlier releases do
not include this verifier.

## 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:

```bash
pip install mcp-vanguard
```

Optional deployment extras:

```bash
# 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:

```bash
# 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:

```bash
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, `strict` profile refuses to start unless transport auth is configured with a long random `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.

If you operate a hosted template or shared gateway, set `VANGUARD_ALLOWED_SERVER_COMMANDS` to 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 the `2.2.x` line. The baseline includes an opt-in stateless transport profile, additive `Mcp-Method` / `Mcp-Name` consistency checks, and explicit `_meta` inspection coverage. It is not a claim of full Tasks, MCP Apps, subscriptions, MRTR, or final-spec conformance. See [docs/MCP_2026_07_28_RC_COMPATIBILITY.md](docs/MCP_2026_07_28_RC_COMPATIBILITY.md).

Deploy on Railway:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/mcpvanguard?referralCode=4AXmAG&utm_medium=integration&utm_source=template&utm_campaign=generic)

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

## Getting Started

Bootstrap a local workspace:

```bash
# 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.

| Layer | Purpose | Notes |
|---|---|---|
| **L0 - Preflight** | Normalize and annotate (URL decode, NFKC, strip zero-width, size/depth gates) | Always on |
| **Auth** | OAuth scope enforcement and destructive-tool policy | Role-aware |
| **L1 - Rules** | Deterministic blocking using signatures, recursive argument inspection, and safe boundaries | Fast path |
| **L1.5 - Camouflage** | Detect trust-signal camouflage and scorer manipulation | Profile-sensitive |
| **L2 - Semantic** | Optional intent scoring (can escalate/block, cannot downgrade deterministic blocks) | Async |
| **L3 - Behavioral** | Session and sequence-aware anomaly checks | Stateful |
| **Policy Composer** | Final verdict: ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK | Explainable |

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](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](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:

```text
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:

```bash
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](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](docs/RESEARCH_LAYERED_MCP_ENFORCEMENT.md).

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

| Backend | Env Vars | Notes |
|---|---|---|
| **Universal Custom** | `VANGUARD_SEMANTIC_CUSTOM_KEY`, related custom vars | Fast inference providers such as Groq or DeepSeek |
| **OpenAI** | `VANGUARD_OPENAI_API_KEY` | Default model: `gpt-4o-mini` |
| **Ollama** | `VANGUARD_OLLAMA_URL` | Local execution, no API key required |

For a more detailed local/offline setup guide, see [docs/LOCAL_SEMANTIC_MODE.md](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.2.x` is the current runtime hardening and MCP 2026-07-28 compatibility-baseline line
- 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](CHANGELOG.md) for the release history and [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for deployment details.

## Privacy

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

## Support

- Issues: [github.com/provnai/McpVanguard/issues](https://github.com/provnai/McpVanguard/issues)
- Contact: [contact@provnai.com](mailto:contact@provnai.com)
- Security: see [SECURITY.md](SECURITY.md)

## 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](LICENSE).

Built by [Provnai](https://provnai.com).