TON MCP: Claude мен Cursor-ды TON-ға қосу — қадамдық нұсқаулық

AI-агентке TON-мен бірдеңе істетіп көрген әркім осы тығырықты біледі. Claude-тан әмиян балансын тексеруді сұрайсың — ол шынын айтып, желіге қол жеткізе алмайтынын хабарлайды, немесе одан да жаманы: жеттон мекенжайын ойдан шығарады, нанотонды тонмен шатастырады да, сандарды жоқтан ойлап табады. Оған ашық API-ге curl бересің — жүктеме артқанда жауап ретінде 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) — AI-агенттер сыртқы құралдарды шақыратын ашық стандарт. USB-ны елестетіңіз: бұрын әр құрылғының өз ағытпасы болатын, енді бәріне бір-ақ порт. MCP — агент пен сыртқы дүние арасындағы дәл сондай «бірыңғай ағытпа». Claude Desktop, Claude Code, Cursor, ChatGPT/Codex және кез келген басқа MCP-клиент бір тілде сөйлейді: клиент MCP-серверге қосылады, құралдар тізімін алады және модельдің сұрауы бойынша оларды шақырады.

Агент TON желісіне шыға алуы үшін соны істей алатын MCP-сервер керек. Біз TONNode-ты аламыз — бұл TON-ға арналған hosted MCP-сервер. Ол агентке дәл 16 құрал береді: желіні оқу (баланс, аккаунт күйі, транзакциялар, контрактілердің get-әдістері, жеттондардың балансы мен метадеректері), Omniston DEX-протоколы арқылы своп, атомарлы 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) жатыр, аралық HTTP-қабаттарсыз TON-ның нативті ADNL-протоколы бойынша жұмыс істейді. Ашық конфиг оқу құралдарының толық жинағын тегін береді — агент баланстарды, транзакцияларды, аккаунт күйлерін оқып, get-әдістерді шақыруы үшін бұл жеткілікті.

Клиенттерге қоятын базалық конфиг былай көрінеді:

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

mcpServers құрылымын есте сақтаңыз — ол барлық дерлік клиенттерде бірдей қайталанады. Әрі қарай оны қайда салу керектігін ғана көрсетемін. Тегін режимнің толық талдауы — жеке TON үшін MCP тегін нұсқаулығында.

Локал орнатқыңыз келмей ме? Hosted-эндпоинтке арналған тегін Hobby кілті жүйеге кірген бойда, картасыз беріледі — оны 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 күйінде тұрғанын тексеріңіз де, агенттен редактордың дәл өзінде сұраңыз:

EQ... әмиянында қанша USDT бар? get_jetton_balance шақыр.

get_jetton_balance жеттон-әмиянның мекенжайын он-чейн өзі есептейді — оны қолмен санаудың қажеті жоқ. USDT балансын бір шақырумен алу туралы бөлек талдау бар.

Codex CLI: config.toml және codex mcp add пәрмені

Codex бөлек тұрады: оның конфигі — JSON емес, TOML, әрі ол ~/.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-ды қолмен түзетсеңіз, мұндағы синтаксис фигуралық жақшалар емес, тік жақшадағы секциялар екенін есте ұстаңыз — сондықтан Cursor-дан JSON-ды механикалық түрде мұнда көшіруге болмайды. Қосқаннан кейін codex іске қосып, get_masterchain_info шақыруды сұраңыз — seqno-мен келген жауап қосылымды растайды.

mcp.tonnode.io hosted-кілтіне қашан көшу керек және оны қалай қою керек

Локал npx-сервер сынап көру мен прототип жинауға тамаша келеді. Бірақ оның да шегі бар: ол глобал конфигтегі ашық TON лайтсерверлері арқылы жүреді. Олар ортақ әрі лимитті — жүктеме кезінде жиі not ready деп жауап береді немесе ADNL-таймаутқа кетеді, әрі терең тарихты сақтамайды. Агент шындап жұмыс істей бастағанда — пайдаланушыларға қызмет көрсеткенде, циклмен баланстарды сұрағанда, ондаған get-әдісті шақырғанда — сіз осы лимиттерге тірелесіз.

Айырмашылық қарапайым кейстен көрінеді. Айталық, агент минутына бір рет елу шақты әмияннан тұратын тізімді аралап, әрқайсысы бойынша get_balance мен get_jetton_balance шақырады — бұл бір өтуде жүзге жуық шақыру. Ашық конфигте мұндай цикл секундына шамамен бір сұрау лимитіне міндетті түрде дерлік тіреледі: мекенжайлардың бір бөлігі not ready қайтарады, бір бөлігі таймаутпен үзіледі, ал агентке сұрауларды қайталауға тура келеді — бұл ортақ лайтсерверді бұрынғыдан да қатты жүктейді. Өз кілтіңіз бар hosted-эндпоинтте дәл сол жүз шақыру сізге бөлінген өткізу қабілетіне сыйып кетеді, ал аккаунттардың тарихы мен күйі ортақ ресурс үшін жарыспай, тұрақты беріледі.

