Guida rapida ai tunnel MCP

Connetti Claude a un server MCP privato utilizzando un deployment locale con Docker Compose.

Questa guida rapida ti porta da zero fino a Claude che chiama un server MCP privato attraverso un tunnel. Utilizza Docker Compose con provisioning manuale delle credenziali, che è il percorso più breve per i test locali. Per i deployment di produzione, consulta Deploy con Helm o Deploy con Docker Compose.

Cosa costruirai

Uno stack del tunnel a due container (il proxy e cloudflared) più un server MCP di esempio in esecuzione accanto ad esso. Quando tutto è in esecuzione, il server di esempio è raggiungibile da Claude all'indirizzo https://echo.<your-tunnel-domain>/mcp anche se nulla è in ascolto su una porta pubblica.

Cosa ti serve

Docker e Docker Compose su una macchina con accesso internet in uscita.
Un ruolo nella Claude Console che possa gestire i tunnel MCP. Consulta i prerequisiti della guida alla Console.
OpenSSL 1.1.1 o successivo. Preinstallato su macOS e sulla maggior parte delle distribuzioni Linux; su Windows, installalo separatamente (il binario openssl deve essere nel tuo PATH).

1
Crea un tunnel
Nella barra laterale della Claude Console, vai su Manage > MCP tunnels e fai clic su New tunnel. Assegnagli un nome. Lascia disattivato Set up programmatic access; questa guida rapida utilizza il provisioning manuale delle credenziali.
Dopo la creazione, apri il tunnel. Copia due valori dalla sezione Connection:
- Domain (ha un aspetto simile a abcd1234.tunnel.anthropic.com)
- Token (fai clic sull'icona a forma di occhio, poi copia)

Configura la directory di deployment

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

Genera una CA e un certificato server

Il proxy termina il TLS interno ("inner TLS") utilizzando un certificato firmato da una CA che controlli tu. Genera entrambi:

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

Tornando nella Console, nella pagina di dettaglio del tunnel, fai clic su Add certificate e carica data/ca.crt (oppure incolla il suo contenuto). Lo stato del tunnel passa a Active.

Scrivi il server MCP di esempio

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

Scrivi la configurazione del proxy e il file 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
Avvialo
docker compose up -d docker compose logs mcp-proxy | grep "route configured" docker compose logs cloudflared | grep "Registered tunnel connection"
Dovresti vedere una riga route configured per echo e quattro righe Registered tunnel connection. I container impiegano alcuni secondi per avviarsi; riesegui i comandi di log se restituiscono un output vuoto.
Chiamalo da Claude
Nella Console, vai su Managed Agents > Sessions e crea una sessione. Nel selettore dell'agente scegli Create new agent, assegna un nome all'agente e mantieni il modello precompilato. Fai clic su + MCP Server, seleziona il tuo tunnel, imposta Subdomain su echo e Path su mcp. Poi chiedi:

Use the hello tool to greet tunnel.

Dovresti vedere una chiamata a uno strumento seguita dal suo risultato.

Passaggi successivi

Il tunnel è verificato end-to-end. Per sostituirlo con il tuo server MCP, aggiungilo a docker-compose.yaml (oppure eseguilo sulla stessa rete Docker), aggiungi una route per esso in config/mcp-proxy.yaml, quindi riavvia il proxy (docker compose restart mcp-proxy).

Per i deployment di produzione:

Deploy con Docker Compose

Deployment rafforzato su singolo host, con o senza accesso programmatico.

Deploy con Helm

Deployment Kubernetes con gestione automatica delle credenziali.

Cosa costruirai

Cosa ti serve

Crea un tunnel