mcp-doorman

Il gateway di sicurezza per i server MCP — ogni chiamata di strumento viene controllata all'ingresso.

CI npm Licenza: Apache-2.0 PR benvenuti

mcp-doorman è un proxy drop-in che si posiziona tra il tuo agente AI (Claude Desktop, Claude Code, Cursor, VS Code, qualsiasi client MCP) e i server MCP che utilizza. Un solo comando, zero infrastruttura, e ogni tools/list e tools/call passa attraverso una pipeline di protezione:

• 🛂 Motore di policy — regole allow / deny / require-approval per strumento, con corrispondenza glob
• 🕵️ Rimozione dei segreti — chiavi AWS, token GitHub/Slack/Stripe/OpenAI/Anthropic, chiavi private, JWT, carte (verifica Luhn)… ripuliti dai risultati degli strumenti prima che raggiungano il modello
• 💉 Screening delle iniezioni di prompt — segnala o blocca i risultati degli strumenti (e le descrizioni degli strumenti — tool poisoning) che tentano di istruire il modello
• 📌 Rilevamento rug-pull — le definizioni degli strumenti vengono ancorate tramite hash al primo utilizzo; se un server sostituisce silenziosamente una descrizione, lo strumento viene bloccato finché un umano non lo ri-ancora
• 🚦 Rate limiting — bucket di token per strumento limitano il raggio d'esplosione di un ciclo di agente fuori controllo
• 🙋 Cancelli di approvazione umana — gli strumenti sensibili attivano un prompt di approvazione interattivo tramite MCP elicitation, direttamente nel tuo client
• 🧾 Registro di audit — ogni chiamata, rifiuto, rimozione e segnalazione finisce in un file JSONL append-only

Perché esiste

Chiunque è a un solo npx some-random-mcp-server di distanza dal consegnare a un processo non verificato le proprie chiavi API e una linea diretta nella finestra di contesto del proprio modello. Le classi di attacco documentate sono reali, non ipotetiche:

Esistono gateway MCP enterprise per i team di piattaforma con cluster Kubernetes. Nessuno strumento leggero protegge il laptop del singolo sviluppatore — il luogo dove gira davvero il 99% dei server MCP. È il vuoto che questo progetto colma.

Avvio rapido (60 secondi)

# 1. Create a config
npx -y mcp-doorman init

# 2. Edit doorman.config.json — put your real servers in it

# 3. Pin the current tool definitions (trust on first use)
npx -y mcp-doorman pin --config doorman.config.json

Poi punta il tuo client al gateway invece che ai tuoi server. Claude Desktop / Claude Code / Cursor:

// BEFORE — every server talks straight to the model
{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repos"] }
  }
}

// AFTER — one doorman guards them all
{
  "mcpServers": {
    "doorman": {
      "command": "npx",
      "args": ["-y", "mcp-doorman", "run", "--config", "/absolute/path/to/doorman.config.json"]
    }
  }
}

Gli strumenti compaiono con namespace come github__create_issue, filesystem__read_file, ecc., più due strumenti integrati: doorman__status e doorman__recent_events (chiedi al tuo agente "cosa ha bloccato di recente doorman?").

Nota per Windows: se una voce di server usa npx direttamente, avviala tramite cmd: "command": "cmd", "args": ["/c", "npx", "-y", "..."].

Guardalo in azione

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

La demo collega il gateway a un server volutamente malfunzionante (examples/demo-server.mjs) che fa trapelare credenziali finte, fornisce un payload di prompt injection e offre uno strumento distruttivo — e mostra ogni protezione che lo intercetta.

Come funziona

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]

Il gateway è un MCP server verso il tuo client e un MCP client verso ogni upstream (processi figli stdio o endpoint streamable-HTTP), aggregandoli dietro un'unica connessione. È costruito sullo TypeScript SDK ufficiale.

Configurazione

Tutto sta in un unico file JSON. Esempio completo con tutte le opzioni:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }   // ${VAR} = read from gateway env
    },
    "remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } }
  },

  "policy": {
    "defaultAction": "allow",                    // "allow" | "deny" | "approve"
    "rules": [                                   // first match wins, evaluated top-down
      { "match": "*__delete*",  "action": "deny",    "reason": "no destructive tools" },
      { "match": ["github__create_*", "*__send_*"], "action": "approve" },
      { "match": "filesystem__*", "action": "allow" }
    ]
  },

  "redaction": {
    "enabled": true,
    "disable": [],                               // built-in rule names to turn off
    "enableOptIn": ["email"],                    // opt-ins: "email", "us-ssn", "ipv4"
    "custom": [{ "name": "acme-id", "pattern": "ACME-[0-9]{6}" }],
    "redactArguments": false                     // also scrub model-supplied arguments
  },

  "injection": {
    "action": "flag",                            // "flag" (warn the model) | "block" | "off"
    "scanToolDescriptions": true,                // tool-poisoning check on tools/list
    "custom": []
  },

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

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

  "approval": { "fallback": "deny", "timeoutMs": 120000 },  // fallback when client lacks elicitation

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

  "logLevel": "info"
}

Lo stato dei pin e il registro di audit vengono salvati per impostazione predefinita in <config-name>.pins.json / <config-name>.audit.jsonl, accanto al file di configurazione.

CLI

Limiti onesti

Uno strumento di sicurezza che promette più di quanto mantiene è peggio di nessuno. Leggi questa parte.

• Le euristiche sono aggirabili. I pattern di injection intercettano forme di attacco documentate e comuni. Un attaccante motivato può trovare una formulazione che aggira qualsiasi regex. Usa le policy deny/approve come confine rigido; lo screening è difesa in profondità.
• La rimozione dei segreti è best-effort. I formati di token noti vengono intercettati in modo affidabile; un segreto hex casuale senza contesto no. Non puntare gli agenti verso archivi di credenziali.
• Non è una sandbox. I server upstream girano comunque come processi figli con i privilegi del tuo utente. Doorman protegge il protocollo; abbinalo a contenitori in stile ToolHive per proteggere il processo.
• TOFU: fiducia alla prima vista. Il pinning rileva i cambiamenti, non gli strumenti che erano maligni dal primo giorno — a questo servono lo scanner delle descrizioni e la tua stessa revisione.
• I cancelli di approvazione richiedono l'elicitation. I client senza supporto all'elicitation ripiegano su approval.fallback (deny per impostazione predefinita).

Roadmap — serve aiuto 🙌

• Proxy di resources/* e prompts/* (attualmente solo strumenti)
• Pass-through per sampling e roots
• Pacchetti di regole della community (doorman-rules-finance, doorman-rules-healthcare…)
• Modalità di apprendimento: osserva per una settimana, propone una policy con privilegi minimi
• Backend di policy OPA / Cedar
• Sottocomando mcp-doorman audit: formatta e interroga il registro JSONL
• Dashboard web per la visualizzazione dell'audit
• Rilevamento generico di segreti basato sull'entropia

Scegline uno dall'elenco sopra, oppure parti da una [good first issue](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue). Le nuove regole di rilevamento sono il contributo più semplice: una regex + due test. Vedi CONTRIBUTING.md e docs/detection-rules.md.

Sviluppo

npm install
npm test          # 69 tests: unit + full stdio e2e
npm run build
npm run demo      # watch the guards fire live

Licenza

Apache-2.0 — libero per qualsiasi uso, con una concessione esplicita di brevetto.