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

Name: mcp-proxy MCP Server
Author: tbxark

Por qué usarlo

Características clave

Puente de transporte: envuelve servidores stdio como HTTP/SSE para que clientes remotos puedan alcanzarlos
Un único archivo de configuración lista todos los servidores upstream — cambia sobre la marcha sin reiniciar clientes
Imagen Docker ghcr.io/tbxark/mcp-proxy para despliegue de un comando
Convertidor de configuración basado en web en tbxark.github.io/mcp-proxy
Herramientas con namespace — evita colisiones cuando dos upstreams exponen el mismo nombre de herramienta

Demo en vivo

Cómo se ve en la práctica

proxy-2.replay ▶ listo

0/0

Instalar

Elige tu cliente

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

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

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

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "proxy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "proxy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/tbxark/mcp-proxy"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add proxy-2 -- TODO 'See README: https://github.com/tbxark/mcp-proxy'

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: mcp-proxy

Cómo ejecutar una puerta de enlace MCP compartida para tu equipo

👤 Ingenieros de plataforma/DevEx cansados de configurar 10 MCPs en cada compañero nuevo ⏱ ~30 min intermediate

Cuándo usarlo: Has encontrado 5+ MCPs que todos en el equipo necesitan, pero estar explicando la configuración de stdio a cada nuevo empleado consume tu semana.

Requisitos previos

Una VM o host de contenedor alcanzable por cada miembro del equipo — Cualquier pequeño box EC2/Fly/Hetzner; 512MB RAM es suficiente
Docker instalado en ese host — curl -fsSL https://get.docker.com | sh

Flujo

Escribe un config.json listando cada MCP upstream que el equipo necesita

Redacta un config.json de mcp-proxy que agregue github, sentry, postgres (réplica de solo lectura) y filesystem (limitado a /data). Dale un namespace único a cada uno.✓ Copiado

→ Config válido con entradas de servidor con namespace
Ejecuta mcp-proxy en Docker en el host compartido

Escribe el comando docker run para lanzar ghcr.io/tbxark/mcp-proxy en puerto 9090 montando config.json, con restart=always y un healthcheck.✓ Copiado

→ El contenedor se mantiene activo; /health devuelve 200
Dale a los compañeros una URL para pegar en cada cliente

Escribe un snippet de onboarding de 5 líneas que los compañeros peguen en la configuración del Claude Desktop para apuntar a nuestra URL de proxy compartido.✓ Copiado

→ Cualquier compañero obtiene todas las herramientas upstream en un paso

Resultado: Los nuevos empleados alcanzan paridad MCP completa en 2 minutos pegando una URL; las actualizaciones ocurren en un único lugar.

Errores comunes

Poner el proxy en internet público sin autenticación — Termina TLS y autenticación en un proxy inverso (Caddy/nginx/Cloudflare) al frente — mcp-proxy no tiene capa de autenticación
Los nombres de herramientas upstream colisionan (dos servidores ambos exponen get_issue) — Usa namespace para que los clientes vean github.get_issue vs gitlab.get_issue

Combinar con: github · sentry · postgres

Expone un MCP stdio local a un IDE remoto vía HTTP

👤 Desarrolladores usando un IDE en la nube que no puede generar procesos stdio ⏱ ~15 min beginner

Cuándo usarlo: Tu cliente solo habla HTTP/SSE pero el MCP que necesitas es solo stdio.

Flujo

Ejecuta mcp-proxy localmente envolviendo el servidor stdio

Genera un config.json de mcp-proxy que envuelva npx -y @modelcontextprotocol/server-filesystem /tmp como un endpoint SSE en :9090.✓ Copiado

→ curl http://localhost:9090 devuelve metadata MCP
Tunnela el puerto a una URL pública

Dame un comando de una línea con cloudflared o ngrok para exponer :9090.✓ Copiado

→ URL HTTPS pública
Apunta el IDE remoto a la URL SSE

Escribe la entrada de configuración del IDE para consumir esto como un servidor MCP SSE.✓ Copiado

→ Las herramientas aparecen en el IDE remoto

Resultado: Un MCP solo stdio alcanzable desde cualquier cliente capaz de HTTP.

Errores comunes

Los túneles públicos están abiertos al mundo mientras están activos — Usa cloudflared con políticas de Access o añade un header de secreto compartido

Combinar con: filesystem

Actualiza un MCP para todo el equipo sin tocar las configuraciones del cliente

👤 Líderes de equipo implementando actualizaciones de versión de MCP ⏱ ~10 min beginner

Cuándo usarlo: Una versión de arreglo de seguridad de un MCP upstream cae y necesitas que todos la tengan hoy.

Flujo

Sube de versión en la configuración central de mcp-proxy

Actualiza mi config.json de mcp-proxy para fijar github-mcp-server en v0.4.2 y recarga.✓ Copiado

→ Nueva versión activa en el proxy
Verifica que las herramientas aún respondan

Llama a list_tools del proxy y confirma que las herramientas github.* están presentes con la nueva versión del servidor.✓ Copiado

→ La lista de herramientas sin cambios desde la perspectiva del consumidor

Resultado: Actualización silenciosa — los compañeros recogen la nueva versión en la siguiente llamada de herramienta, sin necesidad de reiniciar el cliente.

Errores comunes

La nueva versión renombró una herramienta y rompió los prompts downstream — Lee el changelog upstream antes de fijar; mantén la versión anterior configurada brevemente para solapamiento

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

proxy-2 + github + sentry

Pon ambos tras un proxy para que los compañeros no tengan que malabarizar dos tokens en dos configuraciones

Configura mcp-proxy para conectar con ambos servidores MCP github y sentry, cargando credenciales de un único archivo .env que el host lee.✓ Copiado

proxy-2 + agent

Compara vs 1mcp-app/agent — ambos agregan, diferentes tradeoffs (Go vs Node, OAuth vs ninguno)

Configura mcp-proxy junto a 1mcp-app/agent en el mismo host y compara la latencia de llamada de herramienta a través de cada uno.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_tools	(ninguno)	Lado del cliente — el proxy maneja automáticamente en el handshake MCP	gratuito
call_tool	name: str (opcionalmente con namespace), args: object	Cualquier invocación de herramienta — el proxy encamina por nombre/namespace	1 llamada upstream

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Sin cuota propia; pasa a través de los límites del servidor upstream
Tokens por llamada: Overhead negligible más allá de la respuesta upstream
Monetario: Gratuito, licencia MIT
Consejo: Ejecuta en un pequeño box — 512MB RAM maneja docenas de upstreams. El costo real es de las cuotas de API upstream.

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Credenciales upstream en variables de entorno del host o config.json; mantén config.json fuera de git

Salida de datos: El proxy reenvía a cualquiera de los servidores upstream que configures; sin telemetría de vuelta a tbxark

No conceder nunca: Exponer el proxy a internet público sin una capa de autenticación en frente

Sin autenticación incorporada — empareja con autenticación de proxy inverso (Caddy, nginx, Cloudflare Access) antes de exponer públicamente.
Trata config.json como un archivo de secretos; contiene tokens para cada upstream.

Resolución de problemas

Errores comunes y soluciones

El servidor upstream falló al iniciar

Verifica que la ruta del comando en config.json sea absoluta o esté en el PATH del contenedor. Usa docker exec para entrar y ejecuta manualmente.

Verificar: docker logs <proxy-container>

La llamada de herramienta devuelve 'herramienta no encontrada' pero list_tools la muestra

Desajuste de namespace — con namespace activado, los clientes deben llamar a server.tool_name, no tool_name.

Verificar: curl http://proxy:9090/tools | jq

La conexión SSE se cae cada 30s

El timeout de inactividad del proxy inverso es demasiado corto. Aumenta a 5 min o deshabilita el buffering para rutas /sse.

Verificar: El log de nginx/Caddy muestra timeout del cliente

El contenedor Docker se cierra inmediatamente

JSON de configuración inválido. Valida con jq antes de iniciar.

Verificar: docker logs muestra error de análisis JSON

Alternativas

mcp-proxy vs otros

Alternativa	Cuándo usarla	Contrapartida
1mcp-app/agent	Quieres OAuth 2.1 y autenticación basada en scope incorporada	Huella más pesada, basado en Node vs Go
Hyprmcp Jetski	Necesitas análisis y visibilidad a nivel de prompt además de agregación	Requiere Kubernetes/PostgreSQL — excesivo para equipos pequeños
Configuraciones de cliente directo	El equipo es 1-3 personas y raramente cambias servidores	Cero infraestructura, pero cada cambio es N actualizaciones

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills