⚠️ 此仓库已迁移。 活跃开发工作现已转移至 ScopeBlind/scopeblind-gateway。
此个人分支可能落后于规范仓库。请使用组织仓库提交问题、拉取请求及获取最新代码。
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.jsonRelated MCP server: protect-mcp
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"
}
}
}字段 | 值 | 描述 |
|
| 显式拦截此工具 |
|
| 基本访问要求 |
|
| 如果您的主机设置了准入状态，则为所需的最低层级 |
|
| 速率限制（例如 |
工具名称必须完全匹配，支持使用 "*" 作为通配符回退。
添加到 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"
]
}
}
}模式相同 — 将服务器命令替换为封装它的 protect-mcp。
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 分类 |
| CVE-2025-6514: MCP OAuth 代理劫持 (437K 环境) | A01, A03 |
| 自主 Terraform 代理销毁生产环境 | A05, A06 |
| 通过精心构造的 GitHub Issue 进行提示词注入 | A01, A02, A03 |
| 通过出站工具滥用进行代理数据窃取 | A02, A04 |
| 未经授权的金融交易 | A05, A06 |
npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js完整的 OWASP Agentic Top 10 映射：scopeblind.com/docs/owasp
支持 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
Delete a file from the filesystem
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose that deletion is irreversible or mention behavior for missing paths or directories, which is critical for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but could be improved by including context about irreversibility without significant length increase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema or annotations, the description lacks completeness: no mention of return values, errors, or required permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description 'File path to delete' is already clear; the description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'file from the filesystem', distinguishing it from sibling tools like read_file (read) and write_file (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no context about prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy the application to production
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Deployment reason | |
| environment | Yes | Target environment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fails to disclose behavioral traits like destructiveness, auth requirements, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely short (5 words), but underspecified – conciseness should not sacrifice necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not explain return values, side effects, or deployment process outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'deploy the application to production' – clear verb and resource, but slightly misleading as schema allows staging also. No confusion with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or when-not-to-use mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the contents of a file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions reading without specifying encoding, size limits, existence requirements, or return format, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single-sentence description that is front-loaded and efficient with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simplicity, description lacks details on return format, error handling, and behavioral constraints, which are critical for an agent invoking a file read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'path' described as 'File path to read'; description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'read' and resource 'contents of a file', distinguishing it from sibling tools like write_file and delete_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives; usage is implied by the name and description but lacks context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web for information
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks details on behavior such as rate limits, result format, or limitations, leaving the agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but fails to include necessary details, balancing brevity and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations, the description does not adequately cover what the agent needs to know for successful use, such as result types or response details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'query' with a schema description, and the tool description adds no additional meaning beyond what the schema already provides; high schema coverage baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search the web for information' clearly states the verb and resource, and it distinguishes from siblings (file operations and deploy) which are unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, and no exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content to a file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to write | |
| content | Yes | Content to write |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose important behavioral traits such as whether the file is overwritten, permissions required, or error handling. Without annotations, the description carries the full burden, and it is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, to-the-point sentence with no wasted words. It earns its place by conveying the core action concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple file write tool, the description lacks completeness. It does not mention return values, overwrite behavior, or any constraints, making it less useful for an AI agent to fully understand the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, so the description adds no extra meaning. Baseline 3 is appropriate; the schema already documents path and content adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Write content to a file' clearly states the verb 'Write' and the resource 'content to a file', distinguishing it from sibling tools like read_file and delete_file. However, it does not specify whether it overwrites or appends, which would add more precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. An explicit mention of use cases or exclusions (e.g., when to use deploy instead) is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
delete_filedeployread_fileweb_searchwrite_fileScored across 5 tools
Each tool targets a distinct action: file operations (delete, read, write), deployment, and web search. There is no overlap or ambiguity between them.
Most tools follow verb_noun pattern (delete_file, read_file, write_file, web_search), but 'deploy' lacks a noun, breaking the consistent pattern slightly.
5 tools is a reasonable count, but the mix of file management, deployment, and web search seems odd for a single server scope.
The tool set lacks obvious necessary operations for any single domain: e.g., no update for files, no environment or config for deployment, making it incomplete for a coherent purpose.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
