Scopeblind Mcp

⚠️ This repository has moved. Active development continues at ScopeBlind/scopeblind-gateway.

This personal fork may be behind the canonical repository. Please use the org repo for issues, pull requests, and the latest code.

protect-mcp

Security gateway for MCP servers. Shadow-mode logs by default, per-tool policies, optional local Ed25519 receipts, and verification-friendly audit output.

Current CLI path: wrap any stdio MCP server as a transparent proxy. In shadow mode it logs every tools/call request and allows everything through. Add a policy file to enforce per-tool rules. Run protect-mcp init to generate local signing keys and config so the gateway can also emit signed receipts.

Quick Start

# Wrap an existing OpenClaw / MCP config into a usable packnpx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe
# Shadow mode — log every tool call, enforce nothingnpx protect-mcp -- node my-server.js
# Generate keys + config template for local signingnpx protect-mcp init
# Shadow mode with local signing enablednpx protect-mcp --policy protect-mcp.json -- node my-server.js
# Enforce modenpx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js
# Export an offline-verifiable audit bundlenpx protect-mcp bundle --output audit.json

What It Does

protect-mcp sits between your MCP client and server as a stdio proxy:

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

It intercepts tools/call JSON-RPC requests and:

• Shadow mode (default): logs every tool call and allows everything through
• Enforce mode: applies per-tool policy rules such as block, rate_limit, and min_tier
• Optional local signing: when signing is configured, emits an Ed25519-signed receipt alongside the structured log

All other MCP messages (initialize, tools/list, notifications) pass through transparently.

What Ships Today

• Per-tool policies — block destructive tools, rate-limit expensive ones, and attach minimum-tier requirements
• Structured decision logs — every decision is emitted to stderr with [PROTECT_MCP]
• Optional local signed receipts — generated when you run with a policy containing signing.key_path, persisted to .protect-mcp-receipts.jsonl, and exposed at http://127.0.0.1:9876/receipts
• Offline verification — verify receipts or bundles with npx @veritasacta/verify
• No account required — local keys, local policy, local process

Current Capability Boundaries

These are important before you roll this out or talk to users:

• Signing is not automatic on the bare npx protect-mcp -- ... path. That path logs decisions in shadow mode. For local signing, run npx protect-mcp init and then start the gateway with the generated policy file.
• Tier-aware policy checks are live, but manifest admission is not wired into the default CLI/stdio path. The CLI defaults sessions to unknown unless a host integration calls the admission API programmatically.
• Credential config currently validates env-backed credential references and records credential labels in logs/receipts. Generic per-call injection into arbitrary stdio tools is adapter-specific and is not performed by the default proxy path.
• External PDP adapters and audit bundle helpers exist as exported utilities. They are not yet fully wired into the default CLI path.

Policy File

{  "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"    }  }}

Policy Rules

Tool names match exactly, with "*" as a wildcard fallback.

MCP Client Configuration

Claude Desktop

Add to 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

Same pattern — replace the server command with protect-mcp wrapping it.

CLI Options

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

Programmatic Hooks

The library also exposes the primitives that are not yet wired into the default CLI path:

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

Use these if you want to add:

• manifest admission before a session starts
• an external PDP (OPA, Cerbos, or a generic HTTP webhook)
• custom credential-brokered integrations
• audit bundle export around your own receipt store

Decision Logs and Receipts

Every tool call emits structured JSON to stderr:

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

When signing is configured, a signed receipt follows:

[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":"..."}

Verify with the CLI: npx @veritasacta/verify receipt.json Verify in browser: scopeblind.com/verify

Audit Bundles

The package exports a helper for self-contained audit bundles:

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

Use createAuditBundle() around your own collected signed receipts.

Philosophy

• Shadow first. See what agents are doing before you enforce anything.
• Receipts beat dashboard-only logs. Signed artifacts should be independently verifiable.
• Keep the claims tight. The default CLI path does not yet do everything the long-term architecture will support.
• Layer on top of existing auth. Don't rip out your stack just to add control and evidence.

Incident-Anchored Policy Packs

Ship with protect-mcp — each prevents a real attack:

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

Full OWASP Agentic Top 10 mapping: scopeblind.com/docs/owasp

BYOPE: External Policy Engines

Supports OPA, Cerbos, Cedar (AWS AgentCore), and generic HTTP endpoints:

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

Standards & IP

• IETF Internet-Draft: draft-farley-acta-signed-receipts-00 — Signed Decision Receipts for Machine-to-Machine Access Control
• Patent Status: 4 Australian provisional patents pending (2025-2026) covering decision receipts with configurable disclosure, tool-calling gateway, agent manifests, and portable identity
• Verification: MIT-licensed — npx @veritasacta/verify --self-test

License

MIT — free to use, modify, distribute, and build upon without restriction.

scopeblind.com · npm · GitHub · IETF Draft