mcp-policy-gateway

一个策略优先的 MCP 服务器参考实现。它展示了如何为代理提供有用的工具，而不允许模型自行决定授权、跨越租户边界、泄露直接 PII，或自行执行高影响变更。

这是一个作品集/参考实现。所有记录都是合成的；它不是生产软件，也不声称与银行、支付处理器或客户系统集成。

为什么存在

常见的 MCP 演示将原始 API 暴露给模型，并将成功的工具调用视为安全模型。本项目采取相反的立场：

• 策略是确定性的。 模型不能自行授权。

• 租户边界在服务端强制执行。 工具参数不能切换租户。

• 工具输出最小化。 账户摘要故意排除所有者姓名和电子邮件。

• 高影响操作在审批门处停止。 冻结请求不会产生状态变更。

• 每个决策都可审计。 允许、拒绝和需要审批的结果都会创建结构化审计事件。

• 变更请求需要理由和幂等键。

Related MCP server: scopeguard-mcp

架构

MCP client / agent
       │ tool call
       ▼
FastMCP stdio adapter
       │ verified principal (demo fixture here)
       ▼
GatewayService ──► PolicyEngine ──► allow / deny / require approval
       │                 │
       ▼                 ▼
synthetic domain data   structured audit event

在生产部署中，主体将来自模型上下文之外的已验证身份/会话。切勿从工具参数或模型输出中接受 tenant_id、角色或作用域。

工具

快速开始

需要 Python 3.11+。

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .

作为 MCP stdio 服务器运行：

.venv/bin/mcp-policy-gateway

适配器故意使用固定的演示主体进行本地探索。真实身份传播被有意记录为生产集成问题，而不是在这里伪造。

演示的滥用控制

测试证明网关：

1. 拒绝来自 tenant_red 的代理尝试读取 tenant_blue 数据；

2. 拒绝没有所需作用域的工具调用；

3. 不通过摘要工具返回所有者姓名或电子邮件；

4. 返回 require_approval 而不是变更账户状态；以及

5. 拒绝省略理由或幂等键的变更状态请求。

威胁模型和非目标

参见 THREAT_MODEL.md。设计有意保持狭窄：它演示了围绕 MCP 工具的策略边界，而不是完整的身份基础设施、持久化审计存储、机密管理或支付/账本系统。

面试讲解

解释项目的一种简洁方式：

我设计了 MCP 边界，使模型能够基于安全、有作用域的数据进行推理，但不能决定访问权限或执行高影响操作。授权是确定性的，租户隔离在服务端强制执行，工具表面最小化 PII，敏感变更终止于可审计的人工审批门。

开发

.venv/bin/pytest
.venv/bin/ruff check .

CI 在推送和拉取请求上运行这两项检查。

许可证

MIT。参见 LICENSE。