--- title: Referência de túneis MCP url: https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/reference description: Campos de configuração do proxy, a API REST de Tunnels, requisitos de certificado e o componente de setup. --- Os "MCP tunnels" (túneis MCP) estão em prévia de pesquisa. [Solicite acesso](https://claude.com/form/mcp-tunnels) para experimentá-los. ## Configuração do proxy O [proxy](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) lê sua configuração de `/etc/mcp-gateway/config.yaml` (Compose) ou do ConfigMap renderizado (Helm, preenchido a partir de `gateway.config.*`). | Campo | Descrição | Padrão | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `listen_addr` | Endereço e porta em que escutar. | Obrigatório | | `log_level` | Verbosidade de log: `debug`, `info`, `warn` ou `error`. | `info` | | `shutdown_timeout` | Quanto tempo aguardar por requisições em andamento durante o desligamento gracioso. | `30s` | | `tunnel_domain` | Domínio base atribuído ao túnel. Quando definido, a busca de rotas remove esse sufixo dos hostnames recebidos para que as chaves de `routes` possam ser subdomínios simples (`wiki`). Quando vazio, as chaves de `routes` devem ser hostnames completos exatos. | Obrigatório quando as chaves de `routes` são subdomínios simples | | `tls.cert_file` | Caminho para o certificado TLS do servidor. | Obrigatório | | `tls.key_file` | Caminho para a chave privada TLS do servidor. | Obrigatório | | `routes` | Mapa de subdomínio ou hostname completo para URL upstream. Consulte [Correspondência de rotas](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/reference#route-matching). | Obrigatório | | `upstream.allowed_ips` | Faixas CIDR IPv4 ou endereços únicos aos quais o proxy tem permissão para se conectar. Mutuamente exclusivo com `disable_ip_validation`. | Faixas privadas RFC1918 | | `upstream.disable_ip_validation` | Desativa totalmente a validação de IP upstream. Mutuamente exclusivo com `allowed_ips`. | `false` | | `upstream.tls.ca_file` | Bundle de CA para validar o TLS upstream. | Nenhum | | `upstream.tls.include_system_cas` | Confiar também no bundle de CA do sistema para o TLS upstream. | `false` | 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) 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](https://platform.claude.com/docs/pt-BR/api/beta/tunnels/list) para todos os endpoints, esquemas de requisição e resposta, e exemplos. A superfície anterior da Admin API em `/v1/organizations/tunnels` (cabeçalho beta `mcp-tunnels-2026-05-19`, escopo `org:manage_tunnels`) continua funcionando durante uma janela de migração e permanece documentada na [referência da Admin API](https://platform.claude.com/docs/pt-BR/api/beta/organization/mcp_tunnels) com um aviso de descontinuação. Para migrar, atualize o caminho para `/v1/tunnels`, o cabeçalho beta para `mcp-tunnels-2026-06-22` e o escopo do seu token WIF para `workspace:manage_tunnels`. Todos os endpoints de túneis MCP exigem um bearer token com o escopo `workspace:manage_tunnels` obtido por meio de [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation). Chaves de API de administrador não são aceitas. Cabeçalhos obrigatórios em toda requisição: | Cabeçalho | Valor | | ------------------- | ----------------------------------------------- | | `Authorization` | `Bearer ` (o token obtido via troca WIF) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Requisitos de certificado O [componente de setup](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components). * 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 `.`. Um wildcard `*.` 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 ` (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. | Flag | Descrição | Padrão | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `--api-url` | URL base da Claude API. Também lida de `API_URL`. | Obrigatório | | `--tunnel-id` | ID do túnel ao qual se conectar (`tnl_...`). Também lido de `TUNNEL_ID`. Quando omitido, um novo túnel é criado; um ID de túnel já armazenado na saída é reutilizado em novas execuções. | Nenhum (cria um túnel) | | `--output` | Destino de saída: `dir:/path` ou `k8s-secret:NAME`. O chart Helm passa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (detectado automaticamente ao executar em um pod Kubernetes; obrigatório caso contrário) | | `--cert-duration` | Período de validade do certificado do servidor. | `2160h` (90 dias) | | `--token-version` | String de detecção de mudança. Um novo valor aciona a rotação do token em uma nova execução. O chart Helm e o exemplo Compose passam ambos `1` como valor inicial. | Nenhum | O comando se autentica por meio de [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/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](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference) 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. | Flag | Descrição | Padrão | | ----------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `--output` | Destino de saída: `dir:/path` ou `k8s-secret:NAME`. O chart Helm passa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (detectado automaticamente ao executar em um pod Kubernetes; obrigatório caso contrário) | | `--cert-duration` | Período de validade do novo certificado. | `2160h` (90 dias) | | `--renew-before` | Ignora a renovação se o certificado existente tiver mais do que essa duração restante. | `0` (sempre renovar) | 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.