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:

Ataque	Cómo funciona
Envenenamiento de herramientas	Instrucciones maliciosas ocultas en la descripción de una herramienta, invisibles en la mayoría de las interfaces de cliente
Cambio de definición	El servidor presenta herramientas inocentes el primer día, y cambia las definiciones después de que las hayas aprobado
Inyección indirecta de prompts	Una página web/issue/email obtenida por una herramienta legítima lleva instrucciones dirigidas al modelo
Exfiltración de secretos	Una credencial filtrada en un resultado de herramienta + una instrucción inyectada = tu clave en el servidor de otro
Bucles descontrolados	Un agente confundido o secuestrado elimina en masa, envía correos en masa, extrae en masa

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 } },