mcp-guard

Servidor MCP: redacta secretos de los resultados de las herramientas, defiende contra la inyección de prompts y bloquea escrituras del agente en rutas sensibles.

GitHub

Documentación

mcp-guard 🛡️

El cortafuegos local de privacidad, escudo contra inyección de instrucciones, sanitizador de secretos y compresor de tokens para agentes de codificación con IA.

Un proxy de seguridad sin dependencias para servidores del Protocolo de Contexto de Modelos (MCP).

mcp-guard demo

mcp-guard es un binario Go ultrarrápido y sin dependencias que se sitúa de forma transparente entre tu editor (Claude Code, Cursor, VS Code, Copilot) y cualquier servidor del Protocolo de Contexto de Modelos (MCP) — a través de stdio o HTTP/SSE.

Garantiza que tus claves API, credenciales de bases de datos y rutas protegidas (~/.ssh, .env, .git) nunca se filtren a los LLM en la nube, que el contenido malicioso no pueda secuestrar tu agente, y que la ejecución autónoma de herramientas no pueda tocar lo que no debería — todo mientras reduce el gasto de tokens.

💡 ¿Por qué mcp-guard?

Cuando los agentes de IA ejecutan herramientas como @modelcontextprotocol/server-filesystem o postgres-mcp, leen archivos sin procesar y resultados de consultas directamente desde tu máquina. Tres cosas salen mal:

Fuga de secretos. Un archivo con claves AWS, JWT o contraseñas de bases de datos se envía textualmente a un LLM en la nube.
Secuestro de agentes. Un archivo o página web puede contener instrucciones ocultas — Unicode invisible o "ignora todas las instrucciones anteriores" — que el modelo obedece (inyección de instrucciones / envenenamiento de herramientas).
Exceso de alcance del agente. Un agente autónomo sobrescribe ~/.ssh/authorized_keys, canaliza curl … | bash, o lee 100 archivos en una ráfaga.

mcp-guard se ejecuta localmente y soluciona los tres problemas sin romper la ejecución del agente:

🔒 Inspección de E/S de Confianza Cero — intercepta tanto solicitudes como respuestas en cada transporte.
⚡ Binario Go sin dependencias — biblioteca estándar pura, sobrecarga de sub-milisegundos.
🔄 Errores de protección recuperables — devuelve resultados estructurados de isError: true para que los agentes se autocorrijan en lugar de fallar.
📊 Valor visible — un resumen de sesión muestra exactamente qué protegió y cuántos tokens/dólares ahorró.

🎯 Modelo de amenazas — qué reemplaza y qué no

mcp-guard es defensa en profundidad para el límite del agente, no un reemplazo de una buena higiene de seguridad. Ser preciso al respecto importa más que sonar impresionante.

Qué aborda

Riesgo	Cómo lo maneja `mcp-guard`
Datos sensibles que salen de tu máquina cuando un agente lee un archivo o resultado de consulta	Redactados antes de llegar al modelo
Instrucciones inyectadas en el contenido que tu agente consume (archivos, páginas web, descripciones de herramientas)	Unicode oculto eliminado, directivas neutralizadas
Un agente que escribe en rutas que nunca debió tocar	Bloqueado, incluso mediante traversal de `../` y enlaces simbólicos
Un agente descontrolado o comprometido que enumera tu sistema de archivos	Limitado por tasa, ráfagas de lectura marcadas
Sin registro de todo lo anterior	Cada acción auditada en stderr (texto o JSON Lines)

Qué explícitamente no reemplaza

Credenciales de corta duración. Si puedes usar federación STS / OIDC / SSO, hazlo primero — es el control más fuerte. La rotación reduce el radio de explosión; mcp-guard reduce la probabilidad de divulgación en primer lugar. Resuelven mitades diferentes, y la corrección de credenciales es la más importante.
Un gestor de secretos o IAM de menor privilegio. Una clave que nunca estuvo en disco no puede leerse del disco.
Revisar lo que tu agente realmente hace. Las protecciones limitan el radio de explosión; no hacen confiable a un agente no revisado.

Limitaciones conocidas — léelas antes de confiar en ello

La detección es heurística. La coincidencia de secretos por patrones nombrados es de alta precisión y enmascara por defecto; el captador de entropía es de menor precisión (se activa con hashes de integridad y fixtures base64), por lo que es solo auditoría por defecto y solo enmascara cuando optas por ello. La detección de inyección se basa en firmas. Un formato de credencial novedoso o una inyección cuidadosamente redactada pasará — trátalo como una capa, no como una garantía.
Solo ve el tráfico que fluye a través de él. Un servidor MCP que realiza sus propias llamadas de red salientes (un servidor estilo fetch, telemetría, un phone-home) es invisible para mcp-guard. Asegura el canal cliente↔servidor, no la salida propia del servidor.
El escaneo de secretos en solicitudes advierte, no bloquea. Algunas herramientas necesitan legítimamente credenciales en sus argumentos, por lo que bloquear por defecto las rompería.
La compresión puede alterar el texto. Está desactivada por defecto y omite herramientas de lectura-para-edición, porque reescribir un archivo que el agente está a punto de parchear corrompe el diff.
No autentica el servidor MCP. Un servidor malicioso aún puede devolver respuestas incorrectas (aunque sanitizadas). La defensa contra inyección reduce ese riesgo; no lo elimina.

Si encuentras un caso donde un secreto real o payload de inyección se cuela, es un error que vale la pena abrir un issue — tanto los falsos negativos como los falsos positivos son regresiones.

🏗️ Arquitectura

┌─────────────────────────┐          ┌────────────────────────────────────┐          ┌─────────────────────────┐
│                         │  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    │
                                      └────────────────────────────────────┘

✨ Características

1. 🔑 Redacción de Secretos y Credenciales (Servidor ➔ Cliente)

Escanea cada cadena en un resultado de herramienta — incluyendo espejos de structuredContent y descripciones de herramientas — en busca de más de 12 formatos de credenciales antes de que lleguen al LLM:

Claves de nube e IA: AWS (AKIA…), Anthropic, OpenAI, Stripe, Google, Slack, PATs de GitHub.
URIs de bases de datos: enmascara la contraseña en postgres://user:pass@host, mongodb+srv://, redis://:pass@host — incluso contraseñas que contienen @.
Claves privadas y JWTs: enmascaramiento de bloque completo para claves RSA/PEM y tokens Bearer.
🆕 Captador de alta entropía (solo auditoría por defecto): un paso de entropía de Shannon marca secretos generados de formato desconocido que no coinciden con ningún patrón nombrado, usando un discriminador de clases de caracteres para evitar SHAs de git, UUIDs y rutas de archivos. Como la heurística también se activa con hashes de integridad, fixtures base64 y URLs firmadas, informa por defecto (registrando el detector y los desplazamientos de bytes) y solo enmascara cuando optas con --entropy-mask o --profile strict. Esto evita corromper silenciosamente datos estructurados 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. 🧬 Defensa contra Inyección de Instrucciones y Envenenamiento de Herramientas 🆕

El contenido que regresa de un servidor (cuerpos de archivos, páginas web, incluso las descripciones de herramientas de un servidor malicioso) puede llevar instrucciones dirigidas a tu agente. mcp-guard neutraliza ambos vectores:

Unicode oculto — elimina caracteres "etiqueta" invisibles (bloque U+E0000 usado para contrabandear ASCII invisible), controles de anulación bidireccional y espacios de ancho cero. Los joiners legítimos de scripts/emojis se conservan.
Directivas de inyección — frases de alta señal como "ignora todas las instrucciones anteriores", "no le digas al usuario" o "revela tu prompt de sistema" se reemplazan con un marcador visible de [mcp-guard: neutralized-injection] (o solo detección, a tu elección).

3. 🛡️ Protecciones de Directorio y Protección contra Escritura (Cliente ➔ Servidor)

Bloquea a los agentes de modificar rutas protegidas — mediante traversal relativo (../.ssh) y escapes de enlaces simbólicos 🆕 (un enlace project/data → ~/.ssh se resuelve y se detecta):

