Hipo MCP Server

Що таке Hipo MCP Server?

Hipo MCP Server — це невеликий сервіс із відкритим кодом, який дозволяє AI-асистентам діставатися до даних, пов’язаних із Hipo, зокрема до інформації про стейкінг GRAM та інші теми. Він говорить мовою Model Context Protocol (MCP) — відкритого стандарту для підключення AI-клієнтів до зовнішніх даних, тож будь-який клієнт із підтримкою MCP (Claude, Claude Code, Cursor та інші) може зазирнути в документацію Hipo й запитати живі ончейн-цифри замість того, щоб вгадувати з пам’яті.

Щойно сервер підключено, твій асистент зможе відповідати на запитання на кшталт:

Який зараз курс обміну hGRAM/GRAM і який APY із нього випливає?
Скільки GRAM зараз у стейкінгу в Hipo?
Коли завершується поточний раунд валідації і коли мій відкладений внесок перетвориться на hGRAM?
Який баланс hGRAM у цієї адреси й скільки він коштує в GRAM?
Яку комісію за газ додати до внеску?

Відповіді беруться з геттерів смартконтрактів Hipo у мережі TON, а не з даних навчання моделі, тож вони актуальні на момент запиту.

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

Підключення

Хостований сервер (рекомендовано)

Hipo запускає публічний інстанс. Спрямуй свій MCP-клієнт на:

https://mcp.hipo.finance/mcp

У Claude Code достатньо однієї команди:

claude mcp add --transport http hipo https://mcp.hipo.finance/mcp

Так сервер реєструється для поточного проєкту. Щоб діставатися до нього з усіх проєктів, додай -s user — тут user є буквальним ключовим словом області видимості, а не заповнювачем для твого імені користувача:

claude mcp add -s user --transport http hipo https://mcp.hipo.finance/mcp

У будь-якому разі користуйся командою, а не правкою файлу конфігурації вручну: Claude Code зберігає свої MCP-сервери у власному конфігу, а блок mcpServers, вкинутий у settings.json, ігнорується. Виконай claude mcp list, щоб переконатися, що сервер підключено, і перезапусти Claude Code — сервери підключаються під час запуску, тож щойно доданий не буде доступний у сесії, яка вже працює.

Інші клієнти налаштовуються через JSON-файл (Claude Desktop, Cursor і більшість решти) і приймають приблизно такий запис:

{
  "mcpServers": {
    "hipo": {
      "type": "http",
      "url": "https://mcp.hipo.finance/mcp"
    }
  }
}

Запуск локально

Якщо ти волієш запустити сервер сам, він опублікований у npm як @hipo-finance/mcp і працює через stdio. Для цього потрібен Node.js 20 або новіший:

claude mcp add hipo -- npx -y @hipo-finance/mcp

Тут діє та сама порада — додавай командою, а не правкою файлу вручну. Для інших клієнтів запис конфігурації у JSON такий:

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

Інструменти

Ось запитання, на які сервер може відповісти. Твій AI-клієнт сам обирає потрібний інструмент — ти питаєш звичайною мовою.

Інструмент	Що він повертає
`get_exchange_rate`	Поточний курс hGRAM↔GRAM, загальний обсяг GRAM у стейкінгу, емісію hGRAM і нещодавній APY, виведений з ончейн-оновлень курсу
`get_treasury_state`	Підсумки скарбниці: TVL у GRAM, емісія hGRAM, внески та анстейки в обробці, участі в активних раундах, прапорець зупинки й параметри управління
`get_round_timing`	Тайминг раунду валідації: межі поточного та наступного раундів, вікно участі у виборах і те, як довго внески лишаються замороженими
`get_fees`	Поточні комісії за газ для внеску, анстейку та запитів на позику
`get_wallet_status`	Баланс hGRAM вказаної адреси, його вартість у GRAM і будь-які внески чи анстейки в обробці
`get_reward_history`	Історичні винагороди вказаної адреси за стейкінг GRAM за кожен раунд, включно з рівнем у Hipo Club і винагородами в HPO
`get_participation`	Участь Hipo в раунді валідації: стан, кількість позик, підсумки та час вивільнення внесків
`get_loan_info`	Контракт позики позичальника за раунд: адреса, стан розгортання, баланс і сторони
`get_max_punishment`	Максимальне покарання, яке протокол може застосувати до заданого внеску валідатора

