McpVanguard

Um proxy de segurança de código aberto e firewall ativo para o Model Context Protocol (MCP).

Documentação

McpVanguard

Gateway de segurança para agentes MCP e servidores de ferramentas.

O McpVanguard fica entre um agente de IA e um servidor MCP, normaliza e inspeciona o tráfego de ferramentas em tempo real e aplica uma política em camadas antes que chamadas sensíveis alcancem a ferramenta subjacente. Ele é executado localmente na frente de servidores stdio ou como um gateway hospedado via SSE e Streamable HTTP.

Perfis de produto — monitor, balanced, strict — permitem adoção incremental: comece com descoberta somente auditoria, avance para aplicação equilibrada e, em seguida, habilite endurecimento rigoroso para sistemas sensíveis em produção.

Servidores MCP existentes não precisam ser reescritos.

Por Que Desenvolvedores Usam

Fluxos de trabalho MCP são poderosos, mas quando ferramentas tocam arquivos, shells ou redes, proteções importam.

O McpVanguard adiciona um limite de aplicação em tempo de execução para que você possa:

manter o tráfego normal de ferramentas fluindo
bloquear chamadas inseguras antes da execução
inspecionar e depurar decisões de política com logs de auditoria
adotar incrementalmente sem reescrever servidores MCP existentes

O Que Ele Faz

O McpVanguard é para desenvolvedores e equipes de plataforma que desejam aplicação explícita de políticas em torno de fluxos de trabalho MCP.

inspecionar chamadas de ferramentas MCP antes da execução
bloquear padrões inseguros de sistema de arquivos, comandos e rede
aplicar requisitos de autenticação, função e escopo para ferramentas sensíveis
inspecionar metadados do servidor antes que alcancem modelos downstream
rastrear comportamento suspeito repetido ao longo do tempo
emitir sinais de auditoria e telemetria para tráfego bloqueado, avisado e permitido

Cenário Rápido de Verificação

Use um caminho bruto e um caminho protegido contra o mesmo servidor MCP.

leitura segura de arquivo passa em ambos os caminhos
tentativa de path traversal é bloqueada no caminho protegido
solicitação de rede arriscada é bloqueada no caminho protegido
tentativas de envenenamento de metadados são filtradas ou bloqueadas antes da exposição ao modelo

Isso fornece um sinal rápido de que a política está ativa e a aplicação se comporta conforme o esperado.

Casos de Uso

proteger servidores MCP locais de desktop ou máquina de desenvolvedor sem reescrevê-los
adicionar um gateway hospedado na frente de servidores MCP compartilhados
comparar comportamento bruto versus protegido para fluxos de trabalho de ferramentas arriscados
adicionar aplicação de política a ferramentas de alto risco de arquivo, shell e acesso à rede

Início Rápido

Instale o pacote:

pip install mcp-vanguard

Extras opcionais de implantação:

# Multi-instance L3 behavioral state
pip install "mcp-vanguard[redis]"

# RE2-backed deterministic regex matching where the wheel is available
pip install "mcp-vanguard[re2]"

# Hosted/full deployment extras
pip install "mcp-vanguard[full]"

Envolva um servidor MCP stdio local:

# Balanced profile (default OSS/developer behavior)
vanguard start --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

# Strict profile (production hardening)
vanguard start --profile strict --server "npx @modelcontextprotocol/server-filesystem ."

Execute como um gateway hospedado:

export VANGUARD_API_KEY="replace-with-a-long-random-secret"
vanguard sse --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

Para implantações hospedadas públicas/não-loopback, o perfil strict se recusa a iniciar a menos que a autenticação de transporte esteja configurada com um VANGUARD_API_KEY aleatório longo ou configurações OAuth/JWKS. balanced permanece adequado para demonstrações e lançamentos em etapas, mas avisará em voz alta quando exposto sem autenticação.

Implantações hospedadas também podem habilitar orçamentos opcionais por sessão para taxa de chamadas de ferramentas, decisões arriscadas e tentativas bloqueadas repetidas. Eles atuam como disjuntores em torno do caminho de política em camadas sem alterar os padrões para uso OSS local.

Se você opera um modelo hospedado ou gateway compartilhado, defina VANGUARD_ALLOWED_SERVER_COMMANDS para restringir quais executáveis de servidor MCP upstream o McpVanguard pode iniciar.

Para servidores MCP de rede privada alcançados por túneis MCP da Anthropic, a colocação recomendada é túnel -> McpVanguard -> servidor MCP privado. Túneis reduzem a exposição de rede. O McpVanguard aplica o limite de execução.

O McpVanguard fornece uma linha de base de compatibilidade MCP 2026-07-28 documentada na linha 2.2.x. A linha de base inclui um perfil de transporte stateless opt-in, verificações de consistência aditivas Mcp-Method / Mcp-Name e cobertura explícita de inspeção _meta. Não é uma reivindicação de conformidade total com Tasks, MCP Apps, assinaturas, MRTR ou especificação final. Consulte docs/MCP_2026_07_28_RC_COMPATIBILITY.md.

Implante no Railway:

Precisa de um passo a passo completo de implantação? Consulte docs/DEPLOYMENT.md, docs/railway-deployment-guide.md e docs/ANTHROPIC_MCP_TUNNELS.md.

Começando

Inicialize um espaço de trabalho local:

# 1. Initialize safe zones and .env template
vanguard init

# 2. Optionally update Claude Desktop server entries
vanguard configure-claude

# 3. Launch the local security dashboard
vanguard ui --port 4040

# 4. Run compliance and readiness checks
vanguard audit-compliance

Como Funciona

O McpVanguard usa cinco camadas principais de inspeção, L0 a L3 mais L1.5, com política de autenticação e um compositor de política final ao redor delas. Cada chamada de ferramenta é inspecionada antes de alcançar o servidor MCP upstream.

Camada	Propósito	Notas
L0 - Preflight	Normalizar e anotar (URL decode, NFKC, remover largura zero, limites de tamanho/profundidade)	Sempre ativo
Auth	Aplicação de escopo OAuth e política de ferramentas destrutivas	Ciente de função
L1 - Regras	Bloqueio determinístico usando assinaturas, inspeção recursiva de argumentos e limites seguros	Caminho rápido
L1.5 - Camuflagem	Detectar camuflagem de sinal de confiança e manipulação de pontuação	Sensível ao perfil
L2 - Semântico	Pontuação de intenção opcional (pode escalar/bloquear, não pode rebaixar bloqueios determinísticos)	Assíncrono
L3 - Comportamental	Verificações de anomalia cientes de sessão e sequência	Com estado
Compositor de Política	Veredito final: ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK	Explicável

As cinco camadas principais de inspeção são L0, L1, L1.5, L2 e L3. A política de autenticação e o compositor de política final ficam ao redor desse caminho principal.

Se uma solicitação for bloqueada, o agente recebe um erro JSON-RPC padrão e o servidor upstream nunca vê a chamada. O log de auditoria registra o motivo principal e todas as descobertas de suporte.

Zonas seguras são verificações determinísticas de limite de caminho, não um substituto para sandboxing de SO ou isolamento de contêiner. Elas inspecionam nomes de argumentos padrão e comuns personalizados semelhantes a caminhos recursivamente, mas implantações em produção ainda devem ajustar rules/safe_zones.yaml para os esquemas e diretórios reais que suas ferramentas MCP podem acessar. Consulte docs/SAFE_ZONES.md.

Para triagem de operadores, logs de auditoria JSON incluem campos de decisão amigáveis a SIEM e dados estruturados policy_explanation com a camada principal, família de regras, efeito de perfil, status de chamada upstream e dica de ajuste. Consulte docs/BLOCK_DECISIONS.md.

Modelo de Implantação

O McpVanguard é melhor entendido como um gateway de segurança para fluxos de trabalho MCP.

Modo local-first: envolve servidores MCP stdio em uma máquina de desenvolvedor
Modo gateway: expõe endpoints SSE e Streamable HTTP endurecidos para implantações hospedadas ou compartilhadas

Caminho típico:

AI Agent -> McpVanguard -> MCP Server -> Tools / Files / External Systems

Capacidades Atuais

caminhos de transporte SSE e Streamable HTTP endurecidos com controles de taxa de solicitação, concorrência, vinculação de sessão e contagem de sessões
inspeção de envenenamento de metadados em initialize e tools/list
verificações JWT, JWKS, emissor, público, reivindicação e escopo para implantações com autenticação bearer
verificação de integridade do servidor e deriva de capacidade
isolamento entre servidores e rastreabilidade server_id
verificação de confiança com manifesto assinado, proveniência, assinatura destacada e suporte Sigstore
ferramentas de benchmark e taxonomia para cobertura mensurável
emissão opcional de JSONL receipt_v1 para evidência de tempo de execução verificável offline com mcp-receipt após exportação/assinatura

Benchmarks

O McpVanguard inclui corpora de benchmark empacotados para tráfego MCP adversário e benigno. Use-os para comparar perfis antes da implantação:

vanguard benchmark-run --profile monitor
vanguard benchmark-run --profile balanced
vanguard benchmark-run --profile strict
vanguard benchmark-profiles
vanguard benchmark-baselines

Os resultados do benchmark são um sinal de lançamento e ajuste, não uma promessa de detecção universal ou zero falsos positivos. Consulte docs/BENCHMARKS.md para orientação de interpretação e o portão de lançamento recomendado.

Para a nota de pesquisa pública por trás do design em camadas, consulte Por que a Segurança MCP Precisa de Aplicação em Camadas em Tempo de Execução.

Modos de Autenticação

O McpVanguard é local-first e suporta controles mais fortes de gateway hospedado quando necessário.

Modo stdio: sem autenticação de rede necessária
Modo SSE / Streamable HTTP: suporta VANGUARD_API_KEY
Modo Bearer / JWT: suporta validação JWT/JWKS verificada, verificações de emissor/público/reivindicação/escopo e política ciente de autenticação no caminho do gateway hospedado
Modo hospedado estrito: recusa binds públicos sem autenticação de transporte, define o tratamento de incompatibilidade de reivindicação bearer para block e exige Origin quando uma allowlist está configurada

Plano de Gerenciamento

Ferramentas de gerenciamento nativas vanguard_* são desabilitadas por padrão. Se você as habilitar, também escolha um modo explícito de plano de gerenciamento:

disabled: nenhuma ferramenta de gerenciamento nativa é exposta
same_session_dev: somente local/dev; ferramentas de leitura e mutação compartilham a sessão MCP governada e a inicialização imprime um aviso
operator_only: ferramentas somente leitura podem estar visíveis, mas ferramentas de mutação exigem função de administrador ou escopo vanguard:admin / scope:admin

Para produção, mantenha gerenciamento de mutação fora de sessões normais de agente governado, a menos que o chamador seja um operador autenticado. Ações de gerenciamento são auditadas e tentativas negadas/mutantes são visíveis ao risco.

Opções de Backend Semântico

O classificador semântico opcional da Camada 2 suporta múltiplos backends. O primeiro backend configurado vence.

Backend	Variáveis de Ambiente	Notas
Custom Universal	`VANGUARD_SEMANTIC_CUSTOM_KEY`, variáveis custom relacionadas	Provedores de inferência rápidos como Groq ou DeepSeek
OpenAI	`VANGUARD_OPENAI_API_KEY`	Modelo padrão: `gpt-4o-mini`
Ollama	`VANGUARD_OLLAMA_URL`	Execução local, sem chave de API necessária

Para um guia mais detalhado de configuração local/offline, consulte docs/LOCAL_SEMANTIC_MODE.md.

Integridade e Confiança

O McpVanguard inclui:

manifestos de servidor upstream assinados
linhas de base de capacidade e verificações de deriva
ganchos de verificação de proveniência
verificação de assinatura de artefato destacada
verificação de bundle Sigstore com restrições de identidade e emissor

Isso deve ser descrito como integridade de servidor, verificação de linha de base e verificação de confiança, não como uma plataforma completa de SBOM.

Status do Projeto

2.2.x é a linha atual de endurecimento de tempo de execução e linha de base de compatibilidade MCP 2026-07-28
caminho de aplicação em camadas (L0 -> L1 -> L1.5 -> L2 -> L3 -> Policy Composer) está implementado e coberto por verificação local e CI
perfis de produto (monitor / balanced / strict) são os modos de implantação suportados para esta linha de lançamento
recursos mais amplos somente pesquisa (atestação de GPU, proveniência com raiz de hardware, reivindicações de zero FP) estão intencionalmente fora do escopo principal do lançamento OSS

Consulte CHANGELOG.md para o histórico de lançamentos e docs/DEPLOYMENT.md para detalhes de implantação.

Privacidade

O McpVanguard foca em inspeção local e aplicação de gateway. Consulte PRIVACY.md para detalhes atuais de privacidade e tratamento de dados.

Suporte

Problemas: github.com/provnai/McpVanguard/issues
Contato: contact@provnai.com
Segurança: consulte SECURITY.md

FAQ

Isso substitui meu servidor MCP?
Não. O McpVanguard fica na frente do seu servidor MCP existente e aplica política antes que chamadas o alcancem.

Preciso reescrever ferramentas ou código de agente?
Geralmente não. A maioria das configurações começa roteando um fluxo de trabalho pelo McpVanguard.

Isso é apenas para configurações hospedadas?
Não. Suporta envolvimento stdio local-first e modos de gateway hospedado.

Licença

Licença MIT - consulte LICENSE.

Construído por Provnai.