--- title: Référence des tunnels MCP url: https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/reference description: Champs de configuration du proxy, l'API REST Tunnels, exigences relatives aux certificats et le composant de configuration. --- Les « MCP tunnels » (tunnels MCP) sont en « research preview » (aperçu de recherche). [Demandez l'accès](https://claude.com/form/mcp-tunnels) pour les essayer. ## Configuration du proxy Le [proxy](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) lit sa configuration depuis `/etc/mcp-gateway/config.yaml` (Compose) ou depuis la ConfigMap rendue (Helm, renseignée à partir de `gateway.config.*`). | Champ | Description | Valeur par défaut | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `listen_addr` | Adresse et port sur lesquels écouter. | Obligatoire | | `log_level` | Verbosité de la journalisation : `debug`, `info`, `warn` ou `error`. | `info` | | `shutdown_timeout` | Durée d'attente des requêtes en cours lors d'un arrêt progressif. | `30s` | | `tunnel_domain` | Domaine de base attribué au tunnel. Lorsqu'il est défini, la recherche de route supprime ce suffixe des noms d'hôte entrants afin que les clés de `routes` puissent être de simples sous-domaines (`wiki`). Lorsqu'il est vide, les clés de `routes` doivent être des noms d'hôte complets exacts. | Obligatoire lorsque les clés de `routes` sont de simples sous-domaines | | `tls.cert_file` | Chemin vers le certificat TLS du serveur. | Obligatoire | | `tls.key_file` | Chemin vers la clé privée TLS du serveur. | Obligatoire | | `routes` | Correspondance entre sous-domaine ou nom d'hôte complet et URL en amont. Voir [Correspondance des routes](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/reference#route-matching). | Obligatoire | | `upstream.allowed_ips` | Plages CIDR IPv4 ou adresses uniques auxquelles le proxy est autorisé à se connecter. Mutuellement exclusif avec `disable_ip_validation`. | Plages privées RFC1918 | | `upstream.disable_ip_validation` | Désactive entièrement la validation des IP en amont. Mutuellement exclusif avec `allowed_ips`. | `false` | | `upstream.tls.ca_file` | Bundle d'autorités de certification pour la validation du TLS en amont. | Aucune | | `upstream.tls.include_system_cas` | Faire également confiance au bundle d'autorités de certification du système pour le TLS en amont. | `false` | Pour les routes en amont en `https://`, définissez au moins l'un des champs `upstream.tls.ca_file` ou `upstream.tls.include_system_cas` ; sinon, le proxy ne dispose d'aucune ancre de confiance pour le certificat en amont. ### Correspondance des routes `routes` est une table de chaînes plate (`map[string]string`), et non une liste. Le proxy recherche d'abord le nom d'hôte entrant par correspondance exacte, puis en supprimant le suffixe `tunnel_domain` et en faisant correspondre le sous-domaine restant. La correspondance ne prend en compte que le nom d'hôte ; le chemin de la requête et la chaîne de requête sont transmis inchangés au [serveur MCP en amont](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components). Chaque valeur en amont doit être exactement de la forme `scheme://host:port`. Le port est obligatoire. L'inclusion d'un chemin est rejetée au chargement de la configuration avec l'erreur `invalid upstream (must be scheme://host:port)`. ## API Tunnels L'API REST Tunnels se trouve à l'adresse `/v1/tunnels` et permet de créer, lister et archiver des tunnels, d'enregistrer des certificats d'autorité de certification, ainsi que de révéler ou de renouveler le jeton du tunnel. Consultez la [référence de l'API Tunnels](https://platform.claude.com/docs/fr/api/beta/tunnels/list) pour tous les points de terminaison, les schémas de requête et de réponse, ainsi que des exemples. L'ancienne surface de l'Admin API à l'adresse `/v1/organizations/tunnels` (en-tête bêta `mcp-tunnels-2026-05-19`, portée `org:manage_tunnels`) continue de fonctionner pendant une période de migration et reste documentée dans la [référence de l'Admin API](https://platform.claude.com/docs/fr/api/beta/organization/mcp_tunnels) avec un avis de dépréciation. Pour migrer, mettez à jour le chemin vers `/v1/tunnels`, l'en-tête bêta vers `mcp-tunnels-2026-06-22`, et la portée de votre jeton WIF vers `workspace:manage_tunnels`. Tous les points de terminaison des tunnels MCP nécessitent un jeton bearer doté de la portée `workspace:manage_tunnels`, obtenu via la [Workload Identity Federation](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation) (fédération d'identité de charge de travail). Les clés API d'administration ne sont pas acceptées. En-têtes obligatoires pour chaque requête : | En-tête | Valeur | | ------------------- | ------------------------------------------- | | `Authorization` | `Bearer ` (le jeton échangé via WIF) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Exigences relatives aux certificats Le [composant de configuration](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) génère automatiquement des certificats conformes. Ces exigences ne s'appliquent que si vous émettez des certificats via votre propre PKI. ### Certificat d'autorité de certification Téléversez-le avec `POST /v1/tunnels/{tunnel_id}/certificates`. Un tunnel peut contenir jusqu'à deux certificats d'autorité de certification actifs à la fois, ce qui permet une rotation sans interruption de service. * Encodé en PEM, certificat unique, jusqu'à 8 ko. * Extension `BasicConstraints` présente avec `CA:TRUE`, marquée comme critique. * Extension `SubjectKeyIdentifier` présente. * `KeyUsage` inclut `keyCertSign`. * Dans sa période de validité. * RSA 2048 bits ou plus, ou ECDSA P-256 ou plus, avec une signature SHA-256 ou plus forte. ### Certificat serveur Présenté par le proxy lors du [TLS interne](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components). * Signé directement par une autorité de certification enregistrée (sans intermédiaires). * Extension `AuthorityKeyIdentifier` présente et correspondant au `SubjectKeyIdentifier` de l'autorité de certification. * Le Subject Alternative Name inclut un nom DNS correspondant à `.`. Un joker `*.` couvre toutes les routes. * Si l'extension `ExtendedKeyUsage` est présente, elle inclut `serverAuth`. * Dans sa période de validité. * RSA 2048 bits ou plus, ou ECDSA P-256 ou plus, avec une signature SHA-256 ou plus forte. Le composant de configuration génère une autorité de certification ECDSA P-256 d'une validité de cinq ans et un certificat serveur RSA 4096 bits avec un SAN joker et une validité de 90 jours. ## Composant de configuration Le composant de configuration est fourni dans l'image `mcp-proxy` sous la forme du binaire `setup`. Exécutez-le avec `docker compose run --rm setup ` (Compose) ou appuyez-vous sur les hooks et CronJobs du chart (Helm). ### `setup init` S'attache à un tunnel existant (ou en crée un lorsqu'aucun ID de tunnel n'est fourni), puis génère une autorité de certification et un certificat serveur, enregistre l'autorité de certification, récupère le jeton du tunnel et écrit toutes les sorties vers la destination. | Option | Description | Valeur par défaut | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `--api-url` | URL de base de l'API Claude. Également lue depuis `API_URL`. | Obligatoire | | `--tunnel-id` | ID du tunnel auquel s'attacher (`tnl_...`). Également lu depuis `TUNNEL_ID`. Lorsqu'il est omis, un nouveau tunnel est créé ; un ID de tunnel déjà stocké dans la sortie est réutilisé lors des exécutions suivantes. | Aucune (crée un tunnel) | | `--output` | Destination de sortie : `dir:/path` ou `k8s-secret:NAME`. Le chart Helm transmet `k8s-secret:`. | `k8s-secret:mcp-tunnel` (détecté automatiquement lors de l'exécution dans un pod Kubernetes ; obligatoire sinon) | | `--cert-duration` | Période de validité du certificat serveur. | `2160h` (90 jours) | | `--token-version` | Chaîne de détection de changement. Une nouvelle valeur déclenche la rotation du jeton lors d'une nouvelle exécution. Le chart Helm et l'exemple Compose transmettent tous deux `1` comme valeur initiale. | Aucune | La commande s'authentifie via la [Workload Identity Federation](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation). Elle lit `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (facultatif), et exactement l'une des variables `ANTHROPIC_IDENTITY_TOKEN_FILE` ou `ANTHROPIC_IDENTITY_TOKEN`. Consultez la [référence WIF](https://platform.claude.com/docs/fr/manage-claude/wif-reference) pour la sémantique actuelle de ces variables ; le composant de configuration déduit le compte de service à partir de la règle de fédération, il ne nécessite donc pas `ANTHROPIC_SERVICE_ACCOUNT_ID` séparément. ### `setup renew-cert` Émet un nouveau certificat serveur signé par l'autorité de certification stockée. N'effectue aucun appel API. | Option | Description | Valeur par défaut | | ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `--output` | Destination de sortie : `dir:/path` ou `k8s-secret:NAME`. Le chart Helm transmet `k8s-secret:`. | `k8s-secret:mcp-tunnel` (détecté automatiquement lors de l'exécution dans un pod Kubernetes ; obligatoire sinon) | | `--cert-duration` | Période de validité du nouveau certificat. | `2160h` (90 jours) | | `--renew-before` | Ignore le renouvellement si le certificat existant dispose d'une durée restante supérieure à cette valeur. | `0` (toujours renouveler) | Définir `--renew-before=720h` fait de la commande une opération sans effet lorsqu'il reste plus de 30 jours de validité, de sorte qu'elle peut être exécutée en toute sécurité selon un calendrier fixe.