TON MCP: Claude va Cursorni TONga ulash — bosqichma-bosqich

AI agentni TON bilan biror ish qilishga koʻndirmoqchi boʻlgan har bir odam bu devorni biladi. Claudeʼdan hamyon balansini tekshirishni soʻraysiz — u halol javob beradi: tarmoqqa kirish imkoni yoʻq. Yoki bundan ham yomoni: jetton manzilini oʻylab topadi, nanotonni ton bilan chalkashtiradi va raqamlarni oʻzidan toʻqib chiqaradi. Unga ommaviy APIga curl berasiz — yuk ortishi bilan HTTP 429 Too Many Requests uchib keladi, kalitsiz esa limit taxminan sekundiga bitta soʻrov. Global configdagi ommaviy liteserverlar goh not ready deb javob beradi, goh ADNL taymauti bilan uziladi. Muammo modelda emas — agentning blokcheynga tegadigan qoʻli yoʻq, xolos. MCP unga aynan shu qoʻllarni beradi.

Quyida — bir necha daqiqada Claudeni TONga qanday ulash, shuningdek Cursor TON MCP, Claude Code va Codexni qanday sozlash: aniq configlar, npx orqali bepul ishga tushirish va limitlarga urilganingizda hosted kalitga oʻtish.

MCP nima va u TON bilan ishlash uchun agentga nima uchun kerak

MCP (Model Context Protocol) — AI agentlar tashqi vositalarni chaqiradigan ochiq standart. USBni tasavvur qiling: ilgari har bir qurilmaning oʻz ulagichi bor edi, endi esa hamma narsa uchun bitta port. MCP — agent bilan tashqi dunyo oʻrtasidagi xuddi shunday «universal ulagich». Claude Desktop, Claude Code, Cursor, ChatGPT/Codex va boshqa har qanday MCP mijozi bitta tilda gaplashadi: mijoz MCP serverga ulanadi, vositalar roʻyxatini oladi va model soʻroviga koʻra ularni chaqiradi.

Agent TON tarmogʻiga chiqa olishi uchun buni uddalaydigan MCP server kerak. Biz TONNodedan — TON uchun hosted MCP serveridan foydalanamiz. U agentga roppa-rosa 16 ta vosita beradi: tarmoqni oʻqish (balans, hisob holati, tranzaksiyalar, kontraktlarning get-metodlari, jettonlarning balanslari va metamaʼlumotlari), Omniston DEX protokoli orqali swap, atomar HTLC-eskrou boʻyicha cross-chain swaplar va hamyon generatsiyasi. Swap, cross-chain va hamyon vositalari qatʼiy non-custodial: server hech qachon tranzaksiyalarni imzolamaydi va kalitlarni saqlamaydi — u imzolanmagan TonConnect xabarlarini qaytaradi, ularni foydalanuvchining hamyoni imzolaydi.

Bu qoʻllanma uchun aloqani tekshirishga toʻrtta read-vositaning oʻzi yetadi:

• get_masterchain_info — masterchain boshi (server tirikligiga ishonch hosil qilishning eng tez usuli);
• get_balance — manzil boʻyicha GRAM balansi;
• get_jetton_balance — jetton balansi (USDT va boshqalar), jetton-hamyon on-chain hisoblanadi;
• parse_address — EQ/UQ/raw manzillarni konvertatsiya qilish va tekshirish, toʻliq oflayn.

Claudeni TONga qanday ulash: npx orqali tezkor start (bitta buyruq)

Hech narsa oʻrnatish shart emas. Lokal server bitta buyruq bilan koʻtariladi:

npx -y @tonnode/mcp

@tonnode/mcp paketi — open source (MIT), npm va GitHubʼda (tonnode/mcp) yotadi, oraliq HTTP qatlamlarisiz TONning native ADNL protokoli boʻyicha ishlaydi. Ommaviy config oʻqish vositalarining toʻliq toʻplamini bepul beradi — agent balanslarni, tranzaksiyalarni va hisoblar holatini oʻqishi hamda get-metodlarni chaqirishi uchun bu yetarli.

Mijozlarga joylashtiradigan bazaviy config quyidagicha koʻrinadi:

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

