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á uma âncora de confiança para o certificado upstream.

Correspondência de rotas

routes é um mapa simples 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 ao 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 Túneis

Consulte a referência da Admin API de túneis MCP para todos os endpoints, esquemas de requisição e resposta, e exemplos por linguagem.

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

Requisitos de certificado

O componente de configuração gera certificados compatíveis 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/organizations/tunnels/{tunnel_id}/certificates. Um túnel pode manter até dois certificados de CA ativos por vez, 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 ao túnel que você criou no Console, 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 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.