Перейти к содержанию

API RusMcp

Каталог MCP-серверов, ваш аккаунт и «Мои MCP», серверы, которые вы публикуете, — для ваших скриптов и приложений. REST и JSON, ключ из кабинета.

Обзор

адрес
https://api.rus-mcp.ru/v1
формат
JSON в UTF-8; ошибки — application/problem+json
описание
OpenAPI 3.1 — /v1/openapi.json, для генерации клиентов
версия
v1

Это API платформы, а не протокол MCP. Чтобы подключить сервер к Claude, API не нужен — вот инструкция.

Без ключа открыт только каталог. Всё остальное — с ключом, у которого есть нужное право. Заголовков CORS API не отдаёт: из браузера на чужом сайте запрос не пройдёт, да и ключ в браузере не место — вызывайте API со своего сервера или из скрипта.

Первый запрос

Каталог отвечает без ключа. Для остального создайте ключ в кабинете, раздел «Ключи API», и передавайте его в заголовке Authorization. В примерах ключ берётся из переменной окружения RUSMCP_API_KEY.

# без ключа: поиск в каталоге
curl -G https://api.rus-mcp.ru/v1/catalog/servers \
  --data-urlencode "q=погода" -d limit=5

# с ключом: ваш аккаунт
curl https://api.rus-mcp.ru/v1/me \
  -H "Authorization: Bearer $RUSMCP_API_KEY"

Авторизация и права

Ключ передаётся в заголовке Authorization: Bearer mcpb_pat_…. Cookie сайта API не принимает.

  • Ключ создаётся только в кабинете, через API — нельзя. Для этого нужны подтверждённая почта, пароль и код 2FA, если она включена. Полный ключ показывается один раз.
  • Срок жизни — 7, 30, 90, 180 или 365 дней, по умолчанию 90. Ключ можно ограничить своими серверами (до 50) и сетями IP (до 10). Активных ключей — до 25.
  • Неверный, просроченный или отозванный ключ, как и запрос не из разрешённой сети, получает 401 invalid_token. Отзыв действует со следующего запроса.
  • Не хватает права — 403 insufficient_scope, недостающее право названо в detail и в заголовке WWW-Authenticate. Что умеет текущий ключ — GET /token.
ПравоЧто даёт
account:readЧитать профиль
saved_servers:readВидеть «Мои MCP»
saved_servers:writeДобавлять и убирать серверы в «Мои MCP»
usage:readВидеть свой расход вызовов
notifications:readЧитать уведомления
notifications:writeОтмечать уведомления прочитанными
servers:readВидеть свои серверы и статус модерации
deployments:readВидеть сборки и логи
deployments:writeЗапускать сборки
secrets:readВидеть имена ключей сервера
secrets:writeМенять ключи сервера — чувствительное
revenue:readВидеть статистику вызовов и доход
pricing:writeМенять цены инструментов — чувствительное

Списки и страницы

Все списки приходят в одной обёртке. Следующая страница — тот же запрос с cursor, равным next_cursor. Курсор непрозрачный: не разбирайте и не собирайте его сами. Курсор от других фильтров или испорченный — 400 invalid_cursor.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "eyJvIjoyMCwi…"
}

limit: в каталоге — до 50 (по умолчанию 20), в уведомлениях — до 100 (по умолчанию 20). Короткие списки — категории, «Мои MCP», ваши серверы, переменные, цены — приходят целиком, с has_more: false.

Ошибки

Ошибки — в формате RFC 9457 (application/problem+json). Ориентируйтесь на code — он не меняется; текст detail может меняться. request_id (он же заголовок Request-Id в каждом ответе) пришлите в поддержку, если нужна помощь с запросом.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://rus-mcp.ru/api-docs.html#errors",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not have the 'servers:read' permission.",
  "code": "insufficient_scope",
  "request_id": "req_…"
}

Ошибка проверки параметров (422 validation_failed) дополнительно содержит errors — список полей: loc, msg, type.

Коды

codeHTTPЧто случилось
unauthorized401Ключа нет, а метод его требует
invalid_token401Ключ неверный, просрочен, отозван или запрос не из разрешённой сети
insufficient_scope403У ключа нет нужного права
not_found404Нет такого сервера или адреса; сервер не ваш или не входит в серверы ключа
invalid_cursor400Курсор от других фильтров или испорчен
invalid_category400Нет такой категории
validation_failed422Параметры или тело не прошли проверку, подробности в errors
method_not_allowed405Метод не поддерживается для этого адреса
payload_too_large413Тело запроса больше 1 МБ
rate_limited429Превышен лимит запросов, см. «Лимиты»
too_many_failed_attempts429Слишком много неудачных попыток входа с этого IP
internal_error500Ошибка на нашей стороне

Коды методов хостинга и цен

codeHTTPЧто случилось
not_deployed409Сервер не размещён на хостинге rus-mcp.ru
build_in_progress409Сборка уже в очереди или идёт
build_not_running409Нет сборки, которую можно отменить
not_rebuildable409Сервер нельзя пересобрать в текущем состоянии
rebuild_removing409Сервер удаляется
rebuild_not_reviewed409Хостинг для сервера ещё не одобрен
rebuild_suspended409Хостинг сервера приостановлен
rebuild_failed500Пересборку не удалось запустить
too_frequent429Слишком часто: см. Retry-After
hosting_busy503Хостинг занят: см. Retry-After
hosting_unavailable502, 503Хостинг временно недоступен
invalid_name400Имя переменной — заглавные латинские буквы, цифры и «_», с буквы, до 64 символов
reserved_name400Имя занято платформой: PORT и всё на RUSMCP_
too_many400Больше 32 переменных в одном запросе
invalid_value400Значение пустое, длиннее 4096 символов или с управляющими символами
not_hosted409Цены можно назначать только серверам на хостинге rus-mcp.ru
unknown_tool400У сервера нет такого инструмента
invalid_price400Цена вне диапазона 5–1 000 000 кредитов

Лимиты

60 запросов в минуту на ключ, 30 — на IP-адрес без ключа. Запас виден в каждом ответе в заголовках RateLimit-Policy и RateLimit: q — сколько запросов в окне, w — окно в секундах, r — сколько осталось, t — через сколько секунд запас восстановится полностью.

RateLimit-Policy: "token";q=60;w=60
RateLimit: "token";r=57;t=3
  • Превысили — 429 rate_limited и заголовок Retry-After с числом секунд.
  • Неудачных попыток авторизации — до 10 в минуту с одного IP, дальше 429 too_many_failed_attempts.
  • Свои пределы у отдельных методов: лог сервера — не чаще раза в 20 секунд на сервер, пересборка — до 3 в час.
справочник

Каталог

Без ключа. Список — только серверы, которые сейчас видны в каталоге; по id отдаётся и скрытый сервер (listed: false).

GET/catalog/serversПоиск по каталогубез ключа

Серверы каталога, сначала недавно проверенные.

ПараметрТипОписание
qstringЧасть названия сервера, без учёта регистра; 1–120 символов
categorystringslug категории из /catalog/categories, до 32 символов; неизвестная — 400 invalid_category
limitinteger1–50, по умолчанию 20
cursorstringnext_cursor с прошлой страницы

Ответ — страница CatalogServer. requires_account — серверу нужен аккаунт в стороннем сервисе; source_private — репозиторий закрыт. Пример (значения выдуманы, поля — как в API):

{
  "data": [{
    "id": 42,
    "name": "Погода по городам",
    "tagline": "Текущая погода и прогноз по городу",
    "description": "…",
    "category": { "slug": "productivity", "name_ru": "…", "name_en": "…" },
    "author_name": "…",
    "source_url": null,
    "docs_url": null,
    "icon_url": null,
    "is_free": true,
    "requires_account": false,
    "source_private": false,
    "tool_count": 3,
    "listed": true,
    "created_at": "2026-09-14T09:12:44Z",
    "reviewed_at": "2026-09-15T11:03:20Z"
  }],
  "has_more": true,
  "next_cursor": "eyJvIjoyMCwi…"
}
GET/catalog/categoriesКатегориибез ключа

Категории каталога: slug, name_ru, name_en.

GET/catalog/servers/{server_id}Сервербез ключа

Один сервер — те же поля, что в списке. Отдаётся и сервер, скрытый из каталога.

GET/catalog/servers/{server_id}/toolsИнструменты серверабез ключа

Для каждого инструмента — name, title, description, input_schema, annotations и price_credits. Ещё credit_usd — цена кредита в долларах (строкой) и paid_live — списываются ли деньги за платные вызовы.

GET/catalog/servers/{server_id}/trustЧто проверил RusMcpбез ключа

Открыт ли исходный код, подтверждён ли репозиторий, результат проверки описаний инструментов; для сервера на хостинге — коммит сборки, дата выкладки и скан образа.

справочник

Аккаунт и «Мои MCP»

GET/meВаш профильaccount:read

id, login, email, language, email_verified, created_at.

GET/me/saved-serversСерверы в «Мои MCP»saved_servers:read

Новые сверху, с адресами подключения (url).

POST/me/saved-serversДобавить серверsaved_servers:write

Тело {"server_id": 42}, ответ 204. Повторное добавление ничего не меняет.

DELETE/me/saved-servers/{server_id}Убрать серверsaved_servers:write

Ответ 204. Сервер пропадает из «Моих MCP», ваши вызовы перестают учитываться, а доступ всех подключённых к нему приложений отзывается. Чтобы пользоваться снова — добавьте его и подключите приложения заново.

GET/me/usageВаш расход по серверамusage:read

days — период, 1–90 дней, по умолчанию 30.

GET/me/saved-servers/{server_id}/usageРасход по одному серверуusage:read

Итоги, по инструментам и по дням; days — 1–90.

GET/me/notificationsУведомленияnotifications:read

Новые сверху, страницы не пересекаются, даже если тем временем пришли новые. limit — 1–100, по умолчанию 20; unread_only — только непрочитанные.

POST/me/notifications/readОтметить прочитаннымиnotifications:write

Тело {"ids": [1, 2]} (до 100) или {"all": true}, ответ 204.

справочник

Мои серверы

Только серверы владельца ключа и только те, что разрешены ключу, — чужой сервер отвечает 404. Методы с пометкой «хостинг» работают для серверов, размещённых на rus-mcp.ru; когда хостинг выключен, они отвечают 404 not_found.

GET/author/serversВаши серверыservers:read

Со статусом модерации (status), сообщением модератора (moderator_message) и хостингом.

GET/author/servers/{server_id}Один ваш серверservers:read

Те же поля, что в списке.

GET/author/servers/{server_id}/listingВиден ли сервер в каталогеservers:read

listed, причина, если не виден (reason), число инструментов, неудачные проверки подряд, последняя проверка и ошибка.

GET/author/servers/{server_id}/tool-auditПроверка описаний инструментовservers:read

Вердикт (verdict), найденное (findings), дата проверки и подтвердил ли изменения модератор.

GET/author/servers/{server_id}/statsВызовы инструментовrevenue:read

Вызовы, ошибки, время ответа (среднее и p95) — всего, по инструментам и по дням. days — 1–90, по умолчанию 30.

GET/author/servers/{server_id}/revenueЗаработок с платных вызововrevenue:read

По инструментам и всего, в кредитах; days — 1–90.

GET/author/servers/{server_id}/tool-pricesЦены инструментовservers:read

tool_name, price_credits, active, updated_at.

PUT/author/servers/{server_id}/tool-pricesНазначить ценыpricing:write

Тело {"items": [{"tool_name": "…", "price_credits": 10, "active": true}]}, до 100 строк, ответ 204. Применяются все цены из запроса или ни одной. Только для серверов на хостинге; цена — 5–1 000 000 кредитов.

GET/author/servers/{server_id}/deploymentСостояние хостингаdeployments:read · хостинг

Статус размещения, адрес, коммит, последняя сборка и последняя проверка сервера.

GET/author/servers/{server_id}/buildsИстория сборокdeployments:read · хостинг

limit — 1–50, по умолчанию 10.

GET/author/servers/{server_id}/builds/{build_id}Лог сборки и находкиdeployments:read · хостинг

Итог сборки, лог и находки проверок образа.

GET/author/servers/{server_id}/builds/{build_id}/logЛог идущей сборкиdeployments:read · хостинг

Лог кусками: передавайте в since значение next из прошлого ответа.

GET/author/servers/{server_id}/logsПоследние строки лога сервераdeployments:read · хостинг

Не чаще раза в 20 секунд на сервер. limit — 10–500 строк, по умолчанию 200.

GET/author/servers/{server_id}/secretsИмена переменных сервераsecrets:read · хостинг

Только имена: значения можно задать, но не прочитать.

PUT/author/servers/{server_id}/secretsЗадать переменныеsecrets:write · хостинг

Тело {"secrets": {"API_KEY": "…"}}, до 32 переменных за раз — один перезапуск сервера вместо нескольких. Значения в ответе не возвращаются.

DELETE/author/servers/{server_id}/secrets/{name}Удалить переменнуюsecrets:write · хостинг

Ответ 204.

POST/author/servers/{server_id}/deployment/rebuildПересобрать и выложитьdeployments:write · хостинг

Собирает последнюю версию кода из репозитория и выкладывает без простоя. Ответ 202 {"queued": true}. До 3 пересборок в час.

POST/author/servers/{server_id}/deployment/cancelОтменить идущую сборкуdeployments:write · хостинг

Ответ 202 со статусом отмены.

справочник

Ключ

GET/tokenЧто умеет текущий ключлюбой ключ

Название, префикс, права, серверы, сети IP и срок действия ключа, которым сделан запрос.

DELETE/tokenОтозвать текущий ключлюбой ключ

Ключ, которым сделан запрос, сразу перестаёт работать. Ответ 204. Пригодится, если ключ попал в лог.

Нашли ошибку в документации или не хватает метода? Напишите в группу. Все поля ответов — в openapi.json.