mcpServers strukturasini yodda tuting — u deyarli barcha mijozlarda bir xilda takrorlanadi. Keyingi qismda faqat uni qayerga qoʻyishni koʻrsataman. Bepul rejimning batafsil tahlili — alohida TON uchun MCP bepul qoʻllanmasida.

Lokal oʻrnatishni xohlamaysizmi? Hosted endpointga bepul Hobby kaliti tizimga kirganingizdan soʻng darhol, kartasiz beriladi — uni tonnode.io/dashboard sahifasida oling va pastdagi configga darhol joylashtiring.

Claude Desktop: claude_desktop_config.json qayerda yotadi va unga nima yozish kerak

Claude Desktop MCP configni claude_desktop_config.json faylidan oʻqiydi. Yoʻl tizimga bogʻliq:

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

Faylni oching (yoki yoʻq boʻlsa, yarating) va oʻsha mcpServers obyektini yozing:

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

Tahrirdan soʻng ilovani qayta ishga tushiring — Claude Desktop configni faqat start paytida oʻqiydi. Vositalar menyusida ton serveri paydo boʻladi. Endi chatga yozing:

get_masterchain_info vositasini chaqir va masterchain boshining seqno raqamini koʻrsat.

Agar agent blok raqamini qaytargan boʻlsa — MCP ulangan. Xuddi shunday «UQ… hamyonining balansini tekshir» deb ham soʻrash mumkin — kapot ostida get_balance ishlaydi va GRAMʼda haqiqiy raqamni qaytaradi (GRAM — 2026-yil iyunida nomi oʻzgartirilgan Toncoin; tarmoqning oʻzi hamon TON deb ataladi).

Claude Code: claude mcp add buyrugʻi va .mcp.json fayli

Claude Codeʼda server terminaldan bitta buyruq bilan qoʻshiladi — u hamma narsani kerakli faylga oʻzi yozib qoʻyadi. Lokal variant:

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

Ikkita chiziqcha -- serverni ishga tushirish buyrugʻini claudening oʻz flaglaridan ajratadi. Shundan soʻng Claude Code loyiha .mcp.json faylini yaratadi (yoki toʻldiradi). Xohlasangiz, oʻsha mcpServers obyektini faylga qoʻlda ham yozish mumkin — natija bir xil:

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

Aloqani toʻgʻridan-toʻgʻri CLIʼda tekshiring:

parse_address orqali 0:83df... manzilini user-friendly EQ/UQ formatiga keltir.

parse_address oflayn ishlaydi, shuning uchun bu eng ishonchli test: u tarmoq holatiga bogʻliq emas va vositalar agentga koʻrinayotganini bir zumda koʻrsatadi.

Cursor: .cursor/mcp.json fayli (loyiha va global)

Claude Desktopni allaqachon sozlaganlar uchun yoqimli xabar: Cursor xuddi oʻsha mcpServers formatidan foydalanadi. Config aynan bir xil koʻchiriladi — hech narsani qayta yozish kerak emas. Farq faqat faylning joylashuvida:

• loyiha ildizidagi .cursor/mcp.json — server faqat shu loyihada koʻrinadi;
• ~/.cursor/mcp.json — global, barcha loyihalarda.

Konflikt boʻlganda loyiha fayli ustun keladi. Unga quyidagini joylaymiz:

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

Mana shu — Cursor TON MCP sozlamasining hammasi: bitta fayl, toʻrt qator foydali yuk. Saqlagandan soʻng Settings → MCP boʻlimida ton Enabled holatida ekanini tekshiring va toʻgʻridan-toʻgʻri muharrirda agentdan soʻrang:

EQ... hamyonida qancha USDT bor? get_jetton_balance vositasini chaqir.

get_jetton_balance jetton-hamyon manzilini on-chain oʻzi hisoblaydi — uni qoʻlda hisoblash shart emas. USDT balansini bitta chaqiruv bilan olish haqida alohida tahlil bor.

Codex CLI: config.toml va codex mcp add buyrugʻi

Codex alohida turadi: uning configi — JSON emas, TOML, va u ~/.codex/config.toml da yotadi. Struktura boshqacha, maʼnosi esa oʻsha. Lokal serverni qoʻshishning eng oson yoʻli — buyruq:

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

Faylda bu shunday koʻrinadi:

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

