Як підключити Claude і Cursor до TON: покрокова інструкція

Кожен, хто пробував змусити ШІ-агента щось зробити з TON, знає цю стіну. Просиш Claude перевірити баланс гаманця — він чесно відповідає, що не має доступу до мережі, або ще гірше: вигадує адресу жетона, плутає нанотони з тонами і бере цифри зі стелі. Даєш йому curl до публічного API — під навантаженням прилітає HTTP 429 Too Many Requests, а без ключа ліміт — приблизно один запит на секунду. Публічні лайтсервери з глобального конфігу то відповідають not ready, то відвалюються за ADNL-таймаутом. Проблема не в моделі — агент просто не має рук, якими міг би доторкнутися до блокчейну. MCP якраз і дає йому ці руки.

Нижче — як за кілька хвилин підключити Claude до TON, а також налаштувати Cursor TON MCP, Claude Code і Codex: точні конфіги, безкоштовний запуск через npx і перехід на hosted-ключ, коли впретеся в ліміти.

Що таке MCP і навіщо він агенту для роботи з TON

MCP (Model Context Protocol) — відкритий стандарт, за яким ШІ-агенти викликають зовнішні інструменти. Уявіть USB: раніше під кожен пристрій був свій роз’єм, тепер один порт на все. MCP — такий самий «єдиний роз’єм» між агентом і зовнішнім світом. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex і будь-який інший MCP-клієнт говорять однією мовою: клієнт підключається до MCP-сервера, отримує список інструментів і викликає їх на запит моделі.

Щоб агент умів ходити в мережу TON, потрібен MCP-сервер, який уміє це робити. Ми візьмемо TONNode — hosted MCP-сервер для TON. Він дає агенту рівно 16 інструментів: читання мережі (баланс, стан акаунта, транзакції, get-методи контрактів, баланси та метадані жетонів), свап через DEX-протокол Omniston, кросчейн-свапи через атомарний HTLC-ескроу і генерацію гаманців. Інструменти свапу, кросчейну та гаманця строго некастодіальні: сервер ніколи не підписує транзакції і не зберігає ключі — він повертає непідписані TonConnect-повідомлення, які підписує гаманець користувача.

Для цієї інструкції нам вистачить чотирьох read-інструментів, щоб перевірити зв’язок:

• get_masterchain_info — голова мастерчейну (найшвидший спосіб переконатися, що сервер живий);
• get_balance — баланс GRAM за адресою;
• get_jetton_balance — баланс жетона (USDT та інших), джетон-гаманець обчислюється он-чейн;
• parse_address — конвертація та перевірка адрес EQ/UQ/raw, повністю офлайн.

Як підключити Claude до TON: швидкий старт через npx (одна команда)

Нічого встановлювати не потрібно. Локальний сервер піднімається однією командою:

npx -y @tonnode/mcp

Пакет @tonnode/mcp — open source (MIT), лежить на npm і GitHub (tonnode/mcp), працює через нативний ADNL-протокол TON без проміжних HTTP-прошарків. Публічний конфіг дає повний набір інструментів читання безкоштовно — цього достатньо, щоб агент читав баланси, транзакції, стан акаунтів і смикав get-методи.

Базовий конфіг, який ви вставлятимете в клієнти, має такий вигляд:

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

Запам’ятайте структуру mcpServers — вона повторюється майже в усіх клієнтах один в один. Далі просто показую, куди її класти. Детальний розбір безкоштовного режиму — в окремому гайді MCP для TON безкоштовно.

Не хочете ставити локально? Безкоштовний ключ Hobby до hosted-ендпоінту видається одразу після входу, без картки — візьміть його на tonnode.io/dashboard і одразу вставляйте в конфіг нижче.

Claude Desktop: де лежить claude_desktop_config.json і що в нього вписати

Claude Desktop читає конфіг MCP з файлу claude_desktop_config.json. Шлях залежить від системи:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Відкрийте файл (або створіть, якщо його немає) і впишіть той самий об’єкт mcpServers:

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

