MCP против API: один сервис заказов, два интерфейса

Репозиторий-компаньон для видео «MCP против API: зачем нужен MCP, если REST уже работает?»

Склонируйте его, выполните две команды и сделайте одну и ту же работу дважды. Один раз — через обычный REST API. Второй раз — с MCP-сервером поверх него. Займёт около 20 минут.

Что мы строим

У вас небольшой интернет-магазин. Приходят заказы. Некоторые застревают и никогда не отправляются. Вы хотите, чтобы AI-агент находил застрявшие заказы и открывал по одному issue на GitHub для каждого.

Это весь пример. Одна маленькая, реальная задача.

Первый способ: вы даёте агенту документацию вашего API и позволяете ему использовать curl. Ему приходится самому выяснять, какой endpoint вызывать, строить фильтр по дате для «более 7 дней», замечать, что ответ приходит страницами, и переводить центы в доллары.

Второй способ: вы даёте ему инструмент под названием find_stale_orders, который принимает { older_than_days: 7 }.

Оба способа вызывают один и тот же endpoint — GET /orders. Магазин не меняется вообще. Меняется то, кто выполняет思考: агент или ваш сервер.

                        ┌──────────────────────────────────┐
  Web frontend  ───────▶│                                  │
  Mobile app    ───────▶│   Orders service (Express)       │
  Microservice  ───────▶│   GET  /orders                   │
                        │   GET  /orders/:id               │
                        │   PATCH /orders/:id              │
                        └──────────────▲───────────────────┘
                                       │  plain HTTP, nothing AI specific
                        ┌──────────────┴───────────────────┐
  Claude Code   ───────▶│   Orders MCP server              │
  Cursor        ───────▶│   tool: find_stale_orders        │
  Codex         ───────▶│   input: { older_than_days: 7 }  │
                        └──────────────────────────────────┘

Ваш API — это дверь. MCP даёт AI-клиентам стандартную ручку, чтобы её открыть.

Сервис заказов никогда не узнает, что существует Claude Code. MCP-сервер — это просто ещё один HTTP-клиент вашего API. Единственное отличие в том, что он описывает себя так, как понимают агенты.

Related MCP server: OHMS

Попробуйте за одну минуту

Вам нужен Node 20 или новее. Больше ничего. Никакой базы данных, никаких API-ключей.

git clone https://github.com/bytemonk-academy/mcp-vs-api.git
cd mcp-vs-api
npm install
npm test

npm test запускает 31 тест и для REST API, и для MCP-сервера. Если они проходят — всё работает, а дальше вам остаётся только наблюдать за происходящим.

Теперь запустите сервис и оставьте его работать:

npm run api

Во втором терминале посмотрите на данные:

npm run orders

  ID         CUSTOMER             STATUS      PLACED       DAYS  TOTAL
  ----------------------------------------------------------------------
  ORD-1001   Ada Lovelace         UNSHIPPED   2026-07-27   31    $129.00
  ORD-1002   Grace Hopper         UNSHIPPED   2026-08-03   24    $45.99
  ...

  Showing 20 of 24 matching orders.

  !! There are more. page.nextOffset = 20
     You have NOT seen all 24 orders.

Затем задайте ему тот вопрос, ради которого весь этот демо-пример:

npm run orders -- --stale=7

Восемь заказов. Одни и те же восемь на любой машине, в любое время суток.

Что такое npm run orders?

Это сокращение для curl.

Он отправляет GET /orders на ваш API и выводит ответ в виде таблицы вместо сырого JSON. Вот и всё, что он делает. Вы можете выполнить тот же запрос сами:

curl "http://localhost:3000/orders"

Вы получите те же данные, просто их труднее читать. Скрипт нужен только для того, чтобы вы могли быстро проверить данные. Он не является частью урока. В Фазе 1 агент получает curl и документацию — и ничего больше.

Он принимает несколько опций:

npm run orders -- --stale=7             # unshipped for more than 7 days
npm run orders -- --status=UNSHIPPED    # filter by status
npm run orders -- --limit=5 --offset=5  # move through the pages by hand

Почему тестовые данные выглядят именно так

Есть 24 заказа, хранящихся в памяти, с датами, заданными относительно сегодняшнего дня. Поэтому всегда есть ровно 8 просроченных заказов, когда бы вы ни склонировали этот репозиторий.

Три проблемы добавлены намеренно, чтобы вы увидели разницу сами, а не поверили видео на слово:

• Ответ приходит страницами. Запросите заказы — и получите 20 из 24. Ничто в этих 20 строках не выглядит неполным. Агент, который останавливается на первой странице, даёт неверный ответ и звучит при этом уверенно.

