Что такое MCP-сервер на практике: код за вечер, а грабли на недели

Автор продукта Worklore рассказала, как за один вечер агент написал рабочий MCP-сервер (MCP, Model Context Protocol, протокол, по которому ИИ-агенты подключаются к внешним сервисам и вызывают их функции), а затем несколько недель ушло на решения, которые агент принять не мог: сколько инструментов открывать, как называть методы, как поднять OAuth (открытый стандарт авторизации, когда пользователь разрешает доступ через экран «войти через…» вместо ручного ввода ключа) и что делать, когда каталог показывает ноль инструментов. Опыт ценен тем, что описывает не теорию, а конкретные грабли, на которые наступает первый же разработчик после публикации.

Что даёт MCP-сервер и где подвохи?

• Код пишется за вечер. MCP поверх streamable HTTP, это JSON-RPC (способ вызова функций через интернет в формате JSON) в теле POST-запроса. Клиент просит сервер представиться, запрашивает список инструментов, вызывает их по одному. Фреймворк не нужен, SDK не нужен: поверх существующего бэкенда добавляется один маршрут без новых зависимостей.

• Четыре-восемь инструментов, не больше. Каждый дополнительный инструмент это ещё одна сущность, которую модель на стороне клиента должна выбрать верно. Чем меньше, тем точнее выбор.

• Имена нельзя менять после публикации. Как только реестр просканировал сервер и заявка принята, каждое опубликованное имя уходит в листинги, заявки и чужие сохранённые конфигурации. Это уже не рефакторинг, а миграция по системам, которыми вы не управляете. Решение на пятнадцать минут, которое потом невозможно откатить.

• Точечные имена работают не везде. Каталог smithery.ai поощряет точечный путь вроде stories.search: листинг автора набрал 98 из 100 баллов именно за это. Но библиотека серверов ChatGPT требует формат без точки (только буквы, цифры, дефис и подчёркивание, до 64 символов). Это критерий, который стоит осознанно провалить в одном каталоге ради другого.

• Авторизация, самая дорогая часть. Claude и ChatGPT подключаются к серверу сами, вставить API-ключ некуда. Нужен полноценный OAuth-сервер: пользователь нажимает «подключить», видит экран «разрешить доступ» и возвращается авторизованным. Отвечать за безопасность этого сервера придётся вам.

• Анонимный доступ к списку инструментов обязателен. Автор сначала закрыла всё для неавторизованных клиентов, включая список возможностей. После регистрации в каталоге увидела ноль инструментов: зеркалу реестра некем авторизоваться. Правило: анонимно отдавайте ровно то, что и так публично в других местах.

• Для ревью нужен тестовый аккаунт. Если единственный вход через соцсеть, ревьюер магазина приложений не сможет проверить сервер. Нужен специальный аккаунт-песочница.

• GitHub-токен с правом read:org. В официальном реестре MCP-сервер публикуется под именем GitHub-аккаунта. Для публикации от имени организации нужен токен с правом read:org, а стандартный вход через mcp-publisher выдаёт токен без него. Ошибка 403 не объясняет причину. Автору помог токен GitHub CLI: mcp-publisher login github -token "$(gh auth token)".

• Логи показывают то, чего не ищут тесты. После добавления одной строки логирования на вызов выяснилось: клиент регулярно зовёт метод из более новой ревизии протокола, получает ошибку и молча откатывается на старый путь. Внешне ничего не ломалось, ни один тест этого не искал.

Как попробовать?

1. Добавьте один POST-маршрут к существующему бэкенду. MCP-сервер это JSON-RPC эндпоинт: он принимает запрос «представься», отдаёт список инструментов и выполняет вызовы. Фреймворк и SDK не обязательны.

2. Выберите четыре-восемь инструментов и назовите их так, будто имена вечны. Используйте точечные пути (stories.search) для smithery.ai, но учтите формат ChatGPT без точки. Пропишите имена до публикации, после менять их, по сути, нельзя.

3. Поднимите OAuth-сервер и сразу откройте анонимный доступ к списку инструментов. Без OAuth ни Claude, ни ChatGPT не авторизуют пользователя. Без анонимного списка каталоги покажут ноль инструментов.

4. Добавьте логирование с первого дня и создайте тестовый аккаунт-песочницу для ревью. Без логов вы не узнаете, что клиент зовёт несуществующий метод. Без песочницы ревьюер не пройдёт проверку.

Есть ли аналог в России?

Протокол MCP пока не имеет прямого российского аналога. YandexGPT и GigaChat (российские языковые модели от Яндекса и Сбера) предоставляют собственные API, но не поддерживают MCP как стандарт подключения внешних инструментов.

Для автора или предпринимателя из РФ это значит: если вы строите продукт, который должен работать и с западными ИИ-агентами (ChatGPT, Claude), и с российскими моделями, MCP-сервер закрывает первую часть, а для второй придётся интегрироваться через API Яндекса или Сбера отдельно. Понимание того, что такое MCP-сервер и как он устроен, помогает оценить, стоит ли вкладываться в эту интеграцию сейчас или подождать, пока российские платформы поддержат протокол.

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

Автору Дзена. MCP-серверы пока далеки от контент-платформ, но именно через этот протокол ИИ-агенты получают доступ к внешним сервисам. Если вы пользуетесь ChatGPT или Claude для работы с текстами, вы уже косвенно взаимодействуете с MCP. Понимание протокола поможет выбирать плагины и интеграции осознанно.

Разработчику. Три решения до первой строки кода: количество инструментов (четыре-восемь), схема имён (точечная или плоская, в зависимости от целевых каталогов), OAuth с анонимным списком инструментов. Логирование с первого дня обязательно.

Предпринимателю. Стоимость поддержки MCP-сервера складывается не из вычислений (они укладываются в бесплатные лимиты облака), а из сопровождения OAuth-сервера, отслеживания новых ревизий протокола и реакции на несовместимости клиентов. Если у вас нет штатного бэкенд-разработчика, это задача на аутсорс.

Частые вопросы

Сколько стоит запустить MCP-сервер?

Сами вычисления, по словам автора разбора, стоят копейки и обычно укладываются в бесплатные лимиты облака. Листинг в официальном реестре бесплатный, заявка на приложение в ChatGPT тоже бесплатная. Единственная платная строка в описанном случае: каталог коннекторов Claude требует подписку Team, около $40 в месяц при минимуме двух мест.

Можно ли поменять имена инструментов после публикации?

Фактически нет. После сканирования реестром имена уходят в листинги, заявки и чужие сохранённые конфигурации. Автор прямо предупреждает: это решение на пятнадцать минут, которое потом превращается в миграцию по системам, которыми вы не управляете.

Зачем нужен OAuth, если у API есть ключи?

ChatGPT и Claude подключаются к MCP-серверу сами, и вставить API-ключ пользователю некуда. Им нужен вход как на сайтах: человек нажимает «подключить», видит экран «разрешить доступ» и возвращается авторизованным. Для этого придётся поднять собственный OAuth-сервер, и это самая затратная часть всего проекта.

Главный вывод из этого разбора не технический, а управленческий: агент напишет код за вечер, но решения об именах, доступах и каталогах останутся на вас, и именно они определят, сколько вы будете жить с последствиями.