Referência de túneis MCP



Configuração do proxy

O proxy lê sua configuração de /etc/mcp-gateway/config.yaml (Compose) ou do ConfigMap renderizado (Helm, preenchido a partir de gateway.config.*).

Para rotas upstream https://, defina pelo menos um entre upstream.tls.ca_file ou upstream.tls.include_system_cas; caso contrário, o proxy não terá âncora de confiança para o certificado upstream.



Correspondência de rotas

routes é um mapa plano de strings (map[string]string), não uma lista. O proxy busca o hostname recebido primeiro por correspondência exata e, em seguida, removendo o sufixo tunnel_domain e correspondendo o subdomínio restante. A correspondência considera apenas o hostname; o caminho da requisição e a query string são encaminhados ao servidor MCP upstream sem alterações.

Cada valor upstream deve ser exatamente scheme://host:port. A porta é obrigatória. Incluir um caminho é rejeitado no carregamento da configuração com invalid upstream (must be scheme://host:port).



API de Tunnels

A API REST de Tunnels fica em /v1/tunnels e permite criar, listar e arquivar túneis, registrar certificados de CA e revelar ou rotacionar o token do túnel. Consulte a referência da API de Tunnels para todos os endpoints, esquemas de requisição e resposta e exemplos.

Cabeçalhos obrigatórios em todas as requisições:



Requisitos de certificado

O componente de configuração gera certificados em conformidade automaticamente. Esses requisitos se aplicam apenas se você emitir certificados por meio de sua própria PKI.



Certificado de CA

Faça upload com POST /v1/tunnels/{tunnel_id}/certificates. Um túnel pode manter até dois certificados de CA ativos ao mesmo tempo, o que permite rotação sem tempo de inatividade.

• Codificado em PEM, certificado único, até 8 kB.
• Extensão BasicConstraints presente com CA:TRUE, marcada como crítica.
• Extensão SubjectKeyIdentifier presente.
• KeyUsage inclui keyCertSign.
• Dentro do período de validade.
• RSA de 2048 bits ou maior, ou ECDSA P-256 ou maior, com assinatura SHA-256 ou mais forte.



Certificado do servidor

Apresentado pelo proxy durante o TLS interno.

• Assinado diretamente por uma CA registrada (sem intermediários).
• Extensão AuthorityKeyIdentifier presente e correspondente ao SubjectKeyIdentifier da CA.
• Subject Alternative Name inclui um nome DNS correspondente a <route>.<tunnel-domain>. Um curinga *.<tunnel-domain> cobre todas as rotas.
• Se a extensão ExtendedKeyUsage estiver presente, ela inclui serverAuth.
• Dentro do período de validade.
• RSA de 2048 bits ou maior, ou ECDSA P-256 ou maior, com assinatura SHA-256 ou mais forte.

O componente de configuração gera uma CA ECDSA P-256 com validade de cinco anos e um certificado de servidor RSA de 4096 bits com um SAN curinga e validade de 90 dias.



Componente de configuração

O componente de configuração é distribuído dentro da imagem mcp-proxy como o binário setup. Execute-o com docker compose run --rm setup <subcommand> (Compose) ou utilize os hooks e CronJobs do chart (Helm).



setup init

Anexa-se a um túnel existente (ou cria um quando nenhum ID de túnel é fornecido), depois gera uma CA e um certificado de servidor, registra a CA, recupera o token do túnel e grava todas as saídas no destino.

O comando se autentica por meio de Workload Identity Federation. Ele lê ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID (opcional) e exatamente um entre ANTHROPIC_IDENTITY_TOKEN_FILE ou ANTHROPIC_IDENTITY_TOKEN. Consulte a referência de WIF para a semântica atual dessas variáveis; o componente de configuração deriva a conta de serviço a partir da regra de federação, portanto não requer ANTHROPIC_SERVICE_ACCOUNT_ID separadamente.



setup renew-cert

Emite um novo certificado de servidor assinado pela CA armazenada. Não faz chamadas de API.

Definir --renew-before=720h torna o comando uma operação sem efeito quando restam mais de 30 dias de validade, portanto é seguro executá-lo em um agendamento fixo.