API mcpbay.pro

Быстрый старт

1. Откройте кабинет → «Токены API» и создайте токен. Выберите права, которые нужны задаче, — и не больше. Открыть «Токены API»
2. Сразу скопируйте токен — он показывается один раз. Храните его как пароль: в менеджере паролей или в секретах CI.
3. Проверьте его — API ответит, что это за токен и что ему разрешено:

curl https://api.mcpbay.pro/v1/token \
  -H "Authorization: Bearer $MCPBAY_TOKEN"

Дальше вызывайте любые методы. Например, каталог (токен не нужен) или ваши серверы:

curl "https://api.mcpbay.pro/v1/catalog/servers?q=github&limit=5"

curl https://api.mcpbay.pro/v1/author/servers \
  -H "Authorization: Bearer $MCPBAY_TOKEN"

Аутентификация

Передавайте токен в заголовке Authorization каждого запроса. В адресе запроса и в cookie токены не принимаются: вход на сайт для API не используется.

Authorization: Bearer mcpb_pat_…

Токены начинаются с mcpb_pat_. По этому префиксу токен, случайно попавший в код или логи, легко найти — например, своим шаблоном в сканере секретов.

У каждого токена есть срок — от 7 дней до года, его выбираете вы. Мы пишем на почту, когда токен создан, а для токенов сроком больше двух недель — ещё и за 7 дней до его окончания.

Запрос с неверным, истёкшим или отозванным токеном получает 401 invalid_token — ответ одинаковый во всех случаях и не раскрывает, какой именно. Это касается и методов, которым токен не нужен: передавайте действующий токен или никакого. Запрос без токена к методу, которому он нужен, получает 401 unauthorized.

Не кладите токены в код для браузера или мобильного приложения: оттуда их может достать кто угодно. Вызывайте API со своего сервера, из скрипта или CI.

Права

Токен получает только те права, которые вы выбрали при создании. Права выданного токена никогда не расширяются: для новых прав создайте новый токен.

В кабинете можно начать с готового назначения: «Только чтение», «CI: сборка сервера», «Агент: каталог и мои MCP». Чувствительные права ни в одно назначение не входят.

Токен можно ограничить частью ваших серверов: в методах раздела «Ваши серверы» остальные для него выглядят несуществующими (404). Для CI создавайте отдельный токен на каждый сервер.

Токен можно ограничить и IP-адресами или сетями — удобно для CI с постоянными адресами. С любого другого адреса он получает 401 invalid_token.

Часть действий через API недоступна вовсе — только в кабинете в браузере: смена пароля и email, двухфакторная аутентификация, доверенные устройства, выпуск токенов, пополнение кошелька, удаление серверов и аккаунта. Самые чувствительные из них ещё и спрашивают пароль.

Методы

Схемы запросов и ответов всех методов — в спецификации OpenAPI: api.mcpbay.pro/v1/openapi.json

Тело запроса передавайте в JSON с заголовком Content-Type: application/json. Большинство методов записи отвечают 204 No Content; установка переменных — 200 с именами заданных переменных; пересборка и отмена — 202 Accepted: работа продолжается в фоне.

Каталог — без токена

• GET /v1/catalog/categories — категории
• GET /v1/catalog/servers — поиск: q, category, limit, cursor
• GET /v1/catalog/servers/{id} — карточка сервера
• GET /v1/catalog/servers/{id}/tools — tools и их цены
• GET /v1/catalog/servers/{id}/trust — что mcpbay.pro проверил у сервера

Токен

• GET /v1/token — права, ограничения и срок текущего токена
• DELETE /v1/token — отозвать текущий токен

Ваш аккаунт

• GET /v1/me — профиль account:read
• GET /v1/me/saved-servers — «Мои MCP» saved_servers:read
• POST /v1/me/saved-servers — добавить сервер: {"server_id": 123} saved_servers:write
• DELETE /v1/me/saved-servers/{id} — убрать сервер saved_servers:write
• GET /v1/me/usage — расход по всем серверам: days usage:read
• GET /v1/me/saved-servers/{id}/usage — расход по одному серверу — по tools и по дням usage:read
• GET /v1/me/notifications — уведомления: limit, unread_only, cursor notifications:read
• POST /v1/me/notifications/read — отметить прочитанными: {"ids": [...]} или {"all": true} notifications:write

Ваши серверы

• GET /v1/author/servers — серверы, которые вы добавили, в любом статусе проверки servers:read
• GET /v1/author/servers/{id} — один сервер servers:read
• GET /v1/author/servers/{id}/listing — виден ли в каталоге, а если нет — почему servers:read
• GET /v1/author/servers/{id}/tool-audit — результат проверки описаний tools servers:read
• GET /v1/author/servers/{id}/deployment — статус хостинга deployments:read
• POST /v1/author/servers/{id}/deployment/rebuild — собрать свежий код и выложить deployments:write
• POST /v1/author/servers/{id}/deployment/cancel — отменить идущую сборку deployments:write
• GET /v1/author/servers/{id}/builds — история сборок deployments:read
• GET /v1/author/servers/{id}/builds/{build_id} — лог сборки и находки проверки deployments:read
• GET /v1/author/servers/{id}/builds/{build_id}/log — живой лог сборки с позиции since deployments:read
• GET /v1/author/servers/{id}/logs — последние строки лога сервера deployments:read
• GET /v1/author/servers/{id}/secrets — имена переменных secrets:read
• PUT /v1/author/servers/{id}/secrets — задать переменные: {"secrets": {"NAME": "value"}}; работающий сервер один раз перезапустится, staged: true — значения применятся при следующем запуске secrets:write
• DELETE /v1/author/servers/{id}/secrets/{name} — удалить переменную secrets:write
• GET /v1/author/servers/{id}/stats — вызовы tools: days revenue:read
• GET /v1/author/servers/{id}/revenue — доход с платных вызовов: days revenue:read
• GET /v1/author/servers/{id}/tool-prices — цены tools servers:read
• PUT /v1/author/servers/{id}/tool-prices — задать цены — все сразу или ни одной: {"items": [...]} pricing:write

Часть запросов на запись можно безопасно повторять: повторное сохранение не добавит сервер второй раз, а пересборка, пока сборка в очереди или идёт, получит 409 build_in_progress вместо второй сборки.

Ошибки

Ошибки приходят в формате application/problem+json (RFC 9457). Опирайтесь на поле code — оно стабильно, тексты могут меняться.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Request-Id: req_3f9c2a71b0d44e8a

{
  "type": "https://mcpbay.pro/api-docs.html#errors",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not have the 'deployments:write' permission.",
  "code": "insufficient_scope",
  "request_id": "req_3f9c2a71b0d44e8a"
}

У части методов есть свои коды, например not_rebuildable (409, сервер нельзя пересобрать в текущем состоянии), not_deployed (409, сервер не запущен на хостинге mcpbay.pro), build_not_running (409), invalid_category, invalid_price или unknown_tool (400). Каждый поясняет поле detail.

В каждом ответе есть заголовок Request-Id, в каждой ошибке — request_id. Если нужна помощь, пришлите его на support@mcpbay.pro.

Лимиты

До 60 запросов в минуту на токен; без токена — до 30 в минуту с одного IP-адреса. Сколько запросов осталось, показывают заголовки RateLimit:

RateLimit-Policy: "token";q=60;w=60
RateLimit: "token";r=42;t=18

Сверх лимита API отвечает 429 с заголовком Retry-After — подождите указанное число секунд и повторите.

У тяжёлых операций свои лимиты: пересборка — несколько раз в час на сервер; логи сервера — раз в 20 секунд на сервер. Повторные неудачные попытки аутентификации с одного адреса на время блокируются.

Постраничный вывод

Списки возвращают data, has_more и next_cursor. Для следующей страницы передайте next_cursor в параметр cursor с теми же фильтрами. Курсор непрозрачный: не собирайте и не разбирайте его сами.

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJvIjoyMCwiZiI6IjNhOWQifQ"
}

Пример: пересборка сервера из GitHub Actions

Создайте токен с назначением «CI: сборка сервера», ограниченный этим сервером, и сохраните его в секрет репозитория MCPBAY_TOKEN. SERVER_ID — поле id из GET /v1/author/servers. Пересборка берёт последний коммит ветки, указанной для хостинга, а не сам тег, — ставьте тег на коммит, который уже в этой ветке. Пересобирайте по релизным тегам, а не на каждый коммит, — так вы уложитесь в часовой лимит сборок.

name: Deploy to mcpbay.pro
on:
  push:
    tags: ["v*"]

jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Rebuild the hosted server
        env:
          SERVER_ID: "123"
          MCPBAY_TOKEN: ${{ secrets.MCPBAY_TOKEN }}
        run: |
          curl --fail-with-body -X POST \
            "https://api.mcpbay.pro/v1/author/servers/$SERVER_ID/deployment/rebuild" \
            -H "Authorization: Bearer $MCPBAY_TOKEN"

API отвечает 202 Accepted — сборка идёт в фоне. Следите за ней через GET /v1/author/servers/{id}/builds (новые сверху), а за её живым логом — через GET …/builds/{build_id}/log?since=<next>.

Для ИИ-агентов

Дайте агенту только те права, которые нужны его задаче, — например, назначение «Агент: каталог и мои MCP» или «Только чтение», если он не должен ничего менять. Для поиска по каталогу токен не нужен вовсе. Агент может прочитать эту страницу в Markdown (меню «Копировать страницу» выше) и спецификацию OpenAPI.

Если токен утёк

• Отзовите его в кабинете → «Токены API». Отзыв действует со следующего же запроса.
• Нет доступа к кабинету? Токен может отозвать сам себя — команда ниже.
• При смене пароля можно сразу отозвать все токены; сброс пароля по почте отзывает их автоматически.

curl -X DELETE https://api.mcpbay.pro/v1/token \
  -H "Authorization: Bearer $LEAKED_TOKEN"

Версии и изменения

Версия — часть адреса: /v1. Внутри v1 мы только добавляем — новые методы, поля и права. Всё несовместимое уходит в /v2; v1 после этого работает ещё не меньше 6 месяцев, а в её ответах появляются заголовки Deprecation и Sunset.

Журнал изменений

• Сентябрь 2026 — первая версия: каталог, токен, ваш аккаунт, ваши серверы.