Як безкоштовно підключити ШІ-агента до TON через MCP

Ви просите Claude або Cursor «перевір баланс цього TON-гаманця і покажи останні транзакції» — і агент чесно намагається. Смикає публічний лайтсервер із глобального конфіга, отримує not ready, ретраїть, ловить ADNL-таймаут. Або йде в toncenter без ключа, впирається в ліміт приблизно один запит на секунду й отримує HTTP 429 Too Many Requests. Агент не вміє читати TON сам по собі — йому потрібні інструменти. І більшість розробників на цьому етапі думають, що доведеться піднімати ноду, крутити конфіги, платити за доступ. Насправді ні: підключити агента до TON можна безкоштовно і без цих граблів — двома різними способами, і жоден із них не вимагає картки.

Найшвидший спосіб дати агентові руки в TON — це MCP. Model Context Protocol — це стандарт, за яким ШІ-агенти (Claude, Cursor, ChatGPT/Codex і будь-який MCP-клієнт) викликають зовнішні інструменти. Замість того щоб учити агента смикати сирий JSON-RPC і розбирати комірки, ви віддаєте йому набір готових інструментів на кшталт get_balance чи get_jetton_balance — а він сам вирішує, коли їх викликати. TONNode — це hosted MCP-сервер для TON (сайт tonnode.io), і підключити через нього безкоштовний TON MCP можна двома шляхами, жоден з яких не вимагає картки. Розберемо обидва.

Безкоштовний TON MCP: два шляхи — локальний npx і ключ Hobby

Щоб підключити агента до TON безкоштовно, у вас є вибір:

1. Локальний запуск через npx на публічному конфігу — узагалі без ключа і без реєстрації. Пакет завантажується і запускається на вашій машині.
2. Безкоштовний ключ Hobby — вхід на сайт, ключ видається одразу, без картки, 60 запитів на хвилину через hosted-ендпоінт.

Різниця між ними — не в наборі інструментів, а в тому, де крутиться процес і звідки береться пропускна здатність. Почнемо з найпростішого.

Спосіб 1: локальний запуск через npx на публічному конфігу (без ключа)

Це буквально один блок у конфігу вашого MCP-клієнта. Жодної попередньої інсталяції — npx сам підтягне пакет.

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

Усе. На старті клієнта підніметься локальний процес @tonnode/mcp, підключиться до TON за нативним протоколом і віддасть агентові повний набір інструментів читання. Ключ не потрібен, картка не потрібна, акаунт не потрібен.

Важлива деталь під капотом: пакет @tonnode/mcp — open source (MIT), лежить на npm і GitHub (tonnode/mcp), працює за нативним ADNL-протоколом TON, без HTTP-прошарків між вашим агентом і мережею. Тобто це не обгортка над чиїмось REST API, яка впреться в чужий rate limit, — це прямий клієнт до мережі.

Куди класти цей конфіг

• Claude Desktop / Claude Code — у mcpServers файлу конфігурації MCP.
• Cursor — у налаштуваннях MCP-серверів проєкту або глобально.
• ChatGPT/Codex та інші MCP-клієнти — у їхньому розділі підключення MCP.

Детальний розбір по кожному клієнту з картинками — в окремому гайді: як підключити Claude і Cursor до TON.

Що доступно безкоштовно: повний набір читання TON

Локальний безкоштовний режим — це не урізана демка. Вам доступний повний набір читання, вісім інструментів, яких вистачає на переважну більшість агентних задач:

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

Практичний приклад. Класична задача «покажи баланс USDT одним викликом» розв'язується зв'язкою get_jetton_info (дізнатися decimals) + get_jetton_balance. Агентові достатньо промпта людською мовою:

Перевір баланс USDT на адресі UQAbc...xyz
і покажи його з правильною кількістю знаків після коми.

Агент сам викличе get_jetton_info, побачить decimals: 6, потім get_jetton_balance — і видасть коректну суму без жодного рядка вашого коду. Розбір — у гайді з MCP для TON, а окремий приклад — як дізнатися баланс USDT на TON одним викликом.

Спосіб 2: безкоштовний ключ Hobby — 60 запитів/хв без картки

Локальний npx чудово підходить для розробки й поодиноких задач, але є й стеля: він ходить через публічні лайтсервери з глобального конфіга TON. Вони спільні й лімітовані, часто відповідають not ready або ADNL-таймаутом під навантаженням і не зберігають глибокої історії. Для прод-агента, який відповідає реальним користувачам, це лотерея.

Тут вмикається другий безкоштовний шлях — тариф Hobby. Він безкоштовний назавжди, дає 60 запитів на хвилину, а ключ видається одразу після входу, без картки. Різниця з локальним режимом у тому, що запити йдуть не з вашої машини через спільну публічну інфраструктуру, а через hosted-ендпоінт TONNode з вашим особистим ключем — тобто у вас передбачуваний ліміт 60 запитів/хв, прив'язаний саме до вас.

Конфіг для hosted-підключення має такий вигляд:

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

Відмінностей від локального конфіга дві: type: "http" замість запуску процесу і заголовок Authorization з вашим ключем tn_live_…. Сам агент різниці в роботі не помітить — ті самі інструменти, ті самі імена, ті самі параметри.

