Mcpvanguard

McpVanguard

面向 MCP Agent 和工具服务的安全网关。

McpVanguard 位于 AI Agent 与 MCP 服务之间，可实时规范化并检查工具流量，并在敏感调用到达底层工具之前实施分层策略。它可以在本地作为 stdio 服务的前置网关运行，也可以通过 SSE 和 Streamable HTTP 作为托管网关运行。

产品配置——monitor、balanced、strict——让你能够逐步采用：先从仅审计的发现模式开始，再转为均衡执行，最后为生产敏感系统启用严格加固。

现有 MCP 服务无需重写。

开发者为何使用它

MCP 工作流功能强大，但一旦工具接触文件、Shell 或网络，防护措施就很重要。

McpVanguard 增加了运行时执行边界，让你能够：

• 让正常的工具流量顺畅通过
• 在执行前拦截不安全的调用
• 通过审计日志检查并调试策略决策
• 无需重写现有 MCP 服务即可逐步采用

功能

McpVanguard 面向希望在 MCP 工作流中明确实施策略的开发者和平台团队。

• 在执行前检查 MCP 工具调用
• 拦截不安全的文件系统、命令和网络模式
• 为敏感工具实施身份验证、角色和作用域要求
• 在服务器元数据到达下游模型前进行检查
• 持续跟踪重复出现的可疑行为
• 为被拦截、发出警告和允许通过的流量生成审计与遥测信号

快速验证场景

针对同一个 MCP 服务，分别通过原始路径和防护路径执行测试。

• 安全的文件读取在两条路径中均可通过
• 路径遍历尝试会在防护路径中被拦截
• 有风险的网络请求会在防护路径中被拦截
• 元数据投毒尝试会在暴露给模型前被过滤或拦截

这能快速确认策略已启用，且执行行为符合预期。

在 2.2.2 中，如需进行无需凭据的合成检查，请运行 python -m core.demo_verify。 它会针对捆绑的内存上游检查一次无害读取和两次被拦截的调用，并使用明确的仅供演示的安全区域。有关安装、预期输出以及单独的真实工作流评估，请参阅 自助评估。更早的版本不包含此验证器。

使用场景

• 无需重写，即可保护本地桌面或开发者计算机上的 MCP 服务
• 在共享 MCP 服务前添加托管网关
• 比较高风险工具工作流在原始路径与防护路径中的行为
• 为高风险文件、Shell 和网络访问工具添加策略执行

快速开始

安装软件包：

pip install mcp-vanguard

可选的部署扩展：

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

包装本地 stdio MCP 服务：

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

对于公开部署或非环回托管部署，strict 配置在未配置传输身份验证（使用较长的随机 VANGUARD_API_KEY 或 OAuth/JWKS 设置）时会拒绝启动。balanced 仍适用于演示和分阶段推出，但在未进行身份验证就暴露服务时会发出醒目警告。

托管部署还可以选择启用按会话预算，限制工具调用频率、风险决策和重复的拦截尝试。这些预算可在分层策略路径周围充当断路器，同时不改变本地 OSS 用法的默认设置。

如果你运营托管模板或共享网关，请设置 VANGUARD_ALLOWED_SERVER_COMMANDS，以限制 McpVanguard 可以启动的上游 MCP 服务可执行文件。

对于通过 Anthropic MCP 隧道访问的私有网络 MCP 服务，建议采用以下部署位置：隧道 -> McpVanguard -> 私有 MCP 服务。隧道可减少网络暴露。McpVanguard 则负责执行边界控制。

McpVanguard 在 2.2.x 系列中提供了文档化的 MCP 2026-07-28 兼容性基线。该基线包括选择启用的无状态传输配置、增量式 Mcp-Method / Mcp-Name 一致性检查，以及明确覆盖 _meta 检查。它并不表示完全符合 Tasks、MCP Apps、订阅、MRTR 或最终规范。请参阅 docs/MCP_2026_07_28_RC_COMPATIBILITY.md。

在 Railway 上部署：

需要完整的部署指南？请参阅 docs/DEPLOYMENT.md、docs/railway-deployment-guide.md 和 docs/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

工作原理

McpVanguard 使用五个核心检查层：L0 至 L3，以及 L1.5；这些检查层外还设有身份验证策略和最终策略合成器。每次工具调用在到达上游 MCP 服务之前都会经过检查。

层	用途	说明
L0 - 预检	规范化并添加注释（URL 解码、NFKC、移除零宽字符、大小/深度门限）	始终启用
身份验证	OAuth 作用域强制执行和破坏性工具策略	感知角色
L1 - 规则	使用特征签名、递归参数检查和安全边界进行确定性拦截	快速路径
L1.5 - 伪装检测	检测信任信号伪装和评分器操纵	取决于配置
L2 - 语义	可选的意图评分（可以升级处置或拦截，但不能降级确定性拦截）	异步
L3 - 行为	感知会话和序列的异常检查	有状态
策略合成器	最终判定：ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK	可解释

五个核心检查层分别是 L0、L1、L1.5、L2 和 L3。身份验证策略和最终策略合成器围绕这条核心路径运作。

如果请求被拦截，Agent 会收到标准 JSON-RPC 错误，上游服务则完全不会收到该调用。审计日志会记录主要原因和所有辅助发现。

