Tunnel MCP sécurisé

Le tunnel MCP sécurisé vous permet de connecter des serveurs MCP privés aux produits OpenAI compatibles sans ouvrir de ports entrants sur votre pare-feu ni exposer ces serveurs sur Internet. Exécutez tunnel-client sur le réseau qui a déjà accès à votre serveur MCP. Le client établit une connexion HTTPS sortante vers OpenAI, récupère les requêtes MCP en attente, les transmet localement et renvoie les réponses par le même tunnel.

Qu’est-ce qu’un tunnel MCP ?

Un tunnel MCP est une connexion exclusivement sortante qui relie un hôte de votre réseau à un point de terminaison MCP hébergé par OpenAI. Utilisez-le lorsque ChatGPT, Codex, l’API Responses ou une autre interface OpenAI compatible doit appeler un serveur MCP privé, hébergé sur site ou protégé par un pare-feu.

Avec le tunnel MCP sécurisé, le serveur MCP reste privé et les produits OpenAI compatibles peuvent lui envoyer des requêtes MCP comme à l’ordinaire. tunnel-client interroge OpenAI pour récupérer les requêtes MCP en attente, les transmet localement et renvoie les réponses par le même tunnel.

Quand utiliser un tunnel MCP sécurisé ?

• Votre serveur MCP s’exécute sur un réseau privé, sur site, sur une machine de développement ou derrière des contrôles d’accès existants.
• Vous souhaitez que ChatGPT, Codex, l’API Responses ou une autre interface OpenAI compatible utilise ce serveur MCP sans le rendre public.
• Votre réseau permet à l’hôte qui exécute tunnel-client d’envoyer des requêtes HTTPS sortantes à api.openai.com:443 par défaut, ou à mtls.api.openai.com:443 si mTLS est configuré sur le plan de contrôle, et d’accéder au serveur MCP privé.
• Pour découvrir les principes généraux de MCP, commencez par le guide des serveurs MCP.

Fonctionnement

1. Créez ou gérez un point de terminaison de tunnel MCP hébergé par OpenAI dans les paramètres des tunnels de la Plateforme API.
2. Exécutez tunnel-client sur le réseau qui a accès à votre serveur MCP privé.
3. Configurez tunnel-client avec l’identité du tunnel et l’adresse du serveur MCP privé.
4. Les produits OpenAI envoient les requêtes MCP au point de terminaison du tunnel hébergé par OpenAI.
5. tunnel-client récupère les requêtes en attente par interrogation longue, transmet chaque requête JSON-RPC au serveur MCP privé et renvoie la réponse par le tunnel.

Le serveur MCP privé n’a pas besoin d’être à l’écoute sur une adresse publique. Les produits compatibles envoient leurs requêtes MCP comme à l’ordinaire au point de terminaison hébergé par OpenAI, tandis que la connexion réseau est établie depuis votre environnement. Lorsqu’un connecteur demande des résultats en streaming, le tunnel peut transmettre les événements intermédiaires envoyés par le serveur.

Avant de commencer

Vous aurez besoin des éléments suivants :

• Un tunnel_id obtenu dans les paramètres des tunnels de la Plateforme API.
• Une clé API pour l’exécution de tunnel-client.
• Un serveur MCP auquel tunnel-client peut accéder via stdio ou HTTP depuis votre réseau.

Autorisations et accès

Les autorisations relatives aux tunnels de la Plateforme API et l’accès aux serveurs MCP personnalisés dans ChatGPT se gèrent séparément :

• Pour créer ou modifier un tunnel, vous devez disposer des autorisations Lecture + Gestion sur les tunnels.
• Pour exécuter tunnel-client ou sélectionner le tunnel lors de la création d’une application, vous devez disposer des autorisations Lecture + Utilisation sur les tunnels.
• Les autorisations relatives aux tunnels s’appliquent à une organisation de la Plateforme API. Un propriétaire de l’organisation ou un administrateur RBAC attribue le rôle donnant accès aux tunnels.
• L’ajout et l’utilisation de serveurs MCP personnalisés dans ChatGPT restent soumis aux autorisations et aux restrictions de sécurité de l’espace de travail. Consultez la section Ajouter un serveur MCP personnalisé.

Demandez à l’administrateur de l’espace de travail ChatGPT concerné l’autorisation d’ajouter et d’utiliser des serveurs MCP personnalisés. Pour les autorisations relatives aux tunnels, adressez-vous au propriétaire de l’organisation concernée sur la Plateforme API ou à son administrateur RBAC.

Associez les tunnels aux organisations et espaces de travail concernés

