使用说明

mcp零点

位于企业人工智能工具和MCP服务器之间的开源网关，用于执行合规团队在批准之前所需的安全控制主控程序采用。

没有它，人工智能工具可以调用任何没有访问控制、审计跟踪和数据保护的MCP服务器，这在受监管的环境中是不可能的。mcp-zero添加了缺失的治理层：它验证用户身份，检查策略规则，屏蔽敏感数据，并在请求到达下游服务器之前记录每个操作——所有这些都是内联的。

将其部署为单个Python服务。使用YAML策略文件对其进行配置。无需安装代理，无SaaS依赖，无供应商锁定。

Enterprise AI Tool ──► MCP Gateway ──► MCP Servers
                         │
              ┌──────────┴──────────┐
              │   Hook Pipeline     │
              │                     │
              │   Identity  (core)  │
              │   Governance (core) │
              │   ◇ Plugins  (ext)  │
              │   Audit     (core)  │
              └─────────────────────┘

特性

身份 --Okta OAuth2 JWT验证，带有可配置的声明映射(user_id, email, groups)
治理 --具有默认拒绝规则的YAML策略文件，适用于服务器、工具、用户和组
数据保护 --通过Microsoft Presidio对输入和输出进行内联PII和秘密屏蔽
审计 --具有用户归因、关联ID和策略决策的结构化日志
运输 --同一策略管道下的流式HTTP（主）、传统入站SSE（可选）和上游HTTP/SSE/stdio服务器连接
管道 --基于钩子的请求生命周期，具有有序执行和短路支持
插件 --基于入口点的插件架构，用于使用自定义钩子（掩码、速率限制、度量等）扩展管道

快速开始

先决条件

Python 3.12+
Okta租户（用于身份验证）

安全通知

重要：网关设计有故障关闭默认值，但需要适当的配置来实施安全性：

强烈建议使用策略文件：设置 MCP_POLICY_FILE 以启用治理和插件配置。
默认情况下关闭启动失败：如果既没有配置身份也没有配置策略文件，网关将以代码78退出。
发展只能绕过:
- MCP_RELAX_STARTUP_CHECKS=true 允许在没有安全控制的情况下启动。
- MCP_SKIP_TLS_VALIDATION=true 允许非HTTPS身份/服务器/OBO URL。
严格的生产硬化: MCP_STRICT_SECURITY=true 需要身份和治理都是积极的。
掩盖依赖关系：Presidio口罩要求 presidio-analyzer 和 presidio-anonymizer （包含在默认安装中）。

已知限制 （参见安全审查更广泛的分析）：

遗留/开发模式仍可通过以下方式有意启用 MCP_RELAX_STARTUP_CHECKS=true 和 MCP_SKIP_TLS_VALIDATION=true这些不得用于生产。
OBO令牌交换需要显式的环境变量(OKTA_TOKEN_ENDPOINT, OKTA_CLIENT_ID, OKTA_CLIENT_SECRET)以及每台服务器的策略配置。
入站SSE支持仍然可用，但已弃用；禁用 MCP_SSE_ENABLED=false 如果不需要。

切勿在宽松的启动检查或禁用TLS验证的情况下运行生产部署。

安装

# Clone and install
git clone https://github.com/abwaters/mcp-zero.git
cd mcp-zero
python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

pip install -e ".[dev]"

在Windows上，提供了便利脚本：

scripts\install.bat    # Creates venv and installs everything

配置

创建策略文件（例如。， policy.yaml):

version: 1
default: deny

identity:
  provider: okta
  issuer: https://your-org.okta.com
  audience: your-app-audience

servers:
  - name: my-mcp-server
    transport: http
    url: https://mcp-server.internal.corp/mcp

policies:
  - id: allow-devs
    description: Allow developers to use read tools
    effect: allow
    subjects:
      groups:
        - developers
    mcp_servers:
      - name: my-mcp-server
        tools:
          - read_*
          - list_*

masking:
  presidio:
    enabled: true
    entities:
      - PERSON
      - EMAIL_ADDRESS
      - PHONE_NUMBER
      - CREDIT_CARD
      - API_KEY
      - PASSWORD

跑