• Некоторые старые заказы отменены. Они выглядят просроченными, но не являются таковыми. Если фильтровать по shippedAt вместо status, вы посчитаете их по ошибке.

• Некоторые заказы находятся ровно на границе 7 дней. Посчитайте дни чуть неправильно — и получите неверный итог, а не сообщение об ошибке.

MCP-сервер решает все три проблемы в коде, один раз, в src/mcp/server.ts. В версии с curl агенту приходится справляться со всеми тремя каждый раз.

Упражнение

Выполняйте по порядку. Фаза 1 перед Фазой 2 — это и есть суть, потому что разница и есть урок.

Также здесь: справочник по API, который вы даёте агенту в Фазе 1, промпты, которые можно копировать, и устранение неполадок.

Фаза 2 открывает настоящие issue на GitHub, поэтому используйте тестовый репозиторий, который не жалко засорить.

Что здесь находится

src/
  data/orders.ts     The 24 test orders
  api/app.ts         The REST API. Knows nothing about MCP.
  api/server.ts      Starts it on a port.
  mcp/server.ts      The MCP server. Calls the REST API over HTTP.
scripts/orders.ts    The table viewer used above
clients/             Plain MCP clients, in Python and TypeScript
tests/               Tests for both halves
docs/                The walkthrough
.mcp.json            Claude Code reads this automatically
.cursor/mcp.json     Cursor reads this automatically

Три инструмента. Каждый — тонкая обёртка над endpoint'ом, который у вас уже есть:

src/mcp/server.ts — около 170 строк, и большая часть из них — комментарии. Вот и всё, чем на самом деле является MCP-сервер.

Увидеть протокол своими глазами

Claude Code не делает здесь ничего особенного. Он запускает сервер как подпроцесс и отправляет JSON-RPC-сообщения через stdin и stdout. clients/raw_mcp_client.py делает то же самое вручную:

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("find_stale_orders", {"older_than_days": 7})

Тот же скрипт затем общается с MCP-сервером GitHub по HTTP, чтобы открыть issue:

await session.call_tool("create_issue", {"owner": owner, "repo": name, "title": ...})

Одинаковая форма в обоих случаях. Один сервер — это Node-процесс на вашем ноутбуке. Другой запущен GitHub. Клиент не может их различить. Вот эту часть стоит запомнить. В clients/ есть версия на TypeScript, если вы предпочитаете оставаться на одном языке.

Тесты

npm test

31 тест. MCP-тесты управляют настоящим MCP-клиентом через stdio — точно так же, как это делает Claude Code.

Стоит прочитать, если вы планируете писать собственный сервер. Они показывают, что действительно стоит проверять: что у каждого инструмента есть понятное описание и схема, что пагинация действительно работает, что 404 возвращается как ошибка инструмента, а не как падение, и что отменённые заказы не попадают в результаты.

Команды

npm run api        # REST API on :3000
npm run api:dev    # same, restarts when you edit a file
npm run orders     # print the orders as a table
npm run mcp        # run the MCP server directly (agents usually do this for you)
npm test           # the tests
npm run typecheck  # tsc --noEmit
npm run inspect    # MCP Inspector, to try the tools by hand

npm run inspect — самый быстрый способ увидеть ровно то, что видит агент: названия инструментов, описания и схему входных данных для каждого.

Данные хранятся в памяти, поэтому перезапуск npm run api возвращает всё в исходное состояние.

Когда MCP оправдан?

Фаза 1 работает. Это не трюк. Хороший агент найдёт просроченные заказы и откроет issue, используя только curl и вашу документацию. MCP — не то, что делает задачу возможной.

Он меняет форму интеграции. Знание о том, как запрашивать ваш сервис заказов, теперь живёт в одном сервере, а не в контекстном окне каждого агента. Та же возможность работает в Claude Code, Cursor и Codex без написания новой интеграции для каждого. И вы сами выбираете, какие возможности открывать, — это сильно отличается от передачи API-ключа.

Чего он не меняет: аутентификация, авторизация, валидация, ограничение частоты запросов, повторные попытки и хороший дизайн сервиса — всё это по-прежнему ваша работа. MCP-сервер поверх плохо спроектированного API — это всё ещё плохо спроектированный API.

Грубо говоря, ценность растёт вместе с произведением числа клиентов на число инструментов. Один агент вызывает две функции, которыми вы управляете? Пропустите MCP, просто вызывайте функции. Тридцать инструментов в пяти командах и четырёх клиентах? Вот когда общий протокол начинает окупаться. docs/architecture.md подробно разбирает, где проходит граница.

Лицензия MIT. Используйте в своём обучении, указание авторства не требуется.