MCP Remote

Un proxy remoto para MCP que permite a los clientes locales conectarse a servidores remotos mediante OAuth.

Documentación

`mcp-remote`

Conecta un cliente MCP que solo admite 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 en el mundo 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 de API se puede hacer mediante variables de entorno y nunca salen de tu máquina. Y construir sobre npx y uvx ha permitido a los usuarios evitar pasos de instalación explícitos también.

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 computadoras portátiles de los usuarios. O al menos, lo tendrí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 prepárate 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"
      ]
    }
  }
}

Encabezados personalizados

Para omitir la autenticación o emitir encabezados personalizados en todas las solicitudes a tu servidor remoto, pasa los argumentos CLI --header:

{
  "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 se invoca npx, lo que termina distorsionando estos valores. Puedes solucionarlo usando:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

Múltiples instancias

Para ejecutar múltiples instancias del mismo servidor remoto con diferentes configuraciones (por ejemplo, diferentes inquilinos de Atlassian), usa la bandera --resource para aislar las sesiones OAuth:

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    },
    "atlassian_tenant2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant2.atlassian.net/"
      ]
    }
  }
}

Cada combinación única de URL del servidor, recurso y encabezados personalizados mantendrá sesiones OAuth y almacenamiento de tokens separados.

Banderas

Si npx está produciendo 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 que npx siempre verifique 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 cualquier 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 devolución de llamada 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 confiables, 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 de depuración detallados, 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 suprimir registros predeterminados, agrega la bandera --silent. Esto evitará que se emitan registros, excepto en el caso de que también se pase --debug.

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

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 de las respuestas tools/list como bloqueará las solicitudes tools/call. Admite 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" (por ejemplo, deleteTask, deleteUser)
*account - ignora todas las herramientas que terminan con "account" (por ejemplo, getAccount, updateAccount)
exactTool - ignora solo la herramienta llamada exactamente "exactTool"

Para cambiar el tiempo de espera para la devolución de llamada 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 toma mucho tiempo.

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

Estrategias de transporte

MCP Remote admite diferentes estrategias de transporte al conectarse a un servidor MCP. Esto te permite controlar si usa Eventos enviados por el servidor (SSE) o transporte HTTP, y en qué orden los intenta.

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

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

Estrategias disponibles:

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

Metadatos estáticos del cliente OAuth

MCP Remote admite 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 ID de cliente/software o ámbitos específicos.

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

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

Información estática del cliente OAuth

Según la especificación, se recomienda, pero no se requiere, que los servidores admitan el registro dinámico de clientes OAuth.

Para estos servidores, MCP Remote admite proporcionar información estática del cliente OAuth en su lugar. Esto es útil al conectarse a servidores OAuth que requieren clientes pre-registrados.

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

export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

Documentación oficial

Para agregar un servidor MCP a Claude Desktop, debes editar el archivo de configuración ubicado en:

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

Si aún no existe, es posible que debas habilitarlo en Configuración > Desarrollador.

Reinicia Claude Desktop para que se apliquen los cambios en el archivo de configuración. Al reiniciar, deberías ver un ícono de martillo en la esquina inferior derecha del cuadro de entrada.

Cursor

Documentación oficial. El archivo de configuración se encuentra en ~/.cursor/mcp.json.

A partir de la versión 0.48.0, Cursor admite servidores SSE sin autenticación directamente. Si tu servidor MCP usa el protocolo de autorización OAuth oficial de MCP, aún necesitas agregar un servidor "command" y llamar a mcp-remote.

Windsurf

Documentación oficial. El archivo de configuración se encuentra en ~/.codeium/windsurf/mcp_config.json.

Construcción de servidores MCP remotos

Para instrucciones sobre cómo construir e implementar servidores MCP remotos, incluido actuar como un cliente OAuth válido, consulta los siguientes recursos:

https://developers.cloudflare.com/agents/guides/remote-mcp-server/

En particular, consulta:

https://github.com/cloudflare/workers-oauth-provider para definir un servidor OAuth compatible con MCP en Cloudflare Workers
https://github.com/cloudflare/agents/tree/main/examples/mcp para definir un McpAgent usando el framework agents.

Para obtener más información sobre cómo probar estos servidores, consulta también:

https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

¿Conoces más recursos que te gustaría compartir? ¡Agrégalos a este Readme y envía un PR!

Solución de problemas

Limpia tu directorio `~/.mcp-auth`

mcp-remote almacena toda la información de credenciales dentro de ~/.mcp-auth (o donde apunte tu MCP_REMOTE_CONFIG_DIR). Si tienes problemas persistentes, intenta ejecutar:

rm -rf ~/.mcp-auth

Luego reinicia tu cliente MCP.

Verifica tu versión de Node

Asegúrate de que la versión de Node que tienes instalada sea 18 o superior. Claude Desktop usará la versión de Node de tu sistema, incluso si tienes una versión más nueva instalada en otro lugar.

Reinicia Claude

Al modificar claude_desktop_config.json, puede ser útil reiniciar Claude por completo.

Certificados VPN

Puedes encontrar problemas si estás detrás de una VPN; puedes intentar configurar la variable de entorno NODE_EXTRA_CA_CERTS para que apunte al archivo de certificado CA. Si usas claude_desktop_config.json, esto podría verse así:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

Revisa los registros

Sigue los registros de Claude Desktop en tiempo real
MacOS / Linux:
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
Para bash en WSL:
tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
Powershell:
Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Depuración

Registros de depuración

Para solucionar problemas complejos, especialmente con la actualización de tokens o problemas de autenticación, usa la bandera --debug:

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

Esto crea registros detallados en ~/.mcp-auth/{server_hash}_debug.log con marcas de tiempo e información completa sobre cada paso del proceso de conexión y autenticación. Cuando encuentres problemas con la actualización de tokens, problemas de suspensión/reanudación de la computadora portátil o problemas de autenticación, proporciona estos registros al buscar soporte.

Errores de autenticación

Si encuentras el siguiente error, devuelto por la URL /callback:

Authentication Error
Token exchange failed: HTTP 400

Puedes ejecutar rm -rf ~/.mcp-auth para limpiar cualquier estado y tokens almacenados localmente.

Modo "Cliente"

Ejecuta lo siguiente en la línea de comandos (no desde un servidor MCP):

npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse

Esto ejecutará todo el flujo de autorización e intentará listar las herramientas y recursos en la URL remota. Intenta esto después de ejecutar rm -rf ~/.mcp-auth para ver si las credenciales obsoletas son tu problema; de lo contrario, con suerte el problema será más evidente en estos registros que en los de tu cliente MCP.