# Set the policy file path
export MCP_POLICY_FILE=policy.yaml

# Start the gateway
python -m mcp_zero
# or
mcp-zero

或者使用环境变量进行简单设置：

export MCP_UPSTREAM_URL=http://localhost:9000
export OKTA_ISSUER=https://your-org.okta.com
export OKTA_AUDIENCE=your-app-audience
python -m mcp_zero

网关启动 0.0.0.0:8080 默认情况下（可通过配置 MCP_HOST 和 MCP_PORT).

配置

环境变量

变量	描述	默认值
`MCP_POLICY_FILE`	YAML/JSON策略文件的路径	（无）
`MCP_UPSTREAM_URL`	单个上游MCP服务器URL（传统回退）	（无）
`MCP_HOST`	主机绑定网关	`0.0.0.0`
`MCP_PORT`	绑定网关的端口	`8080`
`MCP_RELAX_STARTUP_CHECKS`	允许在没有所需安全控制的情况下启动（仅限开发/测试）	`false`
`MCP_SKIP_TLS_VALIDATION`	允许 `http://` 发行者/服务器/OBO URL（仅限开发/测试）	`false`
`MCP_STRICT_SECURITY`	启动时需要身份和治理	`false`
`MCP_SSE_ENABLED`	启用已弃用的入站SSE端点(`/mcp/sse*`)	`true`
`LOG_LEVEL`	日志记录级别（调试、信息、警告、错误）	`INFO`
`LOG_FORMAT`	日志输出格式(`json` 或 `text`)	`json`
`OKTA_ISSUER`	Okta令牌发行者URL（如果没有策略文件，则回退）	（无）
`OKTA_AUDIENCE`	预期的JWT受众声明（如果没有策略文件，则回退）	（无）
`OKTA_TOKEN_ENDPOINT`	Okta代币交换端点（用于OBO）	（无）
`OKTA_CLIENT_ID`	网关客户端ID（用于OBO）	（无）
`OKTA_CLIENT_SECRET`	网关客户端机密（用于OBO）	（无）
`ANALYTICS_REDIS_URL`	Redis连接URL（设置后启用分析）	（无）
`ANALYTICS_REDIS_CLUSTER`	使用Redis集群客户端	`false`
`ANALYTICS_REDIS_PASSWORD`	Redis身份验证密码	（无）
`ANALYTICS_ENVIRONMENT`	分析密钥命名空间（例如。 `production`)	`default`
`ANALYTICS_GATEWAY_ID`	唯一网关实例ID	（自动生成）
`ANALYTICS_KEY_PREFIX`	用于分析的Redis密钥前缀	`mcpgw`
`ANALYTICS_RETENTION_SECONDS`	分析键的TTL（秒）	`3600`
`MCP_CORS_ORIGINS`	逗号分隔的允许CORS源（设置时启用CORS）	（无）
`MCP_CORS_ALLOW_CREDENTIALS`	允许CORS请求中的凭据	`false`
`MCP_CORS_MAX_AGE`	飞行前缓存持续时间（秒）	`600`

当 MCP_POLICY_FILE 设置后，其标识部分优先于 OKTA_* env变量。CORS和分析环境变量覆盖策略值。

策略文件

看 docs/enterprise_mcp_gateway_policy_schema_example.md 查看完整的注释示例。

工作示例可在 policies/ 目录：

文件	描述
`policies/everything.yaml`	stdio传输 `@modelcontextprotocol/server-everything`
`policies/filesystem.yaml`	stdio传输 `@modelcontextprotocol/server-filesystem`
`policies/filesystem-redacted.yaml`	带有Presidio屏蔽插件的文件系统服务器
`policies/time.yaml`	stdio传输 `@modelcontextprotocol/server-time`
`policies/all.yaml`	多台stdio服务器组合在一起
`policies/remote-github.yaml`	通过流式HTTP远程GitHub MCP服务器
`policies/remote-github-readonly.yaml`	带有显式只读工具allowlist的GitHub服务器

关键概念：

