protect-mcp

Portail de politique Cedar à défaillance fermée plus reçus signés pour les appels d'outils d'agents IA.

protect-mcp est un portail qui se place devant les appels d'outils d'un agent IA. Il évalue chaque appel par rapport à une politique Cedar, bloque ce qui enfreint les règles avant son exécution, et signe un reçu Ed25519 vérifiable hors ligne de chaque décision. La passerelle configurée s'exécute localement et n'envoie aucune télémétrie de décision. L' adaptateur de coordination séparé se connecte au service de collaboration hébergé de ScopeBlind ; ses requêtes et les enregistrements retournés ont le chemin de données décrit ci-dessous. Les deux sont sous licence MIT.

Pour le travail sur un dépôt partagé, utilisez les projets clients : les personnes s'accordent sur le brief et les limites, les agents préparent les revues, et les deux personnes approuvent une version exacte avant que le récepteur du propriétaire puisse modifier le dépôt. Le flux de travail du dépôt ci-dessous inclut la configuration et les cinq outils d'agent délimités.

Ce qui le distingue

• Défaillance fermée par défaut. En cas d'erreur de politique, de moteur manquant, ou d' échec d'évaluation, la décision est DENY. Le portail n'autorise jamais silencieusement. Un mode d'observation existe pour le déploiement en ombre, mais même là, un appel qui serait bloqué est signalé would_deny: true, de sorte qu'un échec n'est jamais silencieux.
• Il prouve sa propre retenue. serve --enforce et doctor exécutent un auto-test au démarrage et refusent d'armer le portail à moins de pouvoir démontrer qu'une action connue comme interdite est effectivement refusée. Un portail qui ne peut pas prouver qu'il refuse ne démarre pas.
• Chaque décision est un reçu que quiconque peut vérifier. Les décisions sont signées Ed25519 et vérifiables hors ligne avec @veritasacta/verify. La vérification de signature ne nécessite aucune recherche réseau. Les affirmations concernant l'exécution dépendent toujours de l'opérateur de portail identifié.

Démarrage rapide : de l'installation à la première preuve utile

# 1. Generate an Ed25519 keypair, config template, and sample policy.
npx protect-mcp init

# 2. Print a shadow-mode client configuration, then apply it in your MCP host.
#    This command prints configuration and exits; it does not launch the server.
npx protect-mcp wrap -- node your-mcp-server.js

# 3. Reopen the host and use its tools, then inspect the local-only dashboard.
npx protect-mcp dashboard --open

# 4. Draft a reviewable policy from observed calls.
npx protect-mcp recommend --write

# 5. When reviewed, restart the wrapper in enforce mode with that policy.
npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Pour Claude Desktop, exécutez d'abord un dry-run de la configuration, puis appliquez-le :

npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

Le tableau de bord se lie à 127.0.0.1, ne lit que les fichiers de journaux/reçus locaux et ne téléverse rien. Utilisez npx protect-mcp connect uniquement si vous souhaitez explicitement un tableau de bord ScopeBlind hébergé.

La porte comme serveur MCP

Si vous préférez appeler la porte comme des outils plutôt que de câbler les hooks Claude Code, exécutez-la comme serveur MCP :

npx protect-mcp mcp

Il parle MCP via stdio et expose quatre outils en lecture seule, toute la boucle :

• evaluate_action : décide d'un appel d'outil proposé selon une politique Cedar en ligne, en mode fail-closed (toute erreur de politique est DENY). Retourne { allowed, decision, reason, policy_digest }.
• sign_decision : transforme une décision en un reçu signé Ed25519 (un refus signe un gateway_restraint, une autorisation un decision_receipt). Retourne le reçu et sa clé publique ; génère une clé éphémère si vous n'en fournissez pas.
• verify_receipt : vérifie un reçu signé hors ligne par rapport à une clé publique. Retourne { valid, error, type, kid, issuer }.
• self_test : le prouve, sans entrées. Une action connue comme interdite est refusée, puis un reçu signé fait un aller-retour et une copie falsifiée échoue.

Pointez n'importe quel hôte MCP vers lui, par exemple Claude Desktop :

{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Les reçus sont compatibles octet pour octet avec ceux que la passerelle signe à l'exécution, donc un reçu généré ici utilise la même enveloppe Acta. Les capacités de vérification et la compatibilité de canonicalisation dépendent de la version du vérificateur ; utilisez l'API verifyReceipt de la passerelle pour le comportement de conformité décrit ci-dessous.

Compatibilité de canonicalisation des reçus

Cet arbre source corrige le défaut d'ordonnancement des clés entières présent jusqu'à la version 0.14.0 : les signatures et les hachages de chaîne utilisent désormais l'émission directe des membres JCS, en conservant le profil de clés d'objet ASCII de la passerelle. Les clés à apparence numérique telles que "10" précèdent "2", y compris à l'intérieur d'objets imbriqués. Les valeurs non-JSON et l'Unicode invalide sont rejetés.

Les reçus JSON ordinaires dont les encodages sont inchangés continuent d'être vérifiés. Les reçus historiques signés avec l'ancien ordre de clés numériques sont signalés comme legacy_non_jcs_signature ; la vérification stricte ne les considère pas comme des JCS valides. Pour un contrôle de compatibilité historique explicite, utilisez verifyReceipt(receipt, publicKey, { allowLegacyNumericKeys: true }) et inspectez les champs canonicalization et warning. Son hash est alors le hachage historique d'origine. Préservez les reçus d'origine et les liens de chaîne : recalculer un ancien reçu à clés numériques avec receiptHash produit désormais son hachage JCS et peut rompre la chaîne historique. Ces changements sont inclus dans 0.15.0.

Commencez avec votre agent, puis autorisez chaque tâche

La version 0.25.0 inclut un profil d'agent réutilisable. Ouvrez Start through your agent pour la commande de configuration avec la clé d'autorité affichée par le service. Vérifiez cette clé auprès d'une source fiable avant de vous connecter. Par exemple :

npx --yes [email protected] coordination agent setup \
  --client claude-code \
  --profile ~/.scopeblind/agent.json \
  --endpoint https://scopeblind.com/api/coordination \
  --authority-key PINNED_64_HEX_AUTHORITY_KEY

Utilisez --client codex ou --client json pour ces instructions d'enregistrement. La configuration affiche la configuration ; appliquez-la dans votre client, puis rouvrez ce client. Le profil privé contient une clé d'agent et des connexions à portée distincte, avec des permissions de fichier 600. La configuration n'accorde aucune permission de tâche et ne copie aucune clé de navigateur humaine. Le serveur enregistré exécute coordination agent --profile FILE.

Demandez à votre agent de préparer une tâche de facture partagée pour votre examen. Le flux de l'outil est :