Claude и MCP-сервер без SDK: как не сломать данные
Автор собрал небольшой 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-ответ был не идеальным.
Практический вывод простой: когда в работу вовлечён ИИ, сервер должен быть максимально детерминированным. Чем яснее описаны правила, тем меньше шанс, что модель случайно перепишет данные, потеряет часть результата или выполнит лишнее действие.