Túnel MCP seguro

El túnel MCP seguro te permite conectar servidores MCP privados a productos de OpenAI compatibles sin abrir puertos de entrada en el firewall ni exponer los servidores a la internet pública. Ejecuta tunnel-client dentro de la red que ya tiene acceso a tu servidor MCP. El cliente abre una conexión HTTPS saliente a OpenAI, recupera las tareas MCP en cola, reenvía las solicitudes localmente y devuelve las respuestas por el mismo túnel.

¿Qué es un túnel MCP?

Un túnel MCP es una conexión de solo salida desde un host dentro de tu red hasta un punto de acceso MCP alojado en OpenAI. Úsalo cuando tu servidor MCP sea privado, esté alojado en tus instalaciones o esté detrás de un firewall y ChatGPT, Codex, la API de Responses u otra interfaz compatible de OpenAI necesite llamarlo.

El túnel MCP seguro mantiene privado el servidor MCP y ofrece a los productos de OpenAI compatibles una vía habitual para enviar solicitudes MCP. tunnel-client consulta periódicamente a OpenAI para obtener tareas, reenvía las solicitudes MCP localmente y devuelve las respuestas por el mismo túnel.

Cuándo usar el túnel MCP seguro

• Tu servidor MCP se ejecuta en una red privada, en tus instalaciones o en un equipo de desarrollo, o está protegido por controles de acceso existentes.
• Quieres que ChatGPT, Codex, la API de Responses u otra interfaz compatible de OpenAI use ese servidor sin hacerlo público.
• Tu red permite que el host que ejecuta tunnel-client envíe solicitudes HTTPS salientes a api.openai.com:443 de forma predeterminada, o a mtls.api.openai.com:443 si configuraste mTLS para el plano de control, y que acceda al servidor MCP privado.
• Consulta primero la guía de servidores MCP para conocer los conceptos generales de MCP.

Cómo funciona

1. Crea o administra un punto de acceso de túnel MCP alojado en OpenAI desde la configuración de túneles de la Plataforma API.
2. Ejecuta tunnel-client dentro de la red que tiene acceso a tu servidor MCP privado.
3. Configura tunnel-client con la identidad del túnel y la dirección del servidor MCP privado.
4. Los productos de OpenAI envían solicitudes MCP al punto de acceso del túnel alojado en OpenAI.
5. tunnel-client usa sondeo prolongado para obtener las tareas en cola, reenvía cada solicitud JSON-RPC al servidor MCP privado y devuelve la respuesta por el túnel.

El servidor MCP privado no necesita escuchar conexiones públicas. El punto de acceso alojado en OpenAI ofrece a los productos compatibles una vía habitual para enviar solicitudes MCP, mientras que la conexión se inicia dentro de tu red. Cuando un conector solicita resultados en streaming, el túnel puede reenviar los eventos intermedios enviados por el servidor.

Antes de empezar

Necesitas lo siguiente:

• Un tunnel_id de la configuración de túneles de la Plataforma API.
• Una clave de API para ejecutar tunnel-client.
• Un servidor MCP al que tunnel-client pueda acceder mediante stdio o HTTP desde tu red.

Permisos y acceso

Los permisos de túneles de la Plataforma API son independientes del acceso a servidores MCP personalizados en ChatGPT:

• Para crear o editar un túnel, necesitas los permisos de túneles Lectura + Administración.
• Para ejecutar tunnel-client o seleccionar el túnel al crear una app, necesitas los permisos de túneles Lectura + Uso.
• Los permisos de túneles se aplican a una organización de la Plataforma API. Un propietario de la organización o un administrador de RBAC otorga el rol de túneles.
• Para agregar y usar servidores MCP personalizados en ChatGPT, se siguen aplicando los permisos y las restricciones de seguridad del espacio de trabajo. Consulta Agregar un servidor MCP personalizado.

Pide al administrador del espacio de trabajo de ChatGPT donde usarás el servidor que te dé permiso para agregar y usar servidores MCP personalizados. Solicita los permisos de túneles al propietario de la organización correspondiente de la Plataforma API o a su administrador de RBAC.

Asocia los túneles con las organizaciones y los espacios de trabajo correctos

