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

Por qué usarlo

Características clave

stdio → SSE/HTTP Streamable (modo salida)
SSE → stdio (modo entrada), múltiples servidores
Autenticación basada en encabezados, OAuth2 o token bearer para endpoints remotos
Imagen Docker para despliegue containerizado
Instalación simple con uv/pipx

Demo en vivo

Cómo se ve en la práctica

proxy.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": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "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": {
      "command": "uvx",
      "args": [
        "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": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

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

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

~/.config/zed/settings.json

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

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

claude mcp add proxy -- uvx 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 usar un servidor MCP SSE remoto dentro de Claude Desktop

👤 Devs con una puerta de enlace MCP alojada en equipo ⏱ ~10 min beginner

Cuándo usarlo: Tu equipo ejecuta una puerta de enlace en https://mcp.team.internal pero Claude Desktop solo habla stdio.

Requisitos previos

uv o pipx — brew install uv

Flujo

Instalar mcp-proxy

Ejecuta: uv tool install mcp-proxy✓ Copiado

→ mcp-proxy en PATH
Configurar Claude Desktop

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

→ Claude Desktop se conecta al reiniciar
Verificar

En Claude, pregunta: ¿qué herramientas tienes?✓ Copiado

→ Herramientas remotas enumeradas

Resultado: Servidor remoto usable desde clientes solo stdio.

Errores comunes

Encabezado de autenticación no detectado — Usa la sintaxis --headers exactamente; algunos clientes distorsionan la interpolación de variables de entorno — expande el token tú mismo

Combinar con: mcphub

Cómo exponer un MCP stdio local sobre HTTP para compañeros remotos

👤 Devs compartiendo una herramienta local temporalmente ⏱ ~15 min intermediate

Cuándo usarlo: Construiste un MCP stdio personalizado y un colega remoto quiere probarlo.

Flujo

Ejecutar proxy en modo entrada

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

→ Endpoint SSE en :3333/my-tool/sse
Tunelizarlo

Usa ngrok o cloudflared para exponer 3333 en una URL pública.✓ Copiado

→ URL compartible
El compañero se conecta

Agregan la URL a su cliente (vía mcp-proxy o directamente si su cliente soporta SSE).✓ Copiado

→ Sesión compartida funcionando

Resultado: Compartición ad-hoc de herramientas locales.

Errores comunes

Sin autenticación por defecto — Usa --bearer-token o colócalo detrás de autenticación básica de Caddy

Cómo servir múltiples MCPs locales desde un puerto proxy

👤 Aficionados de homelab ⏱ ~15 min intermediate

Cuándo usarlo: Quieres una puerta de enlace sirviendo MCPs de github, filesystem y postgres.

Flujo

Comienza con múltiples 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 y /fs/sse
Conecta cada uno en tu cliente

Agrega cada uno como un servidor separado en tu cliente MCP.✓ Copiado

→ Herramientas de ambos aparecen

Resultado: Un proceso, muchos MCPs.

Errores comunes

Los servidores nombrados comparten el presupuesto de recursos del proxy — No pongas MCPs pesados en el mismo proxy que los ligeros

Combinar con: mcphub

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

proxy + mcphub

Usa mcp-proxy para exponer MCPs stdio que MCPHub pueda agregar sobre HTTP

Conecta mi MCP stdio github local a HTTP con mcp-proxy, luego registralo en el grupo 'dev' de MCPHub.✓ Copiado

proxy + unla

Usa la puerta de enlace pública de Unla encima del puente stdio de última milla de mcp-proxy

Conecta MCPs stdio con mcp-proxy y pon Unla al frente para OAuth + multi-arrendamiento.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
(proxy) stdio-to-sse	remote_url, headers?, bearer?	Conecta cliente stdio a servidor SSE remoto	gratuito
(proxy) sse-to-stdio	named_server spec	Expone un MCP stdio sobre HTTP	gratuito

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguno
Tokens por llamada: Sin sobrecarga medible
Monetario: Gratuito (MIT)
Consejo: Omite el proxy cuando tu cliente soporta nativamente el otro transporte — menos piezas móviles.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: Salida de red a la URL remota (modo salida) Vinculación de puerto de entrada (modo entrada)

Almacenamiento de credenciales: Encabezados/tokens pasados vía argumentos CLI o env

Salida de datos: Lo que haga el MCP puente; el proxy en sí es transparente

No conceder nunca: No expongas el modo entrada en 0.0.0.0 sin autenticación No registres tokens en el historial de shell — usa variables de env

Las conexiones SSE pueden agotar tiempo de espera inactivo detrás de balanceadores de carga; ajusta el idle_timeout del LB o cambia a HTTP Streamable.

Resolución de problemas

Errores comunes y soluciones

Conexión cerrada inmediatamente

La ruta de URL remota es incorrecta — los endpoints SSE típicamente terminan en /sse.

Verificar: curl -N <url>

Error CORS en cliente de navegador

Inicia mcp-proxy con --allow-origin o colócalo detrás de un proxy inverso con encabezados CORS.

401 incluso con --bearer-token

El remoto espera el token en un encabezado diferente (p. ej., X-API-Key). Usa --headers para personalizar.

SSE cae después de 60s

Tiempo de espera inactivo del balanceador de carga. Aumentalo o usa HTTP Streamable.

Alternativas

mcp-proxy vs otros

Alternativa	Cuándo usarla	Contrapartida
MCPHub	Necesitas agregación multi-servidor + enrutamiento, no solo un puente	Más pesado — UI, DB, OAuth todo incluido
Unla	Quieres conversión REST-a-MCP + puerta de enlace	Espacio problemático diferente
supergateway	Prefieres un puente stdio-a-SSE de JavaScript	Dependencia de Node

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills