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

`POST https://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-Version` | header | нет | `string` | Версия протокола, согласованная в `initialize`: `2025-06-18`, `2025-03-26` или `2024-11-05`; без заголовка — `2025-03-26`. Другая — `400`. |

## Тело запроса (`application/json`)

Схема `MCPRequest`.

| Поле | Обязательно | Тип | Описание |
|---|---|---|---|
| `id` | нет |  | Номер запроса; ответ вернёт его же. Без `id` — уведомление. |
| `jsonrpc` | да | `string` |  |
| `method` | да | `string` |  |
| `params` | нет | `object` | Параметры метода; у `tools/call` — `name` инструмента и `arguments` по его `inputSchema`. |

## Пример запроса

```bash
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"
  }
}'
```

```python
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())
```

```ts
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());
```

## Ответы

### 200

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

- `application/json`, схема `MCPResponse`

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

### 202

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

### 400

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

- `application/json`, схема `Error`

```json
{
  "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"
  }
}
```

### 403

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

- `application/json`, схема `Error`

```json
{
  "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"
  }
}
```

### 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`, причина — в `error.reason`. Повторите после этого времени (или через `Retry-After` секунд, чтобы узнать, не закончились ли работы раньше); принятые задачи доделываются, переключаться никуда не нужно. Состояние — `GET /v1/status`.

- `application/json`, схема `Error`

```json
{
  "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"
  }
}
```

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.