Túnel MCP seguro

O Túnel MCP seguro permite conectar servidores MCP privados a produtos compatíveis da OpenAI sem abrir portas de entrada no firewall nem expor esses servidores à internet pública. Execute tunnel-client dentro da rede que já tem acesso ao seu servidor MCP; ele abre uma conexão HTTPS de saída com a OpenAI, busca tarefas MCP na fila, encaminha as requisições localmente e retorna as respostas pelo mesmo túnel.

O que é um túnel MCP?

Um túnel MCP é uma conexão somente de saída de um host dentro da sua rede para um endpoint MCP hospedado pela OpenAI. Use-o quando seu servidor MCP for privado, estiver em infraestrutura local ou atrás de um firewall, mas o ChatGPT, o Codex, a API Responses ou outra interface compatível da OpenAI ainda precisar fazer chamadas a ele.

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

Use o Túnel MCP seguro quando

• Seu servidor MCP for executado em uma rede privada, em infraestrutura local, na máquina de um desenvolvedor ou protegido por controles de acesso existentes.
• Você quiser que o ChatGPT, o Codex, a API Responses ou outra interface compatível da OpenAI use esse servidor sem tornar o servidor MCP público.
• Sua rede permitir que o host que executa tunnel-client faça requisiçõ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.
• Comece pelo guia de servidores MCP para conhecer os conceitos gerais de 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 dentro da rede que tem acesso ao seu 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 requisições MCP ao endpoint de túnel hospedado pela OpenAI.
5. O tunnel-client usa consultas de longa duração para buscar tarefas na fila, encaminha cada requisição JSON-RPC ao servidor MCP privado e envia a resposta de volta pelo túnel.

O servidor MCP privado não precisa aceitar conexões públicas de entrada. O endpoint hospedado pela OpenAI oferece aos produtos compatíveis um caminho normal para requisições MCP, enquanto as conexões de rede continuam sendo iniciadas dentro dos limites do seu ambiente. 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 uso pelo tunnel-client em tempo de execução.
• Um servidor MCP que tunnel-client possa acessar por stdio ou HTTP de dentro da sua rede.

Permissões e acesso

As permissões de túneis da Plataforma e o acesso ao modo de desenvolvedor do ChatGPT são independentes:

• Para criar ou editar um túnel, são necessárias as permissões Ler + Gerenciar em Túneis.
• Para executar tunnel-client ou selecionar o túnel ao criar um aplicativo, são necessárias as permissões Ler + Usar em Túneis.
• As permissões de túneis se aplicam a uma organização da Plataforma. Um proprietário da organização da Plataforma ou administrador de RBAC atribui a função de acesso a túneis.
• O modo de desenvolvedor do ChatGPT é uma permissão independente do workspace. Nos planos Enterprise/Edu, um administrador do workspace concede acesso ao modo de desenvolvedor; em seguida, o usuário o ativa em Configurações → Segurança e login. Consulte o artigo da Central de Ajuda sobre o modo de desenvolvedor para conhecer a política específica de cada plano.

Solicite acesso ao modo de desenvolvedor ao administrador do workspace do ChatGPT que você pretende usar e permissões de túneis ao proprietário ou administrador de RBAC da organização da Plataforma correspondente.

Associe túneis às organizações e aos workspaces corretos

Um túnel pode ser associado a uma ou mais organizações da Plataforma ou workspaces do ChatGPT. Use essas associações para definir todos os contextos da OpenAI que devem ter permissão para encontrar ou usar o túnel.

• Inclua a organização da Plataforma que é proprietária do túnel ou o gerencia.
• Inclua o workspace do ChatGPT que deve listar o túnel durante a criação de aplicativos.
• Inclua outra organização da Plataforma quando o Codex, a API Responses ou outro produto compatível for fazer chamadas ao servidor MCP privado a partir dessa organização.
• Use o mesmo tunnel_id para tunnel-client; adicionar organizações ou workspaces não cria um segundo túnel nem altera o endpoint do servidor MCP privado.

Para contas pessoais, use a organização pessoal da Plataforma que pertence à conta. Para testes com o ChatGPT e o Codex, associe o túnel ao workspace do ChatGPT desejado 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 workspace Enterprise/Edu.

Se a organização da Plataforma e o workspace do ChatGPT já estiverem vinculados, você poderá adicionar a organização ou o workspace 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 workspace do ChatGPT correspondente, entre em contato com a equipe da OpenAI responsável pela sua conta para solicitar uma exceção manual de associação, sujeita a revisão, para o mapeamento da conta empresarial que deve usar o túnel.

Requisitos de rede

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

Configure o tunnel-client

Abra as configurações de túneis da Plataforma e use o link de download disponível lá ou a versão pública mais recente do tunnel-client em openai/tunnel-client. Mantenha seu guia operacional apontando para a URL da versão mais recente, em vez de fixar a URL de uma versão específica.

Se você já tem um binário, comece com tunnel-client help quickstart. Para um perfil stdio local com nome definido, use:

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

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

Escolha onde executar o tunnel-client

Execute tunnel-client dentro do mesmo perímetro de confiança que já permite acessar o servidor MCP privado. Alguns padrões comuns de implantação são:

• Sidecar no Kubernetes: execute tunnel-client junto ao servidor MCP no mesmo Pod e conecte-se por localhost.
• Implantação dedicada no Kubernetes: execute tunnel-client separadamente quando o servidor MCP já estiver acessível por meio de um Service privado.
• VM ou serviço systemd: execute tunnel-client em um host que possa acessar o servidor MCP por uma rede privada.

