MCP Remote

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

GitHub
1.6k
Prueba este MCPPatrocinado

Documentación

mcp-remote

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

¿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 API se puede hacer usando 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 sobre 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 lo soportaran todavía. 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 única y prepárate para los clientes MCP que quieras.

Uso

Todos los clientes MCP más populares (Claude Desktop, Cursor y Windsurf) usan 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 para 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, Codex-Cli 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
  }
},

Para mantener una credencial fuera de los argumentos del proceso — donde cualquier otro usuario en la máquina puede leerla desde la lista de procesos — coloca los encabezados en un archivo y pasa --header-file. Un Name: value por línea; # inicia un comentario.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header-file",
        "/path/to/headers.txt"
      ]

# credentials for the example server
Authorization: Bearer my-token
X-Custom-Header: custom-value

Un archivo que no se puede leer es un error en lugar de una advertencia, por lo que una ruta mal escrita falla inmediatamente en lugar de enviar la solicitud sin autenticación.

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, encabezados personalizados y valores de --authorize-param mantendrá sesiones OAuth separadas y almacenamiento de tokens.

El valor de --resource se envía como el indicador de recurso RFC 8707 en las solicitudes de autorización, token y actualización por igual, para que siempre estén de acuerdo.

Parámetros de autorización adicionales

Algunos servidores de autorización requieren sus propios parámetros en la llamada de autorización. Pasa cada uno como --authorize-param key=value, repitiendo la bandera según sea necesario:

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/mcp",
        "--authorize-param",
        "access_type=offline",
        "--authorize-param",
        "prompt=consent"
      ]

Esos dos son lo que Google quiere antes de entregar un token de actualización — no reconoce el ámbito offline_access. Auth0 quiere audience=https://your-api para emitir un JWT en lugar de un token opaco. login_hint=user@example.com también es común.

Estos se aplican solo a la solicitud de autorización. resource es la excepción: RFC 8707 quiere el mismo valor en las solicitudes de token y actualización también, y solo --resource lo coloca allí. Los parámetros que el flujo deriva por solicitud — state, code_challenge, client_id, redirect_uri, response_type — son rechazados, porque un valor que no coincide con el real se manifiesta como un error opaco del servidor.

Cambiar estos inicia un nuevo inicio de sesión, ya que un parámetro como audience decide para qué API es el token y un token emitido para una no es válido para otra.

Algunos servidores de autorización rechazan el parámetro de recurso por completo — Microsoft Entra ID v2 responde AADSTS9010010, por ejemplo. Pasa --disable-resource-parameter para omitirlo por completo:

{
  "mcpServers": {
    "entra-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/mcp",
        "--disable-resource-parameter"
      ]
    }
  }
}

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 a npx a verificar 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, agrega un argumento adicional después de la URL del servidor. Por defecto, el puerto se deriva de la URL del servidor, por lo que cada servidor obtiene un puerto estable propio en algún lugar entre 3335-49150, y mcp-remote sube hasta 8 puertos desde allí si encuentra uno ocupado. Un puerto que pasas explícitamente se usa tal cual: implica un redirect_uri que ya se le ha dado al servidor de autorización, por lo que mcp-remote falla en lugar de moverse silenciosamente a uno diferente. --static-oauth-client-info fija el puerto de la misma manera, por la misma razón.
      "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 cambiar la ruta en la que mcp-remote sirve la devolución de llamada OAuth (por defecto /oauth/callback), agrega la bandera --callback-path. La ruta debe comenzar con /, y /wait-for-auth está reservada.
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--callback-path",
        "/custom/callback"
      ]
  • 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 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 los 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 las 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 de 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"
      ]

  • Para cambiar los tiempos de espera de red, agrega --connect-timeout, --headers-timeout o --body-timeout, cada uno con un valor en segundos. Estos se aplican a cada solicitud saliente, incluidas las de OAuth.

    • --connect-timeout limita el establecimiento de la conexión TCP (predeterminado 10). Redúcelo para fallar más rápido en un servidor inalcanzable.
    • --headers-timeout limita la espera de los encabezados de respuesta (predeterminado 300).
    • --body-timeout limita el intervalo entre fragmentos del cuerpo de una respuesta (predeterminado 300). Este es el que cierra un flujo SSE inactivo después de cinco minutos; pasa 0 para deshabilitarlo en servidores que envían con poca frecuencia.
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--connect-timeout",
        "30",
        "--body-timeout",
        "0"
      ]

  • Para evitar que se elimine una conexión inactiva, agrega la bandera --keep-alive. El proxy entonces envía un ping cada 30 segundos, lo cual es suficiente tráfico para evitar que un servidor — o un balanceador de carga frente a uno — elimine una sesión que ha estado en silencio durante unos minutos. Usa --ping-interval con un valor en segundos para cambiar el período; activarlo enciende el keep-alive, por lo que las dos banderas solo se necesitan juntas cuando quieres que se especifique el período predeterminado.

    Este es el extremo opuesto del problema de --body-timeout: ese gobierna cuánto tiempo nosotros esperamos, mientras que este evita que el otro lado cuelgue.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--keep-alive",
        "--ping-interval",
        "60"
      ]
  • Para conectarte solo a través de IPv4, agrega la bandera --ipv4. Útil cuando un nombre de host resuelve tanto a direcciones IPv4 como IPv6, pero las rutas IPv6 se convierten silenciosamente en agujeros negros en lugar de ser rechazadas — los intentos de conexión entonces se agotan en lugar de fallar, y la solicitud nunca se completa.
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ipv4"
      ]

Estrategias de Transporte

MCP Remote admite diferentes estrategias de transporte al conectarse a un servidor MCP. Esto te permite controlar si usa el transporte de Eventos Enviados por el Servidor (SSE) o 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, y recurre a SSE si HTTP falla con un error 404
  • sse-first: Intenta el transporte SSE primero, y recurre a HTTP si SSE falla con un error 405
  • http-only: Solo usa el transporte HTTP, falla si el servidor no lo admite
  • sse-only: Solo usa el transporte SSE, falla si el servidor no lo admite

Eras de Protocolo (servidores 2026-07-28)

La revisión 2026-07-28 de MCP retiró el protocolo de enlace initialize y la sesión detrás de él. Un servidor que lo implementa atiende solicitudes sin estado que cada una lleva su propia versión de protocolo y capacidades, y se anuncia a través de server/discover en lugar de responder a un protocolo de enlace.

La mayoría de los hosts de escritorio todavía hablan la era 2025-11-25. La matriz de compatibilidad de la especificación coloca ese par — cliente heredado, servidor moderno — en la única celda que simplemente falla, porque un cliente heredado no tiene forma de avanzar. La solución que nombra es un cliente de doble era, que es lo que mcp-remote se convierte con --protocol auto:

npx mcp-remote https://example.remote/mcp --protocol auto

Modos Disponibles:

  • legacy (predeterminado): envía el initialize del cliente directamente, exactamente como cada versión anterior lo hizo. No se sondea nada.
  • auto: gasta un server/discover en el primer protocolo de enlace. Si un servidor 2026-07-28 responde, mcp-remote responde al protocolo de enlace del cliente local por sí mismo y reescribe cada solicitud posterior en la era moderna — _meta por solicitud, con el encabezado MCP-Protocol-Version correspondiente. Si cualquier otra cosa responde, el protocolo de enlace sale sin cambios y nada cambia.

Está desactivado por defecto porque cada servidor en el mundo hoy es uno heredado, y la sonda es un viaje de ida y vuelta que esas conexiones no necesitan.

