mcptrust (9968f5)

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      │
              └─────────────────────────────┘

______________________________________________________________________

特征网格

______________________________________________________________________

信任和安全保证

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

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

______________________________________________________________________

集成

MCPTrust适用于您现有的堆栈：

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@
  with:
    mode: check
    lockfile: mcp-lock.json
    fail_on: critical
    policy: baseline
    server_command: 'npx -y @modelcontextprotocol/server-filesystem /tmp'

\[！提示\] 固定到用于安全工具的提交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 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

______________________________________________________________________

安全态势

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

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

______________________________________________________________________

CLI参考

看 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确保 接口，而不是 实施:

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

______________________________________________________________________

发展

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

______________________________________________________________________

贡献

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

许可证

阿帕奇-2.0