Сервер MCP

Zelnum предоставляет публичный MCP-сервер по адресу https://mcp.zelnum.com/mcp. Любой клиент с поддержкой MCP — Claude, Cursor, агент в вашей IDE — может получить список продуктов, узнать цену проверки, выполнить её и прочитать результат, не написав ни строчки кода интеграции. Один адрес обслуживает всех клиентов: вы подключаетесь своим ключом API, и все списания идут по вашему балансу.

Точка подключения

Параметр	Значение
URL	`https://mcp.zelnum.com/mcp`
Транспорт	Streamable HTTP
Учётные данные	`Authorization: Bearer YOUR_KEY_HERE`

Учётные данные — тот же ключ API, которым вы пользуетесь в REST-запросах. Создать, перевыпустить и отозвать его можно в разделе API Center консоли.

Подключение клиента

Три шага, и устанавливать ничего не нужно.

1. Создайте ключ. Выпустите ключ API в разделе API Center консоли — тот же, которым пользуетесь в REST-запросах. См. Authentication.

2. Добавьте сервер. Cursor и другие клиенты, читающие стандартную карту mcpServers, могут использовать эту запись как есть:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude принимает те же два значения в диалоге пользовательского коннектора — URL и заголовок Authorization с вашим ключом.

3. Проверьте подключение. Попросите агента перечислить продукты, которые он может проверять в реальном времени. Рабочее подключение ответит вызовом list_products — инструмента только для чтения и бесплатного, поэтому проверка ничего не стоит. Ответ 401 означает, что ключ отсутствует, отозван или не принимается платформой.

Инструменты

Инструмент	Что делает	Платный
`list_products`	Каталог активных продуктов с ID, slug и серией. Только чтение.	Нет
`get_balance`	Баланс аккаунта, под которым авторизовано подключение. Только чтение.	Нет
`quote_realtime_check`	Официальная цена одной проверки. Единственный источник цены, которому агенту следует доверять.	Бесплатно
`check_realtime`	Выполняет одну проверку в реальном времени не более чем по десяти продуктам.	Да
`create_bulk_task`	Отправляет встроенный список на асинхронную массовую задачу.	Да
`get_task_status`	Прогресс и счётчики биллинга массовой задачи.	Нет
`get_task_result`	Метаданные результата и авторизованная ссылка на скачивание завершённой задачи.	Нет

Что можно сказать

Выше — инструменты, ниже — фразы, которые набираете вы. Каждую обслуживает уже существующий инструмент — особых формулировок нет.

Скажите так	Что произойдёт
Какие продукты можно проверять в реальном времени?	Вызывает `list_products` и отвечает списком ID для использования. Бесплатно.
Сколько у меня на балансе?	Вызывает `get_balance` для ключа, с которым вы подключились. Бесплатно.
Сколько будет стоить проверка `+14155550123` в WhatsApp?	Вызывает `quote_realtime_check` и показывает цену. Бесплатно, списания не происходит.
Да, по этой цене.	Вызывает `check_realtime` по продуктам из сметы и списывает указанную в ней сумму.
Проверь эти 200 номеров в WhatsApp и скажи, когда закончишь.	Вызывает `create_bulk_task`, затем опрашивает `get_task_status` и сообщает о ходе выполнения.
Задача уже готова? Пришли ссылку на скачивание.	Вызывает `get_task_result` и возвращает авторизованную ссылку.

Две полезные привычки:

Сначала спросите цену. Любой платный инструмент перед списанием отвечает сметой, поэтому вопрос о стоимости всегда бесплатен. Деньги двигает только подтверждение.
Указывайте поле country, если номер не в формате E.164. +14155550123 содержит свою страну; 0812345678 — нет, и шлюз отказывается её угадывать.

Подтверждение списания

Платный инструмент никогда не списывает деньги при первом вызове. Вызванный без confirmed, он вместо этого возвращает подтверждающие данные — продукты, количество и ожидаемую стоимость — вместе с quote_token, подписывающим точный ввод. Подтвердите, повторив тот же вызов с:

confirmed равным true
quote_token из этих данных
quoted_total — ровно та сумма, которая была вам показана
тем же идентификатором, продуктами и полем country

Агент никогда не придумывает ключ идемпотентности сам: шлюз выводит его из подписанной котировки, поэтому одна и та же одобренная котировка сохраняет один и тот же ключ при повторах, переподключениях и перезапусках шлюза. Для другого списания нужна новая котировка. Если из-за тайм-аута результат остался неизвестен, повторите идентичный вызов, а не меняйте параметры.

Идентификаторы

Правила идентификаторов повторяют REST-контракт, поэтому то, что проверяет агент, совпадает с тем, что принимает API:

Поле country не указано — идентификатор должен быть номером E.164 с префиксом +.
Поле country указано — двухбуквенный код ISO в верхнем регистре; тогда идентификатором может быть национальный номер или номер E.164.
Страна никогда не выводится из неоднозначного национального номера вроде 0812345678, который подходит сразу нескольким странам. Опускайте country только тогда, когда номер уже полный E.164.
Массовые задачи по телефонным продуктам требуют явно указанного country.

Финансовые предохранители

Между агентом и вашим балансом стоят четыре предохранителя:

Подписанные котировки. Платформа читает актуальные цены и возвращает зашифрованную котировку, связывающую аккаунт, точный ввод, продукты и снимок цен. Изменённый ввод, истёкшая котировка или сдвинувшаяся цена отклоняются до того, как что-либо будет списано.
Детерминированная идемпотентность. Ключ идемпотентности берётся из подписанной котировки, а не из модели, поэтому никакая формулировка запроса не превратит одно согласие в два списания.
Лимиты на ключ. Дневной потолок расходов и нижняя граница баланса действуют отдельно для каждого ключа API, а каждое резервирование сериализуется перед вызовом платформы, так что параллельные агенты не могут их обойти.
Отказ по умолчанию. Если баланс не читается или приходит в некорректном виде, платные вызовы отклоняются, а не выполняются без защиты.

Ошибки и ограничения

Отсутствующие или некорректные учётные данные отклоняются с HTTP 401 ещё до того, как запрос дойдёт до платформы.
Ключ, который платформа не принимает, возвращается как ошибка инструмента с кодом состояния и телом ответа, поэтому агент сообщает о ней, а не повторяет запрос вслепую.
Ограничения частоты, коды ошибок и скачивание результатов работают точно так же, как в REST — шлюз не добавляет второго контракта, который нужно изучить.

Дальше

Authentication — создайте ключ, с которым будете подключаться.
Realtime check — эндпоинт, стоящий за check_realtime.
Bulk workflow — асинхронный путь за create_bulk_task.
Error codes — коды, которые возвращает платформа.