Після правки перезапустіть застосунок — Claude Desktop підхоплює конфіг лише під час старту. У меню інструментів з’явиться сервер ton. Тепер напишіть у чат:

Виклич get_masterchain_info і покажи seqno голови мастерчейну.

Якщо агент повернув номер блока — MCP підключено. Так само можна попросити «Перевір баланс гаманця UQ…» — під капотом спрацює get_balance і поверне справжню цифру в GRAM (GRAM — це перейменований у червні 2026 року Toncoin; сама мережа, як і раніше, називається TON).

Claude Code: команда claude mcp add і файл .mcp.json

У Claude Code сервер додається однією командою з термінала — вона сама пропише все в потрібний файл. Локальний варіант:

claude mcp add ton -- npx -y @tonnode/mcp

Подвійне тире -- відділяє команду запуску сервера від прапорців самої claude. Після цього Claude Code створить (або доповнить) проєктний .mcp.json. За бажання той самий об’єкт mcpServers можна вписати у файл руками — результат ідентичний:

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

Перевірте зв’язок прямо в CLI:

Через parse_address приведи 0:83df... до user-friendly формату EQ/UQ.

parse_address працює офлайн, тому це найнадійніший тест: він не залежить від стану мережі й миттєво показує, що інструменти видно агенту.

Cursor: файл .cursor/mcp.json (проєкт і глобально)

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

• .cursor/mcp.json у корені проєкту — сервер видно лише в цьому проєкті;
• ~/.cursor/mcp.json — глобально, в усіх проєктах.

У разі конфлікту виграє проєктний файл. Кладемо туди:

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

Це і є весь Cursor TON MCP-сетап: один файл, чотири рядки корисного навантаження. Після збереження перевірте в Settings → MCP, що ton у статусі Enabled, і попросіть агента прямо в редакторі:

Скільки USDT на гаманці EQ...? Виклич get_jetton_balance.

get_jetton_balance сам обчислить адресу джетон-гаманця он-чейн — вручну її рахувати не потрібно. Про те, як отримати баланс USDT одним викликом, є окремий розбір.

Codex CLI: config.toml і команда codex mcp add

Codex стоїть осібно: його конфіг — це TOML, а не JSON, і лежить він у ~/.codex/config.toml. Структура інша, але сенс той самий. Локально сервер найпростіше додати командою:

codex mcp add ton -- npx -y @tonnode/mcp

У файлі це виглядає так:

[mcp_servers.ton]
command = "npx"
args = ["-y", "@tonnode/mcp"]

Для hosted-ендпоінту Codex налаштовується лише через config.toml — готовий блок з url і заголовком Authorization показано в розділі про hosted-ключ нижче. Якщо правите TOML руками, майте на увазі, що синтаксис тут — не фігурні дужки, а секції у квадратних, тож механічно копіювати JSON із Cursor сюди не можна. Після додавання запустіть codex і попросіть викликати get_masterchain_info — відповідь із seqno підтвердить підключення.

Коли переходити на hosted-ключ mcp.tonnode.io і як його підставити

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

Різницю видно на простому кейсі. Припустимо, агент раз на хвилину обходить список із пів сотні гаманців і для кожного кличе get_balance плюс get_jetton_balance — це вже близько сотні викликів за прохід. На публічному конфігу такий цикл майже гарантовано впреться в ліміт приблизно один запит на секунду: частина адрес поверне not ready, частина відвалиться за таймаутом, і агенту доведеться повторювати запити, ще сильніше навантажуючи спільний лайтсервер. На hosted-ендпоінті з власним ключем та сама сотня викликів вкладається у виділену вам пропускну здатність, а історія і стан акаунтів віддаються стабільно, без гонки за спільний ресурс.

Тоді час переходити на hosted-ендпоінт mcp.tonnode.io зі своїм ключем і гарантованою пропускною здатністю. Ключ формату tn_live_… — це Bearer-токен до https://mcp.tonnode.io/mcp. Hosted-конфіг відрізняється транспортом: замість запуску процесу вказуємо HTTP і заголовок авторизації:

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

Для Claude Code є команда — зверніть увагу, прапорці йдуть до імені сервера:

