mcp-doorman

La puerta de seguridad para servidores MCP: cada llamada a herramienta se verifica en la entrada.

CI npm Licencia: Apache-2.0 PRs bienvenidos

mcp-doorman es un proxy plug-and-play que se sitúa entre tu agente de IA (Claude Desktop, Claude Code, Cursor, VS Code, cualquier cliente MCP) y los servidores MCP que utiliza. Un solo comando, cero infraestructura, y cada tools/list y tools/call pasa a través de un pipeline de guardia:

• 🛂 Motor de políticas — reglas de permitir / denegar / requerir aprobación por herramienta, con coincidencia por glob
• 🕵️ Redacción de secretos — claves AWS, tokens de GitHub/Slack/Stripe/OpenAI/Anthropic, claves privadas, JWT, tarjetas (con verificación Luhn)… eliminados de los resultados de herramientas antes de que lleguen al modelo
• 💉 Detección de inyección de prompts — marca o bloquea resultados de herramientas (y descripciones de herramientas — envenenamiento de herramientas) que intenten instruir al modelo
• 📌 Detección de cambio de definición — las definiciones de herramientas se fijan mediante hash en el primer uso; si un servidor cambia silenciosamente una descripción, la herramienta se bloquea hasta que un humano la vuelva a fijar
• 🚦 Límite de velocidad — cubos de tokens por herramienta limitan el radio de explosión de un bucle de agente descontrolado
• 🙋 Puertas de aprobación humana — herramientas sensibles activan un prompt de aprobación interactivo mediante elicitation MCP, directamente en tu cliente
• 🧾 Registro de auditoría — cada llamada, denegación, redacción y marca se almacena en un archivo JSONL de solo adición

Por qué existe esto

Todos están a un npx some-random-mcp-server de entregar a un proceso no verificado sus claves API y una línea directa hacia la ventana de contexto de su modelo. Las clases de ataque documentadas son reales, no hipotéticas:

Existen puertas de enlace MCP empresariales para equipos de plataforma con clústeres de Kubernetes. Nada ligero protege la computadora portátil del desarrollador individual, el lugar donde se ejecuta el 99% de los servidores MCP. Ese es el vacío que cubre este proyecto.

Inicio rápido (60 segundos)

# 1. Crear una configuración
npx -y mcp-doorman init

# 2. Editar doorman.config.json — pon tus servidores reales aquí

# 3. Fijar las definiciones actuales de herramientas (confianza en el primer uso)
npx -y mcp-doorman pin --config doorman.config.json

Luego apunta tu cliente a la puerta de enlace en lugar de a tus servidores. Claude Desktop / Claude Code / Cursor:

// ANTES — cada servidor habla directamente con el modelo
{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repos"] }
  }
}

// DESPUÉS — un solo doorman los protege a todos
{
  "mcpServers": {
    "doorman": {
      "command": "npx",
      "args": ["-y", "mcp-doorman", "run", "--config", "/absolute/path/to/doorman.config.json"]
    }
  }
}

Las herramientas aparecen con espacios de nombres como github__create_issue, filesystem__read_file, etc., más dos incorporadas: doorman__status y doorman__recent_events (pregunta a tu agente "¿qué bloqueó doorman recientemente?").

Nota para Windows: si una entrada de servidor usa npx directamente, ejecútalo a través de cmd: "command": "cmd", "args": ["/c", "npx", "-y", "..."].

Verlo en acción

git clone https://github.com/Sushank05/mcp-doorman && cd mcp-doorman
npm install
npm run demo

La demo conecta la puerta de enlace con un servidor deliberadamente mal comportado (examples/demo-server.mjs) que filtra credenciales falsas, sirve una carga útil de inyección de prompts y ofrece una herramienta destructiva — y muestra cómo cada guardia lo detecta.

Cómo funciona

flowchart LR
    A["MCP client\n(Claude Desktop, Cursor, ...)"] -- stdio --> D
    subgraph D [mcp-doorman]
        direction TB
        P[policy] --> R[rate limit] --> AP[approval] --> RD[redaction] --> I[injection scan] --> AU[(audit log)]
    end
    D -- stdio --> S1[github server]
    D -- stdio --> S2[filesystem server]
    D -- streamable HTTP --> S3[remote server]