Vous pouvez associer un tunnel à une ou plusieurs organisations de la Plateforme API ou à un ou plusieurs espaces de travail ChatGPT. Ces associations déterminent dans quels contextes OpenAI le tunnel peut être découvert ou utilisé.

• Incluez l’organisation de la Plateforme API qui possède ou gère le tunnel.
• Incluez l’espace de travail ChatGPT dans lequel le tunnel doit apparaître lors de la création d’applications.
• Incluez toute autre organisation de la Plateforme API depuis laquelle Codex, l’API Responses ou un autre produit compatible appellera le serveur MCP privé.
• Utilisez le même tunnel_id pour tunnel-client. L’ajout d’organisations ou d’espaces de travail ne crée pas de second tunnel et ne modifie pas le point de terminaison du serveur MCP privé.

Pour un compte personnel, utilisez l’organisation personnelle qui lui est rattachée sur la Plateforme API. Pour effectuer des tests avec ChatGPT et Codex, associez le tunnel à l’espace de travail ChatGPT concerné et à l’organisation de la Plateforme API qu’utilisera Codex. Un tunnel associé uniquement à une organisation personnelle de la Plateforme API n’apparaît pas automatiquement dans un espace de travail Enterprise ou Edu.

Si l’organisation de la Plateforme API et l’espace de travail ChatGPT sont déjà liés, vous pouvez ajouter l’organisation ou l’espace de travail manquant dans les paramètres des tunnels de la Plateforme API. Si votre configuration d’entreprise ne peut pas être vérifiée automatiquement, par exemple si aucun espace de travail ChatGPT ne correspond à l’organisation de la Plateforme API, demandez à votre équipe de compte OpenAI d’examiner le rattachement du compte d’entreprise qui doit utiliser le tunnel et d’autoriser une association manuelle par dérogation.

Prérequis réseau

tunnel-client n’a pas besoin d’accepter de connexions entrantes depuis Internet. Il doit pouvoir se connecter à OpenAI en HTTPS et accéder localement au serveur MCP privé :

Limites

Le tunnel MCP sécurisé applique les limites par défaut suivantes à la création de tunnels et au trafic MCP des connecteurs :

Ces limites protègent le service et ne garantissent ni débit ni latence. La conservation des entrées de la file d’attente à des fins de nettoyage ne prolonge pas le délai de 120 secondes. Pour demander une augmentation du nombre de tunnels ou du trafic autorisé, contactez l’assistance OpenAI.

Configurez tunnel-client

Ouvrez les paramètres des tunnels de la Plateforme API, puis utilisez le lien de téléchargement qui s’y trouve ou téléchargez la dernière version publique de tunnel-client depuis openai/tunnel-client. Dans votre procédure d’exploitation, utilisez l’URL qui pointe toujours vers la dernière version plutôt qu’une URL propre à une version donnée.

Si vous disposez déjà du binaire, commencez par tunnel-client help quickstart. Pour configurer un profil stdio local nommé, utilisez les commandes suivantes :

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

Pour un serveur MCP accessible en HTTP, utilisez --mcp-server-url https://mcp.internal.example.com/mcp à la place de --mcp-command.

Veillez à ce que tunnel-client run ... fonctionne correctement pendant la création ou le test de l’application. La découverte de l’application et les appels aux outils MCP nécessitent que le client soit en cours d’exécution.

Choisissez où exécuter tunnel-client

Exécutez tunnel-client dans le périmètre de confiance qui a déjà accès au serveur MCP privé. Voici les modes de déploiement courants :

• Sidecar Kubernetes : exécutez tunnel-client dans le même Pod que le serveur MCP et connectez-les via localhost.
• Déploiement Kubernetes dédié : exécutez tunnel-client séparément lorsque le serveur MCP est déjà accessible via un Service privé.
• Machine virtuelle ou service systemd : exécutez tunnel-client sur un hôte qui peut accéder au serveur MCP via un réseau privé.

Connectez-vous depuis ChatGPT

Ouvrez les plugins ChatGPT, sélectionnez le bouton plus, puis Ajouter un serveur MCP personnalisé. Choisissez Tunnel sous Connexion. Sélectionnez un tunnel disponible dans la liste affichée par ChatGPT ou collez un tunnel_id valide si vous en avez déjà un. Configurez l’authentification, lisez l’avertissement sur les risques, puis sélectionnez Je comprends et je souhaite continuer et Créer en tant que plugin.

Si le tunnel n’apparaît pas dans ChatGPT, vérifiez qu’il est bien associé à l’espace de travail ChatGPT concerné et pas uniquement à une organisation de la Plateforme API. Vérifiez également que la personne qui crée l’application dispose des autorisations Lecture + Utilisation sur les tunnels.

Configurez et vérifiez le tunnel avec Codex

Pour que Codex vous guide dans la configuration, donnez-lui accès à la Plateforme API et à ChatGPT via le navigateur, ainsi qu’au terminal de l’hôte qui a accès à votre serveur MCP privé. Collez ce prompt dans Codex :

Aidez-moi à configurer un tunnel MCP sécurisé privé entre mon serveur MCP interne et ChatGPT, puis à vérifier son fonctionnement de bout en bout. Utilisez le navigateur, l’ordinateur et un terminal. Suivez les instructions de https://developers.openai.com/api/docs/guides/secure-mcp-tunnels et de https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md en vérifiant à chaque étape les options de l’interface actuelle et l’aide de la CLI.

Identifiez d’abord l’organisation de la Plateforme API et l’espace de travail ChatGPT concernés, l’URL HTTP ou la commande stdio du serveur MCP, ainsi que l’hôte sur lequel le client doit s’exécuter. Examinez les tunnels, les clés et les plugins MCP personnalisés déjà présents dans leurs environnements respectifs et réutilisez ceux qui conviennent. Vérifiez que le tunnel est associé à l’organisation et à l’espace de travail prévus. Vérifiez aussi les autorisations. Les personnes qui créent le tunnel doivent disposer des autorisations Tunnels Read + Manage. La clé d’exécution à autorisations restreintes et l’opérateur du plugin doivent disposer des autorisations Tunnels Read + Use.

Ne faites apparaître la valeur des secrets ni dans la conversation, ni dans les arguments de commande, ni dans les journaux, ni dans les captures d’écran, ni dans les fichiers de configuration. Demandez-moi de saisir les secrets localement dans un champ sécurisé ou de les fournir par référence à une variable d’environnement. Installez la version prise en charge de tunnel-client. Exécutez `tunnel-client help quickstart`, configurez le serveur, puis exécutez `tunnel-client doctor --profile <name> --explain`. Démarrez le client et vérifiez qu’il est prêt et qu’il interroge bien le service. Laissez-le en cours d’exécution pour permettre la découverte et les appels aux outils.

Dans ChatGPT Plugins, ajoutez un serveur MCP personnalisé privé ou terminez la configuration du serveur existant. Utilisez le réglage « Connection: Tunnel », sélectionnez le même tunnel, configurez l’authentification requise et effectuez un appel d’outil représentatif et sans risque. Pour chaque vérification, indiquez les éléments observés qui attestent du résultat. En cas de blocage, indiquez l’erreur exacte et la prochaine action à effectuer. N’annoncez la fin de la configuration qu’après la réussite de l’appel d’outil depuis ChatGPT.

Connectez-vous depuis l’API Responses

Transmettez l’identifiant du tunnel dans le champ tunnel_id de la définition de l’outil MCP. Ne transmettez pas le point de terminaison du tunnel hébergé par OpenAI dans server_url. Utilisez server_url uniquement pour un serveur MCP auquel l’API Responses peut accéder directement.

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

Sécurité et réseau

• L’adresse du serveur MCP reste privée. Elle est utilisée uniquement depuis l’environnement dans lequel s’exécute tunnel-client.
• tunnel-client s’authentifie auprès du plan de contrôle des tunnels OpenAI. Les produits OpenAI compatibles utilisent le point de terminaison du tunnel hébergé par OpenAI.
• L’accès au tunnel dépend de l’organisation et de l’espace de travail existants, sans nécessiter de point d’entrée public distinct.
• tunnel-client prend en charge les configurations réseau d’entreprise, notamment les proxys sortants, les ensembles de certificats d’autorités de certification personnalisés, les certificats clients du plan de contrôle et mTLS côté MCP.

Périmètre de journalisation

Le tunnel MCP sécurisé distingue le transport par tunnel de la journalisation des produits au niveau de l’application :

• Le tunnel ne génère pas d’événements applicatifs dans la plateforme de conformité ChatGPT pour l’authentification auprès du plan de contrôle, les interrogations longues et les réponses, ou les requêtes de transport individuelles.
• Les modifications des métadonnées du tunnel figurent dans les journaux d’audit de la Plateforme API sous forme d’événements tunnel.created, tunnel.updated et tunnel.deleted.
• Lorsque ChatGPT accède à une application personnalisée via un tunnel MCP sécurisé, le tunnel assure uniquement le transport. Les règles habituelles de journalisation à des fins de conformité continuent de s’appliquer côté application. Elles couvrent notamment les appels à l’application et les événements du cycle d’authentification, comme APP_AUTH_LOG lors de l’association ou de la dissociation de l’application.

Configuration avancée : appels HTTP sur liste d’autorisation

Le tunnel MCP sécurisé peut aussi acheminer des appels HTTP ciblés vers le réseau d’un client depuis des workflows d’agents ou d’API compatibles. tunnel-client intègre un serveur MCP, Harpoon, qui expose les cibles HTTP configurées sous des libellés. Les appelants peuvent les invoquer via le tunnel dans les limites prévues pour les requêtes et les réponses.

Utilisez cette fonctionnalité pour accéder à un petit nombre de points de terminaison REST privés sans les exposer sur Internet. Harpoon n’est pas un proxy généraliste : les appelants ne peuvent pas choisir librement les hôtes et les requêtes se limitent aux cibles et aux méthodes que vous avez configurées.

Dépannage

• « Accès aux tunnels requis » dans les paramètres des tunnels de la Plateforme API : les autorisations relatives aux tunnels se définissent au niveau de l’organisation et non du projet. Sélectionnez l’organisation concernée sur la Plateforme API, puis demandez à un propriétaire de l’organisation ou à un administrateur RBAC de vous attribuer un rôle ou de vous ajouter à un groupe disposant de l’autorisation Lecture pour consulter les tunnels, ou des autorisations Lecture + Gestion pour les créer, les modifier ou les supprimer. Si aucun rôle ne convient, cette personne peut en créer un, l’attribuer à un groupe et vous y ajouter. L’autorisation Utilisation est également nécessaire pour exécuter tunnel-client ou sélectionner un tunnel dans les paramètres du connecteur. La prise en compte d’une nouvelle attribution de rôle peut prendre jusqu’à 30 minutes.
• Le tunnel n’apparaît pas dans ChatGPT : vérifiez que le tunnel est associé à l’espace de travail ChatGPT concerné et pas uniquement à une organisation de la Plateforme API. Vérifiez ensuite que l’opérateur du connecteur dispose de l’autorisation Utilisation sur les tunnels. Si l’espace de travail ne peut pas être lié automatiquement à un compte d’entreprise, demandez à votre équipe de compte OpenAI d’examiner la demande et d’autoriser une association manuelle par dérogation.
• La découverte du connecteur ou les appels aux outils échouent : vérifiez que tunnel-client run ... est toujours en cours d’exécution, puis relancez tunnel-client doctor --profile <name> --explain.
• Vous pouvez consulter un tunnel mais pas le modifier : l’opérateur dispose probablement de l’autorisation Lecture sur les tunnels, mais pas de l’autorisation Gestion.
• tunnel-client expose /healthz, /readyz, /metrics et une interface d’administration locale sur /ui.
• Par défaut, l’interface d’administration n’est accessible que sur l’interface de bouclage. N’autorisez l’accès à distance que si vous souhaitez la rendre accessible depuis le réseau des opérateurs.
• Utilisez ces interfaces pour vérifier que le client fonctionne correctement, qu’il est prêt et qu’il interroge le service avant d’effectuer des tests depuis ChatGPT, Codex ou via une API.
• Si le client est déconnecté, les requêtes passant par le tunnel échouent jusqu’à ce que tunnel-client se reconnecte.
• La journalisation du trafic HTTP brut est désactivée par défaut et les données sensibles sont masquées dans les exports destinés à l’assistance.

OAuth

• La découverte OAuth peut passer par le tunnel, ce qui permet au serveur MCP de rester privé.
• Le tunnel préserve les métadonnées du serveur d’autorisation en amont nécessaires aux flux OAuth qui passent par le navigateur.
• Le serveur d’autorisation lui-même n’est pas automatiquement accessible via le tunnel. S’il est inaccessible à la fois depuis Internet et depuis l’hôte de tunnel-client, le flux OAuth peut échouer même si le serveur MCP est accessible.

Où configurer le tunnel ?

• Gérez les points de terminaison des tunnels MCP hébergés par OpenAI dans les paramètres des tunnels de la Plateforme API.
• Utilisez un tunnel lorsque vous ajoutez un serveur MCP personnalisé dans les plugins ChatGPT.
• Pour les workflows Codex ou API, utilisez la cible MCP accessible via le tunnel que propose l’interface du produit compatible.

Étapes suivantes

• Créez ou gérez le tunnel dans les paramètres des tunnels de la Plateforme API.
• Validez votre profil tunnel-client avec tunnel-client doctor --profile <profile> --explain.
• Connectez le tunnel depuis les plugins ChatGPT ou l’interface OpenAI compatible que vous utilisez.