Conecte-se pelo ChatGPT

Acesse Plug-ins do ChatGPT, selecione o botão de mais para criar um aplicativo no modo de desenvolvedor e escolha Túnel em Conexão. Selecione um túnel disponível quando o ChatGPT o listar ou cole um tunnel_id válido, se você já tiver um.

Se o túnel não aparecer no ChatGPT, verifique se ele está associado ao workspace de destino do ChatGPT, e não apenas a uma organização da Plataforma, e se quem criou o aplicativo tem as permissões Ler + Usar para Túneis.

Conecte-se pela API Responses

Passe o identificador do túnel como tunnel_id na definição da ferramenta MCP. Não passe o endpoint do túnel hospedado pela OpenAI como server_url; use server_url apenas para um servidor MCP que a API Responses possa 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 redes

• O endereço do servidor MCP permanece privado e é usado apenas de dentro do ambiente em que tunnel-client é executado.
• tunnel-client se autentica no plano de controle de túneis da OpenAI; os produtos 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 workspace, em vez de introduzir um caminho separado de entrada pública.
• tunnel-client oferece suporte a requisitos de redes corporativas, como proxies de saída, pacotes personalizados de certificados de CA, certificados de cliente para o plano de controle e mTLS no lado do MCP.

Limites do registro de logs

O Túnel MCP seguro separa o transporte pelo túnel do registro de logs do produto no nível do aplicativo:

• O caminho do túnel não emite a autenticação do plano de controle, o tráfego de long polling e respostas nem as solicitações individuais de transporte pelo túnel como eventos de aplicativo na Plataforma de conformidade do ChatGPT.
• As alterações nos metadados do túnel são disponibilizadas na interface de 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 continua sendo apenas o caminho de transporte. O registro normal de logs de conformidade no nível do aplicativo continua se aplicando ao caminho do aplicativo, incluindo logs de invocação e do ciclo de vida de autenticação, como APP_AUTH_LOG quando o aplicativo é vinculado ou desvinculado.

Avançado: chamadas HTTP incluídas na lista de permissões

O Túnel MCP seguro também pode oferecer suporte a chamadas HTTP de escopo restrito feitas por fluxos compatíveis de agentes ou de API para dentro da rede de um cliente. tunnel-client inclui um servidor MCP integrado, o Harpoon, que expõe destinos HTTP configurados por rótulo e permite que os chamadores os invoquem pelo túnel, com limites definidos para solicitações e respostas.

Use esse recurso quando precisar acessar um pequeno conjunto de endpoints REST privados sem expô-los publicamente. O Harpoon não é um proxy de uso geral: os chamadores não podem escolher hosts arbitrários, e as solicitações ficam restritas aos destinos e métodos configurados pelo cliente.

Solução de problemas

• “Acesso a Túneis necessário” nas configurações de túneis da Plataforma: as permissões de túneis se aplicam à organização, não ao projeto. Selecione a organização desejada na Plataforma e peça a um proprietário da organização ou administrador de RBAC que adicione você a uma função ou grupo com a permissão Ler para visualizar túneis, ou Ler + Gerenciar para criá-los, editá-los ou excluí-los. Se não houver uma função adequada, essa pessoa poderá criar uma, atribuí-la a um grupo e adicionar você a esse grupo. Você também precisa da permissão Usar para executar tunnel-client ou selecionar um túnel nas configurações do conector. Aguarde até 30 minutos para que uma nova atribuição de função se propague.
• Túnel não aparece no ChatGPT: verifique se o túnel inclui o workspace de destino do ChatGPT, e não apenas uma organização da Plataforma; depois, verifique se o operador do conector tem a permissão Usar para Túneis. Se não for possível vincular o workspace automaticamente em uma conta corporativa, entre em contato com a equipe da OpenAI responsável pela sua conta para solicitar uma exceção revisada de associação manual.
• Falha na descoberta do conector ou nas chamadas de ferramentas: confirme se 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 Ler para Túneis, mas não a permissão Gerenciar para Túneis.
• tunnel-client expõe /healthz, /readyz, /metrics e uma interface de administração local em /ui.
• Por padrão, a interface de administração só fica acessível via loopback. Exponha-a remotamente apenas quando houver uma necessidade deliberada de acesso pela rede dos operadores.
• Use essas interfaces para confirmar se o cliente está funcionando corretamente, pronto e realizando polling antes de testar pelo ChatGPT, pelo Codex ou por um fluxo de API.
• Se o cliente não estiver conectado, as solicitações pelo túnel falharão até que tunnel-client se reconecte.
• O registro de logs HTTP brutos vem desativado por padrão, e as exportações para suporte têm os dados sensíveis ocultados.

OAuth

• A descoberta OAuth pode passar pelo túnel, permitindo que o próprio 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 interagem com o navegador.
• O próprio servidor de autorização não é automaticamente acessado pelo túnel. Se ele estiver inacessível tanto pela internet pública quanto pelo host do tunnel-client, o fluxo OAuth ainda poderá falhar, mesmo que o servidor MCP esteja acessível.

Onde configurar

• Gerencie os endpoints de túneis MCP hospedados pela OpenAI nas configurações de túneis da Plataforma.
• Use um túnel ao criar um aplicativo no modo de desenvolvedor em Plug-ins do ChatGPT.
• Para fluxos do Codex ou da API, use o destino MCP acessível pelo túnel disponibilizado pela interface do produto compatível.

Próximos passos

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