--- title: Riferimento per i tunnel MCP url: https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/reference description: Campi di configurazione del proxy, l'API REST Tunnels, requisiti dei certificati e il componente di setup. --- I "MCP tunnels" (tunnel MCP) sono in "research preview" (anteprima di ricerca). [Richiedi l'accesso](https://claude.com/form/mcp-tunnels) per provarli. ## Configurazione del proxy Il [proxy](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) legge la propria configurazione da `/etc/mcp-gateway/config.yaml` (Compose) o dalla ConfigMap renderizzata (Helm, popolata da `gateway.config.*`). | Campo | Descrizione | Predefinito | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | `listen_addr` | Indirizzo e porta su cui ascoltare. | Obbligatorio | | `log_level` | Livello di dettaglio dei log: `debug`, `info`, `warn` o `error`. | `info` | | `shutdown_timeout` | Quanto tempo attendere le richieste in corso durante l'arresto controllato. | `30s` | | `tunnel_domain` | Dominio base assegnato al tunnel. Quando impostato, la ricerca delle route rimuove questo suffisso dagli hostname in ingresso, così le chiavi di `routes` possono essere semplici sottodomini (`wiki`). Quando vuoto, le chiavi di `routes` devono essere hostname completi esatti. | Obbligatorio quando le chiavi di `routes` sono semplici sottodomini | | `tls.cert_file` | Percorso del certificato TLS del server. | Obbligatorio | | `tls.key_file` | Percorso della chiave privata TLS del server. | Obbligatorio | | `routes` | Mappa da sottodominio o hostname completo a URL upstream. Vedi [Corrispondenza delle route](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/reference#route-matching). | Obbligatorio | | `upstream.allowed_ips` | Intervalli CIDR IPv4 o singoli indirizzi a cui il proxy è autorizzato a connettersi. Mutuamente esclusivo con `disable_ip_validation`. | Intervalli privati RFC1918 | | `upstream.disable_ip_validation` | Disabilita completamente la validazione degli IP upstream. Mutuamente esclusivo con `allowed_ips`. | `false` | | `upstream.tls.ca_file` | Bundle CA per la validazione del TLS upstream. | Nessuno | | `upstream.tls.include_system_cas` | Considera attendibile anche il bundle CA di sistema per il TLS upstream. | `false` | Per le route upstream `https://`, imposta almeno uno tra `upstream.tls.ca_file` o `upstream.tls.include_system_cas`; altrimenti il proxy non dispone di alcun trust anchor per il certificato upstream. ### Corrispondenza delle route `routes` è una mappa di stringhe piatta (`map[string]string`), non una lista. Il proxy cerca l'hostname in ingresso prima per corrispondenza esatta, poi rimuovendo il suffisso `tunnel_domain` e confrontando il sottodominio rimanente. La corrispondenza considera solo l'hostname; il percorso della richiesta e la query string vengono inoltrati al [server MCP upstream](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) senza modifiche. Ogni valore upstream deve essere esattamente `scheme://host:port`. La porta è obbligatoria. L'inclusione di un percorso viene rifiutata al caricamento della configurazione con `invalid upstream (must be scheme://host:port)`. ## API Tunnels L'API REST Tunnels si trova in `/v1/tunnels` e supporta la creazione, l'elenco e l'archiviazione dei tunnel, la registrazione dei certificati CA e la visualizzazione o la rotazione del token del tunnel. Consulta il [riferimento dell'API Tunnels](https://platform.claude.com/docs/it/api/beta/tunnels/list) per tutti gli endpoint, gli schemi di richiesta e risposta e gli esempi. La precedente superficie dell'Admin API in `/v1/organizations/tunnels` (header beta `mcp-tunnels-2026-05-19`, scope `org:manage_tunnels`) continua a funzionare durante una finestra di migrazione e rimane documentata nel [riferimento dell'Admin API](https://platform.claude.com/docs/it/api/beta/organization/mcp_tunnels) con un avviso di deprecazione. Per migrare, aggiorna il percorso a `/v1/tunnels`, l'header beta a `mcp-tunnels-2026-06-22` e lo scope del tuo token WIF a `workspace:manage_tunnels`. Tutti gli endpoint dei tunnel MCP richiedono un bearer token con lo scope `workspace:manage_tunnels` ottenuto tramite [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation). Le chiavi Admin API non sono accettate. Header obbligatori in ogni richiesta: | Header | Valore | | ------------------- | -------------------------------------------------------- | | `Authorization` | `Bearer ` (il token ottenuto tramite scambio WIF) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Requisiti dei certificati Il [componente di setup](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) genera automaticamente certificati conformi. Questi requisiti si applicano solo se emetti certificati tramite la tua PKI. ### Certificato CA Caricalo con `POST /v1/tunnels/{tunnel_id}/certificates`. Un tunnel può contenere fino a due certificati CA attivi contemporaneamente, il che consente una rotazione senza tempi di inattività. * Codificato PEM, certificato singolo, fino a 8 kB. * Estensione `BasicConstraints` presente con `CA:TRUE`, contrassegnata come critica. * Estensione `SubjectKeyIdentifier` presente. * `KeyUsage` include `keyCertSign`. * Entro il proprio periodo di validità. * RSA a 2048 bit o superiore, oppure ECDSA P-256 o superiore, con firma SHA-256 o più robusta. ### Certificato del server Presentato dal proxy durante il [TLS interno](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components). * Firmato direttamente da una CA registrata (nessun intermediario). * Estensione `AuthorityKeyIdentifier` presente e corrispondente al `SubjectKeyIdentifier` della CA. * Il Subject Alternative Name include un nome DNS corrispondente a `.`. Un wildcard `*.` copre tutte le route. * Se l'estensione `ExtendedKeyUsage` è presente, include `serverAuth`. * Entro il proprio periodo di validità. * RSA a 2048 bit o superiore, oppure ECDSA P-256 o superiore, con firma SHA-256 o più robusta. Il componente di setup genera una CA ECDSA P-256 con validità di cinque anni e un certificato del server RSA a 4096 bit con un SAN wildcard e validità di 90 giorni. ## Componente di setup Il componente di setup è distribuito all'interno dell'immagine `mcp-proxy` come binario `setup`. Eseguilo con `docker compose run --rm setup ` (Compose) oppure affidati agli hook e ai CronJob del chart (Helm). ### `setup init` Si collega a un tunnel esistente (o ne crea uno quando non viene fornito alcun ID tunnel), quindi genera una CA e un certificato del server, registra la CA, recupera il token del tunnel e scrive tutti gli output nella destinazione. | Flag | Descrizione | Predefinito | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `--api-url` | URL base della Claude API. Letto anche da `API_URL`. | Obbligatorio | | `--tunnel-id` | ID del tunnel a cui collegarsi (`tnl_...`). Letto anche da `TUNNEL_ID`. Se omesso, viene creato un nuovo tunnel; un ID tunnel già memorizzato nell'output viene riutilizzato nelle esecuzioni successive. | Nessuno (crea un tunnel) | | `--output` | Destinazione dell'output: `dir:/path` o `k8s-secret:NAME`. Il chart Helm passa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (rilevato automaticamente quando in esecuzione in un pod Kubernetes; obbligatorio altrimenti) | | `--cert-duration` | Periodo di validità del certificato del server. | `2160h` (90 giorni) | | `--token-version` | Stringa di rilevamento delle modifiche. Un nuovo valore attiva la rotazione del token alla riesecuzione. Il chart Helm e l'esempio Compose passano entrambi `1` come valore iniziale. | Nessuno | Il comando si autentica tramite [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation). Legge `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (opzionale) ed esattamente uno tra `ANTHROPIC_IDENTITY_TOKEN_FILE` o `ANTHROPIC_IDENTITY_TOKEN`. Consulta il [riferimento WIF](https://platform.claude.com/docs/it/manage-claude/wif-reference) per la semantica attuale di queste variabili; il componente di setup ricava il service account dalla regola di federazione, quindi non richiede `ANTHROPIC_SERVICE_ACCOUNT_ID` separatamente. ### `setup renew-cert` Emette un nuovo certificato del server firmato dalla CA memorizzata. Non effettua chiamate API. | Flag | Descrizione | Predefinito | | ----------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `--output` | Destinazione dell'output: `dir:/path` o `k8s-secret:NAME`. Il chart Helm passa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (rilevato automaticamente quando in esecuzione in un pod Kubernetes; obbligatorio altrimenti) | | `--cert-duration` | Periodo di validità del nuovo certificato. | `2160h` (90 giorni) | | `--renew-before` | Salta il rinnovo se il certificato esistente ha una durata residua superiore a questa. | `0` (rinnova sempre) | Impostare `--renew-before=720h` rende il comando un no-op quando rimangono più di 30 giorni di validità, quindi è sicuro eseguirlo con una pianificazione fissa.