Las dos superficies modernas sin equivalente 2025-11-25 también se conectan:

  • Notificaciones de cambio. La era moderna solo envía notifications/tools/list_changed y amigos por un flujo subscriptions/listen que el cliente abre. Un cliente de la era 2025 nunca abre uno, por lo que mcp-remote lo abre en nombre del cliente — solicitando exactamente las notificaciones que el servidor dijo que puede enviar — y pasa cada una en la forma que esa era espera.
  • Solicitudes de múltiples rondas. Cuando un servidor responde con input_required, solicitando muestreo, elicitación o raíces en medio de una solicitud, mcp-remote desempaca las preguntas integradas y se las presenta al cliente como las solicitudes ordinarias iniciadas por el servidor que ya entiende, luego reintenta la solicitud original con las respuestas y un eco byte-exacto del requestState del servidor. Al cliente nunca se le dice que esto sucedió: todavía está esperando la única solicitud que envió, y eso es lo que se le responde. Limitado a 10 rondas. Una pregunta que este proxy no puede plantear a un cliente de la era 2025 — cualquier cosa fuera de muestreo, elicitación y raíces, o una elicitación en modo URL, o una que el cliente nunca declaró soportar — se reporta como un error en lugar de descartarse.

Tres métodos que la era moderna retiró son atendidos por mcp-remote mismo en lugar de reenviarse a un servidor que ya no los tiene, porque las capacidades que se le entregan al cliente aún los anuncian:

  • resources/subscribe / resources/unsubscribe se convierten en entradas en el flujo subscriptions/listen, que se reabre cada vez que el conjunto cambia.
  • logging/setLevel se registra y se transporta como el io.modelcontextprotocol/logLevel por solicitud que lo reemplazó — sin el cual un servidor moderno no envía registros en absoluto.

Metadatos de Cliente OAuth Estáticos

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

Proporcione 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'

Lo que proporcione se fusiona sobre los valores predeterminados, por lo que así es también como se fija un valor que mcp-remote de otro modo negociaría. token_endpoint_auth_method se elige del token_endpoint_auth_methods_supported del servidor de autorización: none cuando el servidor acepta clientes públicos, de lo contrario client_secret_post, de lo contrario client_secret_basic. Anúlelo cuando el servidor necesite algo más:

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "token_endpoint_auth_method": "client_secret_post" }'

Información de Cliente OAuth Estática

Según la especificación, se anima a los servidores, aunque no se les exige, a admitir el registro dinámico de clientes OAuth.

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

Proporcione 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'

Documentos de Metadatos de ID de Cliente

SEP-991 permite que un servidor de autorización acepte una URL HTTPS como el client_id, donde esa URL sirve un documento JSON que describe al cliente. Los servidores que lo admiten anuncian "client_id_metadata_document_supported": true en sus metadatos de servidor de autorización, y no se necesita registro dinámico.

Apunte mcp-remote a su documento con --client-metadata-url:

npx mcp-remote https://example.remote/server --client-metadata-url https://client.example.com/.well-known/oauth-client-metadata

La URL debe usar HTTPS y tener una ruta — un origen desnudo se rechaza. Si el servidor no anuncia soporte, mcp-remote se registra dinámicamente como de costumbre, por lo que la bandera es segura de dejar en su lugar.

El documento que aloja debe listar el redirect_uri que mcp-remote enviará, que contiene el puerto de devolución de llamada OAuth. Pasar esta bandera hace que ese puerto sea estricto: mcp-remote usa el puerto derivado de la URL del servidor (o el que pase explícitamente) y falla en lugar de moverse silenciosamente a otro, para que el redirect_uris en su documento permanezca correcto. Ejecútelo una vez para ver el puerto que eligió, o elíjalo usted mismo:

npx mcp-remote https://example.remote/server 3334 --client-metadata-url https://client.example.com/.well-known/oauth-client-metadata

Iniciar Sesión Sin un Usuario

Algunos servidores no están protegidos en nombre de una persona en absoluto — un servidor MCP interno alcanzado por un trabajo programado, por ejemplo, donde no hay usuario que consienta ni navegador en el que consentir. Para esos, --client-credentials usa la concesión de Credenciales de Cliente OAuth: el cliente presenta sus propias credenciales y recibe un token para sí mismo.

