Как подключить 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 инструментов доступен сразу. Хотите сначала посмотреть, что именно умеет сервер, — загляните на страницу инструментов.