sovereign-mcp-gateway

一个用于 Model Context Protocol 服务器的门控代理。 将你的 MCP 客户端指向网关，而不是指向你的服务器。它连接到你列出的每个上游，将它们的工具目录合并为一个，并在每次调用到达将要执行它的服务器之前，将其送入校验链。

pip install sovereign-mcp-gateway
sovereign-mcp-gateway --config gateway.json

网关本身就是一个 MCP 服务器，因此任何支持 MCP 的客户端都无需改动即可使用。

基础安装就是一个可用的网关。四个可选附加项在其上增加更多层——参见安装。

它能阻止什么

一个智能体读取了一个 GitHub issue，其正文携带一条针对模型而非针对你的指令。它被诱导了，并调用了 git_commit。

相同的工具、相同的参数、相同的服务器。区别在于是否有任何东西处于可以拒绝的位置。

阅读演练：你的智能体读取一个 issue——或者运行它：

pip install "sovereign-mcp-gateway[all]" mcp-server-git
python examples/poisoned_issue.py

Related MCP server: Mavryn

为什么是代理而不是库

库必须由服务器作者采用。代理则能保护你无法修改的服务器——而大多数服务器正是如此，因为有用的 MCP 服务器都是别人维护的已发布包。

它还为你提供了一个集中保存策略的地方，以及一条覆盖智能体可访问的每个服务器的审计轨迹，而不是无人同步的逐服务器配置。

配置

{
  "servers": {
    "git":    {"command": "mcp-server-git",    "args": ["--repository", "/repo"]},
    "sqlite": {"command": "mcp-server-sqlite", "args": ["--db-path", "/data.db"]}
  },
  "policy": {"deny_tools": ["git__git_reset"], "pii_policy": "warn"},
  "audit":  {"path": "gateway-audit.jsonl"}
}

在客户端看到它之前，检查连接配置：

sovereign-mcp-gateway --config gateway.json --check

SOVEREIGN GATEWAY - configuration check
upstreams: 2
layers:   policy -> intent -> text-filter -> frozen-verify -> audit

EXPOSED AS                             UPSTREAM TOOL
git__git_status                        git.git_status
git__git_reset                         git.git_reset          [DENIED]
sqlite__read_query                     sqlite.read_query
...
18 tools exposed.

校验链

policy → intent → text-filter → frozen-verify → [ call executes ] → output-verify → logic-rules → audit

安装

基础安装是一个可用的网关，而不是一个空壳：

pip install sovereign-mcp-gateway

这为你提供了策略 → 冻结校验 → 审计，它已经能够拒绝：没有上游暴露的工具、类型错误的参数、未声明的参数、位于你拒绝列表中的工具，以及参数中的提示注入。不需要其他任何东西。

每个附加项都会在之上增加一层：

组合你想要的，或者全部安装：

pip install "sovereign-mcp-gateway[text]"             # one extra
pip install "sovereign-mcp-gateway[text,intent]"      # several
pip install "sovereign-mcp-gateway[all]"              # every layer

这四个附加项都是小巧的纯 Python 包——[all] 不增加任何编译依赖，也不需要运行任何服务。

部分安装会明显降级。 网关在启动时会打印其活动层，因此你随时可以看到实际运行的是什么：

layers:   policy -> frozen-verify -> audit                                  # base
layers:   policy -> intent -> text-filter -> frozen-verify -> audit         # [all]

如果某个层不在那一行中，它就没有运行——无论你认为自己安装了什么。

端到端验证

以 mcp-server-git 和 mcp-server-sqlite 作为真实上游运行，并由真实的 MCP 客户端驱动：

之后，仓库仍然只有一个提交，数据库也恰好包含它应有的那一行——这是通过直接打开它们检查的，而不是信任网关自己的报告。十次调用对应十一条审计记录；编辑其中任何一条都会破坏整条链。

这些案例就是测试套件，而不是截图：pytest tests/ -v。

Layer C：N 模型共识

其他每一层都是确定性的且在本机运行。Layer C 是个例外：它让多个独立模型从工具结果中提取同一份结构化文档，对每个答案进行规范化，并比较 SHA-256 哈希。是否一致由哈希决定，而不是由文本内容决定。

除非经过配置，否则它是关闭的，因为它是唯一一个每次调用都会产生费用和延迟的层，也是唯一一个将工具输出发送给模型的层。

