AI导哈

MCP防护机制

MCP Guardrails是一个为模型上下文协议服务器提供生产级防护的参考实现，包括身份验证、速率限制、策略访问和结构化审计四大核心功能。

  • by hereisSwapnil
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 hereisSwapnil/mcp-guardrails

使用说明

🛡️ MCP Guardrails

Reference Implementation: Building Production-Ready Model Context Protocol Servers

📖 故事：当我的MCP服务器出现故障时

一天晚上，我在本地测试我的MCP服务器。它有一些标准工具： read_file, write_file，以及 summarize连接到克劳德桌面，一切似乎都很顺利。

然后我又试了一件事：

“读取此目录中的所有50个文件，并对每个文件进行汇总。”

几秒钟后，我的终端爆炸了。CPU条固定在红色，我的触控板滞后，底盘感觉就像煎鸡蛋一样。模型已进入重试循环： read_file → error → retry → read_file 没有执行制动器。

此存储库是修复程序。 它将一个“很酷的演示”变成了一个高功率的引擎 带刹车.

[！注意] 阅读其背后的完整故事： 我的MCP服务器出现故障的那一天（以及我如何修复它）

🏗️ 核心规则：愚蠢的工具，集中的护栏

这一突破是简单的关注点分离： 让工具保持沉默。保持护栏集中。

你的 read_file 该工具应仅执行文件读取。身份验证、速率限制和策略检查属于一个中央中间件管道，该管道在每个请求到达敏感逻辑之前拦截它。

🛡️ 生产MCP服务器的四大支柱

此实现演示了从演示到生产的四个基本护栏：

1.身份（认证）

每个请求都必须证明身份。我们执行 MCP_CLIENT_ID 和 MCP_API_KEY 在工具执行之前对每个请求路径进行验证。

2.节流（速率限制）

LLM速度很快；重试循环更快。我们实现了每个客户端和每个工具的滑动窗口限制（例如。， write_file: 5/min).

3.治理（基于策略的访问）

权限是数据驱动的，而不是硬编码的。规则活在 config/policy.yaml 因此，您可以准确地定义谁可以调用哪些工具以及在什么限制下调用。

4.可观察性（结构化审计）

当事件发生时，纯日志是不够的。每次访问尝试（允许/阻止）都以结构化JSON的形式发出，包括决策上下文。

🚀 快速开始

1.安装依赖项

pip install -r requirements.txt

2.配置克劳德桌面

MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下条目：

{
  "mcpServers": {
    "mcp-guardrails": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "app.main"],
      "cwd": "/absolute/path/to/mcp-guardrails",
      "env": {
        "MCP_CLIENT_ID": "client-a",
        "MCP_API_KEY": "sk-client-a-12345"
      }
    }
  }
}

3.对制动器进行压力测试

试着让克劳德“快速阅读100个文件”。您将看到它完全达到速率限制，而不是冻结您的机器：

[rate_limited] Rate limit exceeded for 'read_file'

⚙️ 配置

安全逻辑是数据驱动的，在 config/ 目录。

  • config/clients.example.yaml：定义 谁 正在访问您的服务器（ID和API密钥）。
  • config/policy.example.yaml：定义 什么 他们可以做到（利率限制和允许的工具）。

[！提示] 要开始，请复制 .example.yaml 文件到 .yaml 并对其进行定制！

🔒 威胁模型（假设）

  1. 信任边界：仅当父进程（Claude）受信任时，本地环境变量才受信任。
  2. 秘密处理：基于文件的配置适用于本地/dev。生产应使用密钥管理器（Vault/ASM）。
  3. 纵深防御：即使有泄露的凭据，速率限制和政策限制也会大大减小爆炸半径。

📁 项目结构

mcp-guardrails/
├── app/
│   ├── main.py           # Guardrail Middleware Pipeline
│   ├── config.py         # Policy & Client loading
│   ├── tools.py          # The underlying "Dumb" Tools
│   └── logger.py         # Structured JSON auditing
├── config/               # YAML-based Policy Definitions
└── requirements.txt

相关 MCP