mcp-doorman

O gateway de segurança para servidores MCP — toda chamada de ferramenta é verificada na porta.

CI npm Licença: Apache-2.0 PRs bem-vindos

mcp-doorman é um proxy plug-and-play que se posiciona entre seu agente de IA (Claude Desktop, Claude Code, Cursor, VS Code, qualquer cliente MCP) e os servidores MCP que ele utiliza. Um comando, zero infraestrutura, e cada tools/list e tools/call passa por um pipeline de proteção:

• 🛂 Mecanismo de políticas — regras de permitir/negar/requerer aprovação por ferramenta, com correspondência por glob
• 🕵️ Redação de segredos — chaves AWS, tokens GitHub/Slack/Stripe/OpenAI/Anthropic, chaves privadas, JWTs, cartões (verificados por Luhn)... removidos dos resultados das ferramentas antes de chegarem ao modelo
• 💉 Triagem de injeção de prompt — sinaliza ou bloqueia resultados de ferramentas (e descrições de ferramentas — envenenamento de ferramenta) que tentam instruir o modelo
• 📌 Detecção de troca de ferramenta (rug pull) — definições de ferramentas são fixadas por hash no primeiro uso; se um servidor silenciosamente substituir uma descrição, a ferramenta é bloqueada até que um humano a refixe
• 🚦 Limitação de taxa — baldes de token por ferramenta limitam o raio de explosão de um loop de agente descontrolado
• 🙋 Portões de aprovação humana — ferramentas sensíveis disparam um prompt interativo de aprovação via solicitação MCP, diretamente no seu cliente
• 🧾 Log de auditoria — toda chamada, negação, redação e sinalização são registradas em um arquivo JSONL somente anexação

Por que isso existe

Todo mundo está a um npx some-random-mcp-server de entregar suas chaves de API e uma linha direta para a janela de contexto do modelo a um processo não verificado. As classes de ataque documentadas são reais, não hipotéticas:

Ataque	Como funciona
Envenenamento de ferramenta	Instruções maliciosas escondidas na descrição de uma ferramenta, invisíveis na maioria das interfaces dos clientes
Troca de ferramenta (Rug pull)	Servidor apresenta ferramentas inocentes no primeiro dia, troca as definições depois de você as aprovar
Injeção de prompt indireta	Uma página web/issue/email buscada por uma ferramenta legítima carrega instruções direcionadas ao modelo
Exfiltração de segredos	Uma credencial vazada em um resultado de ferramenta + uma instrução injetada = sua chave no servidor de outra pessoa
Loops descontrolados	Um agente confuso ou sequestrado deleta em massa, envia e-mails em massa, faz scraping em massa

Gateways MCP empresariais existem para equipes de plataforma com clusters Kubernetes. Nada leve protege o laptop do desenvolvedor individual — o lugar onde 99% dos servidores MCP realmente rodam. Essa é a lacuna que este projeto preenche.

Guia rápido (60 segundos)

# 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

Then point your client at the gateway instead of your servers. 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"]
    }
  }
}

Tools show up namespaced as github__create_issue, filesystem__read_file, etc., plus two built-ins: doorman__status and doorman__recent_events (ask your agent "what did doorman block recently?").

Nota para Windows: se uma entrada de servidor usar npx diretamente, execute-a através do cmd: "command": "cmd", "args": ["/c", "npx", "-y", "..."].

Veja funcionando

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

A demonstração conecta o gateway a um servidor deliberadamente malcomportado (examples/demo-server.mjs) que vaza credenciais falsas, serve um payload de injeção de prompt e oferece uma ferramenta destrutiva — e mostra cada proteção capturando-os.

Como 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]

O gateway é um servidor MCP para seu cliente e um cliente MCP para cada upstream (processos filho stdio ou endpoints HTTP transmissíveis), agregando-os em uma única conexão. É construído sobre o TypeScript SDK oficial.

Configuração

Tudo reside em um único arquivo JSON. Exemplo completo com todas as opções:

{
  "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"
}