mcp-guard

Servidor MCP: remove segredos dos resultados das ferramentas, protege contra injeção de prompt e bloqueia gravações do agente em caminhos sensíveis.

GitHub

Documentação

mcp-guard 🛡️

O firewall local de privacidade, escudo contra injeção de prompts, sanitizador de segredos e compressor de tokens para agentes de codificação com IA.

Um proxy de segurança sem dependências para servidores Model Context Protocol (MCP).

mcp-guard demo

mcp-guard é um binário Go ultra-rápido, sem dependências, que fica transparentemente entre seu editor (Claude Code, Cursor, VS Code, Copilot) e qualquer servidor Model Context Protocol (MCP) — via stdio ou HTTP/SSE.

Ele garante que suas chaves de API, credenciais de banco de dados e caminhos protegidos (~/.ssh, .env, .git) nunca vazem para LLMs na nuvem, que conteúdo malicioso não possa sequestrar seu agente, e que a execução autônoma de ferramentas não possa tocar no que não deveria — tudo isso enquanto reduz o gasto de tokens.

💡 Por que mcp-guard?

Quando agentes de IA executam ferramentas como @modelcontextprotocol/server-filesystem ou postgres-mcp, eles leem arquivos brutos e resultados de consultas diretamente da sua máquina. Três coisas dão errado:

Vazamento de segredos. Um arquivo com chaves AWS, JWTs ou senhas de banco de dados é enviado integralmente para um LLM na nuvem.
Agentes sequestrados. Um arquivo ou página web pode conter instruções ocultas — Unicode invisível ou "ignore todas as instruções anteriores" — que o modelo obedece (injeção de prompt / envenenamento de ferramenta).
Agentes excedem limites. Um agente autônomo sobrescreve ~/.ssh/authorized_keys, canaliza curl … | bash, ou lê 100 arquivos em uma rajada.

mcp-guard roda localmente e corrige os três problemas sem quebrar a execução do agente:

🔒 Inspeção de I/O com Confiança Zero — intercepta tanto requisições quanto respostas em todos os transportes.
⚡ Binário Go sem Dependências — biblioteca padrão pura, sobrecarga de submilissegundo.
🔄 Erros de Guardrail Recuperáveis — retorna resultados estruturados isError: true para que os agentes se autocorrijam em vez de travar.
📊 Valor Visível — um resumo da sessão mostra exatamente o que foi protegido e quantos tokens/dólares foram economizados.

🎯 Modelo de Ameaças — o que isso substitui e o que não substitui

mcp-guard é defesa em profundidade para a fronteira do agente, não um substituto para boas práticas de higiene de segurança. Ser preciso sobre isso importa mais do que parecer impressionante.

O que ele aborda

Risco	Como o `mcp-guard` lida com isso
Dados sensíveis saindo da sua máquina quando um agente lê um arquivo ou resultado de consulta	Redigidos antes de chegarem ao modelo
Instruções injetadas no conteúdo que seu agente consome (arquivos, páginas web, descrições de ferramentas)	Unicode oculto removido, diretivas neutralizadas
Um agente escrevendo em caminhos que nunca deveria tocar	Bloqueado, inclusive via travessia `../` e symlinks
Um agente descontrolado ou comprometido enumerando seu sistema de arquivos	Limitado por taxa, rajadas de leitura sinalizadas
Nenhum registro de tudo isso	Cada ação auditada no stderr (texto ou JSON Lines)

O que ele explicitamente não substitui

Credenciais de curta duração. Se você pode usar federação STS / OIDC / SSO, faça isso primeiro — é o controle mais forte. A rotação reduz o raio de impacto; o mcp-guard reduz a chance de divulgação em primeiro lugar. Eles resolvem metades diferentes, e a correção de credenciais é a mais importante.
Um gerenciador de segredos ou IAM com privilégio mínimo. Uma chave que nunca esteve no disco não pode ser lida do disco.
Revisar o que seu agente realmente faz. Guardrails limitam o raio de impacto; eles não tornam um agente não revisado confiável.

Limitações conhecidas — leia antes de confiar nele

