Сообщение MCP-серверу

POSThttps://api.souz.ai/mcp

Сервер Model Context Protocol, транспорт Streamable HTTP, версия протокола 2025-06-18. Методы: initialize, ping, tools/list, tools/call; уведомление (сообщение без id) — 202 без тела. Ответ всегда JSON, потока и сессий нет; GET /mcp — 405.

Каждый инструмент вызывает ту же ручку API, что описана здесь, с тем же заголовком Authorization: каталог, каналы и превью — без ключа, чат и задачи — API-ключ, настройки каналов аккаунта — ключ управления. Отказ ручки (нет ключа, не тот ключ, баланс) — result.isError: true с кодом ошибки API в structuredContent.error; ошибка протокола (нет метода, неверные аргументы) — error JSON-RPC.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

ManagementKey

Ключ управления из кабинета souz.ai (выдают владелец и администратор аккаунта — себе или участнику). Даёт ровно то, что его держатель видит и может в кабинете: баланс, историю операций и запросов, расходы, обычные ключи, настройки аккаунта — с той же ролью, лимитами и цифрами. Модели не запускает. Обычный API-ключ здесь не подходит: 403 forbidden с detail[].reason: requires_management_key.

Заголовки

MCP-Protocol-Versionstring

Версия протокола, согласованная в initialize: 2025-06-18, 2025-03-26 или 2024-11-05; без заголовка — 2025-03-26. Другая — 400.

Тело запроса обязательно

application/json

Схема MCPRequest

Других полей нет.

idодно из

Номер запроса; ответ вернёт его же. Без id — уведомление.

Вариант 1string

Вариант 2integer

jsonrpcstringобязательно

Значение: "2.0"

methodstringобязательно

Пример: "tools/call"

paramsobject

Параметры метода; у tools/call — name инструмента и arguments по его inputSchema.

Ответы

200Ответ JSON-RPC — `result` или `error`.

application/json

Схема MCPResponse

errorobject

Ошибка протокола JSON-RPC.

codeintegerобязательно

-32700 — не JSON, -32600 — не запрос JSON-RPC, -32601 — нет метода, -32602 — неверные параметры или неизвестный инструмент, -32603 — сбой сервера.

dataobject

Подробности у неверных аргументов инструмента (-32602).

errorsarray[object]

Элемент массиваobject

allowedarray[string]

pathstringобязательно

JSON Pointer внутри arguments.

Пример: "/model"

reasonDetailReasonобязательно

toolstring

messagestringобязательно

idодно изобязательно

id запроса; null — запрос не удалось разобрать.

Вариант 1string

Вариант 2integer

Вариант 3null

jsonrpcstringобязательно

Значение: "2.0"

resultobject

Итог метода. У tools/call — content (текст с таблицей), structuredContent (те же данные объектом) и isError.

202Уведомление или ответ клиента принят; тела нет.

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

503Плановые работы (`maintenance`): новые запросы приостановлены до `error.ends_at`,

Плановые работы (maintenance): новые запросы приостановлены до error.ends_at, причина — в error.reason. Повторите после этого времени (или через Retry-After секунд, чтобы узнать, не закончились ли работы раньше); принятые задачи доделываются, переключаться никуда не нужно. Состояние — GET /v1/status.

application/json

Error

Запрос

curl -X POST 'https://api.souz.ai/mcp' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "by": "stability",
      "model": "gpt-5-nano"
    },
    "name": "compare_channels"
  }
}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/mcp",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "id": 2,
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
            "arguments": {
                "by": "stability",
                "model": "gpt-5-nano",
            },
            "name": "compare_channels",
        },
    },
)
print(response.json())

const response = await fetch("https://api.souz.ai/mcp", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "id": 2,
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "arguments": {
        "by": "stability",
        "model": "gpt-5-nano"
      },
      "name": "compare_channels"
    }
  }),
});
console.log(await response.json());

Ответ

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {}
}

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}

{
  "error": {
    "code": "maintenance",
    "ends_at": "2026-10-04T14:15:00+03:00",
    "message": "scheduled maintenance: new requests are paused until ends_at; retry after it, accepted jobs finish afterwards and nothing needs to change on your side",
    "reason": "Обновление сервиса",
    "type": "model_error"
  }
}