Governança de Agentes MCP com protect-mcp

Visão Geral

Orientações para governar chamadas de ferramentas de agentes de IA usando políticas Cedar e recibos assinados Ed25519. Esta habilidade ensina como escrever políticas de controle de acesso para servidores MCP, executá-las em modo de sombra para observação e verificar a trilha de auditoria criptográfica.

Quando Usar Esta Habilidade

• Use quando precisar controlar quais ferramentas MCP um agente pode chamar e sob quais condições
• Use quando quiser uma trilha de auditoria à prova de adulteração para execuções de ferramentas de agente
• Use ao implementar políticas de governança gradualmente (modo de sombra primeiro, depois aplicar)
• Use ao criar políticas Cedar para controle de acesso a ferramentas MCP
• Use ao verificar se um recibo ou pacote de auditoria não foi adulterado

Não Use Esta Habilidade

• Quando precisar de auditoria geral de segurança de aplicativos (use @security-auditor)
• Quando precisar verificar código em busca de vulnerabilidades (use @security-audit)
• Quando precisar de orientação sobre frameworks de conformidade sem governança específica para agentes

Como Funciona

protect-mcp intercepta chamadas de ferramentas MCP, as avalia contra políticas Cedar (o mesmo mecanismo de política usado pelo AWS Verified Permissions) e assina cada decisão como um recibo Ed25519. O recibo é uma prova criptográfica de que uma política específica foi avaliada contra uma chamada de ferramenta específica em um momento específico.

Agent → protect-mcp → Cedar policy evaluation → MCP Server
                ↓
        Ed25519 signed receipt

Três modos de operação:

1. Modo de Sombra (padrão) — registra decisões sem bloquear. Use isso para observar o que suas políticas fariam antes de aplicá-las.
2. Modo de Aplicação — bloqueia chamadas de ferramentas que violam a política. Use após a validação em modo de sombra.
3. Modo de Hooks — integra-se com hooks do Claude Code para governança pré/pós-chamada de ferramenta.

Conceitos Principais

Políticas Cedar

Cedar é uma linguagem de política projetada para autorização. As políticas são avaliadas localmente via WASM — sem necessidade de chamadas de rede.

// Allow read-only file operations
permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name in ["read_file", "list_directory", "search_files"]
};

// Deny destructive operations
forbid(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name in ["execute_command", "delete_file", "write_file"]
  && resource has args
  && resource.args.contains("rm -rf")
};

Recibos Assinados

Cada decisão de política produz um recibo assinado:

{
  "payload": {
    "type": "protectmcp:decision",
    "tool_name": "read_file",
    "decision": "allow",
    "policy_digest": "sha256:9d0fd4c9e72c1d5d",
    "issued_at": "2026-04-05T14:32:04.102Z",
    "issuer_id": "sb:issuer:de073ae64e43"
  },
  "signature": {
    "alg": "EdDSA",
    "kid": "sb:issuer:de073ae64e43",
    "sig": "2a3b5022..."
  }
}

O formato do recibo segue o IETF Internet-Draft draft-farley-acta-signed-receipts.

Guia Passo a Passo

1. Inicialize a Governança para um Projeto

# Install and initialize hooks (Claude Code integration)
npx protect-mcp init-hooks

# Or run as a standalone MCP gateway
npx protect-mcp serve

Isso cria um protect-mcp.config.json e uma política Cedar inicial na raiz do seu projeto.

2. Escreva Sua Primeira Política

Crie policy.cedar em seu projeto:

// Start permissive — allow everything in shadow mode
permit(
  principal,
  action == Action::"call_tool",
  resource
);

3. Execute em Modo de Sombra (Observe Primeiro)

# Shadow mode is the default — logs decisions without blocking
npx protect-mcp --policy policy.cedar -- node your-mcp-server.js

Revise o log de sombra para entender o que seu agente está fazendo antes de escrever políticas restritivas.

4. Aperte e Aplique

Assim que entender os padrões de chamada de ferramentas, escreva políticas específicas:

// Allow file reads, deny writes outside src/
permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name == "read_file"
};

permit(
  principal,
  action == Action::"call_tool",
  resource
) when {
  resource.tool_name == "write_file"
  && resource has args
  && resource.args.path like "src/*"
};

// Deny everything else
forbid(
  principal,
  action == Action::"call_tool",
  resource
);

Mude para o modo de aplicação:

npx protect-mcp --policy policy.cedar --enforce -- node your-mcp-server.js

5. Verifique Recibos

# Verifique um único recibo

…