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:

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

O estado de fixação e o log de auditoria padrão são <nome-do-config>.pins.json / <nome-do-config>.audit.jsonl ao lado do arquivo de configuração.

CLI

Limitações honestas

Ferramentas de segurança que prometem demais são piores que nenhuma. Leia esta parte.

• Heurísticas são contornáveis. Os padrões de injeção capturam formas de ataque documentadas e comuns. Um atacante motivado pode contornar qualquer regex. Use políticas deny/approve como limite rígido; a triagem é defesa em profundidade.
• Redação é melhor esforço. Formatos de token conhecidos são capturados de forma confiável; um segredo hex aleatório sem contexto não é. Não aponte agentes para repositórios de credenciais.
• Isto não é uma sandbox. Servidores upstream ainda rodam como processos filhos com os privilégios do seu usuário. O Doorman protege o protocolo; combine com contêineres (estilo ToolHive) para proteger o processo.
• TOFU confia na primeira visão. Fixação detecta mudanças, não ferramentas que eram maliciosas desde o primeiro dia — para isso serve o scanner de descrições e sua própria revisão.
• Portões de aprovação precisam de solicitação. Clientes sem suporte a solicitação recorrem ao approval.fallback (negar por padrão).

Roteiro — ajuda bem-vinda 🙌

• Proxy para resources/* e prompts/* (atualmente apenas ferramentas)
• Passagem para amostragem e raízes
• Pacotes de regras da comunidade (doorman-rules-finance, doorman-rules-healthcare…)
• Modo de aprendizado: observe por uma semana, proponha uma política de privilégio mínimo
• Backends de política OPA / Cedar
• Subcomando mcp-doorman audit: exibição formatada e consulta do log JSONL
• Painel web para visualização de auditoria
• Detecção genérica de segredos baseada em entropia

Pegue qualquer item acima, ou comece com uma [good first issue](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue). Novas regras de detecção são a contribuição mais fácil: uma regex + dois testes. Veja CONTRIBUTING.md e docs/detection-rules.md.

Desenvolvimento

npm install
npm test          # 69 testes: unitários + e2e completo via stdio
npm run build
npm run demo      # veja as proteções em ação ao vivo

Licença

Apache-2.0 — livre para qualquer uso, com uma concessão explícita de patentes.