Що важливо: на Hobby, як і на всіх інших тарифах, доступні всі 16 інструментів TONNode — не лише читання, а й свап, кросчейн, генерація гаманця. Саме на hosted-ключі до восьми інструментів читання додається, зокрема, generate_wallet — створення нового TON-гаманця версій v3r2, v4, v5r1 або highload_v3: інструмент повертає мнемоніку, ключі й адресу прямо вам, сервер згенеровані гаманці не зберігає. Тариф обмежує не функціональність, а пропускну здатність. Ви платите лише за throughput, якщо він вам знадобиться.

Отримати ключ Hobby (без картки): tonnode.io/dashboard?plan=hobby.

Локально чи hosted: де безкоштовного вистачає, а де потрібен throughput

Коротко: безкоштовного вистачає майже завжди, поки йдеться про розробку, прототипи й невисоку частоту викликів. Різниця між режимами — не в наборі інструментів, а в пропускній здатності.

Режим	Ключ / картка	Пропускна здатність	Для чого
Локальний npx	Не потрібні	Публічні лайтсервери (спільні, ліміт)	Розробка, разові задачі
Hobby (hosted)	Ключ, без картки	60 запитів/хв на вашому ключі	Пет-проєкти, легкий прод
Pro / Scale (hosted)	Ключ + оплата	300 / 1200 запитів/хв	Навантажений прод

Ключовий факт: на всіх тарифах доступні всі 16 інструментів — включно зі свапом і кросчейном. Платите ви лише за пропускну здатність, а не за «розблокування» функцій. Pro коштує $29/міс і дає 300 запитів/хв, Scale — $199/міс і 1200 запитів/хв. Платний throughput потрібен рівно тоді, коли вам замало 60 запитів на хвилину або коли потрібен передбачуваний власний ліміт на hosted-ендпоінті mcp.tonnode.io під реальним навантаженням. Повний розбір — на сторінці тарифів і сторінці про інструменти.

Покроково: підключаємо агента і робимо перший виклик

Зберемо все разом на прикладі з локальним запуском (для Hobby відрізняється лише блок конфіга).

Крок 1. Додайте сервер у конфіг MCP-клієнта. Візьміть блок із npx -y @tonnode/mcp, показаний вище, і вставте в конфіг вашого клієнта (Claude, Cursor, Codex — шлях залежить від клієнта).

Крок 2. Перезапустіть клієнт. Він підніме процес @tonnode/mcp і побачить інструменти. У більшості клієнтів список підключених інструментів видно в інтерфейсі — переконайтеся, що ton з'явився.

Крок 3. Дайте агентові задачу звичайним текстом. Наприклад:

Дізнайся поточну голову мастерчейна TON і заразом
баланс адреси UQAbc...xyz у GRAM.

Агент сам викличе get_masterchain_info, потім get_balance і поверне результат людською мовою.

Крок 4. Складніші задачі — теж одним промптом. Скажімо:

Скільки USDT на гаманці UQAbc...xyz? Поверни суму з урахуванням decimals.

Тут агент викличе get_jetton_info, щоб дізнатися decimals USDT (=6), потім get_jetton_balance, щоб отримати сирий баланс, і перерахує його в людську суму. Джетон-гаманець він обчислить он-чейн — вам не потрібно передавати його адресу.

Крок 5. Коли впретеся в ліміт публічних лайтсерверів (побачите not ready або таймаути) — замініть блок на hosted-конфіг із ключем Hobby. Змінюється лише конфіг, промпти й логіка агента залишаються тими самими.

Некастодіальність: чому безкоштовний доступ безпечний

Логічне запитання: якщо сервер безкоштовний і він же генерує гаманці та будує транзакції — чи не ризикую я ключами? Ні, і це принципова позиція архітектури. TONNode строго некастодіальний.

Сервер ніколи не підписує і не зберігає кошти та приватні ключі. Інструменти читання просто читають публічний ончейн-стейт. А інструменти, які змінюють стан — свап і кросчейн — не відправляють нічого від вашого імені: вони повертають непідписані TonConnect-повідомлення. Підписує їх гаманець користувача, локально, своїм ключем. Те саме і з generate_wallet (він доступний на hosted-ключі): згенерований гаманець і його мнемоніка віддаються вам, сервер їх у себе не залишає.

Інакше кажучи, безкоштовний доступ нічим не ризикованіший за платний: підписувати транзакції фізично може лише власник гаманця — у сервера немає ключів, щоб будь-що підписати. Це принципова відмінність від кастодіальної моделі, де сервер тримає operator-ключ і підписує сам. Розбір двох підходів та їхніх ризиків — в окремому матеріалі про кастодіальний і некастодіальний MCP.

Підсумок

Щоб дати ШІ-агентові руки в TON, не потрібно піднімати ноду і не потрібна картка. Локальний npx -y @tonnode/mcp дає повний набір читання без ключа просто зараз — ідеально, щоб спробувати. Безкоштовний тариф Hobby додає передбачувані 60 запитів/хв на вашому ключі через hosted-ендпоінт, теж без картки, коли публічних лайтсерверів починає бракувати. Обидва режими некастодіальні, обидва використовують ті самі інструменти, і будь-якої миті ви можете перейти на платний throughput, нічого не переписуючи в логіці агента.

Отримати безкоштовний ключ Hobby (без картки): tonnode.io/dashboard?plan=hobby