Hosted endpoint uchun Codex faqat config.toml orqali sozlanadi — url va Authorization sarlavhasi bilan tayyor blok quyida hosted kalit haqidagi boʻlimda koʻrsatilgan. TOMLni qoʻlda tahrirlasangiz, bu yerda sintaksis figurali qavslar emas, balki kvadrat qavslardagi seksiyalar ekanini yodda tuting, shuning uchun Cursordan JSONni mexanik ravishda bu yerga koʻchirib boʻlmaydi. Qoʻshgandan soʻng codex ni ishga tushiring va get_masterchain_info ni chaqirishni soʻrang — seqno bilan kelgan javob ulanishni tasdiqlaydi.

Qachon mcp.tonnode.io hosted kalitiga oʻtish kerak va uni qanday qoʻyish kerak

Lokal npx server sinab koʻrish va prototip yigʻish uchun juda mos. Lekin uning ham chegarasi bor: u global configdagi ommaviy TON liteserverlari orqali ishlaydi. Ular umumiy va limitli — yuk ostida koʻpincha not ready deb javob beradi yoki ADNL taymautiga ketadi, hamda chuqur tarixni saqlamaydi. Agent jiddiy ishlay boshlashi bilan — foydalanuvchilarga xizmat koʻrsatsa, balanslarni sikl ichida soʻrasa, oʻnlab get-metodlarni chaqirsa — siz shu limitlarga urilasiz.

Farq oddiy keysda koʻrinadi. Aytaylik, agent daqiqada bir marta ellikta hamyondan iborat roʻyxatni aylanib chiqadi va har biri uchun get_balance va get_jetton_balance ni chaqiradi — bu bitta aylanishda taxminan yuzta chaqiruv. Ommaviy configda bunday sikl deyarli muqarrar tarzda sekundiga taxminan bitta soʻrov limitiga uriladi: manzillarning bir qismi not ready qaytaradi, bir qismi taymaut boʻyicha uziladi, agentga esa soʻrovlarni takrorlashga toʻgʻri keladi va bu umumiy liteserverni yanada koʻproq yuklaydi. Oʻz kalitingiz bilan hosted endpointda oʻsha yuzta chaqiruv sizga ajratilgan oʻtkazuvchanlikka bemalol sigʻadi, hisoblar tarixi va holati esa umumiy resurs uchun poyga qilmasdan, barqaror beriladi.

Demak, oʻz kalitingiz va kafolatlangan oʻtkazuvchanlik bilan mcp.tonnode.io hosted endpointiga oʻtish vaqti keldi. tn_live_… formatidagi kalit — bu https://mcp.tonnode.io/mcp uchun Bearer token. Hosted config transporti bilan farq qiladi: jarayonni ishga tushirish oʻrniga HTTP va avtorizatsiya sarlavhasini koʻrsatamiz:

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

Claude Code uchun buyruq bor — eʼtibor bering, flaglar server nomidan oldin keladi:

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

Codex uchun hosted endpoint ~/.codex/config.toml ga yoziladi — avtorizatsiya sarlavhasi alohida seksiya bilan beriladi:

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

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

Tariflar halolligi haqida muhim jihat: 16 ta vositaning hammasi barcha tariflarda, jumladan bepul Hobbyʼda ham mavjud. Kalit faqat oʻtkazuvchanlikni belgilaydi, vositalar toʻplamini emas. Hech qanday «obuna ortidagi premium funksiyalar» yoʻq — siz roppa-rosa soʻrovlar oʻtkazuvchanligi uchun toʻlaysiz:

• Hobby — abadiy bepul, daqiqasiga 60 soʻrov;
• Pro — $29/oy, daqiqasiga 300 soʻrov;
• Scale — $199/oy, daqiqasiga 1200 soʻrov.

Bepul Hobby kaliti dashboardga kirganingizdan soʻng darhol, kartasiz beriladi. Yaʼni daqiqasiga 60 soʻrov yetarli boʻlgunicha lokal rejimdan hostedga oʻtish bir tiyin ham turmaydi — bu esa ommaviy liteserverlardan sezilarli darajada ishonchliroq.

Server paydo boʻlmasa nima qilish kerak

