Skip to main content
Glama
deenesjakoruzh
tomjwxf

protect-mcp

by tomjwxf
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

⚠️ 此仓库已迁移。 活跃开发工作现已转移至 ScopeBlind/scopeblind-gateway。

此个人分支可能落后于规范仓库。请使用组织仓库提交问题、拉取请求及获取最新代码。

protect-mcp

MCP 服务器的安全网关。默认采用影子模式记录日志，支持针对工具的策略、可选的本地 Ed25519 回执以及易于验证的审计输出。

当前 CLI 路径： 将任何 stdio MCP 服务器封装为透明代理。在影子模式下，它会记录每个 tools/call 请求并允许所有请求通过。添加策略文件以强制执行针对工具的规则。运行 protect-mcp init 以生成本地签名密钥和配置，从而使网关能够发出已签名的回执。

快速开始

# Wrap an existing OpenClaw / MCP config into a usable pack
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Generate keys + config template for local signing
npx protect-mcp init

# Shadow mode with local signing enabled
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Enforce mode
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Export an offline-verifiable audit bundle
npx protect-mcp bundle --output audit.json

功能概述

protect-mcp 作为 stdio 代理位于您的 MCP 客户端和服务器之间：

MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server

它拦截 tools/call JSON-RPC 请求并执行以下操作：

  • 影子模式（默认）：记录每个工具调用并允许所有请求通过

  • 强制模式：应用针对工具的策略规则，如 block（拦截）、rate_limit（速率限制）和 min_tier（最低层级）

  • 可选的本地签名：配置签名后，会在结构化日志旁发出 Ed25519 签名回执

所有其他 MCP 消息（initialize、tools/list、通知）均透明通过。

当前功能

  • 针对工具的策略 — 拦截破坏性工具，限制高频工具，并附加最低层级要求

  • 结构化决策日志 — 每个决策都会以 [PROTECT_MCP] 标记输出到 stderr

  • 可选的本地签名回执 — 当您使用包含 signing.key_path 的策略运行时生成，持久化到 .protect-mcp-receipts.jsonl，并可通过 http://127.0.0.1:9876/receipts 访问

  • 离线验证 — 使用 npx @veritasacta/verify 验证回执或捆绑包

  • 无需账户 — 本地密钥、本地策略、本地进程

当前能力边界

在推广使用或与用户沟通前，请注意以下事项：

  • 在基础的 npx protect-mcp -- ... 路径下，签名并非自动执行。 该路径在影子模式下记录决策。如需本地签名，请运行 npx protect-mcp init，然后使用生成的策略文件启动网关。

  • 层级感知策略检查已上线，但清单准入尚未集成到默认的 CLI/stdio 路径中。 除非主机集成以编程方式调用准入 API，否则 CLI 默认将所有会话视为 unknown。

  • 凭据配置目前验证基于环境变量的凭据引用，并在日志/回执中记录凭据标签。 针对任意 stdio 工具的通用按调用注入是适配器特定的，默认代理路径不执行此操作。

  • 外部 PDP 适配器和审计捆绑助手作为导出工具存在。 它们尚未完全集成到默认的 CLI 路径中。

策略文件

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

策略规则

字段

值

描述

block

true

显式拦截此工具

require

"any", "none"

基本访问要求

min_tier

"unknown", "signed-known", "evidenced", "privileged"

如果您的主机设置了准入状态，则为所需的最低层级

rate_limit

"N/unit"

速率限制（例如 "5/hour", "100/day"）

工具名称必须完全匹配，支持使用 "*" 作为通配符回退。

MCP 客户端配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

模式相同 — 将服务器命令替换为封装它的 protect-mcp。

CLI 选项

protect-mcp [options] -- <command> [args...]
protect-mcp init

Commands:
  init              Generate Ed25519 keypair + config template
  status            Show decision stats and local passport identity
  digest            Generate a local human-readable summary
  receipts          Show recent persisted signed receipts
  bundle            Export an offline-verifiable audit bundle

Options:
  --policy <path>   Policy/config JSON file
  --slug <slug>     Service identifier for logs/receipts
  --enforce         Enable enforcement mode (default: shadow)
  --verbose         Enable debug logging
  --help            Show help

编程钩子

该库还公开了尚未集成到默认 CLI 路径中的原语：

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

如果您想添加以下功能，请使用这些原语：

  • 会话开始前的清单准入

  • 外部 PDP（OPA、Cerbos 或通用 HTTP Webhook）

  • 自定义凭据代理集成

  • 围绕您自己的回执存储进行审计捆绑导出

决策日志与回执

每个工具调用都会向 stderr 输出结构化 JSON：

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

配置签名后，会随附一个签名回执：

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

使用 CLI 验证：npx @veritasacta/verify receipt.json 在浏览器中验证：scopeblind.com/verify

审计捆绑包

该包导出了一个用于自包含审计捆绑包的助手：

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

在您收集的已签名回执周围使用 createAuditBundle()。

设计理念

  • 影子优先。 在强制执行任何操作之前，先观察代理的行为。

  • 回执优于纯仪表板日志。 签名工件应可独立验证。

  • 保持声明简洁。 默认 CLI 路径尚未实现长期架构将支持的所有功能。

  • 在现有身份验证之上叠加。 不要为了增加控制和证据而推翻现有的技术栈。

基于事件的策略包

随 protect-mcp 一起发布 — 每个策略都能预防真实的攻击：

策略

事件

OWASP 分类

clinejection.json

CVE-2025-6514: MCP OAuth 代理劫持 (437K 环境)

A01, A03

terraform-destroy.json

自主 Terraform 代理销毁生产环境

A05, A06

github-mcp-hijack.json

通过精心构造的 GitHub Issue 进行提示词注入

A01, A02, A03

data-exfiltration.json

通过出站工具滥用进行代理数据窃取

A02, A04

financial-safe.json

未经授权的金融交易

A05, A06

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

完整的 OWASP Agentic Top 10 映射：scopeblind.com/docs/owasp

BYOPE：外部策略引擎

支持 OPA、Cerbos、Cedar (AWS AgentCore) 和通用 HTTP 端点：

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

标准与知识产权

  • IETF Internet-Draft: draft-farley-acta-signed-receipts-00 — 用于机器对机器访问控制的签名决策回执

  • 专利状态: 4 项澳大利亚临时专利申请中 (2025-2026)，涵盖具有可配置披露、工具调用网关、代理清单和便携式身份的决策回执

  • 验证: MIT 许可 — npx @veritasacta/verify --self-test

许可

MIT — 可自由使用、修改、分发和构建，无任何限制。

scopeblind.com · npm · GitHub · IETF Draft

Install Server
A
security – no known vulnerabilities
A
license - permissive license
C
quality - C tier

How are these scores calculated?

Resources

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tomjwxf/scopeblind-gateway'

If you have feedback or need assistance with the MCP directory API, please join our Discord server