Новости Claude

Claude и MCP-сервер без SDK: как не сломать данные

Рабочее место с кодом, тестами и оборудованием для MCP-сервера поверх REST API

Автор собрал небольшой MCP-сервер на чистом Node.js поверх уже готового REST API и проверил, где модель ведёт себя не так, как ожидается. В результате стало ясно, какие детали важнее самого кода: как сообщать ошибки, как помечать опасные действия и как не дать ИИ испортить URL или повторно запустить уже выполненную операцию.

Как устроен MCP-сервер поверх REST API

Сценарий здесь довольно практичный: агент вроде Claude Code или Cursor вызывает внешний инструмент, а тот, в свою очередь, ходит в обычный REST API сервиса коротких ссылок. В конкретном примере это помогало автоматически создавать ссылки с UTM-метками для рассылок и release notes, а затем смотреть статистику переходов.

Сам сервер получился очень компактным — примерно 360 строк на Node.js без SDK и лишних зависимостей. Логика не дублируется: все правила, лимиты и проверки безопасности остаются на основном API, а MCP-слой просто переводит вызовы инструментов в HTTP-запросы. Это удобно тем, что если в API меняется ограничение или проверка URL, обновление сразу видят все MCP-клиенты.

Почему важны ошибки, подсказки и формат ответа

Одна из главных находок — ошибки лучше отдавать не как падение протокола, а как обычный результат инструмента с флагом isError: true. Тогда модель видит текст ошибки в контексте и может сама понять, что делать дальше: например, попросить новый ключ, а не бесконечно повторять запрос.

Ещё автор добавил подсказки для клиента: destructiveHint для опасных действий вроде удаления ссылки, а readOnlyHint для безопасного чтения статистики или списка ссылок. Это не защита само по себе, а лишь сигнал для клиента, чтобы он мог спросить подтверждение у человека перед необратимым действием.

Важно и то, как написано описание инструмента. Если в нём прямо сказано, что действие нельзя отменить, модель чаще сама остановится и уточнит шаг у пользователя. При этом настоящая защита всё равно должна жить на стороне API — через права ключа и серверные проверки.

Где модель чаще всего «исправляет» данные

Отдельная проблема — склонность модели улучшать URL «по своему вкусу». В примере с UTM-метками автор решил не перезаписывать уже существующие параметры и сохранять якорь #fragment. Это закреплено и тестом, и описанием инструмента, чтобы поведение было предсказуемым.

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

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

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

Зачем вообще делать MCP-сервер, если уже есть REST API?
Чтобы агент вроде Claude мог вызывать ваш сервис как инструмент и работать с ним напрямую. Это удобно для автоматизации задач вроде создания ссылок, сбора статистики и других повторяющихся действий.
Почему ошибки лучше возвращать как isError, а не как обычный сбой?
Так модель получает текст ошибки в контекст и может действовать осмысленно: попросить ключ, объяснить проблему пользователю или скорректировать запрос. При жёстком падении протокола она чаще просто теряет полезную информацию.
Можно ли доверять destructiveHint и readOnlyHint как защите?
Нет, это только подсказки для клиента, а не настоящая безопасность. Защита должна быть на сервере API: права ключа, проверки входных данных и ограничения на опасные операции.
Что делать, если пакетная операция выполнилась частично?
Лучше вернуть созданные результаты вместе со списком ошибок, а не обрывать всё целиком. Тогда модель не будет считать, что ничего не произошло, и не запустит уже выполненную часть заново.

Читайте также

Попробовать Lord GPT бесплатно →