Implantar túneis MCP com Docker Compose

Este guia implanta a tunnel stack (stack de túnel) como contêineres reforçados em um único host. A mesma configuração pode ser replicada em vários hosts para disponibilidade.

Antes de começar

Você precisa de:

• Um túnel criado no Console. Siga Criar um túnel e anote o ID do túnel (tnl_...).
• Uma forma de o host se autenticar na Tunnels API.
  • Acesso programático (recomendado). Ative Set up programmatic access ao criar o túnel para que o componente de setup possa se autenticar por meio de Workload Identity Federation. Anote o ID da regra de federação (fdrl_...) e o ID da sua organização.
  • Manual. Pule o acesso programático. Você vai obter o token do túnel no Console, gerar uma CA e um certificado de servidor por conta própria e registrar a CA no Console.
• Um host com Docker e Docker Compose instalados. O fluxo manual também requer openssl (1.1.1 ou mais recente).
• Conectividade de rede de saída do host para api.anthropic.com (443 TCP) e para o tunnel edge (7844 TCP e UDP). Consulte os requisitos de rede completos.
• Um ou mais servidores MCP em execução e acessíveis a partir do host nos endereços que você vai configurar em routes. Se você ainda não tem um, use o servidor de exemplo.

Opcional: Usar um servidor MCP de exemplo

Se você não tem um servidor MCP disponível para testes, use este servidor mínimo:

mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


@mcp.tool()
def hello(name: str = "world") -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")
EOF

As etapas de instalação a seguir fazem cd para mcp-tunnel/ e indicam onde adicionar o serviço e a rota correspondentes.

Instalar

Este guia fornece uma abordagem de referência usando Docker Compose. Você é responsável por adaptá-la para atender aos requisitos de segurança da sua organização.

O arquivo compose lê TUNNEL_TOKEN do ambiente do host sem valor padrão, então o export deve ser repetido em cada novo shell e após uma reinicialização.

Para uma implantação em várias VMs, copie o diretório mcp-tunnel/ para cada host, defina TUNNEL_TOKEN e execute docker compose up -d. No fluxo programático, TUNNEL_TOKEN é $(sudo cat data/tunnel-token); no fluxo manual, é o valor que você copiou do Console. O mesmo token de túnel e certificados funcionam em todas as réplicas.

Verificar a implantação

Verifique de ponta a ponta chamando um servidor MCP upstream do lado da Anthropic: consulte Usar os servidores MCP tunelados. Com o servidor MCP de exemplo, a URL roteada é https://echo.<your-tunnel-domain>/mcp. Se a verificação falhar, consulte Solução de problemas.

Atualizações

Execute os comandos desta seção de dentro do diretório de implantação mcp-tunnel/.

Rotacionar o token do túnel

Com acesso programático, incremente --token-version no comando do serviço setup, defina os identificadores de Workload Identity Federation, gere um novo JWT OIDC e execute novamente o componente de setup:

# Edite docker-compose.yaml: incremente o inteiro no argumento --token-version
# do serviço setup (por exemplo, de --token-version=1 para
# --token-version=2). O binário setup recusa a rotação quando o valor
# não foi alterado.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # se sua regra tiver escopo de workspace
# Gere novamente ANTHROPIC_IDENTITY_TOKEN conforme o guia do provedor WIF para seu
# ambiente (ele terá expirado desde a instalação).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

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

O argumento --token-version é editado em docker-compose.yaml em vez de ser passado na linha de comando para que o novo valor persista em execuções futuras do componente de setup. O componente de setup se autentica com Workload Identity Federation; não há token de API a revogar.

Sem acesso programático, clique em Rotate token na página de detalhes do túnel no Console, depois atualize a variável de ambiente TUNNEL_TOKEN em cada host e reinicie o cloudflared (docker compose up -d cloudflared).

Renovação de certificado

Você é responsável por monitorar a expiração e renovar o certificado do servidor antes que ele expire.

Com acesso programático:

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

Os argumentos da CLI substituem o command do serviço setup (os argumentos de init), mas mantêm seu entrypoint, então isso executa /setup renew-cert --output=dir:/data.

Sem acesso programático, assine um novo certificado de servidor com sua CA existente (a CA registrada no Console não muda) e substitua data/tls.crt. Defina TUNNEL_DOMAIN primeiro se estiver executando isso a partir de um novo shell.

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 \
  -extfile data/tls.ext

Em ambos os fluxos, o proxy monitora tls.cert_file e o recarrega automaticamente, então nenhuma reinicialização é necessária.

Próximos passos