Directorios protegidos (en cualquier parte de la ruta): ~/.ssh, .aws, .gnupg, .kube, .git, .env*
Archivos sensibles: id_rsa, id_ed25519, authorized_keys, .npmrc, .netrc, .pypirc, .dockercfg
Bloqueo de scripts de shell: rechaza patrones de *.sh/*.ps1, bash -c y curl … | sh por defecto.
🆕 Bloqueo opcional de lecturas sensibles: bloqueo duro de lecturas de rutas protegidas (por defecto: permite la lectura y redacta su contenido).

4. 🚦 Protecciones contra Exfiltración y Anomalías 🆕

Una capa de comportamiento sobre las verificaciones por llamada:

Limitación de tasa — limita agentes descontrolados o comprometidos más allá de un máximo de llamadas por minuto.
Detección de ráfagas de lectura — advierte sobre un pico repentino de lecturas de archivos distintos (una firma clásica de exfiltración masiva).
Escaneo de secretos salientes — advierte cuando los argumentos de una llamada de herramienta llevan datos con forma de secreto, para que una clave que el agente acaba de leer no pueda reenviarse silenciosamente a un servidor phone-home sin ser notado.

5. ⚡ Compresión de Tokens de Contexto (Opt-In)

Elimina comentarios redundantes y espacios en blanco para ahorrar capacidad de ventana de contexto, con un estimador de tokens consciente del código para una contabilidad precisa.

La compresión omite automáticamente las herramientas de lectura-para-edición (read_file, get_file_contents) para preservar los límites exactos del diff para una edición segura de archivos.

6. 📊 Resumen de Sesión y Auditoría Estructurada 🆕

Al salir (y en SIGUSR1) mcp-guard imprime un resumen: secretos redactados por tipo, escrituras/lecturas/shell bloqueados, inyecciones neutralizadas, tokens ahorrados y un $ estimado ahorrado.
Toda la actividad se transmite a stderr como texto humano o JSON Lines (--log-format json) para ingestión en SIEM. stdout lleva solo el 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. 🎛️ Perfiles de Política y Recarga en Caliente 🆕

Perfiles aplican estrictez por servidor en una sola bandera: --profile strict|standard|permissive (p. ej., bloquear un servidor de shell, relajar un servidor de documentación de solo lectura).
Recarga en caliente — envía SIGHUP para releer la configuración y cambiar la política en vivo, sin interrumpir la conexión del agente.

🚀 Instalación

Binario precompilado (sin necesidad de toolchain de Go) — descárgalo de la última versión:

# 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/

Con Go:

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

Desde el código fuente:

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

Compilaciones para macOS, Linux y Windows (amd64 + arm64). Cada protección funciona en todas las plataformas; los enlaces de señales SIGHUP/SIGUSR1 son solo Unix, y el resumen de fin de sesión aún se imprime al salir en todas partes.

⚙️ Configuración e Integración

Claude Code

Envuelve cualquier comando estándar de servidor MCP 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)

Protege un servidor MCP remoto que hable Streamable-HTTP/SSE — mismo pipeline, sin proceso hijo:

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

Apunta tu cliente a http://localhost:8080 y cada mensaje JSON y SSE se inspecciona en vuelo.

📋 Referencia de Banderas

Flag	Default	Descripción
`--profile`	(ninguno)	Preset de política: `strict` \| `standard` \| `permissive`
`--redact-secrets`	`true`	Enmascarar claves de API, tokens y contraseñas de bases de datos en los resultados
`--entropy-scan`	`true`	Marcar tokens de alta entropía que no coinciden con ningún patrón conocido (solo auditoría a menos que `--entropy-mask`)
`--entropy-mask`	`false`	Enmascarar hallazgos de entropía en lugar de solo auditarlos (más ruidoso: hashes, base64, URLs firmadas)
`--scan-injection`	`true`	Eliminar Unicode oculto y neutralizar directivas de inyección de prompts
`--neutralize-injection`	`true`	Reescribir directivas detectadas (desactivado = detectar y registrar solo)
`--scan-requests`	`true`	Advertir cuando los argumentos de llamadas a herramientas salientes contengan secretos
`--block-shell`	`true`	Bloquear la ejecución de scripts de shell en herramientas similares a exec
`--block-sensitive-reads`	`false`	Bloquear lecturas de rutas protegidas (predeterminado: permitir + redactar)
`--rate-limit N`	`0`	Máximo de llamadas a herramientas por minuto antes de limitar (0 = deshabilitado)
`--annotate-tools`	`true`	Añadir avisos de política a `tools/list` para que los agentes conozcan los límites
`--compress`	`false`	Eliminar comentarios y líneas en blanco del contexto (solo herramientas seguras)
`--max-tokens N`	`0`	Límite aproximado de presupuesto de tokens por bloque de resultados (0 = ilimitado)
`--protect-paths`	(predeterminados)	Rutas protegidas separadas por comas (anula los predeterminados)
`--protect-names`	(predeterminados)	Segmentos de rutas protegidas separados por comas (anula los predeterminados)
`--allow-shell`	(ninguno)	Subcadenas de lista blanca separadas por comas para comandos de shell
`--stats`	`true`	Imprimir un resumen de sesión al salir y en `SIGUSR1`
`--price-per-1k`	`0.003`	USD por 1K tokens para la estimación de costo ahorrado
`--log-level`	`info`	Verbosidad: `silent` \| `error` \| `info` \| `debug` (stderr)
`--log-format`	`text`	Formato de registro: `text` \| `json` (JSON Lines)
`--dry-run`	`false`	Registrar eventos sin mutar el flujo
`--http-listen`	(ninguno)	Ejecutar como proxy HTTP/SSE en esta dirección (p. ej. `:8080`)
`--http-upstream`	(ninguno)	URL del servidor MCP ascendente para modo HTTP/SSE
`--config`	(ninguno)	Ruta a un archivo de configuración JSON (opcional)

Señales: SIGHUP recarga la configuración en vivo · SIGUSR1 imprime un resumen de sesión intermedio.

🧪 Pruebas y Verificación

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

# Run static analysis
go vet ./...

Pruébalo de extremo a extremo contra un 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

📄 Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más detalles.