Name: MCP服务器运行时代理与CI门控
Author: mcptrust

使用说明

MCPTrust

默认情况下拒绝MCP服务器的运行时代理+CI门。
钉上你跑的东西。核实来源。强制执行允许使用的工具/提示/资源。

适用于： 在Claude Desktop、LangChain、AutoGen、CrewAI或内部AI代理中运行MCP服务器的团队。

它阻碍了什么

MCPTrust是您的AI代理和MCP服务器之间的防火墙。

🚫 运行时的阴影工具 --服务器添加新 exec_shell 在您批准后使用该工具？此路不通。
🚫 锁定文件后漂移 --自上次CI检查以来服务器是否已更改？构建失败。
🚫 供应链互换 --焦油球哈希值与固定工件不匹配？执行被拒绝。

没有MCPTrust，任何MCP服务器都可以默默地添加危险的功能。对于MCPTrust，默认情况下是拒绝的。

2分钟快速入门

# 1. Install
go install github.com/mcptrust/mcptrust/cmd/mcptrust@latest

# 2. Lock the server's capabilities
mcptrust lock -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# 3. Run with enforcement (blocks anything not in lockfile)
mcptrust proxy --lock mcp-lock.json -- npx -y @modelcontextprotocol/server-filesystem /tmp

就这样 代理现在位于主机和服务器之间，阻止任何不在锁文件中的工具/提示/资源。

尝试“失败关闭”演示

请参阅MCPTrust实时阻止流氓工具：

# Lock a server
mcptrust lock -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Now imagine the server adds a new tool after you locked it...
# The proxy blocks unknown tools and logs:

mcptrust proxy --lock mcp-lock.json -- npx -y @modelcontextprotocol/server-filesystem /tmp
# → [BLOCKED] tools/call: unknown tool "exec_shell" not in allowlist

工具被阻塞时的预期输出：

mcptrust: action=blocked method=tools/call tool=exec_shell reason="not in allowlist"

运作原理

┌──────────┐      ┌─────────────────────┐      ┌────────────┐
│   Host   │ ──── │   mcptrust proxy    │ ──── │ MCP Server │
│ (Claude) │      │                     │      │            │
└──────────┘      └─────────────────────┘      └────────────┘
                          │
                          ▼
              ┌─────────────────────────────┐
              │  • ID translation (anti-    │
              │    spoofing, server never   │
              │    sees host request IDs)   │
              │  • List filtering           │
              │  • Call/read blocking       │
              │  • Drift preflight check    │
              │  • Audit logs/receipts      │
              └─────────────────────────────┘

特征网格

功能	它做什么
运行时代理	默认情况下拒绝主机和服务器之间的强制执行
锁定文件v3	允许列表工具、提示、资源、模板
漂移检测	CI在关键/中等/信息更改时失败
策略预设	`baseline` （警告）或 `strict` （故障关闭）
工件钉扎	SHA-512/256完整性+来源验证
ID转换	反欺骗：服务器永远看不到真实的主机ID
仅审核模式	记录所有内容，不阻止任何内容（培训/推广）
仅筛选模式	筛选列表，不阻止呼叫（可见性）

信任和安全保证

MCPTrust明确保证其他工具不会：

不变性	机制
服务器永远看不到主机请求ID	代理生成的ID；主机ID从未转发
丢弃了未知/重复的响应	反欺骗：响应必须与挂起的请求匹配
在等待饱和时失败关闭	如果跟踪表已满，则拒绝（无静默传递）
RNG故障时故障关闭	如果ID生成失败，则拒绝请求
校验和不匹配时失败关闭	工件哈希必须匹配或执行被拒绝
NDJSON行限制	线路>10MB掉线（OOM防御）
仅支持HTTPS的tarball下载	HTTP被阻止；私有IP被阻止（SSRF防御）
CI动作固定在SHA上	复合操作使用固定依赖关系

看担保_担保.md 了解全部细节。

集成

MCPTrust适用于您现有的堆栈：

平台	状态	注释
克劳德桌面版	✅ 作品	要点 `mcpServers` 到 `mcptrust proxy -- <server>`
克劳德代码	✅ 作品	使用 `claude mcp add` 使用mcptrust代理
节点MCP服务器	✅ 适用	任何基于stdio的服务器（npx、节点等）
Python代理	✅ Works	LangChain、AutoGen、CrewAI——使用代理作为子流程
GitHub操作	✅ 原住民	复合作用用于CI门
码头工人	✅ 作品	`mcptrust run` 支持 `docker run IMAGE`

Claude桌面示例

