Интенсив 21–22.11 · БесплатноБесплатный 2-дневный интенсив по вайбкодингу 21–22 ноября в 16:00 МСК (Сб–Вс) · Живой Поток 3 стартует 23.11Записаться бесплатно →Поток 3 (23.11)
РелизКод / SDK · В работуHabr AI→ оригинал

MCP-сервер на 360 строк без SDK: пять решений, после которых агент перестал ломать ссылки

После ответа «tool failed» агент гадает: повторяет вызов, меняет аргументы, извиняется. Автор сервиса коротких ссылок написал MCP-сервер на 360 строк Node.js без SDK, который лишь проксирует REST API сервиса. Ошибки он стал отдавать как обычный результат инструмента, а пакетные операции — с частичным успехом. Вывод: ответы API стоит проектировать и под модель.

AI-обработка оригинала Habr AI; редакция Hamidun News
MCP-сервер на 360 строк без SDK: пять решений, после которых агент перестал ломать ссылки
Источник: Habr AI. Коллаж: Hamidun News.
Слушать статью
Паспорт материала и цифры
ПараметрДанные
ПервоисточникHabr AI ↗
Главный редактор
Ошибки приходят с isErrortrue — модель читает причину и не повторяет вызов
Ключевой факт #2Существующие utm_ в ссылке не перезаписываются, якорь #fragment сохраняется
Ключевой факт #3QR-код отдаётся типом image, а не base64-текстом на несколько килобайт

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

Сюжет

Вопросы и ответы по материалу

Что известно по теме: тонкая обёртка вместо второй копии логики?

В сервере нет собственной бизнес-логики. Он принимает вызов инструмента, ходит в уже существующий 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 сэкономит время.

ЖХ
Жемал Хамидун — CPO Alpina Digital, продакт-менеджер AlpinaGPT. Делает AI-продукты с 2019 года. Hamidun News — pet project, который вырос в production-агрегатор с 6000+ читателей.
✦ Практика · Hamidun Academy

Соберите рабочего ИИ-агента или сервис своими руками без ручного кода

В Академии Жемала Хамидуна (academy.hamidun.com) открыт бесплатный 72-часовой тест-драйв: интерактивные скетч-уроки по Claude Code и Cursor, живой Tech Radar и готовые шаблоны агентов.

Открыть 72ч бесплатный доступ →Интенсив по Вайб-кодингу
Что вы думаете?
Загружаем комментарии…