{"id":46123475,"url":"https://github.com/provnai/mcpvanguard","last_synced_at":"2026-06-08T12:00:44.459Z","repository":{"id":341383567,"uuid":"1169912272","full_name":"provnai/McpVanguard","owner":"provnai","description":"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.","archived":false,"fork":false,"pushed_at":"2026-05-31T23:47:42.000Z","size":2075,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-01T01:19:31.715Z","etag":null,"topics":["agentic-ai","ai-security","anthropic-mcp","claude","cybersecurity","firewall","mcp","model-context-protocol","python","railway","security-proxy","sse"],"latest_commit_sha":null,"homepage":"https://www.provnai.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/provnai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T12:20:37.000Z","updated_at":"2026-05-31T23:37:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/provnai/McpVanguard","commit_stats":null,"previous_names":["provnai/mcpvanguard"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/provnai/McpVanguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provnai%2FMcpVanguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provnai%2FMcpVanguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provnai%2FMcpVanguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provnai%2FMcpVanguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/provnai","download_url":"https://codeload.github.com/provnai/McpVanguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provnai%2FMcpVanguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34061123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-security","anthropic-mcp","claude","cybersecurity","firewall","mcp","model-context-protocol","python","railway","security-proxy","sse"],"created_at":"2026-03-02T01:06:39.640Z","updated_at":"2026-06-08T12:00:44.453Z","avatar_url":"https://github.com/provnai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# McpVanguard\n\nSecurity gateway for MCP agents and tool servers.\n\nMcpVanguard 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.\n\n**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.\n\nExisting MCP servers do not need to be rewritten.\n\n[![Tests](https://github.com/provnai/McpVanguard/actions/workflows/test.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/test.yml)\n[![CodeQL](https://github.com/provnai/McpVanguard/actions/workflows/codeql.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/codeql.yml)\n[![Security Audit](https://github.com/provnai/McpVanguard/actions/workflows/security-audit.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/security-audit.yml)\n[![SBOM](https://github.com/provnai/McpVanguard/actions/workflows/sbom.yml/badge.svg)](https://github.com/provnai/McpVanguard/actions/workflows/sbom.yml)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-vanguard.svg?color=blue)](https://pypi.org/project/mcp-vanguard/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)\n\n## Why Developers Use It\n\nMCP workflows are powerful, but once tools touch files, shells, or networks, guardrails matter.\n\nMcpVanguard adds a runtime enforcement boundary so you can:\n\n- keep normal tool traffic flowing\n- block unsafe calls before execution\n- inspect and debug policy decisions with audit logs\n- adopt incrementally without rewriting existing MCP servers\n\n## What It Does\n\nMcpVanguard is for developers and platform teams who want explicit policy enforcement around MCP workflows.\n\n- inspect MCP tool calls before execution\n- block unsafe filesystem, command, and network patterns\n- enforce auth, role, and scope requirements for sensitive tools\n- inspect server metadata before it reaches downstream models\n- track repeated suspicious behavior over time\n- emit audit and telemetry signals for blocked, warned, and allowed traffic\n\n## Quick Verification Scenario\n\nUse one raw path and one guarded path against the same MCP server.\n\n- safe file read passes in both paths\n- path traversal attempt is blocked in the guarded path\n- risky network request is blocked in the guarded path\n- metadata poisoning attempts are filtered or blocked before model exposure\n\nThis gives you a fast signal that policy is active and enforcement behaves as expected.\n\n## Use Cases\n\n- protect local desktop or developer-machine MCP servers without rewriting them\n- add a hosted gateway in front of shared MCP servers\n- compare raw versus guarded behavior for risky tool workflows\n- add policy enforcement to high-risk file, shell, and network-access tools\n\n## Quickstart\n\nInstall the package:\n\n```bash\npip install mcp-vanguard\n```\n\nWrap a local stdio MCP server:\n\n```bash\n# Balanced profile (default OSS/developer behavior)\nvanguard start --profile balanced --server \"npx @modelcontextprotocol/server-filesystem .\"\n\n# Strict profile (production hardening)\nvanguard start --profile strict --server \"npx @modelcontextprotocol/server-filesystem .\"\n```\n\nRun as a hosted gateway:\n\n```bash\nexport VANGUARD_API_KEY=\"your-secret-key\"\nvanguard sse --profile balanced --server \"npx @modelcontextprotocol/server-filesystem .\"\n```\n\nDeploy on Railway:\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/mcpvanguard?referralCode=4AXmAG\u0026utm_medium=integration\u0026utm_source=template\u0026utm_campaign=generic)\n\nNeed a complete deployment walkthrough? See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) and [docs/railway-deployment-guide.md](docs/railway-deployment-guide.md).\n\n## Getting Started\n\nBootstrap a local workspace:\n\n```bash\n# 1. Initialize safe zones and .env template\nvanguard init\n\n# 2. Optionally update Claude Desktop server entries\nvanguard configure-claude\n\n# 3. Launch the local security dashboard\nvanguard ui --port 4040\n\n# 4. Run compliance and readiness checks\nvanguard audit-compliance\n```\n\n## How It Works\n\nMcpVanguard 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.\n\n| Layer | Purpose | Notes |\n|---|---|---|\n| **L0 - Preflight** | Normalize and annotate (URL decode, NFKC, strip zero-width, size/depth gates) | Always on |\n| **Auth** | OAuth scope enforcement and destructive-tool policy | Role-aware |\n| **L1 - Rules** | Deterministic blocking using signatures, recursive argument inspection, and safe boundaries | Fast path |\n| **L1.5 - Camouflage** | Detect trust-signal camouflage and scorer manipulation | Profile-sensitive |\n| **L2 - Semantic** | Optional intent scoring (can escalate/block, cannot downgrade deterministic blocks) | Async |\n| **L3 - Behavioral** | Session and sequence-aware anomaly checks | Stateful |\n| **Policy Composer** | Final verdict: ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK | Explainable |\n\nThe five core inspection layers are `L0`, `L1`, `L1.5`, `L2`, and `L3`. Auth policy and the final policy composer sit around that core path.\n\nIf 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.\n\nSafe 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).\n\n## Deployment Model\n\nMcpVanguard is best understood as a security gateway for MCP workflows.\n\n- **Local-first mode**: wraps stdio MCP servers on a developer machine\n- **Gateway mode**: exposes hardened SSE and Streamable HTTP endpoints for hosted or shared deployments\n\nTypical path:\n\n```text\nAI Agent -\u003e McpVanguard -\u003e MCP Server -\u003e Tools / Files / External Systems\n```\n\n## Current Capabilities\n\n- hardened SSE and Streamable HTTP transport paths with request rate, concurrency, session-binding, and session-count controls\n- metadata poisoning inspection on `initialize` and `tools/list`\n- JWT, JWKS, issuer, audience, claim, and scope checks for bearer-auth deployments\n- server integrity and capability drift verification\n- cross-server isolation and `server_id` traceability\n- signed-manifest, provenance, detached signature, and Sigstore-backed trust verification\n- benchmark and taxonomy tooling for measurable coverage\n- optional `receipt_v1` JSONL emission for offline-verifiable runtime evidence with `mcp-receipt` after export/signing\n\n## Benchmarks\n\nMcpVanguard includes packaged benchmark corpora for adversarial and benign MCP traffic. Use them to compare profiles before deployment:\n\n```bash\nvanguard benchmark-run --profile monitor\nvanguard benchmark-run --profile balanced\nvanguard benchmark-run --profile strict\n```\n\nThe 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.\n\nFor the public research note behind the layered design, see [Why MCP Security Needs Layered Runtime Enforcement](docs/RESEARCH_LAYERED_MCP_ENFORCEMENT.md).\n\n## Authentication Modes\n\nMcpVanguard is local-first and supports stronger hosted-gateway controls when needed.\n\n- **stdio mode**: no network auth required\n- **SSE / Streamable HTTP mode**: supports `VANGUARD_API_KEY`\n- **Bearer / JWT mode**: supports verified JWT/JWKS validation, issuer/audience/claim/scope checks, and auth-aware policy on the hosted gateway path\n\n## Semantic Backend Options\n\nThe optional Layer 2 semantic scorer supports multiple backends. The first configured backend wins.\n\n| Backend | Env Vars | Notes |\n|---|---|---|\n| **Universal Custom** | `VANGUARD_SEMANTIC_CUSTOM_KEY`, related custom vars | Fast inference providers such as Groq or DeepSeek |\n| **OpenAI** | `VANGUARD_OPENAI_API_KEY` | Default model: `gpt-4o-mini` |\n| **Ollama** | `VANGUARD_OLLAMA_URL` | Local execution, no API key required |\n\nFor a more detailed local/offline setup guide, see [docs/LOCAL_SEMANTIC_MODE.md](docs/LOCAL_SEMANTIC_MODE.md).\n\n## Integrity and Trust\n\nMcpVanguard includes:\n\n- signed upstream server manifests\n- capability baselines and drift checks\n- provenance verification hooks\n- detached artifact-signature verification\n- Sigstore bundle verification with identity and issuer constraints\n\nThis should be described as server integrity, baseline verification, and trust verification, not as a full SBOM platform.\n\n## Project Status\n\n- `2.1.1` is the current runtime hardening patch for the layered enforcement release line\n- layered enforcement path (`L0 -\u003e L1 -\u003e L1.5 -\u003e L2 -\u003e L3 -\u003e Policy Composer`) is implemented and covered by local and CI verification\n- product profiles (`monitor` / `balanced` / `strict`) are the supported deployment modes for this release line\n- broader research-only features (GPU attestation, hardware-rooted provenance, zero-FP claims) are intentionally outside the core OSS release scope\n\nSee [CHANGELOG.md](CHANGELOG.md) for the release history and [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for deployment details.\n\n## Privacy\n\nMcpVanguard focuses on local inspection and gateway enforcement. See [PRIVACY.md](PRIVACY.md) for current privacy and data-handling details.\n\n## Support\n\n- Issues: [github.com/provnai/McpVanguard/issues](https://github.com/provnai/McpVanguard/issues)\n- Contact: [contact@provnai.com](mailto:contact@provnai.com)\n- Security: see [SECURITY.md](SECURITY.md)\n\n## FAQ\n\n**Does this replace my MCP server?**  \nNo. McpVanguard sits in front of your existing MCP server and enforces policy before calls reach it.\n\n**Do I need to rewrite tools or agent code?**  \nUsually no. Most setups start by routing one workflow through McpVanguard.\n\n**Is this only for hosted setups?**  \nNo. It supports local-first stdio wrapping and hosted gateway modes.\n\n## License\n\nMIT License - see [LICENSE](LICENSE).\n\nBuilt by [Provnai](https://provnai.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovnai%2Fmcpvanguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprovnai%2Fmcpvanguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovnai%2Fmcpvanguard/lists"}