TatNet — apps and cloud infrastructure

tatnet-mcp

TatNet MCP 服务：通过 Claude（claude.ai、Desktop、Code）、 ChatGPT 和任何 Model Context Protocol 客户端管理平台。 “创建网站并部署到 TatNet”就是调用 deploy_files。

快速开始 / 英文

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 的薄封装。 没有自有数据库、权限或业务逻辑： 管理工具通过 tatnet-go SDK 或 采用相同调用者授权方式的通用 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 会按名称查找应用，而不是再创建一个。

连接

服务器地址为 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 — …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， 并检查调用的结果：归档中包含了什么、创建了多少个应用、 模型的响应中包含了什么。

目录

服务只有一个；客户端了解它的目录有三个，服务需要分别提交到每个目录。

目录	所需内容	状态
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 表示已创建构件。只有当 status=success 且 deploy_state=live 时，deployment_succeeded 和 succeeded 才为 true。缺失、未知、正在滚动更新或未验证的部署状态都仍视为待处理；启动失败会以 succeeded=false 结束，并附带诊断日志行。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 显示区域和公共 endpoints； get_s3_connection_info 返回所选区域的连接设置； create_s3_bucket 创建默认私有的存储桶，可选指定 region。 如果未指定区域，API 会使用默认区域。授权采用与 /v1 相同的策略， 包括 OAuth 连接；存储桶权限由 API 检查。

VM 和备份

VM 工具：create_vm 接受公开的 VM 创建设置，包括可选的原子化 backup_policy；list_vm_backups 返回恢复点来源、过期时间、压缩大小和不可变的删除期限。API 权限和计费检查仍以 API 为准。

VM 备份：delete_vm_backup 通过公共 API 删除所选恢复点，并保留对正在进行的任务、保留期限和链式依赖项的限制。对于没有存储结果或调度记录超过七天的遗留占位符，可明确将其删除。

get_vm_backup_policy 读取计划；set_vm_backup_policy 接受 project_id、vm_id、enabled、hour_utc（UTC 时间，0–23）和 retention_days （1–365）。存储费用为每压缩十进制 GB 月（730 小时）6 RUB，与 VM 订阅费用分开计算，且不设预付时段。禁用策略不会删除副本，也不会停止收取存储费用。手动副本不会过期；旧锁和链式依赖项仍会受到限制。新建的备份是彼此独立的完整压缩恢复点。请参阅用户指南。

发布和版本验证

版本 1.5.0 新增了 enable_nat_gateway 和 disable_nat_gateway，并保留公网 IP。重新连接时，请等待状态变为 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；服务的实际版本则取自 initialize 和 deploy_state=live 后确认的镜像 SHA。

版本 1.6.0 新增了 create_load_balancer 和 get_load_balancer，支持保留 floating_ip_id，并且该 ID 会在 LB 删除后保留。

新版本发布流程：

1. 将 server.json 更新为尚未发布的版本，描述变更，运行 vet/build/tests，并等待发布提交上的 CI 成功。
2. 在经过验证的提交上创建 v<version> 标签。Workflow image 会在推送到 main 和推送标签时发布镜像。只有 main 会写入完整 SHA 标签；发布推送会写入 v<version>，不会覆盖 SHA 镜像。镜像构建和测试属于不同的 workflows：存在镜像本身并不能证明测试已通过。
3. 创建 GitHub Release，说明变更、检查结果和完整 SHA。
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. 在同一标签的 checkout 中，使用现有发布者账户运行 mcp-publisher publish。通过 Registry API 检查 server.version 和 isLatest。gh release create 和推送标签都不会发布 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。这两项操作都使用通用公共 API，并进行 vm:update 和 vpc:write 检查。

托管 PostgreSQL

• get_postgres_cluster 会读取当前集群、专用只读端点、副本节点状态、字节级复制延迟和待处理变更。
• set_postgres_read_replicas 为 project_id 和 cluster_id 设置 count（0–5）。这些副本节点是集群套餐之外的额外付费节点，与 HA 无关。数量设为零会移除只读节点；主数据库仍会保留。副本不会自动提升为主节点，且可能存在延迟。只读端点与写入地址共用 TCP/5433。更改配置后，请检查 get_postgres_cluster，直到 read_replicas_pending 为 false，并验证观察到的节点状态。

这两项工具都使用通用公共 API，并保留 API 密钥/OAuth 授权。