Túnel MCP seguro

Com o túnel MCP seguro, você pode conectar servidores MCP privados aos produtos da OpenAI compatíveis sem abrir portas de entrada no firewall nem expor os servidores à internet pública. Execute tunnel-client na rede que já tem acesso ao servidor MCP. O cliente abre uma conexão HTTPS de saída com a OpenAI, busca as solicitações MCP na fila, encaminha essas solicitações localmente e devolve as respostas pelo mesmo túnel.

O que é um túnel MCP?

Um túnel MCP é uma conexão exclusivamente de saída entre um host da sua rede e um endpoint MCP hospedado pela OpenAI. Use o túnel quando o servidor MCP for privado, estiver na sua infraestrutura ou atrás de um firewall e o ChatGPT, o Codex, a API Responses ou outra interface compatível da OpenAI precisar acessá-lo.

O túnel MCP seguro mantém o servidor MCP privado e oferece aos produtos da OpenAI compatíveis um caminho padrão para solicitações MCP. O tunnel-client consulta a OpenAI em busca de solicitações, encaminha as solicitações MCP localmente e devolve as respostas pelo mesmo túnel.

Quando usar o túnel MCP seguro

• O servidor MCP é executado em uma rede privada, na sua infraestrutura, na máquina de um desenvolvedor ou em um ambiente protegido por controles de acesso existentes.
• Você quer que o ChatGPT, o Codex, a API Responses ou outra interface compatível da OpenAI use esse servidor sem torná-lo público.
• Sua rede permite que o host que executa tunnel-client faça solicitações HTTPS de saída para api.openai.com:443 por padrão, ou para mtls.api.openai.com:443 quando o mTLS do plano de controle estiver configurado, e acesse o servidor MCP privado.
• Para conhecer os conceitos gerais de MCP, comece pelo guia de servidores MCP.

Como funciona

1. Crie ou gerencie um endpoint de túnel MCP hospedado pela OpenAI nas configurações de túneis da plataforma.
2. Execute tunnel-client na rede que tem acesso ao servidor MCP privado.
3. Configure tunnel-client com a identidade do túnel e o endereço do servidor MCP privado.
4. Os produtos da OpenAI enviam solicitações MCP ao endpoint do túnel hospedado pela OpenAI.
5. O tunnel-client usa long polling para buscar solicitações na fila, encaminha cada solicitação JSON-RPC ao servidor MCP privado e envia a resposta de volta pelo túnel.

O servidor MCP privado não precisa escutar conexões públicas. O endpoint hospedado pela OpenAI oferece aos produtos compatíveis um caminho padrão para solicitações MCP, e a conexão é iniciada de dentro da sua rede. Quando um conector solicita resultados em streaming, o túnel pode encaminhar eventos intermediários enviados pelo servidor.

Antes de começar

Você precisa de:

• Um tunnel_id obtido nas configurações de túneis da plataforma.
• Uma chave de API para executar tunnel-client.
• Um servidor MCP que tunnel-client consiga acessar via stdio ou HTTP de dentro da sua rede.

Permissões e acesso

As permissões de túnel da plataforma são independentes das permissões de acesso a servidores MCP personalizados no ChatGPT:

• Para criar ou editar um túnel, você precisa das permissões Leitura + Gerenciamento de túneis.
• Para executar tunnel-client ou selecionar o túnel durante a criação de um aplicativo, você precisa das permissões Leitura + Uso de túneis.
• As permissões de túnel se aplicam a uma organização da plataforma. O proprietário da organização ou um administrador de RBAC atribui a função de acesso aos túneis.
• A adição e o uso de servidores MCP personalizados no ChatGPT continuam sujeitos às permissões e restrições de segurança do espaço de trabalho. Consulte Adicionar um servidor MCP personalizado.

Peça ao administrador do espaço de trabalho do ChatGPT em que você pretende usar o servidor a permissão para adicionar e usar servidores MCP personalizados. Para obter as permissões de túnel, fale com o proprietário da organização correspondente na plataforma ou com o administrador de RBAC.

Associe os túneis às organizações e aos espaços de trabalho corretos

Você pode associar um túnel a uma ou mais organizações da plataforma ou espaços de trabalho do ChatGPT. Use essas associações para definir todos os contextos da OpenAI em que será possível encontrar ou usar o túnel.

• Inclua a organização da plataforma que é proprietária do túnel ou que o gerencia.
• Inclua o espaço de trabalho do ChatGPT que deve exibir o túnel durante a criação de aplicativos.
• Inclua outra organização da plataforma se o Codex, a API Responses ou outro produto compatível for chamar o servidor MCP privado a partir dessa organização.
• Use o mesmo tunnel_id para tunnel-client. Adicionar organizações ou espaços de trabalho não cria outro túnel nem altera o endpoint do servidor MCP privado.

Para contas pessoais, use a organização pessoal da plataforma vinculada à conta. Para testar com o ChatGPT e o Codex, associe o túnel ao espaço de trabalho do ChatGPT em que você fará os testes e à organização da plataforma que o Codex usará. Um túnel associado apenas a uma organização pessoal da plataforma não aparece automaticamente em um espaço de trabalho Enterprise ou Edu.

Se a organização da plataforma e o espaço de trabalho do ChatGPT já estiverem vinculados, você poderá adicionar a organização ou o espaço de trabalho que falta nas configurações de túneis da plataforma. Se não for possível verificar automaticamente a configuração da sua empresa, por exemplo, quando a organização da plataforma não tiver um espaço de trabalho correspondente no ChatGPT, entre em contato com a equipe da OpenAI responsável pela sua conta. Solicite a análise de uma exceção para associar manualmente a conta empresarial que deve usar o túnel.

Requisitos de rede

O tunnel-client não precisa receber conexões da internet. Ele precisa de uma conexão HTTPS de saída com a OpenAI e de acesso local ao servidor MCP privado:

Limites

O túnel MCP seguro aplica os seguintes limites padrão à criação de túneis e ao tráfego MCP dos conectores:

Esses limites protegem o serviço e não garantem taxa de processamento nem latência. A retenção de registros da fila para limpeza não estende o prazo de 120 segundos da solicitação. Para solicitar um limite maior de túneis ou de tráfego, entre em contato com o suporte da OpenAI.

Configure o tunnel-client

Abra as configurações de túneis da plataforma e use o link de download disponível nessa página ou obtenha a versão pública mais recente do tunnel-client em openai/tunnel-client. No seu manual de operações, use a URL que sempre aponta para a versão mais recente, em vez de fixar a URL de uma versão específica.

Se você já tiver o binário, comece com tunnel-client help quickstart. Para usar um perfil local de stdio com nome definido, execute:

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 um servidor MCP que usa HTTP, use --mcp-server-url https://mcp.internal.example.com/mcp em vez de --mcp-command.

Mantenha tunnel-client run ... em execução e funcionando normalmente enquanto cria ou testa o aplicativo. A descoberta do aplicativo e as chamadas de ferramentas MCP dependem do cliente em execução.

Escolha onde executar o tunnel-client

Execute tunnel-client no perímetro de confiança que já tem acesso ao servidor MCP privado. Estas são algumas configurações comuns de implantação:

• Sidecar no Kubernetes: execute tunnel-client no mesmo Pod do servidor MCP e conecte-se via localhost.
• Deployment dedicado no Kubernetes: execute tunnel-client separadamente quando o servidor MCP já estiver acessível por um Service privado.
• Máquina virtual ou serviço systemd: execute tunnel-client em um host que tenha acesso ao servidor MCP pela rede privada.

Conecte-se pelo ChatGPT

Acesse Plug-ins do ChatGPT, selecione o botão de adição e depois Adicionar servidor MCP personalizado. Escolha Túnel em Conexão. Selecione um túnel disponível na lista do ChatGPT ou cole um tunnel_id válido, caso já tenha um. Configure a autenticação, leia o aviso de risco e selecione Entendo e quero continuar. Em seguida, selecione Criar como plugin.

Se o túnel não aparecer no ChatGPT, verifique se está associado ao espaço de trabalho do ChatGPT que você pretende usar. Uma associação apenas com a organização da plataforma é insuficiente. Confira também se quem cria o aplicativo tem as permissões Leitura + Uso de túneis.

