Развёртывание MCP-туннелей с помощью Docker Compose

В этом руководстве описывается развёртывание стека туннелей в виде защищённых контейнеров на одном хосте. Ту же конфигурацию можно реплицировать на несколько хостов для обеспечения доступности.

Перед началом работы

Вам потребуется:

• Туннель, созданный в Console. Следуйте инструкциям в разделе Создание туннеля и запишите идентификатор туннеля (tnl_...).
• Способ аутентификации хоста в Tunnels API.
  • Программный доступ (рекомендуется). Включите опцию Set up programmatic access при создании туннеля, чтобы компонент настройки мог аутентифицироваться через Workload Identity Federation. Запишите идентификатор правила федерации (fdrl_...) и идентификатор вашей организации.
  • Вручную. Пропустите программный доступ. Вы получите токен туннеля из Console, самостоятельно сгенерируете CA и серверный сертификат, а затем зарегистрируете CA в Console.
• Хост с установленными 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 из окружения хоста без значения по умолчанию, поэтому экспорт необходимо повторять в каждой новой оболочке и после перезагрузки.

Для развёртывания на нескольких виртуальных машинах скопируйте каталог mcp-tunnel/ на каждый хост, задайте TUNNEL_TOKEN и выполните docker compose up -d. В варианте с программным доступом TUNNEL_TOKEN — это $(sudo cat data/tunnel-token); в ручном варианте — значение, которое вы скопировали из Console. Один и тот же токен туннеля и сертификаты работают на всех репликах.

Проверка развёртывания

Выполните сквозную проверку, вызвав вышестоящий MCP-сервер со стороны Anthropic: см. раздел Использование туннелированных MCP-серверов. При использовании примера MCP-сервера маршрутизируемый URL — https://echo.<your-tunnel-domain>/mcp. Если проверка не проходит, см. раздел Устранение неполадок.

Обновления

Выполняйте команды из этого раздела внутри каталога развёртывания mcp-tunnel/.

Ротация токена туннеля

При программном доступе увеличьте --token-version в команде сервиса setup, задайте идентификаторы Workload Identity Federation, выпустите новый OIDC JWT и повторно запустите компонент настройки:

# Отредактируйте docker-compose.yaml: увеличьте целое число в аргументе
# --token-version сервиса setup (например, с --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_...   # если правило ограничено рабочим пространством
# Заново сгенерируйте ANTHROPIC_IDENTITY_TOKEN согласно руководству по провайдеру WIF
# для вашей среды (с момента установки срок его действия истёк).
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-токен не требуется.

Без программного доступа нажмите Rotate token на странице сведений о туннеле в Console, затем обновите переменную окружения TUNNEL_TOKEN на каждом хосте и перезапустите cloudflared (docker compose up -d cloudflared).

Обновление сертификата

Вы несёте ответственность за отслеживание срока действия и обновление серверного сертификата до его истечения.

С программным доступом:

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

Аргументы CLI заменяют command сервиса setup (аргументы init), но сохраняют его entrypoint, поэтому выполняется /setup renew-cert --output=dir:/data.

Без программного доступа подпишите новый серверный сертификат вашим существующим CA (CA, зарегистрированный в Console, не меняется) и замените data/tls.crt. Сначала задайте 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 и перезагружает его автоматически, поэтому перезапуск не требуется.

Дальнейшие шаги