---
title: Solucionar problemas de túneis MCP
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/troubleshooting
description: Diagnostique problemas de conectividade, TLS, validação de IP e roteamento OAuth em uma pilha de túnel.
---
Os "MCP tunnels" (túneis MCP) estão em prévia de pesquisa. [Solicite acesso](https://claude.com/form/mcp-tunnels) para experimentá-los.
Uma requisição através do túnel pode falhar em uma de três camadas; diagnostique-as em ordem: a conexão de saída para a [borda do túnel](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components), o [TLS interno](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) da Anthropic para o seu [proxy](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) e, em seguida, o roteamento e a validação de IP em direção ao [servidor MCP upstream](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components).
## Referência rápida
| Sintoma | Causa | Correção |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| O túnel não aparece no seletor **+ MCP Server** do agente | O seletor lista apenas túneis no workspace da sessão que tenham pelo menos um certificado ativo. | Registre um certificado de CA ou abra a sessão no workspace em que o túnel foi criado. |
| O chamador vê HTTP 500; o [cloudflared](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) registra `No ingress rules were defined` | O cloudflared não tem um destino local. | Adicione `--url http://localhost:8080` e `network_mode: "service:mcp-proxy"` ao serviço cloudflared. |
| O proxy registra `no route for host` | `tunnel_domain` não corresponde ao domínio atribuído, ou `config.yaml` foi editado sem reiniciar. | Defina `tunnel_domain` como o domínio exato mostrado na página de detalhes do túnel e, em seguida, reinicie o proxy (`docker compose restart mcp-proxy`). |
| O proxy registra `IP validation failed: is not a private address` | O servidor MCP upstream resolve para fora do RFC1918. | Consulte [Validação de IP upstream](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). |
| O proxy encerra com `cannot unmarshal !!seq into map[string]string` | `routes` é uma lista YAML. | Use `routes: { name: http://host:port }`. |
| O proxy encerra com `open /data/tls.key: permission denied` | A chave é `0600`; o contêiner do proxy é executado como não-root. | `chmod 644 data/tls.key`. |
| `curl https://:8080` falha com `wrong version number` | Esperado; o listener é WebSocket em texto simples. O TLS acontece dentro do fluxo WS. | Verifique por meio de um [Managed Agent ou da Messages API](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) em vez disso. |
As seções a seguir abordam falhas que precisam de mais do que uma correção de uma linha.
## OAuth falha atrás de uma allowlist de IP de origem
Os fluxos OAuth falham quando a allowlist de IP de origem do seu servidor de autorização impede que o backend da Anthropic alcance `/token`, `/register` e os endpoints de descoberta. Se você preferir não incluir na allowlist os intervalos de egress da Anthropic, pode rotear as chamadas OAuth de backend para backend através do túnel, mantendo o endpoint `/authorize` voltado para o navegador no seu hostname público existente.
```yaml
routes:
mcp: http://your-mcp-server:8080
auth: http://your-auth-server:8080
```
Reinicie o proxy após editar `routes` (`docker compose restart mcp-proxy` ou `helm upgrade`).
A resposta `/.well-known/oauth-authorization-server` do seu servidor de autorização deve apontar `authorization_endpoint` para o seu hostname existente já incluído na allowlist e todo o restante para o túnel:
```json
{
"issuer": "https://auth.",
"authorization_endpoint": "https:///authorize",
"token_endpoint": "https://auth./token",
"registration_endpoint": "https://auth./register",
"code_challenge_methods_supported": ["S256"]
}
```
A resposta `/.well-known/oauth-protected-resource` do seu servidor MCP deve referenciar o hostname do túnel como seu servidor de autorização:
```json
{
"resource": "https://mcp.",
"authorization_servers": ["https://auth."]
}
```
Com essa configuração, o navegador do usuário acessa `/authorize` no seu hostname existente (que sua allowlist já permite), enquanto o backend da Anthropic alcança `/token`, `/register` e os documentos de descoberta através do túnel.
## Falhas de autenticação do componente de setup
O [componente de setup](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/concepts#components) (Job do Helm ou serviço `setup` do Compose) autentica-se na Tunnels API trocando um JWT OIDC por meio da sua regra de federação. Quando a troca falha, consulte [Solucionar problemas de uma troca com falha](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#troubleshoot-a-failed-exchange) na referência de Workload Identity Federation; os modos de falha (subject, audience, issuer, JWKS, tempo de vida) são os mesmos.
Causas específicas de túneis:
* A audience padrão do chart é `api.anthropic.com` (sem esquema). Se a audience da sua regra for `https://api.anthropic.com`, defina `api.wif.audience` para corresponder.
* Um `403` da Tunnels API após uma troca bem-sucedida significa que o escopo da regra não inclui `workspace:manage_tunnels`, ou que a conta de serviço da regra não é membro do workspace do túnel. Defina o escopo e adicione a conta de serviço ao workspace.
No Helm, o componente de setup é executado como um Job de hook pre-install. Em caso de falha, o Job é mantido para inspeção (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). O Helm não gerencia recursos de hook, portanto exclua-o antes de tentar novamente:
```bash
helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup
```
## O túnel não conecta
Verifique primeiro os logs do cloudflared. Causas comuns:
* O `TUNNEL_TOKEN` está ausente, expirado ou foi copiado incorretamente.
* Um firewall está bloqueando TCP/UDP de saída na porta 7844 para a borda do túnel.
O cloudflared também pode registrar avisos sobre tamanhos de buffer de recebimento UDP; isso é uma dica de ajuste de QUIC, não um erro.
## Erros de certificado
Quando a Anthropic rejeita o certificado do proxy durante o TLS interno, o proxy registra `tls handshake failed`. Verifique se:
* O certificado do servidor não expirou.
* O Subject Alternative Name do certificado corresponde a `*.`.
* A CA signatária está registrada na Anthropic para este túnel.
Consulte os [requisitos de certificado](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/reference#certificate-requirements) para as regras de validação completas.
## Validação de IP upstream
Para proteção contra SSRF, por padrão o proxy só se conecta a endereços nos intervalos privados RFC1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`). Apenas IPv4 é suportado para a conexão do proxy ao upstream. (O intervalo de egress do cloudflared para a borda em [Requisitos de rede](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/overview#network-requirements) é um salto diferente.)
Se o proxy registrar `IP validation failed: is not a private address`, o hostname upstream resolveu para fora desse conjunto. No Kubernetes, algumas distribuições gerenciadas alocam o CIDR de Service fora do RFC1918; se `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` retornar um endereço fora dos intervalos privados, procure o CIDR de Service do seu cluster e adicione-o.
Se o endereço for legítimo, adicione o CIDR mais restrito que o cubra a `upstream.allowed_ips`. Definir `allowed_ips` **substitui** o padrão RFC1918 em vez de estendê-lo, portanto inclua os intervalos privados que seus outros servidores MCP upstream usam:
```yaml config/mcp-proxy.yaml
upstream:
allowed_ips:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- 127.0.0.0/8 # loopback, for local testing only
```
Evite `0.0.0.0/0` fora de testes locais; isso desativa totalmente a proteção contra SSRF.