Desenvolvi um scanner somente leitura para prontidão de produção MCP / agent-gateway

Eu construo e mantenho um servidor MCP que funciona no Claude Code, Cursor e Gemini CLI. Fazer isso por um tempo me ensinou algo desconfortável: a distância entre um servidor MCP registrado e o acesso total a tudo que ele expõe é praticamente zero. A conveniência é a exposição.

Então, quando as equipes movem um agente de "funciona na demonstração" para "toca em sistemas reais", as mesmas lacunas aparecem toda vez. O acesso às ferramentas é concedido por servidor em vez de por operação. O modo de falha aberta se torna o padrão que ninguém escolheu de propósito. Novos servidores aparecem editando uma configuração e reiniciando — sem revisão, sem versões fixas. Muitas vezes, nada rastreia uma chamada através de agente → gateway → modelo → ferramenta, e o uso de múltiplos modelos funciona sem uma política de roteamento, o que se torna uma conta surpresa no final do mês.

A maior parte disso é visível ao ler o repositório. Eu me cansei de ler manualmente, então escrevi mcp-gateway-scan.

O que ele verifica

É uma verificação estática e somente leitura em sete dimensões:

1. Acesso às ferramentas / RBAC — as ferramentas estão limitadas por operação contra uma identidade, ou registrar um servidor entrega toda a sua superfície?
2. Falha segura — quando uma dependência de modelo, gateway ou ferramenta degrada, o sistema recusa de forma segura ou improvisa?
3. Onboarding / fixação da cadeia de suprimentos — adicionar um servidor é uma mudança revisada e declarativa com versões fixadas, ou uma edição de configuração e um reinício?
4. Observabilidade / OTel — existe rastreamento de ponta a ponta que você pode reconstruir a partir de uma chamada?
5. Roteamento multi-LLM & custo — existe uma política de roteamento, comportamento de fallback e atribuição de custo por equipe, ou um modelo codificado e esperança?
6. Segredos / identidade — credenciais em configurações vs. referências; a identidade é propagada para chamadas de ferramentas?
7. Prontidão para produção — interruptor de desligamento, limites de taxa, portões de avaliação, as apostas operacionais.

É somente leitura por design. Ele nunca executa seu código e nunca imprime um valor secreto. No máximo, aponta para um literal secreto que está inline em uma configuração que não deveria estar — um local a ser verificado, não um veredicto.

As sete dimensões rastreiam modos de falha que as diretrizes de segurança oficiais do MCP e os 10 principais da OWASP LLM mencionam — acesso excessivo a ferramentas, agência de falha aberta e cadeias de suprimentos não fixadas entre eles (Melhores práticas de segurança do MCP, OWASP LLM Top 10).

Três maneiras de executá-lo

CLI, para uma leitura única:

npx mcp-gateway-scan ./seu-repositorio

Portão CI, sai não-zero em qualquer vermelho:

npx mcp-gateway-scan --ci ./seu-repositorio

Servidor MCP, para que seu agente possa escanear sob demanda:

claude mcp add gateway-scan -- npx -y mcp-gateway-scan mcp

Então pergunte ao Claude ou Cursor "escaneie meu gateway" e o agente chama a ferramenta em si. A coisa que escaneia pilhas de agentes é, adequadamente, uma ferramenta de agente.

Como é a saída

mcp-gateway-scan ./seu-repositorio

  Acesso às ferramentas / RBAC ............ amarelo  ferramentas registradas por servidor; sem concessões por operação
  Falha segura .................... vermelho     sem política de fallback; erros do gateway retornam a última resposta em cache
  Onboarding / cadeia de suprimentos ..... verde   configuração declarativa, versões fixadas
  Observabilidade / OTel .......... amarelo  registro de solicitações presente; sem propagação de rastreamento para chamadas de ferramentas
  Roteamento multi-LLM & custo ...... verde   política de roteamento + atribuição por equipe encontrada
  Segredos / identidade ............ vermelho     chave da API inline em gateway.config.json
  Prontidão para produção .......... amarelo  limites de taxa presentes; sem interruptor de desligamento

  2 vermelhos · 3 amarelos · 2 verdes

Vermelhos são os que eu consertaria antes do próximo deploy. Amarelos são "você tem a fundação, não está conectada". Verdes significam que o padrão está realmente em vigor, não apenas pretendido.

Conectando o portão CI

Para a maioria das equipes, a --ci flag é onde isso ganha seu valor. Coloque-a em um fluxo de trabalho e um novo vermelho bloqueia a mesclagem:

- name: Portão de prontidão do Gateway
  run: npx mcp-gateway-scan --ci ${{ github.workspace }}

Saída não-zero em vermelho, zero caso contrário. Você pode ajustar: enviar hoje com amarelos permitidos, depois apertar o portão para falhar em amarelo uma vez que você tenha resolvido os vermelhos. O scanner é rápido e não tem dependência de rede, então é barato de executar em cada PR.

O que ele não faz

É uma primeira leitura, não um veredicto. Uma verificação estática pode te dizer que não há política de fallback na configuração; ela não pode te dizer se seu comportamento de falha segura realmente se mantém sob carga, porque isso precisa de injeção de falhas contra um sistema em execução. Ela lê o que você declarou, não o que acontece às 3 da manhã quando um provedor limita sua taxa.

Para calibração, eu levei a metodologia das sete dimensões para LiteLLM, um proxy maduro e amplamente implantado, fixado em um commit. Ele voltou 4 verdes / 3 amarelos / 0 vermelhos — pronto para produção, com as bordas usuais que uma passagem estruturada revela em uma boa base de código: um resolvedor de autorização que falha aberto onde seus irmãos falham fechados, servidores MCP de terceiros não fixados, e privilégio mínimo por ferramenta deixado como opt-in. Então eu construí um gateway de referência deliberadamente quebrado que falha nas mesmas verificações por construção. O scanner aqui automatiza a fatia estática dessa metodologia — a parte que você pode executar em segundos, antes de qualquer revisão mais profunda.

Experimente

• Execute: npx mcp-gateway-scan ./seu-repositorio — MIT, github.com/willianpinho/mcp-gateway-scan
• npm: mcp-gateway-scan

Se você quiser a versão mais profunda, eu realizo uma Auditoria de Prontidão do Gateway MCP Provenwright (injeção de falhas ao vivo, verificação de rastreamento, um roteiro de remediação de 90 dias) em willianpinho.com/mcp-audit. O scanner gratuito se sustenta por si só; isso é apenas se você quiser o resto.