Puedes asociar un túnel con una o más organizaciones de la Plataforma API o espacios de trabajo de ChatGPT. Usa estas asociaciones para definir todos los contextos de OpenAI que deben tener permiso para encontrar o usar el túnel.

• Incluye la organización de la Plataforma API que es propietaria del túnel o lo administra.
• Incluye el espacio de trabajo de ChatGPT que debe mostrar el túnel al crear apps.
• Incluye otra organización de la Plataforma API si Codex, la API de Responses u otro producto compatible va a llamar al servidor MCP privado desde esa organización.
• Usa el mismo tunnel_id para tunnel-client. Agregar organizaciones o espacios de trabajo no crea un segundo túnel ni cambia el punto de acceso del servidor MCP privado.

Para las cuentas personales, usa la organización personal de la Plataforma API que corresponde a la cuenta. Para hacer pruebas con ChatGPT y Codex, asocia el túnel con el espacio de trabajo de ChatGPT donde harás las pruebas y con la organización de la Plataforma API que usará Codex. Un túnel asociado únicamente con una organización personal de la Plataforma API no aparece automáticamente en un espacio de trabajo Enterprise o Edu.

Si la organización de la Plataforma API y el espacio de trabajo de ChatGPT ya están vinculados, puedes agregar la organización o el espacio de trabajo que falte en la configuración de túneles de la Plataforma API. Si no se puede verificar automáticamente tu configuración empresarial, por ejemplo, porque la organización de la Plataforma API no tiene un espacio de trabajo de ChatGPT correspondiente, comunícate con el equipo de OpenAI que atiende tu cuenta. Pídele que revise el caso y autorice una excepción para asociar manualmente la cuenta empresarial que debe usar el túnel.

Requisitos de red

tunnel-client no necesita aceptar conexiones entrantes desde internet. Necesita acceso HTTPS saliente a OpenAI y acceso local al servidor MCP privado:

Límites

El túnel MCP seguro aplica estos límites predeterminados a la creación de túneles y al tráfico MCP de los conectores:

Estos límites protegen el servicio y no garantizan un rendimiento ni una latencia determinados. Conservar los registros de la cola para su posterior limpieza no amplía el plazo de 120 segundos de la solicitud. Para solicitar un límite mayor de túneles o de tráfico, comunícate con el equipo de soporte de OpenAI.

Configura tunnel-client

Abre la configuración de túneles de la Plataforma API y usa el enlace de descarga que aparece allí o descarga la última versión pública de tunnel-client desde openai/tunnel-client. Usa en tu guía operativa la URL que apunta a la versión más reciente en lugar de fijar la URL de una versión específica.

Si ya tienes un binario, comienza con tunnel-client help quickstart. Para usar un perfil stdio local con nombre, ejecuta lo siguiente:

12345678910export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile local-stdio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "python /path/to/server.py"

tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio

Para un servidor MCP que usa HTTP, usa --mcp-server-url https://mcp.internal.example.com/mcp en lugar de --mcp-command.

Mantén tunnel-client run ... en ejecución y comprueba que funcione correctamente mientras creas o pruebas la app. Tanto la detección de la app como las llamadas a herramientas MCP dependen de que el cliente esté en ejecución.

Elige dónde ejecutar tunnel-client

Ejecuta tunnel-client dentro del mismo perímetro de confianza desde el que ya se puede acceder al servidor MCP privado. Estas son algunas opciones de implementación habituales:

• Sidecar de Kubernetes: ejecuta tunnel-client junto al servidor MCP en un mismo Pod y establece la conexión mediante localhost.
• Deployment dedicado de Kubernetes: ejecuta tunnel-client por separado si ya se puede acceder al servidor MCP mediante un Service privado.
• Máquina virtual o servicio de systemd: ejecuta tunnel-client en un host que tenga acceso al servidor MCP a través de una red privada.

Conéctate desde ChatGPT

Ve a Complementos de ChatGPT, selecciona el botón con el signo más, luego Agregar servidor MCP personalizado y elige Túnel en Conexión. Selecciona un túnel disponible cuando ChatGPT lo muestre o pega un tunnel_id válido si ya tienes uno. Configura la autenticación, revisa la advertencia sobre los riesgos y selecciona Entiendo y quiero continuar y luego Crear como complemento.