A detecção é heurística. A correspondência de padrões nomeados de segredos é de alta precisão e mascara por padrão; o mecanismo abrangente de entropia é de menor precisão (ele dispara em hashes de integridade e fixtures base64), então é somente auditoria por padrão e só mascara quando você opta por isso. A detecção de injeção é baseada em assinaturas. Um formato de credencial novo ou uma injeção cuidadosamente redigida passará — trate-o como uma camada, não como uma garantia.
Ele só vê o tráfego que passa por ele. Um servidor MCP que faz suas próprias chamadas de rede de saída (um servidor estilo fetch, telemetria, um phone-home) é invisível para o mcp-guard. Ele protege o canal cliente↔servidor, não o egresso do próprio servidor.
A verificação de segredos no lado da requisição avisa, não bloqueia. Algumas ferramentas legitimamente precisam de credenciais em seus argumentos, então bloquear por padrão as quebraria.
A compressão pode alterar texto. Ela está desligada por padrão e pula ferramentas de leitura-para-edição, porque reescrever um arquivo que o agente está prestes a corrigir corrompe o diff.
Ele não autentica o servidor MCP. Um servidor malicioso ainda pode retornar respostas erradas (embora sanitizadas). A defesa contra injeção reduz esse risco; não o elimina.

Se você encontrar um caso em que um segredo real ou payload de injeção passe despercebido, isso é um bug que vale a pena abrir uma issue — falsos negativos e falsos positivos são ambos regressões.

🏗️ Arquitetura

┌─────────────────────────┐          ┌────────────────────────────────────┐          ┌─────────────────────────┐
│                         │  request │             mcp-guard              │  request │                         │
│  Editor / MCP Client    ├─────────►│  ┌──────────────────────────────┐  ├─────────►│       MCP Server        │
│                         │          │  │ →  guardrails · shell block   │  │          │  (filesystem, postgres, │
│  (Claude Code / Cursor  │          │  │    rate-limit · req-secrets   │  │          │   github, http, …)      │
│   / VS Code / Copilot)  │◄─────────┤  │ ←  redact · entropy · inject  │  │◄─────────┤                         │
│                         │ response │  │    defense · compression      │  │ response │                         │
└─────────────────────────┘          │  └──────────────────────────────┘  │          └─────────────────────────┘
                                      │   stdio  ·  HTTP / SSE  ·  audit    │
                                      └────────────────────────────────────┘

✨ Recursos

1. 🔑 Redação de Segredos e Credenciais (Servidor ➔ Cliente)

Verifica cada string em um resultado de ferramenta — incluindo espelhos structuredContent e descrições de ferramentas — em busca de 12+ formatos de credenciais antes que cheguem ao LLM:

Chaves de nuvem e IA: AWS (AKIA…), Anthropic, OpenAI, Stripe, Google, Slack, PATs do GitHub.
URIs de banco de dados: mascara a senha em postgres://user:pass@host, mongodb+srv://, redis://:pass@host — até senhas contendo @.
Chaves privadas e JWTs: mascaramento de bloco completo para chaves RSA/PEM e tokens Bearer.
🆕 Mecanismo abrangente de alta entropia (somente auditoria por padrão): uma passagem de entropia de Shannon sinaliza segredos gerados de formato desconhecido que não correspondem a nenhum padrão nomeado, usando um discriminador de classe de caracteres para evitar SHAs do git, UUIDs e caminhos de arquivo. Como a heurística também dispara em hashes de integridade, fixtures base64 e URLs assinadas, ela relata por padrão (registrando o detector e os offsets de bytes) e só mascara quando você opta com --entropy-mask ou --profile strict. Isso evita corromper silenciosamente dados estruturados válidos.

# Before mcp-guard:
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
DATABASE_URL=postgres://admin:P@ssw0rd123!@db.internal:5432/prod
SESSION=nQ7wLp4sZa1cFd8gHj0tYuXk9mR2vB3E

# After mcp-guard:
AWS_ACCESS_KEY_ID=[REDACTED:aws-access-key]
DATABASE_URL=postgres://admin:[REDACTED:uri-credentials]@db.internal:5432/prod
SESSION=[REDACTED:high-entropy]   # entropy match — masked under --entropy-mask / --profile strict;
                                  # audit-only (logged, not masked) by default

2. 🧬 Defesa contra Injeção de Prompt e Envenenamento de Ferramenta 🆕

