MessagesTúneis MCP

Referência de túneis MCP

Copy page



Campos de configuração do proxy, a API REST de Tunnels, requisitos de certificado e o componente de setup.

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 suporta 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 toda requisição:

Requisitos de certificado

O componente de setup gera certificados em conformidade automaticamente. Estes requisitos se aplicam apenas se você emitir certificados por meio da sua própria PKI.

Certificado de CA

Faça o 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 seu 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árias).
• Extensão AuthorityKeyIdentifier presente e correspondente ao SubjectKeyIdentifier da CA.
• O Subject Alternative Name inclui um nome DNS correspondente a <route>.<tunnel-domain>. Um wildcard *.<tunnel-domain> cobre todas as rotas.
• Se a extensão ExtendedKeyUsage estiver presente, ela inclui serverAuth.
• Dentro do seu 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 setup gera uma CA ECDSA P-256 com validade de cinco anos e um certificado de servidor RSA de 4096 bits com um SAN wildcard e validade de 90 dias.

Componente de setup

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

setup init

Conecta-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, obtém 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 setup 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 à API.

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