MensagensTúneis MCP

Solucionar problemas de túneis MCP

Diagnostique problemas de conectividade, TLS, validação de IP e roteamento OAuth em uma pilha de túnel.

Os túneis MCP estão em prévia de pesquisa. Solicite acesso 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, o TLS interno da Anthropic para o seu proxy, e então o roteamento e a validação de IP em direção ao servidor MCP upstream.

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 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` com o domínio exato mostrado na página de detalhes do túnel, depois reinicie o proxy (`docker compose restart mcp-proxy`).
O proxy registra `IP validation failed: <ip> is not a private address`	O servidor MCP upstream resolve para fora do RFC1918.	Consulte Validação de IP upstream.
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 está com `0600`; o container do proxy executa como não-root.	`chmod 644 data/tls.key`.
`curl https://<proxy>:8080` falha com `wrong version number`	Esperado; o listener é WebSocket em texto simples. O TLS acontece dentro do fluxo WS.	Verifique através de um Managed Agent ou da Messages API em vez disso.

As seções a seguir cobrem 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" (lista de permissões) de IP de origem do seu servidor de autorização bloqueia o backend da Anthropic de alcançar /token, /register e os endpoints de descoberta. Se você preferir não adicionar os intervalos de egresso da Anthropic à allowlist, pode rotear as chamadas OAuth de backend para backend através do túnel, mantendo o endpoint /authorize voltado ao navegador no seu hostname público existente.

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

Sirva metadados de descoberta com endpoints divididos

A resposta de /.well-known/oauth-authorization-server do seu servidor de autorização deve apontar authorization_endpoint para o seu hostname existente na allowlist e todo o resto 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"]
}

Aponte o servidor MCP para o issuer do túnel
A resposta de /.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 configuração

O componente de configuração (Job do Helm ou serviço setup do Compose) autentica-se na Tunnels API trocando um JWT OIDC através 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, lifetime) 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 org: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 configuração executa como um Job de hook pre-install. Em caso de falha, o Job é deixado para inspeção (kubectl logs job/mcp-tunnel-setup -n mcp-tunnel). O Helm não gerencia recursos de hook, então 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 os logs do cloudflared primeiro. 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 do 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 assinante está registrada na Anthropic para este túnel.

Consulte os requisitos de certificado para as regras completas de validação.

Validação de IP upstream

Para proteção contra SSRF, o proxy só disca para endereços nos intervalos privados RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) por padrão. Apenas IPv4 é suportado para a conexão do proxy ao upstream. (O intervalo de egresso 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 Service CIDR fora do RFC1918; se kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}' retornar um endereço fora dos intervalos privados, consulte o Service CIDR 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, então inclua os intervalos privados que seus outros servidores MCP upstream usam:

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 completamente a proteção contra SSRF.

Was this page helpful?

MensagensTúneis MCP

Solucionar problemas de túneis MCP

Diagnostique problemas de conectividade, TLS, validação de IP e roteamento OAuth em uma pilha de túnel.

Os túneis MCP estão em prévia de pesquisa. Solicite acesso para experimentá-los.

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 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` com o domínio exato mostrado na página de detalhes do túnel, depois reinicie o proxy (`docker compose restart mcp-proxy`).
O proxy registra `IP validation failed: <ip> is not a private address`	O servidor MCP upstream resolve para fora do RFC1918.	Consulte Validação de IP upstream.
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 está com `0600`; o container do proxy executa como não-root.	`chmod 644 data/tls.key`.
`curl https://<proxy>:8080` falha com `wrong version number`	Esperado; o listener é WebSocket em texto simples. O TLS acontece dentro do fluxo WS.	Verifique através de um Managed Agent ou da Messages API em vez disso.

As seções a seguir cobrem falhas que precisam de mais do que uma correção de uma linha.

OAuth falha atrás de uma allowlist de IP de origem

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

Sirva metadados de descoberta com endpoints divididos

A resposta de /.well-known/oauth-authorization-server do seu servidor de autorização deve apontar authorization_endpoint para o seu hostname existente na allowlist e todo o resto 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"]
}

Aponte o servidor MCP para o issuer do túnel
A resposta de /.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>"] }

Falhas de autenticação do componente de configuração

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 org: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.

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

O túnel não conecta

Verifique os logs do cloudflared primeiro. 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 do 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 assinante está registrada na Anthropic para este túnel.

Consulte os requisitos de certificado para as regras completas de validação.

Validação de IP upstream

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 completamente a proteção contra SSRF.

Was this page helpful?