Демек, mcp.tonnode.io hosted-эндпоинтіне өз кілтіңізбен және кепілді өткізу қабілетімен көшетін кез келді. tn_live_… форматындағы кілт — https://mcp.tonnode.io/mcp мекенжайына арналған Bearer-токен. 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 кілті дашбордқа кірген бойда, картасыз беріледі. Яғни минутына 60 сұрау жеткілікті болып тұрғанда, локал режимнен hosted-ке көшу бір тиын да тұрмайды — әрі бұл ашық лайтсерверлерден әлдеқайда сенімді.

Сервер пайда болмаса не істеу керек

MCP қосылымының ақауы сирек күрделі болады — әрдайым дерлік мәселе үш ұсақ нәрсенің бірінде:

• Сервер құралдар тізімінде көрінбейді. Клиент конфигті тек старт кезінде оқиды, сондықтан файлды түзеткеннен кейін Claude Desktop немесе Cursor-ды толықтай қайта іске қосыңыз, не Codex сессиясын қайта бастаңыз. Claude Code-та күйді claude mcp list пәрменімен тексеріңіз.
• Сервер іске қосылғанда құлайды. Әдетте node/npx PATH-та жоқ — npx -y @tonnode/mcp пәрмені кәдімгі терминалда қатесіз стартауы керек. Егер ол терминалда істеп, клиенттен істемесе, конфигтегі command өрісіне npx-тің абсолют жолын жазыңыз.
• Оқу құралдары not ready немесе таймаут қайтарады. Бұл сіздің сетапыңыздың қатесі емес, шамадан тыс жүктелген ашық лайтсервер. Сұрауды қайталаңыз, ал егер бұл жүктеме кезінде қайталана берсе — hosted-кілтке көшіңіз: онда ортақ кезектің орнына сізге бөлінген өткізу қабілеті болады.

Сонымен қатар JSON мен TOML синтаксисінің дұрыстығын бөлек тексеріңіз: mcpServers ішіндегі артық үтір немесе config.toml ішінде шатасқан жақшалар — клиенттің серверді үнсіз елемеуінің ең жиі себебі.

Шағын практика: алдымен шақыратын құралдарыңыз

Клиентке қарамастан, соңғы тексеру бірдей — қарапайым read-шақыру. Міне, типтік промптар және олардың артындағы құралдар:

• «Қазір мастерчейннің seqno-сы қанша?» → get_masterchain_info. Желінің басы, MCP-дің тірі екеніне көз жеткізудің ең жақсы тәсілі.
• «UQ… әмиянында қанша GRAM бар?» → get_balance. Нативті монетаның балансы.
• «Осы мекенжайда қанша USDT бар?» → get_jetton_balance. Жеттон-әмиян он-чейн есептеледі, оның мекенжайын алдын ала білудің қажеті жоқ.
• «EQ… мекенжайын UQ форматына келтір» → parse_address. Форматтарды офлайн конвертациялау және тексеру.

Әрі қарай агентке нағыз тапсырмалар беруге болады:

• «Мекенжай бойынша get_account_state тексер де, контракт деплой болған-болмағанын және соңғы транзакция қашан болғанын айт.»
• «run_get_method арқылы жеттон-әмиянның get_wallet_data әдісін шақыр да, жауабын талда.» SDK орнатпай read-only get-әдістерді қалай шақыруға болатыны — SDK-сыз get-әдісті шақыру талдауында.
• «Бұл жеттонда неше ондық белгі бар? get_jetton_info шақыр.» (USDT-де — 6, жеттондардың көбінде — 9; decimals raw-бірліктерді дұрыс қайта есептеу үшін керек.)

TON үшін MCP мүмкіндіктерінің жалпы шолуы үлкен нұсқаулықта жинақталған.

Қорытынды

Агентті TON-ға қосу — бұл клиентіңіздің конфигіндегі небәрі төрт жол JSON (немесе бір ғана пәрмен). Локал npx -y @tonnode/mcp орнатусыз әрі кілтсіз іске қосылады, оқудың толық жинағымен. Ал ашық лайтсерверлердің лимитіне тірелгенде — транспортты mcp.tonnode.io hosted-эндпоинтіне ауыстырып, tn_live_… кілтін қоясыз, агент логикасында бірде-бір жолды өзгертпей.

Тегін Hobby кілтін алып, оны бір минутта конфигке қойыңыз → tonnode.io/dashboard?plan=hobby. Карта керек емес, ал 16 құралдан тұратын толық жинақ бірден қолжетімді. Сервердің нақты не істей алатынын алдымен көргіңіз келсе — құралдар бетіне кіріңіз.