TatNet — apps and cloud infrastructure

tatnet-mcp

MCP-сервер TatNet: управление платформой из Claude (claude.ai, Desktop, Code), ChatGPT и любого клиента Model Context Protocol. «Сделай сайт и выложи на TatNet» — это вызов deploy_files.

Quick start / English

TatNet MCP is a remote server for deploying static and SSR websites from an AI conversation and managing Git/Docker apps, builds, logs, environment variables and domains on TatNet, a Russian cloud platform. Transport: Streamable HTTP. Endpoint: https://mcp.tatnet.cloud/mcp. Authentication: OAuth or a scoped API key.

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

Connect through OAuth, choose a project and write access, then ask the assistant to publish your website. A deployment is ready when both status=success and deploy_state=live are confirmed. Backend apps require Git or a Docker image; Additional tools cover managed Kafka, VM creation and backup policies, regional S3 discovery and bucket creation, VPC display-name changes and the public AI model catalog. list_vm_plans discovers VM plan UUIDs, specifications and prices. Use the CLI/API for discovery of VM images/clusters, other VM operations, databases, DNS zones, S3 credentials and object operations. App deletion and balance top-ups are unavailable through MCP.

• MCP overview and connection docs.
• Publish from Claude Code.
• Diagnose a failed build.
• CLI deployment from CI.

Устройство

• Тонкий слой над публичным /v1. Своей БД, своих прав и бизнес-логики нет: инструменты управления зовут api.tatnet.ru/v1 через SDK tatnet-go или общий JSON-транспорт с той же авторизацией вызывающего. ai_models отдельно читает публичный каталог ИИ без передачи ключа. Права — политика ключа ∩ живая роль создателя, как у CLI и SDK. Чего нет в /v1, того нет и здесь: сначала ручка в /v1, потом инструмент.
• Streamable HTTP без состояния (/mcp), официальный modelcontextprotocol/go-sdk. Реплики взаимозаменяемы, выкат клиентов не рвёт.
• Авторизация — OAuth или ключ /v1. Клиент без поля для заголовка регистрируется сам (DCR), человек входит в TatNet и на экране согласия выбирает аккаунт, проекты и уровень доступа; подключение появляется в панели рядом с API-ключами и отзывается там же. Токен выдан только для MCP и дальше сервера не уходит — в /v1 сервер ходит сам от имени подключения. Клиенты, которые умеют передать заголовок, могут прийти и с ключом Authorization: Bearer tn_live_…. Права в обоих случаях решает api на каждом вызове: политика подключения или ключа пересекается с ролью человека.

Инструменты

Kafka тарифицируется в API: почасовые VM + 30% за управление; IPv4 и дополнительные диски без наценки. Управление оплачивается после первого ready. MCP передаёт цены и решения биллинга, не рассчитывает их самостоятельно.

Удаление аппов не поддерживается. Удаление Kafka и бэкапов уже доступно: инструменты помечены destructiveHint; показ подтверждения зависит от клиента. Серверного двухшагового подтверждения нет, права и защитные ограничения проверяет API.

Правила, на которых держится