Conteúdo que volta do servidor (corpos de arquivos, páginas web, até as próprias descrições de ferramentas de um servidor malicioso) pode carregar instruções direcionadas ao seu agente. O mcp-guard neutraliza ambos os vetores:

Unicode oculto — remove caracteres invisíveis de "etiqueta" (bloco U+E0000 usado para contrabandear ASCII invisível), controles de override bidirecional e espaços de largura zero. Joiners legítimos de script/emoji são preservados.
Diretivas de injeção — frases de alto sinal como "ignore todas as instruções anteriores", "não conte ao usuário" ou "revele seu prompt de sistema" são substituídas por um marcador visível [mcp-guard: neutralized-injection] (ou somente detecção, à sua escolha).

3. 🛡️ Guardrails de Diretório e Proteção contra Escrita (Cliente ➔ Servidor)

Bloqueia agentes de modificar caminhos protegidos — através de travessia relativa (../.ssh) e escapes de symlink 🆕 (um link project/data → ~/.ssh é resolvido e capturado):

Diretórios protegidos (em qualquer lugar do caminho): ~/.ssh, .aws, .gnupg, .kube, .git, .env*
Arquivos sensíveis: id_rsa, id_ed25519, authorized_keys, .npmrc, .netrc, .pypirc, .dockercfg
Bloqueio de scripts shell: recusa padrões *.sh/*.ps1, bash -c e curl … | sh por padrão.
🆕 Bloqueio opcional de leitura sensível: bloqueia leituras de caminhos protegidos (padrão: permite a leitura e redige seu conteúdo).

4. 🚦 Guardrails de Exfiltração e Anomalias 🆕

Uma camada comportamental sobre as verificações por chamada:

Limitação de taxa — limita agentes descontrolados ou comprometidos além de um limite de chamadas por minuto.
Detecção de rajada de leitura — avisa sobre um pico repentino de leituras de arquivos distintos (uma assinatura clássica de exfiltração em massa).
Verificação de segredos de saída — avisa quando os argumentos de uma chamada de ferramenta carregam dados com formato de segredo, para que uma chave que o agente acabou de ler não possa ser silenciosamente encaminhada para um servidor phone-home despercebido.

5. ⚡ Compressão de Tokens de Contexto (Opt-In)

Remove comentários e espaços redundantes para economizar capacidade da janela de contexto, com um estimador de tokens ciente de código para contabilidade precisa.

A compressão automaticamente pula ferramentas de leitura-para-edição (read_file, get_file_contents) para preservar limites exatos de diff para edição segura de arquivos.

6. 📊 Resumo de Sessão e Auditoria Estruturada 🆕

Na saída (e no SIGUSR1) o mcp-guard imprime um resumo: segredos redigidos por tipo, escritas/leituras/shell bloqueados, injeções neutralizadas, tokens economizados e um $ economizado estimado.
Toda a atividade flui para o stderr como texto humano ou JSON Lines (--log-format json) para ingestão em SIEM. O stdout carrega apenas o protocolo MCP.

mcp-guard session summary
  secrets redacted       4
      aws-access-key     1
      uri-credentials    1
      high-entropy       2
  writes blocked         1
  injections neutralized 3
  tokens saved           1840
  est. cost saved        $0.0055

7. 🎛️ Perfis de Política e Recarga a Quente 🆕

Perfis aplicam rigor por servidor em uma única flag: --profile strict|standard|permissive (ex.: bloquear um servidor shell, relaxar um servidor de docs somente leitura).
Recarga a quente — envie SIGHUP para reler a configuração e trocar a política ao vivo, sem derrubar a conexão do agente.

🚀 Instalação

Binário pré-compilado (sem necessidade de toolchain Go) — pegue-o na última versão:

# macOS (Apple Silicon) — swap darwin_arm64 for your platform
curl -sSL https://github.com/sainitish1609/mcp-guard/releases/latest/download/mcp-guard_darwin_arm64.tar.gz | tar xz
sudo mv mcp-guard /usr/local/bin/

Com Go:

go install github.com/sainitish1609/mcp-guard/cmd/mcp-guard@latest

A partir do código-fonte:

git clone https://github.com/sainitish1609/mcp-guard.git
cd mcp-guard
go build -o mcp-guard ./cmd/mcp-guard

Builds para macOS, Linux e Windows (amd64 + arm64). Toda proteção funciona em todas as plataformas; os hooks de sinal SIGHUP/SIGUSR1 são exclusivos do Unix, e o resumo de fim de sessão ainda é impresso na saída em todos os lugares.

⚙️ Configuração e Integração

Claude Code

Envolva qualquer comando de servidor MCP padrão usando mcp-guard --:

claude mcp add postgres -- mcp-guard --profile strict --max-tokens 4000 -- npx -y @modelcontextprotocol/server-postgres

Cursor / VS Code (`.vscode/mcp.json`)

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-guard",
      "args": [
        "--redact-secrets",
        "--scan-injection",
        "--block-shell",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

🌐 HTTP / SSE (servidores remotos)

Proteja um servidor MCP remoto que fala Streamable-HTTP/SSE — mesmo pipeline, sem processo filho:

mcp-guard --profile strict --http-listen :8080 --http-upstream https://my-mcp-host.example/mcp

Aponte seu cliente para http://localhost:8080 e cada mensagem JSON e SSE é inspecionada em voo.

📋 Referência de Flags

Flag	Padrão	Descrição
`--profile`	(nenhum)	Predefinição de política: `strict` \| `standard` \| `permissive`
`--redact-secrets`	`true`	Mascara chaves de API, tokens e senhas de banco de dados nos resultados
`--entropy-scan`	`true`	Sinaliza tokens de alta entropia que não correspondem a nenhum padrão conhecido (somente auditoria, a menos que `--entropy-mask`)
`--entropy-mask`	`false`	Mascara descobertas de entropia em vez de apenas auditá-las (mais ruidoso: hashes, base64, URLs assinadas)
`--scan-injection`	`true`	Remove Unicode oculto e neutraliza diretivas de injeção de prompt
`--neutralize-injection`	`true`	Reescreve diretivas detectadas (desativado = detectar + registrar apenas)
`--scan-requests`	`true`	Avisa quando argumentos de chamadas de ferramentas de saída contêm segredos
`--block-shell`	`true`	Bloqueia a execução de scripts de shell em ferramentas do tipo exec
`--block-sensitive-reads`	`false`	Bloqueia leituras de caminhos protegidos (padrão: permitir + redigir)
`--rate-limit N`	`0`	Máximo de chamadas de ferramentas/min antes da limitação (0 = desativado)
`--annotate-tools`	`true`	Anexa avisos de política a `tools/list` para que os agentes conheçam os limites
`--compress`	`false`	Remove comentários e linhas em branco do contexto (somente ferramentas seguras)
`--max-tokens N`	`0`	Limite aproximado de orçamento de tokens por bloco de resultado (0 = ilimitado)
`--protect-paths`	(padrões)	Caminhos protegidos separados por vírgula (substitui os padrões)
`--protect-names`	(padrões)	Segmentos de caminho protegidos separados por vírgula (substitui os padrões)
`--allow-shell`	(nenhum)	Substrings de lista de permissões separadas por vírgula para comandos de shell
`--stats`	`true`	Imprime um resumo da sessão ao sair e em `SIGUSR1`
`--price-per-1k`	`0.003`	USD por 1K tokens para a estimativa de custo economizado
`--log-level`	`info`	Verbosidade: `silent` \| `error` \| `info` \| `debug` (stderr)
`--log-format`	`text`	Formato de log: `text` \| `json` (JSON Lines)
`--dry-run`	`false`	Registra eventos sem alterar o fluxo
`--http-listen`	(nenhum)	Executa como um proxy HTTP/SSE neste endereço (ex.: `:8080`)
`--http-upstream`	(nenhum)	URL do servidor MCP upstream para o modo HTTP/SSE
`--config`	(nenhum)	Caminho para um arquivo de configuração JSON (opcional)

Sinais: SIGHUP recarrega a configuração ao vivo · SIGUSR1 imprime um resumo intermediário da sessão.

🧪 Testes e Verificação

# Run unit and integration tests
go test ./... -v

# Run static analysis
go vet ./...

Experimente de ponta a ponta contra um servidor real:

printf '%s\n%s\n' \
'{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}' \
'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":"/path/to/a/.env"}}}' \
| mcp-guard --profile strict -- npx -y @modelcontextprotocol/server-filesystem /path/to

📄 Licença

Distribuído sob a Licença MIT. Consulte LICENSE para obter detalhes.