MCP ulanishi kamdan kam hollarda jiddiy buziladi — deyarli har doim gap uchta mayda narsadan birida:

• Server vositalar roʻyxatida koʻrinmayapti. Mijoz configni faqat start paytida oʻqiydi, shuning uchun faylni tahrirlagandan soʻng Claude Desktop yoki Cursorni toʻliq qayta ishga tushiring, Codexda esa sessiyani qaytadan boshlang. Claude Codeʼda statusni claude mcp list buyrugʻi bilan tekshiring.
• Server ishga tushishda yiqilyapti. Odatda node/npx PATHda boʻlmaydi — npx -y @tonnode/mcp buyrugʻi oddiy terminalda xatosiz ishga tushishi kerak. Agar u terminalda ishlasa-yu, mijozdan ishlamasa, configning command maydoniga npx ning toʻliq (absolyut) yoʻlini yozing.
• Oʻqish vositalari not ready yoki taymaut qaytaryapti. Bu sizning sozlamangizdagi xato emas, balki haddan tashqari yuklangan ommaviy liteserver. Soʻrovni takrorlang yoki, agar bu yuk ostida takrorlanaversa, hosted kalitga oʻting — u yerda umumiy navbat oʻrniga ajratilgan oʻtkazuvchanlik bor.

Alohida ravishda JSON va TOML sintaksisining toʻgʻriligini tekshiring: mcpServers dagi ortiqcha vergul yoki config.toml dagi chalkashtirilgan qavslar — mijoz serverni jimgina eʼtiborsiz qoldirishining eng koʻp uchraydigan sababi.

Mini-amaliyot: birinchi boʻlib chaqiradigan vositalaringiz

Mijozdan qatʼi nazar, yakuniy tekshiruv bir xil — oddiy read-chaqiruv. Mana tipik promptlar va ular ortidagi vositalar:

• «Hozir masterchain seqnosi qanday?» → get_masterchain_info. Tarmoq boshi, MCP umuman tirikligiga ishonch hosil qilishning eng yaxshi usuli.
• «UQ… hamyonida qancha GRAM bor?» → get_balance. Native tanganing balansi.
• «Bu manzilda qancha USDT bor?» → get_jetton_balance. Jetton-hamyon on-chain hisoblanadi, uning manzilini oldindan bilish shart emas.
• «EQ… manzilini UQ formatiga keltir» → parse_address. Formatlarni oflayn konvertatsiya qilish va tekshirish.

Keyin agentga haqiqiy vazifalarni berish mumkin:

• «Manzil boʻyicha get_account_state ni tekshir va kontrakt deploy qilinganmi hamda oxirgi tranzaksiya qachon boʻlganini ayt.»
• «run_get_method orqali jetton-hamyonning get_wallet_data metodini chaqir va javobni ajratib ber.» SDK oʻrnatmasdan read-only get-metodlarni qanday chaqirish mumkinligi — SDKsiz get-metod chaqiruvi tahlilida.
• «Bu jettonda nechta oʻnlik xona bor? get_jetton_info ni chaqir.» (USDTʼda — 6 ta, koʻpchilik jettonlarda — 9 ta; decimals raw birliklarni toʻgʻri qayta hisoblash uchun kerak.)

TON uchun MCPning barcha imkoniyatlari haqidagi umumiy sharh katta qoʻllanmada jamlangan.

Xulosa

Agentni TONga ulash — bu tom maʼnoda mijozingiz configidagi toʻrt qator JSON (yoki bitta buyruq). Lokal npx -y @tonnode/mcp oʻrnatishsiz va kalitsiz, oʻqishning toʻliq toʻplami bilan ishga tushadi. Ommaviy liteserverlar limitiga urilganingizda esa transportni mcp.tonnode.io hosted endpointiga oʻzgartirasiz va tn_live_… ni qoʻyasiz — agent logikasidagi bironta qatorni ham oʻzgartirmasdan.

Bepul Hobby kalitini oling va uni bir daqiqada configga qoʻying → tonnode.io/dashboard?plan=hobby. Karta kerak emas, 16 ta vositaning toʻliq toʻplami esa darhol mavjud. Avval server aynan nimalarni uddalashini koʻrmoqchi boʻlsangiz — vositalar sahifasiga kiring.