Configure e verifique o túnel com o Codex

Para que o Codex oriente a configuração, dê a ele acesso à plataforma e ao ChatGPT pelo navegador e acesso ao terminal do host que consegue se conectar ao servidor MCP privado. Cole este prompt no Codex:

Ajude-me a configurar um túnel MCP seguro e privado entre meu servidor MCP interno e o ChatGPT e a verificar a conexão de ponta a ponta. Use o acesso ao navegador e ao computador, além de um terminal. Siga as instruções em https://developers.openai.com/api/docs/guides/secure-mcp-tunnels e https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md e consulte a interface atual e a ajuda da CLI a cada etapa.

Primeiro, identifique a organização da plataforma e o espaço de trabalho do ChatGPT que serão usados, a URL HTTP ou o comando stdio do servidor MCP e o host do cliente. Examine os túneis, as chaves e os plugins MCP personalizados do ChatGPT que já existirem e reutilize os recursos adequados. Confirme que o túnel está associado à organização e ao espaço de trabalho corretos. Confira também as permissões. Quem cria o túnel precisa de Tunnels Read + Manage. A chave de execução restrita e o operador do plugin precisam de Tunnels Read + Use.

Não exponha os valores dos segredos no chat, nos argumentos de comandos, nos logs, nas capturas de tela nem nos arquivos de configuração. Peça que eu forneça esses valores localmente por meio de uma entrada segura ou de uma referência a uma variável de ambiente. Instale a versão compatível do tunnel-client, execute `tunnel-client help quickstart` e configure o servidor. Em seguida, execute `tunnel-client doctor --profile <name> --explain`, inicie o cliente e verifique se ele está pronto e consultando a fila. Mantenha o cliente em execução para a descoberta e as chamadas de ferramentas.

Em ChatGPT Plugins, adicione um servidor MCP personalizado privado ou conclua a configuração de um existente. Use a opção Connection: Tunnel, selecione o mesmo túnel, configure a autenticação exigida e faça uma chamada de ferramenta segura que represente o uso pretendido. Informe o que você observou para confirmar cada etapa. Se algo impedir o avanço, informe o erro exato e a próxima ação. Só considere a configuração concluída depois que o ChatGPT fizer a chamada de ferramenta com sucesso.

Conecte-se pela API Responses

Informe o identificador do túnel em tunnel_id na definição da ferramenta MCP. Não informe o endpoint do túnel hospedado pela OpenAI em server_url. Use server_url apenas para um servidor MCP que a API Responses consiga acessar diretamente.

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"
      }
    ]
  }'

Segurança e rede

• O endereço do servidor MCP permanece privado e só é usado de dentro do ambiente que executa tunnel-client.
• O tunnel-client se autentica no plano de controle de túneis da OpenAI. Os produtos da OpenAI compatíveis usam o endpoint do túnel hospedado pela OpenAI.
• O acesso ao túnel segue o contexto existente da organização e do espaço de trabalho, sem criar uma rota pública de entrada separada.
• O tunnel-client atende a requisitos de redes empresariais, como proxies de saída, conjuntos personalizados de certificados de autoridades certificadoras, certificados de cliente para o plano de controle e mTLS no lado do MCP.

O que é registrado nos logs

O túnel MCP seguro separa o transporte pelo túnel dos logs que o produto gera no nível do aplicativo:

• O túnel não gera eventos de aplicativo na Plataforma de Conformidade do ChatGPT para a autenticação no plano de controle, o tráfego de long polling e de respostas ou as solicitações individuais de transporte pelo túnel.
• As alterações nos metadados do túnel aparecem nos logs de auditoria da Plataforma de API como tunnel.created, tunnel.updated e tunnel.deleted.
• Quando o ChatGPT acessa um aplicativo personalizado pelo túnel MCP seguro, o túnel serve apenas para o transporte. O aplicativo continua sujeito aos registros de conformidade habituais, incluindo logs de chamadas do aplicativo e logs do ciclo de vida da autenticação, como APP_AUTH_LOG quando o aplicativo é vinculado ou desvinculado.

