MCP-сервер поверх своего REST API без SDK: что видит модель и где она ломает данные
Model Context Protocol (MCP) позволяет агенту вроде Claude Code или Cursor вызывать внешние инструменты. Я подключал так свой сервис коротких ссылок: агент пишет рассылку или release notes и сам создаёт ссылку с UTM-метками, а потом смотрит по ней клики. Сервер получился маленький, около 360 строк на чистом Node.js, без SDK и зависимостей. Но почти каждая строка в нём появилась после того, как модель повела себя не так, как я ожидал.
В статье разберу, как устроен такой сервер, и пять решений, которые оказались важнее, чем казалось на старте.
Архитектура: тонкая обёртка
У сервиса уже был REST API с ключом. MCP-сервер не содержит своей логики: он принимает вызов инструмента, ходит в тот же API и возвращает ответ. Вся валидация, лимиты и проверки безопасности остаются на сервере API.
Плюсы такого подхода:
-
одно место, где живут правила. Если поменять лимит или проверку URL, MCP-клиенты получат изменение сразу, обновлять пакет не нужно;
-
MCP-сервер можно запускать локально через npx, ему нужны только ключ и адрес API;
-
его легко тестировать: это просто маппинг «инструмент → HTTP-запрос».
async function callTool(name, args = {}) { if (!API_KEY) { throw new Error( «API_KEY is not set. Create a key at https://linkbit.live/api-keys and set API_KEY to the slk_ value.», ); } switch (name) { case «shorten_url»: return api(«/api/v1/links», { method: «POST», body: JSON.stringify(args) }); case «delete_link»: return api(`/api/v1/links/${args.id}`, { method: «DELETE» }); // … ещё 7 инструментов default: throw new Error(`Unknown tool: ${name}`); } }
Транспорт: stdio и два формата сообщений
Локальный MCP-сервер общается с клиентом через stdin и stdout сообщениями JSON-RPC 2.0. По спецификации каждое сообщение — одна строка JSON. Но на случай, если клиент или отладочная утилита пришлёт сообщение в формате LSP, с заголовком Content-Length, парсер понимает оба варианта:
function takeJsonMessages(chunk) { const messages = []; let rest = chunk; while (rest.length) { const headerMatch = rest.match(/^Content-Length:s*(d+)r?nr?n/i); if (headerMatch) { const size = Number(headerMatch[1]); const start = headerMatch[0].length; const body = rest.slice(start, start + size); if (body.length < size) break; // сообщение пришло не целиком, ждём остаток messages.push(body); rest = rest.slice(start + size); continue; } const nl = rest.indexOf(«n»); if (nl === -1) break; const line = rest.slice(0, nl).trim(); rest = rest.slice(nl + 1); if (line) messages.push(line); } return { messages, rest }; }
Две важные мелочи:
-
stdin приходит кусками произвольной длины. Одно сообщение может разрезаться пополам, а в одном куске может оказаться три сообщения. Поэтому нужен буфер и возврат необработанного остатка.
-
В stdout нельзя писать ничего, кроме протокола. Один случайный console.log ломает клиенту парсинг, и он молча отключает сервер. Всю отладку — в stderr.
Методов, которые реально нужны, немного: initialize, tools/list, tools/call и ping. На уведомления (сообщения без id) отвечать не надо.
Решение 1. Ошибки — это результат инструмента, а не ошибка протокола
Самый очевидный путь — возвращать ошибки API как ошибки JSON-RPC. Но тогда клиент часто показывает модели просто «tool failed», и она начинает гадать: повторяет вызов, меняет аргументы, извиняется перед пользователем.
В MCP есть другой путь: вернуть обычный результат с флагом isError: true. Тогда текст ошибки попадает модели в контекст как данные, и она может с ними работать.
try { const result = await callTool(name, params.arguments || {}); reply(id, { content: [{ type: «text», text: JSON.stringify(result, null, 2) }] }); } catch (error) { reply(id, { isError: true, content: [{ type: «text», text: error instanceof Error ? error.message : «Tool failed» }], }); }
Ошибки протокола я оставил только для того, что действительно сломано на уровне протокола: неизвестный метод, неизвестный инструмент, невалидный JSON.
Второе следствие: текст ошибки надо писать для модели, а не для логов. Не 401, а:
401 Unauthorized: API_KEY is invalid. Create a key at https://linkbit.live/api-keys
Получив такой ответ, агент обычно не повторяет запрос, а говорит пользователю, где взять ключ. То же с лимитами и запрещёнными URL: короткая причина и что делать дальше.
Решение 2. Аннотации опасных инструментов
У инструментов в MCP есть подсказки для клиента: readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Клиенты используют их, чтобы решать, когда спрашивать подтверждение у человека.
{ name: «delete_link», description: «Permanently delete a short link. This cannot be undone.», inputSchema: { type: «object», properties: { id: { type: «string» } }, required: [«id»], }, annotations: { title: «Delete link», readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true, }, }
destructiveHint: true стоит у удаления и отключения ссылки. Чтение списка и статистики помечено readOnlyHint: true, его клиент вызывает без вопросов. Отдельно помогает фраза «This cannot be undone» прямо в описании: модель читает описание и сама переспрашивает пользователя.
Важно помнить, что это подсказки, а не защита. Клиент может их проигнорировать. Настоящие ограничения — права ключа и проверки на сервере API.
Решение 3. Модель «исправляет» URL, сервер должен быть предсказуемым
Модели любят переписывать URL «как им кажется правильнее». Представим: пользователь просит «сократи ссылку и добавь utm_source=newsletter», а в самом URL уже есть utm_source=partner. Что должно победить?
Я решил, что существующие параметры в URL не перезаписываются, а якорь #fragment сохраняется. Ссылка часто приходит из готовой кампании, и метки в ней кто-то ставил осознанно. Это закреплено тестом на стороне API:
it(«does not overwrite existing utm_* params», () => { const out = applyUtm(«https://example.com/?utm_source=original», { utm_source: «other», utm_medium: «cpc», }); const url = new URL(out); assert.equal(url.searchParams.get(«utm_source»), «original»); // старая метка осталась assert.equal(url.searchParams.get(«utm_medium»), «cpc»); // новая добавилась });
И то же правило написано в описании инструмента: «Optional UTM fields are merged without overwriting existing utm_* params». Модель читает описание и перестаёт удивляться результату.
Общий вывод: если модель может передать лишнее или противоречивое, поведение сервера должно быть детерминированным и описанным. Не стоит надеяться, что модель передаст «правильно».
Решение 4. Частичный успех в пакетных операциях
Инструмент shorten_urls создаёт сразу несколько ссылок. Если одна из десяти не прошла проверку, бросать исключение плохо: девять ссылок уже созданы, а модель решит, что не получилось ничего, и запустит всё заново.
Поэтому API для пакета отвечает объектом с двумя массивами, created и errors, и MCP-сервер передаёт его модели как обычный результат, даже при HTTP-ошибке:
const data = await response.json().catch(() => ({})); if (!response.ok) { if (data && Array.isArray(data.created) && Array.isArray(data.errors)) return data; // … }
Модель видит, какие ссылки создались, а какие нет и почему, и повторяет только нужные.
Решение 5. Картинки отдаются картинками
Инструмент get_qr возвращает QR-код. Если отдать base64 текстом, модель получит несколько килобайт бессмысленных символов в контексте. В MCP есть тип контента image, и клиент покажет картинку пользователю:
if (mime.startsWith(«image/»)) { content.push({ type: «image», data: result.base64, mimeType: mime }); } content.push({ type: «text», text: JSON.stringify({ contentType: result.contentType, bytes: result.bytes }, null, 2), });
Рядом идёт короткий текстовый блок с типом и размером: модели этого достаточно, чтобы сказать «QR готов, PNG, 4 КБ».
Подключение
Для Claude Code сервер добавляется одной командой:
claude mcp add linkbit -e API_KEY=slk_… -e APP_URL=https://linkbit.live — npx -y linkbit-mcp
Для Cursor и Claude Desktop то же самое описывается в mcp.json. После этого агенту можно писать обычным текстом: «сократи ссылку со слагом spring и utm_source newsletter», «покажи клики по последней ссылке с 1 января».
Что бы я сделал иначе
-
Сразу проектировал бы ответы API под модель. Короткие причины ошибок и явный частичный успех полезны не только агенту, но и обычным интеграциям.
-
Не писал бы своё без нужды. Без SDK сервер получился прозрачным, и я хорошо понял протокол. Но для чего-то большего, с ресурсами, промптами и HTTP-транспортом, официальный SDK сэкономит время.
-
Проверял бы на нескольких клиентах с первого дня. Claude Code, Cursor и MCP Inspector могут по-разному показывать ошибки и по-разному решать, когда спрашивать подтверждение.
Код сервера целиком можно посмотреть в пакете linkbit-mcp на npm. Если вы тоже делали MCP-серверы поверх своих API, интересно узнать в комментариях, на какие ещё грабли вы наступали.
Теги:
- MCP
- Model Context Protocol
- ИИ-агенты
- Claude
- Cursor
- JSON-RPC
- Node.js
- REST API
Хабы:
- Искусственный интеллект
- Node.JS
- Программирование