Início rápido de túneis MCP

Conecte o Claude a um servidor MCP privado usando uma implantação local com Docker Compose.

Este início rápido leva você do zero até o Claude chamando um servidor MCP privado através de um túnel. Ele usa Docker Compose com provisionamento manual de credenciais, que é o caminho mais curto para testes locais. Para implantações em produção, consulte Implantar com Helm ou Implantar com Docker Compose.

O que você vai construir

Uma "tunnel stack" (pilha de túnel) de dois contêineres (o proxy e o cloudflared) mais um servidor MCP de exemplo executando ao lado dela. Quando tudo estiver em execução, o servidor de exemplo estará acessível a partir do Claude em https://echo.<your-tunnel-domain>/mcp, mesmo que nada esteja escutando em uma porta pública.

O que você precisa

Docker e Docker Compose em uma máquina com acesso de saída à internet.
Uma função no Claude Console que possa gerenciar túneis MCP. Consulte os pré-requisitos do guia do Console.
OpenSSL 1.1.1 ou posterior. Pré-instalado no macOS e na maioria das distribuições Linux; no Windows, instale-o separadamente (o binário openssl deve estar no seu PATH).

1
Crie um túnel
Na barra lateral do Claude Console, vá para Manage > MCP tunnels e clique em New tunnel. Dê um nome a ele. Deixe Set up programmatic access desativado; este início rápido usa provisionamento manual de credenciais.
Depois de criado, abra o túnel. Copie dois valores da seção Connection:
- Domain (parecido com abcd1234.tunnel.anthropic.com)
- Token (clique no ícone de olho e depois copie)

Configure o diretório de implantação

mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE   # from step 1
export TUNNEL_TOKEN='eyJ...'            # from step 1

Gere uma CA e um certificado de servidor

O proxy encerra o "inner TLS" (TLS interno) usando um certificado assinado por uma CA que você controla. Gere ambos:

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout data/ca.key -out data/ca.crt \
  -days 3650 -subj "/CN=mcp-tunnel-ca" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -addext "subjectKeyIdentifier=hash"

cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF

openssl req -newkey rsa:2048 -nodes \
  -keyout 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

chmod 644 data/tls.key

De volta ao Console, na página de detalhes do túnel, clique em Add certificate e faça upload de data/ca.crt (ou cole seu conteúdo). O status do túnel muda para Active.

Escreva o servidor MCP de exemplo

cat > 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

Escreva a configuração do proxy e o arquivo compose

cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key
routes:
  echo: http://hello-mcp:9000
EOF

cat > docker-compose.yaml <<'EOF'
services:
  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    network_mode: "service:mcp-proxy"
    restart: unless-stopped

  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
EOF

6
Inicie
docker compose up -d docker compose logs mcp-proxy | grep "route configured" docker compose logs cloudflared | grep "Registered tunnel connection"
Você deve ver uma linha route configured para echo e quatro linhas Registered tunnel connection. Os contêineres levam alguns segundos para iniciar; execute novamente os comandos de log se eles retornarem vazios.
Chame-o a partir do Claude
No Console, vá para Managed Agents > Sessions e crie uma sessão. No seletor de agentes, escolha Create new agent, dê um nome ao agente e mantenha o modelo pré-preenchido. Clique em + MCP Server, selecione seu túnel, defina Subdomain como echo e Path como mcp. Em seguida, peça:

Use the hello tool to greet tunnel.

Você deve ver uma chamada de ferramenta seguida de seu resultado.

Próximos passos

O túnel está verificado de ponta a ponta. Para substituir pelo seu próprio servidor MCP, adicione-o ao docker-compose.yaml (ou execute-o na mesma rede Docker), adicione uma rota para ele em config/mcp-proxy.yaml e, em seguida, reinicie o proxy (docker compose restart mcp-proxy).

Para implantações em produção:

Implantar com Docker Compose

Implantação reforçada em host único, com ou sem acesso programático.

Implantar com Helm

Implantação em Kubernetes com gerenciamento automático de credenciais.

O que você vai construir

O que você precisa

Crie um túnel