安全区采用确定性的路径边界检查，不能替代操作系统沙箱或容器隔离。它们会递归检查标准路径类参数名称和常见自定义路径类参数名称，但生产部署仍应根据 MCP 工具获准访问的实际架构和目录，调整 rules/safe_zones.yaml。请参阅 docs/SAFE_ZONES.md。

对于运维人员的故障排查，JSON 审计日志包含便于 SIEM 处理的判定字段，以及结构化的 policy_explanation 数据，其中包含主要检查层、规则类别、配置影响、上游调用状态和调整提示。请参阅 docs/BLOCK_DECISIONS.md。

部署模式

McpVanguard 最适合被视为 MCP 工作流的安全网关。

• 本地优先模式：在开发者的计算机上包装 stdio MCP 服务
• 网关模式：为托管或共享部署提供经过加固的 SSE 和 Streamable HTTP 端点

典型路径：

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

当前功能

• 经过加固的 SSE 和 Streamable HTTP 传输路径，支持请求速率、并发、会话绑定和会话数量控制
• 检查 initialize 和 tools/list 中的元数据投毒
• 针对使用 bearer 身份验证的部署，支持 JWT、JWKS、颁发者、受众、声明和范围检查
• 验证服务完整性和能力漂移
• 实现跨服务隔离和 server_id 可追踪性
• 验证签名清单、来源信息、分离签名和 Sigstore 支持的信任
• 提供基准测试和分类工具，用于衡量覆盖范围
• 可选生成 receipt_v1 JSONL，以便导出/签名后使用 mcp-receipt 离线验证运行时证据

基准测试

McpVanguard 包含用于对抗性和良性 MCP 流量的打包基准测试语料库。部署前可使用它们比较不同配置：

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

基准测试结果用于发布和调优，不代表能够普遍检测或实现零误报。有关结果解读的指南和推荐的发布门槛，请参阅 docs/BENCHMARKS.md。

有关分层设计背后的公开研究说明，请参阅 Why MCP Security Needs Layered Runtime Enforcement。

身份验证模式

McpVanguard 采用本地优先设计，并在需要时支持更强的托管网关控制。

• stdio 模式：无需网络身份验证
• SSE / Streamable HTTP 模式：支持 VANGUARD_API_KEY
• Bearer / JWT 模式：支持经过验证的 JWT/JWKS 校验、颁发者/受众/声明/范围检查，以及托管网关路径上的身份验证感知策略
• 严格托管模式：未启用传输身份验证时拒绝公开绑定，将 bearer 声明不匹配的处理方式设为 block，并在配置允许列表时要求提供 Origin

管理平面

原生 vanguard_* 管理工具默认处于禁用状态。如果启用这些工具，也应选择明确的管理平面模式：

• disabled：不公开原生管理工具
• same_session_dev：仅限本地/开发环境；只读工具和变更工具共用受治理的 MCP 会话，启动时会打印警告
• operator_only：可显示只读工具，但变更工具需要管理员角色或 vanguard:admin / scope:admin 范围

在生产环境中，除非调用方是经过身份验证的操作员，否则不要在常规受治理的 Agent 会话中使用变更管理工具。管理操作会经过审计，且被拒绝的操作/变更尝试会显示为风险。

语义后端选项

可选的第 2 层语义评分器支持多个后端。优先使用第一个已配置的后端。

后端	环境变量	说明
通用自定义	VANGUARD_SEMANTIC_CUSTOM_KEY、相关自定义变量	Groq 或 DeepSeek 等快速推理服务提供商
OpenAI	VANGUARD_OPENAI_API_KEY	默认模型：gpt-4o-mini
Ollama	VANGUARD_OLLAMA_URL	本地执行，无需 API 密钥

有关更详细的本地/离线设置指南，请参阅 docs/LOCAL_SEMANTIC_MODE.md。

完整性与信任

McpVanguard 包含：

• 上游服务的签名清单
• 能力基线和漂移检查
• 来源信息验证钩子
• 分离的制品签名验证
• 带身份和颁发者约束的 Sigstore bundle 验证

应将其描述为服务完整性、基线验证和信任验证，而非完整的 SBOM 平台。

项目状态

• 2.2.x 是当前的运行时加固与 MCP 2026-07-28 兼容性基线版本线
• 分层强制执行路径（L0 -> L1 -> L1.5 -> L2 -> L3 -> Policy Composer）已实现，并通过本地与 CI 验证
• 产品配置（monitor / balanced / strict）是此版本线支持的部署模式
• 更广泛的仅供研究使用的功能（GPU 证明、硬件根信任溯源、零误报声明）有意不纳入核心 OSS 版本范围

请参阅 CHANGELOG.md 了解发布历史，并参阅 docs/DEPLOYMENT.md 了解部署详情。

隐私

McpVanguard 专注于本地检查和网关强制执行。请参阅 PRIVACY.md，了解当前的隐私和数据处理详情。

支持

• 问题反馈：github.com/provnai/McpVanguard/issues
• 联系方式：[email protected]
• 安全：请参阅 SECURITY.md

常见问题

这会取代我的 MCP 服务吗？
不会。McpVanguard 位于现有 MCP 服务之前，并在调用到达该服务前强制执行策略。

我需要重写工具或 Agent 代码吗？
通常不需要。大多数配置都是从通过 McpVanguard 路由一个工作流开始的。

这只适用于托管配置吗？
不适用。它支持本地优先的 stdio 封装和托管网关模式。

许可证

MIT 许可证 - 请参阅 LICENSE。

由 Provnai 构建。