Túneis MCP | Anthropic Help Center

O que é?

Conecte Claude com segurança aos servidores MCP em execução na sua rede privada sem abrir portas de entrada ou expor serviços à internet. MCP Tunnels está atualmente em beta privado e depende do serviço Tunnel do Cloudflare.

Como funciona

MCP Tunnels criam uma conexão entre Claude e seus servidores MCP internos que é criptografada em trânsito com múltiplas camadas de segurança.

Quando Claude precisa acessar um servidor MCP na sua rede privada, a solicitação viaja através de um túnel seguro. Você implanta dois componentes do seu lado:

cloudflared (agente de túnel do Cloudflare)
MCP Gateway (fornecido pela Anthropic)

Cloudflared inicia uma conexão apenas de saída para a borda do Cloudflare. Nenhuma porta de entrada precisa ser aberta no seu firewall. O MCP Gateway encerra uma camada TLS interna, valida IPs upstream para evitar SSRF e roteia cada solicitação para o servidor MCP correto com base no subdomínio.

A conexão é protegida com três camadas independentes: mTLS externo entre Anthropic e Cloudflare (com validação de IP), TLS interno que criptografa payloads de ponta a ponta do backend da Anthropic para seu gateway (projetado para que Cloudflare não tenha acesso aos payloads MCP) e autenticação OAuth na camada de aplicação em cada servidor MCP.

O que você implanta

cloudflared

Agente de túnel do Cloudflare. Inicia conexões apenas de saída — nenhuma porta de entrada necessária.

MCP Gateway

Componente fornecido pela Anthropic que encerra TLS interno, valida IPs e roteia solicitações para seus servidores MCP.

Propriedades de segurança principais

Nenhuma porta de entrada necessária. cloudflared inicia apenas conexões de saída — seu firewall permanece fechado.
Criptografia de ponta a ponta. O tráfego é criptografado em trânsito do backend da Anthropic para seu gateway. Os payloads MCP não podem ser lidos pelo Cloudflare.
Defesa em profundidade. Múltiplas camadas de autenticação: mTLS, TLS interno e OAuth na camada de aplicação.
Proteção SSRF. O gateway valida IPs upstream para ajudar a prevenir ataques de falsificação de solicitação.

Este guia fornece implantações de referência via Helm (para Kubernetes) e Docker Compose. Você é responsável por adaptá-las para atender aos requisitos de segurança da sua organização.

Responsabilidade compartilhada

Manter este sistema seguro é uma responsabilidade compartilhada entre Anthropic e sua organização.

Anthropic é responsável por:

Garantir que apenas Anthropic possa acessar os túneis
Validar seu certificado CA antes de conectar ao seu gateway
Garantir que Claude envie solicitações apenas para túneis pertencentes à sua organização

Você é responsável por:

Seguir as orientações neste documento e qualquer orientação subsequente
Proteger o token do túnel e as chaves privadas TLS
Configurar seus servidores MCP para usar autenticação OAuth conforme descrito na especificação MCP
Restringir o acesso aos seus hosts de gateway e servidores MCP ao pessoal apropriado
Notificar Anthropic se você suspeitar que o sistema foi comprometido (consulte Respondendo a uma suspeita de violação)

⚠️ Risco de credencial. Se um invasor obtiver seu token de túnel e uma de suas chaves privadas TLS, ele poderia se passar por seu gateway e ler payloads de solicitação MCP, incluindo tokens OAuth. Proteja essas credenciais de acordo com os requisitos de segurança da sua organização — incluindo permissões de arquivo, criptografia em repouso e gerenciamento de segredos.

Pré-requisitos

Um alvo de implantação — um cluster Kubernetes (para Helm) ou uma VM com Docker e Docker Compose.
Um token de API Anthropic para a API Tunnels — gere um em claude.ai → Organization Settings → Connectors → Tunnels API. A configuração usa este token para provisionar o túnel e registrar seu certificado CA. O gateway não precisa dele em tempo de execução. Revogue-o após concluir a configuração.
Acesso à rede — conectividade de saída conforme a tabela abaixo.
Servidores MCP — um ou mais servidores MCP em execução na sua rede privada que o gateway possa acessar.

Requisitos de rede

Componente	Destino	Propósito
Configuração (uma única vez)	`api.anthropic.com:443` (porta 443)	Provisionamento de túnel
cloudflared	Borda Cloudflare, porta 7844 TCP/UDP (`198.41.192.0/19`, `2606:4700:a0::/44`)	Conexão de túnel
Gateway MCP	Seus servidores MCP	Tráfego upstream

Consulte a documentação do firewall de túnel da Cloudflare para obter a lista de IPs autorizada. Os usuários do Helm podem impor essa restrição de saída ativando o valor networkPolicy do gráfico.

Escolha seu método de implantação

Os Túneis MCP podem ser implantados via Helm (Kubernetes) ou Docker Compose. Escolha o método que se adequa à sua infraestrutura.

⎈ Helm / Kubernetes

Recomendado para a maioria dos clientes. Automatiza o provisionamento de túneis e renovação de certificados. Armazena credenciais como Secrets.

🐳 Docker Compose

Para implantações em host único ou VM.

Implantação Helm / Kubernetes

1. Busque os valores do gráfico

Baixe o arquivo de valores padrão. Inclui comentários explicando cada campo.

Shell

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 > values.yaml

2. Configure suas rotas

Edite values.yaml e adicione pelo menos uma rota em gateway.config.routes. Cada rota mapeia um prefixo de subdomínio para uma URL de servidor MCP upstream.

3. Revise os manifestos renderizados

Renderize o gráfico com um token de espaço reservado para inspecionar os recursos do Kubernetes antes de instalar. O gráfico requer api.token para renderizar, mas helm template não chama a API.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

Revise rendered.yaml de acordo com as práticas da sua organização para verificação de manifestos de terceiros.

4. Instale o gráfico

Armazene seu token de API em uma variável de ambiente e instale. Um namespace dedicado é recomendado para isolamento.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ Importante: Revogue o token de API após a conclusão da instalação. Passar o token via --set o mantém fora do seu arquivo de valores, mas o Helm ainda o registra no histórico de lançamentos (sh.helm.release.v1.* Secrets). Os Kubernetes Secrets não são criptografados em repouso por padrão, portanto o token permanece recuperável do cluster até que você o revogue.

5. Recupere seu domínio de túnel

O Job de configuração escreve o domínio do túnel em um Secret. Você precisará disso para configurar servidores MCP no Claude.

Shell

kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

Assim que o túnel estiver ativo e funcionando, conecte-se ao Claude.

Opcional: Ativar NetworkPolicy

Defina networkPolicy.enabled: true no seu arquivo de valores para restringir a saída do pod do túnel no nível da rede. Configure networkPolicy.mcpServers com seletores de rótulo de pod ou intervalos CIDR para seus servidores MCP upstream. A política já inclui regras de saída para o cloudflared alcançar a borda da Cloudflare. Seu CNI de cluster deve suportar NetworkPolicy—consulte o arquivo de valores para um exemplo.

Opcional: Configuração do gateway

Os campos em gateway.config.* são passados para o arquivo de configuração do gateway. Consulte Apêndice: Configuração do gateway para a lista completa. Os ajustes comuns incluem upstream.allowed_ips, log_level e upstream.tls para rotas https://. Para montar arquivos adicionais que a configuração referencia (como um pacote CA para upstream.tls.ca_file), use gateway.extraVolumes e gateway.extraVolumeMounts.

Atualizações

Sempre especifique --version em helm upgrade. Sem isso, o Helm extrai a versão mais recente do gráfico do registro, o que pode não ser o que você revisou.

Para alterações de configuração (rotas, réplicas, NetworkPolicy, etc.), nenhum token de API é necessário. O Job de configuração é ignorado em atualizações, a menos que você passe api.token:

Shell

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml

Para rotação de token de túnel, incremente tunnel.tokenVersion no seu arquivo de valores, gere um novo token de API e atualize:

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

Revogue o token de API após a conclusão da atualização.

Mantenha um arquivo de valores completo em vez de depender de --reuse-values. O Helm faz mesclagem profunda de campos de mapa, portanto deletar uma rota com --reuse-values falha silenciosamente.

Usando helm template com kubectl ou kustomize

Se você preferir renderizar manifestos e aplicá-los você mesmo (via kubectl apply ou sobreposições kustomize), use modo externo (setup.enabled: false). Provisione o túnel separadamente (consulte Apêndice: API de Túneis) e forneça as credenciais como Secrets pré-criados referenciados por external.tunnelTokenSecretName e external.serverCertSecretName. Se você emitir seus próprios certificados em vez de usar o binário de configuração, consulte Apêndice: Requisitos de certificado.

Implantação Docker Compose

1. Prepare o diretório de implantação

Shell

mkdir -p mcp-gateway/{config,tunnel-data}
cd mcp-gateway
sudo chown 65532:65532 tunnel-data

O chown permite que o contêiner (que é executado como UID 65532) escreva no diretório montado por bind.

2. Crie docker-compose.yaml

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Medidas de segurança: execução sem privilégios (UID 65532), sistema de arquivos somente leitura, sem escalação de privilégios, todas as capacidades do Linux removidas, fixação de imagem por digest SHA256.

3. Provisionar o túnel

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

O comando de configuração cria um túnel via a API de Túneis, gera um certificado de CA e servidor, registra a CA com a Anthropic e escreve todas as saídas em ./tunnel-data/.

Recupere seu domínio de túnel para a próxima etapa:

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ Importante: Revogue o token de API antes de prosseguir.

4. Configurar o gateway

Crie config/mcp-gateway.yaml:

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

Consulte Apêndice: Configuração do gateway para todos os campos disponíveis.

Crie config/cloudflared-config.yaml:

YAML

ingress:
  - service: http://mcp-gateway:8080

5. Implantar

Shell

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d
docker compose logs -f

Estrutura de diretórios:

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

Considere mover a chave privada da CA e o token de túnel para armazenamento seguro.

Para implantações multi-VM: copie o diretório mcp-gateway/ para cada host. O mesmo token de túnel e certificados funcionam em todas as réplicas.

Quando o túnel estiver ativo e funcionando, conecte-se ao Claude.

Renovação de certificado (Compose)

O certificado do servidor tem validade de 90 dias. Renove antes do vencimento:

Shell

docker compose run --rm setup renew-cert --output=dir:/data

O gateway consulta o arquivo de certificado a cada 30 segundos e o recarrega automaticamente quando muda. Consulte Apêndice: Referência da CLI de configuração para sinalizadores que tornam este comando seguro para executar em um cronograma.

Rotação de token de túnel (Compose)

Edite docker-compose.yaml para incrementar --token-version, depois execute a configuração novamente com um novo token de API:

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d cloudflared

Revogue o token de API após a conclusão da rotação.

Conectar ao Claude

Quando o túnel estiver em execução, registre seus servidores MCP no Claude para que fiquem disponíveis aos usuários.

1. Adicionar servidores MCP

Um administrador da organização navega para Configurações da Organização → Conectores → Adicionar → Personalizado → Web em claude.ai.

Digite cada servidor MCP usando seu nome de host de túnel. Por exemplo, docs.abcd1234.tunnel.anthropic.com. O prefixo do subdomínio corresponde à chave de rota da sua configuração de gateway.

2. Usuários se conectam

Usuários individuais navegam para Configurações → Conectores e clicam em Conectar para cada servidor MCP que desejam usar.

Adicionar mais servidores depois? Adicione uma nova rota à sua configuração, aplique a alteração (helm upgrade ou docker compose restart mcp-gateway) e registre o novo nome de host no Claude. Nenhuma alteração de certificado ou cloudflared necessária. O certificado curinga cobre todos os subdomínios.

Práticas recomendadas de segurança

Exija OAuth em seus servidores MCP. O túnel e as camadas TLS protegem o transporte, mas se forem comprometidos, o OAuth na camada de aplicação ainda impede a invocação de ferramentas não autorizada. Configure cada servidor MCP para exigir autenticação OAuth conforme descrito na especificação MCP.
Ative SSO para sua organização claude.ai. Os tokens de túnel são gerados a partir do Console claude.ai. Com SSO aplicado, os controles de sessão do seu provedor de identidade governam as sessões de administrador.
Restrinja allowed_ips. Use os menores intervalos CIDR que cobrem seus servidores MCP.
Monitore logs. Configure alertas para avisos, erros e padrões incomuns.
Rotacione credenciais. Rotacione certificados regularmente ou imediatamente se houver suspeita de comprometimento.
Mantenha imagens atualizadas. Aplique atualizações de gateway prontamente. Fixe imagens por resumo SHA256.
Limite o acesso à rede. O gateway e cloudflared devem ter apenas o acesso à rede necessário.
Limite o escopo do servidor MCP. Os servidores MCP devem expor apenas a funcionalidade necessária.
Proteja credenciais em repouso. Aplique permissões de arquivo apropriadas, criptografia em repouso e gerenciamento de segredos ao diretório tunnel-data/ (Compose) ou ao Secret de credenciais (Helm).

Respondendo a uma possível violação

Se você suspeitar que suas credenciais de túnel, chaves TLS ou algum outro aspecto do sistema foi comprometido:

Interrompa a implantação imediatamente (helm uninstall ou docker compose down --timeout 0)
Remova servidores MCP do Claude (Configurações da Organização → Conectores)
Archive o túnel via a API (consulte Teardown, etapa 3)
Entre em contato com a Anthropic para que possam investigar
Rotacione credenciais — provisione um novo túnel, rotacione tokens OAuth em seus servidores MCP
Revise os registos antes de restaurar o serviço

Resolução de problemas

Falhas de validação de IP

"IP validation failed" nos registos do gateway significa que o upstream foi resolvido para um IP fora de allowed_ips. Verifique o IP resolvido:

Shell

dig +short docs-mcp.internal

Se o IP for legítimo, atualize allowed_ips na configuração do seu gateway para incluir o intervalo CIDR correto.

Túnel não se conecta

Verifique os registos do cloudflared para erros. Causas comuns:

Token de túnel inválido
Firewall bloqueando a porta 7844 TCP/UDP de saída para a borda do Cloudflare

Verifique a conectividade de saída para os intervalos de IP do Cloudflare: 198.41.192.0/19 e 2606:4700:a0::/44.

Avisos de tamanho de buffer UDP

O cloudflared pode registar failed to sufficiently increase receive buffer size. Este é um problema de ajuste de transporte QUIC — consulte a documentação de buffer UDP do quic-go para ajustar.

Erros de certificado

Se o handshake TLS falhar, verifique se:

O certificado do servidor não expirou (validade de 90 dias)
O SAN do certificado corresponde a *.<tunnel-domain>
O certificado da AC está registado na Anthropic através da API
Para Compose, os ficheiros de certificado são legíveis pelo UID 65532

Encaminhamento de OAuth através do túnel (servidor de autenticação atrás da lista de permissões de IP)

Problema: O seu servidor de autenticação está atrás de uma lista de permissões de IP de origem. O backend do Claude precisa de o alcançar para descoberta OAuth, registo de cliente e troca de tokens, mas preferiria não colocar na lista de permissões os intervalos de IP de saída da Anthropic.

Solução: configuração de ponto final dividido. Encaminhe as chamadas OAuth de backend para backend através do túnel. Mantenha o ponto final /authorize voltado para o navegador no seu nome de anfitrião existente na lista de permissões. Isto funciona porque o Claude lê o authorization_endpoint dos seus metadados de descoberta e redireciona o navegador do utilizador para lá. Não precisa de alcançar esse URL em si.

Passo 1: Adicione uma rota de gateway para o seu servidor de autenticação

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

Passo 2: Sirva metadados de descoberta de ponto final dividido

O /.well-known/oauth-authorization-server do seu servidor de autenticação deve devolver:

JSON

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

Apenas authorization_endpoint aponta para o seu nome de anfitrião existente. Tudo o resto utiliza o URL do túnel.

Passo 3: Aponte o seu servidor MCP para o emissor do túnel

O /.well-known/oauth-protected-resource do seu servidor MCP:

JSON

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

Desmontagem

Como desativar um túnel quando já não é necessário.

1. Obtenha o ID do Túnel

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. Pare a implementação

Helm: helm uninstall mcp-tunnel -n mcp-tunnel (nota: o Secret de credenciais foi criado pelo Job de configuração, não pelo Helm, portanto sobrevive à desinstalação)
Compose: docker compose down

3. Archive o túnel

Gere um token de API novo primeiro e revogue-o quando terminar.

Shell

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. Remova as credenciais armazenadas

Helm: kubectl delete secret mcp-tunnel -n mcp-tunnel
Compose: sudo rm -rf tunnel-data

Obter ajuda

Contacte a sua equipa de conta da Anthropic para obter assistência.

Apêndice: Configuração do gateway

O gateway lê a sua configuração a partir de um ficheiro YAML. No Docker Compose, escreve este ficheiro diretamente como config/mcp-gateway.yaml. No Helm, defina estes campos em gateway.config.* no seu ficheiro de valores—o gráfico gere listen_addr, tls e tunnel_domain para si.

Campo	Descrição	Padrão
`listen_addr`	Endereço e porta para escutar	Obrigatório
`log_level`	Verbosidade do registro: `debug`, `info`, `warn`, `error`	`info`
`shutdown_timeout`	Tempo de espera para solicitações em andamento durante desligamento gracioso	`30s`
`tunnel_domain`	Domínio base para resolução de rota com prefixo	Nenhum
`tls.cert_file`	Caminho para o certificado TLS	Obrigatório
`tls.key_file`	Caminho para a chave privada TLS	Obrigatório
`routes`	Mapeamento de nome de host (ou prefixo) para URL upstream	Obrigatório
`upstream.allowed_ips`	Intervalos CIDR aos quais o gateway pode se conectar	Intervalos privados RFC 1918
`upstream.disable_ip_validation`	Desabilitar validação de IP completamente	`false`
`upstream.tls.ca_file`	Pacote CA para validar TLS upstream	Nenhum
`upstream.tls.include_system_cas`	Confiar no pacote CA do sistema para TLS upstream	`false`

Para rotas https://, defina pelo menos uma de upstream.tls.ca_file ou upstream.tls.include_system_cas.

Apêndice: API de Túneis

Para fluxos de trabalho de provisionamento personalizados, você pode chamar a API de Túneis diretamente. Todas as solicitações exigem estes cabeçalhos:

Shell

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

Criar um túnel:

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

Listar túneis:

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Registrar um certificado CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

Consulte Apêndice: Requisitos de certificado para saber o que os certificados CA e servidor devem conter.

Listar certificados CA:

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Revogar um certificado CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Revelar o token do túnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Girar o token do túnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Arquivar um túnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Apêndice: Requisitos de certificado

Se você usar o binário de configuração (setup init / setup renew-cert), ele gera certificados compatíveis automaticamente e você pode pular esta seção. Esses requisitos se aplicam se você emitir certificados através de sua própria PKI.

Certificado CA — carregado via POST /v1/tunnels/{id}/certificates. Um túnel contém no máximo dois certificados CA ativos por vez, permitindo rotação sem tempo de inatividade.

Codificado em PEM, certificado único, no máximo 8 KB
Extensão BasicConstraints com CA:TRUE, marcada como crítica
Extensão SubjectKeyIdentifier presente
KeyUsage inclui keyCertSign
Dentro do período de validade
RSA 2048-bit ou maior, ou ECDSA P-256 ou maior; assinatura SHA-256 ou mais forte

Certificado do servidor — apresentado pelo gateway durante o handshake TLS interno. Não enviado para Anthropic.

Assinado diretamente por uma CA registrada no túnel
Extensão AuthorityKeyIdentifier presente, correspondendo ao SubjectKeyIdentifier da CA
SAN inclui um nome DNS correspondendo a <route>.<tunnel-domain> (um wildcard *.<tunnel-domain> cobre todas as rotas)
Se uma extensão ExtendedKeyUsage estiver presente, inclui serverAuth
Dentro do período de validade
RSA 2048-bit ou maior, ou ECDSA P-256 ou maior; assinatura SHA-256 ou mais forte

Referência: o binário de configuração gera uma CA ECDSA P-256 (validade de 5 anos) e um certificado de servidor RSA 4096-bit com SAN wildcard (validade de 90 dias).

Apêndice: Referência da CLI de configuração

O binário setup é executado dentro do contêiner do gateway via docker compose run --rm setup <subcommand> (Compose) ou como um hook Helm e CronJob (Kubernetes).

setup init — cria um túnel via a API de Túneis, gera uma CA e certificado de servidor, registra a CA e escreve todas as saídas.

Sinalizador	Descrição	Padrão
`--api-url`	URL base da API Anthropic. Também lido de `API_URL`.	obrigatório
`--api-token`	Token de API com escopo de túnel. Também lido de `API_TOKEN`.	obrigatório
`--output`	Destino de saída: `dir:/path` ou `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--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 dispara rotação de token de túnel	nenhum

setup renew-cert — emite um novo certificado de servidor assinado pela CA armazenada. Nenhuma chamada de API necessária.

Sinalizador	Descrição	Padrão
`--output`	Destino de saída: `dir:/path` ou `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--cert-duration`	Período de validade do novo certificado	`2160h` (90 dias)
`--renew-before`	Pule se o certificado existente tiver mais tempo até expiração do que isso	`0` (sempre renovar)

Definir --renew-before=720h torna o comando uma operação nula quando mais de 30 dias permanecem, adequado para executar em um cronograma.