MessaggiTunnel MCP

Gestire i tunnel nella Claude Console

Copy page



Crea tunnel, registra certificati CA, recupera il token del tunnel e collega server MCP in tunnel agli agenti dalla Claude Console.

Questa pagina copre il lato Console di un deployment di tunnel MCP: creare un tunnel, registrare il tuo certificato CA, recuperare il token del tunnel e collegare i server MCP upstream a un agente. Distribuire tunnel MCP con Helm e Distribuire tunnel MCP con Docker Compose coprono l'esecuzione dello stack del tunnel all'interno della tua rete.

Prerequisiti

• Uno o più server MCP in esecuzione nella tua rete privata. Il tunnel instrada il traffico verso di essi; non li ospita. Consulta Server MCP remoti per esempi che puoi distribuire.
• Un ruolo Console con il permesso Manage tunnels, in modo da poter creare e archiviare tunnel, ruotare il token e gestire i certificati. Gli amministratori e i proprietari dell'organizzazione lo hanno per impostazione predefinita; anche i ruoli personalizzati e le concessioni per singolo account possono includerlo. I ruoli che non lo hanno dispongono di accesso in sola lettura alla pagina MCP tunnels e ai dettagli del tunnel.
• Un modo per il tuo stack di autenticarsi alla Tunnels API. Scegli una delle opzioni:
  • Accesso programmatico (consigliato). Configura la Workload Identity Federation durante la creazione del tunnel in modo che il tuo stack emetta token API di breve durata dal tuo identity provider, recuperi il token del tunnel e generi e registri automaticamente un certificato CA. Richiede il permesso di gestire le regole di federazione, un issuer OIDC registrato e una regola di federazione con lo scope workspace:manage_tunnels.
  • Manuale. Salta l'accesso programmatico. Dopo aver creato il tunnel, ottieni il token del tunnel, genera e registra un certificato CA tu stesso, e fornisci il token e il tuo certificato server al tuo stack del tunnel come secret.

Creare un tunnel

1. 1

   Apri la pagina MCP tunnels

   Nella Claude Console, vai alla pagina MCP tunnels (platform.claude.com/settings/workspaces/default/mcp-tunnels). I tunnel hanno ambito di workspace; il nuovo tunnel appartiene al workspace attualmente selezionato nella Console. Seleziona il workspace desiderato nel selettore dei workspace nella barra laterale.

2. 2

   Assegna un nome al tunnel

   Fai clic su New tunnel e inserisci un nome nella finestra di dialogo Create tunnel. Il nome è obbligatorio e identifica il tunnel nell'elenco, nella pagina dei dettagli e nel selettore dei server MCP dell'agente. Un dominio nel formato abcd1234.tunnel.anthropic.com viene assegnato automaticamente.

3. 3

   Facoltativamente, configura l'accesso programmatico

   Se il tuo ruolo può gestire le regole di federazione, appare un interruttore Set up programmatic access (disattivato per impostazione predefinita). In caso contrario, la Console mostra un avviso al suo posto e il tuo stack del tunnel usa invece il flusso manuale. Il resto del flusso di creazione è lo stesso in entrambi i casi.

   L'accesso programmatico si basa sulla Workload Identity Federation; leggi prima quella pagina se issuer di federazione, regole e service account non ti sono familiari. Per attivare l'interruttore hai bisogno di:

   1. Un issuer OIDC registrato per l'identity provider da cui il tuo stack presenta i token (come un cluster Kubernetes, AWS IAM, Google Cloud o GitHub Actions). Registrane uno nella scheda Issuers della pagina Workload identity (platform.claude.com/settings/workload-identity-federation) nella Claude Console se la tua organizzazione non ne ha uno.
   2. Una regola di federazione con lo scope workspace:manage_tunnels. L'attivazione dell'interruttore mostra un selettore Federation rule. Seleziona una regola esistente con quello scope, oppure fai clic su Create federation rule per crearne una direttamente.
   3. Il service account della regola aggiunto a questo workspace. La Tunnels API esegue l'autorizzazione in base alle appartenenze ai workspace del service account. Se stai creando il tunnel in un workspace diverso da quello predefinito dell'organizzazione, aggiungi il service account a quel workspace e passa l'ID del workspace al momento del deployment (api.wif.workspaceId per Helm, ANTHROPIC_WORKSPACE_ID per Compose).

   Saltare questo passaggio è pienamente supportato; entrambe le guide di deployment hanno una scheda Without programmatic access.

4. 4

   Crea il tunnel

   Fai clic su Create tunnel. La Console effettua il provisioning del tunnel e apre la pagina di dettaglio.

5. 5

   Annota gli identificatori per il deployment

   Entrambi i percorsi di deployment richiedono:

   • L'ID del tunnel (tnl_...), mostrato nella pagina di dettaglio del tunnel.
   • Il dominio del tunnel (abcd1234.tunnel.anthropic.com), mostrato nella pagina di dettaglio del tunnel. Usato come tunnel_domain del proxy e nel SAN del certificato server.

   Cos'altro ti serve dipende dalla modalità di provisioning delle credenziali:

   Con accesso programmatico	Senza accesso programmatico
   L'ID della regola di federazione (fdrl_...) della regola selezionata. La regola è a livello di organizzazione, non è memorizzata nel tunnel; la trovi nella scheda Rules della pagina Workload identity (platform.claude.com/settings/workload-identity-federation?tab=rules) nella Claude Console.	Il token del tunnel, visualizzabile con l'icona a forma di occhio accanto a Token nella pagina di dettaglio. Trattalo come un secret. Consulta Ottenere i dettagli di connessione.
   L'ID dell'organizzazione (un UUID), mostrato nella pagina Organization (platform.claude.com/settings/organization) nella Claude Console.	Un certificato CA che generi e registri sul tunnel.

   Con l'accesso programmatico, il tuo stack recupera il token del tunnel tramite la Tunnels API, genera localmente la CA e il certificato server (la chiave privata non lascia mai il tuo ambiente) e registra presso Anthropic solo il certificato pubblico della CA. Resti comunque responsabile della protezione delle chiavi private e del rinnovo del certificato server prima della sua scadenza.

La tua organizzazione può avere fino a 10 tunnel attivi. La creazione di un tunnel non stabilisce alcuna connettività; questa avviene quando il tuo stack si connette con il token del tunnel e viene registrato un certificato CA.

Ottenere i dettagli di connessione

Apri il tunnel. La pagina di dettaglio mostra una sezione Connection con il dominio e il token e una sezione Certificates.

Aggiungere un certificato CA

Anthropic verifica il TLS interno verso il tuo proxy rispetto ai certificati CA che registri sul tunnel. Un tunnel senza certificati attivi non può accettare connessioni e non appare nel selettore dei server MCP dell'agente finché non ne viene registrato uno.

1. 1

   Trova la sezione Certificates

   Nella pagina di dettaglio del tunnel, scorri fino alla sezione Certificates e fai clic su Add certificate.

2. 2

   Fornisci il certificato

   Fai clic su Choose file per selezionare un file .pem, .crt o .cer, trascina il file nell'area di testo oppure incolla direttamente il blocco PEM. La finestra modale rifiuta materiale di chiave privata e contenuti che non siano un blocco -----BEGIN CERTIFICATE-----. Il file deve avere una dimensione di 8 kB o inferiore.

3. 3

   Aggiungi il certificato

   Fai clic su Add certificate. L'impronta digitale e la scadenza appaiono nell'elenco dei certificati e il conteggio degli slot nell'intestazione della sezione aumenta.

Un tunnel contiene fino a due certificati attivi in modo da poter ruotare senza tempi di inattività: registra il nuovo certificato accanto a quello vecchio, ridistribuisci il tuo proxy con la nuova coppia di chiavi, conferma che il traffico stia fluendo, quindi fai clic su Revoke nella riga del vecchio certificato. I certificati revocati restano visibili nell'elenco con un badge Revoked.

Distribuire lo stack del tunnel

Il tunnel esiste nella Console, ma nessun traffico fluisce finché lo stack del tunnel non è in esecuzione all'interno della tua rete e connesso con il token del tunnel. Segui una delle guide di deployment:

Usare il tunnel in un agente

Una volta che il tuo stack è in esecuzione e ha uno o più server MCP configurati, collega un server MCP upstream a una sessione di Managed Agent. Per chiamare gli stessi server dalla Messages API invece, consulta Usare i server MCP in tunnel.

1. 1

   Apri la finestra di dialogo Create session

   Nella Claude Console, vai alla pagina Sessions (platform.claude.com/sessions) e fai clic su Create session.

2. 2

   Definisci un agente inline

   Nel selettore degli agenti, seleziona Create new agent per poter modificare direttamente l'elenco dei server MCP.

3. 3

   Aggiungi il server MCP

   Fai clic su + MCP Server e apri il menu a discesa. I tunnel creati nel workspace corrente appaiono in cima all'elenco, sopra il catalogo pubblico dei connettori. Seleziona il tunnel che fa da front-end al server che vuoi raggiungere.

4. 4

   Fornisci l'instradamento

   La scheda mostra due campi facoltativi: Subdomain (anteposto al dominio del tunnel) e Path (aggiunto dopo di esso). Compila uno o entrambi, a seconda di come sono configurate le route del tuo proxy. La riga Resolves to mostra l'URL completo del server MCP a cui l'agente si connette.

Archiviare un tunnel

L'archiviazione impedisce immediatamente al tunnel di accettare connessioni ed è permanente.

Nella Claude Console, vai alla pagina MCP tunnels (platform.claude.com/settings/workspaces/default/mcp-tunnels). Nel selettore di workspace nella barra laterale, seleziona il workspace che contiene il tunnel. Apri il menu della riga del tunnel e seleziona Archive. I tunnel archiviati rimangono visibili quando filtri l'elenco per Archived o All.

Passaggi successivi