Як дати ШІ-агенту доступ до 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 за пару хвилин.