mcp-proxy MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

stdio → SSE/HTTP Streamable (modo saída)
SSE → stdio (modo entrada), multi-servidor
Autenticação baseada em header, OAuth2, ou token bearer para endpoints remotos
Imagem Docker para implantação containerizada
Instalação simples com uv/pipx

Demo ao vivo

Como fica na prática

proxy.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "proxy",
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "proxy": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-proxy"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add proxy -- uvx mcp-proxy

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: mcp-proxy

Como usar um servidor MCP remoto SSE dentro do Claude Desktop

👤 Desenvolvedores com um gateway MCP hospedado em equipe ⏱ ~10 min beginner

Quando usar: Sua equipe executa um gateway em https://mcp.team.internal mas Claude Desktop só fala stdio.

Pré-requisitos

uv ou pipx — brew install uv

Fluxo

Instale mcp-proxy

Execute: uv tool install mcp-proxy✓ Copiado

→ mcp-proxy no PATH
Configure Claude Desktop

Adicione uma entrada MCP: command=mcp-proxy, args=['--headers','Authorization','Bearer $TOKEN','https://mcp.team.internal/sse'].✓ Copiado

→ Claude Desktop se conecta ao reiniciar
Verifique

No Claude, pergunte: que ferramentas você tem?✓ Copiado

→ Ferramentas remotas listadas

Resultado: Servidor remoto utilizável a partir de clientes apenas stdio.

Armadilhas

Header de autenticação não foi capturado — Use a sintaxe --headers exatamente; alguns clientes corrompem a interpolação de variáveis de ambiente — expanda o token você mesmo

Combine com: mcphub

Como expor um MCP stdio local via HTTP para colegas remotos

👤 Desenvolvedores compartilhando uma ferramenta local temporariamente ⏱ ~15 min intermediate

Quando usar: Você construiu um MCP stdio personalizado e um colega remoto quer experimentá-lo.

Fluxo

Execute o proxy em modo entrada

mcp-proxy --sse-host 0.0.0.0 --sse-port 3333 --named-server my-tool 'uvx my-tool-mcp'✓ Copiado

→ endpoint SSE em :3333/my-tool/sse
Crie um túnel

Use ngrok ou cloudflared para expor a porta 3333 em uma URL pública.✓ Copiado

→ URL compartilhável
Colega se conecta

Eles adicionam a URL ao seu cliente (via mcp-proxy ou diretamente se o cliente suporta SSE).✓ Copiado

→ Sessão compartilhada funcionando

Resultado: Compartilhamento ad-hoc de ferramentas locais.

Armadilhas

Sem autenticação por padrão — Use --bearer-token ou coloque atrás de autenticação básica do Caddy

Como servir múltiplos MCPs locais a partir de uma porta proxy

👤 Entusiastas de homelab ⏱ ~15 min intermediate

Quando usar: Você quer um gateway servindo MCPs de github, filesystem e postgres.

Fluxo

Comece com vários argumentos --named-server

mcp-proxy --sse-port 3333 --named-server gh 'uvx mcp-server-github' --named-server fs 'uvx mcp-server-filesystem ~/src'✓ Copiado

→ Endpoints /gh/sse e /fs/sse
Conecte cada um no seu cliente

Adicione cada um como um servidor separado no seu cliente MCP.✓ Copiado

→ Ferramentas de ambos aparecem

Resultado: Um processo, muitos MCPs.

Armadilhas

Servidores nomeados compartilham o orçamento de recursos do proxy — Não coloque MCPs pesados no mesmo proxy que MCPs leves

Combine com: mcphub

Combinações

Combine com outros MCPs para 10× de alavancagem

proxy + mcphub

Use mcp-proxy para expor MCPs stdio que o MCPHub pode então agregar via HTTP

Conecte meu MCP stdio github local para HTTP com mcp-proxy e depois o registre no grupo 'dev' do MCPHub.✓ Copiado

proxy + unla

Use o gateway público do Unla em conjunto com a ponte stdio do mcp-proxy

Conecte MCPs stdio com mcp-proxy e coloque o Unla na frente para OAuth + multi-tenancy.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
(proxy) stdio-to-sse	remote_url, headers?, bearer?	Conecte o cliente stdio ao servidor SSE remoto	gratuito
(proxy) sse-to-stdio	named_server spec	Exponha um MCP stdio via HTTP	gratuito

Custo e limites

O que custa rodar

Cota de API: Nenhuma
Tokens por chamada: Sem overhead mensurável
Monetário: Gratuito (MIT)
Dica: Pule o proxy quando seu cliente suporta nativamente o outro transporte — menos partes móveis.

Segurança

Permissões, segredos, alcance

Escopos mínimos: Saída de rede para a URL remota (modo saída) Vinculação de porta de entrada (modo entrada)

Armazenamento de credenciais: Headers/tokens passados via argumentos CLI ou env

Saída de dados: O que quer que o MCP ponte faça; o proxy em si é transparente

Nunca conceda: Não exponha o modo entrada em 0.0.0.0 sem autenticação Não registre tokens no histórico do shell — use variáveis de ambiente

Conexões SSE podem sofrer timeout de inatividade atrás de balanceadores de carga; ajuste o idle_timeout do LB ou mude para HTTP Streamable.

Solução de problemas

Erros comuns e correções

Conexão fechada imediatamente

O caminho da URL remota está errado — endpoints SSE normalmente terminam em /sse.

Verificar: curl -N <url>

Erro CORS em cliente do navegador

Inicie mcp-proxy com --allow-origin ou coloque atrás de um proxy reverso com headers CORS.

401 mesmo com --bearer-token

O servidor remoto espera o token em um header diferente (ex: X-API-Key). Use --headers para personalizar.

SSE desconecta após 60s

Timeout de inatividade do balanceador de carga. Aumente-o ou use HTTP Streamable.

Alternativas

mcp-proxy vs. outros

Alternativa	Quando usar	Troca
MCPHub	Você precisa de agregação de multi-servidor + roteamento, não apenas uma ponte	Mais pesado — UI, banco de dados, OAuth tudo incluído
Unla	Você quer conversão REST-para-MCP + gateway	Espaço de problema diferente
supergateway	Você prefere uma ponte stdio-para-SSE em JavaScript	Dependência Node

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills