MCP-сервер на 360 строк без SDK: пять решений, после которых агент перестал ломать ссылки
После ответа «tool failed» агент гадает: повторяет вызов, меняет аргументы, извиняется. Автор сервиса коротких ссылок написал MCP-сервер на 360 строк Node.js без SDK, который лишь проксирует REST API сервиса. Ошибки он стал отдавать как обычный результат инструмента, а пакетные операции — с частичным успехом. Вывод: ответы API стоит проектировать и под модель.
AI-обработка оригинала Habr AI; редакция Hamidun News
Подключить агента к своему сервису через Model Context Protocol (MCP) несложно. Сложно сделать так, чтобы он не путался, не гонял лишние запросы и не портил данные. Разработчик сервиса коротких ссылок поделился опытом: его MCP-сервер занимает около 360 строк на чистом Node.js, без SDK и зависимостей, и почти каждая строка появилась после того, как Claude Code или Cursor повёл себя неожиданно. Сценарий простой: агент пишет рассылку или release notes, сам создаёт ссылку с UTM-метками, а потом смотрит клики.
Тонкая обёртка вместо второй копии логики
В сервере нет собственной бизнес-логики. Он принимает вызов инструмента, ходит в уже существующий REST API с ключом и возвращает ответ. Валидация, лимиты и проверки безопасности остаются на стороне API.
Это даёт три плюса. Правила живут в одном месте: поменяли лимит или проверку URL, и все MCP-клиенты получили изменение без обновления пакета. Сервер запускается локально через npx, ему нужны только ключ и адрес API. А тестировать его легко: это маппинг «инструмент → HTTP-запрос».
Транспорт тоже простой. Локальный сервер общается с клиентом через stdin и stdout сообщениями JSON-RPC 2.0, по одной JSON-строке. На всякий случай парсер понимает и формат с заголовком Content-Length, как в LSP. Две мелочи, на которых легко споткнуться: stdin приходит кусками произвольной длины, поэтому нужен буфер с необработанным остатком, а в stdout нельзя писать ничего, кроме протокола. Один забытый console.log, и клиент молча отключает сервер. Отладку нужно слать в stderr.
Пять решений, которые оказались важнее остальных
Ошибки как данные. Если вернуть сбой API как ошибку JSON-RPC, клиент часто показывает модели лишь «tool failed». Дальше она гадает: повторяет вызов, меняет аргументы, извиняется перед пользователем. Автор вернул ошибку как обычный результат с флагом isError: true, и текст попал в контекст. Ошибки протокола остались только для настоящих поломок: неизвестный метод, неизвестный инструмент, невалидный JSON. Текст ошибки пишется для модели: вместо голого «401» идёт «API_KEY is invalid. Create a key at…». Получив такое, агент обычно не долбит API повторно, а подсказывает пользователю, где взять ключ.
Аннотации опасных инструментов. У инструментов есть подсказки readOnlyHint, destructiveHint, idempotentHint и openWorldHint, по ним клиенты решают, когда спрашивать подтверждение. Удаление и отключение ссылки помечены как destructive, чтение списка и статистики — как read-only. Плюс фраза «This cannot be undone» в описании: модель сама переспрашивает пользователя. Но это лишь подсказки, а не защита. Настоящие ограничения — права ключа и проверки на сервере.
Предсказуемая работа с URL. Модели любят «исправлять» ссылки. Если пользователь просит добавить utm_source=newsletter, а в URL уже стоит utm_source=partner, кто победит? Автор решил: существующие параметры не перезаписываются, якорь #fragment сохраняется, ведь метки в готовой кампании кто-то ставил осознанно. Правило закреплено тестом на API и прописано в описании инструмента. Вывод общий: если модель может передать лишнее или противоречивое, поведение сервера должно быть детерминированным и описанным.
Частичный успех в пакетах. Инструмент shorten_urls создаёт сразу несколько ссылок. Если одна из десяти не прошла проверку, исключение заставит модель решить, что не вышло ничего, и она запустит всё заново, хотя девять ссылок уже созданы. Поэтому API отвечает объектом с массивами created и errors, и сервер отдаёт его как обычный результат, даже при HTTP-ошибке. Модель повторяет только проваленные позиции.
Картинки как картинки. QR-код в base64-тексте — это несколько килобайт бессмысленных символов в контексте, то есть лишние токены и деньги. В MCP есть тип контента image: клиент показывает картинку, а рядом идёт короткий текстовый блок с типом и размером. Этого хватает, чтобы модель сказала «QR готов, PNG, 4 КБ».
Что автор сделал бы иначе
Подключение занимает одну команду: claude mcp add с ключом и адресом через npx, а для Cursor и Claude Desktop то же самое описывается в mcp.json. После этого агенту можно писать обычным текстом.
Автор честно называет ограничения подхода. Ответы API стоило сразу проектировать под модель: короткие причины ошибок и явный частичный успех полезны и обычным интеграциям. Писать протокол руками имеет смысл ради понимания, но для ресурсов, промптов и HTTP-транспорта официальный SDK сэкономит время. И тестировать нужно сразу на нескольких клиентах: Claude Code, Cursor и MCP Inspector по-разному показывают ошибки и по-разному решают, когда спрашивать подтверждение.
Практический вывод для тех, кто делает MCP поверх своего API: держите логику на сервере, пишите ошибки как инструкции для модели, помечайте опасные операции и не отдавайте в контекст то, что модель не умеет читать.
- 21 нояб. 2026 г.Восемь open-source инструментов для ИИ-агентов: Browser Use лидирует со 121 тысячей звёзд
- 21 нояб. 2026 г.Parallel Search взял 83 балла в рейтинге 26 поисковых API для ИИ-агентов
- 21 нояб. 2026 г.Text-to-cad: ИИ-агент рисует детали робота по описанию, проект набрал 26 тысяч звёзд
- 21 нояб. 2026 г.Ролик о Claude в GTA 6 похож на фейк: полчаса управления съели 5-часовой лимит Pro
Вопросы и ответы по материалу
Что известно по теме: тонкая обёртка вместо второй копии логики?
В сервере нет собственной бизнес-логики. Он принимает вызов инструмента, ходит в уже существующий REST API с ключом и возвращает ответ. Валидация, лимиты и проверки безопасности остаются на стороне API. Это даёт три плюса. Правила живут в одном месте: поменяли лимит или проверку URL, и все MCP-клиенты получили изменение без обновления пакета. Сервер запускается локально через npx, ему нужны только ключ и адрес API. А тестировать его легко: это маппинг «инструмент → HTTP-запрос». Транспорт тоже простой.
Что известно по теме: пять решений, которые оказались важнее остальных?
Ошибки как данные. Если вернуть сбой API как ошибку JSON-RPC, клиент часто показывает модели лишь «tool failed». Дальше она гадает: повторяет вызов, меняет аргументы, извиняется перед пользователем. Автор вернул ошибку как обычный результат с флагом isError: true, и текст попал в контекст. Ошибки протокола остались только для настоящих поломок: неизвестный метод, неизвестный инструмент, невалидный JSON. Текст ошибки пишется для модели: вместо голого «401» идёт «API_KEY is invalid. Create a key at…».
Что известно по теме: что автор сделал бы иначе?
Подключение занимает одну команду: claude mcp add с ключом и адресом через npx, а для Cursor и Claude Desktop то же самое описывается в mcp.json. После этого агенту можно писать обычным текстом. Автор честно называет ограничения подхода. Ответы API стоило сразу проектировать под модель: короткие причины ошибок и явный частичный успех полезны и обычным интеграциям. Писать протокол руками имеет смысл ради понимания, но для ресурсов, промптов и HTTP-транспорта официальный SDK сэкономит время.
Соберите рабочего ИИ-агента или сервис своими руками без ручного кода
В Академии Жемала Хамидуна (academy.hamidun.com) открыт бесплатный 72-часовой тест-драйв: интерактивные скетч-уроки по Claude Code и Cursor, живой Tech Radar и готовые шаблоны агентов.
Главное из мира ИИ — раз в неделю
7 ключевых событий недели, отобранных вручную. Без шума, репостов и пресс-релизов.
Готово! Проверьте почту — мы отправили подтверждение.