Riferimento per i tunnel MCP



Configurazione del proxy

Il proxy legge la propria configurazione da /etc/mcp-gateway/config.yaml (Compose) o dal ConfigMap renderizzato (Helm, popolato 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 ha alcun trust anchor per il certificato upstream.



Corrispondenza delle route

routes è una mappa piatta di stringhe (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 su /v1/tunnels e supporta la creazione, l'elenco e l'archiviazione dei tunnel, la registrazione dei certificati CA e la visualizzazione o 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 su 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

Carica con POST /v1/tunnels/{tunnel_id}/certificates. Un tunnel può contenere fino a due certificati CA attivi contemporaneamente, il che consente la rotazione senza tempi di inattività.

• Codificato in PEM, singolo certificato, fino a 8 kB.
• Estensione BasicConstraints presente con CA:TRUE, contrassegnata come critica.
• Estensione SubjectKeyIdentifier presente.
• KeyUsage include keyCertSign.
• All'interno del suo periodo di validità.
• RSA a 2048 bit o superiore, oppure ECDSA P-256 o superiore, con firma SHA-256 o più robusta.



Certificato server

Presentato dal proxy durante l'inner TLS.

• Firmato direttamente da una CA registrata (nessun certificato intermedio).
• 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.
• All'interno del suo 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 server RSA a 4096 bit con un SAN wildcard e validità di 90 giorni.



Componente di setup

Il componente di setup è incluso nell'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 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 deriva il service account dalla regola di federazione, quindi non richiede ANTHROPIC_SERVICE_ACCOUNT_ID separatamente.



setup renew-cert

Emette un nuovo certificato 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.