TatNet — apps and cloud infrastructure

tatnet-mcp

TatNet MCP サーバー：Claude（claude.ai、Desktop、Code）、ChatGPT、および任意の Model Context Protocol クライアントからプラットフォームを管理します。 「サイトを作ってTatNetに公開して」は、deploy_files を呼び出します。

クイックスタート / English

TatNet MCP は、AI との会話から静的サイトや SSR サイトをデプロイし、TatNet というロシアのクラウドプラットフォーム上で Git／Docker アプリ、ビルド、ログ、環境変数、ドメインを管理するためのリモートサーバーです。トランスポート：Streamable HTTP。 エンドポイント：https://mcp.tatnet.cloud/mcp。認証：OAuth またはスコープ付き API キー。

claude mcp add --transport http tatnet https://mcp.tatnet.cloud/mcp

OAuth で接続し、プロジェクトと書き込みアクセスを選択してから、アシスタントにウェブサイトの公開を依頼します。status=success と deploy_state=live の両方が確認されたら、デプロイ完了です。バックエンドアプリには Git または Docker イメージが必要です。 追加のツールでは、マネージド Kafka、VM の作成とバックアップポリシー、リージョン別 S3 の検出とバケット作成、VPC の表示名変更、公開 AI モデルカタログを利用できます。list_vm_plans では、VM プランの UUID、仕様、料金を確認できます。 VM イメージ／クラスターの検出、その他の VM 操作、データベース、DNS ゾーン、S3 認証情報、オブジェクト操作には CLI／API を使用してください。 アプリの削除と残高のチャージは MCP から利用できません。

• MCP の概要と接続ドキュメント。
• Claude Code から公開する。
• 失敗したビルドを診断する。
• CI から CLI でデプロイする。

アーキテクチャ

• 公開 /v1 の薄いラッパーです。 独自のデータベース、権限、ビジネスロジックはありません。 管理ツールは、SDK tatnet-go または呼び出し元と同じ認証を使用する共通 JSON トランスポートを介して api.tatnet.ru/v1 を呼び出します。ai_models はキーを渡さずに、公開 AI カタログを個別に読み取ります。権限は、CLI や SDK と同様に、キーのポリシーと作成者の現在のロールの積集合で決まります。 /v1 にない機能は、ここにもありません。まず /v1 にエンドポイントが追加され、その後にツールが追加されます。
• ステートレスな Streamable HTTP（/mcp）を使用し、公式の modelcontextprotocol/go-sdk を採用しています。レプリカは相互に置き換え可能で、クライアントのロールアウトによって接続が切れることはありません。
• 認証は OAuth または /v1 キーです。 ヘッダーフィールドのないクライアントは、自動で登録されます（DCR）。ユーザーは TatNet にログインし、同意画面でアカウント、プロジェクト、アクセスレベルを選択します。接続は API キーの横にあるパネルに表示され、同じ場所で取り消せます。トークンは MCP 専用に発行され、サーバーの外には送信されません。/v1 へのリクエストは、サーバーが接続の名義で行います。ヘッダーを渡せるクライアントは、キー Authorization: Bearer tn_live_… でも接続できます。どちらの場合も、権限は API が呼び出しのたびに判定します。接続またはキーのポリシーとユーザーのロールが交差して適用されます。

ツール

