使用 Docker Compose 部署 MCP 通道

本指南將通道堆疊以強化容器的形式部署在單一主機上。相同的配置可以複製到多個主機以提高可用性。

開始之前

您需要：

• 在 Console 中建立的通道。 請依照建立通道的步驟操作，並記錄通道 ID（tnl_...）。
• 主機向 Tunnels API 進行驗證的方式。
  • 程式化存取（建議）。 在建立通道時開啟 Set up programmatic access，以便設定元件可以透過 Workload Identity Federation 進行驗證。記錄聯合規則 ID（fdrl_...）和您的組織 ID。
  • 手動。 略過程式化存取。您將從 Console 取得通道權杖、自行產生 CA 和伺服器憑證，並在 Console 中註冊 CA。
• 已安裝 Docker 和 Docker Compose 的主機。 手動流程還需要 openssl（1.1.1 或更新版本）。
• 從主機到 api.anthropic.com（443 TCP）和通道邊緣（7844 TCP 和 UDP）的對外網路連線。請參閱完整的網路需求。
• 一個或多個 MCP 伺服器正在執行，並且可以從主機透過您將在 routes 下配置的位址存取。如果您還沒有伺服器，請使用範例伺服器。

選用：使用範例 MCP 伺服器

如果您沒有可用於測試的 MCP 伺服器，請使用這個最小化的伺服器：

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

以下安裝步驟會 cd 進入 mcp-tunnel/，並說明在何處新增對應的服務和路由。

安裝

本指南提供一種使用 Docker Compose 的參考方法。您有責任調整此方法以符合您組織的安全需求。

compose 檔案從主機環境讀取 TUNNEL_TOKEN 且沒有預設值，因此必須在每個新的 shell 中以及重新開機後重複執行匯出。

對於多虛擬機器部署，請將 mcp-tunnel/ 目錄複製到每個主機、設定 TUNNEL_TOKEN，然後執行 docker compose up -d。在程式化流程中，TUNNEL_TOKEN 是 $(sudo cat data/tunnel-token)；在手動流程中，它是您從 Console 複製的值。相同的通道權杖和憑證適用於所有副本。

驗證部署

透過從 Anthropic 端呼叫上游 MCP 伺服器來進行端對端驗證：請參閱使用通道化的 MCP 伺服器。使用範例 MCP 伺服器時，路由的 URL 為 https://echo.<your-tunnel-domain>/mcp。如果驗證失敗，請參閱疑難排解。

升級

請在 mcp-tunnel/ 部署目錄內執行本節中的命令。

輪替通道權杖

使用程式化存取時，在 setup 服務命令中遞增 --token-version、設定 Workload Identity Federation 識別碼、產生新的 OIDC JWT，然後重新執行設定元件：

# 編輯 docker-compose.yaml：遞增 setup 服務的 --token-version 引數中的整數
# （例如，將 --token-version=1 改為 --token-version=2）。
# 當該值未變更時，setup 二進位檔會拒絕執行輪替。
# 

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # 若您的規則限定於工作區範圍
# 依照您環境適用的 WIF 提供者指南重新產生 ANTHROPIC_IDENTITY_TOKEN
# （自安裝以來該權杖應已過期）。
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

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

--token-version 引數是在 docker-compose.yaml 中編輯而非在命令列上傳遞，以便新值在未來執行設定元件時持續生效。設定元件使用 Workload Identity Federation 進行驗證；沒有需要撤銷的 API 權杖。

不使用程式化存取時，請在 Console 的通道詳細資訊頁面上點擊 Rotate token，然後在每個主機上更新 TUNNEL_TOKEN 環境變數並重新啟動 cloudflared（docker compose up -d cloudflared）。

憑證更新

您有責任監控到期時間，並在伺服器憑證到期前進行更新。

使用程式化存取時：

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

CLI 引數會取代 setup 服務的 command（即 init 引數），但保留其 entrypoint，因此這會執行 /setup renew-cert --output=dir:/data。

不使用程式化存取時，請使用您現有的 CA 簽署新的伺服器憑證（在 Console 中註冊的 CA 不會變更），並替換 data/tls.crt。如果您是從新的 shell 執行此操作，請先設定 TUNNEL_DOMAIN。

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

在任一流程中，代理都會輪詢 tls.cert_file 並自動重新載入，因此不需要重新啟動。

後續步驟