claude mcp add --transport http ton https://mcp.tonnode.io/mcp \
  --header "Authorization: Bearer tn_live_…"

Для Codex hosted-ендпоінт прописується в ~/.codex/config.toml — заголовок авторизації задається окремою секцією:

[mcp_servers.ton]
url = "https://mcp.tonnode.io/mcp"

[mcp_servers.ton.headers]
Authorization = "Bearer tn_live_…"

Важливий момент щодо чесності тарифів: усі 16 інструментів доступні на всіх планах, включно з безкоштовним Hobby. Ключ визначає лише пропускну здатність, а не набір інструментів. Жодних «преміум-функцій за підпискою» — платите рівно за обсяг запитів:

• Hobby — безкоштовно назавжди, 60 запитів/хв;
• Pro — $29/міс, 300 запитів/хв;
• Scale — $199/міс, 1200 запитів/хв.

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

Що робити, якщо сервер не з’явився

Підключення MCP рідко ламається складно — майже завжди причина в одній із трьох дрібниць:

• Сервера не видно у списку інструментів. Клієнт читає конфіг лише під час старту, тому після правки файлу повністю перезапустіть Claude Desktop, Cursor або перезапустіть сесію Codex. У Claude Code перевірте статус командою claude mcp list.
• Сервер падає під час запуску. Зазвичай node/npx немає в PATH — команда npx -y @tonnode/mcp у звичайному терміналі має стартувати без помилок. Якщо вона працює в терміналі, але не з клієнта, пропишіть у конфігу абсолютний шлях до npx у полі command.
• Інструменти читання повертають not ready або таймаут. Це не помилка вашого сетапу, а перевантажений публічний лайтсервер. Повторіть запит або, якщо це повторюється під навантаженням, переходьте на hosted-ключ — там виділена пропускна здатність замість спільної черги.

Окремо перевірте JSON і TOML на валідність: зайва кома в mcpServers або переплутані дужки в config.toml — найчастіша причина, через яку клієнт мовчки ігнорує сервер.

Міні-практика: інструменти, які ви викличете першими

Незалежно від клієнта, фінальна перевірка однакова — простий read-виклик. Ось типові промпти та інструменти за ними:

• «Який зараз seqno мастерчейну?» → get_masterchain_info. Голова мережі, найкращий спосіб переконатися, що MCP взагалі живий.
• «Скільки GRAM на гаманці UQ…?» → get_balance. Баланс нативної монети.
• «Скільки USDT на цій адресі?» → get_jetton_balance. Джетон-гаманець обчислюється он-чейн, знати його адресу заздалегідь не потрібно.
• «Приведи адресу EQ… до формату UQ» → parse_address. Офлайн-конвертація та перевірка форматів.

Далі можна давати агенту справжні задачі:

• «Перевір get_account_state за адресою і скажи, чи задеплоєно контракт і коли була остання транзакція.»
• «Через run_get_method виклич get_wallet_data у джетон-гаманця і розбери відповідь.» Як смикати read-only get-методи без встановлення SDK — у розборі виклику get-методу без SDK.
• «Скільки десяткових знаків у цього жетона? Виклич get_jetton_info.» (У USDT — 6, у більшості жетонів — 9; decimals потрібні, щоб правильно перерахувати raw-одиниці.)

Загальний огляд усіх можливостей MCP для TON зібрано у великому гайді.

Підсумок

Підключення агента до TON — це буквально чотири рядки JSON (або одна команда) у конфігу вашого клієнта. Локальний npx -y @tonnode/mcp запускається без встановлення і без ключа, з повним набором читання. А коли впретеся в ліміти публічних лайтсерверів — перемикаєте транспорт на hosted-ендпоінт mcp.tonnode.io і підставляєте tn_live_…, не змінюючи ані рядка в логіці агента.

Візьміть безкоштовний ключ Hobby і підставте його в конфіг за хвилину → tonnode.io/dashboard?plan=hobby. Картка не потрібна, а повний набір із 16 інструментів доступний одразу. Хочете спочатку подивитися, що саме вміє сервер, — загляньте на сторінку інструментів.