La puerta de enlace es un servidor MCP hacia tu cliente y un cliente MCP hacia cada servidor ascendente (procesos hijo stdio o endpoints HTTP streamable), agregándolos detrás de una conexión. Está construida sobre el SDK de TypeScript oficial.

Configuración

Todo vive en un único archivo JSON. Ejemplo completo con todas las opciones:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }   // ${VAR} = leer de las variables de entorno de la puerta de enlace
    },
    "remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } }
  },

  "policy": {
    "defaultAction": "allow",                    // "allow" | "deny" | "approve"
    "rules": [                                   // primera coincidencia gana, evaluado de arriba abajo
      { "match": "*__delete*",  "action": "deny",    "reason": "no hay herramientas destructivas" },
      { "match": ["github__create_*", "*__send_*"], "action": "approve" },
      { "match": "filesystem__*", "action": "allow" }
    ]
  },

  "redaction": {
    "enabled": true,
    "disable": [],                               // nombres de reglas integradas para desactivar
    "enableOptIn": ["email"],                    // opt-ins: "email", "us-ssn", "ipv4"
    "custom": [{ "name": "acme-id", "pattern": "ACME-[0-9]{6}" }],
    "redactArguments": false                     // también limpiar argumentos proporcionados por el modelo
  },

  "injection": {
    "action": "flag",                            // "flag" (advertir al modelo) | "block" | "off"
    "scanToolDescriptions": true,                // verificación de envenenamiento de herramientas en tools/list
    "custom": []
  },

  "pinning": {
    "enabled": true,
    "onNewTool": "pin",                          // "pin" (TOFU) | "block" (hasta `mcp-doorman pin`)
    "onChangedTool": "block"                     // "block" | "warn"
  },

  "rateLimit": { "perMinute": 120, "perTool": { "*__send_*": 5 } },

  "approval": { "fallback": "deny", "timeoutMs": 120000 },  // fallback cuando el cliente carece de elicitation

  "audit": { "enabled": true, "includeArguments": true, "includeResults": false },

  "logLevel": "info"
}

El estado de fijación y el registro de auditoría se almacenan por defecto en <config-name>.pins.json / <config-name>.audit.jsonl junto al archivo de configuración.

CLI

Limitaciones honestas

Una herramienta de seguridad que promete de más es peor que ninguna. Lee esta parte.

• Las heurísticas son evitables. Los patrones de inyección detectan formas de ataque documentadas y comunes. Un atacante motivado puede redactar alrededor de cualquier expresión regular. Usa políticas de deny/approve como límite duro; la detección es defensa en profundidad.
• La redacción es de buena fe. Los formatos de token conocidos se detectan de manera confiable; un secreto hexadecimal aleatorio sin contexto no lo es. No apuntes agentes a almacenes de credenciales.
• Esto no es un entorno aislado. Los servidores ascendentes aún se ejecutan como procesos hijo con los privilegios de tu usuario. Doorman protege el protocolo; combínalo con contenedores (al estilo ToolHive) para proteger el proceso.
• TOFU confía en la primera vista. La fijación detecta cambios, no herramientas maliciosas desde el primer día — para eso están el escáner de descripciones y tu propia revisión.
• Las puertas de aprobación necesitan elicitation. Los clientes sin soporte de elicitation recurren a approval.fallback (denegar por defecto).

Hoja de ruta — se necesita ayuda 🙌

• Proxy de resources/* y prompts/* (actualmente solo herramientas)
• Paso directo para muestreo y raíces
• Paquetes de reglas comunitarias (doorman-rules-finance, doorman-rules-healthcare…)
• Modo de aprendizaje: observar durante una semana, proponer una política de mínimo privilegio
• Backends de políticas OPA / Cedar
• Subcomando mcp-doorman audit: imprimir de forma bonita y consultar el registro JSONL
• Panel web para visualización de auditoría
• Detección genérica de secretos basada en entropía

Toma cualquier cosa de arriba, o comienza con un [good first issue](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue). Las nuevas reglas de detección son la contribución más fácil: una expresión regular + dos pruebas. Consulta CONTRIBUTING.md y docs/detection-rules.md.

Desarrollo

npm install
npm test          # 69 pruebas: unitarias + e2e completas sobre stdio
npm run build
npm run demo      # observa las guardias en acción en vivo

Licencia

Apache-2.0 — gratuito para cualquier uso, con una concesión de patente explícita.