MessagesTunnel MCP

Riferimento per i tunnel MCP

Copy page



Campi di configurazione del proxy, l'API REST Tunnels, requisiti dei certificati e il componente di setup.

Configurazione del proxy

Il proxy legge la propria configurazione da /etc/mcp-gateway/config.yaml (Compose) o dalla ConfigMap renderizzata (Helm, popolata da gateway.config.*).

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 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 per tutti gli endpoint, gli schemi di richiesta e risposta e gli esempi.

Header obbligatori in ogni richiesta:

Requisiti dei certificati

Il componente di setup 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.

• 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 <route>.<tunnel-domain>. Un wildcard *.<tunnel-domain> 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 <subcommand> (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.

Il comando si autentica tramite 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 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.

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.