npx mcp-remote https://example.remote/mcp \
  --client-credentials \
  --static-oauth-client-info '{"client_id":"my-client","client_secret":"${MCP_CLIENT_SECRET}"}'

Las credenciales provienen de --static-oauth-client-info, que acepta JSON en línea o @path/to/file.json. Los marcadores de posición ${ENV_VAR} se expanden desde el entorno en ambas formas, por lo que el secreto no necesita estar en una línea de comandos donde cualquier otro proceso en la máquina pueda leerlo. Nada registra el valor expandido.

El punto final de token, el ámbito y el indicador resource de RFC 8707 se descubren y aplican de la misma manera que para cualquier otro flujo, y client_secret_basic o client_secret_post se elige de lo que anuncia el servidor de autorización. No hay token de actualización involucrado: las credenciales son lo duradero, por lo que un token caducado se reemplaza pidiendo otro de la misma manera que se obtuvo el primero.

Si un servidor interno no publica metadatos de descubrimiento RFC 9728 o RFC 8414/OIDC, proporcione su punto final de token conocido explícitamente. Esto omite el descubrimiento y solo se acepta con --client-credentials:

npx mcp-remote https://example.remote/mcp \
  --client-credentials \
  --token-endpoint https://auth.example.com/oauth/token \
  --static-oauth-client-info '{"client_id":"my-client","client_secret":"${MCP_CLIENT_SECRET}"}' \
  --static-oauth-client-metadata '{"scope":"mcp.read mcp.write","token_endpoint_auth_method":"client_secret_basic"}'

El punto final explícito debe usar HTTPS, excepto para un punto final de bucle de retorno HTTP. Se rechazan credenciales y fragmentos de URL en la URL del punto final, y cambiar el punto final selecciona una caché de tokens separada. El descubrimiento también se omite en el arranque en frío y en los reintentos de 401. Los tokens se renuevan antes de la caducidad usando las mismas credenciales de cliente; si la renovación falla, el token actual se envía hasta que el servidor lo rechace. Con un punto final explícito, scope se omite a menos que se configure con --static-oauth-client-metadata o se nombre en el desafío 401 del servidor, y resource se omite a menos que se establezca con --resource.

Iniciar Sesión Sin un Navegador

El flujo predeterminado necesita un navegador en esta máquina y un puerto de bucle de retorno para redirigir de vuelta — lo que un trabajo cron, una sesión SSH o un contenedor no tienen. Si su servidor de autorización admite la Concesión de Autorización de Dispositivo OAuth, --device-code mueve el navegador a cualquier máquina en la que realmente esté sentado:

npx mcp-remote https://example.remote/server --device-code

mcp-remote imprime un código corto y una URL, luego sondea hasta que lo apruebe:

To authorize this client, visit:
  https://auth.example.com/activate

And enter the code: WDJB-MJHT

Waiting for approval...

La salida va a stderr, que los clientes MCP capturan en sus propios registros — así que en una ejecución sin cabeza, ese registro es donde lee el código. Esto solo tiene que suceder una vez: el token de actualización que regresa se almacena como cualquier otro, y las ejecuciones posteriores son no interactivas.

No se inicia ningún servidor de devolución de llamada y no se vincula ningún puerto, por lo que este es también el flujo a usar cuando el puerto de bucle de retorno no está disponible.

El servidor debe anunciar device_authorization_endpoint en sus metadatos de servidor de autorización; mcp-remote falla con un mensaje claro en lugar de recurrir a un navegador que no está allí. Tenga en cuenta que los servidores que ofrecen esta concesión a menudo esperan un cliente pre-registrado — combínelo con --static-oauth-client-info si se rechaza el registro dinámico.

Persistencia de Sesión del Balanceador de Carga

Las sesiones MCP viven en un backend, por lo que un servidor detrás de un balanceador de carga necesita que cada solicitud de un cliente llegue al mismo nodo. AWS ALB, Azure Load Balancer y otros hacen esto con una cookie que se espera que el cliente devuelva.