Инструмент	Тип	Что делает
whoami	чтение	аккаунт и проекты, ограничен ли ключ
get_balance	чтение	баланс: доступно сейчас, деньги, бонусы и открыты ли они. Только владельцу: ключу нужно billing:read, OAuth-подключению — выдача на весь аккаунт. Пополнения нет — оно в панели
list_vm_plans	чтение	каталог тарифов через /v1/vms/plans: UUID для vm_plan_id, CPU, память в МиБ, диски, семейство CPU и цены в рублях. cluster_id фильтрует совместимое оборудование, role — назначение (по умолчанию vm). Требуется vm:read
list_apps, get_app	чтение	аппы; у get_app — адрес, домены, последняя сборка
create_app	запись	апп из git или Docker-образа; идемпотентен по имени
set_app_branch	запись	смена ветки Git-приложения для будущих сборок и автодеплоя; требует app:update, текущую версию не выкатывает — затем вызвать deploy_app
deploy_files	запись	выкладка САЙТА (статика, SSR) из файлов разговора: пакует tar.gz → /v1 …/deployments; создаёт апп при первом вызове, повтор с тем же именем — тот же апп. ⚠ Бэкенд платформа из папки пока не собирает — отказ до загрузки
deploy_app	запись	новая сборка git/docker-аппа; у docker-аппа с image — сначала переключает его на новый образ (PATCH docker_image), потом собирает
get_build	чтение	статус с ожиданием до 45 с; при провале — хвост лога
get_build_logs, list_builds	чтение	лог и история сборок
list_env, set_env	чтение/запись	переменные; значения секретов не отдаются никогда
delete_env, remove_domain	удаление	помечены destructiveHint; подтверждение зависит от клиента
list_domains, add_domain	чтение/запись	домены и инструкция по DNS
kafka_regions, kafka_list_clusters, kafka_get_cluster	чтение	Kafka Dev/HA, ставки часа, управление и прогноз за 730 часов
kafka_create_cluster	запись	выделенный платный Kafka-кластер; пароль выдаётся один раз
kafka_resume_cluster	запись	оплатить час остановленных подписок и запустить узлы; оплаченные подписки не списываются повторно
kafka_update_allowlist, kafka_delete_cluster	изменение/удаление	публичный доступ или удаление кластера вместе с данными
kafka_canary_node_power	изменение	закрытая проверка start/stop узла для настроенного canary-аккаунта; VM продолжает тарифицироваться
ai_models	чтение	публичный каталог chat/image/video; без генерации и расходов
create_load_balancer, get_load_balancer	запись/чтение	создать платный LB и проверить статус; floating_ip_id закрепляет свободный IP аккаунта, сохраняющийся после удаления LB
rename_vpc	запись	изменить отображаемое имя VPC
enable_nat_gateway	изменение	включить NAT для VPC: fip_id выбирает свободный адрес аккаунта в том же регионе; без него выделяется новый. Адрес и NAT тарифицируются; подключение асинхронное
disable_nat_gateway	изменение	выключить NAT-шлюз VPC; retain_ip=true сохраняет IP за аккаунтом с продолжением тарификации. Снятие NAT асинхронно; перед повторным использованием адреса нужно дождаться available через API/CLI. expected_fip_id защищает от выключения заменённого шлюза
list_s3_regions, get_s3_connection_info	чтение	регионы, endpoints и примеры подключения S3
create_s3_bucket	запись	создать бакет, приватный по умолчанию
create_vm	запись	создать платную VM, при необходимости сразу с политикой автобэкапов
list_vm_backups, get_vm_backup_policy	чтение	точки восстановления, размеры, сроки защиты и расписание
set_vm_backup_policy	запись	расписание и срок хранения будущих автоматических копий
delete_vm_backup	удаление	безвозвратно удалить точку восстановления с проверками API

Kafka の料金は API で決まります。時間単位の VM 料金に管理費 30％が加算されます。IPv4 と追加ディスクには上乗せ料金はありません。管理費は最初の ready の後から発生します。 MCP は料金と請求に関する判断を受け渡すだけで、独自に計算することはありません。

アプリの削除には対応していません。Kafka とバックアップの削除はすでに利用可能です。 ツールには destructiveHint が設定されています。確認の表示はクライアントによって異なります。 サーバー側の二段階確認はありません。権限と保護制限は API が確認します。

これを支えるルール

• 認証キーはツールから返されません。 deploy_files 内の .env はアーカイブに含まれません（tatnet deploy と同様です）。秘密の env の値も読み取られません。 例外は Kafka の作成です。初期パスワードは一度だけ返され、クライアントのコンテキストに入ります。シークレットマネージャーに保存してください。呼び出しログを公開しないでください。
• 空のリストは「何もない」という意味ではありません。 /v1 は、キーからリソースが見えない場合でも 200 と空のリストを返します。キーに制限がある場合、ツールはそのことを明示します。
• 拒否の内容は、次の対応がわかるメッセージです。何が起きたか、何をすべきかを伝えます（403 →「キーの権限を拡張してください。再試行しないでください」、5xx →「こちら側の問題です。再試行してください」）。
• ビルドログは信頼できないデータです。 クライアントのコードがログを書き込みます。サーバーの指示とフィールドスキーマは、ログ内で見つかった内容を実行しないようモデルに伝えます。
• 「ビルド成功」≠「稼働中」です。 get_build はデプロイの完了を待ち、deploy_state を返します。アプリが稼働中とみなされるのは live の場合のみです。
• 再試行してもリソースは増えません。 モデルは呼び出しを再試行します。create_app と deploy_files は、2つ目を作成する代わりに名前でアプリを検索します。

接続

サーバーのアドレスは https://mcp.tatnet.cloud/mcp です。

OAuth を使用する場合 — リモート MCP サーバーに対応したクライアント（ウェブチャット、デスクトップアプリ、IDE）では、アドレスを指定して OAuth を選択するだけで十分です。クライアントが自動的に登録され、TatNet のログイン画面が開きます。

キーを使用する場合 — ヘッダーを渡すクライアントやスクリプト向けです。キーは TatNet のパネル →「API-ключи」で作成できます。プロジェクトや操作を制限できます。

claude mcp add --transport http tatnet https://mcp.tatnet.cloud/mcp \
  --header "Authorization: Bearer tn_live_…"

環境

変数	デフォルト
LISTEN	:$PORT、未設定の場合は :8080	明示的に指定した LISTEN は Apps Platform のポートより優先されます
PORT	—	Apps Platform から割り当てられたポートです。LISTEN が未設定の場合に使用されます
API_BASE_URL	https://api.tatnet.ru/v1	ステージング — …stage…/v1
PUBLIC_URL	https://mcp.tatnet.cloud	主な外部アドレス（OAuth メタデータ）
EXTRA_PUBLIC_URLS	—	カンマ区切りの追加外部名（例：移行期間中）。各名前でサーバーはその名前を名乗ります
METRICS_TOKEN	—	未設定の場合、/metrics は 404 を返します
OIDC_ISSUER	—	OAuth 発行者。未設定の場合、API キーのみ受け付けます
OIDC_JWKS_URL	$OIDC_ISSUER/.well-known/jwks.json	署名キーのアドレス。内部アドレスも指定できます
MCP_INTERNAL_SECRET	—	OAuth が有効な場合に必須です。API の V1_MCP_INTERNAL_SECRET と一致し、シークレットとして保存されます

メトリクス：tatnet_mcp_tool_calls_total{tool,outcome}、 tatnet_mcp_tool_duration_seconds{tool}、tatnet_mcp_auth_failures_total{reason}。

開発

go vet ./...
go build ./...
go test -count=1 ./...

エンドツーエンドテスト（cmd/tatnet-mcp/e2e_test.go）では、本物の MCP クライアント SDK をサーバーに接続し、サーバーはメモリ内に状態を持つ偽の /v1 に接続します。呼び出しの結果として、アーカイブに何が含まれたか、作成されたアプリの数、モデルへの応答に何が含まれたかを検証します。

ディレクトリ

サーバーは1つですが、クライアントがサーバーを見つけるディレクトリは3つあり、それぞれに個別に登録します。

ディレクトリ	必要なもの	ステータス
公式 MCP レジストリ	ルートにある server.json ＋ tatnet.cloud のドメイン所有権	最新バージョンは Registry API 経由（以下を参照）
Claude コネクタディレクトリ（claude.ai/directory/manage）	フォーム、テストアカウント、ドキュメント、プライバシーポリシー	—
ChatGPT プラグイン（platform.openai.com/plugins）	発行者の認証、/.well-known/openai-apps-challenge ファイル、5＋3件のテストシナリオ	—

