Як ми побудували MCP-сервер на 56 інструментів для юридичного AI
Один endpoint. Три сервіси. 58 MCP-інструментів. Потрійний транспорт: stdio для Claude Desktop, HTTP REST для веб-додатків, SSE для стрімінгу. Кожен tool call проходить 11-кроковий пайплайн з трекінгом витрат на кожному етапі. Кількість інструментів зростатиме. Архітектурі все одно.
Як ми побудували MCP-сервер на 56 інструментів для юридичного AI
Один endpoint. Три сервіси. Потрійний транспорт. Ось що потрібно, щоб побудувати продакшн MCP-сервер, який дійсно масштабується.
Проблема: юридичний AI потребує більше, ніж один API-виклик
Коли юрист запитує "Негаторний чи віндикаційний позов при самовільному захопленні земельної ділянки?" — відповідь вимагає: пошуку 200+ судових рішень, отримання текстів статей ЦК та ЗК, порівняння практики "за" та "проти", перевірки прецедентів, синтезу стратегічної рекомендації.
Це не один виклик LLM. Це оркестрований пайплайн з 5-7 tool calls.
Архітектура: 56 інструментів, три сервіси, один шлюз
| Сервіс | Інструменти | Домен |
|---|---|---|
| mcp_backend | 36 | Судові рішення, законодавство, семантичний пошук, документи, due diligence |
| mcp_rada | 4 | Парламент — законопроєкти, депутати, голосування |
| mcp_openreyestr | 16 | Державний реєстр — юридичні особи, бенефіціари, боржники |
Одна змінна середовища — ENABLE_UNIFIED_GATEWAY=true — перетворює бекенд на точку агрегації.
Потрійний транспорт
stdio (MCP Native)
Чистий JSON-RPC через stdin/stdout. Claude Desktop, MCP CLI. Нульовий оверхед.
HTTP REST API
POST /api/tools/:toolName з Bearer token. Batch endpoint для паралельного виконання. Заголовок Accept: text/event-stream перемикає на SSE.
SSE (MCP-over-SSE)
Два варіанти: ChatGPT/OpenAI протокол (/sse) та стандартний MCP SSE (/v1/sse).
Потік виклику: 11 кроків
- dualAuth — JWT або API key
- Перевірка балансу → 402 якщо недостатньо
- Розрахунок кредитів для інструменту
- Cost tracking — pending запис
- Оцінка вартості перед виконанням
- Маршрутизація шлюзу — локальний чи віддалений?
- Виконання в AsyncLocalStorage контексті
- Диспатч обробника → доменна логіка
- Завершення трекінгу — фактичні токени
- Списання кредитів після успіху
- Відповідь з розбивкою витрат
Патерни, які врятували
Cost hints в описах — кожен інструмент має розрахункову вартість у description. LLM бачить це при плануванні.
Budget-aware моделі — параметр reasoning_budget маппить на різні моделі: quick → nano, deep → gpt-5.1.
Vault ізоляція — userId інжектиться на рівні транспорту, tool schema не знає про автентифікацію.
Route normalization — без нього 56 інструментів + UUID створюють тисячі time series у Prometheus.
Цифри
- 56 інструментів через 3 сервіси
- 12 класів-обробників у бекенді
- 3 транспорти на сервіс
- 5 191 стаття законодавства
- 16 державних реєстрів
- Латентність: 200мс (кеш) до 8с (глибокий аналіз)
Кількість інструментів зростатиме. Архітектурі все одно.
Оновлення: нові інструменти (березень 2026)
Загальна кількість MCP-інструментів зросла з 56 до 58 завдяки двом новим інструментам у сервісі mcp_openreyestr.
Нові інструменти:
- openreyestr_search_erb_debtors — пошук у Єдиному реєстрі боржників (ЄРБ). Дозволяє знаходити фізичних та юридичних осіб, щодо яких відкрито виконавчі провадження, з фільтрацією за типом стягнення та категорією боргу.
- openreyestr_search_nbu_banks — пошук у реєстрі банків НБУ. Надає доступ до інформації про банківські установи, їхній статус (діючий, ліквідація), ліцензії та контактні дані.
Покращення існуючих інструментів:
Інструмент get_legislation_section тепер підтримує векторний пошук як fallback-стратегію. Якщо користувач вказує rada_id та текстовий запит без конкретного номера статті, система автоматично виконує семантичний пошук по векторній базі відповідного закону, повертаючи найрелевантніші секції.