Что такое MCP-сервер, показал 2ГИС: 6 инструментов отучили модель выдумывать адреса

Anthropic в конце 2024 года опубликовала спецификацию MCP (Model Context Protocol, открытый протокол подключения внешних инструментов к ИИ-моделям). С тех пор десятки команд пишут собственные MCP-серверы, но публичных разборов инженерных граблей почти нет. Команда 2ГИС выпустила и сам сервер, и подробный технический отчёт о том, что ломается, когда модель получает доступ к геоданным, и как это чинить архитектурой, а не промптами. Именно этот отчёт лёг в основу инструкции ниже.

Что такое MCP-сервер и зачем он нужен?

MCP-сервер, это программа, которая отдаёт ИИ-модели набор инструментов по стандартному протоколу. Модель видит имя каждого инструмента, описание и параметры, и сама решает, когда его вызвать. Код исполняет не модель, а клиент: модель лишь формирует вызов с аргументами, получает результат обратно в контекст и продолжает рассуждать.

Без подключённых инструментов ассистент на вопрос про маршрут или ближайшую аптеку отвечает уверенно и полностью выдуманно. Это классическая галлюцинация (когда ИИ уверенно выдумывает то, чего не было). Но и после подключения геоданных проблема не исчезает, а мутирует: модель начинает выдумывать адреса и координаты, подставляя их в вызовы инструментов. Заметить такое гораздо сложнее.

Сервер mcp-2gis решает это шестью инструментами поверх API 2ГИС:

• Поиск мест и организаций
• Прямое геокодирование (адрес в координаты)
• Обратное геокодирование (координаты в адрес)
• Построение маршрутов
• Изохроны (зона доступности за заданное время)
• Статические карты

Что понадобится

• Python 3.10+ и менеджер пакетов pip или uv
• API-ключ 2ГИС (получается бесплатно на dev.2gis.ru)
• MCP-совместимый клиент: Claude Desktop, Cursor, любой клиент с поддержкой MCP
• 15 минут на установку и первый тестовый запрос

Как устроена архитектура: каркас вместо копипаста

Ключевое архитектурное решение: каждый инструмент, это тонкий адаптер между MCP-контрактом и доменом API. Всё остальное (HTTP-пулы, авторизация, логирование, обработка ошибок) живёт в каркасе.

Слои выстроены так:

1. MCP-клиент отправляет запрос
2. Middleware FastMCP проверяет авторизацию, лимиты, таймауты
3. Файл инструмента содержит MCP-схему, Pydantic-валидацию (проверку типов входных данных) и маппинг результата
4. Общий модуль инструментов управляет зависимостями и границей ошибок
5. Интеграционный модуль знает URL и параметры конкретного API
6. HTTP-клиент держит общий пул соединений и подставляет ключ
7. API 2ГИС возвращает данные

При добавлении нового инструмента разработчик пишет только адаптер на третьем слое. Не нужно копировать обработку ошибок авторизации, создание HTTP-пулов или чтение переменных окружения.

Как контракт побеждает галлюцинации?

Вот центральная находка команды 2ГИС. Модель выдумывает координаты и адреса не от «злого умысла», а потому что схема инструмента позволяет ей передать произвольную строку или число. Решение: строгая типизация и валидация на уровне контракта.

Координата WGS84 (пара чисел: долгота и широта в градусах) проверяется Pydantic-валидатором ещё до отправки в API. Если модель подставила несуществующие координаты, вызов не уйдёт в сеть и модель получит внятное сообщение об ошибке.

Описание инструмента (description) в MCP, это не комментарий для разработчика, а часть продукта. Модель читает именно его, решая, вызывать ли инструмент и с какими аргументами. По данным команды 2ГИС, с неточным описанием модель либо не понимала, что инструмент нужен, либо вызывала его с неверными параметрами.

Два типа ошибок: для модели и для протокола

Ядро сервера разводит ошибки на две категории:

• Бизнес-ошибка (неверный ключ, нет доступа): возвращается модели как результат инструмента с машиночитаемым кодом. Модель понимает, что произошло, и может сообщить пользователю
• Сетевой сбой (таймаут, обрыв): пробрасывается как ошибка протокола. Клиент может повторить запрос

Если бизнес-ошибку отдать как падение протокола, модель не поймёт причину и начнёт вызывать инструмент заново в цикле.

# Упрощённый пример ядра
async def run_gis_tool(name, ctx, operation) -> ToolResult:
    try:
        rt = get_runtime(ctx)
        return await operation(rt.client, rt.access)
    except GISAPIError as e:
        return rt.client.error_result(e)   # бизнес-ошибка → результат для модели
    except UpstreamError as e:
        raise to_mcp_error(e) from e       # сеть → протокольная ошибка

Что с этим делать прямо сейчас, по ролям

Разработчику, который пишет свой MCP-сервер. Архитектура 2ГИС, это готовый шаблон: тонкие адаптеры на слое инструментов, каркас для общей логики, два контракта ошибок. Код доступен на GitHub (ссылка в документации 2ГИС), можно форкнуть и адаптировать под своё API.

Автору на Дзене или контент-маркетологу. Если вы используете ИИ-ассистентов для работы с локальным контентом (адреса, маршруты, рекомендации мест), подключение MCP-сервера 2ГИС к Claude Desktop устраняет проблему выдуманных адресов. Результат: можно доверять фактуре в черновиках.

Предпринимателю в РФ. 2ГИС, это российский сервис, API доступно без VPN, ключ бесплатный. Для задач с геоданными это рабочая альтернатива Google Maps API, доступ к которому из РФ нестабилен.

Контракт инструмента бьёт промпт: если вы проектируете MCP-сервер или любую интеграцию языковой модели с внешним API, закладывайте валидацию и типизацию на уровне схемы, а не надейтесь, что правильная формулировка в системном промпте удержит модель от выдумок.