{
  "servers": { "...": {} },
  "consensus": {
    "providers": [
      {"type": "local", "model": "llama3.1:8b"},
      {"type": "local", "model": "qwen2.5:7b", "base_url": "http://localhost:11434/v1"},
      {"type": "openrouter", "model": "anthropic/claude-3.5-sonnet",
       "api_key_env": "OPENROUTER_API_KEY"}
    ]
  }
}

两种提供方类型：local（任何兼容 OpenAI 的端点——Ollama、vLLM、LM Studio；base_url 默认为 http://localhost:11434/v1）和 openrouter（密钥从指定的环境变量中读取，绝不会写入配置）。

网关在启动时强制执行三条规则，而不是在运行时才发现：

• 至少两个提供方。 一个模型无法与自己不一致；单一模型的共识会在每次调用时都报告一致，这比没有该层更糟，因为它看起来像是验证。

• 不允许重复模型。 同一个模型的两个实例达成一致并不是独立验证。

• 缺少 API 密钥会拒绝启动。 它不会退回到没有该层的情况下运行。

所有提供方都在 temperature = 0 下运行，这一点在构造函数中强制执行。

在信任该层之前，先确认你的模型能达成一致

--check 会针对你配置的模型执行一次真实的共识调用，并告诉你发生了什么。这比听起来更重要：

LAYER C  - probing the configured models with one real call
--------------------------------------------------------------
  OK. The configured models produced identical documents.
  Layer C will pass ordinary output rather than refusing it.

共识比较的是规范化哈希，因此两个在语义上都正确但结构不同的模型永远不会一致。一个较弱的模型会把模式原样回显——

{"branch": {"type": "string", "value": "main"}}   instead of   {"branch": "main"}

——它会在每次调用时都不匹配，永远如此，而网关会以一条读起来确实是“模型不一致”的原因拒绝一切。因为它们确实不一致。

该探测区分三种结果：

安装 sovereign-mcp-gateway[consensus] 或 [all]——HTTP 提供方需要 requests，而核心库刻意不依赖它。

--check 还会列出活动层，因此你可以一目了然地确认：

layers:   policy -> intent -> text-filter -> frozen-verify -> consensus -> audit

如果 consensus 不在那一行中，它就没有运行，无论配置怎么说。

命名空间

在启用 namespace（默认）的情况下，工具以 git__git_status 的形式暴露。两个提供相同工具名的上游不会冲突、不会互相遮蔽，也不会通过错误的命名空间被访问。只有当你只有一个上游时，才应关闭它。

策略

"policy": {
  "deny_tools":  ["git__git_reset", "write_query"],
  "allow_tools": null,
  "pii_policy":  "warn",
  "fail_closed": true,
  "rate_limit_interval": 0
}

• deny_tools 匹配暴露名称（git__git_reset）或上游工具名称（git_reset，在拥有该工具的每个上游上）。

• allow_tools，一旦设置，会拒绝所有未列出的内容。

• pii_policy 默认为 warn，而不是 block。真实工具会将个人数据作为正常输出返回——每条 git log 记录都带有作者邮箱——而阻止这些输出会让网关无法使用。当你的工具绝不应输出 PII 时，设置为 block。

• fail_closed 决定当某个层自身出错时会发生什么。默认：拒绝。

• rate_limit_interval 为 0，这会禁用行为底线自身的动作间延迟。该延迟适合一个采取谨慎步骤的智能体，但对代理来说是不合适的，因为对代理而言，一阵突发的工具调用是普通流量。

• entropy_policy 默认为 warn。文本过滤器的熵启发式算法会搜寻隐藏在文本中的编码载荷，但工具参数通常是结构化的——路径、标识符、哈希——在这些地方高熵是正常的。仅一个临时目录路径就足以让一次合法调用被拒绝。当你的参数确实是纯文本时，设置为 block。

它不做什么

它根据冻结的定义校验调用，并检查参数和结果。它不读取你的服务器源码，因此它无法发现一个存在、被调用却默默不做任何事的检查。那仍然需要有人阅读实现代码。

它也无法防止被入侵的上游返回看似正确的数据——sovereign-mcp 中的 Layer C 共识解决了这个问题，并且需要你自己配置模型提供商。

许可证

Business Source License 1.1 — 参见 LICENSE。

源代码是公开的。你可以免费阅读、修改、创建衍生作品，并将其用于开发、评估和任何其他非生产目的。

生产使用也是免费的，适用于个人或四人及以下的组织——这已作为附加使用授权写入许可证，而不仅仅是在此声明。较大的组织需要商业许可证。

每个版本在其变更日期（发布四年后）转换为 Apache 2.0。

如需获得生产许可，或询问你的使用是否需要许可：contact@sovereign-shield.net