version：必须是 1
default: deny （推荐）或 allow
servers：下游MCP服务器定义（HTTP或stdio）
**policies**自上而下评估有序规则；显式拒绝覆盖允许
cors：基于浏览器的客户端的CORS配置（默认禁用）
masking：Presidio实体检测配置（旧版--请参见 plugins 在......下面
plugins：可扩展管道挂钩的插件声明（掩码、速率限制等）

CORS配置

添加一个 cors 策略文件的部分，以允许基于浏览器的MCP客户端：

cors:
  allow_origins:
    - https://web-ide.corp.com
    - https://dashboard.corp.com
  allow_methods: ["GET", "POST", "OPTIONS"]
  allow_headers: ["Authorization", "Content-Type"]
  allow_credentials: false
  max_age: 600

默认情况下，CORS被禁用（失败关闭）。仅 allow_origins 是必需的；所有其他字段都有安全默认值。环境变量(MCP_CORS_ORIGINS, MCP_CORS_ALLOW_CREDENTIALS, MCP_CORS_MAX_AGE)覆盖策略文件值。

服务器类型

HTTP服务器 --通过流式HTTP访问的远程MCP服务器：

servers:
  - name: remote-api
    transport: http
    url: https://mcp-server.corp/mcp

SSE服务器 --通过SSE的远程MCP服务器：

servers:
  - name: legacy-sse-server
    transport: sse
    url: https://mcp-server.corp/sse

stdio服务器 --由网关生成和管理的本地进程（在策略文件中配置）：

servers:
  - name: local-filesystem
    transport: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /workspace
    env:
      NODE_ENV: production

发展

# Run tests
python -m pytest                          # all tests
python -m pytest tests/masking/ -v        # specific module
python -m pytest tests/test_main.py -v    # specific file

# Lint and format
ruff check src tests
ruff format src tests

# Run the gateway
python -m mcp_zero

在Windows上，使用提供的脚本：

scripts\test.bat           # Run tests
scripts\lint.bat           # Lint
scripts\format.bat         # Format
scripts\run.bat            # Run gateway

项目结构

src/mcp_zero/
├── main.py              # Application entry point
├── plugin.py            # Plugin protocol and base class
├── plugin_manager.py    # Plugin discovery and lifecycle
├── context.py           # RequestContext, HookContext, UserIdentity
├── identity/            # Okta JWT validation, OBO token exchange
├── governance/          # Policy loading, evaluation, enforcement
├── masking/             # Masking engine interface and hook
├── plugins/             # Built-in plugins (Presidio masking, GitHub repo filter)
├── pipeline/            # Hook lifecycle, registry, execution
├── proxy/               # Starlette app, server management, tool routing
├── analytics/           # Optional Redis-based analytics
└── transport/           # HTTP, SSE, and stdio MCP transport clients

建筑

网关使用基于钩子的管道和插件系统。核心挂钩处理身份、治理和审计。其他一切——屏蔽、速率限制、指标——都是从策略文件加载的插件。

芯钩（始终存在）：

优先级	挂钩	阶段	目的
10	IdentityHook	PRE_VALIDATION	验证JWT，解析用户身份
50	GovernanceHook	PostT_VALIDATION	评估策略规则，允许或拒绝
145	AnalyticsHock	PRE_AUDIT	将指标记录到Redis（配置时）
150	AuditHook	PRE_AUDIT	发出具有完整请求上下文的结构化日志

插件挂钩 （从策略文件加载 plugins: 部分）：

优先级范围	插槽	示例
20–49	预治理	速率限制、请求验证
70-99	后治理	蒙面（Presidio 75岁），转型
100–139	概述	指标、缓存、自定义挂钩

钩子按优先级顺序执行。任何钩子都可能使管道短路（例如，治理拒绝会立即停止处理）。

