Как мы построили 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 и текстовый запрос без конкретного номера статьи, система автоматически выполняет семантический поиск по векторной базе соответствующего закона, возвращая наиболее релевантные секции.