レジストリ。 名前空間 cloud.tatnet/* は tatnet.cloud の APEX にある TXT レコードで確認します（_mcp. のようなセレクターの下ではありません）。サーバーのアドレスも同じドメインに置きます（テスト TestServerJSONFitsTheRegistry。レジストリはこれを必須としていませんが、これは当プロジェクトのルールです）。Ed25519 キーの生成には OpenSSL 3 のみを使用します（macOS のシステム openssl は LibreSSL で、Ed25519 に対応していません）。

O=/opt/homebrew/opt/openssl@3/bin/openssl
$O genpkey -algorithm Ed25519 -out key.pem          # хранить как секрет, не в репозитории
echo "tatnet.cloud. IN TXT \"v=MCPv1; k=ed25519; p=$($O pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
# ↑ эту запись — в зону tatnet.cloud, дождаться распространения
mcp-publisher login dns --domain tatnet.cloud \
  --private-key "$($O pkey -in key.pem -noout -text | grep -A3 priv: | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish

現在の DNS 認証キーは、このリポジトリの外にある発行者設定にローカル保存されています。再度ログインするときは、既存のキーを使用してください。キーの内容を README や Git に含めてはいけません。

⚠ 公開するたびに server.json の version を新しい値にする必要があります。レジストリは公開済みのバージョンの再利用を拒否します。

アノテーション。 どちらのディレクトリも、title、readOnlyHint、destructiveHint、openWorldHint を通信データから読み取ります。また ChatGPT は、フラグが明示的に指定されていないツールを拒否します。テスト TestToolAnnotationsAreExplicitOnTheWire は、生の tools/list を検証します。

アプリの検索とデプロイの確認

list_apps は、完全一致する repo、branch、name、domain のフィルターを受け付けます。project_id を省略すると、接続から見えるすべてのプロジェクトが検索対象になります。limit のデフォルトは一致件数100（最大200）です。next_cursor がある場合は、同じフィルターとそのカーソルを使って続行してください。空のページでも、次のページが残っている場合があります。scope は検索対象となったプロジェクトを示します。フィルタリングは API のページをまたいで行われるため、後続のページにある一致項目も引き続き検索できます。

get_build は build_id または完全一致する commit_sha のいずれかを受け付けます。どちらの検索も、最新の50件だけでなく、ビルド履歴全体を対象に続行されます。両方を省略すると最新のビルドが選択され、その呼び出しでのポーリング中はその ID が固定されます。呼び出しをまたいで続行する場合は、返されたビルド ID を渡すと同じビルドを監視できます。

build_succeeded はアーティファクトの作成を示します。deployment_succeeded と succeeded が true になるのは、status=success かつ deploy_state=live の場合のみです。デプロイ状態が欠落、不明、進行中、または未検証の場合は保留のままです。起動に失敗した場合は処理を終了し、診断用のログ行が出力されます。finished は失敗を含め、待機が終了したことを意味します。これだけを根拠にデプロイ成功と判断しないでください。

AI モデルカタログ

ai_models(kind="chat" | "text" | "image" | "video") は、公開カタログ ai.tatnet.cloud からモデル、機能、クライアント向け価格を取得します。このツールは、クラウド管理キーを推論ゲートウェイに渡さず、生成も実行しません。

有料の AI 生成操作には専用の tnai_live_… が必要ですが、現在の OAuth／MCP キーはクラウド管理を認証します。特定のアカウントの推論キーに安全に交換する方法がないため、リモート MCP 経由の生成は追加しません。残る課題は、アカウント権限を確認したうえでのキー交換／委任です。モデル引数やサーバー共通キーを通じてシークレットを渡すべきではありません。現在、生成には独自の推論キーを使用して tatnet ai を実行してください。

VPC の名前変更

rename_vpc は vpc_id と name を受け付けます。PATCH /v1/vpcs/{id} を通じて表示ラベルのみを変更し、vpc:update 権限が必要です。サブネット、ポート、NAT、OVN の識別子は変更されません。

S3

list_s3_regions はリージョンとパブリックエンドポイントを表示します。 get_s3_connection_info は選択したリージョンの接続設定を返します。 create_s3_bucket は、デフォルトでプライベートなバケットを作成します。region は任意です。 リージョンが指定されていない場合、API はデフォルトのリージョンを使用します。認証には、OAuth 接続を含め、同じ /v1 ポリシーが適用されます。バケットの権限は API が確認します。

VM とバックアップ

VM ツール：create_vm は、任意の backup_policy を含む、VM 作成時に公開されている設定を受け付けます。list_vm_backups は、復旧ポイントの作成元、有効期限、圧縮後のサイズ、不変の削除期限を返します。権限と請求に関する確認は、引き続き API が決定します。

VM バックアップ：delete_vm_backup は、公開 API を通じて選択したポイントを削除し、実行中のジョブ、保持期間、チェーン依存関係に関するガードを維持します。保存された結果もディスパッチもないまま 7 日を経過した、放棄された従来のプレースホルダーは、明示的に削除できます。

get_vm_backup_policy はスケジュールを読み取ります。set_vm_backup_policy は、 project_id、vm_id、enabled、hour_utc（UTC の 0～23）および retention_days （1～365）を受け付けます。ストレージ料金は、圧縮後の 10 進 GB・月あたり 6 RUB（730 時間）で、VM のサブスクリプションとは別料金です。前払い枠はありません。ポリシーを無効にしてもコピーとストレージ料金は維持されます。手動コピーに有効期限はありません。古いロックとチェーン依存関係は引き続き適用されます。新しいキャプチャは、それぞれ独立した完全な圧縮ポイントです。ユーザーガイドを参照してください。

リリースとバージョンの確認

リリース 1.5.0 では、パブリック IP を保持したまま使用できる enable_nat_gateway と disable_nat_gateway が追加されます。再接続する場合は available になるまで待ち、fip_id を渡してください。保持されたアドレスには引き続き料金が発生します。

Git タグ、GitHub Release、GHCR イメージ、稼働中のサーバー、MCP Registry のカードは、それぞれ別々に更新されます。server.json は Registry への公開内容を記述するもので、アプリケーションイメージを切り替えたり、バイナリのバージョンを指定したりするものではありません。MCP initialize のバージョンは、Docker のビルド引数 VERSION（CI では ref + SHA）から取得されます。

現在のバージョンは個別に確認してください。Git/GitHub Release、稼働中のアプリケーションイメージ、MCP Registry は、更新のタイミングが異なる場合があります。カードのバージョンは該当タグの server.json から取得されます。実際のサーバーバージョンは、deploy_state=live になった後の initialize と確認済みのイメージ SHA から取得されます。

リリース 1.6.0 では、削除後も保持される予約済みの floating_ip_id に対応した create_load_balancer と get_load_balancer が追加されます。

新しいリリースの手順：

1. server.json を未公開のバージョンに更新し、変更内容を記述して、vet/build/tests を実行し、リリースコミットの CI が成功するまで待ちます。
2. 検証済みのコミットに v<version> タグを付けます。Workflow image は、main への push 時とタグへの push 時にイメージを公開します。完全な SHA のタグを書き込むのは main のみです。リリースの push では v<version> が書き込まれ、SHA イメージは上書きされません。イメージのビルドとテストは別々の workflows です。イメージが存在するだけでは、テストに合格した証明にはなりません。
3. 変更内容、検証結果、完全な SHA を記載して GitHub Release を作成します。
4. サーバーを変更する場合は、tatnet app update <app-id> --image <image> で ghcr.io/tatnet-ru/tatnet-mcp:<完全な-SHA> イメージを選択してから、tatnet app deploy <app-id> を実行します。CLI には適切なプロジェクトを指定してください（-p <project-id>）。
5. tatnet app get <app-id> -o json を使って deploy_state=live、running_docker_image、running_docker_image_digest を確認します。また、/healthz と、認証済みの MCP initialize/tools/list も確認してください。ロールバックが必要な場合は、以前の SHA イメージに戻して deploy を再実行します。
6. 同じタグのチェックアウトから、既存の発行者アカウントを使って mcp-publisher publish を実行します。Registry API で server.version と isLatest を確認してください。gh release create とタグの push では Registry のカードは公開されません。

操作のサポート範囲は tools/list で確認できます。Registry カードの説明は簡潔なものであり、上記のツール一覧に代わるものではありません。

VM での複数 VPC

各 VPC は、同じアカウントとリージョン内の別個のネットワークインターフェイスとして接続されます。VM のインターフェイスを変更する前に VM を停止してください。設定は起動時に適用されます。プライマリインターフェイスとデフォルトルートは、切断できないよう保護されています。

attach_vm_interface は project_id、vm_id、vpc_id を受け取ります。detach_vm_interface は project_id、vm_id、interface_id を受け取ります。どちらの操作も、vm:update と vpc:write のチェックを含む共通のパブリック API を使用します。

Managed PostgreSQL

• get_postgres_cluster は、現在のクラスター、専用リーダーエンドポイント、レプリカノードの状態、バイト単位のラグ、保留中の変更を読み取ります。
• set_postgres_read_replicas は、project_id と cluster_id に対して count（0～5）を設定します。これらはクラスターのプランに基づく追加の有料ノードであり、HA とは独立しています。カウントをゼロにするとリーダーが削除されますが、プライマリデータベースは残ります。レプリカが自動的に昇格することはなく、ラグが発生する場合があります。読み取りエンドポイントは、TCP/5433 上で書き込み先と同じアドレスを共有します。設定を変更した後は、read_replicas_pending が false になるまで get_postgres_cluster を確認し、観測されたノードの状態を検証してください。

どちらのツールも共通のパブリック API を使用し、API キー/OAuth 認証を維持します。