mcp-zero

关键词

API网关数据脱敏审计日志身份认证安全治理

使用说明（Markdown 格式）

  • 项目简介

    • mcp-zero 是一个自托管的网关，位于企业 AI 工具与 MCP 服务器之间，负责实现对请求的安全性、合规性和可观测性的管控。核心功能包括资源与工具的托管、工具调用以及 Prompt 模板的定义与渲染，并通过 JSON-RPC 风格的消息进行通信。网关还提供会话管理、能力声明以及多传输协议的支持，以为大语言模型应用提供可扩展、可审计的上下文服务。

  • 主要功能点

    • 身份与访问控制：通过 Okta 等身份提供者进行令牌校验和 OBO(Token Exchange) 支持，默认在策略启用时执行身份验证。
    • 政策治理：基于 YAML/JSON 策略文件实现默认拒绝、针对服务器/工具/用户/组的精细化访问控制，以及按顺序的策略匹配规则。
    • 数据脱敏与掩码：内嵌数据脱敏能力，支持对输入输出中的 PII/密钥等敏感信息进行就地掩码（PiI 掩码实现依赖 Presidio 等插件）。
    • 审计与观测：结构化日志，支持可选的审计事件输出、字段过滤、告警与追踪，并可与 Redis 等后端进行指标与审计数据聚合。
    • 插件体系：通过插件注册点扩展管道的前置/后置逻辑（如速率限制、指标、额外的掩码规则等）。
    • 传输协议：原生支持 Streamable HTTP、STDIO（本地子进程化工具）和 SSE（较早期/向后兼容方案，未来可替代）。对同一请求路径通过统一管道处理，确保治理、脱敏和审计在所有传输中保持一致。
    • 架构清晰：管道分为生命周期钩子（Pre/Post Validation、Pre/Post Masking、Pre Audit、On Error）以及可扩展的插件、代理、会话管理等组件，便于测试、扩展和维护。

  • 安装步骤（简要）

    • 获取代码并创建虚拟环境
    • 安装依赖并进入开发环境
    • 根据需要准备 policy.yaml 策略文件（包含身份、服务器、工具、掩码、插件等配置）
    • 运行网关：使用 python -m mcp_zero 启动
    • 如需开发调试，可参考 README 中的快速启动与本地测试指引

  • 服务器配置（MCP 客户端使用的配置示例说明）

    • MCP 服务器配置用于 MCP 客户端与网关对接，配置项以 JSON 结构描述，包含以下字段（说明用途，实际使用时以 JSON 文件形式提供给客户端）：
      • server name：服务器/目标 MCP 实例的唯一名称，例如 weather、db 等
      • command：用于启动该 MCP 服务器的命令（仅对 STDIO 传输有意义，HTTP/SSE 传输直接给出远程服务器 URL）
      • args：启动命令的参数数组，例如 ["--mode", "echo"]，用于 STDIO 服务器
      • transport：传输类型，可以是 http（HTTP/Streamable）、stdio、sse 等
      • url：若为 HTTP/SSE 服务器，目标的完整 URL，如 https://mcp-server.internal
      • allow_insecure：是否允许不使用 https（仅用于开发/测试环境）
      • token_exchange、target_audience、required_scopes：用于 OBO 场景的设置
    • 说明：以上字段用于 MCP 客户端在启动时将目标 MCP 服务器纳入连接/代理范围。MCP 客户端至少需要提供 server 名称、启动命令以及参数来创建与网关的通讯通道（具体 JSON 结构请按业务场景提供给客户端，网关端不需要客户端代码本身）。

  • 基本使用方法

    • 启动前准备
      • 放置策略配置 policy.yaml，或使用环境变量与策略组合配置
      • 如需转发到上游 MCP 服务器，请确保 Upstream URL、策略、身份等配置正确
    • 启动网关
      • 在项目根目录执行命令启动网关，使网关对外提供 API/调用能力
      • 启动后网关会输出启动信息并监听配置的宿主与端口
    • 使用网关
      • 客户端通过网关对 MCP 服务器进行资源读取、工具调用、Prompts 获取等操作
      • 通过策略文件可以控制谁可以访问哪一个 MCP 服务器及其工具
    • 运维与扩展
      • 策略以 YAML/JSON 文件形式定义，支持默认拒绝、服务器/工具/用户/组的组合规则
      • 可以通过插件扩展管线行为（如掩码、速率限制、指标等）
      • 日志格式可通过配置切换为 JSONL 或文本格式，便于在不同环境下收集和分析

  • 运行示例与要点

    • 需要策略文件来开启身份验证、治理与数据保护等能力；在无策略文件时网关会以更低的严格性运行（开发/调试模式），请避免在生产环境开启不安全模式。
    • 支持多传输协议，一套策略与同一策略管道会应用于不同传输场景，确保一致性和安全性。
    • 与 MCP 服务器的对接，网关负责会话与上下文的创建、工具调用路由、以及对请求/响应的响应式治理。

  • 备注

    • 本实现包含大量单元测试、集成测试和示例，覆盖了身份、治理、掩码、审计、工具路由、会话复用、错误处理等核心场景，旨在提供一个可部署、可扩展的 MCP 服务器网关解决方案。

服务器信息

访问项目