{
  "mcpServers": {
    "filesystem": {
      "command": "mcptrust",
      "args": ["proxy", "--lock", "/path/to/mcp-lock.json", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Claude代码示例

# Generate lockfile
mcptrust lock --v3 -- npx @modelcontextprotocol/server-filesystem /tmp

# Add MCP server with MCPTrust proxy
claude mcp add my-server -- mcptrust proxy --lock mcp-lock.json -- npx @modelcontextprotocol/server-filesystem /tmp

GitHub行动（CI门）

在30秒内将MCPTrust添加到您的CI：

- uses: mcptrust/mcptrust/.github/actions/mcptrust@<SHA>
  with:
    mode: check
    lockfile: mcp-lock.json
    fail_on: critical
    policy: baseline
    server_command: 'npx -y @modelcontextprotocol/server-filesystem /tmp'

模式	目的
`lock`	从服务器生成锁文件
`check`	如果检测到漂移，则失败
`policy`	执行CEL治理规则

[！提示] 固定到用于安全工具的提交SHA。看行动自述.

代理模式

                          ┌─────────────────────────────┐
                          │        Proxy Modes          │
                          └─────────────────────────────┘
                                       │
           ┌───────────────────────────┼───────────────────────────┐
           │                           │                           │
           ▼                           ▼                           ▼
   ┌───────────────┐          ┌───────────────┐         ┌────────────────┐
   │    ENFORCE    │          │  FILTER-ONLY  │         │  AUDIT-ONLY    │
   │   (default)   │          │               │         │                │
   ├───────────────┤          ├───────────────┤         ├────────────────┤
   │ ✅ Filter lists│         │ ✅ Filter lists│         │ ❌ No filtering│
   │ ✅ Block calls │         │ ❌ Allow calls │         │ ❌ Allow calls │
   ├───────────────┤          ├───────────────┤         ├───────────── ──┤
   │  Production   │          │    Rollout    │         │   Training     │
   └───────────────┘          └───────────────┘         └────────────────┘

模式	列表已筛选	呼叫已阻止	用例
`enforce` （默认）	✅	✅	生产
`--filter-only`	✅	❌	可见性卷展栏
`--audit-only`	❌	❌	培训/记录

# Enforce mode (default) — blocks unknown tools
mcptrust proxy --lock mcp-lock.json -- npx -y ...

# Audit-only — log but don't block (safe for rollout)
mcptrust proxy --audit-only --lock mcp-lock.json -- npx -y ...

# Filter-only — filter lists, don't block calls
mcptrust proxy --filter-only --lock mcp-lock.json -- npx -y ...

供应链安全

MCPTrust锁定并验证您运行的确切工件：

# Lock with artifact pinning + provenance
mcptrust lock --pin --verify-provenance -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Enforced execution (verifies everything, then runs)
mcptrust run --lock mcp-lock.json

保证	机制
焦油球SHA-512匹配	`lockfile.artifact.integrity`
焦油球SHA-256匹配	`lockfile.artifact.tarball_sha256`
SLSA来源验证	共同签名认证验证
没有安装后脚本	`--ignore-scripts` 强制执行
仅限本地执行	已验证的二进制文件 `node_modules/.bin/`

安全态势

MCPTrust自己的供应链得到加强：

✅ GitHub操作被固定到SHA --所有动作依赖项都使用提交SHA
✅ 启用Dependabot --GitHub操作的自动更新
✅ 释放校验和失败关闭 --需要二进制验证
✅ 仅HTTPS下载 --HTTP和私有IP被阻止
✅ 责任揭秘 --请参阅安全.md

CLI参考

命令	目的
`scan`	检查MCP服务器功能
`lock`	创建 `mcp-lock.json` 从服务器状态
`diff`	检测锁文件和实时服务器之间的漂移
`proxy`	作为stdio强制代理运行
`run`	已验证固定工件的执行情况
`sign` / `verify`	Ed25519或Sigstore签名
`policy check`	执行CEL治理规则
`bundle export`	创建确定性ZIP进行分发

看 docs/CLI.md 供充分参考。

签名与验证

Ed25519（本地）

mcptrust keygen                           # Generate keypair
mcptrust sign --key private.key mcp-lock.json
mcptrust verify --key public.key mcp-lock.json

Sigstore（CI/CD，无钥匙）

mcptrust sign --sigstore mcp-lock.json
mcptrust verify mcp-lock.json \
  --issuer https://token.actions.githubusercontent.com \
  --identity "https://github.com/org/repo/.github/workflows/sign.yml@refs/heads/main"

看 docs/SIGSTORE.md GitHub操作示例。

可观测性

结构化日志记录

mcptrust lock --log-format jsonl --log-output /var/log/mcptrust.jsonl -- "..."

收据（审计跟踪）

mcptrust lock --receipt /var/log/mcptrust/receipt.json -- "..."

开放遥测

mcptrust lock --otel --otel-endpoint localhost:4318 -- "..."

看 docs/observatory-otel.md 完整的选项。

文档

CLI参考 --命令、标志、示例
克劳德代码指南 --完整集成演练
LangChain指南 --用于代理的Python适配器
Sigstore指南 --CI/CD的无密钥签名
安全保障 --显式安全属性
威胁模型 --我们保护什么
政策指南 --编写CEL规则
迁移指南 --版本兼容性

路线图

🔜 策略包 --可共享的治理规则集
🔜 收据模式v2 --SIEM集成的稳定模式
🔜 资源/提示模板锁定 --完全覆盖MCP表面

局限性

MCPTrust确保接口，而不是实施:

超出范围	为什么
恶意逻辑	一个名为 `read_file` 运行 `rm -rf` 通过模式看起来完全相同
运行时提示注入	MCPTrust不监视代理↔ 工具对话
关键妥协	如果 `private.key` 被盗，攻击者可以签署恶意锁文件
开发开销	对于快速原型制作，lockfile工作流程可能过于繁琐

看线程_模式.md 了解全部细节。

发展

go test ./...                              # Unit tests
bash tests/gauntlet.sh                     # Integration suite
MCPTRUST_BIN=./mcptrust bash scripts/smoke.sh  # Smoke test

贡献

欢迎发布问题和PR。看安全.md 用于漏洞报告。

许可证

阿帕奇-2.0