Si el túnel no aparece en ChatGPT, verifica que esté asociado con el espacio de trabajo de ChatGPT correspondiente y no solo con una organización de la Plataforma API. Comprueba también que quien crea la app tenga los permisos de túneles Lectura + Uso.

Configura y verifica el túnel con Codex

Para que Codex te guíe durante la configuración, dale acceso desde el navegador a la Plataforma API y a ChatGPT, y acceso desde la terminal al host que puede conectarse a tu servidor MCP privado. Pega este prompt en Codex:

Ayúdame a configurar un túnel MCP seguro y privado desde mi servidor MCP interno
hasta ChatGPT y a verificar la conexión de extremo a extremo. Usa el acceso al
navegador o a la computadora y una terminal. Sigue las instrucciones de
https://developers.openai.com/api/docs/guides/secure-mcp-tunnels y
https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md y consulta
la interfaz actual y la ayuda de la CLI a medida que avances.

Primero, identifica la organización de la Plataforma API y el espacio de trabajo
de ChatGPT que se usarán, la URL HTTP o el comando stdio del servidor MCP y el
host donde se ejecutará el cliente. Revisa los túneles, las claves y los
complementos MCP personalizados de ChatGPT que ya existan y reutiliza los
recursos adecuados. Confirma que el túnel esté asociado con la organización y
el espacio de trabajo correctos. Verifica también los permisos de túneles.
Quienes crean túneles necesitan Lectura + Administración. Tanto la clave
restringida que se usa para ejecutar el cliente como el operador del complemento
necesitan Lectura + Uso.

No incluyas los valores de los secretos en el chat, los argumentos de los
comandos, los registros, las capturas de pantalla ni los archivos de
configuración. Pídeme que los proporcione localmente mediante un mecanismo de
entrada seguro o una referencia a una variable de entorno. Instala la versión
compatible de tunnel-client, ejecuta `tunnel-client help quickstart`, configura
el servidor y ejecuta `tunnel-client doctor --profile <name> --explain`. Inicia
el cliente y comprueba que esté listo y que esté consultando la cola. Déjalo
en ejecución para que ChatGPT pueda detectar la app y llamar a sus herramientas.

En Complementos de ChatGPT, agrega un servidor MCP personalizado privado o
termina de configurar uno existente. En Conexión, elige Túnel. Selecciona el
mismo túnel, configura la autenticación requerida y haz una llamada segura a
una herramienta que sea representativa del uso previsto. Indica qué observaste
en cada comprobación. Si algo impide continuar, indica el error exacto y el
siguiente paso. Da por terminada la configuración solo después de que la
llamada a la herramienta desde ChatGPT se complete con éxito.

Conéctate desde la API de Responses

Pasa el identificador del túnel como tunnel_id en la definición de la herramienta MCP. No pases el punto de acceso del túnel alojado en OpenAI como server_url. Usa server_url solo para un servidor MCP al que la API de Responses pueda acceder directamente.

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Use the private MCP server to answer my request.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "private_mcp",
        "tunnel_id": "tunnel_0123456789abcdef0123456789abcdef"
      }
    ]
  }'

Seguridad y redes

• La dirección del servidor MCP se mantiene privada y solo se usa desde el entorno donde se ejecuta tunnel-client.
• tunnel-client se autentica ante el plano de control de túneles de OpenAI. Los productos de OpenAI compatibles usan el punto de acceso del túnel alojado en OpenAI.
• El acceso al túnel se rige por el contexto existente de la organización y el espacio de trabajo, sin abrir una vía pública de entrada independiente.
• tunnel-client admite requisitos de redes empresariales como proxies de salida, paquetes personalizados de certificados de autoridades de certificación, certificados de cliente para el plano de control y mTLS del lado de MCP.

Alcance de los registros

El túnel MCP seguro separa el transporte por el túnel de los registros del producto a nivel de la app:

• El túnel no genera eventos de app en la Plataforma de cumplimiento de ChatGPT para la autenticación en el plano de control, el tráfico de sondeo prolongado y de respuestas ni las solicitudes individuales de transporte por el túnel.
• Los cambios en los metadatos del túnel aparecen en los registros de auditoría de la Plataforma API como tunnel.created, tunnel.updated y tunnel.deleted.
• Cuando ChatGPT accede a una app personalizada mediante el túnel MCP seguro, el túnel solo se encarga del transporte. La app sigue generando sus registros habituales de cumplimiento, incluidos los registros de invocación de la app y los del ciclo de vida de la autenticación, como APP_AUTH_LOG cuando se vincula o desvincula la app.

