Solucionar problemas de túneis MCP

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, o TLS interno da Anthropic para o seu proxy e, em seguida, o roteamento e a validação de IP em direção ao servidor MCP upstream.

Referência rápida

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.

1. 1

   Adicione uma rota de proxy para o servidor de autorização

   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).

2. 2

   Sirva metadados de descoberta com endpoints divididos

   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:

   {
     "issuer": "https://auth.<tunnel-domain>",
     "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
     "token_endpoint": "https://auth.<tunnel-domain>/token",
     "registration_endpoint": "https://auth.<tunnel-domain>/register",
     "code_challenge_methods_supported": ["S256"]
   }

   
3. 3

   Aponte o servidor MCP para o emissor do túnel

   A resposta /.well-known/oauth-protected-resource do seu servidor MCP deve referenciar o hostname do túnel como seu servidor de autorização:

   {
     "resource": "https://mcp.<tunnel-domain>",
     "authorization_servers": ["https://auth.<tunnel-domain>"]
   }

   

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 (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 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:

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 *.<tunnel-domain>.
• A CA signatária está registrada na Anthropic para este túnel.

Consulte os requisitos de certificado 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 é um salto diferente.)

Se o proxy registrar IP validation failed: <ip> 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:

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