Першим чотирьом інструментам взагалі не потрібні вхідні дані. get_wallet_status, get_reward_history і get_loan_info приймають адресу TON — власну адресу власника чи позичальника, а не адресу їхнього жетон-гаманця — а get_max_punishment приймає суму внеску в GRAM. get_participation і get_loan_info також приймають час початку раунду, але це необов’язково: якщо його не вказати, вони звітують про поточний раунд.

Кожна відповідь містить те саме нагадування: інструменти повертають живі дані протоколу, а не фінансову пораду; значення змінюються щораунду валідації, і жодної дохідності не гарантовано.

Ресурси документації

Поряд із живими даними сервер надає технічні документи Hipo як MCP-ресурси, які завантажуються з їхніх канонічних публічних адрес, тож вони завжди актуальні:

Ресурс	Вміст
`hipo://docs/overview`	README репозиторію смартконтрактів: огляд протоколу й адреси розгорнутих контрактів
`hipo://docs/architecture`	Контракти, стейт-машина раунду валідації та інваріанти протоколу
`hipo://docs/integration`	Схеми повідомлень і посібник з інтеграції для гаманців та інших протоколів
`hipo://docs/schema`	Повні TL-B схеми всіх контрактів Hipo
`hipo://docs/knowledge`	Впорядкована база знань Hipo (llms.txt)

Приклад

Виклик get_exchange_rate повертає звичайний JSON. Цифри змінюються щораунду, тож сприймай їх як форму відповіді, а не як поточні значення:

{
  "oneHgramInGram": "1.143623345",
  "oneGramInHgram": "0.874413769",
  "totalCoinsGram": "2501952.200844389",
  "totalTokensHgram": "2187741.455006677",
  "recentApy": "15.59%",
  "apyNote": "APY is derived from the last on-chain rate update (current_rate / previous_rate compounded to a year). Rewards accrue in the exchange rate: hGRAM becomes worth more GRAM over time; there is no separate claim.",
  "disclaimer": "Live protocol data, not financial advice. Values change every validation round and no returns are guaranteed."
}

Сервер ніколи не переписує математику протоколу заново. Кожна цифра вище приходить із геттера контракту, а джерелом істини щодо розгорнутих адрес є репозиторій контрактів.

Самостійний хостинг

Сервер має ліцензію MIT і живе за адресою github.com/HipoFinance/mcp. Він постачається з двома транспортами — stdio для локальних клієнтів і streamable HTTP для хостованого розгортання — а також із Dockerfile:

docker build -t hipo-mcp .
docker run -p 3000:3000 -e TONCENTER_API_KEY=... hipo-mcp

Уся конфігурація необов’язкова; типові налаштування націлені на основну мережу через публічний API toncenter.

Змінна середовища	Типове значення	Призначення
`HIPO_NETWORK`	`mainnet`	`mainnet` або `testnet`
`TONCENTER_ENDPOINT`	`https://toncenter.com/api/v2/jsonRPC`	Ендпоїнт TON HTTP API
`TONCENTER_API_KEY`	(немає)	Ключ API toncenter; без нього діє публічний ліміт запитів, а обмежені запити повторюються з відкладанням
`TONCENTER_API_KEY_FILE`	(немає)	Шлях до файлу з ключем API, наприклад секрет Docker; має пріоритет над `TONCENTER_API_KEY`
`HIPO_STATE_CACHE_SECONDS`	`5`	Як довго стан скарбниці, час і комісії кешуються між викликами інструментів
`HIPO_DOCS_CACHE_SECONDS`	`300`	Як довго кешуються ресурси документації
`HIPO_REWARDS_API_BASE`	`https://api.hipogang.io`	Базовий URL API винагород Hipo; залиш порожнім, щоб вимкнути `get_reward_history`
`PORT` / `HOST`	`3000` / `0.0.0.0`	Лише для HTTP-транспорту