Uso avanzado: llamadas HTTP a destinos permitidos

El túnel MCP seguro también admite llamadas HTTP de alcance limitado desde flujos compatibles de agentes o API hacia la red de un cliente. tunnel-client incluye un servidor MCP integrado, Harpoon, que expone los destinos HTTP configurados mediante etiquetas y permite llamarlos a través del túnel con límites para las solicitudes y las respuestas.

Usa esta opción cuando necesites acceder a un conjunto reducido de puntos de acceso REST privados sin exponerlos públicamente. Harpoon no es un proxy de uso general: quien hace la llamada no puede elegir hosts arbitrarios y las solicitudes se limitan a los destinos y métodos configurados por el cliente.

Solución de problemas

• “Se requiere acceso a los túneles” en la configuración de túneles de la Plataforma API: los permisos de túneles se otorgan a nivel de organización, no de proyecto. Selecciona la organización de la Plataforma API que quieres usar y pide a un propietario de la organización o a un administrador de RBAC que te agregue a un rol o grupo con Lectura para ver túneles o con Lectura + Administración para crearlos, editarlos o eliminarlos. Si no existe un rol adecuado, puede crearlo, asignarlo a un grupo y agregarte a ese grupo. También necesitas Uso para ejecutar tunnel-client o seleccionar un túnel en la configuración del conector. Una nueva asignación de rol puede tardar hasta 30 minutos en propagarse.
• El túnel no aparece en ChatGPT: comprueba que el túnel esté asociado con el espacio de trabajo de ChatGPT que quieres usar y no solo con una organización de la Plataforma API. Luego verifica que el operador del conector tenga el permiso de túneles Uso. Si el espacio de trabajo no se puede vincular automáticamente a una cuenta empresarial, comunícate con el equipo de OpenAI que atiende tu cuenta para que revise el caso y autorice una excepción para realizar la asociación manualmente.
• Falla la detección del conector o fallan las llamadas a herramientas: comprueba que tunnel-client run ... siga en ejecución y vuelve a ejecutar tunnel-client doctor --profile <name> --explain.
• Puedes inspeccionar un túnel pero no editarlo: es probable que el operador tenga el permiso de túneles Lectura, pero le falte el permiso de túneles Administración.
• tunnel-client expone /healthz, /readyz, /metrics y una interfaz de administración local en /ui.
• De forma predeterminada, la interfaz de administración solo es accesible mediante la interfaz de loopback. Habilita el acceso remoto únicamente si necesitas permitir el acceso desde una red de operadores.
• Usa estas interfaces para comprobar que el cliente funcione correctamente, esté listo y realice sondeos antes de hacer pruebas desde ChatGPT, Codex o un flujo de API.
• Si el cliente está desconectado, las solicitudes por el túnel fallarán hasta que tunnel-client se vuelva a conectar.
• El registro del tráfico HTTP sin procesar está desactivado de forma predeterminada y los datos sensibles se ocultan en las exportaciones para soporte.

OAuth

• La detección de OAuth puede realizarse a través del túnel para que el servidor MCP se mantenga privado.
• El túnel conserva los metadatos del servidor de autorización de origen que necesitan los flujos de OAuth en el navegador.
• El servidor de autorización no queda conectado automáticamente a través del túnel. Si no se puede acceder a él desde la internet pública ni desde el host de tunnel-client, el flujo de OAuth puede fallar aunque el servidor MCP sea accesible.

Dónde configurar el túnel

• Administra los puntos de acceso de túneles MCP alojados en OpenAI desde la configuración de túneles de la Plataforma API.
• Usa un túnel al agregar un servidor MCP personalizado en Complementos de ChatGPT.
• Para flujos de Codex o de API, usa el destino MCP conectado al túnel que ofrece la interfaz del producto compatible.

Próximos pasos

• Crea o administra el túnel en la configuración de túneles de la Plataforma API.
• Valida tu perfil de tunnel-client con tunnel-client doctor --profile <profile> --explain.
• Conéctate al túnel desde Complementos de ChatGPT o desde la interfaz compatible de OpenAI que estés usando.