mcp-remote mantiene las cookies que el servidor MCP establece y las reenvía en solicitudes posteriores, incluso desde el flujo SSE hacia los POST que lo siguen. Nada que configurar. Las cookies se mantienen en memoria durante la vida del proceso, nunca se escriben en disco, y solo se envían de vuelta al origen exacto que las estableció — Domain se ignora, por lo que nada viaja a otro host.

Un Cookie que pase usted mismo con --header siempre gana.

Para desactivarlo:

npx mcp-remote https://example.remote/server --disable-cookies

Usar el Token de ID como Credencial de Portador

Por defecto, mcp-remote envía el token de acceso OAuth, que dice lo que al llamante se le permite hacer. Algunos servidores en su lugar verifican quién es el llamante: validan un token de ID OIDC contra un punto final JWKS y leen afirmaciones de identidad como sub y email de él. AWS Cognito frente a Bedrock AgentCore funciona de esta manera, y rechaza el token de acceso por completo.

Pase --use-id-token para enviar el token de ID en su lugar:

npx mcp-remote https://example.remote/server --use-id-token

Solo cambia la credencial presentada al servidor MCP — el token de actualización y el flujo de renovación no se tocan. La renovación sigue la afirmación exp del propio token de ID en lugar de la vida útil del token de acceso, ya que el token de ID es lo que realmente va por el cable.

Un token de ID solo se emite cuando openid está entre los ámbitos solicitados. Si su servidor no lo anuncia, pídalo explícitamente:

npx mcp-remote https://example.remote/server --use-id-token --static-oauth-client-metadata '{ "scope": "openid email" }'

Claude Desktop

Documentos Oficiales

Para agregar un servidor MCP a Claude Desktop, debe 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 deba habilitarlo en Configuración > Desarrollador.

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

Cursor

Documentos Oficiales. 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 su servidor MCP usa el protocolo de autorización OAuth oficial de MCP, aún necesita agregar un servidor "command" y llamar a mcp-remote.

Windsurf

Documentos Oficiales. 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, consulte los siguientes recursos:

En particular, consulte:

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

¿Conoce más recursos que le gustaría compartir? ¡Agréguelos a este Readme y envíe un PR!

Solución de Problemas

Limpie su directorio ~/.mcp-auth

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

rm -rf ~/.mcp-auth

Luego reinicie su cliente MCP.

Las credenciales se almacenan bajo mcp-remote-v1, que nombra el diseño del almacén en lugar de la versión del paquete, por lo que actualizar mcp-remote ya no lo desconecta. Las versiones anteriores a este cambio mantenían un directorio separado por versión — si tiene directorios ~/.mcp-auth/mcp-remote-0.x.y sobrantes, contienen tokens antiguos y pueden eliminarse.

Verifique su versión de Node

Asegúrese de que la versión de Node que tiene instalada sea https://modelcontextprotocol.io/quickstart/server. Claude Desktop usará su versión del sistema de Node, incluso si tiene una versión más nueva instalada en otro lugar.

Reinicie Claude

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

Certificados VPN

Puede encontrar problemas si está detrás de una VPN; puede intentar establecer la variable de entorno NODE_EXTRA_CA_CERTS para que apunte al archivo de certificado CA. Si usa 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"
      }
    }
  }
}

Revise los registros

  • Siga 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 renovación de tokens o problemas de autenticación, use 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 encuentre problemas con la renovación de tokens, problemas de suspensión/reanudación de la computadora portátil o problemas de autenticación, proporcione estos registros al buscar soporte.

Errores de Autenticación

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

Authentication Error
Token exchange failed: HTTP 400

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

Modo "Cliente"

Ejecute 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. Intente esto después de ejecutar rm -rf ~/.mcp-auth para ver si las credenciales obsoletas son su problema; de lo contrario, con suerte el problema será más obvio en estos registros que en los de su cliente MCP.

Agradecimientos

Glen Maddern es el autor original de mcp-remote. Él construyó mcp-remote en uno de los bloques de construcción más populares en el ecosistema MCP.