Riferimento per i tunnel MCP

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 alcuna 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 tramite 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 dei Tunnel

Consulta il riferimento dell'Admin API per i tunnel MCP per tutti gli endpoint, gli schemi di richiesta e risposta e gli esempi per ciascun linguaggio.

Header obbligatori su ogni richiesta:

Requisiti dei certificati

Il componente di setup genera automaticamente certificati conformi. Questi requisiti si applicano solo se emetti i certificati tramite la tua PKI.

Certificato CA

Caricalo con POST /v1/organizations/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 proprio 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 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 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 al tunnel creato nella Console, 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.