Що це і навіщо
MCP (Model Context Protocol) — відкритий стандарт від Anthropic для підключення AI-моделей до зовнішніх систем. Один сервер описує свої можливості (tools), і будь-який MCP-сумісний клієнт одразу може ними користуватись — без окремих інтеграцій під кожну модель.
Офіційний MCP «Сільпо» дає AI-агенту повний доступ до e-commerce платформи «Сільпо» від імені гостя: пошук товарів, наповнення кошика, доставка, історія замовлень, бонуси та сертифікати. Це технологічна основа хакатону — усі рішення учасників мають взаємодіяти саме через нього.
- «Додай у кошик 2 літри молока, буханець хліба і десяток яєць»
- «Покажи мої останні 5 замовлень»
- «Які акції доступні на мою адресу доставки?»
- «Застосуй мої балабонуси до поточного кошика»
- «Знайди заміну товару, якого немає в наявності»
Швидкий старт
Додай MCP-сервер у конфіг свого клієнта. На першому підключенні відкриється браузер — увійди в акаунт «Сільпо», і все.
{
"mcpServers": {
"silpo": {
"url": "https://mcp.silpo.ua/mcp"
}
}
}Підключення клієнтів
| Клієнт | Як підключити |
|---|---|
| Claude Desktop | Додай URL https://mcp.silpo.ua/mcp у секцію mcpServers конфіга. |
| Claude Code | claude mcp add --transport http silpo https://mcp.silpo.ua/mcp |
| Cursor | Додай https://mcp.silpo.ua/mcp у налаштування MCP-серверів. |
| Kiro CLI | Додай URL у конфігурацію mcpServers. |
TypeScript SDK
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport }
from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(
new URL("https://mcp.silpo.ua/mcp"),
{ authProvider: mySilpoAuthProvider },
);
const client = new Client(
{ name: "hackathon-agent", version: "0.1.0" },
{ capabilities: {} },
);
await client.connect(transport);
const { tools } = await client.listTools();Vercel AI SDK
import { createMCPClient } from "@ai-sdk/mcp";
const mcp = await createMCPClient({
transport: {
type: "http",
url: "https://mcp.silpo.ua/mcp",
authProvider: mySilpoAuthProvider,
},
});
const tools = await mcp.tools();
const result = await streamText({
model: openai("gpt-4o"),
tools,
prompt: "Знайди варіанти вечері з молочних продуктів до 300 грн",
});Python SDK
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(
"https://mcp.silpo.ua/mcp",
auth=my_oauth_provider,
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()Як працює авторизація
Сервер використовує OAuth 2.1 (Authorization Code + PKCE). Для AI-клієнта процес майже повністю автоматичний: гість авторизується в акаунті «Сільпо» один раз, а далі клієнт сам поновлює доступ.
Перше підключення
- Клієнт отримує
401і читає метадані OAuth-сервера з/.well-known/oauth-authorization-server. - Реєструється через Dynamic Client Registration (
POST /register). - Генерує PKCE-пару та відкриває
/authorizeу браузері. - Гість логіниться на
auth.silpo.ua(телефон + OTP або пароль). - Після успішної авторизації клієнт отримує MCP-токен і використовує його в усіх запитах:
Authorization: Bearer <mcp_token>.
Безпека: AI-клієнт ніколи не бачить Silpo JWT гостя — він залишається всередині інфраструктури «Сільпо».
Доступні tools (39)
Усі tools потребують авторизації. Позначка 🔒 cart означає, що потрібен контекст кошика (branchId, deliveryType, timeslot) — отримай його через silpo_get_my_shopping_cart → silpo_get_shopping_cart_by_id. Позначка ✎ write — tool змінює стан.
Локація та доставка (6)
silpo_find_addressЗнайти координати (lat/lng) за текстом адреси. Перший крок при зміні адреси доставки.
silpo_get_available_delivery_typesДоступні типи доставки для координат: DeliveryHome, WideAssortDelivery, SelfPickup, NovaPoshta, B2B.
silpo_list_branchesСписок магазинів «Сільпо». Фільтри: hasPickup, hasNovaPoshta.
silpo_get_time_slotsДоступні слоти доставки для магазину. ОБОВ'ЯЗКОВО викликати після отримання кошика — валідувати слот.
silpo_find_nova_poshta_settlementsПошук населеного пункту Нової Пошти за назвою.
silpo_find_nova_poshta_officesВідділення / поштомати НП у населеному пункті.
Пошук товарів (7)
silpo_find_products_batch🔒 cartПошук до 30 товарів паралельно. Основний tool для заповнення кошика зі списку покупок.
silpo_get_products🔒 cartТовари з фільтрами: категорія, акція, пошуковий запит, пагінація.
silpo_get_product_details🔒 cartПовна картка товару: склад, харчова цінність, атрибути, зображення.
silpo_get_similar_products🔒 cartСхожі / альтернативні товари за slug.
silpo_get_replacements🔒 cartЗаміни для товарів, яких немає в наявності.
silpo_get_my_favoritesСписок збережених «улюблених» товарів гостя.
silpo_add_or_update_favorite_products✎ writeДодати / прибрати товари з улюблених.
Каталог (6)
silpo_get_promotions🔒 cartАктивні акції та знижки в конкретному магазині.
silpo_get_popular_categories🔒 cartПопулярні категорії в магазині.
silpo_get_category🔒 cartДеталі окремої категорії: підкатегорії, кількість товарів.
silpo_get_categoriesПлоский список усіх категорій магазину.
silpo_get_categories_tree🔒 cartПовне дерево категорій та підкатегорій.
silpo_get_product_setsКураторські добірки товарів (тематичні, сезонні).
Кошик (7)
Кошик — центральний об'єкт. Рекомендований старт сесії: silpo_get_my_shopping_cart → silpo_get_shopping_cart_by_id → silpo_get_time_slots.
silpo_get_my_shopping_cartОтримати ID активного кошика. Завжди перший крок.
silpo_get_shopping_cart_by_idПовний кошик: товари, доставка, тайм-слот, суми, валідації, бонуси, посилання на checkout.
silpo_add_or_update_cart_products✎ writeДодати товари або оновити кількість. Потрібні productId + companyId + branchId з пошуку.
silpo_remove_cart_products✎ writeВидалити конкретні товари з кошика.
silpo_clear_shopping_cart✎ writeОчистити весь кошик.
silpo_update_shopping_cart✎ writeОновити доставку, слот, адресу, промокод, спосіб оплати, застосувати бонуси.
silpo_add_or_update_certificates✎ writeДодати або зняти подарункові сертифікати з кошика.
Замовлення (2)
silpo_get_my_online_ordersІсторія онлайн-замовлень (silpo.ua / застосунок). Дає змогу повторити замовлення одним викликом cart.add.
silpo_get_my_offline_ordersІсторія покупок у фізичних магазинах: чеки, товари, знижки, зароблені бонуси.
Профіль (4)
silpo_get_my_profileДані профілю: ім'я, телефон, email, дата народження.
silpo_get_my_delivery_addressesЗбережені адреси доставки гостя.
silpo_get_my_familyЧлени родини у профілі: діти (з віком) і тварини.
silpo_get_my_food_restrictionsДієтичні обмеження та харчові уподобання.
Лояльність та акції (7)
silpo_get_loyalty_infoКартка «Власний Рахунок»: номер, статус, поточний та нарахований баланс балабонусів.
silpo_get_my_couponsДоступні купони знижок гостя.
silpo_get_coupon_detailsПовна інформація про купон: умови, товари, штрих-код.
silpo_get_my_promosПерсональні промо-пропозиції.
silpo_get_promo_codesАктивні промокоди гостя.
silpo_get_my_certificatesАктивні подарункові сертифікати: код, штрих-код, номінал.
silpo_get_my_premium_subscriptionСтатус Silpo Premium: активність, дата завершення, переваги.
tools/listТочні назви, аргументи та JSON Schema завжди повертає сам сервер після авторизації. Читай tools/list на старті агента — це стандартна MCP-практика.
Типові сценарії
Наповнити кошик зі списку покупок
1. silpo_get_my_shopping_cart → cartId
2. silpo_get_shopping_cart_by_id → branchId, deliveryType, timeslot
3. silpo_get_time_slots ← обов'язково: валідація слота
4. silpo_find_products_batch(items[]) → productId + companyId + branchId
5. silpo_add_or_update_cart_products → додати все
6. silpo_get_shopping_cart_by_id ← перевірити результат
• перевірити validations[]
• якщо loyalty.bonusAvailable > 0 — запропонувати балабонуси
• якщо express доступний — підсвітити варіант і ціну
• показати checkoutWebLink + checkoutMobileLinkЗмінити адресу доставки
1. silpo_find_address(text) → lat, lng
2. silpo_get_available_delivery_types(lat, lng) → варіанти доставки
├─ DeliveryHome / WideAssortDelivery: branchId в відповіді → крок 3
├─ SelfPickup: silpo_list_branches(hasPickup=true) → гість обирає
└─ NovaPoshta: silpo_find_nova_poshta_settlements(city)
silpo_find_nova_poshta_offices(settlementId)
silpo_list_branches(hasNovaPoshta=true)
3. silpo_get_time_slots(branchId, deliveryType) → гість обирає слот
4. silpo_update_shopping_cart(...) → застосувати
5. silpo_get_shopping_cart_by_id ← перевіритиЗастосувати балабонуси
Після silpo_get_shopping_cart_by_id:
якщо loyalty.bonusAvailable > 0
і loyalty.bonusRequested == null
і loyalty.isEnabled:
→ запитати: «У вас є {bonusAvailable} балабонусів. Застосувати?»
→ якщо так: silpo_update_shopping_cart(bonusRequested = bonusAvailable)Помилки та обмеження
401 invalid_token— токен відсутній або протух. Клієнт має використатиrefresh_tokenабо пройти OAuth-потік заново.403— токен валідний, але немає доступу до конкретного tool.429— rate-limit. Використай експоненційний backoff. Ліміти застосовуються per-user черезCookie: mcp-user={userId}.-32601 Method not found— метод JSON-RPC не підтримується поточною версією.
Використання на хакатоні
Щоб проєкт відповідав умовам «Сільпо» AI Factory, він має:
- підключатись саме до
https://mcp.silpo.ua/mcp, а не до сторонніх або неофіційних API; - викликати хоча б один tool із
tools/listу робочому сценарії агента; - мати робочий prototype або demo, у якому цей виклик видно (запис екрана, лог JSON-RPC або трейси);
- зберігати токени серверно, а не в клієнтському коді.
Готовий підключатись?
Зареєструйся на хакатон — і ми надішлемо starter kit, приклади готових агентів та актуальний перелік tools.