• Ключи авторизации не возвращаются инструментами. .env из deploy_files в архив не кладётся (как у 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_…"

Окружение

Метрики: 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 с состоянием в памяти, и проверяет последствия вызовов: что ушло в архив, сколько аппов создано, что попало в ответ модели.

Каталоги

Сервер один; каталогов, из которых о нём узнают клиенты, три, и в каждый он подаётся отдельно.

Реестр. Пространство имён cloud.tatnet/* подтверждается TXT-записью на АПЕКСЕ tatnet.cloud (не под селектором вроде _mcp.), адрес сервера держим на том же домене (тест TestServerJSONFitsTheRegistry; реестр этого не требует, это наше правило). Ключ Ed25519 — только OpenSSL 3 (системный openssl macOS — 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.

⚠ Каждая публикация требует НОВОЙ version в server.json: реестр отвергает повтор уже опубликованной версии.

Аннотации. Оба каталога читают title, readOnlyHint, destructiveHint, openWorldHint с провода, а ChatGPT отклоняет инструмент, у которого флаг не указан явно. Тест TestToolAnnotationsAreExplicitOnTheWire проверяет сырой tools/list.

Finding apps and confirming a deployment

list_apps accepts exact repo, branch, name, and domain filters. Omitting project_id searches all projects visible to the connection. limit defaults to 100 matches (maximum 200). If next_cursor is present, continue with that cursor and the same filters; an empty page can still have more pages. scope states which projects were searched. Filtering happens across API pages, so later matches remain discoverable.

get_build accepts either build_id or an exact full commit_sha. Both searches continue through build history, rather than just the latest 50 builds. Omitting both selects the latest build and pins its ID during that call's polling. When continuing across calls, pass the returned build ID to keep observing the same build.

build_succeeded describes artifact creation. deployment_succeeded and succeeded are true only for status=success and deploy_state=live. A missing, unknown, rolling or unverified deployment state remains pending; startup failures terminate with succeeded=false and diagnostic log lines. finished means waiting has ended, including failure. Never treat it alone as a successful deployment.

Каталог моделей ИИ

ai_models(kind="chat" | "text" | "image" | "video") читает публичный каталог ai.tatnet.cloud: модели, умения и клиентские цены. Инструмент не передаёт ключ управления облаком в шлюз инференса и не запускает генерацию.

Платные операции генерации ИИ требуют отдельного tnai_live_…, тогда как текущий OAuth/ключ MCP авторизует управление облаком. Без безопасного обмена на ключ инференса конкретного аккаунта генерацию через remote MCP не добавляем. Оставшийся шаг — такой обмен/делегирование с проверкой прав аккаунта; передавать секрет через аргументы модели или общий ключ сервера не следует. Для генерации сейчас используйте tatnet ai с собственным ключом инференса.

Rename a VPC

rename_vpc accepts vpc_id and name. It changes only the display label through PATCH /v1/vpcs/{id} and requires vpc:update; subnet, ports, NAT and OVN identifiers stay unchanged.

S3

list_s3_regions показывает регионы и публичные endpoints; get_s3_connection_info возвращает настройки подключения выбранного региона; create_s3_bucket создаёт приватный по умолчанию бакет с необязательным region. При отсутствии региона API использует регион по умолчанию. Авторизация — та же политика /v1, включая OAuth-подключения; права на бакеты проверяет API.

VM и бэкапы

VM tools: create_vm accepts the public VM creation settings, including an optional atomic backup_policy; list_vm_backups returns recovery point origin, expiry, compressed size and immutable deletion deadlines. API permissions and billing checks remain authoritative.

VM backups: delete_vm_backup deletes a selected point through the public API, preserving active-job, retention and chain-dependency guards. Abandoned legacy placeholders can be explicitly deleted after seven days without a stored result or dispatch.

get_vm_backup_policy reads the schedule; set_vm_backup_policy accepts project_id, vm_id, enabled, hour_utc (0–23 UTC) and retention_days (1–365). Storage costs 6 RUB per compressed decimal GB-month (730 hours), separate from the VM subscription, without prepaid slots. Disabling a policy preserves copies and storage charges. Manual copies do not expire; old locks and chain dependencies remain enforced. New captures are independent full compressed points. See the user guide.

Выпуск и проверка версии

Выпуск 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 build-аргумента VERSION (в CI — ref + SHA).

Текущие версии проверяйте отдельно: Git/GitHub Release, образ работающего приложения и MCP Registry могут обновляться в разное время. Версия карточки берётся из server.json соответствующего тега; фактическая версия сервера — из initialize и подтверждённого SHA образа после deploy_state=live.

Выпуск 1.6.0 добавляет create_load_balancer и get_load_balancer с поддержкой зарезервированного floating_ip_id, который сохраняется после удаления LB.

Порядок нового выпуска:

1. Обновить server.json до ещё не опубликованной версии, описать изменения, запустить vet/build/tests и дождаться успешного CI на коммите выпуска.
2. Поставить v<version> на проверенный коммит. Workflow image публикует образы на push в main и на тег. Только main пишет тег полного SHA; релизный push пишет v<version> и не перезаписывает SHA-образ. Сборка образа и тесты — отдельные workflows: наличие образа само по себе не доказывает, что тесты прошли.
3. Оформить GitHub Release с изменениями, результатами проверок и полным SHA.
4. При изменении сервера выбрать образ ghcr.io/tatnet-ru/tatnet-mcp:<полный-SHA> через tatnet app update <app-id> --image <image>, затем 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 существующей учётной записью издателя. Проверить server.version и isLatest по Registry API. gh release create и пуш тега не публикуют карточку Registry.

Полнота поддержки операций определяется tools/list. Описание карточки Registry краткое и не заменяет таблицу инструментов выше.

Несколько VPC на ВМ

Каждая VPC подключается отдельным сетевым интерфейсом в том же аккаунте и регионе. Перед изменением интерфейсов ВМ нужно выключить; настройки применяются при запуске. Основной интерфейс и маршрут по умолчанию защищены от отключения.

attach_vm_interface принимает project_id, vm_id, vpc_id; detach_vm_interface — project_id, vm_id, interface_id. Обе операции используют общий публичный API с проверками vm:update и vpc:write.

Managed PostgreSQL

• get_postgres_cluster reads the current cluster, dedicated reader endpoint, replica node states, byte lag and pending changes.
• set_postgres_read_replicas sets count (0–5) for a project_id and cluster_id. These are additional paid nodes on the cluster plan, independent of HA. Count zero removes readers; the primary database remains. Replicas never automatically promote and can lag. The read endpoint shares the writer address on TCP/5433. After changing intent, inspect get_postgres_cluster until read_replicas_pending is false and verify the observed node states.

Both tools use the common public API and preserve API-key/OAuth authorization.

retain_load_balancer_ip закрепляет именно текущий адрес работающего LB. Передайте project_id, load_balancer_id и точный expected_vip: при смене адреса API вернёт 409. Операция не пересоздаёт LB и не выбирает другой IP. Ответ содержит floating_ip_id; этот резерв остаётся после удаления LB. Оплата адреса остаётся в текущей подписке LB и переходит в отдельный почасовой учёт после её освобождения. Для Kubernetes добавьте UUID в tatnet/lb-floating-ip-id и исходные Helm/GitOps values до пересоздания Service.

Kafka monitoring and password recovery

Kafka now exposes GET /projects/{project}/kafka-clusters/{cluster}/nodes/{node}/metrics?metric=cpu&range=1h (also memory, disk_io, network_io) and POST /projects/{project}/kafka-clusters/{cluster}/password. These use the common authenticated /v1 API, cluster permissions and node ownership checks. Password reset returns a generated password once with applied=false; wait for cluster password_status=applied before updating clients. An empty allowlist closes public client access. Block volumes: list_volumes, attach_app_volume, detach_app_volume use the same public API permissions and lifecycle as the dashboard. Attachment requires a preformatted ext4 disk, one Firecracker backend replica and regional support. Changing mounts restarts the app; detach preserves the volume and its billing.

get_s3_usage читает /v1/object-storage/usage с правами вызывающего. snapshot_at: null означает отсутствие замера размера, а не пустой бакет. egress_bytes_month и request_count_month относятся к traffic_month (UTC); счётчики поступают с задержкой.

Managed Supabase: separate protected endpoint

Connect ChatGPT to https://mcp.tatnet.cloud/supabase/mcp using OAuth. This endpoint has its own protected-resource metadata and OAuth audience. It exposes only:

In ChatGPT on the web, open Plugins → Add → Add custom MCP server, enter the URL above, and choose OAuth. Discovery and dynamic client registration are automatic. Do not provide Studio passwords, anon, or service_role keys. See the connection guide. TatNet's database detail and Studio Connect → MCP show the same instructions. Existing Studio applications receive the updated UI when opened from TatNet.

During OAuth consent, select an account, specific databases and read or write access. Read is the default. Future databases are excluded. No app, billing or infrastructure access is added. Read grants allow database data, including sensitive rows accessible to the database owner; they are not limited by the end-user RLS policies. Write access is database-owner authority, never cluster superuser authority. There is no read-only SQL guarantee on execute_sql.

Revoke the connected app in the dashboard under API keys. API authorization rechecks the live membership and policy for every tool call, including after MCP authentication cache hits. Turning off a member's Supabase access also removes SQL access. Existing application OAuth grants are not extended to databases.

Default SQL limits: 30 seconds, 100 rows per statement; callers may lower the timeout and request up to 1000 rows. SQL bodies are limited to 100 KB. Results are bounded and values are text or JSON null (distinct from empty text). Large values may be truncated. Use SQL pagination for large datasets. query_database requires a row-returning statement (for example SELECT, SHOW or EXPLAIN). It rejects multi-statement scripts, transaction-control commands and writes hidden in SQL functions. A read-only transaction is not a sandbox for arbitrary CPU work or extension side effects: timeouts, the constrained owner role and the platform's extension/egress policy still apply.

execute_sql is marked destructive and non-idempotent. Clients must obtain user confirmation for destructive SQL. The OAuth write grant is the server-side permission boundary; MCP annotations are guidance, not an extra authorization check. No automatic retries: after a timeout the outcome may be unknown. Inspect the database before manually retrying. Multi-statement scripts can commit a prefix if they explicitly manage transactions. Audit records include database, actor, SQL fingerprint, limits and execution outcome, without SQL text or rows.

API keys also work as bearer tokens for non-OAuth MCP clients. Pin their policy to supabase:<database UUID> with supabase:read and supabase:query; add supabase:sql only for writes. Query and SQL actions require the creator's live account:manage_supabase permission; metadata listing requires account:view_supabase.

Operator rollout and verification

1. Deploy tatnet-supabase-control with private POST /v1/projects/{ref}/query. An older control returns an error for reads; there is no fallback to /sql.
2. Deploy API with /v1/supabase, /query, /sql, the action catalog and the endpoint-specific consent policy. No database migration is required.
3. Deploy the auth frontend with explicit database selection and read default.
4. Deploy MCP. Reuse the existing OAuth issuer, JWKS, internal secret and TLS hosting configuration. Protected-resource metadata is at /.well-known/oauth-protected-resource/supabase/mcp; DCR allows both resources. MCP_RESOURCE_URLS continues to contain the application /mcp base resources; the API derives the corresponding /supabase/mcp resources from them.
5. On a disposable managed database, connect ChatGPT through OAuth; verify listing, SELECT, read-mode write rejection and explicit write consent. Revoke the connection and verify the next tool request is denied. Never test destructive SQL against a customer database.

Do not expose Studio's /api/mcp, pg-meta or PostgreSQL as an alternative. This implementation authenticates through TatNet and uses the same public API as CLI. The regenerated Go SDK can be released independently; the new CLI commands use the existing authenticated HTTP transport and do not require an unreleased SDK.

Production OAuth, all three database tools, and grant revocation were verified through ChatGPT on 2026-11-07 without changing application tables or rows. See validation and deployment evidence.

Kafka monitoring tools: kafka_health reads current replication/group lag; kafka_history reads replication or selected consumer-group history; kafka_monitoring_config sets per-group lag warnings (null lag_threshold disables them, duration 60..3600 seconds in whole minutes). Configuration applies asynchronously. Warnings appear in the console only. Unknown lag stays null; committed-offset lag is not processing time. Existing scoped API permissions apply.

Valkey transport

create_valkey_cluster creates a paid instance with tls_mode defaulting to required. preferred accepts TLS and plaintext on the same endpoint port; disabled accepts plaintext only. Creation returns a password once: save it securely. get_valkey_cluster returns the mode, readiness gate and applied receipt. update_valkey_tls_mode changes intent through the public API; changing to required closes plaintext sessions. Old nodes require replacement first, reported as 409. Wait for parameters_applied before claiming completion. All authorization, validation and audit decisions remain in the API.