Uso avançado: chamadas HTTP para destinos permitidos

O túnel MCP seguro também pode encaminhar chamadas HTTP de escopo delimitado de fluxos de agentes ou de API compatíveis para a rede de um cliente. O tunnel-client inclui um servidor MCP integrado, o Harpoon, que disponibiliza os destinos HTTP configurados por rótulo. Quem faz a chamada pode acessá-los pelo túnel, respeitando os limites de tamanho de solicitações e respostas.

Use esse recurso quando precisar acessar um conjunto pequeno de endpoints REST privados sem expô-los publicamente. O Harpoon não é um proxy de uso geral. Quem faz a chamada não pode escolher hosts arbitrários, e as solicitações se restringem aos destinos e métodos configurados pelo cliente.

Solução de problemas

• Mensagem “É necessário ter acesso aos túneis” nas configurações de túneis da plataforma: as permissões de túnel são definidas no nível da organização e não no nível do projeto. Selecione a organização desejada na plataforma. Peça ao proprietário da organização ou a um administrador de RBAC que adicione você a uma função ou grupo com a permissão Leitura para visualizar túneis ou com Leitura + Gerenciamento para criá-los, editá-los ou excluí-los. Se não houver uma função adequada, o responsável poderá criar uma, atribuí-la a um grupo e adicionar você ao grupo. Você também precisa da permissão Uso para executar tunnel-client ou selecionar um túnel nas configurações do conector. A propagação de uma nova atribuição de função pode levar até 30 minutos.
• O túnel não aparece no ChatGPT: verifique se o túnel está associado ao espaço de trabalho desejado do ChatGPT, e não apenas a uma organização da plataforma. Depois, confira se o operador do conector tem a permissão Uso de túneis. Se não for possível vincular automaticamente o espaço de trabalho de uma conta empresarial, peça à equipe da OpenAI responsável pela sua conta que analise uma exceção para fazer a associação manualmente.
• A descoberta do conector ou as chamadas de ferramentas falham: confirme que tunnel-client run ... continua em execução e execute tunnel-client doctor --profile <name> --explain novamente.
• Você consegue inspecionar um túnel, mas não editá-lo: o operador provavelmente tem a permissão Leitura de túneis, mas não a de Gerenciamento.
• O tunnel-client disponibiliza /healthz, /readyz, /metrics e uma interface de administração local em /ui.
• Por padrão, a interface de administração só aceita conexões de loopback. Habilite o acesso remoto apenas quando precisar dar acesso à interface pela rede de um operador.
• Use esses recursos para confirmar que o cliente está funcionando normalmente, está pronto e está consultando a fila antes de testar pelo ChatGPT, pelo Codex ou por um fluxo de API.
• Se o cliente estiver desconectado, as solicitações pelo túnel falharão até que tunnel-client se reconecte.
• O registro do tráfego HTTP bruto fica desativado por padrão, e os dados sensíveis são ocultados nas exportações para suporte.

OAuth

• A descoberta OAuth pode ocorrer pelo túnel, permitindo que o servidor MCP permaneça privado.
• O túnel preserva os metadados do servidor de autorização de origem necessários para os fluxos OAuth que usam o navegador.
• O túnel não encaminha automaticamente as conexões ao próprio servidor de autorização. Se esse servidor estiver inacessível tanto pela internet pública quanto pelo host do tunnel-client, o fluxo OAuth poderá falhar mesmo que o servidor MCP esteja acessível.

Onde configurar o túnel

• Gerencie os endpoints de túneis MCP hospedados pela OpenAI nas configurações de túneis da plataforma.
• Use um túnel ao adicionar um servidor MCP personalizado em Plug-ins do ChatGPT.
• Para fluxos do Codex ou de API, use o destino MCP que a interface do produto compatível disponibiliza por meio do túnel.

Próximas etapas

• Crie ou gerencie o túnel nas configurações de túneis da plataforma.
• Valide o perfil do tunnel-client com tunnel-client doctor --profile <profile> --explain.
• Conecte-se ao túnel por Plug-ins do ChatGPT ou pela interface compatível da OpenAI que você está usando.