插件系统：插件是通过Python入口点发现的(mcp_zero.plugins 组），在策略文件中配置，并在启动时注册到管道中。看 docs/plugin-architecture-design.md 了解详情。

文档

文档	描述
`docs/quickstart.md`	使用Docker Compose和本地路径逐步快速入门
`docs/prd.md`	产品要求和验收标准
`docs/enterprise_mcp_gateway_architecture_diagram.md`	带组件图的逻辑架构
`docs/enterprise_mcp_gateway_implementation_plan_epics.md`	分阶段实施计划
`docs/enterprise_mcp_gateway_policy_schema_example.md`	完整注释策略文件示例
`docs/enterprise_mcp_gateway_security_compliance_positioning.md`	安全控制和合规性协调
`docs/enterprise_mcp_gateway_threat_model_canvas.md`	威胁模型和缓解措施
`docs/okta_obo_for_an_enterprise_mcp_gateway.md`	OBO代币交易所深度跳水
`docs/enterprise_mcp_gateway_leadership_explainer.md`	非技术利益相关者概述
`docs/configuration-architecture.md`	配置加载、环境变量、策略架构、优先级规则
`docs/cors-configuration.md`	基于浏览器的MCP客户端的CORS设置
`docs/plugins/`	插件快速入门和每个插件的文档

比较

mcp zero与其他mcp网关相比如何：

能力	mcp为零	代理网关	MintMCP	微软MCP网关	Lasso MCP网关
许可证	✅ MIT 的✅ Apache 2.0（Linux Foundation）❌ 商业SaaS✅ MIT 的✅ MIT 的
语言	Python	Rust/Go	专有	。NET/C#	Python
运输	✅ 流式HTTP、stdio	✅ 流式HTTP、SSE、stdio	✅ HTTP、SSE、stdio	仅限流式HTTP	仅限stdio
认证	✅ Okta OAuth2 JWT	✅ JWT、API密钥、OAuth（Auth0、Keycap）、MCP身份验证规范	✅ OAuth 2.0、SAML、SSO（Okta、Azure AD）	Azure Entra ID/Outh2.0	❌ 无内置
治理	✅ YAML/JSON策略文件、默认拒绝、服务器/工具/用户/组规则	✅ RBAC、Cedar策略引擎、速率限制	RBAC/ABAC、虚拟MCP基于角色的端点	RBAC通过Entra ID角色	❌ 仅基于插件
数据保护	✅ 输入和输出上的内联Presidio屏蔽	❌ 无内置	✅ PII编辑、机密扫描、内容过滤	❌ 无内置	Presidio PII+正则表达式秘密掩码
审计	✅ 带有用户归因、关联ID和策略决策的结构化日志	✅ OpenTetry指标、日志、分布式跟踪	✅ 不可变的审计跟踪、仪表板、SOC 2	Azure应用程序洞察	基于SQLite的工具调用跟踪
部署	✅ 自托管，轻量级	✅ 自托管（二进制、Docker、Kubernetes）	托管云SaaS（可用自托管）	在Kubernetes上自托管（AKS）	本地代理进程
多用户	✅ 用户/组级策略	✅ 具有每个租户资源的多租户	✅ 基于角色的端点	✅ 资源级RBAC	❌ 单用户本地代理
主要关注点	治理+受监管企业的数据保护	高性能连接+大规模代理人工智能的可观察性	托管治理+部署平台	可扩展的Kubernetes路由+生命周期管理	本地MCP使用的安全护栏

何时选择什么

mcp零点 --您需要一个自托管、轻量级的网关，具有策略即代码治理、内联PII屏蔽和结构化审计日志，以实现合规性。没有供应商锁定，没有云依赖。
代理网关 --您需要一个高性能的、基于Rust的代理，用于大规模的代理到代理和代理到工具的连接，具有OpenTetry可观察性和基于Cedar的策略。如果您需要A2A协议支持或LLM网关路由以及MCP，则非常适合。没有内置的PII掩码。
MintMCP --您需要一个托管的SaaS平台，以最小的运营开销处理部署、托管和治理。商业许可预算。
微软MCP网关 --您已经在使用Azure/AKS，需要与Entra ID集成的Kubernetes原生MCP服务器编排。自带数据保护和策略引擎。
Lasso MCP网关 --您需要一个轻量级的本地代理，专注于为单个开发人员工作站提供秘密/PII掩码。高级功能需要商业Lasso平台。

许可证

看许可证了解详情。

使用说明

mcp零点

特性

快速开始

先决条件

安全通知

安装

配置

跑

配置

环境变量

策略文件

CORS配置

服务器类型

发展

项目结构

建筑

文档

比较

何时选择什么

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器