⚠️ 이 저장소는 이전되었습니다. 활발한 개발은 **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는 MCP 클라이언트와 서버 사이에서 stdio 프록시로 작동합니다:
MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP servertools/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 웹훅)
사용자 지정 자격 증명 중개 통합
자체 영수증 저장소 주변의 감사 번들 내보내기
모든 도구 호출은 구조화된 JSON을 stderr로 출력합니다:
[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 이슈를 통한 프롬프트 인젝션 | 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 — 기계 간 액세스 제어를 위한 서명된 결정 영수증
특허 상태: 구성 가능한 공개, 도구 호출 게이트웨이, 에이전트 매니페스트 및 휴대용 ID를 포함하는 결정 영수증 관련 호주 가특허 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.
