protect-mcp

Portão de política Cedar fail-closed mais recibos assinados para chamadas de ferramentas de agentes de IA.

protect-mcp é um portão que fica à frente das chamadas de ferramentas de um agente de IA. Ele avalia cada chamada contra uma política Cedar (a mesma linguagem que a AWS usa para IAM), bloqueia o que viola as regras antes de ser executado e assina um recibo Ed25519 verificável offline de cada decisão. Ele roda localmente, não envia telemetria das suas decisões para lugar nenhum e é licenciado sob MIT.

Por que ele é diferente

• Fail-closed por padrão. Em qualquer erro de política, ausência de engine ou falha de avaliação, a decisão é DENY. O portão nunca permite silenciosamente. Existe um modo de observação para implantação em sombra, mas mesmo nele uma chamada que seria bloqueada é sinalizada com would_deny: true, então uma falha nunca é silenciosa.
• Ele prova sua própria contenção. serve --enforce e doctor executam um autoteste de inicialização e se recusam a armar o portão a menos que possam demonstrar que uma ação sabidamente proibida é de fato negada. Um portão que não consegue provar que nega não inicia.
• Toda decisão é um recibo que qualquer um pode verificar. As decisões são assinadas com Ed25519 e verificáveis offline com @veritasacta/verify. Nenhuma confiança em fornecedor é necessária: a matemática não se importa com quem a executa.

Início rápido: da instalação à primeira prova útil```bash

1. Generate an Ed25519 keypair, config template, and sample policy.

npx protect-mcp init

2. Wrap any MCP server in shadow mode. Nothing is blocked yet; calls are logged.

npx protect-mcp wrap -- node your-mcp-server.js

3. Inspect the local-only dashboard: tool inventory, risk, approvals, receipts.

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

Para o Claude Desktop, execute primeiro um patch de configuração em modo dry-run e depois aplique-o:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

O dashboard é vinculado a 127.0.0.1, lê apenas arquivos locais de log/recibo e não envia nada. Use npx protect-mcp connect apenas se você quiser explicitamente um dashboard ScopeBlind hospedado.

O gate como um servidor MCP

Se você preferir chamar o gate como ferramentas em vez de configurar os hooks do Claude Code, execute-o como um servidor MCP:```bash npx protect-mcp mcp

Ele fala MCP sobre stdio e expõe quatro ferramentas somente leitura, todo o ciclo:

- **`evaluate_action`**: decide uma chamada de ferramenta proposta contra uma política Cedar inline, fail-closed (qualquer erro de política é DENY). Retorna `{ allowed, decision, reason, policy_digest }`.
- **`sign_decision`**: transforma uma decisão em um recibo assinado com Ed25519 (uma negação assina um `gateway_restraint`, uma permissão um `decision_receipt`). Retorna o recibo e sua chave pública; gera uma chave efêmera se você não fornecer uma.
- **`verify_receipt`**: verifica um recibo assinado offline contra uma chave pública. Retorna `{ valid, error, type, kid, issuer }`.
- **`self_test`**: prova isso, sem entradas. Uma ação conhecidamente proibida é negada, então um recibo assinado faz round-trip e uma cópia adulterada falha.

Aponte qualquer host MCP para ele, por exemplo Claude Desktop:```json
{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Os recibos são compatíveis byte a byte com os que o gate assina em tempo de execução, portanto um recibo emitido aqui é verificado com @veritasacta/verify e o verificador do navegador da mesma forma.

Painel de Ações Local

protect-mcp dashboard é a visão do operador para passar da visibilidade à aplicação:

• Inventário de ferramentas: cada ferramenta observada, contagem de chamadas, risco alto/médio/baixo e se a política ativa tem uma regra exata, um fallback com wildcard ou nenhuma regra.
• Cobertura de política: edições de política local com um clique para Require approval, Block ou Observe. Reinicie o wrapper após revisar as alterações.
• Fila de aprovação de ação exata: a ferramenta exata, ação, destino, pré-visualização de payload redigido, hash do payload, base da política e captura do motivo antes que um humano aprove, negue, edite ou assuma o controle.
• Cadeia de recibos: ids de requisição correlacionados com hashes de recibos assinados, para que um revisor de auditoria possa ver quais decisões têm prova criptográfica.
• Exportação de auditoria: baixa o pacote de auditoria verificável offline quando existem recibos assinados. Se existirem apenas logs locais não assinados, o painel explica que a assinatura deve ser habilitada primeiro.

Para aprovações de fallback em desktop ao vivo, inicie o painel com o endpoint de aprovação do gateway local e o nonce impresso pelo wrapper:```bash npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"

`Approve` encaminha para o gateway local ativo quando esses sinalizadores estão presentes.
`Deny`, `Edit` e `Take over` são registrados localmente como registros de
resolução de aprovação; use-os como a instrução do operador e execute novamente a ferramenta quando necessário.

### MVP de Fronteira Paga: ancoragem de digest, não upload de dados

Recibos autoassinados locais permanecem gratuitos e verificáveis offline. A fronteira paga é
evidência independente de que o ScopeBlind viu um digest de recibo em um momento, sob uma identidade
de organização, sem receber o prompt bruto, o payload da ferramenta, a saída, a chave privada ou o
recibo bruto.```bash
# Create or refresh a local org identity and public-key directory.
npx protect-mcp registry init --org "Meridian Global Macro" --billing-account acct_meridian

# Local preview: writes a digest registry and shareable static verifier page.
npx protect-mcp registry anchor

# Hosted mode: uploads receipt digests only for independent anchoring.
SCOPEBLIND_TOKEN=... npx protect-mcp registry anchor \
  --hosted \
  --endpoint https://api.scopeblind.com \
  --verifier-base https://scopeblind.com

O preview local é deliberadamente rotulado como local-preview-not-independent. O modo hospedado ancora apenas hashes de recibo, ids de requisição, chaves públicas da organização e metadados de faturamento. Ele não faz upload de recibos brutos ou contexto sensível.

Killer Demo: shadow to policy to proof

protect-mcp killer-demo gera um pacote completo de vendas/demo de três minutos:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

Ele cria um filesystem simulado, atividade de GitHub, email e PMS; mostra chamadas de risco em
modo shadow; aplica um policy pack; exige aprovação para um agendamento de PMS sensível;
executa através do gateway; escreve um recibo assinado; prova que o recibo
original verifica; prova que um recibo adulterado falha; e cria um pacote de divulgação
seletiva que oculta contexto sensível enquanto mostra a prova mínima.