Как дать ИИ-агенту доступ к TON: полный гайд по MCP

У вас есть ИИ-агент — Claude в Cursor, скрипт на Codex, кастомный бот, — и вы хотите, чтобы он реально работал с TON: проверял баланс кошелька перед отправкой, читал историю транзакций, считал котировку свапа, готовил кроссчейн-обмен. Но агент, каким бы умным он ни был, слеп: у него нет глаз в блокчейне. Обычный путь — научить его дёргать toncenter или tonapi.io по HTTP. И тут начинается боль: без ключа лимит примерно один запрос в секунду, под нагрузкой прилетает HTTP 429 Too Many Requests, публичные лайтсерверы из глобального конфига отвечают not ready или отваливаются по ADNL-таймауту, а глубокой истории у них попросту нет. Агент, который должен «просто посмотреть баланс», спотыкается на инфраструктуре.

Решение — не учить агента ходить в API руками, а дать ему MCP-сервер для TON. Ниже — полный гайд: что такое MCP, зачем он агенту, как подключиться бесплатно за одну команду и что умеют 16 инструментов TONNode.

Что такое MCP и зачем он ИИ-агенту

MCP (Model Context Protocol) — это открытый стандарт, по которому ИИ-агенты вызывают внешние инструменты. Его понимают Claude, Cursor, ChatGPT/Codex и любой другой MCP-клиент: вы объявляете набор инструментов, агент видит их описания и сам решает, какой вызвать и с какими параметрами.

Аналогия простая: MCP для агента — как USB-порт для компьютера. У модели самой по себе нет доступа ни к сети, ни к блокчейну. Но подключите MCP-сервер — и у агента появляется набор «розеток»: прочитать баланс, собрать транзакцию, отследить сделку. Вы говорите «сколько USDT на кошельке X» — модель понимает, что нужен инструмент get_jetton_balance, подставляет адрес и получает структурированный ответ.

Разница с «дай агенту HTTP-эндпоинт» принципиальная. При работе через сырой API агенту приходится держать в контексте, как формировать запросы, как парсить ответы, как конвертировать адреса и raw-единицы. Всё это — место для галлюцинаций. MCP выносит эту логику на сервер: агент видит инструмент get_balance с понятной сигнатурой и получает готовый ответ. Меньше ошибок, меньше токенов в контексте, предсказуемое поведение.

TONNode (сайт tonnode.io) — это как раз готовый hosted MCP-сервер для TON (The Open Network). Один эндпоинт, 16 инструментов на чтение, свап, кроссчейн и работу с кошельками, поверх нативного протокола TON без промежуточных HTTP-прослоек.

Почему агенту нужен MCP-сервер для TON, а не публичные HTTP-шлюзы

Резонный вопрос: зачем отдельный сервер, если есть публичные API вроде toncenter и tonapi.io? Проблема в том, что публичные шлюзы годятся для разовых ручных запросов, но не рассчитаны на нагрузку от агента, который в цикле дёргает десятки вызовов в минуту.

• Лимиты и 429. Без ключа toncenter и tonapi.io дают порядка одного запроса в секунду и при превышении отвечают HTTP 429 Too Many Requests. Агент в цикле «прочитал состояние → принял решение → прочитал ещё» упирается в потолок моментально — и вместо ответа выдаёт пользователю ошибку.
• Публичные лайтсерверы ненадёжны. Лайтсерверы из глобального конфига (если ходить в TON по ADNL напрямую) — общие и лимитированные. Под нагрузкой они отвечают not ready, отваливаются по ADNL-таймауту и не хранят глубокой истории транзакций.
• Сырой ответ ≠ ответ агенту. Даже успешный JSON часто требует постобработки: вычислить адрес джеттон-кошелька, пересчитать raw-единицы по decimals, сконвертировать адрес между форматами. Каждый такой шаг, отданный модели, — потенциальная ошибка и лишние токены.

MCP-сервер закрывает всё это: стабильная пропускная способность, привязанная к вашему ключу, вычисления на стороне сервера и единый интерфейс с готовыми структурированными ответами. Кстати, если встретите в чатах «ошибку 228» — это мем-число TON-комьюнити, а не код API; реальный код лимита именно 429.

Подробный разбор бесплатного пути есть в отдельной заметке: как подключить TON к агенту бесплатно.

Как подключить: бесплатно через npx и hosted-ключ

Есть два пути, и первый — полностью бесплатный.

Вариант 1. Локально через npx (бесплатно, полный набор чтения)

Полный набор инструментов на чтение доступен без регистрации и без ключа. Пакет @tonnode/mcp — open source (MIT), лежит на npm и GitHub (tonnode/mcp), работает по нативному ADNL-протоколу TON. Добавьте в конфиг MCP-клиента:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Перезапустите Claude Desktop, Cursor или другой клиент — инструменты появятся сами. Пошаговая настройка для конкретных клиентов — в гайде как подключить Claude и Cursor к TON.

Вариант 2. Hosted-ключ (гарантированная пропускная способность)

Когда агент работает в проде и запросов много, нужен свой ключ и стабильный канал:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": {
        "Authorization": "Bearer tn_live_…"
      }
    }
  }
}

Бесплатный ключ Hobby выдаётся сразу после входа, без карты, и на нём доступны все 16 инструментов — tonnode.io/dashboard?plan=hobby.

16 инструментов TONNode по группам

На всех тарифах доступны все инструменты — платите только за пропускную способность. Разберём по группам.

Чтение (8 инструментов)

Фундамент для любого агента, который наблюдает за сетью, ничего не меняя:

• get_masterchain_info — «голова» мастерчейна, текущая точка сети.
• get_balance — баланс GRAM на адресе.
• get_account_state — статус аккаунта, флаги, последняя транзакция.
• get_transactions — история транзакций адреса.
• run_get_method — вызов любого read-only get-метода контракта.
• get_jetton_balance — баланс жетона (например, USDT); адрес джеттон-кошелька вычисляется он-чейн, знать его заранее не нужно.
• parse_address — конвертация и проверка адресов (EQ/UQ/raw), работает офлайн.
• get_jetton_info — метаданные жетона: имя, символ, эмиссия и, главное, decimals. Decimals критичны для пересчёта raw-единиц: у USDT их 6, у большинства жетонов — 9.

Пример промпта агенту с подключённым TONNode:

Проверь баланс GRAM и USDT на кошельке UQ…, покажи последние 5 транзакций.

Агент сам вызовет get_balance, get_jetton_balance (предварительно достав decimals через get_jetton_info) и get_transactions — без единого ручного HTTP-запроса.

Свап (2 инструмента)

Обмен внутри TON через протокол Omniston, который агрегирует ликвидность STON.fi и DeDust:

• get_swap_quote — твёрдая котировка DEX для пары GRAM ⇄ жетон.
• build_swap_tx — неподписанная транзакция свапа, готовая к подписи через TonConnect.

Обратите внимание на слово «неподписанная» — к нему вернёмся в разделе про некастодиальность.

Кроссчейн (5 инструментов)

TON всегда выступает источником, а обмен идёт через атомарный HTLC-эскроу — механизм, где средства блокируются по хешу секрета и разблокируются только при выполнении условий на обеих сетях. Поддержаны: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON пока не поддерживается.

• get_crosschain_quote — котировка кроссчейн-обмена.
• build_crosschain_swap_tx — неподписанная HTLC-эскроу транзакция плюс секрет.
• track_crosschain_swap — фазы сделки на обеих сетях.
• disclose_crosschain_secret — раскрыть секрет для расчёта после проверки готовности он-чейн.
• build_crosschain_refund — вернуть средства из эскроу, если сделка зависла.

HTLC-схема означает, что обмен либо проходит атомарно, либо возвращается через refund — средства не застревают у посредника.

Кошелёк (1 инструмент)

• generate_wallet — создаёт новый TON-кошелёк версий v3r2, v4, v5r1 или highload_v3 и возвращает мнемонику, ключи и адрес. Сгенерированный кошелёк сервер не хранит — он сразу отдаётся вам.

Полный обзор инструментов с параметрами — на странице tonnode.io/mcp.

Некастодиальность: почему сервер никогда не держит ваши ключи

Это принципиальное отличие, и его важно понять до того, как вы подпустите агента к деньгам.

Инструменты свапа, кроссчейна и генерации кошелька строго некастодиальны. Сервер TONNode никогда не подписывает транзакции и никогда не хранит средства или приватные ключи. Когда агент вызывает build_swap_tx или build_crosschain_swap_tx, он получает обратно неподписанное TonConnect-сообщение — заготовку транзакции. Подписывает её кошелёк пользователя, а не сервер. Кошельки из generate_wallet тоже отдаются вам и на сервере не остаются.

Аналогия: MCP-сервер — это штурман, который прокладывает маршрут и заполняет платёжку. Но нажать «отправить» и приложить подпись можете только вы, за рулём своего кошелька. Даже если агент скомпрометирован или ошибается, он не может увести средства — у него на руках только неподписанные заготовки.

Здесь полезно сравнение с официальным @ton/mcp от TON Foundation. Это сильный и официальный пакет: он умеет чтение, отправку GRAM/жетонов/NFT, свап через DEX-агрегатор, работу с NFT и DNS, создание и импорт агент-кошельков. Но по устройству это кастодиальный агент-кошелёк со split-key: operator-ключ держит сам агент и подписывает им, owner-ключ у пользователя. И кроссчейна у него нет — только TON. Разница честная: официальный пакет даёт агенту автономно тратить средства и работать с NFT/DNS; TONNode делает ставку на некастодиальность, кроссчейн и hosted-опцию. Детальный разбор — в статьях TONNode против официального TON MCP и кастодиальный против некастодиального MCP.

Тарифы и с чего начать

На всех тарифах доступны все 16 инструментов — различается только пропускная способность:

Тариф	Цена	Лимит
Hobby	бесплатно навсегда	60 запросов/мин
Pro	$29/мес	300 запросов/мин
Scale	$199/мес	1200 запросов/мин

Оплатить Pro и Scale можно в GRAM или USDT в сети TON через TonConnect, либо в BTC/ETH/SOL и других валютах через счёт xRocket в Telegram. Ключ выдаётся автоматически после расчёта платежа. (На всякий случай: GRAM — это переименованный в июне 2026 года Toncoin, сама сеть по-прежнему называется TON.)

Практичный путь старта:

1. Возьмите бесплатный ключ Hobby — без карты, сразу после входа, со всеми 16 инструментами: tonnode.io/dashboard?plan=hobby.
2. Пропишите hosted-конфиг (или начните локально через npx -y @tonnode/mcp).
3. Дайте агенту первый промпт на чтение — баланс, состояние аккаунта, история — и убедитесь, что 429 и not ready больше не мешают.

Дальше, когда упрётесь в лимит на проде, посмотрите тарифы и обзор инструментов. Начните с бесплатного ключа и подключите агента к TON за пару минут.