MCP-сервер поверх своего REST API без SDK: что видит модель и где она ломает данные

в 11:52, , рубрики: claude, cursor, json-rpc, MCP, model context protocol, node.js, rest api, ии-агенты

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, интересно узнать в комментариях, на какие ещё грабли вы наступали.

Автор: egor-dev

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js