TOPZNANIE

Цифровая практика без сложностей

Выберите город
MET Norway · CC BY 4.0
← На главную

· Общий обзор

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
  • Программирование