mcp-remote

Conecta un Cliente MCP que solo soporta servidores locales (stdio) a un Servidor MCP Remoto, con soporte de autenticación:

Nota: esto es una prueba de concepto funcional pero debe considerarse experimental.

¿Por qué es necesario?

Hasta ahora, la mayoría de los servidores MCP existentes se instalan localmente, utilizando el transporte stdio. Esto tiene algunos beneficios: tanto el cliente como el servidor pueden confiar implícitamente el uno en el otro, ya que el usuario les ha otorgado permiso para ejecutarse. Agregar secretos como claves API se puede hacer usando variables de entorno y nunca salen de tu máquina. Además, basarse en npx y uvx ha permitido a los usuarios evitar pasos de instalación explícitos.

Pero hay una razón por la que la mayoría del software que podría moverse a la web se movió a la web: es mucho más fácil encontrar y corregir errores e iterar en nuevas funciones cuando puedes enviar actualizaciones a todos tus usuarios con un solo despliegue.

Con la última especificación de Autorización de MCP, ahora tenemos una forma segura de compartir nuestros servidores MCP con el mundo sin ejecutar código en las laptops de los usuarios. O al menos, lo harías, si todos los clientes MCP populares ya lo soportaran. La mayoría son solo stdio, y aquellos que sí soportan HTTP+SSE aún no soportan los flujos OAuth requeridos.

Ahí es donde entra mcp-remote. Tan pronto como tu cliente MCP elegido soporte servidores remotos autorizados, puedes eliminarlo. Hasta ese momento, incorpora esta línea y ¡vístete para los clientes MCP que quieras!

Uso

Todos los clientes MCP más populares (Claude Desktop, Cursor y Windsurf) utilizan el siguiente formato de configuración:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

Cabeceras Personalizadas

Para omitir la autenticación, o para emitir cabeceras personalizadas en todas las solicitudes a tu servidor remoto, pasa argumentos --header en la CLI:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

Nota: Cursor y Claude Desktop (Windows) tienen un error donde los espacios dentro de args no se escapan cuando invoca npx, lo que termina distorsionando estos valores. Puedes solucionarlo usando:

{
  // resto de la configuración...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // nota: sin espacios alrededor de ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // espacios OK en variables de entorno
  }
},

Banderas

• Si npx produce errores, considera agregar -y como primer argumento para aceptar automáticamente la instalación del paquete mcp-remote.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• Para forzar a npx a buscar siempre una versión actualizada de mcp-remote, agrega la bandera @latest:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• Para cambiar el puerto en el que mcp-remote escucha una redirección OAuth (por defecto 3334), agrega un argumento adicional después de la URL del servidor. Ten en cuenta que, independientemente del puerto que especifiques, si no está disponible, se elegirá un puerto abierto al azar.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• Para cambiar el host que mcp-remote registra como URL de callback OAuth (por defecto localhost), agrega la bandera --host.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• Para permitir conexiones HTTP en redes privadas de confianza, agrega la bandera --allow-http. Nota: Esto solo debe usarse en redes privadas seguras donde el tráfico no pueda ser interceptado.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• Para habilitar registros detallados de depuración, agrega la bandera --debug. Esto escribirá registros verbosos en ~/.mcp-auth/{server_hash}_debug.log con marcas de tiempo e información detallada sobre el proceso de autenticación, conexiones y actualización de tokens.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• Para habilitar un proxy HTTP(S) saliente para mcp-remote, agrega la bandera --enable-proxy. Cuando está habilitado, mcp-remote usará la configuración de proxy de variables de entorno comunes (por ejemplo HTTP_PROXY, HTTPS_PROXY y NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• Para ignorar herramientas específicas del servidor remoto, agrega la bandera --ignore-tool. Esto filtrará las herramientas que coincidan con los patrones especificados tanto en las respuestas tools/list como bloqueará las solicitudes tools/call. Soporta patrones comodín con *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

Puedes especificar múltiples banderas --ignore-tool para ignorar diferentes patrones. Ejemplos:

• delete* - ignora todas las herramientas que comienzan con "delete" (ej., deleteTask, deleteUser)
• *account - ignora todas las herramientas que terminan con "account" (ej., getAccount, updateAccount)
• exactTool - ignora solo la herramienta llamada exactamente "exactTool"

• Para cambiar el tiempo de espera del callback OAuth (por defecto 30 segundos), agrega la bandera --auth-timeout con un valor en segundos. Esto es útil si el proceso de autenticación en el lado del servidor lleva mucho tiempo.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

Estrategias de Transporte

MCP Remote soporta diferentes estrategias de transporte al conectarse a un servidor MCP. Esto te permite controlar si usa transporte Server-Sent Events (SSE) o HTTP, y en qué orden lo intenta.

Especifica la estrategia de transporte con la bandera --transport:

npx mcp-remote https://example.remote/server --transport sse-only

Estrategias Disponibles:

• http-first (predeterminada): Intenta el transporte HTTP primero, retrocede a SSE si HTTP falla con un error 404
• sse-first: Intenta el transporte SSE primero, retrocede a HTTP si SSE falla con un error 405
• http-only: Solo usa el transporte HTTP, falla si el servidor no lo soporta
• sse-only: Solo usa el transporte SSE, falla si el servidor no lo soporta

Metadatos Estáticos del Cliente OAuth

MCP Remote soporta proporcionar metadatos estáticos del cliente OAuth en lugar de usar los valores predeterminados de mcp-remote. Esto es útil al conectarse a servidores OAuth que esperan identificadores de cliente/software o ámbitos específicos.

Proporciona los metadatos del cliente como una cadena JSON o como una ruta de archivo prefijada con @ usando la bandera --static-oauth-client-metadata: