mcpproxy-go

Servidor proxy MCP local de código aberto. Roteia múltiplos servidores MCP através de um único endpoint com filtragem de ferramentas BM25, segurança de quarentena, registro de atividades e interface web.

GitHub

381

Experimente este MCPPatrocinado

Documentação

MCPProxy web UI demo: server dashboard, tool discovery, activity log, and security quarantine

📺 Assista ao passo a passo completo · 📚 Leia a documentação · 🌐 mcpproxy.app

A demonstração acima mostra a interface web embutida. O núcleo do MCPProxy é um único binário para macOS, Linux e Windows — a interface web vem embutida nele, sem necessidade de serviço adicional. No macOS, um aplicativo opcional de barra de menu adiciona conveniência com um clique (iniciar/parar, saúde do servidor, quarentena, logs).

MCPProxy macOS app — Activity log with sensitive-data detection

Aplicativo de barra de menu para macOS · Log de atividades e auditoria no aplicativo macOS

Por que MCPProxy?

Escale além dos limites de API – Federar centenas de servidores MCP enquanto contorna o limite de 40 ferramentas do Cursor e o limite de 128 funções do OpenAI.
Economize tokens e acelere respostas – Os agentes carregam apenas uma retrieve_tools função em vez de centenas de esquemas. Pesquisas mostram ~99% de redução de tokens com 43% de melhoria na precisão.
Proteção de segurança avançada – Quarentena automática bloqueia ataques de envenenamento de ferramentas até que você aprove manualmente novos servidores.
Scanners de segurança plugáveis – Execute scanners baseados em Docker como Snyk, Semgrep, Trivy, Cisco e outros contra servidores em quarentena antes de aprová-los; os resultados são normalizados para SARIF com uma pontuação de risco composta. Veja Plugins de scanner de segurança.
Funciona offline e multiplataforma – Um único binário principal para macOS (Intel e Apple Silicon), Windows (x64 e ARM64) e Linux (x64 e ARM64), com a interface web embutida. O macOS também inclui um aplicativo opcional de barra de menu.

Início Rápido

1. Instalação

macOS (Recomendado - Instalador DMG):

Baixe o instalador DMG mais recente para sua arquitetura:

Apple Silicon (M1/M2): Baixar DMG → mcpproxy-*-darwin-arm64.dmg
Mac Intel: Baixar DMG → mcpproxy-*-darwin-amd64.dmg

Windows (Recomendado - Instalador):

Baixe o instalador Windows mais recente para sua arquitetura:

x64 (64 bits): Baixar Instalador → mcpproxy-setup-*-amd64.exe
ARM64: Baixar Instalador → mcpproxy-setup-*-arm64.exe

O instalador automaticamente:

Instala tanto o mcpproxy.exe (servidor principal) quanto o mcpproxy-tray.exe (aplicativo de bandeja do sistema) em Program Files
Adiciona o MCPProxy ao PATH do seu sistema para acesso via linha de comando
Cria atalhos no Menu Iniciar
Suporta instalação silenciosa: .\mcpproxy-setup.exe /VERYSILENT

Métodos alternativos de instalação:

macOS (Homebrew):

# macOS — GUI tray app (recommended):
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy

# macOS / Linux — headless CLI only:
brew install smart-mcp-proxy/mcpproxy/mcpproxy

O cask instala o aplicativo de barra de menu (inclui a CLI); a fórmula é apenas o binário da CLI. Ambos são atualizados via brew upgrade.

Linux (Debian/Ubuntu) — repositório apt, atualizações automáticas via apt upgrade:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update && sudo apt install mcpproxy

Linux (Fedora / RHEL / Rocky / AlmaLinux) — repositório dnf, atualizações automáticas via dnf upgrade:

sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
# Fedora 41+ (dnf5): sudo curl -fsSL https://rpm.mcpproxy.app/mcpproxy.repo -o /etc/yum.repos.d/mcpproxy.repo
sudo dnf install -y mcpproxy

Arch Linux (AUR): mcpproxy-bin

yay -S mcpproxy-bin
# or
git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -si

Os pacotes apt e dnf incluem uma unidade systemd endurecida e iniciam o serviço automaticamente. Impressão digital da chave de assinatura do repositório: 3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B.

Para downloads únicos de .deb / .rpm (instalações em ambientes isolados), obtenha-os na última versão.

Download manual (todas as plataformas):

Tarball Linux: AMD64 | ARM64
Windows: AMD64 | ARM64

Builds de Pré-lançamento (Recursos Mais Recentes):

Quer experimentar os recursos mais novos? Baixe builds de pré-lançamento do branch next:

Vá para GitHub Actions
Clique na execução mais recente do fluxo de trabalho "Prerelease" que foi bem-sucedida
Baixe de Artifacts:
- dmg-darwin-arm64 (Macs com Apple Silicon)
- dmg-darwin-amd64 (Macs Intel)
- versioned-linux-amd64, versioned-windows-amd64 (outras plataformas)

Nota: Builds de pré-lançamento são assinados e notarizados para macOS, mas contêm recursos de ponta que podem ser instáveis.

macOS: Intel | Apple Silicon

Em qualquer lugar com Go 1.26+:

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

2. Executar

mcpproxy serve          # starts HTTP server on :8080 and shows tray

3. Adicionar seu primeiro servidor

Crie ou edite ~/.mcpproxy/mcp_config.json:

{
  "listen": "127.0.0.1:8080",
  "mcpServers": [
    { "name": "local-python", "command": "python", "args": ["-m", "my_server"], "protocol": "stdio", "enabled": true },
    { "name": "remote-http", "url": "http://localhost:3001", "protocol": "http", "enabled": true }
  ]
}

Consulte Configuração e Servidores Upstream para a referência completa.

4. Conectar à sua IDE/ferramenta de IA

📖 Guia de Configuração Completo - Instruções detalhadas para Cursor, VS Code, Claude Desktop e Goose

Adicionar proxy ao Cursor

Instalação com um clique na IDE Cursor

Instalação manual

Abra as Configurações do Cursor
Clique em "Tools & Integrations"
Adicione o servidor MCP

    "MCPProxy": {
      "type": "http",
      "url": "http://localhost:8080/mcp/"
    }

Como os Agentes de IA Funcionam Através do MCPProxy

Uma vez conectado, seu agente vê um punhado de ferramentas MCPProxy integradas em vez de centenas de esquemas upstream. Uma sessão típica tem três etapas — descobrir, chamar, auditar — além de uma porta de pré-verificação opcional para automações não supervisionadas.

1. Descobrir — gaste uma consulta, não sua janela de contexto

O agente pede o que precisa em palavras-chave simples via retrieve_tools:

{ "query": "create github issue", "limit": 5 }

O MCPProxy executa uma busca BM25 em todos os servidores conectados e retorna apenas as correspondências mais bem classificadas — cada uma com uma dica de call_with recomendando a variante de chamada correta para suas anotações:

{
  "tools": [
    { "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
    { "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
  ]
}

É aqui que vem a economia de tokens: os esquemas das centenas de ferramentas que o agente não precisou nunca entram em seu contexto. O agente carrega esquemas completos sob demanda com describe_tool (lote de até 5 IDs) apenas para as ferramentas que está prestes a usar.

2. Chamar — com intenção declarada

O agente executa a ferramenta através da variante que corresponde à sua intenção (call_tool_read, call_tool_write ou call_tool_destructive), endereçando-a como server:tool:

{
  "name": "github:create_issue",
  "args_json": "{\"repo\": \"acme/api\", \"title\": \"Bug report\"}",
  "intent": { "operation_type": "write", "reason": "Filing bug per user request" }
}

O MCPProxy valida a intenção contra as anotações da ferramenta (uma chamada "read" não pode alcançar uma ferramenta destrutiva), verifica o estado de quarentena e aprovação, e examina argumentos e respostas em busca de dados sensíveis antes que qualquer coisa saia da máquina.

3. Auditar — toda chamada fica registrada

Toda chamada vai para o Log de Atividades local com um ID de solicitação, para que você possa reconstruir exatamente o que um agente fez:

mcpproxy activity list                          # everything, newest first
mcpproxy activity list --request-id <id>        # one workflow, correlated

Gate de automações antes de queimarem tokens

Para trabalhos headless recorrentes (cron, CI, n8n), não deixe o agente descobrir uma ferramenta ausente da maneira cara. Um comando de pré-verificação confirma que toda ferramenta necessária está pronta — sem contatar nenhum servidor upstream — e relata exatamente o motivo quando não está (servidor em quarentena, ferramenta alterada desde a aprovação, OAuth expirado, ID com erro de digitação):

mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
case $? in
  0)  run-agent-session ;;   # all ready — go
  10) exit 75 ;;             # transient (server starting) — let the next cron tick retry
  11) page-operator ;;       # blocked — someone must approve / enable / log in
  12) fail-pipeline ;;       # unknown tool id — the automation itself is misconfigured
esac

Consulte Pré-verificação de Ferramentas Necessárias para a taxonomia completa de motivos, endpoint REST e receitas para GitHub Actions / n8n.

🔐 Configuração HTTPS Opcional

O MCPProxy funciona com HTTP por padrão para facilitar a configuração. HTTPS é opcional e principalmente útil para ambientes de produção ou quando é necessária segurança mais rigorosa.

💡 Nota: A maioria dos usuários pode continuar com HTTP (o padrão), pois funciona perfeitamente com todos os clientes suportados, incluindo Claude Desktop, Cursor e VS Code.

Configuração Rápida de HTTPS

1. Habilite HTTPS (escolha um método):

# Method 1: Environment variable
export MCPPROXY_TLS_ENABLED=true
mcpproxy serve

# Method 2: Config file
# Edit ~/.mcpproxy/mcp_config.json and set "tls.enabled": true

2. Confie no certificado (configuração única):

mcpproxy trust-cert

3. Use URLs HTTPS:

Endpoint MCP: https://localhost:8080/mcp
Interface web: https://localhost:8080/ui/

Integração com Claude Desktop

Para Claude Desktop, adicione isto ao seu claude_desktop_config.json:

HTTP (Padrão - Recomendado):

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/mcp"
      ]
    }
  }
}

HTTPS (Com Confiança no Certificado):

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://localhost:8080/mcp"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "~/.mcpproxy/certs/ca.pem"
      }
    }
  }
}

Gerenciamento de Certificados

Geração automática: Certificados criados na primeira inicialização HTTPS
Suporte a múltiplos domínios: Funciona com localhost, 127.0.0.1, ::1
Instalação de confiança: Use mcpproxy trust-cert para adicionar ao chaveiro do sistema
Localização dos certificados: ~/.mcpproxy/certs/ (ca.pem, server.pem, server-key.pem)

Solução de Problemas HTTPS

Problemas de confiança no certificado:

# Re-trust certificate
mcpproxy trust-cert --force

# Check certificate location
ls ~/.mcpproxy/certs/

# Test HTTPS connection
curl -k https://localhost:8080/api/v1/status

Problemas de conexão com Claude Desktop:

Certifique-se de que NODE_EXTRA_CA_CERTS aponta para o arquivo ca.pem correto
Reinicie o Claude Desktop após alterações na configuração
Verifique se HTTPS está habilitado: mcpproxy serve --log-level=debug

Documentação

Primeiros Passos

Configuração

Recursos

Referência da CLI

API

Contribuindo

Aceitamos issues, ideias de recursos e PRs!

Configuração de Desenvolvimento

make dev-setup                # Install swag, frontend deps, Playwright
brew install prek             # Install pre-commit hook runner (or: uv tool install prek)
prek install                  # Install pre-commit hooks
prek install --hook-type pre-push  # Install pre-push hooks

Hooks de Pré-commit

Usamos prek para detectar problemas antes que cheguem ao CI:

Hook	Estágio	O que faz
`gofmt`	pre-commit	Formata automaticamente arquivos Go em staged
`trailing-whitespace`	pre-commit	Remove espaços em branco no final das linhas
`end-of-file-fixer`	pre-commit	Garante que os arquivos terminem com nova linha
`check-merge-conflict`	pre-commit	Detecta marcadores de conflito de merge
`swagger-verify`	pre-push	Falha se a especificação OpenAPI estiver desatualizada
`go-build`	pre-push	Verifica se o projeto compila

Execute os hooks manualmente: prek run --all-files

Build e Testes

make build          # Build frontend + backend
make swagger        # Regenerate OpenAPI spec
make test           # Unit tests
make test-e2e       # E2E tests
make lint           # Run linters